WCSTOMBS(3C) Standard C Library Functions WCSTOMBS(3C)

NAME


wcstombs, wcstombs_l - convert a wide-character string to a multibyte
character string

LIBRARY


Standard C Library (libc, -lc)

SYNOPSIS


#include <stdlib.h>

size_t
wcstombs(char *restrict s, const wchar_t *restrict pwcs, size_t n);

#include <stdlib.h>
#include <xlocale.h>

size_t
wcstombs_l(char *restrict s, const wchar_t *restrict pwcs, size_t n,
locale_t loc);

DESCRIPTION


The wcstombs() function converts a wide-character string pwcs into a
multibyte character string, beginning in the initial conversion state. If
s is not NULL, converted characters are stored into the array pointed to by
s.

Conversion continues up to and including a terminating null wide-character,
which is also stored, or until n bytes have been stored into the array
pointed to by s. If the latter case results in partial multibyte character
at the end of the string, it is not stored.

The behavior of wcstombs() function is affected by the LC_CTYPE category of
the current locale.

The wcstombs_l() function behaves identically to wcstombs(), except instead
of using the current locale, it uses the locale as specified by loc.

RETURN VALUES


The wcstombs() and wcstombs_l() functions return the number of bytes in the
resulting character sequence, not including the terminating null (if any),
or -1 if a code is reached that does not correspond to a valid character.

ERRORS


The wcstombs() and wcstombs_l() functions will fail if:

EILSEQ A wide-character code does not correspond to a valid
character.

EINVAL The conversion state is invalid.

INTERFACE STABILITY


The wcstombs() function is Standard. The wcstombs_l() function is
Uncommitted.

MT-LEVEL
MT-Safe

SEE ALSO


mbstowcs(3C), newlocale(3C), setlocale(3C), uselocale(3C), wcsnrtombs(3C),
wctomb(3C), attributes(5), environ(5), standards(5)

illumos March 28, 2017 illumos