Linux Certif

Toute la documentation sur la certification Linux LPI

all_list

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 management. 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 number 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 caller 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 element. The caller can reuse the element. al_insert() returns a pointer to an internally allocated list element.

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 descriptor. 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 element 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 element 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 ALSO

all_hash(3), all_queue(3)