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);
DESCRIPTIONmbstowcs 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 ALSOwchrtbl(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.
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 wide-
character codes outside the domain of the collating sequence, then errno
is set to EINVAL.
Page 2
