mbrtowc
- convert a character to a wide-character code (restartable)
LIBRARY
Lb libc
SYNOPSIS
#include <wchar.h> size_t
Fo mbrtowc
Fa wchar_t * restrict pwc const char * restrict s size_t n
Fa mbstate_t * restrict ps
Fc
DESCRIPTION
The
mbrtowc ();
function inspects at most
Fa n
bytes pointed to by
Fa s
to determine the number of bytes needed to complete the next multibyte
character.
If a character can be completed, and
Fa pwc
is not
NULL
the wide character which is represented by
Fa s
is stored in the
Vt wchar_t
it points to.
If
Fa s
is
NULL
mbrtowc ();
behaves as if
Fa pwc
was
NULL
Fa s
was an empty string
(Qq and
)
Fa n
was 1.
The
Vt mbstate_t
argument,
Fa ps ,
is used to keep track of the shift state.
If it is
NULL
mbrtowc ();
uses an internal, static
Vt mbstate_t
object, which is initialized to the initial conversion state
at program startup.
RETURN VALUES
The
mbrtowc ();
functions returns:
0
The next
Fa n
or fewer bytes
represent the null wide character
(L'\0'
)
>0
The next
Fa n
or fewer bytes
represent a valid character,
mbrtowc ();
returns the number of bytes used to complete the multibyte character.
Po Vt size_t Pc -2
The next
Fa n
contribute to, but do not complete, a valid multibyte character sequence,
and all
Fa n
bytes have been processed.
Po Vt size_t Pc -1
An encoding error has occurred.
The next
Fa n
or fewer bytes do not contribute to a valid multibyte character.
