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

slist.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 2020-10-22 14:38:19 +02:00 committed by Michael Kerrisk
parent 6a1c4d6fc4
commit bb8164dec0
1 changed files with 140 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

260
man3/slist.3
View File

@ -31,60 +31,77 @@
.\" .\"
.TH SLIST 3 2020-10-21 "GNU" "Linux Programmer's Manual" .TH SLIST 3 2020-10-21 "GNU" "Linux Programmer's Manual"
.SH NAME .SH NAME
.Nm SLIST_EMPTY , SLIST_EMPTY,
.Nm SLIST_ENTRY , SLIST_ENTRY,
.Nm SLIST_FIRST , SLIST_FIRST,
.Nm SLIST_FOREACH , SLIST_FOREACH,
.\" .Nm SLIST_FOREACH_FROM , .\"SLIST_FOREACH_FROM,
.\" .Nm SLIST_FOREACH_FROM_SAFE , .\"SLIST_FOREACH_FROM_SAFE,
.\" .Nm SLIST_FOREACH_SAFE , .\"SLIST_FOREACH_SAFE,
.Nm SLIST_HEAD , SLIST_HEAD,
.Nm SLIST_HEAD_INITIALIZER , SLIST_HEAD_INITIALIZER,
.Nm SLIST_INIT , SLIST_INIT,
.Nm SLIST_INSERT_AFTER , SLIST_INSERT_AFTER,
.Nm SLIST_INSERT_HEAD , SLIST_INSERT_HEAD,
.Nm SLIST_NEXT , SLIST_NEXT,
.Nm SLIST_REMOVE , SLIST_REMOVE,
.\" .Nm SLIST_REMOVE_AFTER , .\"SLIST_REMOVE_AFTER,
.Nm SLIST_REMOVE_HEAD , SLIST_REMOVE_HEAD
.\" .Nm SLIST_SWAP , .\"SLIST_SWAP
.SH SYNOPSIS .SH SYNOPSIS
.In sys/queue.h .nf
.\" .B #include <sys/queue.h>
.Fn SLIST_EMPTY "SLIST_HEAD *head" .PP
.Fn SLIST_ENTRY "TYPE" .BI "int SLIST_EMPTY(SLIST_HEAD *" head ");"
.Fn SLIST_FIRST "SLIST_HEAD *head" .PP
.Fn SLIST_FOREACH "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" .B SLIST_ENTRY(TYPE);
.\" .Fn SLIST_FOREACH_FROM "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" .PP
.\" .Fn SLIST_FOREACH_FROM_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" .BI "SLIST_ENTRY *SLIST_FIRST(SLIST_HEAD *" head ");"
.\" .Fn SLIST_FOREACH_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" .PP
.Fn SLIST_HEAD "HEADNAME" "TYPE" .BI "SLIST_FOREACH(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
.Fn SLIST_HEAD_INITIALIZER "SLIST_HEAD head" .\".PP
.Fn SLIST_INIT "SLIST_HEAD *head" .\".BI "SLIST_FOREACH_FROM(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
.Fn SLIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "SLIST_ENTRY NAME" .\".PP
.Fn SLIST_INSERT_HEAD "SLIST_HEAD *head" "TYPE *elm" "SLIST_ENTRY NAME" .\".BI "SLIST_FOREACH_FROM_SAFE(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", TYPE *" temp_var ");"
.Fn SLIST_NEXT "TYPE *elm" "SLIST_ENTRY NAME" .\".PP
.Fn SLIST_REMOVE "SLIST_HEAD *head" "TYPE *elm" "TYPE" "SLIST_ENTRY NAME" .\".BI "SLIST_FOREACH_SAFE(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", TYPE *" temp_var ");"
.\" .Fn SLIST_REMOVE_AFTER "TYPE *elm" "SLIST_ENTRY NAME" .PP
.Fn SLIST_REMOVE_HEAD "SLIST_HEAD *head" "SLIST_ENTRY NAME" .B SLIST_HEAD(HEADNAME, TYPE);
.\" .Fn SLIST_SWAP "SLIST_HEAD *head1" "SLIST_HEAD *head2" "SLIST_ENTRY NAME" .PP
.\" .BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head ");"
.PP
.BI "void SLIST_INIT(SLIST_HEAD *" head ");"
.PP
.BI "void SLIST_INSERT_AFTER(TYPE *" listelm ", TYPE *" elm ", SLIST_ENTRY " NAME ");"
.PP
.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head ", TYPE *" elm ", SLIST_ENTRY " NAME ");"
.PP
.BI "SLIST_ENTRY *SLIST_NEXT(TYPE *" elm ", SLIST_ENTRY " NAME ");"
.PP
.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", TYPE *" elm ", SLIST_ENTRY " NAME ");"
.\".PP
.\".BI "void SLIST_REMOVE_AFTER(TYPE *" elm ", SLIST_ENTRY " NAME ");"
.PP
.BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
.\".PP
.\".BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 ", SLIST_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 SLIST_ENTRY , .IR SLIST_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 SLIST_HEAD . .BR SLIST_HEAD ().
.Ss Singly-linked lists .PP
A singly-linked list is headed by a structure defined by the A singly-linked list is headed by a structure defined by the
.Nm SLIST_HEAD .BR SLIST_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,159 +110,162 @@ overhead at the expense of O(n) removal for arbitrary elements.
New elements can be added to the list after an existing element or New elements can be added to the list after an existing element or
at the head of the list. at the head of the list.
An An
.Fa SLIST_HEAD .I SLIST_HEAD
structure is declared as follows: structure is declared as follows:
.Bd -literal -offset indent .PP
.in +4
.EX
SLIST_HEAD(HEADNAME, TYPE) head; SLIST_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 SLIST_HEAD_INITIALIZER .BR SLIST_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 SLIST_EMPTY .BR SLIST_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 SLIST_ENTRY .BR SLIST_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 SLIST_FIRST .BR SLIST_FIRST ()
returns the first element in the list or NULL if the list is empty. returns the first element in the list or NULL if the list is empty.
.Pp .PP
The macro The macro
.Nm SLIST_FOREACH .BR SLIST_FOREACH ()
traverses the list referenced by traverses the list referenced by
.Fa head .I head
in the forward direction, assigning each element in in the forward direction, assigning each element in
turn to turn to
.Fa var . .IR var .
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm SLIST_FOREACH_FROM .\" .BR SLIST_FOREACH_FROM ()
.\" behaves identically to .\" behaves identically to
.\" .Nm SLIST_FOREACH .\" .BR SLIST_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 SLIST element and begins the loop at .\" as a previously found SLIST element and begins the loop at
.\" .Fa var .\" .I var
.\" instead of the first element in the SLIST referenced by .\" instead of the first element in the SLIST referenced by
.\" .Fa head . .\" .IR head .
.\" .Pp .\" .Pp
.\" The macro .\" The macro
.\" .Nm SLIST_FOREACH_SAFE .\" .BR SLIST_FOREACH_SAFE ()
.\" traverses the list referenced by .\" traverses the list referenced by
.\" .Fa head .\" .I head
.\" in the forward direction, assigning each element in .\" in the forward direction, assigning each element in
.\" turn to .\" turn to
.\" .Fa var . .\" .IR var .
.\" However, unlike .\" However, unlike
.\" .Fn SLIST_FOREACH .\" .BR SLIST_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 SLIST_FOREACH_FROM_SAFE .\" .BR SLIST_FOREACH_FROM_SAFE ()
.\" behaves identically to .\" behaves identically to
.\" .Nm SLIST_FOREACH_SAFE .\" .BR SLIST_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 SLIST element and begins the loop at .\" as a previously found SLIST element and begins the loop at
.\" .Fa var .\" .I var
.\" instead of the first element in the SLIST referenced by .\" instead of the first element in the SLIST referenced by
.\" .Fa head . .\" .IR head .
.Pp .PP
The macro The macro
.Nm SLIST_INIT .BR SLIST_INIT ()
initializes the list referenced by initializes the list referenced by
.Fa head . .IR head .
.Pp .PP
The macro The macro
.Nm SLIST_INSERT_HEAD .BR SLIST_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 SLIST_INSERT_AFTER .BR SLIST_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 SLIST_NEXT .BR SLIST_NEXT ()
returns the next element in the list. returns the next element in the list.
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm SLIST_REMOVE_AFTER .\" .BR SLIST_REMOVE_AFTER ()
.\" removes the element after .\" removes the element after
.\" .Fa elm .\" .I elm
.\" from the list. .\" from the list.
.\" Unlike .\" Unlike
.\" .Fa SLIST_REMOVE , .\" .IR SLIST_REMOVE ,
.\" this macro does not traverse the entire list. .\" this macro does not traverse the entire list.
.Pp .PP
The macro The macro
.Nm SLIST_REMOVE_HEAD .BR SLIST_REMOVE_HEAD ()
removes the element removes the element
.Fa elm .I elm
from the head of the list. from the head of the list.
For optimum efficiency, For optimum efficiency,
elements being removed from the head of the list should explicitly use elements being removed from the head of the list should explicitly use
this macro instead of the generic this macro instead of the generic
.Fa SLIST_REMOVE .I SLIST_REMOVE
macro. macro.
.Pp .PP
The macro The macro
.Nm SLIST_REMOVE .BR SLIST_REMOVE ()
removes the element removes the element
.Fa elm .I elm
from the list. from the list.
.\" .Pp .\" .PP
.\" The macro .\" The macro
.\" .Nm SLIST_SWAP .\" .BR SLIST_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
(SLIST macros first appeared in (SLIST macros first appeared in 4.4BSD).
.Bx 4.4 ).
.SH BUGS .SH BUGS
.SH EXAMPLES .SH EXAMPLES
.Ss Singly-linked list example .EX
.Bd -literal
#include <stddef.h> #include <stddef.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
@ -299,5 +319,5 @@ main(void)
exit(EXIT_SUCCESS); exit(EXIT_SUCCESS);
} }
.Ed .EE
.SH SEE ALSO .SH SEE ALSO