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

.\" Copyright (c) 2002 Tim J. Robbins
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" 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 $
.\"
.Dd November 11, 2002
.Dt MBRLEN 3
.Os
.Sh NAME
.Nm mbrlen
.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"
.Sh DESCRIPTION
The
.Fn mbrlen
function determines the number of bytes constituting the
multibyte character sequence pointed to by
.Fa s ,
examining at most
.Fa n
bytes.
.Pp
The
.Vt mbstate_t
argument,
.Fa ps ,
is used to keep track of the shift state.
If it is
.Dv NULL ,
.Fn mbrlen
uses an internal, static
.Vt mbstate_t
object.
.Pp
It is equivalent to:
.Pp
.Dl "mbrtowc(NULL, s, n, ps);"
.Pp
Except that when
.Fa ps
is a
.Dv NULL
pointer,
.Fn mbrlen
uses its own static, internal
.Vt mbstate_t
object to keep track of the shift state.
.Sh RETURN VALUES
The
.Fn mbrlen
functions returns:
.Bl -tag -width indent
.It 0
The first
.Fa n
or fewer bytes of
.Fa s
represent the null wide character
.Pq Li "L'\e0'" .
.It >0
The first
.Fa n
or fewer bytes of
.Fa s
represent a valid character,
.Fn mbrtowc
returns the length (in bytes) of the multibyte sequence.
.It Po Vt size_t Pc Ns \-2
The first
.Fa n
bytes of
.Fa s
are an incomplete multibyte sequence.
.It Po Vt size_t Pc Ns \-1
The byte sequence pointed to by
.Fa s
is an invalid multibyte sequence.
.El
.Sh EXAMPLES
A function which calculates the number of characters in a multibyte
character string:
.Bd -literal -offset indent
size_t
nchars(const char *s)
{
	size_t charlen, chars;
	mbstate_t mbs;

	chars = 0;
	memset(&mbs, 0, sizeof(mbs));
	while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 &&
	    charlen != (size_t)-1 && charlen != (size_t)-2) {
		s += charlen;
		chars++;
	}

	return (chars);
}
.Ed
.Sh ERRORS
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.
.El
.Sh SEE ALSO
.Xr mblen 3 ,
.Xr mbrtowc 3
.Sh STANDARDS
The
.Fn mbrlen
function conforms to
.St -isoC-99 .
.Sh BUGS
The current implementation does not support shift states.
Commit	Line	Data
9385eb3d A	1	.\" Copyright (c) 2002 Tim J. Robbins
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/lib/libc/locale/mbrlen.3,v 1.6 2002/11/29 17:35:09 ru Exp $
	26	.\"
	27	.Dd November 11, 2002
	28	.Dt MBRLEN 3
	29	.Os
	30	.Sh NAME
	31	.Nm mbrlen
	32	.Nd "get number of bytes in a character (restartable)"
	33	.Sh LIBRARY
	34	.Lb libc
	35	.Sh SYNOPSIS
	36	.In wchar.h
	37	.Ft size_t
	38	.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
	39	.Sh DESCRIPTION
	40	The
	41	.Fn mbrlen
	42	function determines the number of bytes constituting the
	43	multibyte character sequence pointed to by
	44	.Fa s ,
	45	examining at most
	46	.Fa n
	47	bytes.
	48	.Pp
	49	The
	50	.Vt mbstate_t
	51	argument,
	52	.Fa ps ,
	53	is used to keep track of the shift state.
	54	If it is
	55	.Dv NULL ,
	56	.Fn mbrlen
	57	uses an internal, static
	58	.Vt mbstate_t
	59	object.
	60	.Pp
	61	It is equivalent to:
	62	.Pp
	63	.Dl "mbrtowc(NULL, s, n, ps);"
	64	.Pp
65	Except that when
66	.Fa ps
67	is a
68	.Dv NULL
69	pointer,
70	.Fn mbrlen
71	uses its own static, internal
72	.Vt mbstate_t
73	object to keep track of the shift state.
74	.Sh RETURN VALUES
75	The
76	.Fn mbrlen
77	functions returns:
78	.Bl -tag -width indent
79	.It 0
80	The first
81	.Fa n
82	or fewer bytes of
83	.Fa s
84	represent the null wide character
85	.Pq Li "L'\e0'" .
86	.It >0
87	The first
88	.Fa n
89	or fewer bytes of
90	.Fa s
91	represent a valid character,
92	.Fn mbrtowc
93	returns the length (in bytes) of the multibyte sequence.
94	.It Po Vt size_t Pc Ns \-2
95	The first
96	.Fa n
97	bytes of
98	.Fa s
99	are an incomplete multibyte sequence.
100	.It Po Vt size_t Pc Ns \-1
101	The byte sequence pointed to by
102	.Fa s
103	is an invalid multibyte sequence.
104	.El
105	.Sh EXAMPLES
106	A function which calculates the number of characters in a multibyte
107	character string:
108	.Bd -literal -offset indent
109	size_t
110	nchars(const char *s)
111	{
112	size_t charlen, chars;
113	mbstate_t mbs;
114
115	chars = 0;
116	memset(&mbs, 0, sizeof(mbs));
117	while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 &&
118	charlen != (size_t)-1 && charlen != (size_t)-2) {
119	s += charlen;
120	chars++;
121	}
122
123	return (chars);
124	}
125	.Ed
126	.Sh ERRORS
127	The
128	.Fn mbrlen
129	function will fail if:
130	.Bl -tag -width Er
131	.\".It Bq Er EINVAL
132	.\"Invalid argument.
133	.It Bq Er EILSEQ
134	An invalid multibyte sequence was detected.
135	.El
136	.Sh SEE ALSO
137	.Xr mblen 3 ,
138	.Xr mbrtowc 3
139	.Sh STANDARDS
140	The
141	.Fn mbrlen
142	function conforms to
143	.St -isoC-99 .
144	.Sh BUGS
145	The current implementation does not support shift states.