mbsrtowcsmbsnrtowcs
- convert a character string to a wide-character string (restartable)
LIBRARY
Lb libc
SYNOPSIS
#include <wchar.h> size_t
Fo mbsrtowcs
Fa wchar_t * restrict dst const char ** restrict src size_t len
Fa mbstate_t * restrict ps
Fc Ft size_t
Fo mbsnrtowcs
Fa wchar_t * restrict dst const char ** restrict src size_t nms
Fa size_t len mbstate_t * restrict ps
Fc
DESCRIPTION
The
mbsrtowcs ();
function converts a sequence of multibyte characters pointed to indirectly by
Fa src
into a sequence of corresponding wide characters and stores at most
Fa len
of them in the
Vt wchar_t
array pointed to by
Fa dst ,
until it encounters a terminating null character
('\0'
)
If
Fa dst
is
NULL
no characters are stored.
If
Fa dst
is not
NULL
the pointer pointed to by
Fa src
is updated to point to the character after the one that conversion stopped at.
If conversion stops because a null character is encountered,
Fa *src
is set to
NULL
The
Vt mbstate_t
argument,
Fa ps ,
is used to keep track of the shift state.
If it is
NULL
mbsrtowcs ();
uses an internal, static
Vt mbstate_t
object, which is initialized to the initial conversion state
at program startup.
The
mbsnrtowcs ();
function behaves identically to
mbsrtowcs (,);
except that conversion stops after reading at most
Fa nms
bytes from the buffer pointed to by
Fa src .
RETURN VALUES
The
mbsrtowcs ();
and
mbsnrtowcs ();
functions return the number of wide characters stored in
the array pointed to by
Fa dst
if successful, otherwise it returns
Po Vt size_t Pc Ns -1 .
ERRORS
The
mbsrtowcs ();
and
mbsnrtowcs ();
functions will fail if:
Bq Er EILSEQ
An invalid multibyte character sequence was encountered.
