Document newer queue macros.

2 files changed, 329 insertions, 41 deletions

diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index 733627fd361..e65bf968df5 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -7,17 +7,29 @@ MLINKS+=bitstring.3 bit_alloc.3 bitstring.3 bit_clear.3 \
 	bitstring.3 bit_nclear.3 bitstring.3 bit_set.3 \
 	bitstring.3 bit_size.3  bitstring.3 bit_test.3
 MLINKS+=end.3 edata.3 end.3 etext.3
-MLINKS+=queue.3 list_entry.3 queue.3 list_head.3 queue.3 list_init.3
-MLINKS+=queue.3 list_insert_after.3 queue.3 list_insert_before.3
-MLINKS+=queue.3 list_insert_head.3
-MLINKS+=queue.3 list_remove.3 queue.3 tailq_entry.3 queue.3 tailq_head.3
-MLINKS+=queue.3 tailq_init.3 queue.3 tailq_insert_after.3
-MLINKS+=queue.3 tailq_insert_before.3
-MLINKS+=queue.3 tailq_insert_head.3 queue.3 tailq_insert_tail.3
-MLINKS+=queue.3 tailq_remove.3 queue.3 circleq_entry.3 queue.3 circleq_head.3
-MLINKS+=queue.3 circleq_init.3 queue.3 circleq_insert_after.3
-MLINKS+=queue.3 circleq_insert_before.3 queue.3 circleq_insert_head.3
-MLINKS+=queue.3 circleq_insert_tail.3 queue.3 circleq_remove.3
+MLINKS+=queue.3 list_entry.3 queue.3 list_head.3 \
+	queue.3 list_head_initializer.3 queue.3 list_first.3 \
+	queue.3 list_next.3 queue.3 list_end.3 queue.3 list_init.3 \
+	queue.3 list_insert_after.3 queue.3 list_insert_before.3 \
+	queue.3 list_insert_head.3 queue.3 list_remove.3 
+MLINKS+=queue.3 simpleq_entry.3 queue.3 simpleq_head.3 \
+	queue.3 simpleq_head_initializer.3 queue.3 simpleq_first.3 \
+	queue.3 simpleq_next.3 queue.3 simpleq_end.3 queue.3 simpleq_init.3 \
+	queue.3 simpleq_insert_head.3 queue.3 simpleq_insert_tail.3 \
+	queue.3 simpleq_insert_after.3 queue.3 simpleq_remove_head.3
+MLINKS+=queue.3 tailq_entry.3 queue.3 tailq_head.3 \
+	queue.3 tailq_head_initializer.3 queue.3 tailq_first.3 \
+	queue.3 tailq_next.3 queue.3 tailq_end.3 queue.3 tailq_last.3 \
+	queue.3 tailq_prev.3 queue.3 tailq_init.3 queue.3 tailq_insert_after.3 \
+	queue.3 tailq_insert_before.3 queue.3 tailq_insert_head.3 \
+	queue.3 tailq_insert_tail.3 queue.3 tailq_remove.3 
+MLINKS+=queue.3 circleq_entry.3 queue.3 circleq_head.3 \
+	queue.3 circleq_head_initializer.3 queue.3 circleq_first.3 \
+	queue.3 circleq_last.3 queue.3 circleq_end.3 queue.3 circleq_next.3 \
+	queue.3 circleq_prev.3 queue.3 circleq_init.3 \
+	queue.3 circleq_insert_after.3 queue.3 circleq_insert_before.3 \
+	queue.3 circleq_insert_head.3 queue.3 circleq_insert_tail.3 \
+	queue.3 circleq_remove.3
 MLINKS+=stdarg.3 varargs.3 stdarg.3 va_arg.3 stdarg.3 va_end.3
 MLINKS+=stdarg.3 va_start.3
 MLINKS+=dlfcn.3 dlopen.3 dlfcn.3 dlclose.3 dlfcn.3 dlsym.3 dlfcn.3 dlctl.3 \
diff --git a/share/man/man3/queue.3 b/share/man/man3/queue.3
index 19ba2da2557..4871a466fc7 100644
--- a/share/man/man3/queue.3
+++ b/share/man/man3/queue.3
@@ -1,3 +1,4 @@
+.\"	$OpenBSD: queue.3,v 1.7 1999/09/05 15:55:46 espie Exp $
 .\"	$NetBSD: queue.3,v 1.4 1995/07/03 00:25:36 mycroft Exp $
 .\"
 .\" Copyright (c) 1993 The Regents of the University of California.
