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

# wcstombs(3)

convert a wide-character string to a character string

## NAME

**wcstombs**, **wcstombs\_l** – convert a wide-character string to a character string

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

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

*size\_t*\

**wcstombs**(*char \*restrict s*, *const wchar\_t \*restrict pwcs*, *size\_t n*);

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

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

*size\_t*\

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

## DESCRIPTION

The **wcstombs**() function converts a wide character string *pwcs* into a multibyte character string, *s*, beginning in the initial conversion state. Up to *n* bytes are stored in *s*. Partial multibyte characters at the end of the string are not stored. The multibyte character string is null terminated, if there is room.

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

## RETURN VALUES

The **wcstombs**() function returns the number of bytes converted (not including any terminating null), if successful; otherwise, it returns (*size\_t*)-1.

## ERRORS

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

- \[EILSEQ\]

  An invalid wide character was encountered.

- \[EINVAL\]

  The conversion state is invalid.

## SEE ALSO

[mbstowcs(3)](/mbstowcs/3.md), [multibyte(3)](/multibyte/3.md), [wcsrtombs(3)](/wcsrtombs/3.md), [wctomb(3)](/wctomb/3.md), [xlocale(3)](/xlocale/3.md)

## STANDARDS

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