2 \label{group__dbprim__link}\index{Linked lists@{Linked lists}}
3 Operations for linked lists.
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}
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}
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}
54 \begin{CompactList}\small\item\em Linked list location.\item\end{CompactList}\end{CompactItemize}
55 \subsection*{Functions}
56 \begin{CompactItemize}
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}
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.
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.
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}
89 This macro statically initializes a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.\begin{Desc}
90 \item[{\bf Parameters: }]\par
93 {\em obj}]A pointer to {\tt void} representing the object associated with the element. \end{description}
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}
102 This macro statically initializes a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.\begin{Desc}
103 \item[{\bf Parameters: }]\par
106 {\em extra}]Extra pointer data that should be associated with the list head. \end{description}
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}
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
119 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
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}
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
137 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
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}
151 This macro retrieves a pointer to the next element in the linked list.\begin{Desc}
152 \item[{\bf Parameters: }]\par
155 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
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}
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
173 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
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}
187 This macro retrieves a pointer to the previous element in the linked list.\begin{Desc}
188 \item[{\bf Parameters: }]\par
191 {\em elem}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
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}
205 This macro verifies that a given pointer actually does point to a linked list element.\begin{Desc}
206 \item[{\bf Parameters: }]\par
209 {\em element}]A pointer to a {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})}.
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}
223 This macro retrieves the number of elements in a linked list.\begin{Desc}
224 \item[{\bf Parameters: }]\par
227 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
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}
241 This macro retrieves the extra pointer data associated with a particular linked list.\begin{Desc}
242 \item[{\bf Parameters: }]\par
245 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
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}
259 This macro retrieves the first element in a linked list.\begin{Desc}
260 \item[{\bf Parameters: }]\par
263 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
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}
277 This macro retrieves the last element in a linked list.\begin{Desc}
278 \item[{\bf Parameters: }]\par
281 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
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}
295 This macro verifies that a given pointer actually does point to a linked list head.\begin{Desc}
296 \item[{\bf Parameters: }]\par
299 {\em list}]A pointer to a {\bf link\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a0})}.
304 \item[{\bf Returns: }]\par
305 Boolean true if {\tt list} is a valid linked list head or false otherwise. \end{Desc}
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}
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}
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}
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}
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}
344 See the documentation for the enumeration {\bf \_\-link\_\-loc\_\-e} {\rm (p.\,\pageref{group__dbprim__link_a26})}.
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}
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
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}
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}
378 This function dynamically initializes a linked list element.\begin{Desc}
379 \item[{\bf Parameters: }]\par
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}
386 \item[{\bf Return values: }]\par
389 {\em DB\_\-ERR\_\-BADARGS}]A {\tt NULL} pointer was passed for {\tt elem} or {\tt object}. \end{description}
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}
398 This function adds a given element to a specified linked list in the specified location.\begin{Desc}
399 \item[{\bf Parameters: }]\par
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}
408 \item[{\bf Return values: }]\par
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}
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}
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
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}
434 \item[{\bf Return values: }]\par
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}
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}
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
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}
457 \item[{\bf Return values: }]\par
460 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \end{description}
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}
469 This function dynamically initializes a linked list head.\begin{Desc}
470 \item[{\bf Parameters: }]\par
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}
477 \item[{\bf Return values: }]\par
480 {\em DB\_\-ERR\_\-BADARGS}]A {\tt NULL} pointer was passed for {\tt list}. \end{description}
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}
489 This function iterates over a linked list, executing the given {\tt iter\_\-func} for each entry.\begin{Desc}
490 \item[{\bf Parameters: }]\par
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}
498 \item[{\bf Return values: }]\par
501 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \end{description}
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}
510 This function moves a specified element within the linked list.\begin{Desc}
511 \item[{\bf Parameters: }]\par
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}
520 \item[{\bf Return values: }]\par
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}
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}
535 This function removes a specified element from a linked list.\begin{Desc}
536 \item[{\bf Parameters: }]\par
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}
543 \item[{\bf Return values: }]\par
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}