xref: /freebsd/lib/libc/gen/stringlist.3 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
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$
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
61The
62.Nm
63functions manipulate stringlists, which are lists of
64strings that extend automatically if necessary.
65.Pp
66The
67.Vt StringList
68structure has the following definition:
69.Bd -literal -offset indent
70typedef 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
79a pointer to the base of the array containing the list.
80.It Va sl_max
81the size of
82.Va sl_str .
83.It Va sl_cur
84the offset in
85.Va sl_str
86of the current element.
87.El
88.Pp
89The following stringlist manipulation functions are available:
90.Bl -tag -width "sl_init()"
91.It Fn sl_init
92Create a stringlist.
93Returns a pointer to a
94.Vt StringList ,
95or
96.Dv NULL
97in case of failure.
98.It Fn sl_free
99Releases memory occupied by
100.Fa sl
101and the
102.Fa sl->sl_str
103array.
104If
105.Fa freeall
106is non-zero, then each of the items within
107.Fa sl->sl_str
108is released as well.
109.It Fn sl_add
110Add
111.Fa item
112to
113.Fa sl->sl_str
114at
115.Fa sl->sl_cur ,
116extending the size of
117.Fa sl->sl_str .
118Returns zero upon success, \-1 upon failure.
119.It Fn sl_find
120Find
121.Fa item
122in
123.Fa sl ,
124returning NULL if it is not found.
125.El
126.Sh SEE ALSO
127.Xr free 3 ,
128.Xr malloc 3
129.Sh HISTORY
130The
131.Nm
132functions appeared in
133.Fx 2.2.6
134and
135.Nx 1.3 .
136