./_Man_SunOS_4.1.3_html/html3/mblen.3.html

Manual page for MBLEN(3)

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

SYNOPSIS

#include <stdlib.h>

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

size_t mbstowcs(s, pwcs, n)
char *s;
wchar_t *pwcs;
size_t n;

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

int wcstombs(s, pwcs, n)
char *s;
wchar_t *pwcs;
size_t n;

int wctomb(s, wchar)
char *s;
wchar_t wcar;

DESCRIPTION

The behavior of these functions is affected by the LC_CTYPE category of the program's locale. For a stat-dependent encoding, each function is placed into its initial state by a call for which its character pointer argument, s, is a NULL pointer. Subsequent calls with s as other than a NULL pointer cause the internal stste of the function to be altered as necessary. A call with a s as a NULL pointer causes these functions to return a nonzero value if encodings have state dependency, and zero otherwise. After the LC_CTYPE category is changed, the shift state of these functions is indeterminate.

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.
mbstowcs(): Converts a sequence of multibyte characters that begins in the initial shift state from the array pointed to by s into a sequence of corresponding codes and stores no more than n codes into the array pointed to by pwcs. 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(), except that the shift state of mbtowc() is not affected.
: No more than n elements will be modified in the array pointed to by pwcs. If copying takes place between objects that overlap, the behavior is undefined.
mbtowc(): Determines the number of bytes that comprise the multibyte character pointed to by s. mbtowc() then determines the code for value of type wchar_t that corresponds to that multibyte character. The value of the code corresponding to the null caharacter is zero. If the multibyte character is valid and pwc is not a null pointer, mbtowc() stores the code in the object pointed to by pwc. At most n bytes of the array pointed to by s will be examined.
wcstowcs(): Converts a sequence of codes that correspond to multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters that begins in the initial shift state 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 code is converted as if by a call to wctomb(), except that the shift state of wctomb() is not affected.
wctomb(): Determines the number of bytes needed to represent the multibyte character corresponding to the code whose value is wchar (including any change in shift state). wctomb() stores the multibyte character representation in the array object 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, wctomb() is left in the initial shift state.

RETURN VALUES

If s is a null pointer, mblen(), mbtowc(), and wctomb() return a nonzero or zero value, if multibyte character encodings, respectively, do or do not have state dependent encodings.

If s is not a null pointer, mblen() and mbtowc() either return 0 (if s points to the null character), or return the number of bytes that comprise the converted multibyte character (if the next n or fewer bytes form a valid multibyte character), or return -1 (if they do not form a valid multibyte character).

In no case will the value returned by mbtowc() be greater than n or the value of the MB_CUR_MAX macro. If s is not a null pointer, wctomb() returns -1 (if the value does not correspond to a valid multibyte character), or returns the number of bytes that comprise the multibyte character corresponding to wchar.

If an invalid multibyte character is encountered, mbstowcs() and wcstombs() return (size_t) -1. Otherwise, they return the number of bytes modified, not including a terminating null character, if any.

NOTE

When an application program using these routines is statically linked, user defined multibyte character handling routines in a user provided shared library will not be used.