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

SEE ALSO

mbsnrtowcs(3C), mbtowc(3C), newlocale(3C), setlocale(3C),
uselocale(3C), wcstombs(3C), attributes(7), environ(7), standards(7)

illumos March 28, 2017 illumos