lib/libc/gen/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 .\"
  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 REGENTS OR CONTRIBUTORS BE
  21 .\" 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 .\" $FreeBSD$
  30 .\"
  31 .Dd November 28, 1999
  32 .Dt STRINGLIST 3
  33 .Os
  34 .Sh NAME
  35 .Nm stringlist ,
  36 .Nm sl_init ,
  37 .Nm sl_add ,
  38 .Nm sl_free ,
  39 .Nm sl_find
  40 .Nd stringlist manipulation functions
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In stringlist.h
  45 .Ft StringList *
  46 .Fn sl_init
  47 .Ft int
  48 .Fn sl_add "StringList *sl" "char *item"
  49 .Ft void
  50 .Fn sl_free "StringList *sl" "int freeall"
  51 .Ft char *
  52 .Fn sl_find "StringList *sl" "const char *item"
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 functions manipulate stringlists, which are lists of
  57 strings that extend automatically if necessary.
  58 .Pp
  59 The
  60 .Vt StringList
  61 structure has the following definition:
  62 .Bd -literal -offset indent
  63 typedef struct _stringlist {
  64         char    **sl_str;
  65         size_t    sl_max;
  66         size_t    sl_cur;
  67 } StringList;
  68 .Ed
  69 .Bl -tag -width "sl_str" -offset indent
  70 .It Va sl_str
  71 a pointer to the base of the array containing the list.
  72 .It Va sl_max
  73 the size of
  74 .Va sl_str .
  75 .It Va sl_cur
  76 the offset in
  77 .Va sl_str
  78 of the current element.
  79 .El
  80 .Pp
  81 The following stringlist manipulation functions are available:
  82 .Bl -tag -width "sl_init()"
  83 .It Fn sl_init
  84 Create a stringlist.
  85 Returns a pointer to a
  86 .Vt StringList ,
  87 or
  88 .Dv NULL
  89 in case of failure.
  90 .It Fn sl_free
  91 Releases memory occupied by
  92 .Fa sl
  93 and the
  94 .Fa sl->sl_str
  95 array.
  96 If
  97 .Fa freeall
  98 is non-zero, then each of the items within
  99 .Fa sl->sl_str
 100 is released as well.
 101 .It Fn sl_add
 102 Add
 103 .Fa item
 104 to
 105 .Fa sl->sl_str
 106 at
 107 .Fa sl->sl_cur ,
 108 extending the size of
 109 .Fa sl->sl_str .
 110 Returns zero upon success, \-1 upon failure.
 111 .It Fn sl_find
 112 Find
 113 .Fa item
 114 in
 115 .Fa sl ,
 116 returning NULL if it is not found.
 117 .El
 118 .Sh SEE ALSO
 119 .Xr free 3 ,
 120 .Xr malloc 3
 121 .Sh HISTORY
 122 The
 123 .Nm
 124 functions appeared in
 125 .Fx 2.2.6
 126 and
 127 .Nx 1.3 .