X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/9385eb3d10ebe5eb398c52040ec3dbfba9b0cdcf..2be56ee90c5c5bee77895b8787a43e894249002b:/locale/FreeBSD/mbrlen.3 diff --git a/locale/FreeBSD/mbrlen.3 b/locale/FreeBSD/mbrlen.3 index a1898d5..ca7be65 100644 --- 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.