diff --git a/lib/libc/locale/mblen.3 b/lib/libc/locale/mblen.3 index e23dd356abf4..39ff6a6c3bd6 100644 --- a/lib/libc/locale/mblen.3 +++ b/lib/libc/locale/mblen.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -37,7 +37,7 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD$ .\" -.Dd November 19, 2003 +.Dd April 7, 2004 .Dt MBLEN 3 .Os .Sh NAME @@ -54,7 +54,8 @@ The .Fn mblen function computes the length in bytes of a multibyte character -.Fa mbchar . +.Fa mbchar +according to the current conversion state. Up to .Fa nbytes bytes are examined. @@ -73,31 +74,34 @@ the .Fn mblen function returns nonzero if shift states are supported, zero otherwise. -If +.Pp +Otherwise, if .Fa mbchar -is valid, +is not a null pointer, .Fn mblen returns the number of bytes processed in .Fa mbchar , or \-1 if no multibyte character could be recognized or converted. +In this case, +.Fn mblen Ns No 's +internal conversion state is undefined. .Sh ERRORS The .Fn mblen 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 internal conversion state is not valid. .El .Sh SEE ALSO .Xr mbrlen 3 , -.Xr mbtowc 3 +.Xr mbtowc 3 , +.Xr multibyte 3 .Sh STANDARDS The .Fn mblen function conforms to -.St -isoC . -.Sh BUGS -The current implementation does not support shift states. +.St -isoC-99 . diff --git a/lib/libc/locale/mbrlen.3 b/lib/libc/locale/mbrlen.3 index 51548a41dcd5..cbdd13e58b43 100644 --- a/lib/libc/locale/mbrlen.3 +++ b/lib/libc/locale/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 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 11, 2002 +.Dd April 7, 2004 .Dt MBRLEN 3 .Os .Sh NAME @@ -39,12 +39,12 @@ .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,7 +56,8 @@ 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 @@ -77,33 +78,33 @@ The 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 fn +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 +129,17 @@ 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 .Sh STANDARDS The .Fn mbrlen function conforms to .St -isoC-99 . -.Sh BUGS -The current implementation does not support shift states. diff --git a/lib/libc/locale/mbrtowc.3 b/lib/libc/locale/mbrtowc.3 index b986db2f3361..d0a13cbca407 100644 --- a/lib/libc/locale/mbrtowc.3 +++ b/lib/libc/locale/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 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.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 fn +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. diff --git a/lib/libc/locale/mbsinit.3 b/lib/libc/locale/mbsinit.3 index 37c01cf25a56..afc2500c3a77 100644 --- a/lib/libc/locale/mbsinit.3 +++ b/lib/libc/locale/mbsinit.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 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 16, 2002 +.Dd April 8, 2004 .Dt MBSINIT 3 .Os .Sh NAME @@ -53,12 +53,15 @@ is .Dv NULL or describes an initial conversion state, otherwise it returns zero. +.Sh SEE ALSO +.Xr mbrlen 3 , +.Xr mbrtowc 3 , +.Xr mbsrtowcs 3 , +.Xr multibyte 3 , +.Xr wcrtomb 3 , +.Xr wcsrtombs 3 .Sh STANDARDS The .Fn mbsinit function conforms to .St -isoC-99 . -.Sh BUGS -The current implementation does not support shift states; -.Fn mbsinit -always returns non-zero. diff --git a/lib/libc/locale/mbsrtowcs.3 b/lib/libc/locale/mbsrtowcs.3 index c45a4f32ebd6..9963d8552088 100644 --- a/lib/libc/locale/mbsrtowcs.3 +++ b/lib/libc/locale/mbsrtowcs.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 @@ -23,7 +23,7 @@ .\" SUCH DAMAGE. .\" .\" $FreeBSD$ -.Dd August 16, 2002 +.Dd April 8, 2004 .Dt MBSRTOWCS 3 .Os .Sh NAME @@ -80,7 +80,8 @@ If it is .Fn mbsrtowcs 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 mbsrtowcs @@ -96,15 +97,16 @@ function will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid multibyte character sequence was encountered. +.It Bq Er EINVAL +The conversion state is invalid. .El .Sh SEE ALSO .Xr mbrtowc 3 , .Xr mbstowcs 3 , +.Xr multibyte 3 , .Xr wcsrtombs 3 .Sh STANDARDS The .Fn mbsrtowcs function conforms to .St -isoC-99 . -.Sh BUGS -The current implementation does not support shift states. diff --git a/lib/libc/locale/mbstowcs.3 b/lib/libc/locale/mbstowcs.3 index 3feb499a58ed..f0e3a9f5c986 100644 --- a/lib/libc/locale/mbstowcs.3 +++ b/lib/libc/locale/mbstowcs.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -37,7 +37,7 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD$ .\" -.Dd November 19, 2003 +.Dd April 8, 2004 .Dt MBSTOWCS 3 .Os .Sh NAME @@ -54,6 +54,7 @@ The .Fn mbstowcs function converts a multibyte character string .Fa mbstring +beginning in the initial conversion state into a wide character string .Fa wcstring . No more than @@ -71,18 +72,17 @@ The .Fn mbstowcs 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 mbsrtowcs 3 +.Xr mbsrtowcs 3 , +.Xr multibyte 3 .Sh STANDARDS The .Fn mbstowcs function conforms to -.St -isoC . -.Sh BUGS -The current implementation does not support shift states. +.St -isoC-99 . diff --git a/lib/libc/locale/mbtowc.3 b/lib/libc/locale/mbtowc.3 index 81f0377d174e..fbc0ceb24f93 100644 --- a/lib/libc/locale/mbtowc.3 +++ b/lib/libc/locale/mbtowc.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -37,7 +37,7 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD$ .\" -.Dd November 19, 2003 +.Dd April 7, 2004 .Dt MBTOWC 3 .Os .Sh NAME @@ -54,7 +54,8 @@ The .Fn mbtowc function converts a multibyte character .Fa mbchar -into a wide character and stores the result +into a wide character according to the current conversion state, +and stores the result in the object pointed to by .Fa wcharp . Up to @@ -63,7 +64,7 @@ bytes are examined. .Pp A call with a null .Fa mbchar -pointer returns nonzero if the current locale requires shift states, +pointer returns nonzero if the current encoding requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state. .Sh RETURN VALUES @@ -75,35 +76,38 @@ the .Fn mbtowc function returns nonzero if shift states are supported, zero otherwise. -If +.Pp +Otherwise, if .Fa mbchar -is valid, +is not a null pointer, .Fn mbtowc returns the number of bytes processed in .Fa mbchar , or \-1 if no multibyte character could be recognized or converted. +In this case, +.Fn mbtowc Ns No 's +internal conversion state is undefined. .Sh ERRORS The .Fn mbtowc 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 internal conversion state is invalid. .El .Sh SEE ALSO .Xr btowc 3 , .Xr mblen 3 , .Xr mbrtowc 3 , .Xr mbstowcs 3 , +.Xr multibyte 3 , .Xr wctomb 3 .Sh STANDARDS The .Fn mbtowc function conforms to -.St -isoC . -.Sh BUGS -The current implementation does not support shift states. +.St -isoC-99 . diff --git a/lib/libc/locale/multibyte.3 b/lib/libc/locale/multibyte.3 index c274db5f8200..db003c51e083 100644 --- a/lib/libc/locale/multibyte.3 +++ b/lib/libc/locale/multibyte.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -36,7 +36,7 @@ .\" @(#)multibyte.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd December 7, 2003 +.Dd April 8, 2004 .Dt MULTIBYTE 3 .Os .Sh NAME @@ -118,7 +118,7 @@ Null bytes are not permitted within multibyte characters. The C library provides the following functions for dealing with multibyte characters: .Bl -column "Description" -.It Sy "Function Description" +.It Sy "Function Description" .It "mblen get number of bytes in a character" .It "mbrlen get number of bytes in a character (restartable)" .It "mbrtowc convert a character to a wide-character code (restartable)" @@ -144,9 +144,4 @@ multibyte characters: .Xr utf8 5 .Sh STANDARDS These functions conform to -.St -isoC -and -.St -isoC-99 -as documented in their individual manual pages. -.Sh BUGS -The current implementation does not support shift states. +.St -isoC-99 . diff --git a/lib/libc/locale/wcrtomb.3 b/lib/libc/locale/wcrtomb.3 index a2da1c292ed3..c89614e2d34b 100644 --- a/lib/libc/locale/wcrtomb.3 +++ b/lib/libc/locale/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 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 15, 2002 +.Dd April 8, 2004 .Dt WCRTOMB 3 .Os .Sh NAME @@ -70,7 +70,8 @@ If it is .Fn wcrtomb 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 wcrtomb @@ -87,13 +88,14 @@ The .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 EINVAL +The conversion state is invalid. .El .Sh SEE ALSO .Xr mbrtowc 3 , +.Xr multibyte 3 , .Xr setlocale 3 , .Xr wctomb 3 .Sh STANDARDS @@ -101,5 +103,3 @@ The .Fn wcrtomb function conforms to .St -isoC-99 . -.Sh BUGS -The current implementation does not support shift states. diff --git a/lib/libc/locale/wcsrtombs.3 b/lib/libc/locale/wcsrtombs.3 index 155f78e385fc..91e61fde5086 100644 --- a/lib/libc/locale/wcsrtombs.3 +++ b/lib/libc/locale/wcsrtombs.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 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 16, 2002 +.Dd April 8, 2004 .Dt WCSRTOMBS 3 .Os .Sh NAME @@ -80,7 +80,8 @@ If it is .Fn wcsrtombs 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 wcsrtombs @@ -96,6 +97,8 @@ function will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid wide character was encountered. +.It Bq Er EINVAL +The conversion state is invalid. .El .Sh SEE ALSO .Xr mbsrtowcs 3 , @@ -106,5 +109,3 @@ The .Fn wcsrtombs function conforms to .St -isoC-99 . -.Sh BUGS -The current implementation does not support shift states. diff --git a/lib/libc/locale/wcstombs.3 b/lib/libc/locale/wcstombs.3 index 5fd198d9d75a..310ff95a23ef 100644 --- a/lib/libc/locale/wcstombs.3 +++ b/lib/libc/locale/wcstombs.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -37,7 +37,7 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD$ .\" -.Dd November 19, 2003 +.Dd April 8, 2004 .Dt WCSTOMBS 3 .Os .Sh NAME @@ -54,8 +54,9 @@ The .Fn wcstombs function converts a wide character string .Fa wcstring -into a multibyte character string -.Fa mbstring . +into a multibyte character string, +.Fa mbstring , +beginning in the initial conversion state. Up to .Fa nbytes bytes are stored in @@ -73,19 +74,18 @@ The .Fn wcstombs function will fail if: .Bl -tag -width Er -.\".It Bq Er EINVAL -.\"Invalid argument. .It Bq Er EILSEQ An invalid wide character was encountered. +.It Bq Er EINVAL +The conversion state is invalid. .El .Sh SEE ALSO .Xr mbstowcs 3 , +.Xr multibyte 3 , .Xr wcsrtombs 3 , .Xr wctomb 3 .Sh STANDARDS The .Fn wcstombs function conforms to -.St -isoC . -.Sh BUGS -The current implementation does not support shift states. +.St -isoC-99 . diff --git a/lib/libc/locale/wctomb.3 b/lib/libc/locale/wctomb.3 index f53f6c81b052..d1fb16542c3d 100644 --- a/lib/libc/locale/wctomb.3 +++ b/lib/libc/locale/wctomb.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved. +.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -37,7 +37,7 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD$ .\" -.Dd November 19, 2003 +.Dd April 8, 2004 .Dt WCTOMB 3 .Os .Sh NAME @@ -87,15 +87,18 @@ the number of bytes processed in .Fa mbchar , or \-1 if no multibyte character could be recognized or converted. +In this case, +.Fn wctomb Ns No 's +internal conversion state is undefined. .Sh ERRORS The .Fn wctomb 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 internal conversion state is invalid. .El .Sh SEE ALSO .Xr mbtowc 3 , @@ -106,6 +109,4 @@ An invalid multibyte sequence was detected. The .Fn wctomb function conforms to -.St -isoC . -.Sh BUGS -The current implementation does not support shift states. +.St -isoC-99 .