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

# mbstowcs(3)

convert a character string to a wide-character string

## NAME

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

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

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

*size\_t*\

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

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

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

*size\_t*\

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

## DESCRIPTION

The **mbstowcs**() function converts a multibyte character string *s*, beginning in the initial conversion state, into a wide character string *pwcs*. No more than *n* wide characters are stored. A terminating null wide character is appended, if there is room.

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

## RETURN VALUES

The **mbstowcs**() function returns the number of wide characters converted, not counting any terminating null wide character, or -1 if an invalid multibyte character was encountered.

## ERRORS

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

- \[EILSEQ\]

  An invalid multibyte sequence was detected.

- \[EINVAL\]

  The conversion state is invalid.

## SEE ALSO

[mbsrtowcs(3)](/mbsrtowcs/3.md), [mbtowc(3)](/mbtowc/3.md), [multibyte(3)](/multibyte/3.md), [xlocale(3)](/xlocale/3.md)

## STANDARDS

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