MBSRTOWCS(3)

MBSRTOWCS(3) | Library Functions Manual | MBSRTOWCS(3)

# NAME

`mbsrtowcs` —
converts a multibyte character string to a wide-character string (restartable)

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <wchar.h>`

size_t
`mbsrtowcs`(wchar_t * restrict pwcs, const char ** restrict s, size_t n, mbstate_t * restrict ps);

# DESCRIPTION

The `mbsrtowcs`() converts the multibyte character string indirectly pointed to by s to the corresponding wide-character string, and stores it in the array pointed to by pwcs. The conversion stops due to the following reasons:

- The conversion reaches a nul byte. In this case, the nul byte is also converted.
- The `mbsrtowcs`() has already stored n wide characters.
- The conversion encounters an invalid character.

Each character will be converted as if mbrtowc(3) is continuously called.

After conversion, if pwcs is not a null pointer, the pointer object pointed to by s is a null pointer (if the conversion is stopped due to reaching a nul byte) or the first byte of the character just after the last character converted.

If pwcs is not a null pointer and the conversion is stopped due to reaching a nul byte, the `mbsrtowcs`() places the state object pointed to by ps to an initial state after the conversion has taken place.

The behaviour of `mbsrtowcs`() is affected by the `LC_CTYPE` category of the current locale.

These are the special cases:

s == NULL || *s == NULL
  Undefined (may cause the program to crash).
pwcs == NULL
  The conversion has taken place, but the resulting wide-character string was discarded. In this case, the pointer object pointed to by s is not modified and n is ignored.
ps == NULL
  The `mbsrtowcs`() uses its own internal state object to keep the conversion state, instead of ps mentioned in this manual page.

  Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of `mbsrtowcs`(), which is initialized at startup time of the program.

# RETURN VALUES

`mbsrtowcs`() returns:

0 or positive
  The value returned is the number of elements stored in the array pointed to by pwcs, except for a terminating nul wide character (if any). If pwcs is not `NULL` and the value returned is equal to n, the wide-character string pointed to by pwcs is not nul-terminated. If pwcs is a null pointer, the value returned is the number of elements to contain the whole string converted, except for a terminating nul wide character.
(size_t)-1
  The array indirectly pointed to by s contains a byte sequence forming invalid character. In this case, `mbsrtowcs`() sets errno to indicate the error.

# ERRORS

`mbsrtowcs`() may cause an error in the following case:

[`EILSEQ`]
  The pointer pointed to by s points to an invalid or incomplete multibyte character.
[`EINVAL`]
  ps points to an invalid or uninitialized mbstate_t object.

# SEE ALSO

mbrtowc(3), mbstowcs(3), setlocale(3)

# STANDARDS

The `mbsrtowcs`() function conforms to ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”). The restrict qualifier is added at ISO/IEC 9899:1999 (“ISO C99”).

February 4, 2002 | NetBSD 9.0