@@ -39,13 +40,34 @@
 .Sh NAME
 .Nm LIST_ENTRY ,
 .Nm LIST_HEAD ,
+.Nm LIST_HEAD_INITIALIZER ,
+.Nm LIST_FIRST ,
+.Nm LIST_NEXT ,
+.Nm LIST_END ,
 .Nm LIST_INIT ,
 .Nm LIST_INSERT_AFTER ,
 .Nm LIST_INSERT_BEFORE ,
 .Nm LIST_INSERT_HEAD ,
 .Nm LIST_REMOVE ,
+.Nm SIMPLEQ_ENTRY ,
+.Nm SIMPLEQ_HEAD ,
+.Nm SIMPLEQ_HEAD_INITIALIZER ,
+.Nm SIMPLEQ_FIRST ,
+.Nm SIMPLEQ_NEXT ,
+.Nm SIMPLEQ_END ,
+.Nm SIMPLEQ_INIT ,
+.Nm SIMPLEQ_INSERT_HEAD ,
+.Nm SIMPLEQ_INSERT_TAIL ,
+.Nm SIMPLEQ_INSERT_AFTER ,
+.Nm SIMPLEQ_REMOVE_HEAD ,
 .Nm TAILQ_ENTRY ,
 .Nm TAILQ_HEAD ,
+.Nm TAILQ_HEAD_INITIALIZER ,
+.Nm TAILQ_FIRST ,
+.Nm TAILQ_NEXT ,
+.Nm TAILQ_END ,
+.Nm TAILQ_LAST ,
+.Nm TAILQ_PREV ,
 .Nm TAILQ_INIT ,
 .Nm TAILQ_INSERT_AFTER ,
 .Nm TAILQ_INSERT_BEFORE ,
@@ -54,45 +76,116 @@
 .Nm TAILQ_REMOVE ,
 .Nm CIRCLEQ_ENTRY ,
 .Nm CIRCLEQ_HEAD ,
+.Nm CIRCLEQ_HEAD_INITIALIZER ,
+.Nm CIRCLEQ_FIRST ,
+.Nm CIRCLEQ_LAST ,
+.Nm CIRCLEQ_END ,
+.Nm CIRCLEQ_NEXT ,
+.Nm CIRCLEQ_PREV ,
 .Nm CIRCLEQ_INIT ,
 .Nm CIRCLEQ_INSERT_AFTER ,
 .Nm CIRCLEQ_INSERT_BEFORE ,
 .Nm CIRCLEQ_INSERT_HEAD ,
 .Nm CIRCLEQ_INSERT_TAIL ,
 .Nm CIRCLEQ_REMOVE
-.Nd implementations of lists, tail queues, and circular queues
+.Nd "implementations of lists, simple queues, tail queues, and circular queues"
 .Sh SYNOPSIS
 .Fd #include <sys/queue.h>
 .sp
 .Fn LIST_ENTRY "TYPE"
 .Fn LIST_HEAD "HEADNAME" "TYPE"
+.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head"
+.Ft "struct TYPE *"
+.Fn LIST_FIRST "LIST_HEAD *head"
+.Ft "struct TYPE *"
+.Fn LIST_NEXT "struct TYPE *listelm" "LIST_ENTRY NAME"
+.Ft "struct TYPE *"
+.Fn LIST_END "LIST_HEAD *head"
+.Ft void
 .Fn LIST_INIT "LIST_HEAD *head"
