mbtowc(3)
- NetBSD Manual Pages
MBTOWC(3) NetBSD Library Functions Manual MBTOWC(3)
NAME
mbtowc -- converts a multibyte character to a wide character
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
int
mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n);
DESCRIPTION
mbtowc() usually converts the multibyte character pointed to by s to a
wide character, and stores it in the wchar_t object pointed to by pwc if
pwc is non-NULL and s points to a valid character. This function may
inspect at most n bytes of the array beginning from s.
In state-dependent encodings, s may point to the special sequence bytes
to change the shift-state. Although such sequence bytes correspond to no
individual wide-character code, mbtowc() changes its own state by the
sequence bytes and treats them as if they are a part of the subsequence
multibyte character.
Unlike mbrtowc(3), the first n bytes pointed to by s need to form an
entire multibyte character. Otherwise, this function causes an error.
Calling any other functions in Standard C Library (libc, -lc) never
changes the internal state of mbtowc(), except for calling setlocale(3)
with changing the LC_CTYPE category of the current locale. Such
setlocale(3) call causes the internal state of this function to be inde-
terminate.
The behaviour of mbtowc() is affected by the LC_CTYPE category of the
current locale.
There are special cases:
s == NULL mbtowc() initializes its own internal state to an initial
state, and determines whether the current encoding is
state-dependent. This function returns 0 if the encoding
is state-independent, otherwise non-zero. In this case,
pwc is completely ignored.
pwc == NULL mbtowc() executes the conversion as if pwc is non-NULL, but
a result of the conversion is discarded.
n == 0 In this case, the first n bytes of the array pointed to by
s never form a complete character. Thus, the mbtowc()
always fails.
RETURN VALUES
Normally, the mbtowc() returns:
0 s points to a nul byte (`\0').
positive Number of bytes for the valid multibyte character pointed
to by s. There are no cases that the value returned is
greater than the value of the MB_CUR_MAX macro.
-1 s points to an invalid or an incomplete multibyte charac-
ter. The mbtowc() also sets errno to indicate the error.
When s is equal to NULL, mbtowc() returns:
0 The current encoding is state-independent.
non-zero The current encoding is state-dependent.
ERRORS
mbtowc() may cause an error in the following case:
[EILSEQ] s points to an invalid or incomplete multibyte charac-
ter.
SEE ALSO
mblen(3), mbrtowc(3), setlocale(3)
STANDARDS
The mbtowc() function conforms to ANSI X3.159-1989 (``ANSI C89''). The
restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'').
NetBSD 7.1.1 February 3, 2002 NetBSD 7.1.1
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.