ALL_LIST(3) LAM INTERNALS ALL_LIST(3)NAME
all_list, all_slist - general purpose list management package (LAM)
SYNOPSIS
#include <all_list.h>
LIST *al_init (int elemsize, int (*comp)());
int al_delete (LIST *ald, void *old);
void *al_insert (LIST *ald, void *unew);
void *al_append (LIST *ald, void *unew);
int al_free (LIST *ald);
void *al_find (LIST *ald, void *key);
void *al_next (LIST *ald, void *old);
void *al_prev (LIST *ald, void *old);
int al_count (LIST *ald);
void *al_top (LIST *ald);
void *al_bottom (LIST *ald);
#include <all_slist.h>
SLIST *als_init (int elemsize, int (*comp)(), int nlist,
char *plist, SLIST *pdesc);
int als_delete (SLIST *ald, void *old);
void *als_insert (SLIST *ald, void *unew);
void *als_append (SLIST *ald, void *unew);
void *als_find (SLIST *ald, void *key);
void *als_next (SLIST *ald, void *old);
void *als_prev (SLIST *ald, void *old);
int als_count (SLIST *ald);
void *als_top (LIST *ald);
void *als_bottom (LIST *ald);
DESCRIPTION
The all_list and all_slist packages provide general purpose list man‐
agement. They differ only in the way memory is allocated for a list.
The dynamic package, all_list, obtains memory from malloc(3) whenever a
new element is inserted into a list and returns memory with free(3)
whenever an element is deleted from a list. The static package,
all_slist, requires that the caller provide memory for the maximum num‐
ber of list elements when the list is first created. Functions that
operate on a dynamic list are named al_* and functions that operate on
a static list are named als_*.
A list is created and initialized with the al_init() or als_init()
functions which both return a pointer to a list descriptor, typedef
LIST or SLIST respectively. The list descriptor pointer is used in all
subsequent list functions. In the static function, als_init(), the
caller supplies space not only for the maximum number of list elements,
but for the list descriptor also. A dynamic list is freed with the
al_free() function. A static list is simply forgotten, since the call‐
er is responsible for all the memory involved. Allocating the space
for a static list is a bit tricky since each element must contain the
caller's structure and the list management overhead structure. An
example of how to allocate space for a static list is given below:
char *mylist[25 * (sizeof(struct al_head) +
sizeof(myelement))];
Twenty-five elements of type myelement are allocated and named mylist.
Other than this space allocation, the caller never sees the al_head
structure. Element pointers always point to the caller's element type.
Dynamic List Operators
The following functions operate on dynamic lists:
al_init() Allocate and initialize a list. A list descriptor
pointer is returned, but the null pointer is returned if
allocation failed. The caller supplies a pointer to a
function that will compare two list elements, given
pointers to each. The comparison function must return 0
if the elements are equal, -1 if the first element is
less than the second, and 1 if the first element is
greater than the second.
al_delete() Delete an existing element from a list. The function
returns -1 and sets errno to EDELETE if the element
could not be found in the given list.
al_insert() Insert a new element into a list. The caller prepares
and supplies a pointer to the new element. The function
allocates its own element to actually insert into the
list and copies the contents of the caller supplied ele‐
ment. The caller can reuse the element. al_insert()
returns a pointer to an internally allocated list ele‐
ment.
al_append() This function is identical to al_insert() except that
the new element is always placed at the end of the list.
al_free() Free all elements in a list and free the list descrip‐
tor. The list is effectively blown away. The list
descriptor pointer is no longer valid. This function
always returns 0.
al_find() Find an existing list element. The caller prepares a
search key element, filling in only the key fields
needed by the compare function to identify an element.
A pointer to the found element is returned, or the null
pointer if the element is not found.
al_next() The caller gives a pointer to an existing list element
and a pointer to the next element in the list is
returned. This pointer may be null if the supplied ele‐
ment is the last element in the list.
al_prev() The caller gives a pointer to an existing list element
and a pointer to the previous element in the list is
returned. This pointer may be null if the supplied ele‐
ment is the first element in the list.
al_count() A count of all elements in a given list is returned.
al_top() Return a pointer to the first element in the list. The
is pointer may be null if the list is empty.
al_bottom() Return a pointer to the last element in the list. The
is pointer may be null if the list is empty.
Static List Operators
The static list functions are very similar. The differences are listed
below.
als_insert() This function returns the null pointer and sets errno to
EFULL if there are no free elements available.
als_append() The same is true for this function.
als_free() This function does not exist.
SEE ALSOall_hash(3), all_queue(3)LAM 7.1.2 March, 2006 ALL_LIST(3)
