---
name: "mbtowc"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/mbtowc"
---

# mbtowc(3)

convert a character to a wide-character code

## NAME

**mbtowc**, **mbtowc\_l** – convert a character to a wide-character code

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<stdlib.h\>**

*int*\

**mbtowc**(*wchar\_t \*restrict pwc*, *const char \*restrict s*, *size\_t n*);

**#include \<stdlib.h\>**

**#include \<xlocale.h\>**

*int*\

**mbtowc\_l**(*wchar\_t \*restrict pwc*, *const char \*restrict s*, *size\_t n*, *locale\_t loc*);

## DESCRIPTION

The **mbtowc**() function converts a multibyte character *s* into a wide character, according to the current conversion state, and stores the result in the object pointed to by *pwc*. Up to *n* bytes are examined.

A call with a null *s* pointer returns nonzero if the current encoding requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state.

While the **mbtowc**() function uses the current locale, the **mbtowc\_l**() function may be passed a locale directly. See [xlocale(3)](/xlocale/3.md) for more information.

## RETURN VALUES

If *s* is NULL, the **mbtowc**() function returns nonzero if shift states are supported, zero otherwise.

Otherwise, if *s* is not a null pointer, **mbtowc**() either returns 0 if *s* represents the null wide character, or returns the number of bytes processed in *s*, or returns -1 if no multibyte character could be recognized or converted. In this case, **mbtowc**(*Ns*, *'s*) internal conversion state is undefined.

## ERRORS

The **mbtowc**() function will fail if:

- \[EILSEQ\]

  An invalid multibyte sequence was detected.

- \[EINVAL\]

  The internal conversion state is invalid.

## SEE ALSO

[btowc(3)](/btowc/3.md), [mblen(3)](/mblen/3.md), [mbrtowc(3)](/mbrtowc/3.md), [mbstowcs(3)](/mbstowcs/3.md), [multibyte(3)](/multibyte/3.md), [wctomb(3)](/wctomb/3.md), [xlocale(3)](/xlocale/3.md)

## STANDARDS

The **mbtowc**() function conforms to ISO/IEC 9899:1999 (“ISO C99”).