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