'\"macro stdmacro
.if n .pH g3c.mbchar @(#)mbchar	40.16 of 10/27/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} mbchar 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} mbchar 3C "C Programming Language Utilities"
.if \nX=2 .ds x} mbchar 3C "" "\&"
.if \nX=3 .ds x} mbchar "" "" "\&"
.TH \*(x}
.SH NAME
\f4mbchar\f1: \f4mbtowc\f1, \f4mblen\f1, \f4wctomb\f1 \- multibyte character handling
.SH SYNOPSIS
\f4#include <stdlib.h>\f1
.PP
\f4int mbtowc (wchar_t \(**pwc, const char \(**s, size_t n);\f1
.PP
\f4int mblen (const char \(**s, size_t n);\f1
.PP
\f4int wctomb (char \(**s, wchar_t wchar);\f1
.SH DESCRIPTION
.PP
Multibyte characters are used to represent characters in an extended
character set.  This is needed for locales where 8 bits are not enough
to represent all the characters in the character set.
.PP
The multibyte character handling functions provide the means of
translating multibyte characters into wide characters and back again.
Wide characters have type \f4wchar_t\f1 (defined in \f4stdlib.h\f1), 
which is an integral type whose range of values can represent
distinct codes for all members
of the largest extended character set specified among the supported
locales.
.PP
A maximum of 3 extended character sets are supported for each locale.
The number of bytes in an extended character set is defined by the
\f4LC_CTYPE\fP
category of the locale [see \f4setlocale\fP(3C)].
However, the maximum number of bytes in any multibyte character
will never be greater than
\f4MB_LEN_MAX\fP.
which is defined in \f4stdlib.h\f1.
The maximum number of bytes in a character in an extended character set in the
\f4current\f1 locale is given by the macro, 
\f4MB_CUR_MAX\fP,
also defined in \f4stdlib.h\f1.
.PP
\f4mbtowc\fP determines the number of bytes that comprise the multibyte
character pointed to by \f2s\f1. Also, if \f2pwc\f1 is not a
null pointer,
\f4mbtowc\fP converts the multibyte character to a wide character and places
the result in the object pointed to by \f2pwc\f1.  
(The value of the wide character corresponding to the
null character is zero.)
At most \f2n\f1
characters will be examined, starting at the character pointed to by \f2s\f1.
.PP
If \f2s\f1 is a
null pointer, \f4mbtowc\fP simply returns 0.
If \f2s\f1 is not a
null pointer, then,
if \f2s\f1 points to the
null character, 
\f4mbtowc\fP returns 0; 
if the next \f2n\fP or fewer bytes form a valid multibyte character,
\f4mbtowc\fP returns the number of bytes
that comprise the converted multibyte character;
otherwise, \f2s\f1 does not point to a valid multibyte character and
\f4mbtowc\fP returns \-1.
.PP
\f4mblen\fP determines the number of bytes comprising the multibyte
character pointed to by \f2s\f1.  It is equivalent to 
.PP
.RS
.ft CW
mbtowc ((wchar_t *)0, s, n);
.ft
.RE
.PP
\f4wctomb\fP determines the number of bytes needed to represent the
multibyte character corresponding to the code whose value is \f2wchar\f1,
and, if \f2s\f1 is not a
null pointer, stores the multibyte character
representation in the array pointed to by \f2s\f1.
At most
\f4MB_CUR_MAX\fP
characters are stored. 
.PP
If \f2s\f1 is a
null pointer, \f4wctomb\fP simply returns 0.
If \f2s\f1 is not a
null pointer,
\f4wctomb\fP returns \-1 if the value of \f2wchar\f1 does not correspond
to a valid multibyte character;
otherwise it returns the number of bytes that comprise
the multibyte character corresponding to the value of \f2wchar\f1.
.SH "SEE ALSO"
\f4mbstring\fP(3C), \f4setlocale\fP(3C), \f4environ\f1(5).
.br
\f4chrtbl\fP(1M) in the \f2System Administrator's Reference Manual\f1.
.\"	@(#)mbchar.3c	
.Ee
