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

# wcstombs(3)

convert a wide-character string to a multibyte string

## NAME

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

## LIBRARY

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

## SYNOPSIS

```
#include <stdlib.h>
```

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

## DESCRIPTION

If *dest* is not NULL, the **wcstombs**() function converts the wide-character string *src* to a multibyte string starting at *dest*. At most *dsize* bytes are written to *dest*. The sequence of characters placed in *dest* begins in the initial shift state. 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, *(size\_t) -1* is returned.

- •

  The length limit forces a stop. In this case, the number of bytes written to *dest* is returned, but the shift state at this point is lost.

- •

  The wide-character string has been completely converted, including the terminating null wide character (L'\\0'). In this case, the conversion ends in the initial shift state. The number of bytes written to *dest*, excluding the terminating null byte ('\\0'), is returned.

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

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 no length limit exists.

In order to avoid the case 2 above, the programmer should make sure *dsize* is greater than or equal to *wcstombs(NULL,src,0)+1*.

## RETURN VALUE

The **wcstombs**() function returns the number of bytes that make up the converted part of a multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted, *(size\_t) -1* is returned.

## ATTRIBUTES

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

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **wcstombs**() | Thread safety | MT-Safe |

## VERSIONS

The function [**wcsrtombs**(3)](/wcsrtombs/3.md) provides a better interface to the same functionality.

## STANDARDS

C11, POSIX.1-2008.

## HISTORY

POSIX.1-2001, C99.

## NOTES

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

## SEE ALSO

[**mblen**(3)](/mblen/3.md), [**mbstowcs**(3)](/mbstowcs/3.md), [**mbtowc**(3)](/mbtowc/3.md), [**wcsrtombs**(3)](/wcsrtombs/3.md), [**wctomb**(3)](/wctomb/3.md)