February 3, 2002 MBSTOWCS 3

### NAME

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

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

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

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

These are the special cases:

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

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

### RETURN VALUES

mbstowcs(``) returns:

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

(size_t)-1
  ```s` points to a string containing an invalid or incomplete multibyte character. The mbstowcs(``) also sets errno to indicate the error.

### ERRORS

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

[```EILSEQ`]
  ```s` points to a string containing an invalid or incomplete multibyte character.

### SEE ALSO

mbtowc(3), setlocale(3)

### STANDARDS

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