MBSRTOWCS(3C) Standard C Library Functions MBSRTOWCS(3C)
NAME
mbsnrtowcs, mbsnrtowcs_l, mbsrtowcs, mbsrtowcs_l - convert a
character string to a wide-character string (restartable)
SYNOPSIS
#include <wchar.h>
size_t mbsnrtowcs(
wchar_t *restrict dst,
const char **restrict src,
size_t nms,
size_t len,
mbstate_t *restrict ps);
size_t mbsrtowcs(
wchar_t *restrict dst,
const char **restrict src,
size_t len,
mbstate_t *restrict ps);
#include <wchar.h>
#include <xlocale.h>
size_t mbsnrtowcs_l(
wchar_t *restrict dst,
const char **restrict src,
size_t nms,
size_t len,
mbstate_t *restrict ps,
locale_t loc);
size_t mbsrtowcs_l(
wchar_t *restrict dst,
const char **restrict src,
size_t len,
mbstate_t *restrict ps,
locale_t loc);
DESCRIPTION
These function converts a sequence of characters, beginning in the
conversion state described by the object pointed to by
ps, from the
array indirectly pointed to by
src into a sequence of corresponding
wide-characters. If
dst is not a null pointer, the converted
characters are stored into the array pointed to by
dst. Conversion
continues up to and including a terminating null character, which is
also stored. Conversion stops early in either of the following
cases:
o When a sequence of bytes is encountered that does not form
a valid character.
o When
len codes have been stored into the array pointed to
by
dst (and
dst is not a null pointer).
Each conversion takes place as if by a call to the
mbrtowc() function.
If
dst is not a null pointer, the pointer object pointed to by
src is
assigned either a null pointer (if conversion stopped due to reaching
a terminating null character) or the address just past the last
character converted (if any). If conversion stopped due to reaching
a terminating null character, and if
dst is not a null pointer, the
resulting state described is the initial conversion state.
If
ps is a null pointer, these functions uses their own internal
mbstate_t object, which is initialized at program startup to the
initial conversion state. Otherwise, the
mbstate_t object pointed to
by
ps is used to completely describe the current conversion state of
the associated character sequence. The system will behave as if no
function defined in the Reference Manual calls any of these
functions.
The function
mbsnrtowcs() behaves identically to
mbsrtowcs(), except
the conversion stops after reading
nms bytes from the buffer pointed
to by
src.
The behavior of
mbnrtowcs() and
mbsrtowcs() functions are affected by
the
LC_CTYPE category of the current locale. See
environ(7). The
functions
mbsrtowcs_l() and
mbsnrtowcs_l() behave identically to
mbsrtowcs() and
mbsnrtowcs(), except that instead of using the
current locale, they use the locale specified by
loc.
RETURN VALUES
If the input conversion encounters a sequence of bytes that do not
form a valid character, an encoding error occurs. In this case,
these functions store the value of the macro
EILSEQ in
errno and
return
(size_t)-1; the conversion state is undefined. Otherwise,
they return the number of characters successfully converted, not
including the terminating null (if any).
ERRORS
These functions may fail if:
EINVAL The
ps argument points to an object that contains an
invalid conversion state.
EILSEQ Invalid character sequence is detected.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+
|MT-Level | See below. |
+--------------------+-----------------+
The
mbsnrtowcs() and
mbsrtowcs() functions are Standard. The
mbsnrtowcs_l() and
mbsrtowcs_l() functions are Uncommitted.
If
ps is not a null pointer, these functions use the
mbstate_t object
pointed to by
ps and can be used safely in multithreaded
applications, otherwise they use an internal
mbstate_t object and are
Unsafe in multithreaded applications.
SEE ALSO
mbrtowc(3C),
mbsinit(3C),
newlocale(3C),
setlocale(3C),
uselocale(),
attributes(7),
environ(7),
standards(7) December 28, 2020 MBSRTOWCS(3C)
