libs/dbprim/doc/latex/group__dbprim__link.tex

   1 \section{Linked lists}
   2 \label{group__dbprim__link}\index{Linked lists@{Linked lists}}
   3 Operations for linked lists.
   4 \subsection*{Defines}
   5 \begin{CompactItemize}
   6 \item
   7 \#define {\bf LINK\_\-HEAD\_\-INIT}(extra)
   8 \begin{CompactList}\small\item\em Linked list head static initializer.\item\end{CompactList}\item
   9 \#define {\bf ll\_\-verify}(list)
  10 \begin{CompactList}\small\item\em Linked list head verification macro.\item\end{CompactList}\item
  11 \#define {\bf ll\_\-count}(list)
  12 \begin{CompactList}\small\item\em Linked list count.\item\end{CompactList}\item
  13 \#define {\bf ll\_\-first}(list)
  14 \begin{CompactList}\small\item\em First element in linked list.\item\end{CompactList}\item
  15 \#define {\bf ll\_\-last}(list)
  16 \begin{CompactList}\small\item\em Last element in a linked list.\item\end{CompactList}\item
  17 \#define {\bf ll\_\-extra}(list)
  18 \begin{CompactList}\small\item\em Extra pointer data in a linked list.\item\end{CompactList}\item
  19 \#define {\bf LINK\_\-ELEM\_\-INIT}(obj)
  20 \begin{CompactList}\small\item\em Linked list element static initializer.\item\end{CompactList}\item
  21 \#define {\bf le\_\-verify}(element)
  22 \begin{CompactList}\small\item\em Linked list element verification macro.\item\end{CompactList}\item
  23 \#define {\bf le\_\-next}(elem)
  24 \begin{CompactList}\small\item\em Linked list element next pointer.\item\end{CompactList}\item
  25 \#define {\bf le\_\-prev}(elem)
  26 \begin{CompactList}\small\item\em Linked list element previous pointer.\item\end{CompactList}\item
  27 \#define {\bf le\_\-object}(elem)
  28 \begin{CompactList}\small\item\em Linked list element object pointer.\item\end{CompactList}\item
  29 \#define {\bf le\_\-head}(elem)
  30 \begin{CompactList}\small\item\em Linked list element head pointer.\item\end{CompactList}\item
  31 \#define {\bf le\_\-flags}(elem)
  32 \begin{CompactList}\small\item\em Linked list element flags.\item\end{CompactList}\end{CompactItemize}
  33 \subsection*{Typedefs}
  34 \begin{CompactItemize}
  35 \item
  36 typedef struct \_\-link\_\-head\_\-s {\bf link\_\-head\_\-t}
  37 \begin{CompactList}\small\item\em Linked list head.\item\end{CompactList}\item
  38 typedef struct \_\-link\_\-elem\_\-s {\bf link\_\-elem\_\-t}
  39 \begin{CompactList}\small\item\em Linked list element.\item\end{CompactList}\item
  40 typedef unsigned long ($\ast$ {\bf link\_\-iter\_\-t} )({\bf link\_\-head\_\-t} $\ast$, {\bf link\_\-elem\_\-t} $\ast$, void $\ast$)
  41 \begin{CompactList}\small\item\em Linked list iteration callback.\item\end{CompactList}\item
  42 typedef unsigned long ($\ast$ {\bf link\_\-comp\_\-t} )({\bf db\_\-key\_\-t} $\ast$, void $\ast$)
  43 \begin{CompactList}\small\item\em Linked list comparison callback.\item\end{CompactList}\item
  44 typedef enum {\bf \_\-link\_\-loc\_\-e} {\bf link\_\-loc\_\-t}
  45 \begin{CompactList}\small\item\em Linked list location.\item\end{CompactList}\end{CompactItemize}
  46 \subsection*{Enumerations}
  47 \begin{CompactItemize}
  48 \item
  49 enum {\bf \_\-link\_\-loc\_\-e} \{ {\bf LINK\_\-LOC\_\-HEAD},
  50 {\bf LINK\_\-LOC\_\-TAIL},
  51 {\bf LINK\_\-LOC\_\-BEFORE},
  52 {\bf LINK\_\-LOC\_\-AFTER}
  53  \}
  54 \begin{CompactList}\small\item\em Linked list location.\item\end{CompactList}\end{CompactItemize}
  55 \subsection*{Functions}
  56 \begin{CompactItemize}
  57 \item
  58 unsigned long {\bf ll\_\-init} ({\bf link\_\-head\_\-t} $\ast$list, void $\ast$extra)
  59 \begin{CompactList}\small\item\em Dynamically initialize a linked list head.\item\end{CompactList}\item
  60 unsigned long {\bf ll\_\-add} ({\bf link\_\-head\_\-t} $\ast$list, {\bf link\_\-elem\_\-t} $\ast$new, {\bf link\_\-loc\_\-t} loc, {\bf link\_\-elem\_\-t} $\ast$elem)
  61 \begin{CompactList}\small\item\em Add an element to a linked list.\item\end{CompactList}\item
  62 unsigned long {\bf ll\_\-move} ({\bf link\_\-head\_\-t} $\ast$list, {\bf link\_\-elem\_\-t} $\ast$new, {\bf link\_\-loc\_\-t} loc, {\bf link\_\-elem\_\-t} $\ast$elem)
  63 \begin{CompactList}\small\item\em Move an element within a linked list.\item\end{CompactList}\item
  64 unsigned long {\bf ll\_\-remove} ({\bf link\_\-head\_\-t} $\ast$list, {\bf link\_\-elem\_\-t} $\ast$elem)
  65 \begin{CompactList}\small\item\em Remove an element from a linked list.\item\end{CompactList}\item
  66 unsigned long {\bf ll\_\-find} ({\bf link\_\-head\_\-t} $\ast$list, {\bf link\_\-elem\_\-t} $\ast$$\ast$elem\_\-p, {\bf link\_\-comp\_\-t} comp\_\-func, {\bf link\_\-elem\_\-t} $\ast$start, {\bf db\_\-key\_\-t} $\ast$key)
  67 \begin{CompactList}\small\item\em Find an element in a linked list.\item\end{CompactList}\item
  68 unsigned long {\bf ll\_\-iter} ({\bf link\_\-head\_\-t} $\ast$list, {\bf link\_\-iter\_\-t} iter\_\-func, void $\ast$extra)
  69 \begin{CompactList}\small\item\em Iterate over each entry in a linked list.\item\end{CompactList}\item
  70 unsigned long {\bf ll\_\-flush} ({\bf link\_\-head\_\-t} $\ast$list, {\bf link\_\-iter\_\-t} flush\_\-func, void $\ast$extra)
  71 \begin{CompactList}\small\item\em Flush a linked list.\item\end{CompactList}\item
  72 unsigned long {\bf le\_\-init} ({\bf link\_\-elem\_\-t} $\ast$elem, void $\ast$object)
  73 \begin{CompactList}\small\item\em Dynamically initialize a linked list element.\item\end{CompactList}\end{CompactItemize}
  74
  75
  76 \subsection{Detailed Description}
  77 Linked lists are a very basic data structure used in building databases. This library provides a simple yet powerful implementation of generic linked lists, based on two caller-allocated structures. The {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})} structure describes the head of a linked list and contains information regarding the number of elements in the linked list as well as pointers referencing the first and last elements in the list. The {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} structure describes a specific element in the linked list and contains pointers referencing the next and previous elements in the list, as well as a pointer to the object, a pointer to the head of the linked list, and a set of user-specified flags.
  78
  79 Elements may be added at any arbitrary location in the linked list with {\bf ll\_\-add}() {\rm (p.\,\pageref{group__dbprim__link_a6})}; moved to any other arbitrary location in the linked list with {\bf ll\_\-move}() {\rm (p.\,\pageref{group__dbprim__link_a7})}, or removed from the list with {\bf ll\_\-remove}() {\rm (p.\,\pageref{group__dbprim__link_a8})}. In addition, the user may search the list using a user-defined comparison function with {\bf ll\_\-find}() {\rm (p.\,\pageref{group__dbprim__link_a9})}; iterate over every element in the list with {\bf ll\_\-iter}() {\rm (p.\,\pageref{group__dbprim__link_a10})}; or remove all items from the list with {\bf ll\_\-flush}() {\rm (p.\,\pageref{group__dbprim__link_a11})}, optionally executing a user-specified clean-up function.
  80
  81 \subsection{Define Documentation}
  82 \index{dbprim_link@{dbprim\_\-link}!LINK_ELEM_INIT@{LINK\_\-ELEM\_\-INIT}}
  83 \index{LINK_ELEM_INIT@{LINK\_\-ELEM\_\-INIT}!dbprim_link@{dbprim\_\-link}}
  84 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define LINK\_\-ELEM\_\-INIT(obj)}\label{group__dbprim__link_a19}
  85
  86
  87
  88
  89  This macro statically initializes a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.\begin{Desc}
  90 \item[{\bf Parameters: }]\par
  91 \begin{description}
  92 \item[
  93 {\em obj}]A pointer to {\tt void} representing the object associated with the element. \end{description}
  94 \end{Desc}
  95 \index{dbprim_link@{dbprim\_\-link}!LINK_HEAD_INIT@{LINK\_\-HEAD\_\-INIT}}
  96 \index{LINK_HEAD_INIT@{LINK\_\-HEAD\_\-INIT}!dbprim_link@{dbprim\_\-link}}
  97 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define LINK\_\-HEAD\_\-INIT(extra)}\label{group__dbprim__link_a13}
  98
  99
 100
 101
 102  This macro statically initializes a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.\begin{Desc}
 103 \item[{\bf Parameters: }]\par
 104 \begin{description}
 105 \item[
 106 {\em extra}]Extra pointer data that should be associated with the list head. \end{description}
 107 \end{Desc}
 108 \index{dbprim_link@{dbprim\_\-link}!le_flags@{le\_\-flags}}
 109 \index{le_flags@{le\_\-flags}!dbprim_link@{dbprim\_\-link}}
 110 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define le\_\-flags(elem)}\label{group__dbprim__link_a25}
 111
 112
 113
 114
 115  This macro retrieves a set of user-defined flags associated with the element. It may be used as an lvalue to set those flags.\begin{Desc}
 116 \item[{\bf Parameters: }]\par
 117 \begin{description}
 118 \item[
 119 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
 120
 121 \end{description}
 122 \end{Desc}
 123 \begin{Desc}
 124 \item[{\bf Returns: }]\par
 125 An {\tt unsigned long} containing the flags associated with the element. \end{Desc}
 126 \index{dbprim_link@{dbprim\_\-link}!le_head@{le\_\-head}}
 127 \index{le_head@{le\_\-head}!dbprim_link@{dbprim\_\-link}}
 128 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define le\_\-head(elem)}\label{group__dbprim__link_a24}
 129
 130
 131
 132
 133  This macro retrieves a pointer to the head of the linked list that the element is in.\begin{Desc}
 134 \item[{\bf Parameters: }]\par
 135 \begin{description}
 136 \item[
 137 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
 138
 139 \end{description}
 140 \end{Desc}
 141 \begin{Desc}
 142 \item[{\bf Returns: }]\par
 143 A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})} representing the head of the linked list the element is in. \end{Desc}
 144 \index{dbprim_link@{dbprim\_\-link}!le_next@{le\_\-next}}
 145 \index{le_next@{le\_\-next}!dbprim_link@{dbprim\_\-link}}
 146 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define le\_\-next(elem)}\label{group__dbprim__link_a21}
 147
 148
 149
 150
 151  This macro retrieves a pointer to the next element in the linked list.\begin{Desc}
 152 \item[{\bf Parameters: }]\par
 153 \begin{description}
 154 \item[
 155 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
 156
 157 \end{description}
 158 \end{Desc}
 159 \begin{Desc}
 160 \item[{\bf Returns: }]\par
 161 A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} representing the next element in the linked list. \end{Desc}
 162 \index{dbprim_link@{dbprim\_\-link}!le_object@{le\_\-object}}
 163 \index{le_object@{le\_\-object}!dbprim_link@{dbprim\_\-link}}
 164 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define le\_\-object(elem)}\label{group__dbprim__link_a23}
 165
 166
 167
 168
 169  This macro retrieves a pointer to the object represented by the element. It may be used as an lvalue to change the object pointed to. Care should be taken when using this feature.\begin{Desc}
 170 \item[{\bf Parameters: }]\par
 171 \begin{description}
 172 \item[
 173 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
 174
 175 \end{description}
 176 \end{Desc}
 177 \begin{Desc}
 178 \item[{\bf Returns: }]\par
 179 A pointer to {\tt void} representing the object associated with the linked list element. \end{Desc}
 180 \index{dbprim_link@{dbprim\_\-link}!le_prev@{le\_\-prev}}
 181 \index{le_prev@{le\_\-prev}!dbprim_link@{dbprim\_\-link}}
 182 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define le\_\-prev(elem)}\label{group__dbprim__link_a22}
 183
 184
 185
 186
 187  This macro retrieves a pointer to the previous element in the linked list.\begin{Desc}
 188 \item[{\bf Parameters: }]\par
 189 \begin{description}
 190 \item[
 191 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
 192
 193 \end{description}
 194 \end{Desc}
 195 \begin{Desc}
 196 \item[{\bf Returns: }]\par
 197 A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} representing the previous element in the linked list. \end{Desc}
 198 \index{dbprim_link@{dbprim\_\-link}!le_verify@{le\_\-verify}}
 199 \index{le_verify@{le\_\-verify}!dbprim_link@{dbprim\_\-link}}
 200 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define le\_\-verify(element)}\label{group__dbprim__link_a20}
 201
 202
 203
 204
 205  This macro verifies that a given pointer actually does point to a linked list element.\begin{Desc}
 206 \item[{\bf Parameters: }]\par
 207 \begin{description}
 208 \item[
 209 {\em element}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
 210
 211 \end{description}
 212 \end{Desc}
 213 \begin{Desc}
 214 \item[{\bf Returns: }]\par
 215 Boolean true if {\tt element} is a valid linked list element or false otherwise. \end{Desc}
 216 \index{dbprim_link@{dbprim\_\-link}!ll_count@{ll\_\-count}}
 217 \index{ll_count@{ll\_\-count}!dbprim_link@{dbprim\_\-link}}
 218 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define ll\_\-count(list)}\label{group__dbprim__link_a15}
 219
 220
 221
 222
 223  This macro retrieves the number of elements in a linked list.\begin{Desc}
 224 \item[{\bf Parameters: }]\par
 225 \begin{description}
 226 \item[
 227 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
 228
 229 \end{description}
 230 \end{Desc}
 231 \begin{Desc}
 232 \item[{\bf Returns: }]\par
 233 An {\tt unsigned long} containing a count of the number of elements in the linked list. \end{Desc}
 234 \index{dbprim_link@{dbprim\_\-link}!ll_extra@{ll\_\-extra}}
 235 \index{ll_extra@{ll\_\-extra}!dbprim_link@{dbprim\_\-link}}
 236 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define ll\_\-extra(list)}\label{group__dbprim__link_a18}
 237
 238
 239
 240
 241  This macro retrieves the extra pointer data associated with a particular linked list.\begin{Desc}
 242 \item[{\bf Parameters: }]\par
 243 \begin{description}
 244 \item[
 245 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
 246
 247 \end{description}
 248 \end{Desc}
 249 \begin{Desc}
 250 \item[{\bf Returns: }]\par
 251 A pointer to {\tt void}. \end{Desc}
 252 \index{dbprim_link@{dbprim\_\-link}!ll_first@{ll\_\-first}}
 253 \index{ll_first@{ll\_\-first}!dbprim_link@{dbprim\_\-link}}
 254 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define ll\_\-first(list)}\label{group__dbprim__link_a16}
 255
 256
 257
 258
 259  This macro retrieves the first element in a linked list.\begin{Desc}
 260 \item[{\bf Parameters: }]\par
 261 \begin{description}
 262 \item[
 263 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
 264
 265 \end{description}
 266 \end{Desc}
 267 \begin{Desc}
 268 \item[{\bf Returns: }]\par
 269 A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}. \end{Desc}
 270 \index{dbprim_link@{dbprim\_\-link}!ll_last@{ll\_\-last}}
 271 \index{ll_last@{ll\_\-last}!dbprim_link@{dbprim\_\-link}}
 272 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define ll\_\-last(list)}\label{group__dbprim__link_a17}
 273
 274
 275
 276
 277  This macro retrieves the last element in a linked list.\begin{Desc}
 278 \item[{\bf Parameters: }]\par
 279 \begin{description}
 280 \item[
 281 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
 282
 283 \end{description}
 284 \end{Desc}
 285 \begin{Desc}
 286 \item[{\bf Returns: }]\par
 287 A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}. \end{Desc}
 288 \index{dbprim_link@{dbprim\_\-link}!ll_verify@{ll\_\-verify}}
 289 \index{ll_verify@{ll\_\-verify}!dbprim_link@{dbprim\_\-link}}
 290 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define ll\_\-verify(list)}\label{group__dbprim__link_a14}
 291
 292
 293
 294
 295  This macro verifies that a given pointer actually does point to a linked list head.\begin{Desc}
 296 \item[{\bf Parameters: }]\par
 297 \begin{description}
 298 \item[
 299 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
 300
 301 \end{description}
 302 \end{Desc}
 303 \begin{Desc}
 304 \item[{\bf Returns: }]\par
 305 Boolean true if {\tt list} is a valid linked list head or false otherwise. \end{Desc}
 306
 307
 308 \subsection{Typedef Documentation}
 309 \index{dbprim_link@{dbprim\_\-link}!link_comp_t@{link\_\-comp\_\-t}}
 310 \index{link_comp_t@{link\_\-comp\_\-t}!dbprim_link@{dbprim\_\-link}}
 311 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long($\ast$ link\_\-comp\_\-t)({\bf db\_\-key\_\-t} $\ast$, void $\ast$)}\label{group__dbprim__link_a3}
 312
 313
 314
 315
 316  This function pointer references a callback used by {\bf ll\_\-find}() {\rm (p.\,\pageref{group__dbprim__link_a9})}. It should return 0 if the entry passed as the second argument matches the key passed as the first argument. \index{dbprim_link@{dbprim\_\-link}!link_elem_t@{link\_\-elem\_\-t}}
 317 \index{link_elem_t@{link\_\-elem\_\-t}!dbprim_link@{dbprim\_\-link}}
 318 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct \_\-link\_\-elem\_\-s link\_\-elem\_\-t}\label{group__dbprim__link_a1}
 319
 320
 321
 322
 323  This structure represents a single element of a linked list. \index{dbprim_link@{dbprim\_\-link}!link_head_t@{link\_\-head\_\-t}}
 324 \index{link_head_t@{link\_\-head\_\-t}!dbprim_link@{dbprim\_\-link}}
 325 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct \_\-link\_\-head\_\-s link\_\-head\_\-t}\label{group__dbprim__link_a0}
 326
 327
 328
 329
 330  This structure is the head of all linked lists maintained by this library. \index{dbprim_link@{dbprim\_\-link}!link_iter_t@{link\_\-iter\_\-t}}
 331 \index{link_iter_t@{link\_\-iter\_\-t}!dbprim_link@{dbprim\_\-link}}
 332 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long($\ast$ link\_\-iter\_\-t)({\bf link\_\-head\_\-t} $\ast$, {\bf link\_\-elem\_\-t} $\ast$, void $\ast$)}\label{group__dbprim__link_a2}
 333
 334
 335
 336
 337  This function pointer references a callback used by {\bf ll\_\-iter}() {\rm (p.\,\pageref{group__dbprim__link_a10})} and {\bf ll\_\-flush}() {\rm (p.\,\pageref{group__dbprim__link_a11})}. It should return 0 for success. A non-zero return value will terminate the operation and will become the return value of the {\bf ll\_\-iter}() {\rm (p.\,\pageref{group__dbprim__link_a10})} or {\bf ll\_\-flush}() {\rm (p.\,\pageref{group__dbprim__link_a11})} call. \index{dbprim_link@{dbprim\_\-link}!link_loc_t@{link\_\-loc\_\-t}}
 338 \index{link_loc_t@{link\_\-loc\_\-t}!dbprim_link@{dbprim\_\-link}}
 339 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef enum {\bf \_\-link\_\-loc\_\-e} link\_\-loc\_\-t}\label{group__dbprim__link_a4}
 340
 341
 342
 343
 344  See the documentation for the enumeration {\bf \_\-link\_\-loc\_\-e} {\rm (p.\,\pageref{group__dbprim__link_a26})}.
 345
 346 \subsection{Enumeration Type Documentation}
 347 \index{dbprim_link@{dbprim\_\-link}!_link_loc_e@{\_\-link\_\-loc\_\-e}}
 348 \index{_link_loc_e@{\_\-link\_\-loc\_\-e}!dbprim_link@{dbprim\_\-link}}
 349 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum \_\-link\_\-loc\_\-e}\label{group__dbprim__link_a26}
 350
 351
 352
 353
 354  This enumeration is used to specify where an element in a linked list should be placed. It should be referenced by the typedef {\bf link\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a4})}. \begin{Desc}
 355 \item[{\bf Enumeration values:}]\par
 356 \begin{description}
 357 \index{LINK_LOC_HEAD@{LINK\_\-LOC\_\-HEAD}!dbprim_link@{dbprim\_\-link}}\index{dbprim_link@{dbprim\_\-link}!LINK_LOC_HEAD@{LINK\_\-LOC\_\-HEAD}}\item[
 358 {\em LINK\_\-LOC\_\-HEAD}\label{group__dbprim__link_a26a98}
 359 ]Element should be inserted at head of list. \index{LINK_LOC_TAIL@{LINK\_\-LOC\_\-TAIL}!dbprim_link@{dbprim\_\-link}}\index{dbprim_link@{dbprim\_\-link}!LINK_LOC_TAIL@{LINK\_\-LOC\_\-TAIL}}\item[
 360 {\em LINK\_\-LOC\_\-TAIL}\label{group__dbprim__link_a26a99}
 361 ]Element should be inserted at tail of list. \index{LINK_LOC_BEFORE@{LINK\_\-LOC\_\-BEFORE}!dbprim_link@{dbprim\_\-link}}\index{dbprim_link@{dbprim\_\-link}!LINK_LOC_BEFORE@{LINK\_\-LOC\_\-BEFORE}}\item[
 362 {\em LINK\_\-LOC\_\-BEFORE}\label{group__dbprim__link_a26a100}
 363 ]Element should be inserted before specified element. \index{LINK_LOC_AFTER@{LINK\_\-LOC\_\-AFTER}!dbprim_link@{dbprim\_\-link}}\index{dbprim_link@{dbprim\_\-link}!LINK_LOC_AFTER@{LINK\_\-LOC\_\-AFTER}}\item[
 364 {\em LINK\_\-LOC\_\-AFTER}\label{group__dbprim__link_a26a101}
 365 ]Element should be inserted after specified element. \end{description}
 366 \end{Desc}
 367
 368
 369
 370 \subsection{Function Documentation}
 371 \index{dbprim_link@{dbprim\_\-link}!le_init@{le\_\-init}}
 372 \index{le_init@{le\_\-init}!dbprim_link@{dbprim\_\-link}}
 373 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long le\_\-init ({\bf link\_\-elem\_\-t} $\ast$ {\em elem}, void $\ast$ {\em object})}\label{group__dbprim__link_a12}
 374
 375
 376
 377
 378  This function dynamically initializes a linked list element.\begin{Desc}
 379 \item[{\bf Parameters: }]\par
 380 \begin{description}
 381 \item[
 382 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} to be initialized. \item[
 383 {\em object}]A pointer to {\tt void} used to represent the object associated with the element. May not be {\tt NULL}.\end{description}
 384 \end{Desc}
 385 \begin{Desc}
 386 \item[{\bf Return values: }]\par
 387 \begin{description}
 388 \item[
 389 {\em DB\_\-ERR\_\-BADARGS}]A {\tt NULL} pointer was passed for {\tt elem} or {\tt object}. \end{description}
 390 \end{Desc}
 391 \index{dbprim_link@{dbprim\_\-link}!ll_add@{ll\_\-add}}
 392 \index{ll_add@{ll\_\-add}!dbprim_link@{dbprim\_\-link}}
 393 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-add ({\bf link\_\-head\_\-t} $\ast$ {\em list}, {\bf link\_\-elem\_\-t} $\ast$ {\em new}, {\bf link\_\-loc\_\-t} {\em loc}, {\bf link\_\-elem\_\-t} $\ast$ {\em elem})}\label{group__dbprim__link_a6}
 394
 395
 396
 397
 398  This function adds a given element to a specified linked list in the specified location.\begin{Desc}
 399 \item[{\bf Parameters: }]\par
 400 \begin{description}
 401 \item[
 402 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}. \item[
 403 {\em new}]A pointer to the {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} to be added to the linked list. \item[
 404 {\em loc}]A {\bf link\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a4})} indicating where the entry should be added. \item[
 405 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} describing another element in the list if {\tt loc} is {\bf LINK\_\-LOC\_\-BEFORE} {\rm (p.\,\pageref{group__dbprim__link_a26a100})} or {\bf LINK\_\-LOC\_\-AFTER} {\rm (p.\,\pageref{group__dbprim__link_a26a101})}.\end{description}
 406 \end{Desc}
 407 \begin{Desc}
 408 \item[{\bf Return values: }]\par
 409 \begin{description}
 410 \item[
 411 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 412 {\em DB\_\-ERR\_\-BUSY}]The element is already in a list. \item[
 413 {\em DB\_\-ERR\_\-WRONGTABLE}]{\tt elem} is in a different list. \item[
 414 {\em DB\_\-ERR\_\-UNUSED}]{\tt elem} is not in any list. \end{description}
 415 \end{Desc}
 416 \index{dbprim_link@{dbprim\_\-link}!ll_find@{ll\_\-find}}
 417 \index{ll_find@{ll\_\-find}!dbprim_link@{dbprim\_\-link}}
 418 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-find ({\bf link\_\-head\_\-t} $\ast$ {\em list}, {\bf link\_\-elem\_\-t} $\ast$$\ast$ {\em elem\_\-p}, {\bf link\_\-comp\_\-t} {\em comp\_\-func}, {\bf link\_\-elem\_\-t} $\ast$ {\em start}, {\bf db\_\-key\_\-t} $\ast$ {\em key})}\label{group__dbprim__link_a9}
 419
 420
 421
 422
 423  This function iterates through a linked list looking for an element that matches the given {\tt key}.\begin{Desc}
 424 \item[{\bf Parameters: }]\par
 425 \begin{description}
 426 \item[
 427 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}. \item[
 428 {\em elem\_\-p}]A pointer to a pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}. This is a result parameter. {\tt NULL} is an invalid value. \item[
 429 {\em comp\_\-func}]A pointer to a comparison function used to compare the key to a particular element. See the documentation for {\bf link\_\-comp\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a3})} for more information. \item[
 430 {\em start}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} describing where in the linked list to start. If {\tt NULL} is passed, the beginning of the list will be assumed. \item[
 431 {\em key}]A key to search for.\end{description}
 432 \end{Desc}
 433 \begin{Desc}
 434 \item[{\bf Return values: }]\par
 435 \begin{description}
 436 \item[
 437 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 438 {\em DB\_\-ERR\_\-WRONGTABLE}]{\tt start} is not in this linked list. \item[
 439 {\em DB\_\-ERR\_\-NOENTRY}]No matching entry was found. \end{description}
 440 \end{Desc}
 441 \index{dbprim_link@{dbprim\_\-link}!ll_flush@{ll\_\-flush}}
 442 \index{ll_flush@{ll\_\-flush}!dbprim_link@{dbprim\_\-link}}
 443 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-flush ({\bf link\_\-head\_\-t} $\ast$ {\em list}, {\bf link\_\-iter\_\-t} {\em flush\_\-func}, void $\ast$ {\em extra})}\label{group__dbprim__link_a11}
 444
 445
 446
 447
 448  This function flushes a linked list--that is, it removes each element from the list. If a {\tt flush\_\-func} is specified, it will be called on the entry after it has been removed from the list, and may safely call {\tt free()}.\begin{Desc}
 449 \item[{\bf Parameters: }]\par
 450 \begin{description}
 451 \item[
 452 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}. \item[
 453 {\em flush\_\-func}]A pointer to a callback function used to perform user-specified actions on an element after removing it from the list. May be {\tt NULL}. See the documentation for {\bf link\_\-iter\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a2})} for more information. \item[
 454 {\em extra}]A {\tt void} pointer that will be passed to {\tt flush\_\-func}.\end{description}
 455 \end{Desc}
 456 \begin{Desc}
 457 \item[{\bf Return values: }]\par
 458 \begin{description}
 459 \item[
 460 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \end{description}
 461 \end{Desc}
 462 \index{dbprim_link@{dbprim\_\-link}!ll_init@{ll\_\-init}}
 463 \index{ll_init@{ll\_\-init}!dbprim_link@{dbprim\_\-link}}
 464 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-init ({\bf link\_\-head\_\-t} $\ast$ {\em list}, void $\ast$ {\em extra})}\label{group__dbprim__link_a5}
 465
 466
 467
 468
 469  This function dynamically initializes a linked list head.\begin{Desc}
 470 \item[{\bf Parameters: }]\par
 471 \begin{description}
 472 \item[
 473 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})} to be initialized. \item[
 474 {\em extra}]A pointer to {\tt void} containing extra pointer data associated with the linked list.\end{description}
 475 \end{Desc}
 476 \begin{Desc}
 477 \item[{\bf Return values: }]\par
 478 \begin{description}
 479 \item[
 480 {\em DB\_\-ERR\_\-BADARGS}]A {\tt NULL} pointer was passed for {\tt list}. \end{description}
 481 \end{Desc}
 482 \index{dbprim_link@{dbprim\_\-link}!ll_iter@{ll\_\-iter}}
 483 \index{ll_iter@{ll\_\-iter}!dbprim_link@{dbprim\_\-link}}
 484 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-iter ({\bf link\_\-head\_\-t} $\ast$ {\em list}, {\bf link\_\-iter\_\-t} {\em iter\_\-func}, void $\ast$ {\em extra})}\label{group__dbprim__link_a10}
 485
 486
 487
 488
 489  This function iterates over a linked list, executing the given {\tt iter\_\-func} for each entry.\begin{Desc}
 490 \item[{\bf Parameters: }]\par
 491 \begin{description}
 492 \item[
 493 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}. \item[
 494 {\em iter\_\-func}]A pointer to a callback function used to perform user-specified actions on an element in a linked list. {\tt NULL} is an invalid value. See the documentation for {\bf link\_\-iter\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a2})} for more information. \item[
 495 {\em extra}]A {\tt void} pointer that will be passed to {\tt iter\_\-func}.\end{description}
 496 \end{Desc}
 497 \begin{Desc}
 498 \item[{\bf Return values: }]\par
 499 \begin{description}
 500 \item[
 501 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \end{description}
 502 \end{Desc}
 503 \index{dbprim_link@{dbprim\_\-link}!ll_move@{ll\_\-move}}
 504 \index{ll_move@{ll\_\-move}!dbprim_link@{dbprim\_\-link}}
 505 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-move ({\bf link\_\-head\_\-t} $\ast$ {\em list}, {\bf link\_\-elem\_\-t} $\ast$ {\em elem}, {\bf link\_\-loc\_\-t} {\em loc}, {\bf link\_\-elem\_\-t} $\ast$ {\em elem2})}\label{group__dbprim__link_a7}
 506
 507
 508
 509
 510  This function moves a specified element within the linked list.\begin{Desc}
 511 \item[{\bf Parameters: }]\par
 512 \begin{description}
 513 \item[
 514 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}. \item[
 515 {\em elem}]A pointer to the {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} describing the element to be moved. \item[
 516 {\em loc}]A {\bf link\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a4})} indicating where the entry should be moved to. \item[
 517 {\em elem2}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} describing another element in the list if {\tt loc} is {\bf LINK\_\-LOC\_\-BEFORE} {\rm (p.\,\pageref{group__dbprim__link_a26a100})} or {\bf LINK\_\-LOC\_\-AFTER} {\rm (p.\,\pageref{group__dbprim__link_a26a101})}.\end{description}
 518 \end{Desc}
 519 \begin{Desc}
 520 \item[{\bf Return values: }]\par
 521 \begin{description}
 522 \item[
 523 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 524 {\em DB\_\-ERR\_\-BUSY}]{\tt elem} and {\tt elem2} are the same element. \item[
 525 {\em DB\_\-ERR\_\-WRONGTABLE}]{\tt elem} or {\tt elem2} are in a different list. \item[
 526 {\em DB\_\-ERR\_\-UNUSED}]{\tt elem} or {\tt elem2} are not in any list. \end{description}
 527 \end{Desc}
 528 \index{dbprim_link@{dbprim\_\-link}!ll_remove@{ll\_\-remove}}
 529 \index{ll_remove@{ll\_\-remove}!dbprim_link@{dbprim\_\-link}}
 530 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long ll\_\-remove ({\bf link\_\-head\_\-t} $\ast$ {\em list}, {\bf link\_\-elem\_\-t} $\ast$ {\em elem})}\label{group__dbprim__link_a8}
 531
 532
 533
 534
 535  This function removes a specified element from a linked list.\begin{Desc}
 536 \item[{\bf Parameters: }]\par
 537 \begin{description}
 538 \item[
 539 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}. \item[
 540 {\em elem}]A pointer to the {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} describing the element to be removed.\end{description}
 541 \end{Desc}
 542 \begin{Desc}
 543 \item[{\bf Return values: }]\par
 544 \begin{description}
 545 \item[
 546 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 547 {\em DB\_\-ERR\_\-UNUSED}]{\tt elem} is not in a linked list. \item[
 548 {\em DB\_\-ERR\_\-WRONGTABLE}]{\tt elem} is not in this linked list. \end{description}
 549 \end{Desc}