-.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME"
-.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME"
-.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME"
-.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME"
+.Ft void
+.Fn LIST_INSERT_AFTER "struct TYPE *listelm" "struct TYPE *elm" "LIST_ENTRY NAME"
+.Ft void
+.Fn LIST_INSERT_BEFORE "struct TYPE *listelm" "struct TYPE *elm" "LIST_ENTRY NAME"
+.Ft void
+.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "struct TYPE *elm" "LIST_ENTRY NAME"
+.Ft void
+.Fn LIST_REMOVE "struct TYPE *elm" "LIST_ENTRY NAME"
+.sp
+.Fn SIMPLEQ_ENTRY "TYPE"
+.Fn SIMPLEQ_HEAD "HEADNAME" "TYPE"
+.Fn SIMPLEQ_HEAD_INITIALIZER "SIMPLEQ_HEAD head"
+.Ft "struct TYPE *"
+.Fn SIMPLEQ_FIRST "SIMPLEQ_HEAD *head"
+.Ft "struct TYPE *"
+.Fn SIMPLEQ_NEXT "struct TYPE *listelm" "SIMPLEQ_ENTRY NAME"
+.Ft "struct TYPE *"
+.Fn SIMPLEQ_END "SIMPLEQ_HEAD *head"
+.Ft void
+.Fn SIMPLEQ_INIT "SIMPLEQ_HEAD *head"
+.Ft void
+.Fn SIMPLEQ_INSERT_HEAD "SIMPLEQ_HEAD *head" "struct TYPE *elm" "SIMPLEQ_ENTRY NAME"
+.Ft void
+.Fn SIMPLEQ_INSERT_TAIL "SIMPLEQ_HEAD *head" "struct TYPE *elm" "SIMPLEQ_ENTRY NAME"
+.Ft void
+.Fn SIMPLEQ_INSERT_AFTER "struct TYPE *listelm" "struct TYPE *elm" "SIMPLEQ_ENTRY NAME"
+.Ft void
+.Fn SIMPLEQ_REMOVE_HEAD "SIMPLEQ_HEAD *head" "struct TYPE *elm" "SIMPLEQ_ENTRY NAME"
 .sp
 .Fn TAILQ_ENTRY "TYPE"
 .Fn TAILQ_HEAD "HEADNAME" "TYPE"
+.Fn TAILQ_HEAD_INITIALIZER "TAILQ_HEAD head"
+.Ft "struct TYPE *"
+.Fn TAILQ_FIRST "TAILQ_HEAD *head"
+.Ft "struct TYPE *"
+.Fn TAILQ_NEXT "struct TYPE *listelm" "TAILQ_ENTRY NAME"
+.Ft "struct TYPE *"
+.Fn TAILQ_END "TAILQ_HEAD *head"
+.Ft "struct TYPE *"
+.Fn TAILQ_LAST "TAILQ_HEAD *head" "HEADNAME NAME"
+.Fn TAILQ_PREV "TAILQ_HEAD *head" "HEADNAME NAME"
+.Ft void
 .Fn TAILQ_INIT "TAILQ_HEAD *head"
-.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME"
-.Fn TAILQ_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME"
-.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME"
-.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME"
-.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME"
+.Ft void
+.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "struct TYPE *listelm" "struct TYPE *elm" "TAILQ_ENTRY NAME"
+.Ft void
+.Fn TAILQ_INSERT_BEFORE "struct TYPE *listelm" "struct TYPE *elm" "TAILQ_ENTRY NAME"
+.Ft void
+.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "struct TYPE *elm" "TAILQ_ENTRY NAME"
+.Ft void
+.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "struct TYPE *elm" "TAILQ_ENTRY NAME"
+.Ft void
+.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "struct TYPE *elm" "TAILQ_ENTRY NAME"
 .sp
 .Fn CIRCLEQ_ENTRY "TYPE"
 .Fn CIRCLEQ_HEAD "HEADNAME" "TYPE"
+.Fn CIRCLEQ_HEAD_INITIALIZER "CIRCLEQ_HEAD head"
+.Ft "struct TYPE *"
+.Fn CIRCLEQ_FIRST "CIRCLEQ_HEAD *head"
+.Ft "struct TYPE *"
+.Fn CIRCLEQ_LAST "CIRCLEQ_HEAD *head"
+.Ft "struct TYPE *"
+.Fn CIRCLEQ_END "CIRCLEQ_HEAD *head"
+.Ft "struct TYPE *"
+.Fn CIRCLEQ_NEXT "struct TYPE *listelm" "CIRCLEQ_ENTRY NAME"
+.Ft "struct TYPE *"
+.Fn CIRCLEQ_PREV "struct TYPE *listelm" "CIRCLEQ_ENTRY NAME"
+.Ft void
 .Fn CIRCLEQ_INIT "CIRCLEQ_HEAD *head"
