=head1 NAME

list - list routines

=head1 SYNOPSIS

    #include <inn/list.h>

    struct node {
        struct node *succ;
        struct node *pred;
    };

    struct list {
        struct node *head;
        struct node *tail;
        struct node *tailpred;
    };

    void list_new(struct list *list);

    struct node *list_addhead(struct list *list, struct node *node);

    struct node *list_addtail(struct list *list, struct node *node);

    struct node *list_head(struct list *list);

    struct node *list_tail(struct list *list);

    struct node *list_succ(struct node *node);

    struct node *list_pred(struct node *node);

    struct node *list_remhead(struct list *list);

    struct node *list_remtail(struct list *list);

    struct node *list_remove(struct node *node);

    struct node *list_insert(struct list *list, struct node *node, struct node *pred);

    bool list_isempty(struct list *list);

=head1 DESCRIPTION

B<list_new> initialises the list header I<list> so as to create an
empty list.

B<list_addhead> adds I<node> to the head of I<list>, returning the node
just added.

B<list_addtail> adds I<node> to the tail of I<list>, returning the node
just added.

B<list_head> returns a pointer to the the node at the head of I<list>
or B<NULL> if the list is empty.

B<list_tail> returns a pointer to the the node at the tail of I<list>
or B<NULL> if the list is empty.

B<list_succ> returns the next (successor) node on the list after
I<node> or B<NULL> if I<node> was the final node.

B<list_pred> returns the previous (predecessor) node on the list before
I<node> or B<NULL> if I<node> was the first node.

B<list_remhead> removes the first node from I<list> and returns it to
the caller.  If the list is empty B<NULL> is returned.

B<list_remtail> removes the last node from I<list> and returns it to
the caller.  If the list is empty B<NULL> is returned.

B<list_remove> removes I<node> from the list it is on and returns it
to the caller.

B<list_insert> inserts I<node> onto I<list> after the node I<pred>.  If
I<pred> is B<NULL> then I<node> is added to the head of I<list>.

=head1 HISTORY

Written by Alex Kiernan <alex.kiernan@thus.net> for S<InterNetNews 2.4.0>.

=cut
