LIST_FUNCS(3)

NAME
lCreateList, lFreeList, lCopyList, lAddList, lPSortList, lDumpList, lUndumpList, lWriteList, lWriteListTo, lGetListName, lGetListDescr, lGetNumberOfElem

generic list manipulation and information functions

SYNOPSIS
#include "cull.h"

lList* lCreateList( char *listname, lDescr *descriptor );

lList* lCreateElemList( char *listname, lDescr *descriptor, int n );

lList* lFreeList( lList *list );

lList* lCopyList( char *listname, lList *list );

void lAddList( lList *list1, lList *list2 );

int lPSortList( lList *list, char *orderstring, ... );

int lDumpList( FILE *file, lList *list, int indent );

lList* lUndumpList(
    FILE *file,
    char *newname,
    lDescr *descriptor
);

void lWriteList( lList *list );

void lWriteListTo( lList *list, FILE *fp );

char* lGetListName( lList *list );

lDescr* lGetListDescr( lList *list );

int lGetNumberOfElem( lList *list );

int lGetNumberOfRemainingElem( lListElem *elem );

DESCRIPTION

lCreateList
    gets the new name of the list to be created and its descriptor which enumerates the fields (name,type), that a list element will contain. The memory for the list is dynamically created and a pointer to the newly created list is returned. If one of the arguments is NULL or if the descriptor contains no fields the return value of lCreateList is NULL. This is also true for any error that might occur. The list must be freed with lFreeList when the list is no longer used (all associated sub-lists and strings are also freed).

lCreateElemList
    gets the new name of the list to be created and its descriptor which enumerates the fields (name,type), that a list element will contain. The third argument specifies the number of elements that shall be created. The memory for the list is dynamically created and a pointer to the newly created list is returned. If one of the arguments is NULL, if the descriptor contains no fields or if creation of all requested elements fails the return value of lCreateElemList is NULL. This is also true for any error that might occur. The list must be freed with lFreeList when the list is no longer used (all associated sub-lists and strings are also freed).

lFreeList
    gets as argument a pointer to a generic list. If the list pointer is NULL the function simply returns, otherwise the list, all its sub-lists and its strings are freed.

lCopyList
    copies an existing generic list with all its sub-lists. The required memory is allocated by lCopyList and must be released via lFreeList if the copied list is no longer used. The first argument to lCopyList is the name of the copied list, the second argument is an existing list. In case of success a pointer to the copied list is returned. Otherwise the return value is NULL.

lAddList
    concatenates two generic lists. The first argument is the list which is expanded. The second argument is the list that is added to the first list. The descriptors of both lists have to be equal. After appending the elements of the second list to the first list, the second list gets destroyed.

lPSortList
    sorts a given list corresponding to a given sort order. The first argument is the generic list to be sorted, the second argument is the sort order string and the following variable argument list specifies the fields which act as sorting keys. lPSortList returns -1 in case of error, 0 otherwise.
    The sort order string has the following syntax:

        sort order string = %I{+|-} [%I{+|-}...]

    %I stands for the field and +/- stands for ascending/descending sorting order
    for every percent sign there is one 'fieldname' in the variable argument list, %I stands for the field and +/- stands for ascending/descending sorting order.

    The following example may show the usage:

        lPSortList( list, "%I+ %I-", field1, field2 );

lDumpList
    writes a generic list and all its sub-lists to a file. The first argument is a FILE pointer, the second argument is a generic list pointer and the third argument is the number of indentation units for the lines in the list file (for better readability).

lUndumpList
    read a dumped list and all its sub-lists from a dump file. The first argument is the FILE pointer of the dump file. The second argument is the program internal name of the read in list or the name of the list in the dump file if NULL is specified. The third argument is the descriptor of the new list or the list descriptor stored in the dump file if NULL is specified. If the new list descriptor is a subset of the descriptor in the dump file the obsolete fields are skipped and a warning message is displayed. If additional fields occur in the new descriptor they remain unchanged (i.e. they keep their creation time value). If lUndumpList is successful, a generic list is created and the list pointer is returned. Otherwise the return value is NULL.

lWriteList
    writes a generic list and all its sub-lists if Monitoring Level CULL_LAYER is set to info. The generic list pointer is the only function argument. If the list pointer is NULL the function displays a warning and returns.

lWriteListTo
    writes a generic list and all its sub-lists to the stream connected with fp. The generic list pointer is the first function argument. The second argument is the file pointer. If the file pointer is NULL, the function behaves as "lWriteList".

lGetListName
    returns the name of the specified generic list. If the function argument is NULL, the string 'No List specified' is returned.

lGetListDescr
    returns the list descriptor of the specified list or NULL if a NULL if the argument is NULL.

lGetNumberOfElem
    gets the number of list elements actually contained in the generic list specified as function argument. If the generic list pointer is NULL, -1 is returned, the number of list elements is returned otherwise.

lGetNumberOfRemainingElem
    returns the number of list elements contained in the remainder of a generic list after a specified list element.

RETURN VALUES
In case of error the return value is -1 or NULL, otherwise 0 or a valid pointer to the corresponding struct is returned.

ERRORS
The following errors may occur. The affected functions are listed in parentheses.

LENOLISTNAME
    No list name specified. (lCreateList)

LEDESCRNULL
    List descriptor is NULL. (lCreateList)

LEMALLOC
    failed. (lCreateList, lUndumpList)

LESTRDUP
    failed. (lCreateList)

LECOUNTDESCR
    Counting the descriptor length failed. (lCreateList, lAddList, lUndumpList)

LELISTNULL
    List pointer is NULL. (lFreeList, lCopyList, lAddList, lPSortList, lWriteList, lGetListName, lGetListDescr, lGetNumberOfElem, lDumpList)

LECREATELIST
    Creation of a new list failed. (lCopyList, lPSortList, lUndumpList)

LEAPPENDELEM
    lAppendElem function failed. (lCopyList, lAddList, lUndumpList)

LEDIFFDESCR
    Unequal descriptors specified. (lAddList)

LEDECHAINELEM
    lDechainElem failed. (lAddList, lPSortList)

LENOFORMATSTR
    No format string specified. (lPSortList)

LEPARSESORTORD
    Parsing the sort order format string failed. (lPSortList)

LEGETNROFELEM
    Getting number of list elements failed. (lPSortList)

LEFILENULL
    File pointer to dump file is NULL. (lDumpList, lUndumpList)

LESYNTAX
    A syntax error occurred. (lUndumpList)

LEFIELDREAD
    Reading a field value failed. (lUndumpList)

LEFGETDESCR
    lUndumpDescr failed. (lUndumpList)

LEUNDUMPELEM
    lUndumpElem failed. (lUndumpList)

LECREATEELEM
    lCreateElem failed. (lUndumpList)

LECOPYSWITCH
    Copying list element fields failed. (lUndumpList)

SEE ALSO

COPYRIGHT
See for a full statement of rights and permissions.