August 8, 2006 WCSRTOMBS 3

### NAME

wcsrtombs - converts a wide character string to a multibyte character string (restartable)

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```size_t` wcsrtombs(```char * restrict s``, const wchar_t ** restrict pwcs``, size_t n``, mbstate_t * restrict ps`)

### DESCRIPTION

The wcsrtombs(``) converts the nul-terminated wide character string indirectly pointed to by ```pwcs` to the corresponding multibyte character string, and stores it in the array pointed to by ```s`. The conversion stops due to the following reasons:

- The conversion reaches a nul wide character. In this case, the nul wide character is also converted.

- The wcsrtombs(``) has already stored ```n` bytes in the array pointed to by ```s`.

- The conversion encounters an invalid character.

Each character will be converted as if wcrtomb(3) is continuously called, except the internal state of wcrtomb(3) will not be affected.

After conversion, if ```s` is not a null pointer, the pointer object pointed to by ```pwcs` is a null pointer (if the conversion is stopped due to reaching a nul wide character) or the first byte of the character just after the last character converted.

If ```s` is not a null pointer and the conversion is stopped due to reaching a nul wide character, wcsrtombs(``) places the state object pointed to by ```ps` to an initial state after the conversion is taken place.

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

These are the special cases:

s == NULL
  wcsrtombs(``) returns the number of bytes to store the whole multibyte character string corresponding to the wide character string pointed to by ```pwcs`, not including the terminating nul byte. In this case, ```n` is ignored.

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

ps == NULL
  wcsrtombs(``) uses its own internal state object to keep the conversion state, instead of ```ps` mentioned in this manual page.

  Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of wcsrtombs(``), which is initialized at startup time of the program.

### RETURN VALUES

wcsrtombs(``) returns:

0 or positive
  Number of bytes stored in the array pointed to by ```s`, except for a nul byte. 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. The wcsrtombs(``) also sets errno to indicate the error.

### ERRORS

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

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

### SEE ALSO

setlocale(3), wcrtomb(3), wcstombs(3)

### STANDARDS

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