mbstring(3C)							  mbstring(3C)

NAME    [Toc]    [Back]

     mbstring: mbstowcs, wcstombs, wcsxfrm - multibyte string functions

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     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    [Toc]    [Back]

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

DIAGNOSTICS    [Toc]    [Back]

     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.



									Page 1






mbstring(3C)							  mbstring(3C)



     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 widecharacter
 codes outside the domain	of the collating sequence, then	errno
     is	set to EINVAL.


									PPPPaaaaggggeeee 2222