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
     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 ALSO
     wchrtbl(1M), mbchar(3C), mbstring(3C), mbrchar(3S), setlocale(3C),
     environ(5), <wchar.h>.