NAME
mbsrtowcs —
converts a multibyte
character string to a wide-character string (restartable)
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <wchar.h>
size_t
mbsrtowcs(
wchar_t
* restrict pwcs,
const char
** restrict s,
size_t
n,
mbstate_t * restrict
ps);
DESCRIPTION
The
mbsrtowcs() converts the multibyte character string
indirectly pointed to by
s to the corresponding
wide-character string, and stores it in the array pointed to by
pwcs. The conversion stops due to the following reasons:
- The conversion reaches a nul byte. In this case, the nul
byte is also converted.
- The mbsrtowcs() has already stored
n wide characters.
- The conversion encounters an invalid character.
Each character will be converted as if
mbrtowc(3) is continuously
called.
After conversion, if
pwcs is not a null pointer, the
pointer object pointed to by
s is a null pointer (if the
conversion is stopped due to reaching a nul byte) or the first byte of the
character just after the last character converted.
If
pwcs is not a null pointer and the conversion is
stopped due to reaching a nul byte, the
mbsrtowcs() places
the state object pointed to by
ps to an initial state
after the conversion has taken place.
The behaviour of
mbsrtowcs() is affected by the
LC_CTYPE
category of the current locale.
These are the special cases:
-
-
- s == NULL || *s == NULL
- Undefined (may cause the program to crash).
-
-
- pwcs == NULL
- The conversion has taken place, but the resulting
wide-character string was discarded. In this case, the pointer object
pointed to by s is not modified and
n is ignored.
-
-
- ps == NULL
- The mbsrtowcs() uses its own internal
state object to keep the conversion state, instead of
ps mentioned in this manual page.
Calling any other functions in Standard C Library (libc,
-lc) never changes the internal state of
mbsrtowcs(), which is initialized at startup time of the
program.
RETURN VALUES
mbsrtowcs() returns:
-
-
- 0 or positive
- The value returned is the number of elements stored in the
array pointed to by pwcs, except for a terminating
nul wide character (if any). If pwcs is not
NULL
and the value returned is equal to
n, the wide-character string pointed to by
pwcs is not nul-terminated. If
pwcs is a null pointer, the value returned is the
number of elements to contain the whole string converted, except for a
terminating nul wide character.
-
-
- (size_t)-1
- The array indirectly pointed to by s
contains a byte sequence forming invalid character. In this case,
mbsrtowcs() sets errno to indicate
the error.
ERRORS
mbsrtowcs() may cause an error in the following case:
-
-
- [
EILSEQ
]
- The pointer pointed to by s points to
an invalid or incomplete multibyte character.
-
-
- [
EINVAL
]
- ps points to an invalid or
uninitialized mbstate_t object.
SEE ALSO
mbrtowc(3),
mbstowcs(3),
setlocale(3)
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”).