NAME

mblen, mbtowc, wctomb, mbstowcs, wcstombs − multibyte character handling

SYNOPSIS

#include <stdlib.h>

int mblen (s, n)
char ∗s;
int n;

int mbtowc(pwc, s, n)
wchar_t ∗pwc;
char ∗s;
int n;

int wctomb(s, wc)
char ∗s;
wchar_t wc;

int mbstowcs(ws, s, n)
wchar_t ∗ws;
char ∗s;
int n;

int wcstombs(s, ws, n)
char ∗s;
wchar_t ∗ws;
int n;

DESCRIPTION

The behavior of the multibyte character functions is affected by the LC_CTYPE category of the current locale.  A call with s as a NULL pointer causes these functions to return zero. 

If s is not a null pointer, these functions work as follows:

mblen Determines the number of bytes comprising the multibyte character pointed to by s.

If s points to the null character, mblen returns zero.  If the next n or fewer bytes form a valid multibyte character, it returns the number of bytes that comprises the multibyte character.  If they do not form a valid multibyte character, it returns −1. 

mbtowc Determines the number of bytes that comprise the multibyte character pointed to by s. It then determins the wide character that corresponds to that multibyte character. If the multibyte character is valid and pwc is not a NULL pointer, mbtowc stores the wide character in the object pointed by pwc.

mbtowc returns the same value as mblen. 

wctomb Determines the number of bytes needed to represent the multibyte character corresponding to the wide character.  It stores the multibyte character representation in the array object pointed to by s. At most MB_CUR_MAX characters are stored. 

If wctomb returns −1 if the value of wc does not correspond to a valid multibyte character, or returns the number of bytes that comprise the multibyte character corresponding to the value of wc. In no case will the value returned be geater than the value of the MB_CUR_MAX macro. 

mbstowcs Converts a sequence of multibyte characters that begins from the array pointed to by s into sequece of corresponding wide characters and stores not more than n wide characters into the array pointed to by ws. No multibyte characters that follow a null character (which is converted into a code with value zero) will be examined or converted. Each multibyte character is converted as if by a call to mbtowc.  No more than n elements will be modified in the array pointed to by ws. If copying takes place between objects that overlap, the behavior is undefined.

If an invalid multibyte character is encountered, mbstowcs returns −1.  Otherwise, mbstowcs returns the number of array elements modified, not including a terminating zero code, if any. 

wcstombs Converts a sequence of wide characters that correspond to multibyte characters from the array pointed to by ws into a sequece of multibyte characters and stores these multibyte characters into the array pointed to by s, stopping if a multibyte character would exceed the limit of n total bytes or if a null character is stored.  Each wide character is converted as if by a call to wctomb.  No more than n bytes will be modified in the array pointed to by s. If copying takes place between objects that overlap, the behavior is undefined.

If a wide character is encounterd that does not corresponds to a valid multibyte character, wcstombs returns −1.  Otherwise, wcstombs returns the number of bytes modified, not including a terminating null character, if any. 

SEE ALSO

setlocale(3)

NEWS-OSRelease 4.2.1R