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.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 21.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd November 28, 1999 32.Dt STRINGLIST 3 33.Os 34.Sh NAME 35.Nm stringlist , 36.Nm sl_init , 37.Nm sl_add , 38.Nm sl_free , 39.Nm sl_find 40.Nd stringlist manipulation functions 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In stringlist.h 45.Ft StringList * 46.Fn sl_init 47.Ft int 48.Fn sl_add "StringList *sl" "char *item" 49.Ft void 50.Fn sl_free "StringList *sl" "int freeall" 51.Ft char * 52.Fn sl_find "StringList *sl" "const char *item" 53.Sh DESCRIPTION 54The 55.Nm 56functions manipulate stringlists, which are lists of 57strings that extend automatically if necessary. 58.Pp 59The 60.Vt StringList 61structure has the following definition: 62.Bd -literal -offset indent 63typedef struct _stringlist { 64 char **sl_str; 65 size_t sl_max; 66 size_t sl_cur; 67} StringList; 68.Ed 69.Bl -tag -width "sl_str" -offset indent 70.It Va sl_str 71a pointer to the base of the array containing the list. 72.It Va sl_max 73the size of 74.Va sl_str . 75.It Va sl_cur 76the offset in 77.Va sl_str 78of the current element. 79.El 80.Pp 81The following stringlist manipulation functions are available: 82.Bl -tag -width "sl_init()" 83.It Fn sl_init 84Create a stringlist. 85Returns a pointer to a 86.Vt StringList , 87or 88.Dv NULL 89in case of failure. 90.It Fn sl_free 91Releases memory occupied by 92.Fa sl 93and the 94.Fa sl->sl_str 95array. 96If 97.Fa freeall 98is non-zero, then each of the items within 99.Fa sl->sl_str 100is released as well. 101.It Fn sl_add 102Add 103.Fa item 104to 105.Fa sl->sl_str 106at 107.Fa sl->sl_cur , 108extending the size of 109.Fa sl->sl_str . 110Returns zero upon success, \-1 upon failure. 111.It Fn sl_find 112Find 113.Fa item 114in 115.Fa sl , 116returning NULL if it is not found. 117.El 118.Sh SEE ALSO 119.Xr free 3 , 120.Xr malloc 3 121.Sh HISTORY 122The 123.Nm 124functions appeared in 125.Fx 2.2.6 126and 127.Nx 1.3 . 128