MBSTOWCS(3C) Standard C Library Functions MBSTOWCS(3C)
NAME
mbstowcs,
mbstowcs_l - convert a multibyte character string to a wide-
character string
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h> size_t mbstowcs(
wchar_t *restrict pwcs,
const char *restrict s,
size_t n);
#include <stdlib.h> #include <xlocale.h> size_t mbstowcs_l(
wchar_t *restrict pwcs,
const char *restrict s,
size_t n,
locale_t loc);
DESCRIPTION
The
mbstowcs() function converts a multibyte character string
s beginning in the initial conversion state into a wide-character string.
If
pwcs is not NULL, the converted characters are stored into array
pointed to by
pwcs.
Conversion continues up to and including a terminating null character,
which is also stored, or until
n wide-characters have been stored into
the array pointed to by
pwcs.
The behavior of
mbstowcs() function is affected by the LC_CTYPE
category of the current locale.
The
mbstowcs_l() function behaves identically to
mbstowcs(), except
instead of using the current locale, it uses the locale as specified by
loc.
RETURN VALUES
The
mbstowcs() and
mbstowcs_l() functions return the number of wide-
characters successfully converted, not including the terminating null
(if any), or -1 if conversion encounters a sequence of bytes that does
not form a valid character.
ERRORS
The
mbstowcs() and
mbstowcs_l() functions will fail if:
EILSEQ An invalid multibyte sequence was detected.
EINVAL The conversion state is invalid.
INTERFACE STABILITY
The
mbstowcs() function is
Standard. The
mbstowcs_l() function is
Uncommitted.
MT-LEVEL MT-SafeSEE ALSO
mbsnrtowcs(3C),
mbtowc(3C),
newlocale(3C),
setlocale(3C),
uselocale(3C),
wcstombs(3C),
attributes(7),
environ(7),
standards(7)illumos March 28, 2017 illumos
