xref: /dragonfly/lib/libc/gen/stringlist.3 (revision 19fe1c42)
1.\"	$NetBSD: stringlist.3,v 1.2 1997/04/09 08:59:25 kleink Exp $
2.\"
3.\" Copyright (c) 1997 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.3.2.4 2001/12/14 18:33:51 ru Exp $
37.\" $DragonFly: src/lib/libc/gen/stringlist.3,v 1.4 2008/11/23 21:55:52 swildner Exp $
38.\"
39.Dd February 24, 1997
40.Os
41.Dt STRINGLIST 3
42.Sh NAME
43.Nm stringlist ,
44.Nm sl_init ,
45.Nm sl_add ,
46.Nm sl_free ,
47.Nm sl_find
48.Nd stringlist manipulation functions
49.Sh LIBRARY
50.Lb libc
51.Sh SYNOPSIS
52.In stringlist.h
53.Ft StringList *
54.Fn sl_init
55.Ft void
56.Fn sl_add "StringList *sl" "char *item"
57.Ft void
58.Fn sl_free "StringList *sl" "int freeall"
59.Ft char *
60.Fn sl_find "StringList *sl" "char *item"
61.Sh DESCRIPTION
62The
63.Nm
64functions manipulate stringlists, which are lists of
65strings that extend automatically if necessary.
66.Pp
67The
68.Ar StringList
69structure has the following definition:
70.Bd -literal -offset indent
71typedef struct _stringlist {
72	char	**sl_str;
73	size_t	  sl_max;
74	size_t	  sl_cur;
75} StringList;
76.Ed
77.Bl -tag -width "sl_str" -offset indent
78.It Ar sl_str
79a pointer to the base of the array containing the list.
80.It Ar sl_max
81the size of
82.Ar sl_str .
83.It Ar sl_cur
84the offset in
85.Ar sl_str
86of the current element.
87.El
88.Pp
89The following stringlist manipulation functions are available:
90.Bl -tag -width ".Fn sl_init"
91.It Fn sl_init
92Create a stringlist.
93Returns a pointer to a
94.Ar StringList .
95.It Fn sl_free
96Releases memory occupied by
97.Ar sl
98and the
99.Ar sl->sl_str
100array.
101If
102.Ar freeall
103is non-zero, then each of the items within
104.Ar sl->sl_str
105is released as well.
106.It Fn sl_add
107Add
108.Ar item
109to
110.Ar sl->sl_str
111at
112.Ar sl->sl_cur ,
113extending the size of
114.Ar sl->sl_str
115.It Fn sl_find
116Find
117.Ar item
118in
119.Ar sl ,
120returning NULL if it's not found.
121.El
122.Sh SEE ALSO
123.Xr free 3 ,
124.Xr malloc 3
125