NAME

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

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 nmc, size_t len, mbstate_t * restrict ps);

DESCRIPTION

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

• The conversion reaches a null byte. In this case, the null byte is also converted.
• The conversion has already stored len wide characters.
• The conversion encounters an invalid character.

The mbsnrtowcs() function is equivalent to mbsrtowcs() except that it will additionally stop the conversion after processing nmc bytes.

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

After conversion, if dst is not a null pointer, the pointer object pointed to by src is a null pointer (if the conversion is stopped due to reaching a null byte) or the address just past the last byte processed.

If dst is not a null pointer and the conversion is stopped due to reaching a null byte, the state object pointed to by ps is set to an initial state after the conversion has taken place.

The behaviour of the mbsrtowcs() and mbsnrtowcs() functions is affected by the LC_CTYPE category of the current locale.

There are two special cases:

dst == NULL

The conversion takes place, but the resultant wide-character string is discarded. In this case, the pointer object pointed to by src is not modified and len is ignored.

ps == NULL

The mbsrtowcs() and mbsnrtowcs() functions use their own internal state objects to keep the conversion state, instead of ps as mentioned in this manual page.

Calling any other functions in libc never change these internal states, which are initialized at startup time of the program.

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 dst, except for a terminating null wide character (if any). If dst is not null and the value returned is equal to len, the wide-character string pointed to by dst is not null terminated. If dst is a null pointer, the value returned is the number of elements to contain the whole string converted, except for a terminating null wide character.

(size_t)-1

The array indirectly pointed to by src contains a byte sequence forming invalid character. In this case, errno is set to indicate the error.

ERRORS

The mbsrtowcs() and mbsnrtowcs() functions may return the following errors:

[EILSEQ]

The pointer pointed to by src 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)”.

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