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

... / ...

Commit	Line	Data
	1	.\" $NetBSD: stringlist.3,v 1.5 1999/03/22 19:44:46 garbled Exp $
	2	.\"
	3	.\" Copyright (c) 1997, 1999 The NetBSD Foundation, Inc.
	4	.\" All rights reserved.
	5	.\"
	6	.\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
	7	.\"
	8	.\" Redistribution and use in source and binary forms, with or without
	9	.\" modification, are permitted provided that the following conditions
	10	.\" are met:
	11	.\" 1. Redistributions of source code must retain the above copyright
	12	.\" notice, this list of conditions and the following disclaimer.
	13	.\" 2. Redistributions in binary form must reproduce the above copyright
	14	.\" notice, this list of conditions and the following disclaimer in the
	15	.\" documentation and/or other materials provided with the distribution.
	16	.\" 3. All advertising materials mentioning features or use of this software
	17	.\" must display the following acknowledgement:
	18	.\" This product includes software developed by the NetBSD
	19	.\" Foundation, Inc. and its contributors.
	20	.\" 4. Neither the name of The NetBSD Foundation nor the names of its
	21	.\" contributors may be used to endorse or promote products derived
	22	.\" from this software without specific prior written permission.
	23	.\"
	24	.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
	25	.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
	26	.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	27	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
	28	.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	29	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	30	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	31	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	32	.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	33	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	34	.\" POSSIBILITY OF SUCH DAMAGE.
	35	.\"
	36	.\" $FreeBSD: src/lib/libc/gen/stringlist.3,v 1.11 2005/02/13 23:45:46 ru Exp $
	37	.\"
	38	.Dd November 28, 1999
	39	.Os
	40	.Dt STRINGLIST 3
	41	.Sh NAME
	42	.Nm stringlist ,
	43	.Nm sl_init ,
	44	.Nm sl_add ,
	45	.Nm sl_free ,
	46	.Nm sl_find
	47	.Nd stringlist manipulation functions
	48	.Sh LIBRARY
	49	.Lb libc
	50	.Sh SYNOPSIS
	51	.In stringlist.h
	52	.Ft StringList *
	53	.Fn sl_init
	54	.Ft int
	55	.Fn sl_add "StringList sl" "char item"
	56	.Ft void
	57	.Fn sl_free "StringList *sl" "int freeall"
	58	.Ft char *
	59	.Fn sl_find "StringList sl" "char item"
	60	.Sh DESCRIPTION
	61	The
	62	.Nm
	63	functions manipulate stringlists, which are lists of
	64	strings that extend automatically if necessary.
	65	.Pp
	66	The
	67	.Vt StringList
	68	structure has the following definition:
	69	.Bd -literal -offset indent
	70	typedef struct _stringlist {
	71	char **sl_str;
	72	size_t sl_max;
	73	size_t sl_cur;
	74	} StringList;
	75	.Ed
	76	.Pp
	77	.Bl -tag -width "sl_str" -offset indent
	78	.It Va sl_str
	79	a pointer to the base of the array containing the list.
	80	.It Va sl_max
	81	the size of
	82	.Va sl_str .
	83	.It Va sl_cur
	84	the offset in
	85	.Va sl_str
	86	of the current element.
	87	.El
	88	.Pp
	89	The following stringlist manipulation functions are available:
	90	.Bl -tag -width "sl_init()"
	91	.It Fn sl_init
	92	Create a stringlist.
	93	Returns a pointer to a
	94	.Vt StringList ,
	95	or
	96	.Dv NULL
	97	in case of failure.
	98	.It Fn sl_free
	99	Releases memory occupied by
	100	.Fa sl
	101	and the
	102	.Fa sl->sl_str
	103	array.
	104	If
	105	.Fa freeall
	106	is non-zero, then each of the items within
	107	.Fa sl->sl_str
	108	is released as well.
	109	.It Fn sl_add
	110	Add
	111	.Fa item
	112	to
	113	.Fa sl->sl_str
	114	at
	115	.Fa sl->sl_cur ,
	116	extending the size of
	117	.Fa sl->sl_str .
	118	Returns zero upon success, \-1 upon failure.
	119	.It Fn sl_find
	120	Find
	121	.Fa item
	122	in
	123	.Fa sl ,
	124	returning NULL if it is not found.
	125	.El
	126	.Sh SEE ALSO
	127	.Xr free 3 ,
	128	.Xr malloc 3
	129	.Sh HISTORY
	130	The
	131	.Nm
	132	functions appeared in
	133	.Fx 2.2.6
	134	and
	135	.Nx 1.3 .