Convert a multibyte character into a wide character (restartable)
Synopsis:
#include <wchar.h>
size_t mbrtowc( wchar_t * pwc,
const char * s,
size_t n,
mbstate_t * ps );
Arguments:
- pwc
- A pointer to a wchar_t object where the function can
store the wide character.
- s
- A pointer to the multibyte character that you want to convert.
- n
- The maximum number of bytes in the multibyte character to convert.
- ps
- An internal pointer that lets mbrtowc() be a restartable version of
mbtowc();
if ps is NULL, mbrtowc() uses its
own internal variable.
You can call
mbsinit()
to determine the status of this variable.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The mbrtowc() function converts single multibyte characters pointed to by s into wide characters pointed to by pwc, to a maximum of n bytes (not characters).
This function is affected by LC_CTYPE.
Returns:
- (size_t)-2
- After converting all n characters, the resulting conversion state indicates an
incomplete multibyte character.
- (size_t)-1
- The function detected an encoding error before completing the next multibyte character; the function sets
errno
to EILSEQ and leaves the resulting conversion state undefined.
- 0
- The next completed character is a null character; the resulting conversion state is the same
as the initial one.
- x
- The number of bytes needed to complete the next multibyte character, in which case the
resulting conversion state indicates that x bytes have been converted.
Errors:
- EILSEQ
- Invalid character sequence.
- EINVAL
- The ps argument points to an invalid object.
Classification:
ANSI,
POSIX 1003.1
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Read the Caveats |
Caveats:
This function is safe to call in a multithreaded program if the ps
argument isn't NULL.