.TH libtar_list_new 3 "Jan 2000" "University of Illinois" "C Library Calls"
\" listhash/libtar_list_new.3.  Generated from list_new.3.in by configure.
.SH NAME
libtar_list_new, libtar_list_free, libtar_list_next,
libtar_list_prev, libtar_list_add, libtar_list_del,
libtar_list_search, libtar_list_dup, libtar_list_merge,
libtar_list_add_str \- linked list routines
.SH SYNOPSIS
.B #include <libtar.h>
.P
.BI "libtar_list_t *libtar_list_new(int " flags ","
.BI "int (*" cmpfunc ")());"
.br
.BI "void libtar_list_free(libtar_list_t *" l ", void (*" freefunc ")());"
.br
.BI "int libtar_list_add_str(libtar_list_t *" l ", char *" str ","
.BI "char *" delim ");"
.br
.BI "int libtar_list_add(libtar_list_t *" l ", void *" data ");"
.br
.BI "void libtar_list_del(libtar_list_t *" l ", libtar_node_t **" n ");"
.br
.BI "int libtar_list_search(libtar_list_t *" l ", libtar_node_t **" n ","
.BI "void *" data ", int (*" matchfunc ")());"
.br
.BI "int libtar_list_next(libtar_list_t *" l ", libtar_node_t **" n ");"
.br
.BI "int libtar_list_prev(libtar_list_t *" l ", libtar_node_t **" n ");"
.br
.BI "libtar_list_t *libtar_list_dup(libtar_list_t *" l ");"
.br
.BI "libtar_list_t *libtar_list_merge(int (*" cmpfunc ")(), int " flags ","
.BI "libtar_list_t *" list1 ", libtar_list_t *" list2 ");"
.SH DESCRIPTION
The \fBlibtar_list_new\fP() function creates a new list.  The \fIflags\fP
argument must be one of the following values:
.IP \fBLIST_USERFUNC\fP
The \fIcmpfunc\fP argument points to a user-supplied function which
determines the ordering of the list.
.IP \fBLIST_STACK\fP
Use the list as a stack.  New elements are added to the front of the list.
.IP \fBLIST_QUEUE\fP
Use the list as a queue.  New elements are added to the end of the list.
.PP
The \fBlibtar_list_free\fP() function deallocates all memory associated
with the list \fIl\fP.  If \fIfreefunc\fP is not \fINULL\fP, it is called
to free memory associated with each node in the list.

The \fBlibtar_list_add\fP() function adds the element pointed to by
\fIdata\fP to the list \fIl\fP.  The position of the new element will
be determined by the flags passed to \fBlibtar_list_new\fP() when the
list was created.

The \fBlibtar_list_add_str\fP() function tokenizes the string \fIstr\fP
using the delimiter characters in the string \fIdelim\fP.  The resulting
tokens are added to list \fIl\fP using \fBlibtar_list_add\fP().

The \fBlibtar_list_search\fP() function searches for an element which
matches \fIdata\fP using the matching function \fImatchfunc\fP.  If
\fImatchfunc\fP is \fINULL\fP, a default matching function designed for
ASCII strings is used.  Searching begins from the node pointed to by
\fIn\fP.

The \fBlibtar_list_del\fP() function removes the entry pointed to by
\fIn\fP from the list pointed to by \fIl\fP.

The \fBlibtar_list_dup\fP() function creates a copy of the list \fIl\fP
using dynamically allocated memory.

The \fBlibtar_list_merge\fP() function creates a new
list with \fIflags\fP and \fIcmpfunc\fP, in the same way as
\fBlibtar_list_new\fP().  It then adds all elements from \fIlist1\fP
and \fIlist2\fP using \fBlibtar_list_add\fP().
.SH RETURN VALUE
The \fBlibtar_list_new\fP(), \fBlibtar_list_dup\fP(), and
\fBlibtar_list_merge\fP() functions return a pointer to the new list
structure, or \fINULL\fP on error.

The \fBlibtar_list_next\fP(), \fBlibtar_list_prev\fP(), and
\fBlibtar_list_search\fP() functions return 1 when valid data is
returned, or 0 otherwise.

The \fBlibtar_list_add\fP() and \fBlibtar_list_add_str\fP() functions
return 0 on success, or \-1 on error.
.SH SEE ALSO
.BR libtar_hash_new (3)