[BACK]Return to stringlist.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

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>