mblen(3)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 stan‐
dards 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
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.
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 encod‐
ing. 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 char‐
acter, 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) multi‐
byte 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() func‐
tions 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: 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)mblen(3)