mbrtowc()

QNX SDP8.0C Library ReferenceAPIDeveloper

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 pointNo
Signal handlerYes
ThreadRead the Caveats

Caveats:

This function is safe to call in a multithreaded program if the ps argument isn't NULL.

Page updated: