LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

list.3: ffix: Use man markup 

list.3: NAME: ffix: Use man markup
list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: ffix: Use man markup
list.3: DESCRIPTION: ffix: Use man markup
list.3: CONFORMING TO: ffix: Use man markup
list.3: EXAMPLES: 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 2020-10-20 23:31:05 +02:00 committed by Michael Kerrisk
parent 481854f548
commit 87241f17f6
1 changed files with 141 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
man3/list.3
View File

@ -31,60 +31,77 @@
.\" .\"
.TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" .TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual"
.SH NAME .SH NAME
.Nm LIST_EMPTY , LIST_EMPTY,
.Nm LIST_ENTRY , LIST_ENTRY,
.Nm LIST_FIRST , LIST_FIRST,
.Nm LIST_FOREACH , LIST_FOREACH,
.\" .Nm LIST_FOREACH_FROM , .\"LIST_FOREACH_FROM,
.\" .Nm LIST_FOREACH_SAFE , .\"LIST_FOREACH_SAFE,
.\" .Nm LIST_FOREACH_FROM_SAFE , .\"LIST_FOREACH_FROM_SAFE,
.Nm LIST_HEAD , LIST_HEAD,
.Nm LIST_HEAD_INITIALIZER , LIST_HEAD_INITIALIZER,
.Nm LIST_INIT , LIST_INIT,
.Nm LIST_INSERT_AFTER , LIST_INSERT_AFTER,
.Nm LIST_INSERT_BEFORE , LIST_INSERT_BEFORE,
.Nm LIST_INSERT_HEAD , LIST_INSERT_HEAD,
.Nm LIST_NEXT , LIST_NEXT,
.\" .Nm LIST_PREV , LIST_PREV,
.Nm LIST_REMOVE , LIST_REMOVE
.\" .Nm LIST_SWAP , .\"LIST_SWAP
.SH SYNOPSIS .SH SYNOPSIS
.In sys/queue.h .nf
.\" .B #include <sys/queue.h>
.Fn LIST_EMPTY "LIST_HEAD *head" .PP
.Fn LIST_ENTRY "TYPE" .BI "int LIST_EMPTY(LIST_HEAD *" head ");"
.Fn LIST_FIRST "LIST_HEAD *head" .PP
.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" .B LIST_ENTRY(TYPE);
.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" .PP
.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" .BI "LIST_ENTRY *LIST_FIRST(LIST_HEAD *" head ");"
.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" .PP
.Fn LIST_HEAD "HEADNAME" "TYPE" .BI "LIST_FOREACH(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" .\".PP
.Fn LIST_INIT "LIST_HEAD *head" .\".BI "LIST_FOREACH_FROM(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" .\".PP
.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" .\".BI "LIST_FOREACH_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");"
.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" .\".PP
.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" .\".BI "LIST_FOREACH_FROM_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");"
.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" .PP
.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" .B LIST_HEAD(HEADNAME, TYPE);
.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .PP
.\" .BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head ");"
.PP
.BI "void LIST_INIT(LIST_HEAD *" head ");"
.PP
.BI "void LIST_INSERT_AFTER(TYPE *" listelm ", TYPE *" elm ", LIST_ENTRY " NAME ");"
.PP
.BI "void LIST_INSERT_BEFORE(TYPE *" listelm ", TYPE *" elm ", LIST_ENTRY " NAME ");"
.PP
.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ", TYPE *" elm ", LIST_ENTRY " NAME ");"
.PP
.BI "LIST_ENTRY *LIST_NEXT(TYPE *" elm ", LIST_ENTRY " NAME ");"
.\".PP
.\".BI "LIST_ENTRY LIST_PREV(TYPE *" elm ", LIST_HEAD *" head ", TYPE, LIST_ENTRY " NAME ");"
.PP
.BI "void LIST_REMOVE(TYPE *" elm ", LIST_ENTRY " NAME ");"
.\".PP
.\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", TYPE, LIST_ENTRY " NAME ");"
.fi
.SH DESCRIPTION .SH DESCRIPTION
In the macro definitions, In the macro definitions,
.Fa TYPE .I TYPE
is the name of a user defined structure, is the name of a user defined structure,
that must contain a field of type that must contain a field of type
.Li LIST_ENTRY , .IR LIST_ENTRY ,
named named
.Fa NAME . .IR NAME .
The argument The argument
.Fa HEADNAME .IR HEADNAME
is the name of a user defined structure that must be declared is the name of a user defined structure that must be declared
using the macro using the macro
.Li LIST_HEAD . .BR LIST_HEAD ().
.Ss Lists .PP
A list is headed by a structure defined by the A list is headed by a structure defined by the
.Nm LIST_HEAD .BR LIST_HEAD ()
macro. macro.
This structure contains a single pointer to the first element This structure contains a single pointer to the first element
on the list. on the list.
@ -93,152 +110,156 @@ removed without traversing the list.
New elements can be added to the list after an existing element, New elements can be added to the list after an existing element,
before an existing element, or at the head of the list. before an existing element, or at the head of the list.
A A
.Fa LIST_HEAD .I LIST_HEAD
structure is declared as follows: structure is declared as follows:
.Bd -literal -offset indent .PP
.in +4
.EX
LIST_HEAD(HEADNAME, TYPE) head; LIST_HEAD(HEADNAME, TYPE) head;
.Ed .EE
.Pp .in
.PP
where where
.Fa HEADNAME .I HEADNAME
is the name of the structure to be defined, and is the name of the structure to be defined, and
.Fa TYPE .I TYPE
is the type of the elements to be linked into the list. 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: A pointer to the head of the list can later be declared as:
.Bd -literal -offset indent .PP
.in +4
.EX
struct HEADNAME *headp; struct HEADNAME *headp;
.Ed .EE
.Pp .in
.PP
(The names (The names
.Li head .I head
and and
.Li headp .I headp
are user selectable.) are user selectable.)
.Pp .PP
The macro The macro
.Nm LIST_HEAD_INITIALIZER .BR LIST_HEAD_INITIALIZER ()
evaluates to an initializer for the list evaluates to an initializer for the list
.Fa head . .IR head .
.Pp .PP
The macro The macro
.Nm LIST_EMPTY .BR LIST_EMPTY ()
evaluates to true if there are no elements in the list. evaluates to true if there are no elements in the list.
.Pp .PP
The macro The macro
.Nm LIST_ENTRY .BR LIST_ENTRY ()
declares a structure that connects the elements in declares a structure that connects the elements in
the list. the list.
.Pp .PP
The macro The macro
.Nm LIST_FIRST .BR LIST_FIRST ()
returns the first element in the list or NULL if the list returns the first element in the list or NULL if the list
is empty. is empty.
.Pp .PP
The macro The macro
.Nm LIST_FOREACH .BR LIST_FOREACH ()
traverses the list referenced by traverses the list referenced by
.Fa head .I head
in the forward direction, assigning each element in turn to in the forward direction, assigning each element in turn to
.Fa var . .IR var .
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm LIST_FOREACH_FROM .\" .BR LIST_FOREACH_FROM ()
.\" behaves identically to .\" behaves identically to
.\" .Nm LIST_FOREACH .\" .BR LIST_FOREACH ()
.\" when .\" when
.\" .Fa var .\" .I var
.\" is NULL, else it treats .\" is NULL, else it treats
.\" .Fa var .\" .I var
.\" as a previously found LIST element and begins the loop at .\" as a previously found LIST element and begins the loop at
.\" .Fa var .\" .I var
.\" instead of the first element in the LIST referenced by .\" instead of the first element in the LIST referenced by
.\" .Fa head . .\" .IR head .
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm LIST_FOREACH_SAFE .\" .BR LIST_FOREACH_SAFE ()
.\" traverses the list referenced by .\" traverses the list referenced by
.\" .Fa head .\" .I head
.\" in the forward direction, assigning each element in turn to .\" in the forward direction, assigning each element in turn to
.\" .Fa var . .\" .IR var .
.\" However, unlike .\" However, unlike
.\" .Fn LIST_FOREACH .\" .BR LIST_FOREACH ()
.\" here it is permitted to both remove .\" here it is permitted to both remove
.\" .Fa var .\" .I var
.\" as well as free it from within the loop safely without interfering with the .\" as well as free it from within the loop safely without interfering with the
.\" traversal. .\" traversal.
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm LIST_FOREACH_FROM_SAFE .\" .BR LIST_FOREACH_FROM_SAFE ()
.\" behaves identically to .\" behaves identically to
.\" .Nm LIST_FOREACH_SAFE .\" .BR LIST_FOREACH_SAFE ()
.\" when .\" when
.\" .Fa var .\" .I var
.\" is NULL, else it treats .\" is NULL, else it treats
.\" .Fa var .\" .I var
.\" as a previously found LIST element and begins the loop at .\" as a previously found LIST element and begins the loop at
.\" .Fa var .\" .I var
.\" instead of the first element in the LIST referenced by .\" instead of the first element in the LIST referenced by
.\" .Fa head . .\" .IR head .
.Pp .PP
The macro The macro
.Nm LIST_INIT .BR LIST_INIT ()
initializes the list referenced by initializes the list referenced by
.Fa head . .IR head .
.Pp .PP
The macro The macro
.Nm LIST_INSERT_HEAD .BR LIST_INSERT_HEAD ()
inserts the new element inserts the new element
.Fa elm .I elm
at the head of the list. at the head of the list.
.Pp .PP
The macro The macro
.Nm LIST_INSERT_AFTER .BR LIST_INSERT_AFTER ()
inserts the new element inserts the new element
.Fa elm .I elm
after the element after the element
.Fa listelm . .IR listelm .
.Pp .PP
The macro The macro
.Nm LIST_INSERT_BEFORE .BR LIST_INSERT_BEFORE ()
inserts the new element inserts the new element
.Fa elm .I elm
before the element before the element
.Fa listelm . .IR listelm .
.Pp .PP
The macro The macro
.Nm LIST_NEXT .BR LIST_NEXT ()
returns the next element in the list, or NULL if this is the last. returns the next element in the list, or NULL if this is the last.
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm LIST_PREV .\" .BR LIST_PREV ()
.\" returns the previous element in the list, or NULL if this is the first. .\" returns the previous element in the list, or NULL if this is the first.
.\" List .\" List
.\" .Fa head .\" .I head
.\" must contain element .\" must contain element
.\" .Fa elm . .\" .IR elm .
.Pp .PP
The macro The macro
.Nm LIST_REMOVE .BR LIST_REMOVE ()
removes the element removes the element
.Fa elm .I elm
from the list. from the list.
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm LIST_SWAP .\" .BR LIST_SWAP ()
.\" swaps the contents of .\" swaps the contents of
.\" .Fa head1 .\" .I head1
.\" and .\" and
.\" .Fa head2 . .\" .IR head2 .
.SH RETURN VALUE .SH RETURN VALUE
.SH CONFORMING TO .SH CONFORMING TO
Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
Present on the BSDs Present on the BSDs
(LIST macros first appeared in (LIST macros first appeared in 4.4BSD).
.Bx 4.4 ).
.SH BUGS .SH BUGS
.SH EXAMPLES .SH EXAMPLES
.Ss List example .EX
.Bd -literal
#include <stddef.h> #include <stddef.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
@ -289,5 +310,5 @@ main(void)
exit(EXIT_SUCCESS); exit(EXIT_SUCCESS);
} }
.Ed .EE
.SH SEE ALSO .SH SEE ALSO