mbstring(3C)                                                      mbstring(3C)


NAME
     mbstring: mbstowcs, wcstombs, wcsxfrm - multibyte string functions

SYNOPSIS
     #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 wcsxfrm (wchar_t *ws1, const wchar_t *ws2, size_t n);

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 codes into the array pointed to by pwcs, stopping after n
     codes are stored or a code with value zero (a converted null character)
     is stored.  If pwcs is a null pointer, mbstowcs returns the length
     required to convert the entire array regardless of the value of n, but no
     values are stored.

     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, stopping if a
     multibyte character would exceed the limit of n total bytes or if a null
     character is stored.  If s is a null pointer, wcstombs returns the length
     required to convert the entire array regardless of the value of n, but no
     values are stored.  This function returns the number of bytes required
     for the character array.

     wcsxfrm  transforms the wide character string pointed to by ws2 and
     places the resulting wide character string into the array pointed to by
     ws1 . The transformation is such that if wcscmp is applied to two
     transformed wide strings, it returns a value greater than, equal to or
     less than 0, corresponding to the result of wcscoll applied to the same
     two original wide character strings.  No more than n wide-character codes
     are placed into the resulting array pointed to by ws1 , including the
     terminating null wide-character code.  If n is 0, ws1 is permitted to be
     a null pointer.  If copying takes place between objects that overlap, the
     behaviour is undefined.  wcsxfrm returns the length of the transformed
     wide character string (not including the terminating null wide-character
     code). If the value returned is n or more, the contents of the array
     pointed to by ws1 are indeterminate.

SEE ALSO
     wchrtbl(1M), mbchar(3C), setlocale(3C), wcscmp(3S), wcscoll(3S),
     environ(5), <wchar.h>.

DIAGNOSTICS
     If an invalid multibyte character is encountered, mbstowcs returns
     (size_t)-1 with errno set equal to EILSEQ.  Otherwise, mbstowcs returns
     the number of array elements modified, not including the terminating zero
     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.

     On error, wcsxfrm returns (size_t)-1 and sets errno to indicate the
     error.  If the  wide character string pointed to by ws2 contains wide-
     character codes outside the domain of the collating sequence, then errno
     is set to EINVAL.


                                                                        Page 2