mbrstring(3S)mbrstring(3S)NAME
mbrstring: mbsrtowcs, wcsrtombs - multibyte string functions
(restartable)
SYNOPSIS
#include <wchar.h>
size_t mbsrtowcs (wchar_t *dst, const char **src, size_t n, mbstate_t
*ps);
size_t wcsrtombs (char *dst, const wchar_t **src, size_t n, mbstate_t
*ps);
DESCRIPTION
The mbsrtowcs function converts a sequence of multibyte characters, from
the array indirectly pointed to by src into a sequence of corresponding
wide character codes, and stores these codes into the array pointed to by
dst, stopping after n codes are stored or a code with value zero (a
converted null character) is stored, if dst is not a null pointer.
Conversion stops in either of the following cases: when a sequence of
bytes is encountered that does not comprise a valid character, or when n
converted codes have been stored into the array pointed to by dst which
is not a null pointer, or when the multibyte string including a null
character is converted completely and stored into the array. If dst is a
null pointer, the value of n is ignored, and the function returns the
number of characters required to convert the entire string. If dst is not
a null pointer, the pointer object pointed to by src is assigned either a
null pointer if conversion stopped due to reaching a null character, or
the position just past the last character converted if any. If conversion
stopped due to reaching a null character and if dst is not a null
pointer, the conversion state is initialized. If ps is a null pointer,
the mbsrtowcs function uses its own internal mbstate_t object, which is
initialised at program startup. Otherwise, the mbstate_t object pointed
to by ps is used.
The wcstombs function converts a sequence of wide character codes, from
the array indirectly pointed to by src into a sequence of multibyte
characters, and stores these multibyte characters into the array pointed
to by dst, stopping if a multibyte character would exceed the limit of n
total bytes or if a null character is stored. If dst is a null pointer,
wcstombs returns the number of bytes required to convert the entire array
regardless of the value of n, but no values are stored. If dst is not a
null pointer, the converted characters are stored into the array pointed
to by dst. Conversion continues up to and including a null wide
character, which is also stored. Conversion stops in the following cases:
when a code is reached that does not correspond to a valid character, or
when the next character would exceed the limit of n total bytes to be
stored in the array pointed to by dst which is not a null pointer, or
when the wide character string including a null wide character is
converted completely and stored into the array of the multibyte
characters. If dst is not a null pointer, the pointer object pointed to
by src is assigned either a null pointer if conversion stopped due to
reaching a null wide character or the address just past the last wide
Page 1
mbrstring(3S)mbrstring(3S)
character converted if any. If conversion stopped due to reaching a null
wide character, the conversion state is initialized. If ps is a null
pointer, the wcsrtombs function uses its own internal mbstate_t object.
Otherwise, the mbstate_t object pointed to by ps is used.
DIAGNOSTICS
If an invalid multibyte character sequence is encountered, mbsrtowcs
returns (size_t)-1 with errno set equal to EILSEQ; the conversion state
is undefined. Otherwise, it returns the number of characters converted
not including the terminating null code, if any.
If a wide character code is encountered that does not correspond to a
valid multibyte character, wcstombs returns (size_t)-1 with errno set
equal to EILSEQ. Otherwise, wcstombs returns the number of bytes
modified, not including a terminating null character, if any.
NOTES
The behaviour of those functions is affected by the LC_CTYPE category of
the current locale. (Stateful encodings are not supported on IRIX.)
Those functions are supported in n32 and 64 bit C Libraries for IRIX
6.5.17 and later versions.
SEE ALSOwchrtbl(1M), mbchar(3C), mbstring(3C), mbrchar(3S), setlocale(3C),
environ(5), <wchar.h>.
Page 2
