10.7. Multi-byte Character Functions

10.7.1. The mblen function

Synopsis
#include <stdlib.h>

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

Description

If s is not a null pointer, the mblen function determines the number of bytes contained in the multi-byte character pointed to by s. Except that the shift state of the mbtowc function is not affected, it is equivalent to

mbtowc((wchar_t *)0, s, n);
The implementation shall behave as if no library function calls the mblen function.
Returns

If s is a null pointer, the mblen function returns a non-zero or zero value, if multi-byte encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the mblen function either returns 0 (if s points to the null character) or returns the number of bytes that are contained in the multi-byte character (if the next n or fewer bytes form a multi-byte character), or returns -1 (if they do not form a valid multi-byte character).

See Also

Section 10.7.2

Implementation Notes

10.7.2. The mbtowc function

Synopsis
#include <stdlib.h>

int mbtowc (wchar_t * pwc , const char * s , size_t n );

Description

If s is not a null pointer, the mbtowc function determines the number of bytes in the multi-byte character pointer to by s. It then determines the code for the value of type wchar_t that corresponds to the multi-byte character. I the multi-byte character is valid and pwc is not a null pointer then mbtowc stores the code in the object pointer to by pwc. At most n bytes of the array pointed to by s will be examined.

The implementation shall behave as if no library function calls th mbtowc function.

Returns

If s is a null pointer, mbtowc returns a non-zero or zero value, if multi-byte character encodings respectively do or do no have state dependent encodings. If s is not a null pointer the mbtowc function either returns zero (if s points to the null character), or returns the number of bytes that are contained in the converted multi-byte character (if the next n or fewer bytes for a valid multi-byte character), or returns -1 (if they do not form a valid multi-byte character).

In no case will the value returned be greater than n or the value of the MB_CUR_MAX macro.

See Also

Section 10.7.3

Implementation Notes

None.

10.7.3. The wctomb function

Synopsis
#include <stdlib.h>

int wctomb (char * s , wchar_t wchar );

Description

The wctomb function determines the number of bytes needed to represent the multi-byte character corresponding to the code whose value is wchar (including any change in shift state). It store the multi-byte character representation in the array pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters are stored. If the value of wchar is zero, th wctomb function is left in the initial shift state.

The implementation shall behave as if no library function calls th wctomb function.

Returns

If s is a null pointer, wctomb returns a non-zero or zero value, if multi-byte character encodings respectively do or do no have state dependent encodings. If s is not a null pointer the wctomb function either returns zero (if s points to the null character), or returns the number of bytes that are contained in the converted multi-byte character (if the next n or fewer bytes for a valid multi-byte character), or returns -1 (if the do not form a valid multi-byte character).

In no case will the value returned be greater than n or the value of the MB_CUR_MAX macro.

See Also

Section 10.7.2

Implementation Notes

None.