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 | |
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')
-rw-r--r-- | lib/libc/locale/Makefile.inc | 9 | ||||
-rw-r--r-- | lib/libc/locale/mblen.3 | 103 | ||||
-rw-r--r-- | lib/libc/locale/mbstowcs.3 | 88 | ||||
-rw-r--r-- | lib/libc/locale/mbtowc.3 | 109 | ||||
-rw-r--r-- | lib/libc/locale/multibyte.3 | 178 | ||||
-rw-r--r-- | lib/libc/locale/wcstombs.3 | 90 | ||||
-rw-r--r-- | lib/libc/locale/wctomb.3 | 111 |
7 files changed, 543 insertions, 145 deletions
diff --git a/lib/libc/locale/Makefile.inc b/lib/libc/locale/Makefile.inc index d67a90b..b776e4e 100644 --- a/lib/libc/locale/Makefile.inc +++ b/lib/libc/locale/Makefile.inc @@ -22,15 +22,16 @@ SRCS+= big5.c btowc.c collate.c collcmp.c euc.c fix_grouping.c frune.c \ MAN+= btowc.3 \ ctype.3 digittoint.3 isalnum.3 isalpha.3 isascii.3 isblank.3 iscntrl.3 \ isdigit.3 isgraph.3 islower.3 isprint.3 ispunct.3 isspace.3 \ - isupper.3 iswalnum.3 isxdigit.3 localeconv.3 mbrlen.3 mbrtowc.3 \ + isupper.3 iswalnum.3 isxdigit.3 localeconv.3 mblen.3 mbrlen.3 \ + mbrtowc.3 \ mbrune.3 mbsinit.3 \ - mbsrtowcs.3 multibyte.3 \ + mbsrtowcs.3 mbstowcs.3 mbtowc.3 multibyte.3 \ nl_langinfo.3 \ rune.3 \ setlocale.3 toascii.3 tolower.3 toupper.3 towlower.3 towupper.3 \ wcsftime.3 \ wcrtomb.3 \ - wcsrtombs.3 wcstod.3 wcstol.3 \ + wcsrtombs.3 wcstod.3 wcstol.3 wcstombs.3 wctomb.3 \ wctrans.3 wctype.3 wcwidth.3 MAN+= big5.5 euc.5 gb18030.5 gb2312.5 gbk.5 mskanji.5 utf2.5 utf8.5 @@ -45,8 +46,6 @@ MLINKS+=iswalnum.3 iswalpha.3 iswalnum.3 iswascii.3 iswalnum.3 iswblank.3 \ iswalnum.3 iswupper.3 iswalnum.3 iswxdigit.3 MLINKS+=isxdigit.3 ishexnumber.3 MLINKS+=mbrune.3 mbmb.3 mbrune.3 mbrrune.3 -MLINKS+=multibyte.3 mblen.3 multibyte.3 mbstowcs.3 multibyte.3 mbtowc.3 \ - multibyte.3 wcstombs.3 multibyte.3 wctomb.3 MLINKS+=rune.3 fgetrune.3 rune.3 fputrune.3 rune.3 fungetrune.3 \ rune.3 setinvalidrune.3 rune.3 setrunelocale.3 rune.3 sgetrune.3 \ rune.3 sputrune.3 diff --git a/lib/libc/locale/mblen.3 b/lib/libc/locale/mblen.3 new file mode 100644 index 0000000..e23dd35 --- /dev/null +++ b/lib/libc/locale/mblen.3 @@ -0,0 +1,103 @@ +.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 +.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp +.\" $FreeBSD$ +.\" +.Dd November 19, 2003 +.Dt MBLEN 3 +.Os +.Sh NAME +.Nm mblen +.Nd get number of bytes in a character +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn mblen "const char *mbchar" "size_t nbytes" +.Sh DESCRIPTION +The +.Fn mblen +function computes the length in bytes +of a multibyte character +.Fa mbchar . +Up to +.Fa nbytes +bytes are examined. +.Pp +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. +.Sh RETURN VALUES +If +.Fa mbchar +is +.Dv NULL , +the +.Fn mblen +function returns nonzero if shift states are supported, +zero otherwise. +If +.Fa mbchar +is valid, +.Fn mblen +returns the number of bytes processed in +.Fa mbchar , +or \-1 if no multibyte character +could be recognized or converted. +.Sh ERRORS +The +.Fn mblen +function will fail if: +.Bl -tag -width Er +.\".It Bq Er EINVAL +.\"Invalid argument. +.It Bq Er EILSEQ +An invalid multibyte sequence was detected. +.El +.Sh SEE ALSO +.Xr mbrlen 3 , +.Xr mbtowc 3 +.Sh STANDARDS +The +.Fn mblen +function conforms to +.St -isoC . +.Sh BUGS +The current implementation does not support shift states. diff --git a/lib/libc/locale/mbstowcs.3 b/lib/libc/locale/mbstowcs.3 new file mode 100644 index 0000000..3feb499 --- /dev/null +++ b/lib/libc/locale/mbstowcs.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 +.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp +.\" $FreeBSD$ +.\" +.Dd November 19, 2003 +.Dt MBSTOWCS 3 +.Os +.Sh NAME +.Nm mbstowcs +.Nd convert a character string to a wide-character string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft size_t +.Fn mbstowcs "wchar_t * restrict wcstring" "const char * restrict mbstring" "size_t nwchars" +.Sh DESCRIPTION +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. +.Sh RETURN VALUES +The +.Fn mbstowcs +function returns the number of wide characters converted, +not counting any terminating null wide character, or \-1 +if an invalid multibyte character was encountered. +.Sh ERRORS +The +.Fn mbstowcs +function will fail if: +.Bl -tag -width Er +.\".It Bq Er EINVAL +.\"Invalid argument. +.It Bq Er EILSEQ +An invalid multibyte sequence was detected. +.El +.Sh SEE ALSO +.Xr mbtowc 3 , +.Xr mbsrtowcs 3 +.Sh STANDARDS +The +.Fn mbstowcs +function conforms to +.St -isoC . +.Sh BUGS +The current implementation does not support shift states. diff --git a/lib/libc/locale/mbtowc.3 b/lib/libc/locale/mbtowc.3 new file mode 100644 index 0000000..81f0377 --- /dev/null +++ b/lib/libc/locale/mbtowc.3 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 +.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp +.\" $FreeBSD$ +.\" +.Dd November 19, 2003 +.Dt MBTOWC 3 +.Os +.Sh NAME +.Nm mbtowc +.Nd convert a character to a wide-character code +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn mbtowc "wchar_t * restrict wcharp" "const char * restrict mbchar" "size_t nbytes" +.Sh DESCRIPTION +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 +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. +.Sh RETURN VALUES +If +.Fa mbchar +is +.Dv NULL , +the +.Fn mbtowc +function returns nonzero if shift states are supported, +zero otherwise. +If +.Fa mbchar +is valid, +.Fn mbtowc +returns +the number of bytes processed in +.Fa mbchar , +or \-1 if no multibyte character +could be recognized or converted. +.Sh ERRORS +The +.Fn mbtowc +function will fail if: +.Bl -tag -width Er +.\".It Bq Er EINVAL +.\"Invalid argument. +.It Bq Er EILSEQ +An invalid multibyte sequence was detected. +.El +.Sh SEE ALSO +.Xr btowc 3 , +.Xr mblen 3 , +.Xr mbrtowc 3 , +.Xr mbstowcs 3 , +.Xr wctomb 3 +.Sh STANDARDS +The +.Fn mbtowc +function conforms to +.St -isoC . +.Sh BUGS +The current implementation does not support shift states. 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. diff --git a/lib/libc/locale/wcstombs.3 b/lib/libc/locale/wcstombs.3 new file mode 100644 index 0000000..ba35247 --- /dev/null +++ b/lib/libc/locale/wcstombs.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 +.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp +.\" $FreeBSD$ +.\" +.Dd November 19, 2003 +.Dt WCSTOMBS 3 +.Os +.Sh NAME +.Nm wcstombs , +.Nd convert a wide-character string to a character string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft size_t +.Fn wcstombs "char * restrict mbstring" "const wchar_t * restrict wcstring" "size_t nbytes" +.Sh DESCRIPTION +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 +.Fn wcstombs +function returns the number of bytes converted, +not counting any terminating null byte, or \-1 +if an invalid multibyte character was encountered. +.Sh ERRORS +The +.Fn wcstombs +function will fail if: +.Bl -tag -width Er +.\".It Bq Er EINVAL +.\"Invalid argument. +.It Bq Er EILSEQ +An invalid multibyte sequence was detected. +.El +.Sh SEE ALSO +.Xr mbstowcs 3 , +.Xr wcsrtombs 3 , +.Xr wctomb 3 +.Sh STANDARDS +The +.Fn wcstombs +function conforms to +.St -isoC . +.Sh BUGS +The current implementation does not support shift states. diff --git a/lib/libc/locale/wctomb.3 b/lib/libc/locale/wctomb.3 new file mode 100644 index 0000000..f53f6c8 --- /dev/null +++ b/lib/libc/locale/wctomb.3 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 +.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp +.\" $FreeBSD$ +.\" +.Dd November 19, 2003 +.Dt WCTOMB 3 +.Os +.Sh NAME +.Nm wctomb +.Nd convert a wide-character code to a character +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn wctomb "char *mbchar" "wchar_t wchar" +.Sh DESCRIPTION +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, which +may be up to +.Dv MB_LEN_MAX +bytes. +.Pp +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. +.Sh RETURN VALUES +If +.Fa mbchar +is +.Dv NULL , +the +.Fn wctomb +function returns nonzero if shift states are supported, +zero otherwise. +If +.Fa mbchar +is valid, +.Fn wctomb +returns +the number of bytes processed in +.Fa mbchar , +or \-1 if no multibyte character +could be recognized or converted. +.Sh ERRORS +The +.Fn wctomb +function will fail if: +.Bl -tag -width Er +.\".It Bq Er EINVAL +.\"Invalid argument. +.It Bq Er EILSEQ +An invalid multibyte sequence was detected. +.El +.Sh SEE ALSO +.Xr mbtowc 3 , +.Xr wcrtomb 3 , +.Xr wcstombs 3 , +.Xr wctob 3 +.Sh STANDARDS +The +.Fn wctomb +function conforms to +.St -isoC . +.Sh BUGS +The current implementation does not support shift states. |