February 4, 2002 MBRTOWC 3

### NAME

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

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```size_t` mbrtowc(```wchar_t * restrict pwc``, const char * restrict s``, size_t n``, mbstate_t * restrict ps`)

### DESCRIPTION

The mbrtowc(``) usually converts the multibyte character pointed to by ```s` to a wide character, and stores the wide character to the wchar_t object pointed to by ```pwc` if ```pwc` is non-```NULL` and ```s` points to a valid character. The conversion happens in accordance with, and changes the conversion state described in the mbstate_t object pointed to by ```ps`. This function may examine at most ```n` bytes of the array beginning from ```s`.

If ```s` points to a valid character and the character corresponds to a nul wide character, then the mbrtowc(``) places the mbstate_t object pointed to by ```ps` to an initial conversion state.

Unlike mbtowc(3), the mbrtowc(``) may accept the byte sequence pointed to by ```s` not forming a complete multibyte character but which may be part of a valid character. In this case, this function will accept all such bytes and save them into the conversion state object pointed to by ```ps`. They will be used at subsequent calls of this function to restart the conversion suspended.

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

These are the special cases:

s == NULL
  mbrtowc(``) sets the conversion state object pointed to by ```ps` to an initial state and always returns 0. Unlike mbtowc(3), the value returned does not indicate whether the current encoding of the locale is state-dependent.

  In this case, mbrtowc(``) ignores ```pwc` and ```n`, and is equivalent to the following call:

    `

        mbrtowc(NULL, "", 1, ps);

    `

pwc == NULL
  The conversion from a multibyte character to a wide character has taken place and the conversion state may be affected, but the resulting wide character is discarded.

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

In the usual cases, mbrtowc(``) returns:

0
  The next bytes pointed to by ```s` form a nul character.

positive
  If ```s` points to a valid character, mbrtowc(``) returns the number of bytes in the character.

(size_t)-2
  ```s` points to a byte sequence which possibly contains part of a valid multibyte character, but which is incomplete. When ```n` is at least ```MB_CUR_MAX`, this case can only occur if the array pointed to by ```s` contains a redundant shift sequence.

(size_t)-1
  ```s` points to an illegal byte sequence which does not form a valid multibyte character. In this case, mbrtowc(``) sets errno to indicate the error.

### ERRORS

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

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

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

### SEE ALSO

mbrlen(3), mbtowc(3), setlocale(3)

### STANDARDS

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