-.Fn CIRCLEQ_INSERT_AFTER "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
-.Fn CIRCLEQ_INSERT_BEFORE "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
-.Fn CIRCLEQ_INSERT_HEAD "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
-.Fn CIRCLEQ_INSERT_TAIL "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
-.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
+.Ft void
+.Fn CIRCLEQ_INSERT_AFTER "CIRCLEQ_HEAD *head" "struct TYPE *listelm" "struct TYPE *elm" "CIRCLEQ_ENTRY NAME"
+.Ft void
+.Fn CIRCLEQ_INSERT_BEFORE "CIRCLEQ_HEAD *head" "struct TYPE *listelm" "struct TYPE *elm" "CIRCLEQ_ENTRY NAME"
+.Ft void
+.Fn CIRCLEQ_INSERT_HEAD "CIRCLEQ_HEAD *head" "struct TYPE *elm" "CIRCLEQ_ENTRY NAME"
+.Ft void
+.Fn CIRCLEQ_INSERT_TAIL "CIRCLEQ_HEAD *head" "struct TYPE *elm" "CIRCLEQ_ENTRY NAME"
+.Ft void
+.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "struct TYPE *elm" "CIRCLEQ_ENTRY NAME"
 .Sh DESCRIPTION
-These macros define and operate on three types of data structures:
-lists, tail queues, and circular queues.
-All three structures support the following functionality:
+These macros define and operate on four types of data structures:
+lists, simple queues, tail queues, and circular queues.
+All structures except simple queues support the following functionality:
 .Pp
 .Bl -enum -compact -offset indent
 .It
@@ -105,13 +198,30 @@ Removal of any entry in the list.
 Forward traversal through the list.
 .El
 .Pp
-Lists are the simplest of the three data structures and support
-only the above functionality.
+Lists support only the above functionality.
+.Pp
+Simple queues are simplified list structures in exchange for 
+restricted functionality:
+.Pp
+.Bl -enum -compact -offset indent
+.It
+Simple queue entries require only one pointer.
+.It
+Code is roughly twice as small and fast as lists.
+.It
+Entries can be added to the end of the queue.
+.It
+No insertion of a new entry before a list element.
+.It
+Only the first element can be removed.
+.El
+.Pp
+.Bl -enum -compact -offset indent
 .Pp
 Tail queues add the following functionality:
 .Bl -enum -offset indent
 .It
-Entries can be added to the end of a list.
+Entries can be added to the end of the list.
 .El
 .Pp
 However:
@@ -152,9 +262,10 @@ than lists.
 .Pp
 In the macro definitions,
 .Fa TYPE
-is the name of a user defined structure,
+is the name tag of a user defined structure,
 that must contain a field of type
 .Li LIST_ENTRY ,
+.Li SIMPLEQ_ENTRY ,
 .Li TAILQ_ENTRY ,
 or
 .Li CIRCLEQ_ENTRY ,
@@ -162,9 +273,10 @@ named
 .Fa NAME .
 The argument
 .Fa HEADNAME
-is the name of a user defined structure that must be declared
+is the name tag of a user defined structure that must be declared
 using the macros
 .Fn LIST_HEAD ,
+.Fn SIMPLEQ_HEAD ,
 .Fn TAILQ_HEAD ,
 or
 .Fn CIRCLEQ_HEAD .
@@ -189,7 +301,7 @@ LIST_HEAD(HEADNAME, TYPE) head;
 .sp
 where
 .Fa HEADNAME
-is the name of the structure to be defined, and
+is the name of the structure to be defined, and struct
 .Fa 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:
@@ -202,6 +314,13 @@ struct HEADNAME *headp;
 and
 .Li headp
 are user selectable.)
+.sp
+The 
+.Fa HEADNAME 
+facility is often not used, leading to the following bizarre code:
+.Bd -literal -offset indent
+LIST_HEAD(, TYPE) head, *headp;
+.Ed
 .Pp
 The
 .Fn LIST_ENTRY
@@ -213,6 +332,13 @@ The
 macro initializes the list referenced by
 .Fa head .
 .Pp
