1ALL_LIST(3) LAM INTERNALS ALL_LIST(3)
2
6 all_list, all_slist - general purpose list management package (LAM)
7
9 #include <all_list.h>
10 LIST *al_init (int elemsize, int (*comp)());
12 int al_delete (LIST *ald, void *old);
13 void *al_insert (LIST *ald, void *unew);
14 void *al_append (LIST *ald, void *unew);
15 int al_free (LIST *ald);
16 void *al_find (LIST *ald, void *key);
17 void *al_next (LIST *ald, void *old);
18 void *al_prev (LIST *ald, void *old);
19 int al_count (LIST *ald);
20 void *al_top (LIST *ald);
21 void *al_bottom (LIST *ald);
22 #include <all_slist.h>
24 SLIST *als_init (int elemsize, int (*comp)(), int nlist,
26 char *plist, SLIST *pdesc);
27 int als_delete (SLIST *ald, void *old);
28 void *als_insert (SLIST *ald, void *unew);
29 void *als_append (SLIST *ald, void *unew);
30 void *als_find (SLIST *ald, void *key);
31 void *als_next (SLIST *ald, void *old);
32 void *als_prev (SLIST *ald, void *old);
33 int als_count (SLIST *ald);
34 void *als_top (LIST *ald);
35 void *als_bottom (LIST *ald);
36
38 The all_list and all_slist packages provide general purpose list man‐
39 agement. They differ only in the way memory is allocated for a list.
40 The dynamic package, all_list, obtains memory from malloc(3) whenever a
41 new element is inserted into a list and returns memory with free(3)
42 whenever an element is deleted from a list. The static package,
43 all_slist, requires that the caller provide memory for the maximum num‐
44 ber of list elements when the list is first created. Functions that
45 operate on a dynamic list are named al_* and functions that operate on
46 a static list are named als_*.
47 A list is created and initialized with the al_init() or als_init()
49 functions which both return a pointer to a list descriptor, typedef
50 LIST or SLIST respectively. The list descriptor pointer is used in all
51 subsequent list functions. In the static function, als_init(), the
52 caller supplies space not only for the maximum number of list elements,
53 but for the list descriptor also. A dynamic list is freed with the
54 al_free() function. A static list is simply forgotten, since the call‐
55 er is responsible for all the memory involved. Allocating the space
56 for a static list is a bit tricky since each element must contain the
57 caller's structure and the list management overhead structure. An
58 example of how to allocate space for a static list is given below:
59 char *mylist[25 * (sizeof(struct al_head) +
61 sizeof(myelement))];
62 Twenty-five elements of type myelement are allocated and named mylist.
64 Other than this space allocation, the caller never sees the al_head
65 structure. Element pointers always point to the caller's element type.
66 Dynamic List Operators
68 The following functions operate on dynamic lists:
69 al_init() Allocate and initialize a list. A list descriptor
71 pointer is returned, but the null pointer is returned if
72 allocation failed. The caller supplies a pointer to a
73 function that will compare two list elements, given
74 pointers to each. The comparison function must return 0
75 if the elements are equal, -1 if the first element is
76 less than the second, and 1 if the first element is
77 greater than the second.
78 al_delete() Delete an existing element from a list. The function
80 returns -1 and sets errno to EDELETE if the element
81 could not be found in the given list.
82 al_insert() Insert a new element into a list. The caller prepares
84 and supplies a pointer to the new element. The function
85 allocates its own element to actually insert into the
86 list and copies the contents of the caller supplied ele‐
87 ment. The caller can reuse the element. al_insert()
88 returns a pointer to an internally allocated list ele‐
89 ment.
90 al_append() This function is identical to al_insert() except that
92 the new element is always placed at the end of the list.
93 al_free() Free all elements in a list and free the list descrip‐
95 tor. The list is effectively blown away. The list
96 descriptor pointer is no longer valid. This function
97 always returns 0.
98 al_find() Find an existing list element. The caller prepares a
100 search key element, filling in only the key fields
101 needed by the compare function to identify an element.
102 A pointer to the found element is returned, or the null
103 pointer if the element is not found.
104 al_next() The caller gives a pointer to an existing list element
106 and a pointer to the next element in the list is
107 returned. This pointer may be null if the supplied ele‐
108 ment is the last element in the list.
109 al_prev() The caller gives a pointer to an existing list element
111 and a pointer to the previous element in the list is
112 returned. This pointer may be null if the supplied ele‐
113 ment is the first element in the list.
114 al_count() A count of all elements in a given list is returned.
116 al_top() Return a pointer to the first element in the list. The
118 is pointer may be null if the list is empty.
119 al_bottom() Return a pointer to the last element in the list. The
121 is pointer may be null if the list is empty.
122 Static List Operators
124 The static list functions are very similar. The differences are listed
125 below.
126 als_insert() This function returns the null pointer and sets errno to
128 EFULL if there are no free elements available.
129 als_append() The same is true for this function.
131 als_free() This function does not exist.
133
135 all_hash(3), all_queue(3)
136LAM 7.1.2 March, 2006 ALL_LIST(3)