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

# wcrtomb(3)

convert a wide-character code to a character (restartable)

## NAME

**wcrtomb**, **wcrtomb\_l** – convert a wide-character code to a character (restartable)

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

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

*size\_t*\

**wcrtomb**(*char \*restrict s*, *wchar\_t wc*, *mbstate\_t \*restrict ps*);

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

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

*size\_t*\

**wcrtomb\_l**(*char \*restrict s*, *wchar\_t wc*, *mbstate\_t \*restrict ps*, *locale\_t loc*);

## DESCRIPTION

The **wcrtomb**() function stores a multibyte sequence representing the wide character *wc*, including any necessary shift sequences, to the character array *s*. A maximum of MB\_CUR\_MAX bytes will be stored.

If *s* is NULL, **wcrtomb**() behaves as if *s* pointed to an internal buffer and *wc* were a null wide character (L'\\0').

The *mbstate\_t* argument, *ps*, is used to keep track of the shift state. If it is NULL, **wcrtomb**() uses an internal, static *mbstate\_t* object, which is initialized to the initial conversion state at program startup.

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

## RETURN VALUES

The **wcrtomb**() functions returns the length (in bytes) of the multibyte sequence needed to represent *wc*, or (*size\_t*)-1 if *wc* is not a valid wide character code.

## ERRORS

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

- \[EILSEQ\]

  An invalid wide character code was specified.

- \[EINVAL\]

  The conversion state is invalid.

## SEE ALSO

[mbrtowc(3)](/mbrtowc/3.md), [multibyte(3)](/multibyte/3.md), [setlocale(3)](/setlocale/3.md), [wctomb(3)](/wctomb/3.md), [xlocale(3)](/xlocale/3.md)

## STANDARDS

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