OpenBSD manual page server

Manual Page Search Parameters

WCSRTOMBS(3) Library Functions Manual WCSRTOMBS(3)

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

#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);

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 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.

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.

The wcsrtombs() and wcsnrtombs() functions may return the following errors:
[]
src points to the string containing an invalid wide character.
[]
ps points to an invalid or uninitialized mbstate_t object.

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

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”).

June 5, 2013 OpenBSD-current