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.2 2003/06/17 04:26:42 dillon 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 .Pp
  78 .Bl -tag -width "sl_str" -offset indent
  79 .It Ar sl_str
  80 a pointer to the base of the array containing the list.
  81 .It Ar sl_max
  82 the size of
  83 .Ar sl_str .
  84 .It Ar sl_cur
  85 the offset in
  86 .Ar sl_str
  87 of the current element.
  88 .El
  89 .Pp
  90 The following stringlist manipulation functions are available:
  91 .Bl -tag -width "sl_init()"
  92 .It Fn sl_init
  93 Create a stringlist.
  94 Returns a pointer to a
  95 .Ar StringList .
  96 .It Fn sl_free
  97 Releases memory occupied by
  98 .Ar sl
  99 and the
 100 .Ar sl->sl_str
 101 array.
 102 If
 103 .Ar freeall
 104 is non-zero, then each of the items within
 105 .Ar sl->sl_str
 106 is released as well.
 107 .It Fn sl_add
 108 Add
 109 .Ar item
 110 to
 111 .Ar sl->sl_str
 112 at
 113 .Ar sl->sl_cur ,
 114 extending the size of
 115 .Ar sl->sl_str
 116 .It Fn sl_find
 117 Find
 118 .Ar item
 119 in
 120 .Ar sl ,
 121 returning NULL if it's not found.
 122 .El
 123 .Sh SEE ALSO
 124 .Xr free 3 ,
 125 .Xr malloc 3