share/man/man9f/list_create.9f

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH LIST_CREATE 9F "Sep 17, 2009"
   7 .SH NAME
   8 list_create, list_destroy, list_insert_after, list_insert_before,
   9 list_insert_head, list_insert_tail, list_remove, list_remove_head,
  10 list_remove_tail, list_head, list_tail, list_next, list_prev, list_is_empty,
  11 list_link_init, list_link_active, list_move_tail, list_link_replace \- list
  12 functions
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 #include <sys/list.h>
  17
  18 \fBvoid\fR \fBlist_create\fR(\fBlist_t *\fR \fIlist\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fIoffset\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBlist_destroy\fR(\fBlist_t *\fR \fIlist\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBlist_insert_after\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR,
  29      \fBvoid *\fR\fInew_item\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBvoid\fR \fBlist_insert_before\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR,
  35      \fBvoid *\fR\fInew_item\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBlist_insert_head\fR(\fBlist_t *\fR \fIlist\fR*, \fBvoid *\fR\fInew_item\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBvoid\fR \fBlist_insert_tail\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fInew_item\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBvoid\fR \fBlist_remove\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fRitem);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBvoid *\fR\fBlist_remove_head\fR(\fBlist_t *\fR \fIlist\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBvoid *\fR\fBlist_remove_tail\fR(\fBlist_t *\fR \fIlist\fR);
  61 .fi
  62
  63 .LP
  64 .nf
  65 \fBvoid *\fR\fBlist_head\fR(\fBlist_t *\fR \fIlist\fR);
  66 .fi
  67
  68 .LP
  69 .nf
  70 \fBvoid *\fR\fBlist_tail\fR(\fBlist_t *\fR \fIlist\fR);
  71 .fi
  72
  73 .LP
  74 .nf
  75 \fBvoid *\fR\fBlist_next\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR);
  76 .fi
  77
  78 .LP
  79 .nf
  80 \fBvoid *\fR\fBlist_prev\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR);
  81 .fi
  82
  83 .LP
  84 .nf
  85 \fBint\fR \fBlist_is_empty\fR(\fBlist_t *\fR \fIlist\fR);
  86 .fi
  87
  88 .LP
  89 .nf
  90 \fBvoid\fR \fBlist_link_init\fR(\fBlist_node_t *\fR\fInode\fR);
  91 .fi
  92
  93 .LP
  94 .nf
  95 \fBint\fR \fBlist_link_active\fR(\fBlist_node_t *\fR\fInode\fR);
  96 .fi
  97
  98 .LP
  99 .nf
 100 \fBvoid\fR \fBlist_move_tail\fR(\fBlist_t *\fR\fIdst\fR, \fBlist_t *\fR\fIsrc\fR);
 101 .fi
 102
 103 .LP
 104 .nf
 105 \fBvoid\fR \fBlist_link_replace\fR(\fBlist_node_t *\fR\fInode1\fR, \fBlist_node_t *\fR\fInode2\fR);
 106 .fi
 107
 108 .SH DESCRIPTION
 109 .LP
 110 These functions provide a generic doubly-linked list implementation. To
 111 utilize it, simply embed a \fBlist_node_t\fR field in the structures
 112 that will constitute the linked list elements and pass the
 113 \fBlist_node_t\fR field offset to \fBlist_create()\fR in the appropriate
 114 parameter (see below). A single \fBlist_node_t\fR field can only be used
 115 in a single list simultaneously, so to add a structure to multiple
 116 lists, embed multiple \fBlist_node_t\fR fields in your user structure.
 117 .sp
 118 .LP
 119 Please note that a \fBlist_node_t\fR contains pointers back to its
 120 parent \fBlist_t\fR so you cannot copy the \fBlist_t\fR around once it
 121 has been initialized. In particular, this kind of construct won't work:
 122 .sp
 123 .in +2
 124 .nf
 125 struct { list_t l; } a, b;
 126 list_create(&a.l, ...);
 127 b = a;    <= This will break the list in `b', as the `l' element
 128              in `a' got copied to a different memory address.
 129 .fi
 130 .in -2
 131 .sp
 132 To do this you must move the list items to the new list using functions
 133 such as \fBlist_move_tail()\fR.
 134 .sp
 135 .LP
 136 The \fBlist_create()\fR function initializes a new list. The driver supplies
 137 the storage for the list handle, the size of an individual element, and the
 138 offset of a \fBlist_node_t\fR within the element to use for the links of the
 139 list.
 140 .sp
 141 .LP
 142 The \fBlist_destroy()\fR function destroys the list handle, including freeing
 143 any resources that may have been internally allocated for the list. The list
 144 must be empty when this function is called.
 145 .sp
 146 .LP
 147 The \fBlist_insert_after()\fR and \fBlist_insert_before()\fR functions insert
 148 \fInew_item\fR into the linked list at a location after or before the reference
 149 item, which must already be on the list.
 150 .sp
 151 .LP
 152 The \fBlist_insert_head()\fR and \fBlist_insert_tail()\fR functions insert the
 153 \fInew_item\fR on the list at either the head or tail of the list.  (The head
 154 is the first item, the tail is the last item).
 155 .sp
 156 .LP
 157 The \fBlist_remove()\fR function removes the item from the list.
 158 .sp
 159 .LP
 160 The \fBlist_remove_head()\fR and \fBlist_remove_tail()\fR functions remove the
 161 head (first) or tail (last) item from the list. The item removed is returned to
 162 the caller. If the list is empty when these functions are called, then no
 163 change is made and \fINULL\fR is returned to the caller.
 164 .sp
 165 .LP
 166 The \fBlist_head()\fR and \fBlist_tail()\fR functions simply return the head
 167 (first) or tail (last) item on the list.  \fINULL\fR is returned if the list is
 168 empty.
 169 .sp
 170 .LP
 171 The \fBlist_next()\fR and \fBlist_prev()\fR functions return the next or
 172 previous item in the list, relative to the named reference item which must be
 173 linked on the list.
 174 .sp
 175 .LP
 176 The \fBlist_is_empty()\fR function returns 0 if the list has items in it, or
 177 non-zero otherwise.
 178 .sp
 179 .LP
 180 The \fBlist_link_init()\fR function initializes the \fBlist_node_t\fR. It is
 181 functionally equivalent to \fBbzero\fR(\fInode\fR, \fBsizeof\fR(*\fInode\fR));
 182 .sp
 183 .LP
 184 The \fBlist_link_active()\fR function returns non-zero if the node is on an
 185 active list.
 186 .sp
 187 .LP
 188 The \fBlist_move_tail()\fR function is used to append the items on the
 189 \fIsrc\fR list to the end of the \fIdst\fR list. It is mandatory that the two
 190 lists were initialized using identical size and offset parameters. Upon
 191 completion, the \fIsrc\fR list will be empty.
 192 .sp
 193 .LP
 194 The \fBlist_link_replace()\fR function swaps two items on a list.  Note that
 195 the items need not be on the same list, but extreme care must be used to ensure
 196 that both lists are protected from concurrent accesses and that the lists were
 197 initialized with identical size and offset parameters.
 198 .SH ATTRIBUTES
 199 .LP
 200 See \fBattributes\fR(5) for descriptions of the following attributes:
 201 .sp
 202
 203 .sp
 204 .TS
 205 box;
 206 c | c
 207 l | l .
 208 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 209 _
 210 Interface Stability     Committed
 211 .TE
 212
 213 .SH SEE ALSO
 214 .LP
 215 \fBattributes\fR(5)