NAME

wcstombs − Converts a wide-character string into a multibyte character string

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stdlib.h>

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

PARAMETERS

sPoints to the location where the converted multibyte-character string is stored. 

pwcsPoints to the wide-character string to be converted. 

nSpecifies the number of bytes to be converted. 

DESCRIPTION

The wcstombs() function converts a wide-character string into a multibyte-character string and stores the converted string in a location pointed to by the s parameter.  The wcstombs() function stores only the number of bytes specified by the n parameter as the output string.  When copying between objects that overlap, the behavior of wcstombs() is undefined. 

The behavior of the wcstombs() 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 s begins in its initial shift state. 

The wcstombs() function converts each character in the pwcs wide-character string and stores the converted character in the s string. The wcstombs() function stops storing characters in the output array under the following conditions:

       •The function has encountered a null wide character in the pwcs wide-character string and has written a corresponding null byte in s. 

       •The function cannot store the next converted wide character because there is not enough room in s, that is, the function would have to store more than n bytes in the s parameter to store the character. 

       •The function has already stored n bytes in the s parameter. 

       •The function has encountered an invalid wide-character code in the pwcs wide-character string. 

If the wcstombs() function stores exactly n bytes in the s parameter, the function does not store a terminating null byte. 

To ensure that there is enough room in the s parameter to fit the converted string, you can allocate enough memory to store the maximum multibyte string based on the number of wide characters in the wide-character string. Allocate the number of bytes (and pass the value in the n parameter) equal the length of the pwcs wide-character string multiplied by the value of MB_CUR_MAX in the current locale. The wcslen() function returns the length of a wide-character string. 

NOTES

AES Support Level:
Full use.

RETURN VALUES

If the wcstombs() function does not encounter an invalid wide-character code, the function returns the number of bytes stored, not including the terminating null byte.  When  the wcstombs() function encounters a wide-character code that does not correspond to a valid multibyte character, the function returns a value of -1 cast to size_t and sets errno to indicate the error. 

If the wcstombs() function cannot store all of the converted characters in the output array, the function stops before storing a character that would overflow the output array, and returns the number of bytes stored in the array.  When the return value is n, the output array is not null terminated. 

If the s parameter is a null pointer, the wcstombs() function returns the number of bytes required for the character array. 

ERRORS

If any of the following conditions occur, the wcstombs() function sets errno to the corresponding value:

[EILSEQ]The array pointed to by the pwcs parameter contains an entry that does not correspond with a valid multibyte character. 

RELATED INFORMATION

Functions: mblen(3), mbstowcs(3), mbtowc(3), wcslen(3), wctomb(3).