Libc-763.13.tar.gz

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

diff --git a/locale/FreeBSD/mbrtowc.3 b/locale/FreeBSD/mbrtowc.3
index adbc66a920e9eeaa1b2f58c42102477110bc76aa..ab7138eb5417303e840abd28771742f7d8b3cbfa 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
@@ -22,9 +22,9 @@
 .\" 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
@@ -46,16 +46,15 @@ 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
+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 ,
-the multibyte character which
+the wide character which is represented by
 .Fa s
-represents is stored in the
+is stored in the
 .Vt wchar_t
 it points to.
 .Pp
@@ -85,50 +84,52 @@ If it is
 .Fn mbrtowc
 uses an internal, static
 .Vt mbstate_t
-object.
+object, which is initialized to the initial conversion state
+at program startup.
 .Sh RETURN VALUES
 The
 .Fn mbrtowc
 functions returns:
 .Bl -tag -width indent
 .It 0
-The first
+The next
 .Fa n
-or fewer bytes of
-.Fa s
+or fewer bytes
 represent the null wide character
 .Pq Li "L'\e0'" .
 .It >0
-The first
+The next
 .Fa n
-or fewer bytes of
-.Fa s
+or fewer bytes
 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
-The first
+The next
 .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
-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
-.\".It Bq Er EINVAL
-.\"Invalid argument.
 .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 ,
+.Xr multibyte 3 ,
 .Xr setlocale 3 ,
 .Xr wcrtomb 3
 .Sh STANDARDS
@@ -136,5 +137,3 @@ The
 .Fn mbrtowc
 function conforms to
 .St -isoC-99 .
-.Sh BUGS
-The current implementation does not support shift states.