MBSRTOWCS(3)

NAME
mbsrtowcs, mbsrtowcs_l, mbsnrtowcs, mbsnrtowcs_l - 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
mbsrtowcs_l(wchar_t * restrict dst, const char ** restrict src, size_t len, mbstate_t * restrict ps, locale_t l);
size_t
mbsnrtowcs(wchar_t * restrict dst, const char ** restrict src, size_t nmc, size_t len, mbstate_t * restrict ps);
size_t
mbsnrtowcs_l(wchar_t * restrict dst, const char ** restrict src, size_t nmc, size_t len, mbstate_t * restrict ps, locale_t l);

DESCRIPTION
The functions mbsrtowcs() and mbsrtowcs_l() convert 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() and mbsnrtowcs_l() functions are equivalent to mbsrtowcs() except that they 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, while the behaviour of the mbsrtowcs_l() and mbsnrtowcs_l() functions is affected by the LC_CTYPE category of the locale provided as parameter, see xlocale(3)

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
    These functions 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(), mbsrtowcs_l(), mbsnrtowcs(), mbsnrtowcs_l() 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
    src is NULL or points to NULL or to an array that contains a byte sequence forming invalid character. In this case, errno is set to indicate the error.

ERRORS
These functions may return the following errors:

[EILSEQ]
    src is NULL or points to NULL or 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) xlocale(3)

STANDARDS
The mbsrtowcs() function conforms to POSIX 2008, 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 p1003.1-2008.