February 3, 2002 MBTOWC 3

### NAME

mbtowc - converts a multibyte character to a wide character

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```int` mbtowc(```wchar_t * restrict pwc``, const char * restrict s``, size_t n`)

### DESCRIPTION

mbtowc(``) usually converts the multibyte character pointed to by ```s` to a wide character, and stores it in the wchar_t object pointed to by ```pwc` if ```pwc` is non-```NULL` and ```s` points to a valid character. This function may inspect at most n bytes of the array beginning from ```s`.

In state-dependent encodings, ```s` may point to the special sequence bytes to change the shift-state. Although such sequence bytes correspond to no individual wide-character code, mbtowc(``) changes its own state by the sequence bytes and treats them as if they are a part of the subsequence multibyte character.

Unlike mbrtowc(3), the first ```n` bytes pointed to by ```s` need to form an entire multibyte character. Otherwise, this function causes an error.

Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of mbtowc(``), except for calling setlocale(3) with changing the ```LC_CTYPE` category of the current locale. Such setlocale(3) call causes the internal state of this function to be indeterminate.

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

There are special cases:

s == NULL
  mbtowc(``) initializes its own internal state to an initial state, and determines whether the current encoding is state-dependent. This function returns 0 if the encoding is state-independent, otherwise non-zero. In this case, ```pwc` is completely ignored.

pwc == NULL
  mbtowc(``) executes the conversion as if ```pwc` is non-NULL, but a result of the conversion is discarded.

n == 0
  In this case, the first ```n` bytes of the array pointed to by ```s` never form a complete character. Thus, the mbtowc(``) always fails.

### RETURN VALUES

Normally, the mbtowc(``) returns:

0
  ```s` points to a nul byte (`\0').

positive
  Number of bytes for the valid multibyte character pointed to by ```s`. There are no cases that the value returned is greater than the value of the ```MB_CUR_MAX` macro.

-1
  ```s` points to an invalid or an incomplete multibyte character. The mbtowc(``) also sets errno to indicate the error.

When ```s` is equal to ```NULL`, mbtowc(``) returns:

0
  The current encoding is state-independent.

non-zero
  The current encoding is state-dependent.

### ERRORS

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

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

### SEE ALSO

mblen(3), mbrtowc(3), setlocale(3)

### STANDARDS

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