    NAME
         lCreateList,  lFreeList,  lCopyList,  lAddList,  lPSortList,
         lDumpList,  lUndumpList, lWriteList, lWriteListTo, lGetList-
         Name, 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  associ-
              ated 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, oth-
              erwise 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 argu-
              ment 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 Monitor-
              ing  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 speci-
              fied' 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 ele-
              ment.

    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
              Malloc(3) failed. (lCreateList, lUndumpList)

         LESTRDUP
              Strdup(3) 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, lUn-
              dumpList)

         LEDIFFDESCR
              Unequal descriptors specified. (lAddList)

         LEDECHAINELEM
              lDechainElem failed. (lAddList, lPSortList)

         LENOFORMATSTR
              No format string specified. (lPSortList)

         LEPARSESORTORD
              Parsing the sort order format string  failed.  (lPSort-
              List)

         LEGETNROFELEM
              Getting number of list elements failed. (lPSortList)

         LEFILENULL
              File pointer to dump file is NULL. (lDumpList,  lUndum-
              pList)

         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
         sge_intro(1), list_intro(3).

    COPYRIGHT
         See sge_intro(1) for a full statement of rights and  permis-
         sions.