illumos: manual page: wcstombs.3c

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