mbtowc — convert a multibyte sequence to a wide character
#include <stdlib.h>
int
mbtowc( |
wchar_t * | pwc, |
const char * | s, | |
size_t | n) ; |
The main case for this function is when s
is not NULL and pwc
is not NULL. In this case,
the mbtowc
() function inspects
at most n
bytes of
the multibyte string starting at s
, extracts the next complete
multibyte character, converts it to a wide character and
stores it at *pwc
. It
updates an internal shift state only known to the mbtowc
function. If s
does
not point to a '\0' byte, it returns the number of bytes that
were consumed from s
,
otherwise it returns 0.
If the n
bytes
starting at s
do not
contain a complete multibyte character, or if they contain an
invalid multibyte sequence, mbtowc
() returns −1. This can happen
even if n
>=
MB_CUR_MAX
, if the multibyte
string contains redundant shift sequences.
A different case is when s
is not NULL but pwc
is NULL. In this case the
mbtowc
() function behaves as
above, except that it does not store the converted wide
character in memory.
A third case is when s
is NULL. In this case,
pwc
and n
are ignored. The mbtowc
() function resets the shift state,
only known to this function, to the initial state, and
returns non-zero if the encoding has nontrivial shift state,
or zero if the encoding is stateless.
If s
is not NULL,
the mbtowc
() function returns
the number of consumed bytes starting at s
, or 0 if s
points to a null byte, or
−1 upon failure.
If s
is NULL, the
mbtowc
() function returns
non-zero if the encoding has nontrivial shift state, or zero
if the encoding is stateless.
The behavior of mbtowc
()
depends on the LC_CTYPE
category of the current locale.
This function is not multithread safe. The function mbrtowc(3) provides a better interface to the same functionality.
This page is part of release 3.17 of the Linux man-pages
project. A
description of the project, and information about reporting
bugs, can be found at
http://www.kernel.org/doc/man-pages/.
Copyright (c) Bruno Haible <haibleclisp.cons.org> This is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. References consulted: GNU glibc-2 source code and manual Dinkumware C library reference http://www.dinkumware.com/ OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html ISO/IEC 9899:1999 |