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
 .\" 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.
 .\"
 .\" 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
 .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
 .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
 .Sh DESCRIPTION
 The
 .Fn wcrtomb


@@ -44,10 +58,10 @@ wide character
 .Fa wc ,
 including any necessary shift sequences, to the
 character array
 .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
 .Dv MB_CUR_MAX

-bytes.
+bytes will be stored.

 .Pp
 If
 .Fa s
 .Pp
 If
 .Fa s


@@ -58,7 +72,7 @@ behaves as if
 .Fa s
 pointed to an internal buffer and
 .Fa wc
 .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
 .Pp
 The
 .Ft mbstate_t


@@ -70,7 +84,16 @@ If it is
 .Fn wcrtomb
 uses an internal, static
 .Vt mbstate_t
 .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
 .Sh RETURN VALUES
 The
 .Fn wcrtomb


@@ -87,19 +110,19 @@ The
 .Fn wcrtomb
 function will fail if:
 .Bl -tag -width Er
 .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 EILSEQ
 An invalid wide character code was specified.

+.It Bq Er EINVAL
+The conversion state is invalid.

 .El
 .Sh SEE ALSO
 .Xr mbrtowc 3 ,
 .El
 .Sh SEE ALSO
 .Xr mbrtowc 3 ,

+.Xr multibyte 3 ,

 .Xr setlocale 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 STANDARDS
 The
 .Fn wcrtomb
 function conforms to
 .St -isoC-99 .

-.Sh BUGS
-The current implementation does not support shift states.