MBSRTOWCS(3)

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

# NAME

`mbsrtowcs`, `mbsrntowcs` —
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);

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

# DESCRIPTION

The `mbsrtowcs`() function 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.

The `mbsnrtowcs`() function behaves identically to `mbsrtowcs`(), except that the conversion stops after reading at most nmc characters from the buffer pointed to by s.

# RETURN VALUES

The `mbsrtowcs`() and `mbsnrtowcs`() functions return:

`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

The `mbsrtowcs`() and `mbsnrtowcs`() functions may fail with the following errors:

[`EILSEQ`]
  s points to a string containing 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 was added by ISO/IEC 9899:1999 (“ISO C99”).

The `mbsnrtowcs`() function conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

September 9, 2024 | NetBSD 10.1