+The list can also be initialized statically by using the 
+.Fn LIST_HEAD_INITIALIZER
+macro like this:
+.Bd -literal -offset indent
+LIST_HEAD(HEADNAME, TYPE) head = LIST_HEAD_INITIALIZER(head);
+.Ed
+.Pp
 The
 .Fn LIST_INSERT_HEAD
 macro inserts the new element
@@ -238,6 +364,15 @@ The
 macro removes the element
 .Fa elm
 from the list.
+.Pp
+The 
+.Fn LIST_FIRST ,
+and
+.Fn LIST_NEXT
+macros can be used to traverse the list:
+.Bd -literal -offset indent
+for (np = LIST_FIRST(&head); np != NULL; np = LIST_NEXT(np, NAME))
+.Ed
 .Sh LIST EXAMPLE
 .Bd -literal
 LIST_HEAD(listhead, entry) head;
@@ -265,6 +400,109 @@ for (np = head.lh_first; np != NULL; np = np->entries.le_next)
 while (head.lh_first != NULL)		/* Delete. */
 	LIST_REMOVE(head.lh_first, entries);
 .Ed
+.Sh SIMPLE QUEUES
+A simple queue is headed by a structure defined by the
+.Fn LIST_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 simply linked.
+New elements can be added to the queue after an existing element,
+at the head of the queue or at the tail of the queue.
+A
+.Fa SIMPLEQ_HEAD
+structure is declared as follows:
+.Bd -literal -offset indent
+SIMPLEQ_HEAD(HEADNAME, TYPE) head;
+.Ed
+.sp
+where
+.Fa HEADNAME
+is the name of the structure to be defined, and struct
+.Fa TYPE
+is the type of the elements to be linked into the queue.
+A pointer to the head of the queue can later be declared as:
+.Bd -literal -offset indent
+struct HEADNAME *headp;
+.Ed
+.sp
+(The names
+.Li head
+and
+.Li headp
+are user selectable.)
+.Pp
+The
+.Fn SIMPLEQ_ENTRY
+macro declares a structure that connects the elements in
+the queue.
+.Pp
+The
+.Fn SIMPLEQ_INIT
+macro initializes the queue referenced by
+.Fa head .
+.Pp
+The queue can also be initialized statically by using the 
+.Fn SIMPLEQ_HEAD_INITIALIZER
+macro like this:
+.Bd -literal -offset indent
+SIMPLEQ_HEAD(HEADNAME, TYPE) head = SIMPLEQ_HEAD_INITIALIZER(head);
+.Ed
+.Pp
+The
+.Fn SIMPLEQ_INSERT_HEAD
+macro inserts the new element
+.Fa elm
+at the head of the queue.
+.Pp
+The
+.Fn SIMPLEQ_INSERT_TAIL
+macro inserts the new element
+.Fa elm
+at the end of the queue.
+.Pp
+The
+.Fn SIMPLEQ_INSERT_AFTER
+macro inserts the new element
+.Fa elm
+after the element
+.Fa listelm .
+.Pp
+The
+.Fn SIMPLEQ_REMOVE_HEAD
+macro removes the first element
+from the queue.
+.Pp
+The 
+.Fn SIMPLEQ_FIRST ,
+and
+.Fn SIMPLEQ_NEXT
+macros can be used to traverse the queue.
+.Sh SIMPLE QUEUE EXAMPLE
+.Bd -literal
+SIMPLEQ_HEAD(listhead, entry) head = SIMPLEQ_HEAD_INITIALIZER(head);
+struct entry {
+	...
+	SIMPLEQ_ENTRY(entry) entries;	/* List. */
+	...
+} *n1, *n2, *np;
+
+n1 = malloc(sizeof(struct entry));	/* Insert at the head. */
+SIMPLEQ_INSERT_HEAD(&head, n1, entries);
+
+n2 = malloc(sizeof(struct entry));	/* Insert after. */
+SIMPLEQ_INSERT_AFTER(n1, n2, entries);
+
+n2 = malloc(sizeof(struct entry));	/* Insert at the tail. */
+SIMPLEQ_INSERT_TAIL(&head, n1, entries);
+					/* Forward traversal. */
+for (np = SIMPLEQ_FIRST(&head); np != NULL; np = SIMPLEQ_NEXT(np, entries))
+	np-> ...
+					/* Delete. */
+while (SIMPLEQ_FIRST(&head) != NULL)		
+	SIMPLEQ_REMOVE_HEAD(&head, n1, entries);
+.Ed
 .Sh TAIL QUEUES
 A tail queue is headed by a structure defined by the
 .Fn TAILQ_HEAD
