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