August 8, 2006 WCSTOMBS 3

### NAME

wcstombs - converts a wide character string to a multibyte character string

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```size_t` wcstombs(```char * restrict s``, const wchar_t * restrict pwcs``, size_t n`)

### DESCRIPTION

wcstombs(``) converts the nul-terminated wide character string pointed to by ```pwcs` to the corresponding multibyte character string, and stores it in the array pointed to by ```s`. This function may modify the first at most ```n` bytes of the array pointed to by ```s`. Each character will be converted as if wctomb(3) is continuously called, except the internal state of wctomb(3) will not be affected.

For state-dependent encoding, the wcstombs(``) implies the result multibyte character string pointed to by ```s` always to begin with an initial state.

The behaviour of wcstombs(``) is affected by the ```LC_CTYPE` category of the current locale.

These are the special cases:

s == NULL
  The wcstombs(``) returns the number of bytes to store the whole multibyte character string corresponding to the wide character string pointed to by ```pwcs`. In this case, ```n` is ignored.

pwcs == NULL
  Undefined (may cause the program to crash).

### RETURN VALUES

wcstombs(``) returns:

0 or positive
  Number of bytes stored in the array pointed to by ```s`. There are no cases that the value returned is greater than ```n` (unless ```s` is a null pointer). If the return value is equal to ```n`, the string pointed to by ```s` will not be nul-terminated.

(size_t)-1
  ```pwcs` points to a string containing an invalid wide character. wcstombs(``) also sets errno to indicate the error.

### ERRORS

wcstombs(``) may cause an error in the following case:

[```EILSEQ`]
  ```pwcs` points to a string containing an invalid wide character.

### SEE ALSO

setlocale(3), wctomb(3)

### STANDARDS

The wcstombs(``) function conforms to ANSI X3.159-1989 (``ANSI C89'') . The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'') .