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