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).

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.