NAME

wcsrtombs, wcsnrtombs — converts a wide-character string to a multibyte character string (restartable)

SYNOPSIS

#include <wchar.h>

size_t
wcsrtombs(const char * restrict dst, const wchar_t ** restrict src, size_t len, mbstate_t * restrict ps);

size_t
wcsnrtombs(const char * restrict dst, const wchar_t ** restrict src, size_t nwc, size_t len, mbstate_t * restrict ps);

DESCRIPTION

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

• The conversion reaches a null wide character. In this case, the null wide character is also converted.
• The conversion has already stored len bytes to the array pointed to by dst.
• The conversion encounters an invalid character.

The wcsnrtombs() function is equivalent to wcsrtombs() except that it additionally stops the conversion after processing nwc wide characters.

Each character will be converted as if wcrtomb(3) is continuously called, except the internal state of wcrtomb(3) will not be affected.

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 wide character) or the address just past the last wide character processed.

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

The behaviour of the wcsrtombs() and wcsnrtombs() 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 resulting multibyte string is discarded. In this case, the pointer object pointed to by src is not modified and len is ignored.

ps == NULL

The wcsrtombs() and wcsnrtombs() 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 wcsrtombs() and wcsnrtombs() functions return:

0 or positive

Number of bytes stored to the array pointed to by dst, except for a null byte. There is no cases that the value returned is greater than len (unless dst is a null pointer). If the return value is equal to len, the string pointed to by dst will not be null-terminated.

(size_t)-1

src points to the string containing invalid wide character. In this case, errno is set to indicate the error.

ERRORS

The wcsrtombs() and wcsnrtombs() functions may return the following errors:

[EILSEQ]

src points to the string containing an invalid wide character.

[EINVAL]

ps points to an invalid or uninitialized mbstate_t object.

SEE ALSO

setlocale(3), wcrtomb(3), wcstombs(3)

STANDARDS

The wcsrtombs() function conforms to ANSI X3.159-1989 (“ANSI C89”). The restrict qualifier is added at ISO/IEC 9899/AMD1:1995 (“ISO C99”).

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