gen/FreeBSD/stringlist.3

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