NAME
mbsrtowcs,
mbsnrtowcs —
converts a multibyte character string
to a wide-character string (restartable)
SYNOPSIS
#include
<wchar.h>
size_t
mbsrtowcs(wchar_t
* restrict dst, const
char ** restrict src,
size_t len,
mbstate_t * restrict
ps);
size_t
mbsnrtowcs(wchar_t
* restrict dst, const
char ** restrict src,
size_t nmc,
size_t len,
mbstate_t * restrict
ps);
DESCRIPTION
The
mbsrtowcs()
function converts the multibyte character string indirectly pointed to by
src to the corresponding wide-character string and
stores it in the array pointed to by dst. The
conversion stops due to the following reasons:
- The conversion reaches a null byte. In this case, the null byte is also converted.
- The conversion has already stored len wide characters.
- The conversion encounters an invalid character.
The
mbsnrtowcs()
function is equivalent to mbsrtowcs() except that it
will additionally stop the conversion after processing
nmc bytes.
Each character is converted as if mbrtowc(3) is continuously called.
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 byte) or the address just past the last byte processed.
If dst is not a null pointer and the conversion is stopped due to reaching a null byte, the state object pointed to by ps is set to an initial state after the conversion has taken place.
The behaviour of the
mbsrtowcs()
and mbsnrtowcs() 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 resultant wide-character string is discarded. In this case, the pointer object pointed to by src is not modified and len is ignored.
- ps == NULL
- The
mbsrtowcs() andmbsnrtowcs() 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 mbsrtowcs() and
mbsnrtowcs() functions return:
- 0 or positive
- The value returned is the number of elements stored in the array pointed to by dst, except for a terminating null wide character (if any). If dst is not null and the value returned is equal to len, the wide-character string pointed to by dst is not null terminated. If dst is a null pointer, the value returned is the number of elements to contain the whole string converted, except for a terminating null wide character.
- (size_t)-1
- The array indirectly pointed to by src contains a byte sequence forming invalid character. In this case, errno is set to indicate the error.
ERRORS
The mbsrtowcs() and
mbsnrtowcs() functions may return the following
errors:
- [
EILSEQ] - The pointer pointed to by src points to an invalid or incomplete multibyte character.
- [
EINVAL] - ps points to an invalid or uninitialized mbstate_t object.
SEE ALSO
STANDARDS
The mbsrtowcs() function conforms to
ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”). The restrict
qualifier is added at ISO/IEC 9899/1999 “(ISO C99)”.
The mbsnrtowcs() function conforms to
IEEE Std 1003.1-2008 (“POSIX.1”).