Libc-1082.20.4.tar.gz

[apple/libc.git] / locale / FreeBSD / multibyte.3

diff --git a/locale/FreeBSD/multibyte.3 b/locale/FreeBSD/multibyte.3
index b2ba2cf4d10920d3a31db869cb38d62749d14993..de7099c05d3acf8eeda89dd6994bc78ff731a196 100644 (file)
--- a/locale/FreeBSD/multibyte.3
+++ b/locale/FreeBSD/multibyte.3
@@ -1,3 +1,4 @@
+.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved.

 .\" Copyright (c) 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Copyright (c) 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"


@@ -12,10 +13,6 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.

-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.

 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.


@@ -33,49 +30,35 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)multibyte.3 8.1 (Berkeley) 6/4/93
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)multibyte.3 8.1 (Berkeley) 6/4/93

-.\" $FreeBSD: src/lib/libc/locale/multibyte.3,v 1.19 2003/02/06 11:04:46 charnier Exp $
+.\" $FreeBSD: src/lib/libc/locale/multibyte.3,v 1.28 2007/01/09 00:28:00 imp Exp $

 .\"
 .\"

-.Dd October 6, 2002
+.Dd April 8, 2004

 .Dt MULTIBYTE 3
 .Os
 .Sh NAME
 .Dt MULTIBYTE 3
 .Os
 .Sh NAME

-.Nm mblen ,
-.Nm mbstowcs ,
-.Nm mbtowc ,
-.Nm wcstombs ,
-.Nm wctomb
-.Nd multibyte character support for C
+.Nm multibyte
+.Nd multibyte and wide character manipulation functions

 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS

+.In limits.h

 .In stdlib.h
 .In stdlib.h

-.Ft int
-.Fn mblen "const char *mbchar" "size_t nbytes"
-.Ft size_t
-.Fn mbstowcs "wchar_t * restrict wcstring" "const char * restrict mbstring" "size_t nwchars"
-.Ft int
-.Fn mbtowc "wchar_t * restrict wcharp" "const char * restrict mbchar" "size_t nbytes"
-.Ft size_t
-.Fn wcstombs "char * restrict mbstring" "const wchar_t * restrict wcstring" "size_t nbytes"
-.Ft int
-.Fn wctomb "char *mbchar" "wchar_t wchar"
+.In wchar.h

 .Sh DESCRIPTION
 .Sh DESCRIPTION

-The basic elements of some written natural languages such as Chinese
+The basic elements of some written natural languages, such as Chinese,

 cannot be represented uniquely with single C
 cannot be represented uniquely with single C

-.Va char Ns s .
+.Vt char Ns s .

 The C standard supports two different ways of dealing with
 The C standard supports two different ways of dealing with

-extended natural language encodings,
-.Em wide
-characters and
-.Em multibyte
-characters.
+extended natural language encodings:
+wide characters and
+multibyte characters.

 Wide characters are an internal representation
 which allows each basic element to map
 to a single object of type
 Wide characters are an internal representation
 which allows each basic element to map
 to a single object of type

-.Va wchar_t .
+.Vt wchar_t .

 Multibyte characters are used for input and output
 and code each basic element as a sequence of C
 Multibyte characters are used for input and output
 and code each basic element as a sequence of C

-.Va char Ns s .
+.Vt char Ns s .

 Individual basic elements may map into one or more
 (up to
 .Dv MB_LEN_MAX )
 Individual basic elements may map into one or more
 (up to
 .Dv MB_LEN_MAX )


@@ -88,7 +71,7 @@ The locale category
 .Dv LC_CTYPE
 specifically controls this interpretation.
 The
 .Dv LC_CTYPE
 specifically controls this interpretation.
 The

-.Va wchar_t
+.Vt wchar_t

 type is wide enough to hold the largest value
 in the wide character representations for all locales.
 .Pp
 type is wide enough to hold the largest value
 in the wide character representations for all locales.
 .Pp


@@ -102,25 +85,17 @@ but are lumped with a neighboring character.
 There is always a distinguished
 .Sq initial
 shift state.
 There is always a distinguished
 .Sq initial
 shift state.

-The
-.Fn mbstowcs
-and
-.Fn wcstombs
-functions assume that multibyte strings are interpreted
-starting from the initial shift state.
-The
-.Fn mblen ,
-.Fn mbtowc
+Some functions (e.g.,
+.Xr mblen 3 ,
+.Xr mbtowc 3

 and
 and

-.Fn wctomb
-functions maintain static shift state internally.
-A call with a null
-.Fa mbchar
-pointer returns nonzero if the current locale requires shift states,
-zero otherwise;
-if shift states are required, the shift state is reset to the initial state.
-The internal shift states are undefined after a call to
-.Fn setlocale
+.Xr wctomb 3 )
+maintain static shift state internally, whereas
+others store it in an
+.Vt mbstate_t
+object passed by the caller.
+Shift states are undefined after a call to
+.Xr setlocale 3

 with the
 .Dv LC_CTYPE
 or
 with the
 .Dv LC_CTYPE
 or


