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