Libc-1082.20.4.tar.gz

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

diff --git a/locale/FreeBSD/wcrtomb.3 b/locale/FreeBSD/wcrtomb.3
index 458a88111e78171e3953efc5980efc576436b1aa..2b320a2c13b6ba6e353c6de23dfc09b03ebc1b5d 100644 (file)
--- a/locale/FreeBSD/wcrtomb.3
+++ b/locale/FreeBSD/wcrtomb.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2002 Tim J. Robbins
+.\" Copyright (c) 2002-2004 Tim J. Robbins
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -22,20 +22,34 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/lib/libc/locale/wcrtomb.3,v 1.3 2002/11/29 17:35:09 ru Exp $
+.\" $FreeBSD: src/lib/libc/locale/wcrtomb.3,v 1.4 2004/04/08 09:59:02 tjr Exp $
 .\"
-.Dd August 15, 2002
+.Dd April 8, 2004
 .Dt WCRTOMB 3
 .Os
 .Sh NAME
-.Nm wcrtomb
+.Nm wcrtomb ,
+.Nm wcrtomb_l
 .Nd "convert a wide-character code to a character (restartable)"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In wchar.h
 .Ft size_t
-.Fn wcrtomb "char * restrict s" "wchar_t wc" "mbstate_t * restrict ps"
+.Fo wcrtomb
+.Fa "char *restrict s"
+.Fa "wchar_t wc"
+.Fa "mbstate_t *restrict ps"
+.Fc
+.In wchar.h
+.In xlocale.h
+.Ft size_t
+.Fo wcrtomb_l
+.Fa "char *restrict s"
+.Fa "wchar_t wc"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn wcrtomb
@@ -44,10 +58,10 @@ wide character
 .Fa wc ,
 including any necessary shift sequences, to the
 character array
-.Fa s ,
-storing a maximum of
+.Fa s .
+A maximum of
 .Dv MB_CUR_MAX
-bytes.
+bytes will be stored.
 .Pp
 If
 .Fa s
@@ -58,7 +72,7 @@ behaves as if
 .Fa s
 pointed to an internal buffer and
 .Fa wc
-was a null wide character (L'\e0').
+were a null wide character (L'\e0').
 .Pp
 The
 .Ft mbstate_t
@@ -70,7 +84,16 @@ If it is
 .Fn wcrtomb
 uses an internal, static
 .Vt mbstate_t
-object.
+object, which is initialized to the initial conversion state
+at program startup.
+.Pp
+While the
+.Fn wcrtomb
+function uses the current locale, the
+.Fn wcrtomb_l
+function may be passed a locale directly. See
+.Xr xlocale 3
+for more information.
 .Sh RETURN VALUES
 The
 .Fn wcrtomb
@@ -87,19 +110,19 @@ The
 .Fn wcrtomb
 function will fail if:
 .Bl -tag -width Er
-.\".It Bq Er EINVAL
-.\"Invalid argument.
 .It Bq Er EILSEQ
 An invalid wide character code was specified.
+.It Bq Er EINVAL
+The conversion state is invalid.
 .El
 .Sh SEE ALSO
 .Xr mbrtowc 3 ,
+.Xr multibyte 3 ,
 .Xr setlocale 3 ,
-.Xr wctomb 3
+.Xr wctomb 3 ,
+.Xr xlocale 3
 .Sh STANDARDS
 The
 .Fn wcrtomb
 function conforms to
 .St -isoC-99 .
-.Sh BUGS
-The current implementation does not support shift states.