@@ -136,113 +111,32 @@ and the character with value 0
 is recognized as the multibyte character string terminator.
 Null bytes are not permitted within multibyte characters.
 .Pp
 is recognized as the multibyte character string terminator.
 Null bytes are not permitted within multibyte characters.
 .Pp

-The
-.Fn mblen
-function computes the length in bytes
-of a multibyte character
-.Fa mbchar .
-Up to
-.Fa nbytes
-bytes are examined.
-.Pp
-The
-.Fn mbtowc
-function converts a multibyte character
-.Fa mbchar
-into a wide character and stores the result
-in the object pointed to by
-.Fa wcharp .
-Up to
-.Fa nbytes
-bytes are examined.
-.Pp
-The
-.Fn wctomb
-function converts a wide character
-.Fa wchar
-into a multibyte character and stores
-the result in
-.Fa mbchar .
-The object pointed to by
-.Fa mbchar
-must be large enough to accommodate the multibyte character.
-.Pp
-The
-.Fn mbstowcs
-function converts a multibyte character string
-.Fa mbstring
-into a wide character string
-.Fa wcstring .
-No more than
-.Fa nwchars
-wide characters are stored.
-A terminating null wide character is appended if there is room.
-.Pp
-The
-.Fn wcstombs
-function converts a wide character string
-.Fa wcstring
-into a multibyte character string
-.Fa mbstring .
-Up to
-.Fa nbytes
-bytes are stored in
-.Fa mbstring .
-Partial multibyte characters at the end of the string are not stored.
-The multibyte character string is null terminated if there is room.
-.Sh "RETURN VALUES
-If
-.Fa mbchar
-is
-.Dv NULL ,
-the
-.Fn mblen ,
-.Fn mbtowc
-and
-.Fn wctomb
-functions return nonzero if shift states are supported,
-zero otherwise.
-If
-.Fa mbchar
-is valid,
-then these functions return
-the number of bytes processed in
-.Fa mbchar ,
-or \-1 if no multibyte character
-could be recognized or converted.
-.Pp
-The
-.Fn mbstowcs
-function returns the number of wide characters converted,
-not counting any terminating null wide character.
-The
-.Fn wcstombs
-function returns the number of bytes converted,
-not counting any terminating null byte.
-If any invalid multibyte characters are encountered,
-both functions return \-1.
+The C library provides the following functions for dealing with
+multibyte characters:
+.Bl -column "Description"
+.It Sy "Function       Description"
+.It Xr mblen 3 Ta "get number of bytes in a character"
+.It Xr mbrlen 3 Ta "get number of bytes in a character (restartable)"
+.It Xr mbrtowc 3 Ta "convert a character to a wide-character code (restartable)"
+.It Xr mbsrtowcs 3 Ta "convert a character string to a wide-character string (restartable)"
+.It Xr mbstowcs 3 Ta "convert a character string to a wide-character string"
+.It Xr mbtowc 3 Ta "convert a character to a wide-character code"
+.It Xr wcrtomb 3 Ta "convert a wide-character code to a character (restartable)"
+.It Xr wcstombs 3 Ta "convert a wide-character string to a character string"
+.It Xr wcsrtombs 3 Ta "convert a wide-character string to a character string (restartable)"
+.It Xr wctomb 3 Ta "convert a wide-character code to a character"
+.El

 .Sh SEE ALSO
 .Sh SEE ALSO

-.Xr btowc 3 ,
-.Xr mbrlen 3 ,
-.Xr mbrtowc 3 ,
-.Xr mbrune 3 ,
-.Xr mbsrtowcs 3 ,
-.Xr rune 3 ,
+.Xr mklocale 1 ,

 .Xr setlocale 3 ,
 .Xr setlocale 3 ,

-.Xr wcrtomb 3 ,
-.Xr wcsrtombs 3 ,
-.Xr euc 4 ,
-.Xr utf2 4 ,
+.Xr stdio 3 ,
+.Xr big5 5 ,
+.Xr euc 5 ,
+.Xr gb18030 5 ,
+.Xr gb2312 5 ,
+.Xr gbk 5 ,
+.Xr mskanji 5 ,

 .Xr utf8 5
 .Sh STANDARDS
 .Xr utf8 5
 .Sh STANDARDS

-The
-.Fn mblen ,
-.Fn mbstowcs ,
-.Fn mbtowc ,
-.Fn wcstombs
-and
-.Fn wctomb
-functions conform to
-.St -isoC .
-.Sh BUGS
-The current implementation does not support shift states.
+These functions conform to
+.St -isoC-99 .