February 4, 2002 MBSRTOWCS 3

### NAME

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

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

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

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

- The mbsrtowcs(``) has already stored ```n` wide characters.

- The conversion encounters an invalid character.

Each character will be converted as if mbrtowc(3) is continuously called.

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

If ```pwcs` is not a null pointer and the conversion is stopped due to reaching a nul byte, the mbsrtowcs(``) places the state object pointed to by ```ps` to an initial state after the conversion has taken place.

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

These are the special cases:

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

pwcs == NULL
  The conversion has taken place, but the resulting wide character string was discarded. In this case, the pointer object pointed to by ```s` is not modified and ```n` is ignored.

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

### RETURN VALUES

mbsrtowcs(``) returns:

0 or positive
  The value returned is the number of elements stored in the array pointed to by ```pwcs`, except for a terminating nul wide character (if any). If ```pwcs` is not ```NULL` and the value returned is equal to ```n`, the wide character string pointed to by ```pwcs` is not nul-terminated. If ```pwcs` is a null pointer, the value returned is the number of elements to contain the whole string converted, except for a terminating nul wide character.

(size_t)-1
  The array indirectly pointed to by ```s` contains a byte sequence forming invalid character. In this case, mbsrtowcs(``) sets errno to indicate the error.

### ERRORS

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

[```EILSEQ`]
  The pointer pointed to by ```s` points to an invalid or incomplete multibyte character.

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

### SEE ALSO

mbrtowc(3), mbstowcs(3), setlocale(3)

### STANDARDS

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