OSF

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

s Points to the location where the converted multibyte character string is stored. 

pwcs Points to the wide-character string to be converted. 

n Specifies the number of bytes to be converted. 

DESCRIPTION

The wcstombs() function converts a wide character string into a multibyte character string and stores the coverted string in a location pointed to by the s parameter. The wcstombs() function  stops storing characters supplied to the output array when it encounters a null character.  The wcstombs() function only stores 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. 

Conversion terminates when the wide-character null is encountered or when the number of bytes expressed by the value of the n parameter (or n-1) has been stored at the location pointed to by the s parameter.  When the amount of space available at the location pointed to by s only permits a partial multibyte character to be stored, n-1 bytes are used because only valid (complete) multibyte characters are allowed. 

NOTES

AES Support Level: Full use

RETURN VALUES

When  the wcstombs() function encounters a wide character code that does not correspond to a valid multibyte character, the value (size_t) -1 is returned and errno is set to indicate the error. Otherwise, wcstombs() returns the number of bytes stored, not including a null terminator.  (When the return value is n, the output array is not null terminated.) 

ERRORS

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

[EINVAL] 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), wctomb(3)