---
name: "mbrtowc"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/mbrtowc"
---

# mbrtowc(3)

convert a multibyte sequence to a wide character

## NAME

mbrtowc - convert a multibyte sequence to a wide character

## LIBRARY

Standard C library (*libc*, *-lc*)

## SYNOPSIS

```
#include <wchar.h>
```

**size\_t mbrtowc(**size\_t n;                **wchar\_t \*restrict** *pwc***, const char** *s***\[restrict** *n***\],**                **size\_t** *n***, mbstate\_t \*restrict** *ps***);**

## DESCRIPTION

The main case for this function is when *s* is not NULL and *pwc* is not NULL. In this case, the **mbrtowc**() function inspects at most *n* bytes of the multibyte string starting at *s*, extracts the next complete multibyte character, converts it to a wide character and stores it at *\*pwc*. It updates the shift state *\*ps*. If the converted wide character is not L'\\0' (the null wide character), it returns the number of bytes that were consumed from *s*. If the converted wide character is L'\\0', it resets the shift state *\*ps* to the initial state and returns 0.

If the *n* bytes starting at *s* do not contain a complete multibyte character, **mbrtowc**() returns *(size\_t) -2*. This can happen even if *n* \>= *MB\_CUR\_MAX*, if the multibyte string contains redundant shift sequences.

If the multibyte string starting at *s* contains an invalid multibyte sequence before the next complete character, **mbrtowc**() returns *(size\_t) -1* and sets *errno* to **EILSEQ**. In this case, the effects on *\*ps* are undefined.

A different case is when *s* is not NULL but *pwc* is NULL. In this case, the **mbrtowc**() function behaves as above, except that it does not store the converted wide character in memory.

A third case is when *s* is NULL. In this case, *pwc* and *n* are ignored. If the conversion state represented by *\*ps* denotes an incomplete multibyte character conversion, the **mbrtowc**() function returns *(size\_t) -1*, sets *errno* to **EILSEQ**, and leaves *\*ps* in an undefined state. Otherwise, the **mbrtowc**() function puts *\*ps* in the initial state and returns 0.

In all of the above cases, if *ps* is NULL, a static anonymous state known only to the **mbrtowc**() function is used instead. Otherwise, *\*ps* must be a valid *mbstate\_t* object. An *mbstate\_t* object *a* can be initialized to the initial state by zeroing it, for example using

```
memset(&a, 0, sizeof(a));
```

## RETURN VALUE

The **mbrtowc**() function returns the number of bytes parsed from the multibyte sequence starting at *s*, if a non-L'\\0' wide character was recognized. It returns 0, if a L'\\0' wide character was recognized. It returns *(size\_t) -1* and sets *errno* to **EILSEQ**, if an invalid multibyte sequence was encountered. It returns *(size\_t) -2* if the consumed *n* bytes form a valid partial character sequence; more subsequent data needs to be fed in.

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **mbrtowc**() | Thread safety | MT-Unsafe race:mbrtowc/!ps |

## STANDARDS

C11, POSIX.1-2008.

## HISTORY

POSIX.1-2001, C99.

## NOTES

The behavior of **mbrtowc**() depends on the **LC\_CTYPE** category of the current locale.

## SEE ALSO

[**mbsinit**(3)](/mbsinit/3.md), [**mbsrtowcs**(3)](/mbsrtowcs/3.md)