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/mbsrtowcs.3,v 1.6 2005/01/11 20:50:49 ru Exp $
	26	.Dd July 21, 2004
	27	.Dt MBSRTOWCS 3
	28	.Os
	29	.Sh NAME
	30	.Nm mbsnrtowcs ,
	31	.Nm mbsnrtowcs_l ,
	32	.Nm mbsrtowcs ,
	33	.Nm mbsrtowcs_l
	34	.Nd "convert a character string to a wide-character string (restartable)"
	35	.Sh LIBRARY
	36	.Lb libc
	37	.Sh SYNOPSIS
	38	.In wchar.h
	39	.Ft size_t
	40	.Fo mbsnrtowcs
	41	.Fa "wchar_t *restrict dst"
	42	.Fa "const char **restrict src"
	43	.Fa "size_t nms"
	44	.Fa "size_t len"
	45	.Fa "mbstate_t *restrict ps"
	46	.Fc
	47	.Ft size_t
	48	.Fo mbsrtowcs
	49	.Fa "wchar_t *restrict dst"
	50	.Fa "const char **restrict src"
	51	.Fa "size_t len"
	52	.Fa "mbstate_t *restrict ps"
	53	.Fc
	54	.In wchar.h
	55	.In xlocale.h
	56	.Ft size_t
	57	.Fo mbsrtowcs_l
	58	.Fa "wchar_t *restrict dst"
	59	.Fa "const char **restrict src"
	60	.Fa "size_t len"
	61	.Fa "mbstate_t *restrict ps"
	62	.Fa "locale_t loc"
	63	.Fc
	64	.Ft size_t
	65	.Fo mbsnrtowcs_l
	66	.Fa "wchar_t *restrict dst"
	67	.Fa "const char **restrict src"
	68	.Fa "size_t nms"
	69	.Fa "size_t len"
	70	.Fa "mbstate_t *restrict ps"
	71	.Fa "locale_t loc"
	72	.Fc
	73	.Sh DESCRIPTION
	74	The
	75	.Fn mbsrtowcs
	76	function converts a sequence of multibyte characters, pointed to indirectly by
	77	.Fa src ,
	78	into a sequence of corresponding wide characters. It stores at most
	79	.Fa len
	80	of them in the
	81	.Vt wchar_t
	82	array pointed to by
	83	.Fa dst ,
	84	until it encounters a terminating null character
	85	.Pq Li '\e0' .
	86	.Pp
	87	If
	88	.Fa dst
	89	is
	90	.Dv NULL ,
	91	no characters are stored.
	92	.Pp
	93	If
	94	.Fa dst
	95	is not
	96	.Dv NULL ,
	97	the pointer pointed to by
	98	.Fa src
	99	is updated to point to the character after the one that conversion stopped at.
	100	If conversion stops because a null character is encountered,
	101	.Fa *src
	102	is set to
	103	.Dv NULL .
	104	.Pp
	105	The
	106	.Vt mbstate_t
	107	argument,
	108	.Fa ps ,
	109	is used to keep track of the shift state.
	110	If it is
	111	.Dv NULL ,
	112	.Fn mbsrtowcs
	113	uses an internal, static
	114	.Vt mbstate_t
	115	object, which is initialized to the initial conversion state
	116	at program startup.
	117	.Pp
	118	The
	119	.Fn mbsnrtowcs
	120	function behaves identically to
	121	.Fn mbsrtowcs ,
	122	except that conversion stops after reading at most
	123	.Fa nms
	124	bytes from the buffer pointed to by
	125	.Fa src .
	126	.Pp
	127	While the
	128	.Fn mbsrtowcs
	129	and
	130	.Fn mbsnrtowcs
	131	functions use the current locale, the
	132	.Fn mbsrtowcs_l
	133	and
	134	.Fn mbsnrtowcs_l
	135	functions may be passed locales directly. See
	136	.Xr xlocale 3
	137	for more information.
	138	.Sh RETURN VALUES
	139	The
	140	.Fn mbsrtowcs
	141	and
	142	.Fn mbsnrtowcs
	143	functions return the number of wide characters stored in
	144	the array pointed to by
	145	.Fa dst
	146	if successful, otherwise it returns
	147	.Po Vt size_t Pc Ns \-1 .
	148	.Sh ERRORS
	149	The
	150	.Fn mbsrtowcs
	151	and
	152	.Fn mbsnrtowcs
	153	functions will fail if:
	154	.Bl -tag -width Er
	155	.It Bq Er EILSEQ
	156	An invalid multibyte character sequence was encountered.
	157	.It Bq Er EINVAL
	158	The conversion state is invalid.
	159	.El
	160	.Sh SEE ALSO
	161	.Xr mbrtowc 3 ,
	162	.Xr mbstowcs 3 ,
	163	.Xr multibyte 3 ,
	164	.Xr wcsrtombs 3 ,
	165	.Xr xlocale 3
	166	.Sh STANDARDS
	167	The
	168	.Fn mbsrtowcs
	169	function conforms to
	170	.St -isoC-99 .
	171	.Pp
	172	The
	173	.Fn mbsnrtowcs
	174	function is an extension to the standard.