mbstring(S)

mbstring: mbstowcs, wcstombs, mbsrtowcs, wcsrtombs -- multibyte string functions

Syntax

cc ...-lc

#include <stdlib.h>

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

#include <wchar.h>

size_t mbsrtowcs(wchar_t *pwcs, const char **s, size_t n,
                   mbstate_t *ps);
size_t wcsrtombs(char *s, const wchar_t **pwcs, size_t n,
                   mbstate_t *ps);

Description

mbstowcs- convert a string of multibyte characters to wide characters

wcstombs- convert a string of wide characters to multibyte characters

mbsrtowcs- convert a string of multibyte characters in a specified shift state to wide characters

wcsrtombs- convert a string of wide characters to multibyte characters in a specified shift state

mbstowcs

mbstowcs(S) converts a sequence of multibyte characters taken from the array pointed to by s into a sequence of corresponding wide character codes and stores the wide characters in the array pointed to by pwcs, stopping after n codes are stored or a code with value zero (a converted null character) is stored.

wcstombs

wcstombs(S) converts a sequence of wide character codes taken from the array pointed to by pwcs ino a sequence of multibyte characters and stores the multibyte characters in 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.

mbsrtowcs

mbsrtowcs(S) converts a sequence of multibyte characters that begins in the shift state described by ps from the array indirectly pointed to by s into a sequence of corresponding wide characters, which, if pwcs is not a null pointer, are then stored in the array pointed to by pwcs. Conversion continues up to and including a terminating null character, but the terminating null wide character is not stored.

Conversion stops prematurely in two cases: when a sequence of bytes is reached that does not form a valid multibyte character, or, if pwcs is not a null pointer, when n codes have been stored in the array pointed to by pwcs. Thus, the value of n is ignored if pwcs is a null pointer. Each conversion takes place as if by a call to mbrtowc( ).

If pwcs is not a null pointer, the pointer object pointed to by s is assigned either a null pointer (if conversion stopped due to reaching a terminating null character) or the address just past the last multibyte character converted. If conversion stopped due to reaching a terminating null character and if pwcs is not a null pointer, the resulting state described is the initial conversion state.

wcsrtombs

wcsrtombs(S) converts a sequence of wide characters from the array indirectly pointed to by pwcs into a sequence of corresponding multibyte characters that begins in the shift state described by ps, which, if s is not a null pointer, are then stored into the array pointed to by s. Conversion continues up to and including a terminating null wide character, but the terminating null character (byte) is not stored.

Conversion stops prematurely in two cases: when a code is reached that does not correspond to a valid multibyte character, or (if s is not a null pointer) when the next multibyte character does exceed the limit of n total bytes to be stored into the array pointed to by s. Each conversion takes place as if by a call to wcrtomb( ).

If s is not a null pointer, the pointer object pointed to by pwcs is assigned either a null pointer (if conversion stopped due to reaching a terminating null wide character) or the address just past the last wide character converted. If conversion stopped due to reaching a terminating null wide character and if s is not a null pointer, the resulting state described is the initial conversion state.

Return values

If mbstowcs( ) encounters an invalid multibyte character, it returns (size_t)-1. Otherwise, mbstowcs( ) returns the number of array elements modified, not including the terminating zero code, if any. If pwcs is a null pointer, mbstowcs( ) returns the number of elements required for the wide character code array.

If wcstombs( ) encounters a wide character code that does not correspond to a valid multibyte character, it returns (size_t)-1. Otherwise, wcstombs( ) returns the number of bytes modified, not including a terminating null character, if any. If s is a null pointer, wcstombs( ) returns the number of bytes required for the character array.

If the input string does not begin with a valid multibyte character, an encoding error occurs for mbsrtowcs( ). In this case, it stores the value of the macro [EILSEQ] in errno and returns (size_t)-1, but the conversion state is unchanged. Otherwise, it returns the number of multibyte characters successfully converted, which is the same as the number of array elements modified when s is not a null pointer.

If the first code is not a valid wide character, an encoding error occurs for wcsrtombs( ). In this case, it stores the value of the macro [EILSEQ] in errno and returns (size_t)-1, but the conversion state is unchanged. Otherwise, it returns the number of bytes in the resulting multibyte characters sequence, which is the same as the number of array elements modified when s is not a null pointer.

Diagnostics

If the following condition occurs, mbrtowc( ) or wcrtomb( ) returns -1 and sets errno to the corresponding value:

[EILSEQ]: the last character processed was not complete and valid.

Standards conformance

mbstowcs(S) and wcstombs(S) are conformant with:

ANSI X3.159-1989 Programming Language -- C,
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992,
and IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) .

mbsrtowcs(S) and wcsrtombs(S) are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.