mirror of https://github.com/mkerrisk/man-pages
circleq.3: ffix: Use man markup
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Alejandro Colomar
Michael Kerrisk
parent
0d1891f3b6
commit
086acf39f1
257
man3/circleq.3
257
man3/circleq.3
|
|
@ -31,61 +31,86 @@
|
|||
.\"
|
||||
.TH CIRCLEQ 3 2020-10-21 "GNU" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
.Nm CIRCLEQ_EMPTY ,
|
||||
.Nm CIRCLEQ_ENTRY ,
|
||||
.Nm CIRCLEQ_FIRST ,
|
||||
.Nm CIRCLEQ_FOREACH ,
|
||||
.Nm CIRCLEQ_FOREACH_REVERSE ,
|
||||
.Nm CIRCLEQ_HEAD ,
|
||||
.Nm CIRCLEQ_HEAD_INITIALIZER ,
|
||||
.Nm CIRCLEQ_INIT ,
|
||||
.Nm CIRCLEQ_INSERT_AFTER ,
|
||||
.Nm CIRCLEQ_INSERT_BEFORE ,
|
||||
.Nm CIRCLEQ_INSERT_HEAD ,
|
||||
.Nm CIRCLEQ_INSERT_TAIL ,
|
||||
.Nm CIRCLEQ_LAST ,
|
||||
.Nm CIRCLEQ_LOOP_NEXT ,
|
||||
.Nm CIRCLEQ_LOOP_PREV ,
|
||||
.Nm CIRCLEQ_NEXT ,
|
||||
.Nm CIRCLEQ_PREV ,
|
||||
.Nm CIRCLEQ_REMOVE
|
||||
CIRCLEQ_EMPTY,
|
||||
CIRCLEQ_ENTRY,
|
||||
CIRCLEQ_FIRST,
|
||||
CIRCLEQ_FOREACH,
|
||||
CIRCLEQ_FOREACH_REVERSE,
|
||||
CIRCLEQ_HEAD,
|
||||
CIRCLEQ_HEAD_INITIALIZER,
|
||||
CIRCLEQ_INIT,
|
||||
CIRCLEQ_INSERT_AFTER,
|
||||
CIRCLEQ_INSERT_BEFORE,
|
||||
CIRCLEQ_INSERT_HEAD,
|
||||
CIRCLEQ_INSERT_TAIL,
|
||||
CIRCLEQ_LAST,
|
||||
CIRCLEQ_LOOP_NEXT,
|
||||
CIRCLEQ_LOOP_PREV,
|
||||
CIRCLEQ_NEXT,
|
||||
CIRCLEQ_PREV,
|
||||
CIRCLEQ_REMOVE
|
||||
.SH SYNOPSIS
|
||||
.In sys/queue.h
|
||||
.\"
|
||||
.Fn CIRCLEQ_EMPTY "CIRCLEQ_HEAD *head"
|
||||
.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_HEAD_INITIALIZER "CIRCLEQ_HEAD head"
|
||||
.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_LAST "CIRCLEQ_HEAD *head"
|
||||
.Fn CIRCLEQ_LOOP_NEXT "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.Fn CIRCLEQ_LOOP_PREV "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.Fn CIRCLEQ_NEXT "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.Fn CIRCLEQ_PREV "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.nf
|
||||
.B #include <sys/queue.h>
|
||||
.PP
|
||||
.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ");"
|
||||
.PP
|
||||
.B CIRCLEQ_ENTRY(TYPE);
|
||||
.PP
|
||||
.BI "CIRCLEQ_ENTRY *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ");"
|
||||
.PP
|
||||
.BI "CIRCLEQ_FOREACH(TYPE *" var ", CIRCLEQ_HEAD *" head ", CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "CIRCLEQ_FOREACH_REVERSE(TYPE *" var ", CIRCLEQ_HEAD *" head ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.B CIRCLEQ_HEAD(HEADNAME, TYPE);
|
||||
.PP
|
||||
.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", TYPE *" listelm ", TYPE *" elm ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", TYPE *" listelm ", TYPE *" elm ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "CIRCLEQ_ENTRY *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
|
||||
.BI " CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "CIRCLEQ_ENTRY *CIRCLEQ_NEXT(TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "CIRCLEQ_ENTRY *CIRCLEQ_PREV(TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
|
||||
.PP
|
||||
.BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
|
||||
.SH DESCRIPTION
|
||||
In the macro definitions,
|
||||
.Fa TYPE
|
||||
.I TYPE
|
||||
is the name of a user-defined structure,
|
||||
that must contain a field of type
|
||||
.Li CIRCLEQ_ENTRY ,
|
||||
.IR CIRCLEQ_ENTRY ,
|
||||
named
|
||||
.Fa NAME .
|
||||
.IR NAME .
|
||||
The argument
|
||||
.Fa HEADNAME
|
||||
.I HEADNAME
|
||||
is the name of a user-defined structure that must be declared
|
||||
using the macro
|
||||
.Li CIRCLEQ_HEAD .
|
||||
.Ss Circular queues
|
||||
.BR CIRCLEQ_HEAD ().
|
||||
.PP
|
||||
A circular queue is headed by a structure defined by the
|
||||
.Nm CIRCLEQ_HEAD
|
||||
.BR CIRCLEQ_HEAD ()
|
||||
macro.
|
||||
This structure contains a pair of pointers,
|
||||
one to the first element in the circular queue and the other to
|
||||
|
|
@ -96,140 +121,144 @@ New elements can be added to the circular queue after an existing element,
|
|||
before an existing element, at the head of the circular queue,
|
||||
or at the end of the circular queue.
|
||||
A
|
||||
.Fa CIRCLEQ_HEAD
|
||||
.I CIRCLEQ_HEAD
|
||||
structure is declared as follows:
|
||||
.Bd -literal -offset indent
|
||||
.PP
|
||||
.in +4
|
||||
.EX
|
||||
CIRCLEQ_HEAD(HEADNAME, TYPE) head;
|
||||
.Ed
|
||||
.Pp
|
||||
.EE
|
||||
.in
|
||||
.PP
|
||||
where
|
||||
.Li HEADNAME
|
||||
.I HEADNAME
|
||||
is the name of the structure to be defined, and
|
||||
.Li TYPE
|
||||
.I 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:
|
||||
.Bd -literal -offset indent
|
||||
.PP
|
||||
.in +4
|
||||
.EX
|
||||
struct HEADNAME *headp;
|
||||
.Ed
|
||||
.Pp
|
||||
.EE
|
||||
.in
|
||||
.PP
|
||||
(The names
|
||||
.Li head
|
||||
.I head
|
||||
and
|
||||
.Li headp
|
||||
.I headp
|
||||
are user selectable.)
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_HEAD_INITIALIZER
|
||||
.BR CIRCLEQ_HEAD_INITIALIZER ()
|
||||
evaluates to an initializer for the circular queue
|
||||
.Fa head .
|
||||
.Pp
|
||||
.IR head .
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_EMPTY
|
||||
.BR CIRCLEQ_EMPTY ()
|
||||
evaluates to true if there are no items on the circular queue.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_ENTRY
|
||||
.BR CIRCLEQ_ENTRY ()
|
||||
declares a structure that connects the elements in
|
||||
the circular queue.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_FIRST
|
||||
.BR CIRCLEQ_FIRST ()
|
||||
returns the first item on the circular queue.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_FOREACH
|
||||
.BR CIRCLEQ_FOREACH ()
|
||||
traverses the circular queue referenced by
|
||||
.Fa head
|
||||
.I head
|
||||
in the forward direction, assigning each element in turn to
|
||||
.Fa var .
|
||||
.Fa var
|
||||
.IR var .
|
||||
.I var
|
||||
is set to
|
||||
.Fa &head
|
||||
.I &head
|
||||
if the loop completes normally, or if there were no elements.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_FOREACH_REVERSE
|
||||
.BR CIRCLEQ_FOREACH_REVERSE ()
|
||||
traverses the circular queue referenced by
|
||||
.Fa head
|
||||
.I head
|
||||
in the reverse direction, assigning each element in turn to
|
||||
.Fa var .
|
||||
.Pp
|
||||
.IR var .
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_INIT
|
||||
.BR CIRCLEQ_INIT ()
|
||||
initializes the circular queue referenced by
|
||||
.Fa head .
|
||||
.Pp
|
||||
.IR head .
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_HEAD
|
||||
.BR CIRCLEQ_INSERT_HEAD ()
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
.I elm
|
||||
at the head of the circular queue.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_TAIL
|
||||
.BR CIRCLEQ_INSERT_TAIL ()
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
.I elm
|
||||
at the end of the circular queue.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_AFTER
|
||||
.BR CIRCLEQ_INSERT_AFTER ()
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
.I elm
|
||||
after the element
|
||||
.Fa listelm .
|
||||
.Pp
|
||||
.IR listelm .
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_BEFORE
|
||||
.BR CIRCLEQ_INSERT_BEFORE ()
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
.I elm
|
||||
before the element
|
||||
.Fa listelm .
|
||||
.Pp
|
||||
.IR listelm .
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_LAST
|
||||
.BR CIRCLEQ_LAST ()
|
||||
returns the last item on the circular queue.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_NEXT
|
||||
.BR CIRCLEQ_NEXT ()
|
||||
returns the next item on the circular queue, or
|
||||
.Fa &head
|
||||
.I &head
|
||||
if this item is the last one.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_PREV
|
||||
.BR CIRCLEQ_PREV ()
|
||||
returns the previous item on the circular queue, or
|
||||
.Fa &head
|
||||
.I &head
|
||||
if this item is the first one.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_LOOP_NEXT
|
||||
.BR CIRCLEQ_LOOP_NEXT ()
|
||||
returns the next item on the circular queue.
|
||||
If
|
||||
.Fa elm
|
||||
.I elm
|
||||
is the last element on the circular queue, the first element is returned.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_LOOP_PREV
|
||||
.BR CIRCLEQ_LOOP_PREV ()
|
||||
returns the previous item on the circular queue.
|
||||
If
|
||||
.Fa elm
|
||||
.I elm
|
||||
is the first element on the circular queue, the last element is returned.
|
||||
.Pp
|
||||
.PP
|
||||
The macro
|
||||
.Nm CIRCLEQ_REMOVE
|
||||
.BR CIRCLEQ_REMOVE ()
|
||||
removes the element
|
||||
.Fa elm
|
||||
.I elm
|
||||
from the circular queue.
|
||||
.SH RETURN VALUE
|
||||
.SH CONFORMING TO
|
||||
Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
|
||||
Present on the BSDs
|
||||
(CIRCLEQ macros first appeared in
|
||||
.Bx 4.4 ).
|
||||
(CIRCLEQ macros first appeared in 4.4BSD).
|
||||
.SH BUGS
|
||||
.SH EXAMPLES
|
||||
.Ss Circular queue example
|
||||
.Bd -literal
|
||||
.EX
|
||||
#include <stddef.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
|
|
@ -283,5 +312,5 @@ main(void)
|
|||
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.Ed
|
||||
.EE
|
||||
.SH SEE ALSO
|
||||
|
|
|
|||
Loading…
Reference in New Issue