February 4, 2002 WCRTOMB 3

### NAME

wcrtomb - converts a wide character to a multibyte character (restartable)

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```size_t` wcrtomb(```char * restrict s``, wchar_t wc``, mbstate_t * restrict ps`)

### DESCRIPTION

wcrtomb(``) converts the wide character given by ```wc` to the corresponding multibyte character, and stores it in the array pointed to by ```s` unless ```s` is a null pointer. This function will modify the first at most ```MB_CUR_MAX` bytes of the array pointed to by ```s`.

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

These are the special cases:

wc == 0
  For state-dependent encodings, wcrtomb(``) stores a nul byte preceded by special byte sequence (if any) to return to an initial state in the array pointed to by ```s`, and the state object pointed to by ```ps` also returns to an initial state.

s == NULL
  wcrtomb(``) just places ```ps` into an initial state. It is equivalent to the following call:
    `

        wcrtomb(buf, L'\0', ps);

    `

  Here, ```buf` is a dummy buffer. In this case, ```wc` is ignored.

ps == NULL
  mbrtowc(``) 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 mbrtowc(``), which is initialized at startup time of the program.

### RETURN VALUES

wcrtomb(``) returns:

positive
  The number of bytes (including any shift sequences) which are stored in the array.

(size_t)-1
  ```wc` is not a valid wide character. In this case, wcrtomb(``) also sets errno to indicate the error.

### ERRORS

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

[```EILSEQ`]
  ```wc` is not a valid wide character.

[```EINVAL`]
  ```ps` points to an invalid or uninitialized mbstate_t object.

### SEE ALSO

setlocale(3), wctomb(3)

### STANDARDS

The wcrtomb(``) function conforms to ISO/IEC 9899/AMD1:1990 (``ISO C90'') . The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'') .