[4/8] queue.3, stailq.3: DESCRIPTION: Move stailq specific code from queue.3 to stailq.3
Commit Message
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/queue.3 | 177 --------------------------------------------------
man3/stailq.3 | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 177 insertions(+), 177 deletions(-)
@@ -245,183 +245,6 @@ or
.Li CIRCLEQ_HEAD .
See the examples below for further explanation of how these
macros are used.
-.Ss Singly-linked tail queues
-A singly-linked tail queue is headed by a structure defined by the
-.Nm STAILQ_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 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 tail queue after an existing element,
-at the head of the tail queue, or at the end of the tail queue.
-A
-.Fa STAILQ_HEAD
-structure is declared as follows:
-.Bd -literal -offset indent
-STAILQ_HEAD(HEADNAME, TYPE) head;
-.Ed
-.Pp
-where
-.Li HEADNAME
-is the name of the structure to be defined, and
-.Li 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:
-.Bd -literal -offset indent
-struct HEADNAME *headp;
-.Ed
-.Pp
-(The names
-.Li head
-and
-.Li headp
-are user selectable.)
-.Pp
-The macro
-.Nm STAILQ_HEAD_INITIALIZER
-evaluates to an initializer for the tail queue
-.Fa head .
-.Pp
-The macro
-.Nm STAILQ_CONCAT
-concatenates the tail queue headed by
-.Fa head2
-onto the end of the one headed by
-.Fa head1
-removing all entries from the former.
-.Pp
-The macro
-.Nm STAILQ_EMPTY
-evaluates to true if there are no items on the tail queue.
-.Pp
-The macro
-.Nm STAILQ_ENTRY
-declares a structure that connects the elements in
-the tail queue.
-.Pp
-The macro
-.Nm STAILQ_FIRST
-returns the first item on the tail queue or NULL if the tail queue
-is empty.
-.Pp
-The macro
-.Nm STAILQ_FOREACH
-traverses the tail queue referenced by
-.Fa head
-in the forward direction, assigning each element
-in turn to
-.Fa var .
-.\" .Pp
-.\" The macro
-.\" .Nm STAILQ_FOREACH_FROM
-.\" behaves identically to
-.\" .Nm STAILQ_FOREACH
-.\" when
-.\" .Fa var
-.\" is NULL, else it treats
-.\" .Fa var
-.\" as a previously found STAILQ element and begins the loop at
-.\" .Fa var
-.\" instead of the first element in the STAILQ referenced by
-.\" .Fa head .
-.\" .Pp
-.\" The macro
-.\" .Nm STAILQ_FOREACH_SAFE
-.\" traverses the tail queue referenced by
-.\" .Fa head
-.\" in the forward direction, assigning each element
-.\" in turn to
-.\" .Fa var .
-.\" However, unlike
-.\" .Fn STAILQ_FOREACH
-.\" here it is permitted to both remove
-.\" .Fa var
-.\" as well as free it from within the loop safely without interfering with the
-.\" traversal.
-.\" .Pp
-.\" The macro
-.\" .Nm STAILQ_FOREACH_FROM_SAFE
-.\" behaves identically to
-.\" .Nm STAILQ_FOREACH_SAFE
-.\" when
-.\" .Fa var
-.\" is NULL, else it treats
-.\" .Fa var
-.\" as a previously found STAILQ element and begins the loop at
-.\" .Fa var
-.\" instead of the first element in the STAILQ referenced by
-.\" .Fa head .
-.Pp
-The macro
-.Nm STAILQ_INIT
-initializes the tail queue referenced by
-.Fa head .
-.Pp
-The macro
-.Nm STAILQ_INSERT_HEAD
-inserts the new element
-.Fa elm
-at the head of the tail queue.
-.Pp
-The macro
-.Nm STAILQ_INSERT_TAIL
-inserts the new element
-.Fa elm
-at the end of the tail queue.
-.Pp
-The macro
-.Nm STAILQ_INSERT_AFTER
-inserts the new element
-.Fa elm
-after the element
-.Fa listelm .
-.\" .Pp
-.\" The macro
-.\" .Nm STAILQ_LAST
-.\" returns the last item on the tail queue.
-.\" If the tail queue is empty the return value is
-.\" .Dv NULL .
-.Pp
-The macro
-.Nm STAILQ_NEXT
-returns the next item on the tail queue, or NULL this item is the last.
-.\" .Pp
-.\" The macro
-.\" .Nm STAILQ_REMOVE_AFTER
-.\" removes the element after
-.\" .Fa elm
-.\" from the tail queue.
-.\" Unlike
-.\" .Fa STAILQ_REMOVE ,
-.\" this macro does not traverse the entire tail queue.
-.Pp
-The macro
-.Nm STAILQ_REMOVE_HEAD
-removes the element at the head of the tail queue.
-For optimum efficiency,
-elements being removed from the head of the tail queue should
-use this macro explicitly rather than the generic
-.Fa STAILQ_REMOVE
-macro.
-.Pp
-The macro
-.Nm STAILQ_REMOVE
-removes the element
-.Fa elm
-from the tail queue.
-.\" .Pp
-.\" The macro
-.\" .Nm STAILQ_SWAP
-.\" swaps the contents of
-.\" .Fa head1
-.\" and
-.\" .Fa head2 .
-.Pp
-See the EXAMPLES section below for an example program
-using a singly-linked tail queue.
.Ss Tail queues
A tail queue is headed by a structure defined by the
.Nm TAILQ_HEAD
@@ -74,6 +74,183 @@
.\" .Fn STAILQ_SWAP "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" "STAILQ_ENTRY NAME"
.\"
.SH DESCRIPTION
+.Ss Singly-linked tail queues
+A singly-linked tail queue is headed by a structure defined by the
+.Nm STAILQ_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 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 tail queue after an existing element,
+at the head of the tail queue, or at the end of the tail queue.
+A
+.Fa STAILQ_HEAD
+structure is declared as follows:
+.Bd -literal -offset indent
+STAILQ_HEAD(HEADNAME, TYPE) head;
+.Ed
+.Pp
+where
+.Li HEADNAME
+is the name of the structure to be defined, and
+.Li 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:
+.Bd -literal -offset indent
+struct HEADNAME *headp;
+.Ed
+.Pp
+(The names
+.Li head
+and
+.Li headp
+are user selectable.)
+.Pp
+The macro
+.Nm STAILQ_HEAD_INITIALIZER
+evaluates to an initializer for the tail queue
+.Fa head .
+.Pp
+The macro
+.Nm STAILQ_CONCAT
+concatenates the tail queue headed by
+.Fa head2
+onto the end of the one headed by
+.Fa head1
+removing all entries from the former.
+.Pp
+The macro
+.Nm STAILQ_EMPTY
+evaluates to true if there are no items on the tail queue.
+.Pp
+The macro
+.Nm STAILQ_ENTRY
+declares a structure that connects the elements in
+the tail queue.
+.Pp
+The macro
+.Nm STAILQ_FIRST
+returns the first item on the tail queue or NULL if the tail queue
+is empty.
+.Pp
+The macro
+.Nm STAILQ_FOREACH
+traverses the tail queue referenced by
+.Fa head
+in the forward direction, assigning each element
+in turn to
+.Fa var .
+.\" .Pp
+.\" The macro
+.\" .Nm STAILQ_FOREACH_FROM
+.\" behaves identically to
+.\" .Nm STAILQ_FOREACH
+.\" when
+.\" .Fa var
+.\" is NULL, else it treats
+.\" .Fa var
+.\" as a previously found STAILQ element and begins the loop at
+.\" .Fa var
+.\" instead of the first element in the STAILQ referenced by
+.\" .Fa head .
+.\" .Pp
+.\" The macro
+.\" .Nm STAILQ_FOREACH_SAFE
+.\" traverses the tail queue referenced by
+.\" .Fa head
+.\" in the forward direction, assigning each element
+.\" in turn to
+.\" .Fa var .
+.\" However, unlike
+.\" .Fn STAILQ_FOREACH
+.\" here it is permitted to both remove
+.\" .Fa var
+.\" as well as free it from within the loop safely without interfering with the
+.\" traversal.
+.\" .Pp
+.\" The macro
+.\" .Nm STAILQ_FOREACH_FROM_SAFE
+.\" behaves identically to
+.\" .Nm STAILQ_FOREACH_SAFE
+.\" when
+.\" .Fa var
+.\" is NULL, else it treats
+.\" .Fa var
+.\" as a previously found STAILQ element and begins the loop at
+.\" .Fa var
+.\" instead of the first element in the STAILQ referenced by
+.\" .Fa head .
+.Pp
+The macro
+.Nm STAILQ_INIT
+initializes the tail queue referenced by
+.Fa head .
+.Pp
+The macro
+.Nm STAILQ_INSERT_HEAD
+inserts the new element
+.Fa elm
+at the head of the tail queue.
+.Pp
+The macro
+.Nm STAILQ_INSERT_TAIL
+inserts the new element
+.Fa elm
+at the end of the tail queue.
+.Pp
+The macro
+.Nm STAILQ_INSERT_AFTER
+inserts the new element
+.Fa elm
+after the element
+.Fa listelm .
+.\" .Pp
+.\" The macro
+.\" .Nm STAILQ_LAST
+.\" returns the last item on the tail queue.
+.\" If the tail queue is empty the return value is
+.\" .Dv NULL .
+.Pp
+The macro
+.Nm STAILQ_NEXT
+returns the next item on the tail queue, or NULL this item is the last.
+.\" .Pp
+.\" The macro
+.\" .Nm STAILQ_REMOVE_AFTER
+.\" removes the element after
+.\" .Fa elm
+.\" from the tail queue.
+.\" Unlike
+.\" .Fa STAILQ_REMOVE ,
+.\" this macro does not traverse the entire tail queue.
+.Pp
+The macro
+.Nm STAILQ_REMOVE_HEAD
+removes the element at the head of the tail queue.
+For optimum efficiency,
+elements being removed from the head of the tail queue should
+use this macro explicitly rather than the generic
+.Fa STAILQ_REMOVE
+macro.
+.Pp
+The macro
+.Nm STAILQ_REMOVE
+removes the element
+.Fa elm
+from the tail queue.
+.\" .Pp
+.\" The macro
+.\" .Nm STAILQ_SWAP
+.\" swaps the contents of
+.\" .Fa head1
+.\" and
+.\" .Fa head2 .
+.Pp
+See the EXAMPLES section below for an example program
+using a singly-linked tail queue.
.SH RETURN VALUE
.SH CONFORMING TO
.SH BUGS