@@ -286,7 +524,7 @@ TAILQ_HEAD(HEADNAME, TYPE) head;
 .sp
 where
 .Fa HEADNAME
-is the name of the structure to be defined, and
+is the name of the structure to be defined, and struct
 .Fa 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:
@@ -310,6 +548,10 @@ The
 macro initializes the tail queue referenced by
 .Fa head .
 .Pp
+The tail queue can also be initialized statically by using the
+.Fn TAILQ_HEAD_INITIALIZER
+macro.
+.Pp
 The
 .Fn TAILQ_INSERT_HEAD
 macro inserts the new element
@@ -341,6 +583,14 @@ The
 macro removes the element
 .Fa elm
 from the tail queue.
+.Pp
+The
+.Fn TAIL_FIRST ,
+.Fn TAILQ_NEXT ,
+.Fn TAILQ_LAST 
+and
+.Fn TAILQ_PREV 
+macros can be used to traverse a tail queue.
 .Sh TAIL QUEUE EXAMPLE
 .Bd -literal
 TAILQ_HEAD(tailhead, entry) head;
@@ -392,7 +642,7 @@ CIRCLEQ_HEAD(HEADNAME, TYPE) head;
 .sp
 where
 .Fa HEADNAME
-is the name of the structure to be defined, and
+is the name of the structure to be defined, and struct
 .Fa TYPE
 is the type of the elements to be linked into the circular queue.
 A pointer to the head of the circular queue can later be declared as:
@@ -416,6 +666,10 @@ The
 macro initializes the circular queue referenced by
 .Fa head .
 .Pp
+The circular queue can also be initialized statically by using the
+.Fn CIRCLEQ_HEAD_INITIALIZER
+macro.
+.Pp
 The
 .Fn CIRCLEQ_INSERT_HEAD
 macro inserts the new element
@@ -447,6 +701,15 @@ The
 macro removes the element
 .Fa elm
 from the circular queue.
+.Pp
+The
+.Fn CIRCLEQ_FIRST ,
+.Fn CIRCLEQ_LAST ,
+.Fn CIRCLEQ_END ,
+.Fn CIRCLEQ_NEXT 
+and
+.Fn CIRCLEQ_PREV
+macros can be used to traverse a circular queue.
 .Sh CIRCULAR QUEUE EXAMPLE
 .Bd -literal
 CIRCLEQ_HEAD(circleq, entry) head;
@@ -471,15 +734,28 @@ CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries);
 n2 = malloc(sizeof(struct entry));	/* Insert before. */
 CIRCLEQ_INSERT_BEFORE(&head, n1, n2, entries);
 					/* Forward traversal. */
-for (np = head.cqh_first; np != (void *)&head; np = np->entries.cqe_next)
+for (np = CIRCLEQ_FIRST(&head); np != CIRCLEQ_END(&head); 
+    np = CIRCLEQ_NEXT(np, entries))
 	np-> ...
 					/* Reverse traversal. */
-for (np = head.cqh_last; np != (void *)&head; np = np->entries.cqe_prev)
+for (np = CIRCLEQ_LAST(&head); np != CIRCLEQ_END(&head); 
+    np = CIRCLEQ_PREV(np, entries))
 	np-> ...
 					/* Delete. */
-while (head.cqh_first != (void *)&head)
-	CIRCLEQ_REMOVE(&head, head.cqh_first, entries);
+while (CIRCLEQ_FIRST(&head) != CIRCLEQ_END(&head))
+	CIRCLEQ_REMOVE(&head, CIRCLEQ_FIRST(&head), entries);
 .Ed
+.Sh NOTES
+The
+.Fn LIST_END ,
+.Fn SIMPLEQ_END 
+and
+.Fn TAILQ_END
+macros are provided for symetry with
+.Fn CIRCLEQ_END .
+They expand to 
+.Dv NULL
+and don't serve any useful purpose.
 .Sh HISTORY
 The
 .Nm queue