mbstring(3C)                                                   mbstring(3C)

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

SYNOPSIS
     #include <stdlib.h>
     #include <wchar.h>

     sizet mbstowcs(wchart *pwcs, const char *s, sizet n);

     sizet wcstombs(char *s, const wchart *pwcs, sizet n);

     sizet mbsrtowcs(wchart *dst, const char **src, sizet len,
            mbstatet *ps);

     sizet wcsrtombs(char *dst, const wchart **src, sizet len,
            mbstatet *ps);

DESCRIPTION
     mbstowcs() converts a sequence of multibyte characters from the array
     pointed to by s into a sequence of corresponding wide-character codes
     and stores these into the array pointed to by pwcs. Execution is
     halted after n characters are stored or a character with value zero (a
     converted null character) is stored. If an invalid multibyte character
     is encountered, mbstowcs() returns the value (sizet)-1. Otherwise,
     mbstowcs() returns the number of array elements modified, not includ-
     ing the terminating zero code, if any.

     wcstombs() converts a sequence of wide-character codes from the array
     pointed to by pwcs into a sequence of multibyte characters and stores
     these multibyte characters into the array pointed to by s. Execution
     is halted if a multibyte character would exceed the limit of n total
     bytes or if a null character is stored. If a wide-character code is
     encountered that does not correspond to a valid multibyte character,
     wcstombs() returns the value (sizet)-1. Otherwise, wcstombs() returns
     the number of bytes modified, not including a terminating null charac-
     ter, if any.

     The mbsrtowcs() function converts a sequence of multibyte characters,
     beginning in the conversion state described by the object pointed to
     by ps, from the array indirectly pointed to by src into a sequence of
     corresponding wide-characters. If dst is not a null pointer, the con-
     verted characters are stored not in the array pointed to by dst.
     Conversion continues up to and including a terminating null character,
     which is also stored. Conversion stops earlier in two cases: when a
     sequence of bytes is encountered that does not form a valid multibyte
     character, or (if dst is not a null pointer) when len codes have been
     stored into the array pointed to by dst. Thus, the value of len is
     ignored if dst is a null pointer. Each conversion takes place as if by
     a call to the mbrtowc() function.





Page 1                       Reliant UNIX 5.44                Printed 11/98

mbstring(3C)                                                   mbstring(3C)

     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 terminating null character) or the address just past the last multi-
     byte character converted (if any). If conversion stopped due to reach-
     ing a terminating null character and if dst is not a null pointer, the
     resulting state described is the initial conversion state.

     The wcsrtombs() function converts a sequence of wide-characters from
     the array indirectly pointed to by src into a sequence of correspond-
     ing multibyte characters, beginning in the conversion state described
     by the object pointed to by ps. If dst is not a null pointer, the con-
     verted characters are then stored into the array pointed to by dst.
     Conversion continues up to and including a terminating null wide-
     character, which is also stored. Conversion stops earlier in two
     cases; when a code is reached that does not correspond to a valid mul-
     tibyte character, or (if dst is not a null pointer) when the next mul-
     tibyte character would exceed the limit of len total bytes to be
     stored into the array pointed to by dst. Each conversion takes place
     as if by a call to the wscrtombs() function. If conversion stops
     because a terminating null wide-character has been reached, the bytes
     stored include those necessary to reach the initial shift state
     immediately before the null byte.

     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 terminating null wide-character) or the address just past the last
     wide-character converted (if any). If conversion stopped due to reach-
     ing a terminating null wide-character, the resulting state described
     is the initial conversion state.

SEE ALSO
     chrtbl(1M), mbchar(3C), setlocale(3C), environ(5), stdlib(5),
     wchar(5).





















Page 2                       Reliant UNIX 5.44                Printed 11/98