libtar_list_new(3)						  C Library Calls						libtar_list_new(3)

NAME

       libtar_list_new,   libtar_list_free,   libtar_list_next,   libtar_list_prev,  libtar_list_add,  libtar_list_del,  libtar_list_search,  lib-
       tar_list_dup, libtar_list_merge, libtar_list_add_str - linked list routines

SYNOPSIS

       #include <libtar.h>

       libtar_list_t *libtar_list_new(int flags, int (*cmpfunc)());
       void libtar_list_free(libtar_list_t *l, void (*freefunc)());
       int libtar_list_add_str(libtar_list_t *l, char *str, char *delim);
       int libtar_list_add(libtar_list_t *l, void *data);
       void libtar_list_del(libtar_list_t *l, libtar_node_t **n);
       int libtar_list_search(libtar_list_t *l, libtar_node_t **n, void *data, int (*matchfunc)());
       int libtar_list_next(libtar_list_t *l, libtar_node_t **n);
       int libtar_list_prev(libtar_list_t *l, libtar_node_t **n);
       libtar_list_t *libtar_list_dup(libtar_list_t *l);
       libtar_list_t *libtar_list_merge(int (*cmpfunc)(), int flags, libtar_list_t *list1, libtar_list_t *list2);

DESCRIPTION

       The libtar_list_new() function creates a new list.  The flags argument must be one of the following values:

       LIST_USERFUNC
	      The cmpfunc argument points to a user-supplied function which determines the ordering of the list.

       LIST_STACK
	      Use the list as a stack.	New elements are added to the front of the list.

       LIST_QUEUE
	      Use the list as a queue.	New elements are added to the end of the list.

       The libtar_list_free() function deallocates all memory associated with the list l.  If freefunc is not NULL, it is called  to  free  memory
       associated with each node in the list.

       The  libtar_list_add()  function  adds the element pointed to by data to the list l.  The position of the new element will be determined by
       the flags passed to libtar_list_new() when the list was created.

       The libtar_list_add_str() function tokenizes the string str using the delimiter characters in the string delim.	The resulting  tokens  are
       added to list l using libtar_list_add().

       The  libtar_list_search() function searches for an element which matches data using the matching function matchfunc.  If matchfunc is NULL,
       a default matching function designed for ASCII strings is used.	Searching begins from the node pointed to by n.

       The libtar_list_del() function removes the entry pointed to by n from the list pointed to by l.

       The libtar_list_dup() function creates a copy of the list l using dynamically allocated memory.

       The libtar_list_merge() function creates a new list with flags and cmpfunc, in the same way as libtar_list_new().  It then  adds  all  ele-
       ments from list1 and list2 using libtar_list_add().

RETURN VALUE

       The libtar_list_new(), libtar_list_dup(), and libtar_list_merge() functions return a pointer to the new list structure, or NULL on error.

       The libtar_list_next(), libtar_list_prev(), and libtar_list_search() functions return 1 when valid data is returned, or 0 otherwise.

       The libtar_list_add() and libtar_list_add_str() functions return 0 on success, or -1 on error.

SEE ALSO

       libtar_hash_new(3)

University of Illinois						     Jan 2000							libtar_list_new(3)