shithub: scc

ref: d98e084e77dc2794355477421e8e6386236285bc
dir: /doc/man3/mbtowc.3/

View raw version
.TH MBTOWC 3
.SH NAME
mbtowc - converts from multibyte encoding to wchar_t
.SH SYNOPSIS
#include <stdlib.h>

int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n)
.SH DESCRIPTION
if
.I s
is not a null pointer,
the
.BR mbtowc ()
function inspects at most
.I n
bytes beginning with the byte pointed to by
.I s
to determine the number of bytes needed
to complete the next multibyte character
(including any shift sequences).
If the function determines
that the next multibyte character is complete and valid,
it determines the value of the corresponding wide character
and then,
if
.I pwc
is not a null pointer,
stores that value in the object pointed to by
.IR pwc .
If the corresponding wide character is the null wide character,
the function is left in the initial conversion state.
.SH RETURN VALUE
If
.I s
is a null pointer,
the
.BR  mbtowc ()
function returns a nonzero or zero value,
if multibyte character encodings,
respectively,
do or do not have state-dependent encodings.
If
.I s
is not a null pointer,
the
.BR mbtowc ()
function either returns 0
(if
.I s
points to the null character),
or returns the number of bytes
that are contained in the converted multibyte character
(if the next
.I n
or fewer bytes form a valid multibyte character),
or returns -1
(if they do not form a valid multibyte character).
.PP
In no case will the value returned be
greater than
.I n
or the value of the
.I MB_CUR_MAX
macro.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.20.7.2 Paragraph 1,2,3,4,5
.SH SEE ALSO
.BR stdlib.h (3)
.BR wchar.h (3)