HP C/iX Library Reference Manual (30026-90004)

Chapter 5 249
HP C/iX Library Function Descriptions
mblen
mblen
Determines the number of bytes in a multibyte character.
Syntax
#include <stdlib.h>
int mblen(const char * s , size_t n );
Parameters
s A pointer to a single multibyte character.
n A variable of type size_t that controls the number of characters that
mblen searches when scanning for a multibyte character. This argument is
typically set to MB_CUR_MAX.
Return Values
>0 The length of the multibyte character to which s points.
−1 The
s parameter does not point to a valid multibyte character.
=0 The
s parameter is a null pointer and multibyte character encodings are
not state-dependent, or
s points to a null character.
Description
The mblen function examines the multibyte character pointed to by s . If a valid multibyte
character is recognized within
n bytes from the location pointed to by s , the length of the
multibyte character is returned.
This function retains state information. Multibyte encodings can be state-dependent,
employing "shift characters" to alter the meaning of subsequent characters. The shift state
is persistent between calls to the routines for processing extended character sets unless
the LC_CTYPE category of the locale is changed.
Calling this function with the
s argument set to NULL resets the function to its initial state.
When using a NULL pointer to clear the shift state, zero is returned if the multibyte shift
state was previously clear. A nonzero value is returned if the locale-specific shift state was
previously set.
Locale-specific character sets that are too large to be represented within one byte are
handled in ANSI C by using extended character sets. Extended character sets have two
representations, the internal representation, and the external representation. The
external representation is a multibyte character. The multibyte character is a sequence of
normal characters used to represent the locale-specific extended character. The internal
representation of this multibyte character is a wide character of type wchar_t. The
maximum number of bytes in a multibyte character in the current locale (see also
LC_CTYPE) is given by the macro MB_CUR_MAX.