Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / stringlist.3
CommitLineData
984263bc
MD
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 $
1de703da 37.\" $DragonFly: src/lib/libc/gen/stringlist.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
984263bc
MD
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.Pp
78.Bl -tag -width "sl_str" -offset indent
79.It Ar sl_str
80a pointer to the base of the array containing the list.
81.It Ar sl_max
82the size of
83.Ar sl_str .
84.It Ar sl_cur
85the offset in
86.Ar sl_str
87of the current element.
88.El
89.Pp
90The following stringlist manipulation functions are available:
91.Bl -tag -width "sl_init()"
92.It Fn sl_init
93Create a stringlist.
94Returns a pointer to a
95.Ar StringList .
96.It Fn sl_free
97Releases memory occupied by
98.Ar sl
99and the
100.Ar sl->sl_str
101array.
102If
103.Ar freeall
104is non-zero, then each of the items within
105.Ar sl->sl_str
106is released as well.
107.It Fn sl_add
108Add
109.Ar item
110to
111.Ar sl->sl_str
112at
113.Ar sl->sl_cur ,
114extending the size of
115.Ar sl->sl_str
116.It Fn sl_find
117Find
118.Ar item
119in
120.Ar sl ,
121returning NULL if it's not found.
122.El
123.Sh SEE ALSO
124.Xr free 3 ,
125.Xr malloc 3