Libc-1082.20.4.tar.gz

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

diff --git a/locale/FreeBSD/mbrtowc.3 b/locale/FreeBSD/mbrtowc.3
index adbc66a920e9eeaa1b2f58c42102477110bc76aa..406618419a07541e6e78d5908bbd902881d9d807 100644 (file)
--- a/locale/FreeBSD/mbrtowc.3
+++ b/locale/FreeBSD/mbrtowc.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,13 +22,14 @@
 .\" 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/mbrtowc.3,v 1.3 2002/11/29 17:35:09 ru Exp $
+.\" $FreeBSD: src/lib/libc/locale/mbrtowc.3,v 1.5 2004/06/30 19:32:41 ru Exp $

 .\"
 .\"

-.Dd August 15, 2002
+.Dd April 8, 2004

 .Dt MBRTOWC 3
 .Os
 .Sh NAME
 .Dt MBRTOWC 3
 .Os
 .Sh NAME

-.Nm mbrtowc
+.Nm mbrtowc ,
+.Nm mbrtowc_l

 .Nd "convert a character to a wide-character code (restartable)"
 .Sh LIBRARY
 .Lb libc
 .Nd "convert a character to a wide-character code (restartable)"
 .Sh LIBRARY
 .Lb libc


@@ -36,26 +37,37 @@
 .In wchar.h
 .Ft size_t
 .Fo mbrtowc
 .In wchar.h
 .Ft size_t
 .Fo mbrtowc

-.Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
-.Fa "mbstate_t * restrict ps"
+.Fa "wchar_t *restrict pwc"
+.Fa "const char *restrict s"
+.Fa "size_t n"
+.Fa "mbstate_t *restrict ps"
+.Fc
+.In wchar.h
+.In xlocale.h
+.Ft size_t
+.Fo mbrtowc_l
+.Fa "wchar_t *restrict pwc"
+.Fa "const char *restrict s"
+.Fa "size_t n"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"

 .Fc
 .Sh DESCRIPTION
 The
 .Fn mbrtowc
 function inspects at most
 .Fa n
 .Fc
 .Sh DESCRIPTION
 The
 .Fn mbrtowc
 function inspects at most
 .Fa n

-bytes pointed to by
-.Fa s
-and interprets them as a multibyte character sequence
-according to the current setting of
-.Ev LC_CTYPE .
-If
+bytes, pointed to by
+.Fa s ,
+to determine the number of bytes needed to complete the next multibyte
+character.
+If a character can be completed, and

 .Fa pwc
 is not
 .Dv NULL ,
 .Fa pwc
 is not
 .Dv NULL ,

-the multibyte character which
+the wide character which is represented by

 .Fa s
 .Fa s

-represents is stored in the
+is stored in the

 .Vt wchar_t
 it points to.
 .Pp
 .Vt wchar_t
 it points to.
 .Pp


@@ -66,14 +78,14 @@ is
 .Fn mbrtowc
 behaves as if
 .Fa pwc
 .Fn mbrtowc
 behaves as if
 .Fa pwc

-was
+were

 .Dv NULL ,
 .Fa s
 .Dv NULL ,
 .Fa s

-was an empty string
-.Pq Qq
+were an empty string
+.Pq Qq ,

 and
 .Fa n
 and
 .Fa n

-was 1.
+were 1.

 .Pp
 The
 .Vt mbstate_t
 .Pp
 The
 .Vt mbstate_t


@@ -85,56 +97,65 @@ If it is
 .Fn mbrtowc
 uses an internal, static
 .Vt mbstate_t
 .Fn mbrtowc
 uses an internal, static
 .Vt mbstate_t

-object.
+object, which is initialized to the initial conversion state
+at program startup.
+.Pp
+While the
+.Fn mbrtowc
+function uses the current locale, the
+.Fn mbrtowc_l
+function may be passed a locale directly. See
+.Xr xlocale 3
+for more information.

 .Sh RETURN VALUES
 The
 .Fn mbrtowc
 functions returns:
 .Bl -tag -width indent
 .It 0
 .Sh RETURN VALUES
 The
 .Fn mbrtowc
 functions returns:
 .Bl -tag -width indent
 .It 0

-The first
+The next

 .Fa n
 .Fa n

-or fewer bytes of
-.Fa s
+or fewer bytes

 represent the null wide character
 .Pq Li "L'\e0'" .
 .It >0
 represent the null wide character
 .Pq Li "L'\e0'" .
 .It >0

-The first
+The next

 .Fa n
 .Fa n

-or fewer bytes of
-.Fa s
+or fewer bytes

 represent a valid character,
 .Fn mbrtowc
 represent a valid character,
 .Fn mbrtowc

-returns the length (in bytes) of the multibyte sequence.
+returns the number of bytes used to complete the multibyte character.

 .It Po Vt size_t Pc Ns \-2
 .It Po Vt size_t Pc Ns \-2

-The first
+The next

 .Fa n
 .Fa n

-bytes of
-.Fa s
-are an incomplete multibyte sequence.
+contribute to, but do not complete, a valid multibyte character sequence,
+and all
+.Fa n
+bytes have been processed.

 .It Po Vt size_t Pc Ns \-1
 .It Po Vt size_t Pc Ns \-1

-The byte sequence pointed to by
-.Fa s
-is an invalid multibyte sequence.
+An encoding error has occurred.
+The next
+.Fa n
+or fewer bytes do not contribute to a valid multibyte character.

 .El
 .Sh ERRORS
 The
 .Fn mbrtowc
 function will fail if:
 .Bl -tag -width Er
 .El
 .Sh ERRORS
 The
 .Fn mbrtowc
 function will fail if:
 .Bl -tag -width Er

-.\".It Bq Er EINVAL
-.\"Invalid argument.

 .It Bq Er EILSEQ
 An invalid multibyte sequence was detected.
 .It Bq Er EILSEQ
 An invalid multibyte sequence was detected.

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

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

+.Xr multibyte 3 ,

 .Xr setlocale 3 ,
 .Xr setlocale 3 ,

-.Xr wcrtomb 3
+.Xr wcrtomb 3 ,
+.Xr xlocale 3

 .Sh STANDARDS
 The
 .Fn mbrtowc
 function conforms to
 .St -isoC-99 .
 .Sh STANDARDS
 The
 .Fn mbrtowc
 function conforms to
 .St -isoC-99 .

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