diff options
author | tjr <tjr@FreeBSD.org> | 2003-12-07 06:33:52 +0000 |
---|---|---|
committer | tjr <tjr@FreeBSD.org> | 2003-12-07 06:33:52 +0000 |
commit | 11f17fd074db7b1d7f92fec4275c2105cb941f85 (patch) | |
tree | 3f57bcd320ea6ee2a5226f446ba0f3d0f8db1859 /lib/libc/locale/multibyte.3 | |
parent | 412df50614470cff988f5c9b1b900e43245b3bd1 (diff) | |
download | FreeBSD-src-11f17fd074db7b1d7f92fec4275c2105cb941f85.zip FreeBSD-src-11f17fd074db7b1d7f92fec4275c2105cb941f85.tar.gz |
Split multibyte(3) into separate manual pages for each function.
Instead of just deleting it, turn the original page into a general
overview of the multibyte character conversion functions, somewhat
similar to stdio(3).
Diffstat (limited to 'lib/libc/locale/multibyte.3')
-rw-r--r-- | lib/libc/locale/multibyte.3 | 178 |
1 files changed, 38 insertions, 140 deletions
diff --git a/lib/libc/locale/multibyte.3 b/lib/libc/locale/multibyte.3 index 19d71c5..c274db5 100644 --- a/lib/libc/locale/multibyte.3 +++ b/lib/libc/locale/multibyte.3 @@ -1,3 +1,4 @@ +.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -35,40 +36,26 @@ .\" @(#)multibyte.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd August 10, 2003 +.Dd December 7, 2003 .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 +.In limits.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 -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 .Va char Ns s . 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 @@ -102,24 +89,16 @@ but are lumped with a neighboring character. 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 +Some functions (e.g. .Fn mblen , .Fn mbtowc 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 wctomb ) +maintain static shift state internally, whereas +others store in an +.Vt mbstate_t +object passed by the caller. +Shift states are undefined after a call to .Fn setlocale with the .Dv LC_CTYPE @@ -136,102 +115,25 @@ and the character with value 0 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 "mblen get number of bytes in a character" +.It "mbrlen get number of bytes in a character (restartable)" +.It "mbrtowc convert a character to a wide-character code (restartable)" +.It "mbsrtowcs convert a character string to a wide-character string (restartable)" +.It "mbstowcs convert a character string to a wide-character string" +.It "mbtowc convert a character to a wide-character code" +.It "wcrtomb convert a wide-character code to a character (restartable)" +.It "wcstombs convert a wide-character string to a character string" +.It "wcsrtombs convert a wide-character string to a character string (restartable)" +.It "wctomb convert a wide-character code to a character" +.El .Sh SEE ALSO -.Xr btowc 3 , -.Xr mbrlen 3 , -.Xr mbrtowc 3 , -.Xr mbrune 3 , -.Xr mbsinit 3 , -.Xr mbsrtowcs 3 , -.Xr rune 3 , +.Xr mklocale 1 , +.Xr stdio 3 , .Xr setlocale 3 , -.Xr wcrtomb 3 , -.Xr wcsrtombs 3 , .Xr big5 5 , .Xr euc 5 , .Xr gb18030 5 , @@ -241,14 +143,10 @@ both functions return \-1. .Xr utf2 5 , .Xr utf8 5 .Sh STANDARDS -The -.Fn mblen , -.Fn mbstowcs , -.Fn mbtowc , -.Fn wcstombs +These functions conform to +.St -isoC and -.Fn wctomb -functions conform to -.St -isoC . +.St -isoC-99 +as documented in their individual manual pages. .Sh BUGS The current implementation does not support shift states. |