NAME

wcstombs − convert a wide-character string to a character string

SYNOPSIS

#include <stdlib.h> size_t wcstombs(char ∗s, const wchar_t ∗pwcs, size_t n);

DESCRIPTION

The wcstombs() function converts the sequence of wide-character codes from the array pointed to by pwcs into a sequence of characters and stores these characters into the array pointed to by s, stopping if a character would exceed the limit of n total bytes or if a null byte is stored.  Each wide-character code is converted as if by a call to wctomb(3C). 

The behavior of this function is affected by the LC_CTYPE category of the current locale. 

No more than n bytes will be modified in the array pointed to by s. If copying takes place between objects that overlap, the behavior is undefined. If s is a null pointer, wcstombs() returns the length required to convert the entire array regardless of the value of n, but no values are stored.

RETURN VALUES

If a wide-character code is encountered that does not correspond to a valid character (of one or more bytes each), wcstombs() returns (size_t)−1.  Otherwise, wcstombs() returns the number of bytes stored in the character array, not including any terminating NULL byte.  The array will not be null-terminated if the value returned is n.

ERRORS

The wcstombs() function may fail if the following error is detected:

EILSEC A wide-character code does not correspond to a valid character. 

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

SEE ALSO

mblen(3C), mbstowcs(3C), mbtowc(3C), setlocale(3C), wctomb(3C), attributes(5)

SunOS 5.6  —  Last change: 20 Dec 1996