OSF

NAME

mbstowcs −  Converts a multibyte (single-byte or double-byte) 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 string to be converted. 

DESCRIPTION

The mbstowcs() function converts a multibyte character string into a wide character string, which is stored at a specified location.  The mbstowcs() function does not convert characters occurring after a null character in the input string (which is converted to value 0 (zero)). 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, (size_t) - 1 is returned and errno is set to indicate the error.  Otherwise, mbstowcs() returns the number of wide characters stored in the output array, not including a terminating null. (When the return value is n, the output array is not null-terminated.) 

ERRORS

If the mbstowcs() function fails, errno may be set to the following value:

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

RELATED INFORMATION

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