NAME

mbstowcs − Converts a multibyte character string to a wide character string

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stdlib.h>

size_t mbstowcs(
        wchar_t ∗pwcs,
        const char ∗s,
        size_t n);

PARAMETERS

pwcsPoints to the array where the result of the conversion is stored. 

sPoints to the multibyte character string to be converted. 

nSpecifies the number of wide characters in the destination array. 

DESCRIPTION

The mbstowcs() function converts a multibyte character string into a wide character string, which is stored at a specified location.  No characters that follow a null byte (which is converted into a wide-character code with value zero) will be examined or converted.  When operating on overlapping strings, the behavior of this function is undefined. 

Behavior of the mbstowcs() function is affected by the LC_CTYPE category of the current locale.  In environments that use shift-state-dependent encoding, the array pointed to by the s parameter begins in the initial shift state. 

NOTES

AES Support Level:
Full use.

RETURN VALUES

When mbstowcs() encounters an invalid multibyte character during conversion, the function returns a value of -1 cast to size_t and sets errno to indicate the error.  Otherwise, mbstowcs() returns the number of wide characters stored in the output array, not including a terminating null wide character. (When the return value is n, the output array is not null-terminated.) 

ERRORS

If the following condition occurs, the mbstowcs() function sets errno to the corresponding value:

[EILSEQ]The s parameter points to a string containing an invalid multibyte character. 

RELATED INFORMATION

Functions: mblen(3), mbtowc(3), wctomb(3), wcstombs(3).