lib/libc/gen/stringlist.3

   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 .Dt STRINGLIST 3
  31 .Os
  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
  55 The
  56 .Nm
  57 functions manipulate stringlists, which are lists of
  58 strings that extend automatically if necessary.
  59 .Pp
  60 The
  61 .Ar StringList
  62 structure has the following definition:
  63 .Bd -literal -offset indent
  64 typedef 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
  73 a pointer to the base of the array containing the list.
  74 .It Ar sl_max
  75 the size of
  76 .Ar sl_str .
  77 .It Ar sl_cur
  78 the offset in
  79 .Ar sl_str
  80 of the current element.
  81 .El
  82 .Pp
  83 The following stringlist manipulation functions are available:
  84 .Bl -tag -width "sl_init()"
  85 .It Fn sl_init
  86 Create a stringlist.
  87 Returns a pointer to a
  88 .Ar StringList ,
  89 or
  90 .Dv NULL
  91 in case of failure.
  92 .It Fn sl_free
  93 Releases memory occupied by
  94 .Ar sl
  95 and the
  96 .Ar sl-\*[Gt]sl_str
  97 array.
  98 If
  99 .Ar freeall
 100 is non-zero, then each of the items within
 101 .Ar sl-\*[Gt]sl_str
 102 is released as well.
 103 .It Fn sl_add
 104 Add
 105 .Ar item
 106 to
 107 .Ar sl-\*[Gt]sl_str
 108 at
 109 .Ar sl-\*[Gt]sl_cur ,
 110 extending the size of
 111 .Ar sl-\*[Gt]sl_str .
 112 Returns zero upon success, \-1 upon failure.
 113 .It Fn sl_find
 114 Find
 115 .Ar item
 116 in
 117 .Ar sl ,
 118 returning
 119 .Dv NULL
 120 if it's not found.
 121 .It Fn sl_delete
 122 Remove
 123 .Ar item
 124 from the list.
 125 If
 126 .Ar freeit
 127 is non-zero, the string is freed.
 128 Returns
 129 .Dv 0
 130 if the name is found
 131 and
 132 .Dv \-1
 133 if the name is not found.
 134 .El
 135 .Sh SEE ALSO
 136 .Xr free 3 ,
 137 .Xr malloc 3
 138 .Sh HISTORY
 139 The
 140 .Nm
 141 functions appeared in
 142 .Nx 1.3 .