d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update manual pages for change to C99 mbrtowc() semantics.

Browse Source
This commit is contained in:
Tim J. Robbins 2004-04-08 09:59:02 +00:00
parent e8410540b7
commit 8b8109275c
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=128032
12 changed files with 143 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
lib/libc/locale/mblen.3
View File

@ -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 .

58
lib/libc/locale/mbrlen.3
View File

@ -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.

53
lib/libc/locale/mbrtowc.3
View File

@ -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.

15
lib/libc/locale/mbsinit.3
View File

@ -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.

12
lib/libc/locale/mbsrtowcs.3
View File

@ -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.

16
lib/libc/locale/mbstowcs.3
View File

@ -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 .

26
lib/libc/locale/mbtowc.3
View File

@ -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 .

13
lib/libc/locale/multibyte.3
View File

@ -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 .

14
lib/libc/locale/wcrtomb.3
View File

@ -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.

11
lib/libc/locale/wcsrtombs.3
View File

@ -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.

18
lib/libc/locale/wcstombs.3
View File

@ -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 .

15
lib/libc/locale/wctomb.3
View File

@ -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 .