1.\" $NetBSD: stringlist.3,v 1.13 2008/04/30 13:10:50 martin 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 FOUNDATION OR CONTRIBUTORS 21.\" BE 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.Dd July 27, 2006 30.Os 31.Dt STRINGLIST 3 32.Sh NAME 33.Nm stringlist , 34.Nm sl_init , 35.Nm sl_add , 36.Nm sl_free , 37.Nm sl_find , 38.Nm sl_delete 39.Nd stringlist manipulation functions 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In stringlist.h 44.Ft StringList * 45.Fn sl_init 46.Ft int 47.Fn sl_add "StringList *sl" "char *item" 48.Ft void 49.Fn sl_free "StringList *sl" "int freeall" 50.Ft char * 51.Fn sl_find "StringList *sl" "const char *item" 52.Ft int 53.Fn sl_delete "StringList *sl" "const char *item" "int freeit" 54.Sh DESCRIPTION 55The 56.Nm 57functions manipulate stringlists, which are lists of 58strings that extend automatically if necessary. 59.Pp 60The 61.Ar StringList 62structure has the following definition: 63.Bd -literal -offset indent 64typedef struct _stringlist { 65 char **sl_str; 66 size_t sl_max; 67 size_t sl_cur; 68} StringList; 69.Ed 70.Pp 71.Bl -tag -width "sl_str" -offset indent 72.It Ar sl_str 73a pointer to the base of the array containing the list. 74.It Ar sl_max 75the size of 76.Ar sl_str . 77.It Ar sl_cur 78the offset in 79.Ar sl_str 80of the current element. 81.El 82.Pp 83The following stringlist manipulation functions are available: 84.Bl -tag -width "sl_init()" 85.It Fn sl_init 86Create a stringlist. 87Returns a pointer to a 88.Ar StringList , 89or 90.Dv NULL 91in case of failure. 92.It Fn sl_free 93Releases memory occupied by 94.Ar sl 95and the 96.Ar sl-\*[Gt]sl_str 97array. 98If 99.Ar freeall 100is non-zero, then each of the items within 101.Ar sl-\*[Gt]sl_str 102is released as well. 103.It Fn sl_add 104Add 105.Ar item 106to 107.Ar sl-\*[Gt]sl_str 108at 109.Ar sl-\*[Gt]sl_cur , 110extending the size of 111.Ar sl-\*[Gt]sl_str . 112Returns zero upon success, \-1 upon failure. 113.It Fn sl_find 114Find 115.Ar item 116in 117.Ar sl , 118returning 119.Dv NULL 120if it's not found. 121.It Fn sl_delete 122Remove 123.Ar item 124from the list. 125If 126.Ar freeit 127is non-zero, the string is freed. 128Returns 129.Dv 0 130if the name is found 131and 132.Dv \-1 133if the name is not found. 134.El 135.Sh SEE ALSO 136.Xr free 3 , 137.Xr malloc 3 138.Sh HISTORY 139The 140.Nm 141functions appeared in 142.Nx 1.3 . 143