Libc-1082.20.4.tar.gz

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

diff --git a/locale/FreeBSD/mbrlen.3 b/locale/FreeBSD/mbrlen.3
index a1898d5391e87de2ca1d6c674b8fa6261178f4ca..ca7be65345c594d9d4dab41eaffb415f9e4ab0a0 100644 (file)
--- a/locale/FreeBSD/mbrlen.3
+++ b/locale/FreeBSD/mbrlen.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,29 +22,43 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/lib/libc/locale/mbrlen.3,v 1.6 2002/11/29 17:35:09 ru Exp $
+.\" $FreeBSD: src/lib/libc/locale/mbrlen.3,v 1.8 2004/06/30 19:32:41 ru Exp $
 .\"
-.Dd November 11, 2002
+.Dd April 7, 2004
 .Dt MBRLEN 3
 .Os
 .Sh NAME
-.Nm mbrlen
+.Nm mbrlen ,
+.Nm mbrlen_l
 .Nd "get number of bytes in a character (restartable)"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In wchar.h
 .Ft size_t
-.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
+.Fo mbrlen
+.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 mbrlen_l
+.Fa "const char *restrict s"
+.Fa "size_t n"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn mbrlen
-function determines the number of bytes constituting the
-multibyte character sequence pointed to by
-.Fa s ,
-examining at most
+function inspects at most
 .Fa n
-bytes.
+bytes, pointed to by
+.Fa s ,
+to determine the number of bytes needed to complete the next
+multibyte character.
 .Pp
 The
 .Vt mbstate_t
@@ -56,13 +70,14 @@ If it is
 .Fn mbrlen
 uses an internal, static
 .Vt mbstate_t
-object.
+object, which is initialized to the initial conversion state
+at program startup.
 .Pp
 It is equivalent to:
 .Pp
 .Dl "mbrtowc(NULL, s, n, ps);"
 .Pp
-Except that when
+Except that, when
 .Fa ps
 is a
 .Dv NULL
@@ -71,39 +86,47 @@ pointer,
 uses its own static, internal
 .Vt mbstate_t
 object to keep track of the shift state.
+.Pp
+Although the
+.Fn mbrlen
+function uses the current locale, the
+.Fn mbrlen_l
+function may be passed a locale directly. See
+.Xr xlocale 3
+for more information.
 .Sh RETURN VALUES
 The
 .Fn mbrlen
 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.
+.Fn mbrlen
+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 EXAMPLES
-A function which calculates the number of characters in a multibyte
+A function that calculates the number of characters in a multibyte
 character string:
 .Bd -literal -offset indent
 size_t
@@ -128,18 +151,18 @@ The
 .Fn mbrlen
 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 mblen 3 ,
-.Xr mbrtowc 3
+.Xr mbrtowc 3 ,
+.Xr multibyte 3 ,
+.Xr xlocale 3
 .Sh STANDARDS
 The
 .Fn mbrlen
 function conforms to
 .St -isoC-99 .
-.Sh BUGS
-The current implementation does not support shift states.