lib/libc/gen/stringlist.3

   1 .\"     $NetBSD: stringlist.3,v 1.15 2010/05/06 09:46:49 jruoho 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 May 6, 2010
  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 where:
  72 .Bl -tag -width "sl_str" -offset indent
  73 .It Ar sl_str
  74 is a pointer to the base of the array containing the list,
  75 .It Ar sl_max
  76 is the size of
  77 .Ar sl_str ,
  78 and
  79 .It Ar sl_cur
  80 is the offset in
  81 .Ar sl_str
  82 of the current element.
  83 .El
  84 .Pp
  85 The following stringlist manipulation functions are available:
  86 .Bl -tag -width "sl_delete()" -offset 2n
  87 .It Fn sl_init
  88 Create a stringlist.
  89 Returns a pointer to a
  90 .Ar StringList ,
  91 or
  92 .Dv NULL
  93 in case of failure.
  94 .It Fn sl_free
  95 Releases memory occupied by
  96 .Ar sl
  97 and the
  98 .Ar sl-\*[Gt]sl_str
  99 array.
 100 If
 101 .Ar freeall
 102 is non-zero, then each of the items within
 103 .Ar sl-\*[Gt]sl_str
 104 is released as well.
 105 .It Fn sl_add
 106 Add
 107 .Ar item
 108 to
 109 .Ar sl-\*[Gt]sl_str
 110 at
 111 .Ar sl-\*[Gt]sl_cur ,
 112 extending the size of
 113 .Ar sl-\*[Gt]sl_str .
 114 Returns zero upon success, \-1 upon failure.
 115 .It Fn sl_find
 116 Find
 117 .Ar item
 118 in
 119 .Ar sl ,
 120 returning
 121 .Dv NULL
 122 if it's not found.
 123 .It Fn sl_delete
 124 Remove
 125 .Ar item
 126 from the list.
 127 If
 128 .Ar freeit
 129 is non-zero, the string is freed.
 130 Returns
 131 .Dv 0
 132 if the name is found
 133 and
 134 .Dv \-1
 135 if the name is not found.
 136 .El
 137 .Sh SEE ALSO
 138 .Xr free 3 ,
 139 .Xr malloc 3
 140 .Sh HISTORY
 141 The
 142 .Nm
 143 functions appeared in
 144 .Nx 1.3 .