From 6c1d0fbf066754ca4585eb5976e766b73049cf18 Mon Sep 17 00:00:00 2001
From: Archie Cobbs <archie@FreeBSD.org>
Date: Mon, 1 May 2000 18:22:59 +0000
Subject: [PATCH] Document TAILQ_FOREACH_REVERSE() and
 CIRCLEQ_FOREACH_REVERSE() macros.

Submitted by:	Jake Burkholder <jburkhol@home.com>
---
 share/man/man3/queue.3 | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/share/man/man3/queue.3 b/share/man/man3/queue.3
index b1769db24c8..ac8416c0e96 100644
--- a/share/man/man3/queue.3
+++ b/share/man/man3/queue.3
@@ -75,6 +75,7 @@
 .Nm TAILQ_ENTRY ,
 .Nm TAILQ_FIRST ,
 .Nm TAILQ_FOREACH ,
+.Nm TAILQ_FOREACH_REVERSE ,
 .Nm TAILQ_HEAD ,
 .Nm TAILQ_INIT ,
 .Nm TAILQ_INSERT_AFTER ,
@@ -89,6 +90,7 @@
 .Nm CIRCLEQ_ENTRY ,
 .Nm CIRCLEQ_FIRST ,
 .Nm CIRCLEQ_FOREACH ,
+.Nm CIRCLEQ_FOREACH_REVERSE ,
 .Nm CIRCLEQ_HEAD ,
 .Nm CIRCLEQ_INIT ,
 .Nm CIRCLEQ_INSERT_AFTER ,
@@ -146,6 +148,7 @@ lists, tail queues, and circular queues
 .Fn TAILQ_ENTRY "TYPE"
 .Fn TAILQ_FIRST "TAILQ_HEAD *head"
 .Fn TAILQ_FOREACH "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME"
+.Fn TAILQ_FOREACH_REVERSE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME"
 .Fn TAILQ_HEAD "HEADNAME" "TYPE"
 .Fn TAILQ_INIT "TAILQ_HEAD *head"
 .Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME"
@@ -161,6 +164,7 @@ lists, tail queues, and circular queues
 .Fn CIRCLEQ_ENTRY "TYPE"
 .Fn CIRCLEQ_FIRST "CIRCLEQ_HEAD *head"
 .Fn CIRCLEQ_FOREACH "TYPE *var" "CIRCLEQ_HEAD *head" "CIRCLEQ_ENTRY NAME"
+.Fn CIRCLEQ_FOREACH_REVERSE "TYPE *var" "CIRCLEQ_HEAD *head" "CIRCLEQ_ENTRY NAME"
 .Fn CIRCLEQ_HEAD "HEADNAME" "TYPE"
 .Fn CIRCLEQ_INIT "CIRCLEQ_HEAD *head"
 .Fn CIRCLEQ_INSERT_AFTER "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
@@ -239,6 +243,8 @@ Tail queues add the following functionality:
 .Bl -enum -compact -offset indent
 .It
 Entries can be added at the end of a list.
+.It
+They may be traversed backwards, from tail to head.
 .El
 However:
 .Bl -enum -compact -offset indent
@@ -764,6 +770,13 @@ in the forward direction, assigning each element in turn to
 .Fa var .
 .Pp
 The macro
+.Nm TAILQ_FOREACH_REVERSE
+traverses the tail queue referenced by
+.Fa head
+in the reverse direction, assigning each element in turn to
+.Fa var .
+.Pp
+The macro
 .Nm TAILQ_INIT
 initializes the tail queue referenced by
 .Fa head .
@@ -841,6 +854,9 @@ TAILQ_REMOVE(&head, n2, entries);	/* Deletion. */
 free(n2);
 					/* Forward traversal. */
 TAILQ_FOREACH(np, &head, entries)
+	np-> ...
+					/* Reverse traversal. */
+TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries)
 	np-> ...
 					/* TailQ Deletion. */
 while (!TAILQ_EMPTY(head)) {
@@ -914,6 +930,13 @@ in the forward direction, assigning each element in turn to
 .Fa var .
 .Pp
 The macro
+.Nm CICRLEQ_FOREACH_REVERSE
+traverses the circle queue referenced by
+.Fa head
+in the reverse direction, assigning each element in turn to
+.Fa var .
+.Pp
+The macro
 .Nm CIRCLEQ_INIT
 initializes the circular queue referenced by
 .Fa head .
@@ -991,7 +1014,7 @@ free(n1);
 CIRCLEQ_FOREACH(np, &head, entries)
 	np-> ...
 					/* Reverse traversal. */
-for (np = CIRCLEQ_LAST(&head); np != (void *)&head; np = CIRCLEQ_PREV(np->entries))
+CIRCLEQ_FOREACH_REVERSE(np, &head, entries)
 	np-> ...
 					/* CircleQ Deletion. */
 while (CIRCLEQ_FIRST(&head) != (void *)&head) {