---
name: "wcrtomb"
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/wcrtomb"
---

# wcrtomb(3)

convert a wide character to a multibyte sequence

## NAME

wcrtomb - convert a wide character to a multibyte sequence

## LIBRARY

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

## SYNOPSIS

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

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

## DESCRIPTION

The main case for this function is when *s* is not NULL and *wc* is not a null wide character (L'\\0'). In this case, the **wcrtomb**() function converts the wide character *wc* to its multibyte representation and stores it at the beginning of the character array pointed to by *s*. It updates the shift state *\*ps*, and returns the length of said multibyte representation, that is, the number of bytes written at *s*.

A different case is when *s* is not NULL, but *wc* is a null wide character (L'\\0'). In this case, the **wcrtomb**() function stores at the character array pointed to by *s* the shift sequence needed to bring *\*ps* back to the initial state, followed by a '\\0' byte. It updates the shift state *\*ps* (i.e., brings it into the initial state), and returns the length of the shift sequence plus one, that is, the number of bytes written at *s*.

A third case is when *s* is NULL. In this case, *wc* is ignored, and the function effectively returns

```
wcrtomb(buf, L'\0', ps)
```

where *buf* is an internal anonymous buffer.

In all of the above cases, if *ps* is NULL, a static anonymous state known only to the **wcrtomb**() function is used instead.

At most **MB\_CUR\_MAX** bytes will be written at *s*. The programmer must ensure that there is enough room to store the multibyte sequence at *s*.

## RETURN VALUE

The **wcrtomb**() function returns the number of bytes that have been or would have been written to the byte array at *s*. If *wc* can not be represented as a multibyte sequence (according to the current locale), *(size\_t) -1* is returned, and *errno* set to **EILSEQ**.

## ATTRIBUTES

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

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

## STANDARDS

C11, POSIX.1-2008.

## HISTORY

POSIX.1-2001, C99.

## NOTES

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

Passing NULL as *ps* is not multithread safe.

## SEE ALSO

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