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

# mbsrtowcs(3)

convert a character string to a wide-character string (restartable)

## NAME

**mbsnrtowcs**, **mbsnrtowcs\_l**, **mbsrtowcs**, **mbsrtowcs\_l** – convert a character string to a wide-character string (restartable)

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

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

*size\_t*\

**mbsnrtowcs**(*wchar\_t \*restrict dst*, *const char \*\*restrict src*, *size\_t nms*, *size\_t len*, *mbstate\_t \*restrict ps*);

*size\_t*\

**mbsrtowcs**(*wchar\_t \*restrict dst*, *const char \*\*restrict src*, *size\_t len*, *mbstate\_t \*restrict ps*);

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

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

*size\_t*\

**mbsrtowcs\_l**(*wchar\_t \*restrict dst*, *const char \*\*restrict src*, *size\_t len*, *mbstate\_t \*restrict ps*, *locale\_t loc*);

*size\_t*\

**mbsnrtowcs\_l**(*wchar\_t \*restrict dst*, *const char \*\*restrict src*, *size\_t nms*, *size\_t len*, *mbstate\_t \*restrict ps*, *locale\_t loc*);

## DESCRIPTION

The **mbsrtowcs**() function converts a sequence of multibyte characters, pointed to indirectly by *src*, into a sequence of corresponding wide characters. It stores at most *len* of them in the *wchar\_t* array pointed to by *dst*, until it encounters a terminating null character ('\\0').

If *dst* is NULL, no characters are stored.

If *dst* is not NULL, the pointer pointed to by *src* is updated to point to the character after the one that conversion stopped at. If conversion stops because a null character is encountered, *\*src* is set to NULL.

The *mbstate\_t* argument, *ps*, is used to keep track of the shift state. If it is NULL, **mbsrtowcs**() uses an internal, static *mbstate\_t* object, which is initialized to the initial conversion state at program startup.

The **mbsnrtowcs**() function behaves identically to **mbsrtowcs**(), except that conversion stops after reading at most *nms* bytes from the buffer pointed to by *src*.

While the **mbsrtowcs**() and **mbsnrtowcs**() functions use the current locale, the **mbsrtowcs\_l**() and **mbsnrtowcs\_l**() functions may be passed locales directly. See [xlocale(3)](/xlocale/3.md) for more information.

## RETURN VALUES

The **mbsrtowcs**() and **mbsnrtowcs**() functions return the number of wide characters stored in the array pointed to by *dst* if successful, otherwise it returns (*size\_t*)-1.

## ERRORS

The **mbsrtowcs**() and **mbsnrtowcs**() functions will fail if:

- \[EILSEQ\]

  An invalid multibyte character sequence was encountered.

- \[EINVAL\]

  The conversion state is invalid.

## SEE ALSO

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

## STANDARDS

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

The **mbsnrtowcs**() function is an extension to the standard.