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" "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.Pp 70.Bl -tag -width "sl_str" -offset indent 71.It Va sl_str 72a pointer to the base of the array containing the list. 73.It Va sl_max 74the size of 75.Va sl_str . 76.It Va sl_cur 77the offset in 78.Va sl_str 79of the current element. 80.El 81.Pp 82The following stringlist manipulation functions are available: 83.Bl -tag -width "sl_init()" 84.It Fn sl_init 85Create a stringlist. 86Returns a pointer to a 87.Vt StringList , 88or 89.Dv NULL 90in case of failure. 91.It Fn sl_free 92Releases memory occupied by 93.Fa sl 94and the 95.Fa sl->sl_str 96array. 97If 98.Fa freeall 99is non-zero, then each of the items within 100.Fa sl->sl_str 101is released as well. 102.It Fn sl_add 103Add 104.Fa item 105to 106.Fa sl->sl_str 107at 108.Fa sl->sl_cur , 109extending the size of 110.Fa sl->sl_str . 111Returns zero upon success, \-1 upon failure. 112.It Fn sl_find 113Find 114.Fa item 115in 116.Fa sl , 117returning NULL if it is not found. 118.El 119.Sh SEE ALSO 120.Xr free 3 , 121.Xr malloc 3 122.Sh HISTORY 123The 124.Nm 125functions appeared in 126.Fx 2.2.6 127and 128.Nx 1.3 . 129