lib/libc/gen/stringlist.3

   1 .\"     $NetBSD: stringlist.3,v 1.2 1997/04/09 08:59:25 kleink Exp $
   2 .\"
   3 .\" Copyright (c) 1997 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.3.2.4 2001/12/14 18:33:51 ru Exp $
  37 .\" $DragonFly: src/lib/libc/gen/stringlist.3,v 1.3 2008/05/02 02:05:03 swildner Exp $
  38 .\"
  39 .Dd February 24, 1997
  40 .Os
  41 .Dt STRINGLIST 3
  42 .Sh NAME
  43 .Nm stringlist ,
  44 .Nm sl_init ,
  45 .Nm sl_add ,
  46 .Nm sl_free ,
  47 .Nm sl_find
  48 .Nd stringlist manipulation functions
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In stringlist.h
  53 .Ft StringList *
  54 .Fn sl_init
  55 .Ft void
  56 .Fn sl_add "StringList *sl" "char *item"
  57 .Ft void
  58 .Fn sl_free "StringList *sl" "int freeall"
  59 .Ft char *
  60 .Fn sl_find "StringList *sl" "char *item"
  61 .Sh DESCRIPTION
  62 The
  63 .Nm
  64 functions manipulate stringlists, which are lists of
  65 strings that extend automatically if necessary.
  66 .Pp
  67 The
  68 .Ar StringList
  69 structure has the following definition:
  70 .Bd -literal -offset indent
  71 typedef struct _stringlist {
  72         char    **sl_str;
  73         size_t    sl_max;
  74         size_t    sl_cur;
  75 } StringList;
  76 .Ed
  77 .Bl -tag -width "sl_str" -offset indent
  78 .It Ar sl_str
  79 a pointer to the base of the array containing the list.
  80 .It Ar sl_max
  81 the size of
  82 .Ar sl_str .
  83 .It Ar sl_cur
  84 the offset in
  85 .Ar 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 .Ar StringList .
  95 .It Fn sl_free
  96 Releases memory occupied by
  97 .Ar sl
  98 and the
  99 .Ar sl->sl_str
 100 array.
 101 If
 102 .Ar freeall
 103 is non-zero, then each of the items within
 104 .Ar sl->sl_str
 105 is released as well.
 106 .It Fn sl_add
 107 Add
 108 .Ar item
 109 to
 110 .Ar sl->sl_str
 111 at
 112 .Ar sl->sl_cur ,
 113 extending the size of
 114 .Ar sl->sl_str
 115 .It Fn sl_find
 116 Find
 117 .Ar item
 118 in
 119 .Ar sl ,
 120 returning NULL if it's not found.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr free 3 ,
 124 .Xr malloc 3