NAME
wcsrtombs,
wcsrtombs_l, wcsnrtombs,
wcsnrtombs_l —
convert a wide-character string to a
character string (restartable)
LIBRARY
library “libc”
SYNOPSIS
#include
<wchar.h>
size_t
wcsrtombs(char * restrict dst,
const wchar_t ** restrict src, size_t
len, mbstate_t * restrict ps);
size_t
wcsnrtombs(char * restrict dst,
const wchar_t ** restrict src, size_t
nwc, size_t len, mbstate_t *
restrict ps);
#include
<xlocale.h>
size_t
wcsrtombs_l(char * restrict dst,
const wchar_t ** restrict src, size_t
len, mbstate_t * restrict ps,
locale_t locale);
size_t
wcsnrtombs_l(char * restrict
dst, const wchar_t ** restrict src,
size_t nwc, size_t len,
mbstate_t * restrict ps, locale_t
locale);
DESCRIPTION
Thewcsrtombs()
and wcsrtombs_l() functions convert a string of wide
characters indirectly pointed to by src to a
corresponding multibyte character string stored in the array pointed to by
dst. No more than len bytes are
written to dst.
If dst is NULL, no
characters are stored.
If dst is not NULL,
the pointer pointed to by src is updated to point to
the character after the one that conversion stopped at. If conversion stops
because a null character is encountered, *src is set
to NULL.
The mbstate_t argument,
ps, is used to keep track of the shift state. If it is
NULL,
wcsrtombs()
and wcsrtombs_l() use an internal, static
mbstate_t object, which is initialized to the initial
conversion state at program startup.
The
wcsnrtombs()
and
wcsnrtombs_l()
functions behave identically to wcsrtombs() and
wcsrtombs_l(), except that conversion stops after
reading at most nwc characters from the buffer pointed
to by src.
The
wcsrtombs_l()
and
wcsnrtombs_l()
functions take an explicit locale argument, whereas
the wcsrtombs() and
wcsnrtombs() functions use the current global or
per-thread locale.
RETURN VALUES
The wcsrtombs(),
wcsrtombs_l(), wcsnrtombs(),
and wcsnrtombs_l() functions return the number of
bytes stored in the array pointed to by dst (not
including any terminating null), if successful, otherwise they return
(size_t)-1.
ERRORS
The wcsrtombs(),
wcsrtombs_l(), wcsnrtombs(),
and wcsnrtombs_l() functions will fail if:
- [
EILSEQ] - An invalid wide character was encountered.
- [
EINVAL] - The conversion state is invalid.
SEE ALSO
STANDARDS
The wcsrtombs() function conforms to
ISO/IEC 9899:1999
(“ISO C99”).
The wcsrtombs_l(),
wcsnrtombs(), and
wcsnrtombs_l() functions are an extension to the
standard.