NAME

mbstowcs, mbsrtowcs − Converts a multibyte character string to a wide-character string

LIBRARY

Standard C Library (libc)

SYNOPSIS

#include <stdlib.h> size_t mbstowcs(
        wchar_t ∗pwcs,
        const char ∗s,
        size_t n); #include <wchar.h> size_t mbsrtowcs(
        wchar_t ∗pwcs,
        const char ∗∗s,
        size_t n,
        mbstate_t ∗ps );

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

mbstowcs(), mbsrtowcs(): XSH5.0

Refer to the standards(5) reference page for more information about industry standards and associated tags. 

PARAMETERS

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

∗s or ∗∗s
Points or indirectly points to the multibyte-character string to be converted.

nSpecifies the number of wide characters in the destination array. 

∗psPoints to an mbstate_t structure containing the conversion state of the data in s. 

DESCRIPTION

The mbstowcs() function converts a multibyte-character string into a wide-character string, which is stored at a specified location.  The function does not examine or convert any characters that follow a null byte, which is converted and stored as a wide-character code with value zero.  The function does not store more than n wide characters in pwcs.  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 locales that use shift-state encoding, the array pointed to by the s parameter begins in the initial shift state. 

The mbsrtowcs() function is a restartable version of mbstowcs().  Restartable conversion functions obtain and store the conversion state in an mbstate_t structure that can be read and changed by subsequent calls to the same or other restartable conversion functions. 

RESTRICTIONS

[Tru64 UNIX]  The mbsrtowcs() and other restartable versions of conversion functions are functional only when used with locales that support shift-state encoding. Currently, the operating system does not provide any locales that support shift-state encoding, so the mbstowcs() and mbsrtowcs() functions do not differ in terms of run-time behavior. 

RETURN VALUES

When the mbstowcs() and mbsrtowcs() functions encounter an invalid multibyte character during conversion, they return a value of −1 cast to size_t and set errno to indicate the error.  Otherwise:

       •The mbstowcs() function returns the number of characters stored in the output array (or required if pwcs is null), not including a terminating null wide character, if any. When the return value is n, the output array is not null-terminated. 

       •The mbsrtowcs() function returns the number of characters stored in the output array, not including a terminating null wide character, if any. 

ERRORS

If the following condition occurs, the mbstowcs() and mbsrtowcs() functions set errno to the corresponding value:

[EILSEQ]The s parameter contains an invalid multibyte character. 

RELATED INFORMATION

Functions: btowc(3), mblen(3), mbsinit(3), mbtowc(3), wcstombs(3), wcslen(3), wctob(3), wctomb(3)