Index for Section 3

Alphabetical listing for M

Bottom of page

mblen(3)
NAME
  mblen, mbrlen - Determine the length in bytes of a multibyte character

SYNOPSIS
  #include <stdlib.h>

  int mblen(
	  const char *mbs,
	  size_t n );

  #include <wchar.h>

  size_t mbrlen(
	  const char *mbs,
	  size_t n,
	  mbstate_t *ps );

LIBRARY
  Standard C Library (libc)

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  mblen(): ISO C, XPG4

  mbrlen(): ISO C

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  *mbs
      Points to a multibyte-character string.

  n   Specifies the maximum number of bytes to consider.

  *ps Points to an mbstate_t structure that contains the current conversion
      state of the multibyte-character string.

DESCRIPTION
  The mblen() function determines the number of bytes in a multibyte
  character.  The behavior of the mblen() function is affected by the
  LC_CTYPE category of the current locale.

  In locales with shift-state character encoding, a call to mblen() with a
  null pointer as the mbs parameter, places the function in the initial shift
  state. A call to mblen() with an mbs parameter that is not a null pointer
  may change the shift state for subsequent calls to mblen(), depending on
  the character examined. Changing the LC_CTYPE category of the locale causes
  the shift state of the function to be indeterminate. The implementation
  behaves as though no other function calls the mblen() function.

  In the case of nonrestartable functions, such as mblen(), conversion to
  shift-state encoding must first be enabled by calling the function with a
  null pointer parameter and then calling the function again with the wide-
  character value to be converted. The status of the conversion operation
  after the call is not available to subsequent calls.

  The mbrlen() function is a restartable version of mblen(), which means
  that, for locales that define state-dependent encoding, the shift state for
  the character in mbs is maintained in the mbstate_t structure and is
  therefore available to subsequent calls by mbrlen() and other restartable
  conversion functions.

RESTRICTIONS
  The mbrlen() and other restartable versions of conversion routines are
  functional only when used with locales that support shift-state encoding.
  Currently, the Tru64 UNIX product does not provide any locales that use
  shift-state encoding. Therefore, the mblen() and mbrlen() functions have
  the same run-time behavior and always return values for the nonshift-state
  case.

RETURN VALUES
  If the mbs parameter is not a null pointer, the mblen() function returns a
  value determined as follows:

    ·  The number of bytes in the character, if the number of bytes is n or
       fewer and if mbs points to a valid multibyte character other than the
       null character

    ·  Zero (0), if mbs points to the null character

    ·  -1, if mbs does not point to a valid multibyte character or if the
       length of the character in bytes is more than the value of the n
       parameter or the MB_CUR_MAX variable

       In this case, mblen() also sets errno to indicate the error.

  If mbs is not a null pointer, the mbrlen() function returns the first value
  that applies in the following list:

    ·  Zero, if the next n or fewer bytes constitute a null wide character

    ·  A positive value indicating the number of bytes in the converted
       multibyte character, if the next n or fewer bytes constitute a valid
       multibyte character

    ·  (size_t)-2, if the next n bytes contribute to an incomplete (but
       potentially valid) multibyte character

    ·  (size_t)-1, if an encoding error occurs, in which case the next n or
       fewer bytes do not contribute to a complete and valid multibyte
       character

       In this case, the mbrlen() function sets errno to indicate the error
       and the conversion state is undefined.

  If the mbs parameter is a null pointer, the mblen() and mbrlen() functions
  both return one of the following values, depending on whether the current
  locale supports shift-state character encoding:

    ·  A nonzero value, if the character encoding is shift-state dependent

    ·  Zero (0), if the character encoding is not shift-state dependent

ERRORS
  If the following condition occurs, the mblen() and mbrlen() functions set
  errno to the corresponding value:

  [EILSEQ]
      The mbs parameter points to an invalid multibyte character.

SEE ALSO
  Functions: btowc(3), mbsinit(3), mbtowc(3), wctomb(3), mbstowcs(3),
  wcslen(3), wcstombs(3), wctob(3)

Index for Section 3

Alphabetical listing for M

Top of page