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

# wcsrtombs(3)

convert a wide-character string to a multibyte string

## NAME

wcsrtombs - convert a wide-character string to a multibyte string

## LIBRARY

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

## SYNOPSIS

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

**size\_t wcsrtombs(**size\_t dsize;                  **char** *dest***\[restrict** *dsize***\],**                  **const wchar\_t \*\*restrict** *src***,**                  **size\_t** *dsize***, mbstate\_t \*restrict** *ps***);**

## DESCRIPTION

If *dest* is not NULL, the **wcsrtombs**() function converts the wide-character string *\*src* to a multibyte string starting at *dest*. At most *dsize* bytes are written to *dest*. The shift state *\*ps* is updated. The conversion is effectively performed by repeatedly calling *wcrtomb(dest, \*src, ps)*, as long as this call succeeds, and then incrementing *dest* by the number of bytes written and *\*src* by one. The conversion can stop for three reasons:

- •

  A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case, *\*src* is left pointing to the invalid wide character, *(size\_t) -1* is returned, and *errno* is set to **EILSEQ**.

- •

  The size limit forces a stop. In this case, *\*src* is left pointing to the next wide character to be converted, and the number of bytes written to *dest* is returned.

- •

  The wide-character string has been completely converted, including the terminating null wide character (L'\\0'), which has the side effect of bringing back *\*ps* to the initial state. In this case, *\*src* is set to NULL, and the number of bytes written to *dest*, excluding the terminating null byte ('\\0'), is returned.

If *dest* is NULL, *dsize* is ignored, and the conversion proceeds as above, except that the converted bytes are not written out to memory, and that no size limit exists.

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

The programmer must ensure that there is room for at least *dsize* bytes at *dest*.

## RETURN VALUE

The **wcsrtombs**() function returns the number of bytes that make up the converted part of multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted, *(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** |
| **wcsrtombs**() | Thread safety | MT-Unsafe race:wcsrtombs/!ps |

## STANDARDS

C11, POSIX.1-2008.

## HISTORY

POSIX.1-2001, C99.

## NOTES

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

Passing NULL as *ps* is not multithread safe.

## SEE ALSO

[**iconv**(3)](/iconv/3.md), [**mbsinit**(3)](/mbsinit/3.md), [**wcrtomb**(3)](/wcrtomb/3.md), [**wcsnrtombs**(3)](/wcsnrtombs/3.md), [**wcstombs**(3)](/wcstombs/3.md)