---
name: "mbsrtowcs"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/mbsnrtowcs"
---

# mbsrtowcs(3)

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

Part of [mbsnrtowcs(3)](/mbsnrtowcs/3.md).

## NAME

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

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

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

*size\_t*\

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

*size\_t*\

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

## DESCRIPTION

The **mbsrtowcs**() function converts a sequence of multibyte characters pointed to indirectly by *src* into a sequence of corresponding wide characters and 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*.

## RETURN VALUES

If successful, and *dst* is not NULL, the **mbsrtowcs**() and **mbsnrtowcs**() functions return the number of wide characters stored in the array pointed to by *dst*.

If *dst* was NULL then the functions **mbsrtowcs**() and **mbsnrtowcs**() return the number of wide characters that would have been stored where *dst* points to an infinitely large array.

If either one of the functions is not successful then (*size\_t*)-1 is returned.

## 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)

## STANDARDS

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

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