mblen, mbrlen - Determine the length in bytes of a multibyte
character
#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 );
Standard C Library (libc)
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.
Points to a multibyte-character string. Specifies the
maximum number of bytes to consider. Points to an
mbstate_t structure that contains the current conversion
state of the multibyte-character string.
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.
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.
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
If the following condition occurs, the mblen() and
mbrlen() functions set errno to the corresponding value:
The mbs parameter points to an invalid multibyte character.
Functions: btowc(3), mbsinit(3), mbtowc(3), wctomb(3),
mbstowcs(3), wcslen(3), wcstombs(3), wctob(3)
mblen(3)
[ Back ] |
