illumos: manual page: mbstowcs

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-Safe