NAME
SLIST_HEAD,
SLIST_HEAD_INITIALIZER,
SLIST_ENTRY,
SLIST_FIRST,
SLIST_EMPTY,
SLIST_NEXT,
SLIST_FOREACH,
SLIST_FOREACH_SAFE,
SLIST_INIT,
SLIST_INSERT_AFTER,
SLIST_INSERT_HEAD,
SLIST_REMOVE_AFTER,
SLIST_REMOVE_HEAD,
SLIST_REMOVE,
LIST_HEAD,
LIST_HEAD_INITIALIZER,
LIST_ENTRY,
LIST_FIRST,
LIST_EMPTY,
LIST_NEXT,
LIST_FOREACH,
LIST_FOREACH_SAFE,
LIST_INIT,
LIST_INSERT_AFTER,
LIST_INSERT_BEFORE,
LIST_INSERT_HEAD,
LIST_REMOVE,
LIST_REPLACE,
LIST_MOVE,
SIMPLEQ_HEAD,
SIMPLEQ_HEAD_INITIALIZER,
SIMPLEQ_ENTRY,
SIMPLEQ_FIRST,
SIMPLEQ_EMPTY,
SIMPLEQ_NEXT,
SIMPLEQ_LAST,
SIMPLEQ_FOREACH,
SIMPLEQ_FOREACH_SAFE,
SIMPLEQ_INIT,
SIMPLEQ_INSERT_AFTER,
SIMPLEQ_INSERT_HEAD,
SIMPLEQ_INSERT_TAIL,
SIMPLEQ_REMOVE_AFTER,
SIMPLEQ_REMOVE_HEAD,
SIMPLEQ_REMOVE,
SIMPLEQ_CONCAT,
TAILQ_HEAD,
TAILQ_HEAD_INITIALIZER,
TAILQ_ENTRY,
TAILQ_FIRST,
TAILQ_NEXT,
TAILQ_LAST,
TAILQ_PREV,
TAILQ_EMPTY,
TAILQ_FOREACH,
TAILQ_FOREACH_SAFE,
TAILQ_FOREACH_REVERSE,
TAILQ_FOREACH_REVERSE_SAFE,
TAILQ_INIT,
TAILQ_INSERT_AFTER,
TAILQ_INSERT_BEFORE,
TAILQ_INSERT_HEAD,
TAILQ_INSERT_TAIL,
TAILQ_REMOVE,
TAILQ_REPLACE,
TAILQ_CONCAT,
STAILQ_HEAD,
STAILQ_HEAD_INITIALIZER,
STAILQ_ENTRY,
STAILQ_FIRST,
STAILQ_EMPTY,
STAILQ_NEXT,
STAILQ_LAST,
STAILQ_FOREACH,
STAILQ_FOREACH_SAFE,
STAILQ_INIT,
STAILQ_INSERT_AFTER,
STAILQ_INSERT_HEAD,
STAILQ_INSERT_TAIL,
STAILQ_REMOVE_HEAD,
STAILQ_REMOVE,
STAILQ_CONCAT —
implementations of
singly-linked lists, lists, simple queues, tail queues, and singly-linked tail
queues
SYNOPSIS
#include <sys/queue.h>
SLIST_HEAD(
HEADNAME,
TYPE);
SLIST_HEAD_INITIALIZER(
head);
SLIST_ENTRY(
TYPE);
TYPE *
SLIST_FIRST(
SLIST_HEAD
*head);
int
SLIST_EMPTY(
SLIST_HEAD
*head);
TYPE *
SLIST_NEXT(
TYPE
*elm,
SLIST_ENTRY
NAME);
SLIST_FOREACH(
TYPE
*var,
SLIST_HEAD
*head,
SLIST_ENTRY
NAME);
SLIST_FOREACH_SAFE(
TYPE
*var,
SLIST_HEAD
*head,
SLIST_ENTRY
NAME,
TYPE *tmp);
SLIST_INIT(
SLIST_HEAD
*head);
SLIST_INSERT_HEAD(
SLIST_HEAD
*head,
TYPE *elm,
SLIST_ENTRY NAME);
SLIST_INSERT_AFTER(
TYPE
*listelm,
TYPE *elm,
SLIST_ENTRY NAME);
SLIST_REMOVE(
SLIST_HEAD
*head,
TYPE *elm,
TYPE,
SLIST_ENTRY NAME);
SLIST_REMOVE_HEAD(
SLIST_HEAD
*head,
SLIST_ENTRY
NAME);
LIST_HEAD(
HEADNAME,
TYPE);
LIST_HEAD_INITIALIZER(
head);
LIST_ENTRY(
TYPE);
TYPE *
LIST_FIRST(
LIST_HEAD
*head);
TYPE *
LIST_NEXT(
TYPE
*elm,
LIST_ENTRY
NAME);
int
LIST_EMPTY(
LIST_HEAD
*head);
LIST_FOREACH(
TYPE
*var,
LIST_HEAD
*head,
LIST_ENTRY
NAME);
LIST_FOREACH_SAFE(
TYPE
*var,
LIST_HEAD
*head,
LIST_ENTRY
NAME,
TYPE *tmp);
LIST_INIT(
LIST_HEAD
*head);
LIST_INSERT_AFTER(
TYPE
*listelm,
TYPE *elm,
LIST_ENTRY NAME);
LIST_INSERT_BEFORE(
TYPE
*listelm,
TYPE *elm,
LIST_ENTRY NAME);
LIST_INSERT_HEAD(
LIST_HEAD
*head,
TYPE *elm,
LIST_ENTRY NAME);
LIST_REMOVE(
TYPE
*elm,
LIST_ENTRY
NAME);
LIST_REPLACE(
TYPE
*elm,
TYPE *new,
LIST_ENTRY NAME);
LIST_MOVE(
LIST_HEAD
*head1,
LIST_HEAD
*head2,
LIST_ENTRY
NAME);
SIMPLEQ_HEAD(
HEADNAME,
TYPE);
SIMPLEQ_HEAD_INITIALIZER(
head);
SIMPLEQ_ENTRY(
TYPE);
TYPE *
SIMPLEQ_FIRST(
SIMPLEQ_HEAD
*head);
int
SIMPLEQ_EMPTY(
SIMPLEQ_HEAD
*head);
TYPE *
SIMPLEQ_NEXT(
TYPE
*elm,
SIMPLEQ_ENTRY
NAME);
TYPE *
SIMPLEQ_LAST(
SIMPLEQ_HEAD
*head,
TYPE *elm,
SIMPLEQ_ENTRY NAME);
SIMPLEQ_FOREACH(
TYPE
*var,
SIMPLEQ_HEAD
*head,
SIMPLEQ_ENTRY
NAME);
SIMPLEQ_FOREACH_SAFE(
TYPE
*var,
SIMPLEQ_HEAD
*head,
SIMPLEQ_ENTRY
NAME,
TYPE *tmp);
SIMPLEQ_INIT(
SIMPLEQ_HEAD
*head);
SIMPLEQ_INSERT_HEAD(
SIMPLEQ_HEAD
*head,
TYPE *elm,
SIMPLEQ_ENTRY NAME);
SIMPLEQ_INSERT_TAIL(
SIMPLEQ_HEAD
*head,
TYPE *elm,
SIMPLEQ_ENTRY NAME);
SIMPLEQ_INSERT_AFTER(
SIMPLEQ_HEAD
*head,
TYPE *listelm,
TYPE *elm,
SIMPLEQ_ENTRY NAME);
SIMPLEQ_REMOVE_HEAD(
SIMPLEQ_HEAD
*head,
SIMPLEQ_ENTRY
NAME);
SIMPLEQ_REMOVE_AFTER(
SIMPLEQ_HEAD
*head,
TYPE *elm,
SIMPLEQ_ENTRY NAME);
SIMPLEQ_REMOVE(
SIMPLEQ_HEAD
*head,
TYPE *elm,
TYPE,
SIMPLEQ_ENTRY NAME);
SIMPLEQ_CONCAT(
SIMPLEQ_HEAD
*head1,
SIMPLEQ_HEAD
*head2);
TAILQ_HEAD(
HEADNAME,
TYPE);
TAILQ_HEAD_INITIALIZER(
head);
TAILQ_ENTRY(
TYPE);
TYPE *
TAILQ_FIRST(
TAILQ_HEAD
*head);
TYPE *
TAILQ_NEXT(
TYPE
*elm,
TAILQ_ENTRY
NAME);
TYPE *
TAILQ_LAST(
TAILQ_HEAD
*head,
HEADNAME);
TYPE *
TAILQ_PREV(
TYPE
*elm,
HEADNAME,
TAILQ_ENTRY NAME);
int
TAILQ_EMPTY(
TAILQ_HEAD
*head);
TAILQ_FOREACH(
TYPE
*var,
TAILQ_HEAD
*head,
TAILQ_ENTRY
NAME);
TAILQ_FOREACH_SAFE(
TYPE
*var,
TAILQ_HEAD
*head,
TAILQ_ENTRY
NAME,
TYPE *tmp);
TAILQ_FOREACH_REVERSE(
TYPE
*var,
TAILQ_HEAD
*head,
HEADNAME,
TAILQ_ENTRY NAME);
TAILQ_FOREACH_REVERSE_SAFE(
TYPE
*var,
TAILQ_HEAD
*head,
HEADNAME,
TAILQ_ENTRY NAME,
TYPE *tmp);
TAILQ_INIT(
TAILQ_HEAD
*head);
TAILQ_INSERT_HEAD(
TAILQ_HEAD
*head,
TYPE *elm,
TAILQ_ENTRY NAME);
TAILQ_INSERT_TAIL(
TAILQ_HEAD
*head,
TYPE *elm,
TAILQ_ENTRY NAME);
TAILQ_INSERT_AFTER(
TAILQ_HEAD
*head,
TYPE *listelm,
TYPE *elm,
TAILQ_ENTRY NAME);
TAILQ_INSERT_BEFORE(
TYPE
*listelm,
TYPE *elm,
TAILQ_ENTRY NAME);
TAILQ_REMOVE(
TAILQ_HEAD
*head,
TYPE *elm,
TAILQ_ENTRY NAME);
TAILQ_REPLACE(
TAILQ_HEAD
*head,
TYPE *elm,
TYPE *new,
TAILQ_ENTRY NAME);
TAILQ_CONCAT(
TAILQ_HEAD
*head1,
TAILQ_HEAD
*head2,
TAILQ_ENTRY
NAME);
STAILQ_HEAD(
HEADNAME,
TYPE);
STAILQ_HEAD_INITIALIZER(
head);
STAILQ_ENTRY(
TYPE);
TYPE *
STAILQ_FIRST(
STAILQ_HEAD
*head);
int
STAILQ_EMPTY(
STAILQ_HEAD
*head);
TYPE *
STAILQ_NEXT(
TYPE
*elm,
STAILQ_ENTRY
NAME);
TYPE *
STAILQ_LAST(
STAILQ_HEAD
*head,
TYPE *elm,
STAILQ_ENTRY NAME);
STAILQ_FOREACH(
TYPE
*var,
STAILQ_HEAD
*head,
STAILQ_ENTRY
NAME);
STAILQ_FOREACH_SAFE(
TYPE
*var,
STAILQ_HEAD
*head,
STAILQ_ENTRY
NAME,
TYPE *tmp);
STAILQ_INIT(
STAILQ_HEAD
*head);
STAILQ_INSERT_HEAD(
STAILQ_HEAD
*head,
TYPE *elm,
STAILQ_ENTRY NAME);
STAILQ_INSERT_TAIL(
STAILQ_HEAD
*head,
TYPE *elm,
STAILQ_ENTRY NAME);
STAILQ_INSERT_AFTER(
STAILQ_HEAD
*head,
TYPE *listelm,
TYPE *elm,
STAILQ_ENTRY NAME);
STAILQ_REMOVE_HEAD(
STAILQ_HEAD
*head,
STAILQ_ENTRY
NAME);
STAILQ_REMOVE(
STAILQ_HEAD
*head,
TYPE *elm,
TYPE,
STAILQ_ENTRY NAME);
STAILQ_CONCAT(
STAILQ_HEAD
*head1,
STAILQ_HEAD
*head2);
DESCRIPTION
These macros define and operate on five types of data structures: singly-linked
lists, simple queues, lists, tail queues, and singly-linked tail queues. All
five structures support the following functionality:
- Insertion of a new entry at
the head of the list.
- Insertion of a new entry after
any element in the list.
- Removal of any entry in the
list.
- Forward traversal through the
list.
Singly-linked lists are the simplest of the four data structures and support
only the above functionality. Singly-linked lists are ideal for applications
with large datasets and few or no removals, or for implementing a LIFO queue.
Simple queues add the following functionality:
- Entries can be added at the
end of a list.
- They may be concatenated.
However:
- Entries may not be added
before any element in the list.
- All list insertions and
removals must specify the head of the list.
- Each head entry requires two
pointers rather than one.
Simple queues are ideal for applications with large datasets and few or no
removals, or for implementing a FIFO queue.
All doubly linked types of data structures (lists and tail queues) additionally
allow:
- Insertion of a new entry
before any element in the list.
- O(1) removal of any entry in
the list.
However:
- Each element requires two
pointers rather than one.
- Code size and execution time
of operations (except for removal) is about twice that of the
singly-linked data-structures.
Linked lists are the simplest of the doubly linked data structures and support
only the above functionality over singly-linked lists.
Tail queues add the following functionality:
- Entries can be added at the
end of a list.
- They may be concatenated.
However:
- All list insertions and
removals, except insertion before another element, must specify the head
of the list.
- Each head entry requires two
pointers rather than one.
- Code size is about 15% greater
and operations run about 20% slower than lists.
Circular queues add the following functionality:
- Entries can be added at the
end of a list.
- They may be traversed
backwards, from tail to head.
However:
- All list insertions and
removals must specify the head of the list.
- Each head entry requires two
pointers rather than one.
- The termination condition for
traversal is more complex.
- Code size is about 40% greater
and operations run about 45% slower than lists.
In the macro definitions,
TYPE is the name of a user
defined structure, that must contain a field of type
SLIST_ENTRY
,
LIST_ENTRY
,
SIMPLEQ_ENTRY
,
TAILQ_ENTRY
, or
STAILQ_ENTRY
, named
NAME. The
argument
HEADNAME is the name of a user defined
structure that must be declared using the macros
LIST_HEAD
,
SIMPLEQ_HEAD
,
SLIST_HEAD
, or
TAILQ_HEAD
. See
the examples below for further explanation of how these macros are used.
Summary of Operations
The following table summarizes the supported macros for each type of data
structure.
|
SLIST |
LIST |
SIMPLEQ |
TAILQ |
STAILQ |
|
_FIRST |
+ |
+ |
+ |
+ |
+ |
_EMPTY |
+ |
+ |
+ |
+ |
+ |
_NEXT |
+ |
+ |
+ |
+ |
+ |
_PREV |
- |
- |
- |
+ |
- |
_LAST |
- |
- |
+ |
+ |
+ |
_FOREACH |
+ |
+ |
+ |
+ |
+ |
_FOREACH_SAFE |
+ |
+ |
+ |
+ |
+ |
_FOREACH_REVERSE |
- |
- |
- |
+ |
- |
_FOREACH_REVERSE_SAFE |
- |
- |
- |
+ |
- |
_INSERT_HEAD |
+ |
+ |
+ |
+ |
+ |
_INSERT_AFTER |
+ |
+ |
+ |
+ |
+ |
_INSERT_BEFORE |
- |
+ |
- |
+ |
- |
_INSERT_TAIL |
- |
- |
+ |
+ |
+ |
_REMOVE |
+ |
+ |
+ |
+ |
+ |
_REMOVE_HEAD |
+ |
- |
+ |
- |
+ |
_REMOVE_AFTER |
- |
- |
+ |
- |
+ |
_REPLACE |
- |
+ |
- |
+ |
- |
_CONCAT |
- |
- |
+ |
+ |
+ |
SINGLY-LINKED LISTS
A singly-linked list is headed by a structure defined by the
SLIST_HEAD() macro. This structure contains a single pointer
to the first element on the list. The elements are singly linked for minimum
space and pointer manipulation overhead at the expense of O(n) removal for
arbitrary elements. New elements can be added to the list after an existing
element or at the head of the list. An
SLIST_HEAD
structure is declared as follows:
SLIST_HEAD(HEADNAME, TYPE) head;
where
HEADNAME is the name of the structure to be defined,
and
TYPE is the type of the elements to be linked into
the list. A pointer to the head of the list can later be declared as:
(The names
head
and
headp
are
user selectable.)
The macro
SLIST_HEAD_INITIALIZER() evaluates to an initializer
for the list
head.
The macro
SLIST_ENTRY() declares a structure that connects the
elements in the list.
The macro
SLIST_FIRST() returns the first element in the list
or NULL if the list is empty.
The macro
SLIST_EMPTY() evaluates to true if there are no
elements in the list.
The macro
SLIST_NEXT() returns the next element in the list.
SLIST_FOREACH() traverses the list referenced by
head in the forward direction, assigning each element in
turn to
var.
The SAFE version uses
tmp to hold the next element, so
var may be freed or removed from the list.
The macro
SLIST_INIT() initializes the list referenced by
head.
The macro
SLIST_INSERT_HEAD() inserts the new element
elm at the head of the list.
The macro
SLIST_INSERT_AFTER() inserts the new element
elm after the element
listelm.
The macro
SLIST_REMOVE() removes the element
elm from the list.
The macro
SLIST_REMOVE_HEAD() removes the first element from
the head of the list. For optimum efficiency, elements being removed from the
head of the list should explicitly use this macro instead of the generic
SLIST_REMOVE() macro.
The macro
SLIST_REMOVE_AFTER() removes the element after the
one specified. For optimum efficiency, elements being removed after a
specified one should explicitly use this macro instead of the generic
SLIST_REMOVE()
SINGLY-LINKED LIST EXAMPLE
SLIST_HEAD(slisthead, entry) head =
SLIST_HEAD_INITIALIZER(head);
struct slisthead *headp; /* Singly-linked List head. */
struct entry {
...
SLIST_ENTRY(entry) entries; /* Singly-linked List. */
...
} *n1, *n2, *n3, *np;
SLIST_INIT(&head); /* Initialize the list. */
n1 = malloc(sizeof(struct entry)); /* Insert at the head. */
SLIST_INSERT_HEAD(&head, n1, entries);
n2 = malloc(sizeof(struct entry)); /* Insert after. */
SLIST_INSERT_AFTER(n1, n2, entries);
SLIST_REMOVE(&head, n2, entry, entries);/* Deletion. */
free(n2);
n3 = SLIST_FIRST(&head);
SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head. */
free(n3);
SLIST_FOREACH(np, &head, entries) /* Forward traversal. */
np-> ...
while (!SLIST_EMPTY(&head)) { /* List Deletion. */
n1 = SLIST_FIRST(&head);
SLIST_REMOVE_HEAD(&head, entries);
free(n1);
}
LISTS
A list is headed by a structure defined by the
LIST_HEAD()
macro. This structure contains a single pointer to the first element on the
list. The elements are doubly linked so that an arbitrary element can be
removed without traversing the list. New elements can be added to the list
after an existing element, before an existing element, or at the head of the
list. A
LIST_HEAD structure is declared as follows:
LIST_HEAD(HEADNAME, TYPE) head;
where
HEADNAME is the name of the structure to be defined,
and
TYPE is the type of the elements to be linked into
the list. A pointer to the head of the list can later be declared as:
(The names
head
and
headp
are
user selectable.)
The macro
LIST_ENTRY() declares a structure that connects the
elements in the list.
The macro
LIST_HEAD_INITIALIZER() provides a value which can
be used to initialize a list head at compile time, and is used at the point
that the list head variable is declared, like:
struct HEADNAME head = LIST_HEAD_INITIALIZER(head);
The macro
LIST_FIRST() returns the first element of the list
head.
The macro
LIST_EMPTY() returns true if the list
head has no elements.
The macro
LIST_NEXT() returns the element after the element
elm.
The macro
LIST_FOREACH() traverses the list referenced by
head in the forward direction, assigning each element in
turn to
var.
The SAFE version uses
tmp to hold the next element, so
var may be freed or removed from the list.
The macro
LIST_INIT() initializes the list referenced by
head.
The macro
LIST_INSERT_AFTER() inserts the new element
elm after the element
listelm.
The macro
LIST_INSERT_BEFORE() inserts the new element
elm before the element
listelm.
The macro
LIST_INSERT_HEAD() inserts the new element
elm at the head of the list.
The macro
LIST_REMOVE() removes the element
elm from the list.
The macro
LIST_REPLACE() replaces the element
elm with
new in the list.
The macro
LIST_MOVE() moves the list headed by
head1 onto the list headed by
head2, always making the former empty.
LIST EXAMPLE
LIST_HEAD(listhead, entry) head;
struct listhead *headp; /* List head. */
struct entry {
...
LIST_ENTRY(entry) entries; /* List. */
...
} *n1, *n2, *np;
LIST_INIT(&head); /* Initialize the list. */
n1 = malloc(sizeof(struct entry)); /* Insert at the head. */
LIST_INSERT_HEAD(&head, n1, entries);
n2 = malloc(sizeof(struct entry)); /* Insert after. */
LIST_INSERT_AFTER(n1, n2, entries);
n2 = malloc(sizeof(struct entry)); /* Insert before. */
LIST_INSERT_BEFORE(n1, n2, entries);
LIST_FOREACH(np, &head, entries) /* Forward traversal. */
np-> ...
while (LIST_FIRST(&head) != NULL) /* Delete. */
LIST_REMOVE(LIST_FIRST(&head), entries);
if (LIST_EMPTY(&head)) /* Test for emptiness. */
printf("nothing to do\n");
SIMPLE QUEUES
A simple queue is headed by a structure defined by the
SIMPLEQ_HEAD() macro. This structure contains a pair of
pointers, one to the first element in the simple queue and the other to the
last element in the simple queue. The elements are singly linked for minimum
space and pointer manipulation overhead at the expense of O(n) removal for
arbitrary elements. New elements can be added to the queue after an existing
element, at the head of the queue, or at the end of the queue. A
SIMPLEQ_HEAD structure is declared as follows:
SIMPLEQ_HEAD(HEADNAME, TYPE) head;
where
HEADNAME
is the name of the structure to be
defined, and
TYPE
is the type of the elements to be
linked into the simple queue. A pointer to the head of the simple queue can
later be declared as:
(The names
head
and
headp
are
user selectable.)
The macro
SIMPLEQ_ENTRY() declares a structure that connects
the elements in the simple queue.
The macro
SIMPLEQ_HEAD_INITIALIZER() provides a value which
can be used to initialize a simple queue head at compile time, and is used at
the point that the simple queue head variable is declared, like:
struct HEADNAME head = SIMPLEQ_HEAD_INITIALIZER(head);
The macro
SIMPLEQ_FIRST() returns the first element of the
simple queue
head.
The macro
SIMPLEQ_EMPTY() returns true if the simple queue
head has no elements.
The macro
SIMPLEQ_NEXT() returns the element after the element
elm.
The macro
SIMPLEQ_LAST() returns the last item on the tail
queue. If the tail queue is empty the return value is
NULL
.
The macro
SIMPLEQ_FOREACH() traverses the tail queue
referenced by
head in the forward direction, assigning
each element in turn to
var.
The SAFE version uses
tmp to hold the next element, so
var may be freed or removed from the list.
The macro
SIMPLEQ_INIT() initializes the simple queue
referenced by
head.
The macro
SIMPLEQ_INSERT_HEAD() inserts the new element
elm at the head of the simple queue.
The macro
SIMPLEQ_INSERT_TAIL() inserts the new element
elm at the end of the simple queue.
The macro
SIMPLEQ_INSERT_AFTER() inserts the new element
elm after the element
listelm.
The macro
SIMPLEQ_REMOVE_HEAD() removes the first element from
the head of the simple queue. For optimum efficiency, elements being removed
from the head of the queue should explicitly use this macro instead of the
generic
SIMPLEQ_REMOVE() macro.
The macro
SIMPLEQ_REMOVE_AFTER() removes the element after the
one specified from the simple queue. For optimum efficiency, elements being
removed after specified elements should explicitly use this macro instead of
the generic
SIMPLEQ_REMOVE() macro.
The macro
SIMPLEQ_REMOVE() removes
elm
from the simple queue.
The macro
SIMPLEQ_CONCAT() concatenates the tail queue headed
by
head2 onto the end of the one headed by
head1, removing all entries from the former.
SIMPLE QUEUE EXAMPLE
SIMPLEQ_HEAD(simplehead, entry) head;
struct simplehead *headp; /* Simple queue head. */
struct entry {
...
SIMPLEQ_ENTRY(entry) entries; /* Simple queue. */
...
} *n1, *n2, *np;
SIMPLEQ_INIT(&head); /* Initialize the queue. */
n1 = malloc(sizeof(struct entry)); /* Insert at the head. */
SIMPLEQ_INSERT_HEAD(&head, n1, entries);
n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */
SIMPLEQ_INSERT_TAIL(&head, n1, entries);
n2 = malloc(sizeof(struct entry)); /* Insert after. */
SIMPLEQ_INSERT_AFTER(&head, n1, n2, entries);
SIMPLEQ_FOREACH(np, &head, entries) /* Forward traversal. */
np-> ...
while (SIMPLEQ_FIRST(&head) != NULL) /* Delete. */
SIMPLEQ_REMOVE_HEAD(&head, entries);
if (SIMPLEQ_EMPTY(&head)) /* Test for emptiness. */
printf("nothing to do\n");
TAIL QUEUES
A tail queue is headed by a structure defined by the
TAILQ_HEAD() macro. This structure contains a pair of
pointers, one to the first element in the tail queue and the other to the last
element in the tail queue. The elements are doubly linked so that an arbitrary
element can be removed without traversing the tail queue. New elements can be
added to the queue after an existing element, before an existing element, at
the head of the queue, or at the end the queue. A
TAILQ_HEAD structure is declared as follows:
TAILQ_HEAD(HEADNAME, TYPE) head;
where
HEADNAME
is the name of the structure to be
defined, and
TYPE
is the type of the elements to be
linked into the tail queue. A pointer to the head of the tail queue can later
be declared as:
(The names
head
and
headp
are
user selectable.)
The macro
TAILQ_ENTRY() declares a structure that connects the
elements in the tail queue.
The macro
TAILQ_HEAD_INITIALIZER() provides a value which can
be used to initialize a tail queue head at compile time, and is used at the
point that the tail queue head variable is declared, like:
struct HEADNAME head = TAILQ_HEAD_INITIALIZER(head);
The macro
TAILQ_FIRST() returns the first element of the tail
queue
head.
The macro
TAILQ_NEXT() returns the element after the element
elm.
The macro
TAILQ_LAST() returns the last item on the tail
queue. If the tail queue is empty the return value is
NULL
.
The macro
TAILQ_PREV() returns the previous item on the tail
queue, from the one specified. If the tail queue is empty the return value is
NULL
.
The macro
TAILQ_EMPTY() returns true if the tail queue
head has no elements.
The macros
TAILQ_FOREACH(),
TAILQ_FOREACH_REVERSE(),
TAILQ_FOREACH_SAFE(), and
TAILQ_FOREACH_REVERSE_SAFE() traverse the tail queue
referenced by
head in the forward or reverse direction
direction, assigning each element in turn to
var.
The SAFE versions use
tmp to hold the next element, so
var may be freed or removed from the list.
The macro
TAILQ_INIT() initializes the tail queue referenced
by
head.
The macro
TAILQ_INSERT_HEAD() inserts the new element
elm at the head of the tail queue.
The macro
TAILQ_INSERT_TAIL() inserts the new element
elm at the end of the tail queue.
The macro
TAILQ_INSERT_AFTER() inserts the new element
elm after the element
listelm.
The macro
TAILQ_INSERT_BEFORE() inserts the new element
elm before the element
listelm.
The macro
TAILQ_REMOVE() removes the element
elm from the tail queue.
The macro
TAILQ_REPLACE() replaces the element
elm with the
new one specified in
the tail queue.
The macro
TAILQ_CONCAT() concatenates the tail queue headed by
head2 onto the end of the one headed by
head1, removing all entries from the former.
TAIL QUEUE EXAMPLE
TAILQ_HEAD(tailhead, entry) head;
struct tailhead *headp; /* Tail queue head. */
struct entry {
...
TAILQ_ENTRY(entry) entries; /* Tail queue. */
...
} *n1, *n2, *np;
TAILQ_INIT(&head); /* Initialize the queue. */
n1 = malloc(sizeof(struct entry)); /* Insert at the head. */
TAILQ_INSERT_HEAD(&head, n1, entries);
n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */
TAILQ_INSERT_TAIL(&head, n1, entries);
n2 = malloc(sizeof(struct entry)); /* Insert after. */
TAILQ_INSERT_AFTER(&head, n1, n2, entries);
n2 = malloc(sizeof(struct entry)); /* Insert before. */
TAILQ_INSERT_BEFORE(n1, n2, entries);
TAILQ_FOREACH(np, &head, entries) /* Forward traversal. */
np-> ...
/* Reverse traversal. */
TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries)
np-> ...
while (TAILQ_FIRST(&head) != NULL) /* Delete. */
TAILQ_REMOVE(&head, TAILQ_FIRST(&head), entries);
if (TAILQ_EMPTY(&head)) /* Test for emptiness. */
printf("nothing to do\n");
SINGLY LINKED TAIL QUEUES
The macros prefixed with “
STAILQ_”
(
STAILQ_HEAD(),
STAILQ_HEAD_INITIALIZER(),
STAILQ_ENTRY(),
STAILQ_FOREACH(),
STAILQ_FOREACH_SAFE(),
STAILQ_FIRST(),
STAILQ_EMPTY(),
STAILQ_NEXT(),
STAILQ_LAST(),
STAILQ_INIT(),
STAILQ_INSERT_HEAD(),
STAILQ_INSERT_TAIL(),
STAILQ_INSERT_AFTER(),
STAILQ_REMOVE_HEAD(),
STAILQ_REMOVE(), and
STAILQ_CONCAT()) are functionally identical to these simple
queue functions, and are provided for compatibility with
FreeBSD.
NOTES
Some of these macros or functions perform no error checking, and invalid usage
leads to undefined behaviour. In the case of macros or functions that expect
their arguments to be elements that are present in the list or queue, passing
an element that is not present is invalid.
HISTORY
The
queue functions first appeared in
4.4BSD. The
SIMPLEQ functions first
appeared in
NetBSD 1.2. The
SLIST
and
STAILQ functions first appeared in
FreeBSD 2.1.5.