git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 2002-2004 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.8 2004/06/30 19:32:41 ru Exp $
	26	.\"
	27	.Dd April 7, 2004
	28	.Dt MBRLEN 3
	29	.Os
	30	.Sh NAME
	31	.Nm mbrlen ,
	32	.Nm mbrlen_l
	33	.Nd "get number of bytes in a character (restartable)"
	34	.Sh LIBRARY
	35	.Lb libc
	36	.Sh SYNOPSIS
	37	.In wchar.h
	38	.Ft size_t
	39	.Fo mbrlen
	40	.Fa "const char *restrict s"
	41	.Fa "size_t n"
	42	.Fa "mbstate_t *restrict ps"
	43	.Fc
	44	.In wchar.h
	45	.In xlocale.h
	46	.Ft size_t
	47	.Fo mbrlen_l
	48	.Fa "const char *restrict s"
	49	.Fa "size_t n"
	50	.Fa "mbstate_t *restrict ps"
	51	.Fa "locale_t loc"
	52	.Fc
	53	.Sh DESCRIPTION
	54	The
	55	.Fn mbrlen
	56	function inspects at most
	57	.Fa n
	58	bytes, pointed to by
	59	.Fa s ,
	60	to determine the number of bytes needed to complete the next
	61	multibyte character.
	62	.Pp
	63	The
	64	.Vt mbstate_t
	65	argument,
	66	.Fa ps ,
	67	is used to keep track of the shift state.
	68	If it is
	69	.Dv NULL ,
	70	.Fn mbrlen
	71	uses an internal, static
	72	.Vt mbstate_t
	73	object, which is initialized to the initial conversion state
	74	at program startup.
	75	.Pp
	76	It is equivalent to:
	77	.Pp
	78	.Dl "mbrtowc(NULL, s, n, ps);"
	79	.Pp
	80	Except that, when
	81	.Fa ps
	82	is a
	83	.Dv NULL
	84	pointer,
	85	.Fn mbrlen
	86	uses its own static, internal
	87	.Vt mbstate_t
	88	object to keep track of the shift state.
	89	.Pp
	90	Although the
	91	.Fn mbrlen
	92	function uses the current locale, the
	93	.Fn mbrlen_l
	94	function may be passed a locale directly. See
	95	.Xr xlocale 3
	96	for more information.
	97	.Sh RETURN VALUES
	98	The
	99	.Fn mbrlen
	100	functions returns:
	101	.Bl -tag -width indent
	102	.It 0
	103	The next
	104	.Fa n
	105	or fewer bytes
	106	represent the null wide character
	107	.Pq Li "L'\e0'" .
	108	.It >0
	109	The next
	110	.Fa n
	111	or fewer bytes
	112	represent a valid character,
	113	.Fn mbrlen
	114	returns the number of bytes used to complete the multibyte character.
	115	.It Po Vt size_t Pc Ns \-2
	116	The next
	117	.Fa n
	118	contribute to, but do not complete, a valid multibyte character sequence,
	119	and all
	120	.Fa n
	121	bytes have been processed.
	122	.It Po Vt size_t Pc Ns \-1
	123	An encoding error has occurred.
	124	The next
	125	.Fa n
	126	or fewer bytes do not contribute to a valid multibyte character.
	127	.El
	128	.Sh EXAMPLES
	129	A function that calculates the number of characters in a multibyte
	130	character string:
	131	.Bd -literal -offset indent
	132	size_t
	133	nchars(const char *s)
	134	{
	135	size_t charlen, chars;
	136	mbstate_t mbs;
	137
	138	chars = 0;
	139	memset(&mbs, 0, sizeof(mbs));
	140	while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 &&
	141	charlen != (size_t)-1 && charlen != (size_t)-2) {
	142	s += charlen;
	143	chars++;
	144	}
	145
	146	return (chars);
	147	}
	148	.Ed
	149	.Sh ERRORS
	150	The
	151	.Fn mbrlen
	152	function will fail if:
	153	.Bl -tag -width Er
	154	.It Bq Er EILSEQ
	155	An invalid multibyte sequence was detected.
	156	.It Bq Er EINVAL
	157	The conversion state is invalid.
	158	.El
	159	.Sh SEE ALSO
	160	.Xr mblen 3 ,
	161	.Xr mbrtowc 3 ,
	162	.Xr multibyte 3 ,
	163	.Xr xlocale 3
	164	.Sh STANDARDS
	165	The
	166	.Fn mbrlen
	167	function conforms to
	168	.St -isoC-99 .