list.3: New page forked from queue.3
cover list.3: New page forked from queue.3
Hi Michael,
I finished one of the pages: list.3
Would you maybe call the page LIST.3 instead?
I didn't write the link pages yet in case we call it differently.
Please comment any improvements you may find.
There are too many patches, so you may prefer to pull from my repo, where I created the tag 'list_v1' for this patchset:
https://github.com/alejandro-colomar/man-pages.git list_v1
As you can probably guess, if you prefer to pull from the repo, I'll create similar tags for revisions of this patchset (e.g., 'list_v2').
Cheers,
Alex
Alejandro Colomar (22):
list.3: New page that will hold the (list) contents of queue.3 list.3, queue.3: NAME: Move code from queue.3 to list.3 list.3: NAME: ffix: Use man markup
list.3: NAME: Add description
list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3 list.3: SYNOPSIS: Copy include from queue.3
list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: Add short description
list.3: DESCRIPTION: Copy description about naming of macros from
queue.3
list.3: DESCRIPTION: Remove unrelated code to adapt to this page
list.3: DESCRIPTION: ffix: Use man markup
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3 list.3: DESCRIPTION: ffix: Use man markup
list.3: DESCRIPTION: Remove line pointing to the EXAMPLES list.3: CONFORMING TO: Copy from queue.3
list.3: CONFORMING TO: Adapt to this page
list.3: CONFORMING TO: ffix: Use man markup
list.3: SEE ALSO: Add insque(3) and queue(3)
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3 list.3: EXAMPLES: ffix: Use man markup
list.3: BUGS: Note LIST_FOREACH() limitations
list.3: RETURN VALUE: Add details about the return value of those
macros that "return" a value
man3/list.3 | 347 +++++++++++++++++++++++++++++++++++++++++++++++++++ man3/queue.3 | 237 ----------------------------------- 2 files changed, 347 insertions(+), 237 deletions(-) create mode 100644 man3/list.3
Signature · 1 line
2.28.0
PATCH 1/22 list.3: New page that will hold the (list) contents of queue.3
--- man3/list.3 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 man3/list.3
man3/list.3 new file +40 -0
@@ -0,0 +1,40 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <[email protected]> +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" +.TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" +.SH NAME +.SH SYNOPSIS +.SH DESCRIPTION +.SH RETURN VALUE +.SH CONFORMING TO +.SH BUGS +.SH EXAMPLES +.SH SEE ALSO
Signature · 1 line
2.28.0
PATCH 2/22 list.3, queue.3: NAME: Move code from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 17 +++++++++++++++++ man3/queue.3 | 17 ----------------- 2 files changed, 17 insertions(+), 17 deletions(-)
man3/list.3 +17 -0
@@ -31,6 +31,23 @@ .\" .TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" .SH NAME +.Nm LIST_EMPTY , +.Nm LIST_ENTRY , +.Nm LIST_FIRST , +.Nm LIST_FOREACH , +.\" .Nm LIST_FOREACH_FROM , +.\" .Nm LIST_FOREACH_SAFE , +.\" .Nm LIST_FOREACH_FROM_SAFE , +.Nm LIST_HEAD , +.Nm LIST_HEAD_INITIALIZER , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_BEFORE , +.Nm LIST_INSERT_HEAD , +.Nm LIST_NEXT , +.\" .Nm LIST_PREV , +.Nm LIST_REMOVE , +.\" .Nm LIST_SWAP , .SH SYNOPSIS .SH DESCRIPTION .SH RETURN VALUE
man3/queue.3 +0 -17
@@ -71,23 +71,6 @@ .Nm STAILQ_REMOVE_HEAD , .Nm STAILQ_REMOVE , .\" .Nm STAILQ_SWAP , -.Nm LIST_EMPTY , -.Nm LIST_ENTRY , -.Nm LIST_FIRST , -.Nm LIST_FOREACH , -.\" .Nm LIST_FOREACH_FROM , -.\" .Nm LIST_FOREACH_SAFE , -.\" .Nm LIST_FOREACH_FROM_SAFE , -.Nm LIST_HEAD , -.Nm LIST_HEAD_INITIALIZER , -.Nm LIST_INIT , -.Nm LIST_INSERT_AFTER , -.Nm LIST_INSERT_BEFORE , -.Nm LIST_INSERT_HEAD , -.Nm LIST_NEXT , -.\" .Nm LIST_PREV , -.Nm LIST_REMOVE , -.\" .Nm LIST_SWAP , .Nm TAILQ_CONCAT , .Nm TAILQ_EMPTY , .Nm TAILQ_ENTRY ,
Signature · 1 line
2.28.0
PATCH 3/22 list.3: NAME: ffix: Use man markup
In reply to Alejandro Colomar--- man3/list.3 | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-)
man3/list.3 +17 -17
@@ -31,23 +31,23 @@ .\" .TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" .SH NAME -.Nm LIST_EMPTY , -.Nm LIST_ENTRY , -.Nm LIST_FIRST , -.Nm LIST_FOREACH , -.\" .Nm LIST_FOREACH_FROM , -.\" .Nm LIST_FOREACH_SAFE , -.\" .Nm LIST_FOREACH_FROM_SAFE , -.Nm LIST_HEAD , -.Nm LIST_HEAD_INITIALIZER , -.Nm LIST_INIT , -.Nm LIST_INSERT_AFTER , -.Nm LIST_INSERT_BEFORE , -.Nm LIST_INSERT_HEAD , -.Nm LIST_NEXT , -.\" .Nm LIST_PREV , -.Nm LIST_REMOVE , -.\" .Nm LIST_SWAP , +LIST_EMPTY, +LIST_ENTRY, +LIST_FIRST, +LIST_FOREACH, +.\"LIST_FOREACH_FROM, +.\"LIST_FOREACH_SAFE, +.\"LIST_FOREACH_FROM_SAFE, +LIST_HEAD, +LIST_HEAD_INITIALIZER, +LIST_INIT, +LIST_INSERT_AFTER, +LIST_INSERT_BEFORE, +LIST_INSERT_HEAD, +LIST_NEXT, +LIST_PREV, +LIST_REMOVE +.\"LIST_SWAP .SH SYNOPSIS .SH DESCRIPTION .SH RETURN VALUE
Signature · 1 line
2.28.0
PATCH 4/22 list.3: NAME: Add description
In reply to Alejandro Colomar--- man3/list.3 | 1 + 1 file changed, 1 insertion(+)
man3/list.3 +1 -0
@@ -48,6 +48,7 @@ LIST_NEXT, LIST_PREV, LIST_REMOVE .\"LIST_SWAP +\- implementation of a doubly-linked list .SH SYNOPSIS .SH DESCRIPTION .SH RETURN VALUE
Signature · 1 line
2.28.0
PATCH 5/22 list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 18 ++++++++++++++++++ man3/queue.3 | 18 ------------------ 2 files changed, 18 insertions(+), 18 deletions(-)
man3/list.3 +18 -0
@@ -50,6 +50,24 @@ LIST_REMOVE .\"LIST_SWAP \- implementation of a doubly-linked list .SH SYNOPSIS +.Fn LIST_EMPTY "LIST_HEAD *head" +.Fn LIST_ENTRY "TYPE" +.Fn LIST_FIRST "LIST_HEAD *head" +.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" +.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" +.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.\" .SH DESCRIPTION .SH RETURN VALUE .SH CONFORMING TO
man3/queue.3 +0 -18
@@ -157,24 +157,6 @@ lists, tail queues, and circular queues .Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" .\" .Fn STAILQ_SWAP "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" "STAILQ_ENTRY NAME" .\" -.Fn LIST_EMPTY "LIST_HEAD *head" -.Fn LIST_ENTRY "TYPE" -.Fn LIST_FIRST "LIST_HEAD *head" -.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.Fn LIST_HEAD "HEADNAME" "TYPE" -.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" -.Fn LIST_INIT "LIST_HEAD *head" -.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" -.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" -.\" .Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" .Fn TAILQ_EMPTY "TAILQ_HEAD *head" .Fn TAILQ_ENTRY "TYPE"
Signature · 1 line
2.28.0
PATCH 6/22 list.3: SYNOPSIS: Copy include from queue.3
In reply to Alejandro Colomar--- man3/list.3 | 2 ++ 1 file changed, 2 insertions(+)
man3/list.3 +2 -0
@@ -50,6 +50,8 @@ LIST_REMOVE .\"LIST_SWAP \- implementation of a doubly-linked list .SH SYNOPSIS +.In sys/queue.h +.\" .Fn LIST_EMPTY "LIST_HEAD *head" .Fn LIST_ENTRY "TYPE" .Fn LIST_FIRST "LIST_HEAD *head"
Signature · 1 line
2.28.0
PATCH 7/22 list.3: SYNOPSIS: ffix: Use man markup
In reply to Alejandro Colomar--- man3/list.3 | 57 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 20 deletions(-)
man3/list.3 +37 -20
@@ -50,26 +50,43 @@ LIST_REMOVE .\"LIST_SWAP \- implementation of a doubly-linked list .SH SYNOPSIS -.In sys/queue.h -.\" -.Fn LIST_EMPTY "LIST_HEAD *head" -.Fn LIST_ENTRY "TYPE" -.Fn LIST_FIRST "LIST_HEAD *head" -.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.Fn LIST_HEAD "HEADNAME" "TYPE" -.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" -.Fn LIST_INIT "LIST_HEAD *head" -.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" -.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" -.\" +.nf +.B #include <sys/queue.h> +.PP +.BI "int LIST_EMPTY(LIST_HEAD *" head ");" +.PP +.B LIST_ENTRY(TYPE); +.PP +.BI "LIST_ENTRY *LIST_FIRST(LIST_HEAD *" head ");" +.PP +.BI "LIST_FOREACH(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");" +.\".PP +.\".BI "LIST_FOREACH_FROM(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");" +.\".PP +.\".BI "LIST_FOREACH_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");" +.\".PP +.\".BI "LIST_FOREACH_FROM_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");" +.PP +.B LIST_HEAD(HEADNAME, TYPE); +.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 RETURN VALUE .SH CONFORMING TO
Signature · 1 line
2.28.0
PATCH 8/22 list.3: DESCRIPTION: Add short description
In reply to Alejandro Colomar--- man3/list.3 | 1 + 1 file changed, 1 insertion(+)
man3/list.3 +1 -0
@@ -88,6 +88,7 @@ LIST_REMOVE .\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", TYPE, LIST_ENTRY " NAME ");" .fi .SH DESCRIPTION +These macros define and operate on doubly-linked lists. .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
Signature · 1 line
2.28.0
PATCH 9/22 list.3: DESCRIPTION: Copy description about naming of macros from queue.3
In reply to Alejandro Colomar--- man3/list.3 | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+)
man3/list.3 +25 -0
@@ -89,6 +89,31 @@ LIST_REMOVE .fi .SH DESCRIPTION These macros define and operate on doubly-linked lists. +.Pp +In the macro definitions, +.Fa TYPE +is the name of a user defined structure, +that must contain a field of type +.Li SLIST_ENTRY , +.Li STAILQ_ENTRY , +.Li LIST_ENTRY , +.Li TAILQ_ENTRY , +or +.Li CIRCLEQ_ENTRY , +named +.Fa NAME . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macros +.Li SLIST_HEAD , +.Li STAILQ_HEAD , +.Li LIST_HEAD , +.Li TAILQ_HEAD , +or +.Li CIRCLEQ_HEAD . +See the examples below for further explanation of how these +macros are used. .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
Signature · 1 line
2.28.0
PATCH 10/22 list.3: DESCRIPTION: Remove unrelated code to adapt to this page
In reply to Alejandro Colomar--- man3/list.3 | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-)
man3/list.3 +2 -14
@@ -94,26 +94,14 @@ In the macro definitions, .Fa TYPE is the name of a user defined structure, that must contain a field of type -.Li SLIST_ENTRY , -.Li STAILQ_ENTRY , .Li LIST_ENTRY , -.Li TAILQ_ENTRY , -or -.Li CIRCLEQ_ENTRY , named .Fa NAME . The argument .Fa HEADNAME is the name of a user defined structure that must be declared -using the macros -.Li SLIST_HEAD , -.Li STAILQ_HEAD , -.Li LIST_HEAD , -.Li TAILQ_HEAD , -or -.Li CIRCLEQ_HEAD . -See the examples below for further explanation of how these -macros are used. +using the macro +.Fa LIST_HEAD . .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
Signature · 1 line
2.28.0
PATCH 11/22 list.3: DESCRIPTION: ffix: Use man markup
In reply to Alejandro Colomar--- man3/list.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
man3/list.3 +6 -6
@@ -89,19 +89,19 @@ LIST_REMOVE .fi .SH DESCRIPTION These macros define and operate on doubly-linked lists. -.Pp +.PP In the macro definitions, -.Fa TYPE +.I TYPE is the name of a user defined structure, that must contain a field of type -.Li LIST_ENTRY , +.IR LIST_ENTRY , named -.Fa NAME . +.IR NAME . The argument -.Fa HEADNAME +.IR HEADNAME is the name of a user defined structure that must be declared using the macro -.Fa LIST_HEAD . +.BR LIST_HEAD (). .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
Signature · 1 line
2.28.0
PATCH 12/22 list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++ man3/queue.3 | 149 --------------------------------------------------- 2 files changed, 149 insertions(+), 149 deletions(-)
man3/list.3 +149 -0
@@ -102,6 +102,155 @@ The argument is the name of a user defined structure that must be declared using the macro .BR LIST_HEAD (). +.Ss Lists +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element, +before an existing element, or at the head of the list. +A +.Fa LIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +LIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +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: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm LIST_EMPTY +evaluates to true if there are no elements in the list. +.Pp +The macro +.Nm LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_FIRST +returns the first element in the list or NULL if the list +is empty. +.Pp +The macro +.Nm LIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_FROM +.\" behaves identically to +.\" .Nm LIST_FOREACH +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found LIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the LIST referenced by +.\" .Fa head . +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_SAFE +.\" traverses the list referenced by +.\" .Fa head +.\" in the forward direction, assigning each element in turn to +.\" .Fa var . +.\" However, unlike +.\" .Fn LIST_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 LIST_FOREACH_FROM_SAFE +.\" behaves identically to +.\" .Nm LIST_FOREACH_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found LIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the LIST referenced by +.\" .Fa head . +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm LIST_NEXT +returns the next element in the list, or NULL if this is the last. +.\" .Pp +.\" The macro +.\" .Nm LIST_PREV +.\" returns the previous element in the list, or NULL if this is the first. +.\" List +.\" .Fa head +.\" must contain element +.\" .Fa elm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +from the list. +.\" .Pp +.\" The macro +.\" .Nm LIST_SWAP +.\" swaps the contents of +.\" .Fa head1 +.\" and +.\" .Fa head2 . +.Pp +See the EXAMPLES section below for an example program using a linked list. .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
man3/queue.3 +0 -149
155 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH 13/22 list.3: DESCRIPTION: ffix: Use man markup
In reply to Alejandro Colomar--- man3/list.3 | 154 +++++++++++++++++++++++++++------------------------- 1 file changed, 80 insertions(+), 74 deletions(-)
man3/list.3 +80 -74
@@ -102,9 +102,9 @@ The argument is the name of a user defined structure that must be declared using the macro .BR LIST_HEAD (). -.Ss Lists +.PP A list is headed by a structure defined by the -.Nm LIST_HEAD +.BR LIST_HEAD () macro. This structure contains a single pointer to the first element on the list.
@@ -113,143 +113,149 @@ removed without traversing the list. New elements can be added to the list after an existing element, before an existing element, or at the head of the list. A -.Fa LIST_HEAD +.I LIST_HEAD structure is declared as follows: -.Bd -literal -offset indent +.PP +.in +4 +.EX LIST_HEAD(HEADNAME, TYPE) head; -.Ed -.Pp +.EE +.in +.PP where -.Fa HEADNAME +.I HEADNAME 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. A pointer to the head of the list 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 LIST_HEAD_INITIALIZER +.BR LIST_HEAD_INITIALIZER () evaluates to an initializer for the list -.Fa head . -.Pp +.IR head . +.PP The macro -.Nm LIST_EMPTY +.BR LIST_EMPTY () evaluates to true if there are no elements in the list. -.Pp +.PP The macro -.Nm LIST_ENTRY +.BR LIST_ENTRY () declares a structure that connects the elements in the list. -.Pp +.PP The macro -.Nm LIST_FIRST +.BR LIST_FIRST () returns the first element in the list or NULL if the list is empty. -.Pp +.PP The macro -.Nm LIST_FOREACH +.BR LIST_FOREACH () traverses the list referenced by -.Fa head +.I head in the forward direction, assigning each element in turn to -.Fa var . -.\" .Pp +.IR var . +.\" .PP .\" The macro -.\" .Nm LIST_FOREACH_FROM +.\" .BR LIST_FOREACH_FROM () .\" behaves identically to -.\" .Nm LIST_FOREACH +.\" .BR LIST_FOREACH () .\" when -.\" .Fa var +.\" .I var .\" is NULL, else it treats -.\" .Fa var +.\" .I var .\" 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 -.\" .Fa head . -.\" .Pp +.\" .IR head . +.\" .PP .\" The macro -.\" .Nm LIST_FOREACH_SAFE +.\" .BR LIST_FOREACH_SAFE () .\" traverses the list referenced by -.\" .Fa head +.\" .I head .\" in the forward direction, assigning each element in turn to -.\" .Fa var . +.\" .IR var . .\" However, unlike -.\" .Fn LIST_FOREACH +.\" .BR LIST_FOREACH () .\" 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 .\" traversal. -.\" .Pp +.\" .PP .\" The macro -.\" .Nm LIST_FOREACH_FROM_SAFE +.\" .BR LIST_FOREACH_FROM_SAFE () .\" behaves identically to -.\" .Nm LIST_FOREACH_SAFE +.\" .BR LIST_FOREACH_SAFE () .\" when -.\" .Fa var +.\" .I var .\" is NULL, else it treats -.\" .Fa var +.\" .I var .\" 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 -.\" .Fa head . -.Pp +.\" .IR head . +.PP The macro -.Nm LIST_INIT +.BR LIST_INIT () initializes the list referenced by -.Fa head . -.Pp +.IR head . +.PP The macro -.Nm LIST_INSERT_HEAD +.BR LIST_INSERT_HEAD () inserts the new element -.Fa elm +.I elm at the head of the list. -.Pp +.PP The macro -.Nm LIST_INSERT_AFTER +.BR LIST_INSERT_AFTER () inserts the new element -.Fa elm +.I elm after the element -.Fa listelm . -.Pp +.IR listelm . +.PP The macro -.Nm LIST_INSERT_BEFORE +.BR LIST_INSERT_BEFORE () inserts the new element -.Fa elm +.I elm before the element -.Fa listelm . -.Pp +.IR listelm . +.PP The macro -.Nm LIST_NEXT +.BR LIST_NEXT () returns the next element in the list, or NULL if this is the last. -.\" .Pp +.\" .PP .\" The macro -.\" .Nm LIST_PREV +.\" .BR LIST_PREV () .\" returns the previous element in the list, or NULL if this is the first. .\" List -.\" .Fa head +.\" .I head .\" must contain element -.\" .Fa elm . -.Pp +.\" .IR elm . +.PP The macro -.Nm LIST_REMOVE +.BR LIST_REMOVE () removes the element -.Fa elm +.I elm from the list. -.\" .Pp +.\" .PP .\" The macro -.\" .Nm LIST_SWAP +.\" .BR LIST_SWAP () .\" swaps the contents of -.\" .Fa head1 +.\" .I head1 .\" and -.\" .Fa head2 . -.Pp +.\" .IR head2 . +.PP See the EXAMPLES section below for an example program using a linked list. .SH RETURN VALUE .SH CONFORMING TO
Signature · 1 line
2.28.0
PATCH 14/22 list.3: DESCRIPTION: Remove line pointing to the EXAMPLES
In reply to Alejandro Colomar--- man3/list.3 | 2 -- 1 file changed, 2 deletions(-)
man3/list.3 +0 -2
@@ -255,8 +255,6 @@ from the list. .\" .I head1 .\" and .\" .IR head2 . -.PP -See the EXAMPLES section below for an example program using a linked list. .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
Signature · 1 line
2.28.0
PATCH 15/22 list.3: CONFORMING TO: Copy from queue.3
In reply to Alejandro Colomar--- man3/list.3 | 5 +++++ 1 file changed, 5 insertions(+)
man3/list.3 +5 -0
@@ -257,6 +257,11 @@ from the list. .\" .IR head2 . .SH RETURN VALUE .SH CONFORMING TO +Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. +Present on the BSDs. +.Nm queue +functions first appeared in +.Bx 4.4 . .SH BUGS .SH EXAMPLES .SH SEE ALSO
Signature · 1 line
2.28.0
PATCH 16/22 list.3: CONFORMING TO: Adapt to this page
In reply to Alejandro Colomar--- man3/list.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)
man3/list.3 +3 -4
@@ -258,10 +258,9 @@ from the list. .SH RETURN VALUE .SH CONFORMING TO Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. -Present on the BSDs. -.Nm queue -functions first appeared in -.Bx 4.4 . +Present on the BSDs +(LIST macros first appeared in +.Bx 4.4 ). .SH BUGS .SH EXAMPLES .SH SEE ALSO
Signature · 1 line
2.28.0
PATCH 17/22 list.3: CONFORMING TO: ffix: Use man markup
In reply to Alejandro Colomar--- man3/list.3 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
man3/list.3 +1 -2
@@ -259,8 +259,7 @@ from the list. .SH CONFORMING TO Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. Present on the BSDs -(LIST macros first appeared in -.Bx 4.4 ). +(LIST macros first appeared in 4.4BSD). .SH BUGS .SH EXAMPLES .SH SEE ALSO
Signature · 1 line
2.28.0
PATCH 18/22 list.3: SEE ALSO: Add insque(3) and queue(3)
In reply to Alejandro Colomar--- man3/list.3 | 2 ++ 1 file changed, 2 insertions(+)
man3/list.3 +2 -0
@@ -263,3 +263,5 @@ Present on the BSDs .SH BUGS .SH EXAMPLES .SH SEE ALSO +.BR insque (3), +.BR queue (3)
Signature · 1 line
2.28.0
PATCH 19/22 list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++ man3/queue.3 | 53 ---------------------------------------------------- 2 files changed, 53 insertions(+), 53 deletions(-)
man3/list.3 +53 -0
@@ -262,6 +262,59 @@ Present on the BSDs (LIST macros first appeared in 4.4BSD). .SH BUGS .SH EXAMPLES +.Ss List example +.Bd -literal +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> + +struct entry { + int data; + LIST_ENTRY(entry) entries; /* List. */ +}; + +LIST_HEAD(listhead, entry); + +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct listhead head; /* List head. */ + int i; + + LIST_INIT(&head); /* Initialize the list. */ + + n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ + LIST_INSERT_HEAD(&head, n1, entries); + + n2 = malloc(sizeof(struct entry)); /* Insert after. */ + LIST_INSERT_AFTER(n1, n2, entries); + + n3 = malloc(sizeof(struct entry)); /* Insert before. */ + LIST_INSERT_BEFORE(n2, n3, entries); + + i = 0; /* Forward traversal. */ + LIST_FOREACH(np, &head, entries) + np->data = i++; + + LIST_REMOVE(n2, entries); /* Deletion. */ + free(n2); + /* Forward traversal. */ + LIST_FOREACH(np, &head, entries) + printf("%i\en", np->data); + /* List Deletion. */ + n1 = LIST_FIRST(&head); + while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; + } + LIST_INIT(&head); + + exit(EXIT_SUCCESS); +} +.Ed .SH SEE ALSO .BR insque (3), .BR queue (3)
man3/queue.3 +0 -53
59 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH 20/22 list.3: EXAMPLES: ffix: Use man markup
In reply to Alejandro Colomar--- man3/list.3 | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
man3/list.3 +2 -3
@@ -262,8 +262,7 @@ Present on the BSDs (LIST macros first appeared in 4.4BSD). .SH BUGS .SH EXAMPLES -.Ss List example -.Bd -literal +.EX #include <stddef.h> #include <stdio.h> #include <stdlib.h>
@@ -314,7 +313,7 @@ main(void) exit(EXIT_SUCCESS); } -.Ed +.EE .SH SEE ALSO .BR insque (3), .BR queue (3)
Signature · 1 line
2.28.0
PATCH 21/22 list.3: BUGS: Note LIST_FOREACH() limitations
In reply to Alejandro Colomar--- man3/list.3 | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
man3/list.3 +14 -0
@@ -261,6 +261,20 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. Present on the BSDs (LIST macros first appeared in 4.4BSD). .SH BUGS +The macro +.BR LIST_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +The macro +.BR LIST_FOREACH_SAFE (), +which is not present in glibc, +solves this bug by +allowing to both remove +.I var +as well as free it from within the loop safely +without interfering with the traversal. .SH EXAMPLES .EX #include <stddef.h>
Signature · 1 line
2.28.0
PATCH 22/22 list.3: RETURN VALUE: Add details about the return value of those macros that "return" a value
In reply to Alejandro Colomar--- man3/list.3 | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
man3/list.3 +14 -0
@@ -256,6 +256,20 @@ from the list. .\" and .\" .IR head2 . .SH RETURN VALUE +.BR LIST_EMPTY () +returns non-zero if the list is empty, +and zero if the list contains at least one entry. +.PP +.BR LIST_FIRST (), +and +.BR LIST_NEXT () +return a pointer to the first or next +.I LIST_ENTRY +structre, respectively. +.PP +.BR LIST_HEAD_INITIALIZER () +returns an initializer that can be assigned to the list +.IR head . .SH CONFORMING TO Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. Present on the BSDs
Signature · 1 line
2.28.0
v2 cover list.3: New page forked from queue.3
Hi Michael,
Anyway, I did the rebase :-}
This way I have a good pattern to follow in the next pages. And it was somewhat affordable.
Changes since v1:
- rebase + reorder + squash
- Minor fixes (squashed into the previous commits)
- LIST_*.3 links now point to list.3
- queue.3: SEE ALSO: Add list(3)
Kind regards,
Alex
Alejandro Colomar (10):
list.3: New page that will hold the (list) contents of queue.3 list.3, queue.3: NAME: Move code from queue.3 to list.3 list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3 list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3 list.3: Copy and adapt code from queue.3
list.3: ffix: Use man markup
list.3: Add details
LIST_EMPTY.3, LIST_ENTRY.3, LIST_FIRST.3, LIST_FOREACH.3, LIST_HEAD.3,
LIST_HEAD_INITIALIZER.3, LIST_INIT.3, LIST_INSERT_AFTER.3, LIST_INSERT_BEFORE.3, LIST_INSERT_HEAD.3, LIST_NEXT.3, LIST_REMOVE.3: Link to the new list.3 page instead of queue.3
queue.3: SEE ALSO: Add list(3)
man3/LIST_EMPTY.3 | 2 +- man3/LIST_ENTRY.3 | 2 +- man3/LIST_FIRST.3 | 2 +- man3/LIST_FOREACH.3 | 2 +- man3/LIST_HEAD.3 | 2 +- man3/LIST_HEAD_INITIALIZER.3 | 2 +- man3/LIST_INIT.3 | 2 +- man3/LIST_INSERT_AFTER.3 | 2 +- man3/LIST_INSERT_BEFORE.3 | 2 +- man3/LIST_INSERT_HEAD.3 | 2 +- man3/LIST_NEXT.3 | 2 +- man3/LIST_REMOVE.3 | 2 +- man3/list.3 | 347 +++++++++++++++++++++++++++++++++++ man3/queue.3 | 238 +----------------------- 14 files changed, 360 insertions(+), 249 deletions(-) create mode 100644 man3/list.3
Signature · 1 line
2.28.0
Hello Alex,
Quoted 3 lines · Alejandro Colomar
Hi Michael,
Anyway, I did the rebase :-}
Thanks!
Quoted 8 lines
This way I have a good pattern to follow in the next pages. And it was somewhat affordable.
Changes since v1:
- rebase + reorder + squash
- Minor fixes (squashed into the previous commits)
- LIST_*.3 links now point to list.3
- queue.3: SEE ALSO: Add list(3)
I've applied all of the patches, and pushed. You may want to take a look at a few of the teaks I added after your commits for some pieces that may be helpful in the next patches that you write for these changes.
Thanks,
Michael
Quoted 33 lines
Alejandro Colomar (10):
list.3: New page that will hold the (list) contents of queue.3 list.3, queue.3: NAME: Move code from queue.3 to list.3 list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3 list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 tolist.3list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3 list.3: Copy and adapt code from queue.3
list.3: ffix: Use man markup
list.3: Add details
LIST_EMPTY.3, LIST_ENTRY.3, LIST_FIRST.3, LIST_FOREACH.3, LIST_HEAD.3,
LIST_HEAD_INITIALIZER.3, LIST_INIT.3, LIST_INSERT_AFTER.3, LIST_INSERT_BEFORE.3, LIST_INSERT_HEAD.3, LIST_NEXT.3, LIST_REMOVE.3: Link to the new list.3 page instead of queue.3
queue.3: SEE ALSO: Add list(3)man3/LIST_EMPTY.3 | 2 +- man3/LIST_ENTRY.3 | 2 +- man3/LIST_FIRST.3 | 2 +- man3/LIST_FOREACH.3 | 2 +- man3/LIST_HEAD.3 | 2 +- man3/LIST_HEAD_INITIALIZER.3 | 2 +- man3/LIST_INIT.3 | 2 +- man3/LIST_INSERT_AFTER.3 | 2 +- man3/LIST_INSERT_BEFORE.3 | 2 +- man3/LIST_INSERT_HEAD.3 | 2 +- man3/LIST_NEXT.3 | 2 +- man3/LIST_REMOVE.3 | 2 +- man3/list.3 | 347 +++++++++++++++++++++++++++++++++++ man3/queue.3 | 238 +----------------------- 14 files changed, 360 insertions(+), 249 deletions(-) create mode 100644 man3/list.3
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH v2 1/10 list.3: New page that will hold the (list) contents of queue.3
In reply to Alejandro Colomar--- man3/list.3 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 man3/list.3
man3/list.3 new file +40 -0
@@ -0,0 +1,40 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <[email protected]> +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" +.TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" +.SH NAME +.SH SYNOPSIS +.SH DESCRIPTION +.SH RETURN VALUE +.SH CONFORMING TO +.SH BUGS +.SH EXAMPLES +.SH SEE ALSO
Signature · 1 line
2.28.0
PATCH v2 2/10 list.3, queue.3: NAME: Move code from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 17 +++++++++++++++++ man3/queue.3 | 17 ----------------- 2 files changed, 17 insertions(+), 17 deletions(-)
man3/list.3 +17 -0
@@ -31,6 +31,23 @@ .\" .TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" .SH NAME +.Nm LIST_EMPTY , +.Nm LIST_ENTRY , +.Nm LIST_FIRST , +.Nm LIST_FOREACH , +.\" .Nm LIST_FOREACH_FROM , +.\" .Nm LIST_FOREACH_SAFE , +.\" .Nm LIST_FOREACH_FROM_SAFE , +.Nm LIST_HEAD , +.Nm LIST_HEAD_INITIALIZER , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_BEFORE , +.Nm LIST_INSERT_HEAD , +.Nm LIST_NEXT , +.\" .Nm LIST_PREV , +.Nm LIST_REMOVE , +.\" .Nm LIST_SWAP , .SH SYNOPSIS .SH DESCRIPTION .SH RETURN VALUE
man3/queue.3 +0 -17
@@ -71,23 +71,6 @@ .Nm STAILQ_REMOVE_HEAD , .Nm STAILQ_REMOVE , .\" .Nm STAILQ_SWAP , -.Nm LIST_EMPTY , -.Nm LIST_ENTRY , -.Nm LIST_FIRST , -.Nm LIST_FOREACH , -.\" .Nm LIST_FOREACH_FROM , -.\" .Nm LIST_FOREACH_SAFE , -.\" .Nm LIST_FOREACH_FROM_SAFE , -.Nm LIST_HEAD , -.Nm LIST_HEAD_INITIALIZER , -.Nm LIST_INIT , -.Nm LIST_INSERT_AFTER , -.Nm LIST_INSERT_BEFORE , -.Nm LIST_INSERT_HEAD , -.Nm LIST_NEXT , -.\" .Nm LIST_PREV , -.Nm LIST_REMOVE , -.\" .Nm LIST_SWAP , .Nm TAILQ_CONCAT , .Nm TAILQ_EMPTY , .Nm TAILQ_ENTRY ,
Signature · 1 line
2.28.0
PATCH v2 3/10 list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 18 ++++++++++++++++++ man3/queue.3 | 18 ------------------ 2 files changed, 18 insertions(+), 18 deletions(-)
man3/list.3 +18 -0
@@ -49,6 +49,24 @@ .Nm LIST_REMOVE , .\" .Nm LIST_SWAP , .SH SYNOPSIS +.Fn LIST_EMPTY "LIST_HEAD *head" +.Fn LIST_ENTRY "TYPE" +.Fn LIST_FIRST "LIST_HEAD *head" +.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" +.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" +.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.\" .SH DESCRIPTION .SH RETURN VALUE .SH CONFORMING TO
man3/queue.3 +0 -18
@@ -157,24 +157,6 @@ lists, tail queues, and circular queues .Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" .\" .Fn STAILQ_SWAP "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" "STAILQ_ENTRY NAME" .\" -.Fn LIST_EMPTY "LIST_HEAD *head" -.Fn LIST_ENTRY "TYPE" -.Fn LIST_FIRST "LIST_HEAD *head" -.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.Fn LIST_HEAD "HEADNAME" "TYPE" -.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" -.Fn LIST_INIT "LIST_HEAD *head" -.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" -.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" -.\" .Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" .Fn TAILQ_EMPTY "TAILQ_HEAD *head" .Fn TAILQ_ENTRY "TYPE"
Signature · 1 line
2.28.0
PATCH v2 4/10 list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++ man3/queue.3 | 149 --------------------------------------------------- 2 files changed, 149 insertions(+), 149 deletions(-)
man3/list.3 +149 -0
@@ -68,6 +68,155 @@ .\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .\" .SH DESCRIPTION +.Ss Lists +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element, +before an existing element, or at the head of the list. +A +.Fa LIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +LIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +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: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm LIST_EMPTY +evaluates to true if there are no elements in the list. +.Pp +The macro +.Nm LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_FIRST +returns the first element in the list or NULL if the list +is empty. +.Pp +The macro +.Nm LIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_FROM +.\" behaves identically to +.\" .Nm LIST_FOREACH +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found LIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the LIST referenced by +.\" .Fa head . +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_SAFE +.\" traverses the list referenced by +.\" .Fa head +.\" in the forward direction, assigning each element in turn to +.\" .Fa var . +.\" However, unlike +.\" .Fn LIST_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 LIST_FOREACH_FROM_SAFE +.\" behaves identically to +.\" .Nm LIST_FOREACH_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found LIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the LIST referenced by +.\" .Fa head . +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm LIST_NEXT +returns the next element in the list, or NULL if this is the last. +.\" .Pp +.\" The macro +.\" .Nm LIST_PREV +.\" returns the previous element in the list, or NULL if this is the first. +.\" List +.\" .Fa head +.\" must contain element +.\" .Fa elm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +from the list. +.\" .Pp +.\" The macro +.\" .Nm LIST_SWAP +.\" swaps the contents of +.\" .Fa head1 +.\" and +.\" .Fa head2 . +.Pp +See the EXAMPLES section below for an example program using a linked list. .SH RETURN VALUE .SH CONFORMING TO .SH BUGS
man3/queue.3 +0 -149
155 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH v2 5/10 list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3
In reply to Alejandro Colomar--- man3/list.3 | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++ man3/queue.3 | 53 ---------------------------------------------------- 2 files changed, 53 insertions(+), 53 deletions(-)
man3/list.3 +53 -0
@@ -221,4 +221,57 @@ See the EXAMPLES section below for an example program using a linked list. .SH CONFORMING TO .SH BUGS .SH EXAMPLES +.Ss List example +.Bd -literal +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> + +struct entry { + int data; + LIST_ENTRY(entry) entries; /* List. */ +}; + +LIST_HEAD(listhead, entry); + +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct listhead head; /* List head. */ + int i; + + LIST_INIT(&head); /* Initialize the list. */ + + n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ + LIST_INSERT_HEAD(&head, n1, entries); + + n2 = malloc(sizeof(struct entry)); /* Insert after. */ + LIST_INSERT_AFTER(n1, n2, entries); + + n3 = malloc(sizeof(struct entry)); /* Insert before. */ + LIST_INSERT_BEFORE(n2, n3, entries); + + i = 0; /* Forward traversal. */ + LIST_FOREACH(np, &head, entries) + np->data = i++; + + LIST_REMOVE(n2, entries); /* Deletion. */ + free(n2); + /* Forward traversal. */ + LIST_FOREACH(np, &head, entries) + printf("%i\en", np->data); + /* List Deletion. */ + n1 = LIST_FIRST(&head); + while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; + } + LIST_INIT(&head); + + exit(EXIT_SUCCESS); +} +.Ed .SH SEE ALSO
man3/queue.3 +0 -53
59 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH v2 6/10 list.3: Copy and adapt code from queue.3
In reply to Alejandro Colomarlist.3: SYNOPSIS: Copy include from queue.3
list.3: DESCRIPTION: Copy description about naming of macros from queue.3 list.3: DESCRIPTION: Remove unrelated code to adapt to this page list.3: DESCRIPTION: Remove lines pointing to the EXAMPLES list.3: CONFORMING TO: Copy from queue.3
list.3: CONFORMING TO: Adapt to this page
--- man3/list.3 | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)
man3/list.3 +18 -2
@@ -49,6 +49,8 @@ .Nm LIST_REMOVE , .\" .Nm LIST_SWAP , .SH SYNOPSIS +.In sys/queue.h +.\" .Fn LIST_EMPTY "LIST_HEAD *head" .Fn LIST_ENTRY "TYPE" .Fn LIST_FIRST "LIST_HEAD *head"
@@ -68,6 +70,18 @@ .\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .\" .SH DESCRIPTION +In the macro definitions, +.Fa TYPE +is the name of a user defined structure, +that must contain a field of type +.Li LIST_ENTRY , +named +.Fa NAME . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macro +.Li LIST_HEAD . .Ss Lists A list is headed by a structure defined by the .Nm LIST_HEAD
@@ -215,10 +229,12 @@ from the list. .\" .Fa head1 .\" and .\" .Fa head2 . -.Pp -See the EXAMPLES section below for an example program using a linked list. .SH RETURN VALUE .SH CONFORMING TO +Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. +Present on the BSDs +(LIST macros first appeared in +.Bx 4.4 ). .SH BUGS .SH EXAMPLES .Ss List example
Signature · 1 line
2.28.0
PATCH v2 7/10 list.3: ffix: Use man markup
In reply to Alejandro Colomarlist.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
--- man3/list.3 | 261 ++++++++++++++++++++++++++++------------------------ 1 file changed, 141 insertions(+), 120 deletions(-)
man3/list.3 +141 -120
@@ -31,60 +31,77 @@ .\" .TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual" .SH NAME -.Nm LIST_EMPTY , -.Nm LIST_ENTRY , -.Nm LIST_FIRST , -.Nm LIST_FOREACH , -.\" .Nm LIST_FOREACH_FROM , -.\" .Nm LIST_FOREACH_SAFE , -.\" .Nm LIST_FOREACH_FROM_SAFE , -.Nm LIST_HEAD , -.Nm LIST_HEAD_INITIALIZER , -.Nm LIST_INIT , -.Nm LIST_INSERT_AFTER , -.Nm LIST_INSERT_BEFORE , -.Nm LIST_INSERT_HEAD , -.Nm LIST_NEXT , -.\" .Nm LIST_PREV , -.Nm LIST_REMOVE , -.\" .Nm LIST_SWAP , +LIST_EMPTY, +LIST_ENTRY, +LIST_FIRST, +LIST_FOREACH, +.\"LIST_FOREACH_FROM, +.\"LIST_FOREACH_SAFE, +.\"LIST_FOREACH_FROM_SAFE, +LIST_HEAD, +LIST_HEAD_INITIALIZER, +LIST_INIT, +LIST_INSERT_AFTER, +LIST_INSERT_BEFORE, +LIST_INSERT_HEAD, +LIST_NEXT, +LIST_PREV, +LIST_REMOVE +.\"LIST_SWAP .SH SYNOPSIS -.In sys/queue.h -.\" -.Fn LIST_EMPTY "LIST_HEAD *head" -.Fn LIST_ENTRY "TYPE" -.Fn LIST_FIRST "LIST_HEAD *head" -.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" -.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" -.Fn LIST_HEAD "HEADNAME" "TYPE" -.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" -.Fn LIST_INIT "LIST_HEAD *head" -.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" -.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" -.\" +.nf +.B #include <sys/queue.h> +.PP +.BI "int LIST_EMPTY(LIST_HEAD *" head ");" +.PP +.B LIST_ENTRY(TYPE); +.PP +.BI "LIST_ENTRY *LIST_FIRST(LIST_HEAD *" head ");" +.PP +.BI "LIST_FOREACH(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");" +.\".PP +.\".BI "LIST_FOREACH_FROM(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");" +.\".PP +.\".BI "LIST_FOREACH_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");" +.\".PP +.\".BI "LIST_FOREACH_FROM_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");" +.PP +.B LIST_HEAD(HEADNAME, TYPE); +.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 In the macro definitions, -.Fa TYPE +.I TYPE is the name of a user defined structure, that must contain a field of type -.Li LIST_ENTRY , +.IR LIST_ENTRY , named -.Fa NAME . +.IR NAME . The argument -.Fa HEADNAME +.IR HEADNAME is the name of a user defined structure that must be declared using the macro -.Li LIST_HEAD . -.Ss Lists +.BR LIST_HEAD (). +.PP A list is headed by a structure defined by the -.Nm LIST_HEAD +.BR LIST_HEAD () macro. This structure contains a single pointer to the first element on the list.
@@ -93,152 +110,156 @@ removed without traversing the list. New elements can be added to the list after an existing element, before an existing element, or at the head of the list. A -.Fa LIST_HEAD +.I LIST_HEAD structure is declared as follows: -.Bd -literal -offset indent +.PP +.in +4 +.EX LIST_HEAD(HEADNAME, TYPE) head; -.Ed -.Pp +.EE +.in +.PP where -.Fa HEADNAME +.I HEADNAME 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. A pointer to the head of the list 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 LIST_HEAD_INITIALIZER +.BR LIST_HEAD_INITIALIZER () evaluates to an initializer for the list -.Fa head . -.Pp +.IR head . +.PP The macro -.Nm LIST_EMPTY +.BR LIST_EMPTY () evaluates to true if there are no elements in the list. -.Pp +.PP The macro -.Nm LIST_ENTRY +.BR LIST_ENTRY () declares a structure that connects the elements in the list. -.Pp +.PP The macro -.Nm LIST_FIRST +.BR LIST_FIRST () returns the first element in the list or NULL if the list is empty. -.Pp +.PP The macro -.Nm LIST_FOREACH +.BR LIST_FOREACH () traverses the list referenced by -.Fa head +.I head in the forward direction, assigning each element in turn to -.Fa var . -.\" .Pp +.IR var . +.\" .PP .\" The macro -.\" .Nm LIST_FOREACH_FROM +.\" .BR LIST_FOREACH_FROM () .\" behaves identically to -.\" .Nm LIST_FOREACH +.\" .BR LIST_FOREACH () .\" when -.\" .Fa var +.\" .I var .\" is NULL, else it treats -.\" .Fa var +.\" .I var .\" 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 -.\" .Fa head . -.\" .Pp +.\" .IR head . +.\" .PP .\" The macro -.\" .Nm LIST_FOREACH_SAFE +.\" .BR LIST_FOREACH_SAFE () .\" traverses the list referenced by -.\" .Fa head +.\" .I head .\" in the forward direction, assigning each element in turn to -.\" .Fa var . +.\" .IR var . .\" However, unlike -.\" .Fn LIST_FOREACH +.\" .BR LIST_FOREACH () .\" 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 .\" traversal. -.\" .Pp +.\" .PP .\" The macro -.\" .Nm LIST_FOREACH_FROM_SAFE +.\" .BR LIST_FOREACH_FROM_SAFE () .\" behaves identically to -.\" .Nm LIST_FOREACH_SAFE +.\" .BR LIST_FOREACH_SAFE () .\" when -.\" .Fa var +.\" .I var .\" is NULL, else it treats -.\" .Fa var +.\" .I var .\" 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 -.\" .Fa head . -.Pp +.\" .IR head . +.PP The macro -.Nm LIST_INIT +.BR LIST_INIT () initializes the list referenced by -.Fa head . -.Pp +.IR head . +.PP The macro -.Nm LIST_INSERT_HEAD +.BR LIST_INSERT_HEAD () inserts the new element -.Fa elm +.I elm at the head of the list. -.Pp +.PP The macro -.Nm LIST_INSERT_AFTER +.BR LIST_INSERT_AFTER () inserts the new element -.Fa elm +.I elm after the element -.Fa listelm . -.Pp +.IR listelm . +.PP The macro -.Nm LIST_INSERT_BEFORE +.BR LIST_INSERT_BEFORE () inserts the new element -.Fa elm +.I elm before the element -.Fa listelm . -.Pp +.IR listelm . +.PP The macro -.Nm LIST_NEXT +.BR LIST_NEXT () returns the next element in the list, or NULL if this is the last. -.\" .Pp +.\" .PP .\" The macro -.\" .Nm LIST_PREV +.\" .BR LIST_PREV () .\" returns the previous element in the list, or NULL if this is the first. .\" List -.\" .Fa head +.\" .I head .\" must contain element -.\" .Fa elm . -.Pp +.\" .IR elm . +.PP The macro -.Nm LIST_REMOVE +.BR LIST_REMOVE () removes the element -.Fa elm +.I elm from the list. -.\" .Pp +.\" .PP .\" The macro -.\" .Nm LIST_SWAP +.\" .BR LIST_SWAP () .\" swaps the contents of -.\" .Fa head1 +.\" .I head1 .\" and -.\" .Fa head2 . +.\" .IR head2 . .SH RETURN VALUE .SH CONFORMING TO Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. Present on the BSDs -(LIST macros first appeared in -.Bx 4.4 ). +(LIST macros first appeared in 4.4BSD). .SH BUGS .SH EXAMPLES -.Ss List example -.Bd -literal +.EX #include <stddef.h> #include <stdio.h> #include <stdlib.h>
@@ -289,5 +310,5 @@ main(void) exit(EXIT_SUCCESS); } -.Ed +.EE .SH SEE ALSO
Signature · 1 line
2.28.0
PATCH v2 8/10 list.3: Add details
In reply to Alejandro Colomarlist.3: NAME: Add description
list.3: DESCRIPTION: Add short description
list.3: SEE ALSO: Add insque(3) and queue(3)
list.3: BUGS: Note LIST_FOREACH() limitations
list.3: RETURN VALUE: Add details about the return value of those macros that "return" a value
--- man3/list.3 | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+)
man3/list.3 +33 -0
@@ -48,6 +48,7 @@ LIST_NEXT, LIST_PREV, LIST_REMOVE .\"LIST_SWAP +\- implementation of a doubly-linked list .SH SYNOPSIS .nf .B #include <sys/queue.h>
@@ -87,6 +88,8 @@ LIST_REMOVE .\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", TYPE, LIST_ENTRY " NAME ");" .fi .SH DESCRIPTION +These macros define and operate on doubly-linked lists. +.PP In the macro definitions, .I TYPE is the name of a user defined structure,
@@ -253,11 +256,39 @@ from the list. .\" and .\" .IR head2 . .SH RETURN VALUE +.BR LIST_EMPTY () +returns non-zero if the list is empty, +and zero if the list contains at least one entry. +.PP +.BR LIST_FIRST (), +and +.BR LIST_NEXT () +return a pointer to the first or next +.I LIST_ENTRY +structre, respectively. +.PP +.BR LIST_HEAD_INITIALIZER () +returns an initializer that can be assigned to the list +.IR head . .SH CONFORMING TO Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. Present on the BSDs (LIST macros first appeared in 4.4BSD). .SH BUGS +The macro +.BR LIST_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +The macro +.BR LIST_FOREACH_SAFE (), +which is not present in glibc, +solves this bug by +allowing to both remove +.I var +as well as free it from within the loop safely +without interfering with the traversal. .SH EXAMPLES .EX #include <stddef.h>
@@ -312,3 +343,5 @@ main(void) } .EE .SH SEE ALSO +.BR insque (3), +.BR queue (3)
Signature · 1 line
2.28.0
PATCH v2 9/10 LIST_EMPTY.3, LIST_ENTRY.3, LIST_FIRST.3, LIST_FOREACH.3, LIST_HEAD.3, LIST_HEAD_INITIALIZER.3, LIST_INIT.3, LIST_INSERT_AFTER.3, LIST_INSERT_BEFORE.3, LIST_INSERT_HEAD.3, LIST_NEXT.3, LIST_REMOVE.3: Link to the new list.3 page instead of queue.3
In reply to Alejandro Colomar--- man3/LIST_EMPTY.3 | 2 +- man3/LIST_ENTRY.3 | 2 +- man3/LIST_FIRST.3 | 2 +- man3/LIST_FOREACH.3 | 2 +- man3/LIST_HEAD.3 | 2 +- man3/LIST_HEAD_INITIALIZER.3 | 2 +- man3/LIST_INIT.3 | 2 +- man3/LIST_INSERT_AFTER.3 | 2 +- man3/LIST_INSERT_BEFORE.3 | 2 +- man3/LIST_INSERT_HEAD.3 | 2 +- man3/LIST_NEXT.3 | 2 +- man3/LIST_REMOVE.3 | 2 +- 12 files changed, 12 insertions(+), 12 deletions(-)
man3/LIST_EMPTY.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_ENTRY.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_FIRST.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_FOREACH.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_HEAD.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_HEAD_INITIALIZER.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_INIT.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_INSERT_AFTER.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_INSERT_BEFORE.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_INSERT_HEAD.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_NEXT.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
man3/LIST_REMOVE.3 +1 -1
@@ -1 +1 @@ -.so man3/queue.3 +.so man3/list.3
Signature · 1 line
2.28.0
PATCH v2 10/10 queue.3: SEE ALSO: Add list(3)
In reply to Alejandro Colomar--- man3/queue.3 | 1 + 1 file changed, 1 insertion(+)
man3/queue.3 +1 -0
@@ -1275,4 +1275,5 @@ functions first appeared in .Bx 4.4 . .Sh SEE ALSO .Xr insque 3 +.Xr list 3 .\" .Xr tree 3
Signature · 1 line
2.28.0
Hi Alex,
Quoted 5 lines · Alejandro Colomar
Hi Michael,
I finished one of the pages: list.3
Would you maybe call the page LIST.3 instead?
I think list.3 is okay.
Quoted 3 lines
I didn't write the link pages yet in case we call it differently.
Please comment any improvements you may find.
Overall, I think the result is fine, but:
Quoted 7 lines
There are too many patches, so you may prefer to pull from my repo, where I created the tag '
list_v1' for this patchset:https://github.com/alejandro-colomar/man-pages.git
list_v1As you can probably guess, if you prefer to pull from the repo, I'll create similar tags for revisions of this patchset (e.g., '
list_v2').
I suppose if I was doing this work I would chunk it up into bigger pieces. I appreciate that you are trying to meticulously show the steps that you took to build the page, but 22 patches does really feel like too much. And I would have combined the "Use man markup" patches into one step at the end, and I'd prefer you do that for future patches (but I can live with things as they are in this patch series).
In terms of fewer patches, how would you feel about squashing the patches as per the blank line separators below (and consequently having bigger commit messages):
Quoted 28 lines
Alejandro Colomar (22):
list.3: New page that will hold the (list) contents of queue.3list.3, queue.3: NAME: Move code from queue.3 to list.3 list.3: NAME: ffix: Use man markup
list.3: NAME: Add descriptionlist.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3 list.3: SYNOPSIS: Copy include from queue.3 list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: Add short description
list.3: DESCRIPTION: Copy description about naming of macros fromqueue.3list.3: DESCRIPTION: Remove unrelated code to adapt to this page list.3: DESCRIPTION: ffix: Use man markup
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3list.3: DESCRIPTION: ffix: Use man markup list.3: DESCRIPTION: Remove line pointing to the EXAMPLES
list.3: CONFORMING TO: Copy from queue.3
list.3: CONFORMING TO: Adapt to this page
list.3: CONFORMING TO: ffix: Use man markuplist.3: SEE ALSO: Add insque(3) and queue(3)
Quoted 7 lines
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3 list.3: EXAMPLES: ffix: Use man markup
list.3: BUGS: Note
LIST_FOREACH()limitationslist.3: RETURN VALUE: Add details about the return value of those
macros that "return" a value
Squashing as above would yield 10 patches, and I'd kind of prefer that so as to avoid quite so many commits in the history. (For future patches though, I would prefer to split out the "Use man markup" into a single patch at the end of the series.)
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 70 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 5 lines · Alejandro Colomar
Hi Michael,
I finished one of the pages: list.3
Would you maybe call the page LIST.3 instead?
I think list.3 is okay.
Quoted 3 lines
I didn't write the link pages yet in case we call it differently.
Please comment any improvements you may find.
Overall, I think the result is fine, but:
Quoted 7 lines
There are too many patches, so you may prefer to pull from my repo, where I created the tag '
list_v1' for this patchset:https://github.com/alejandro-colomar/man-pages.git
list_v1As you can probably guess, if you prefer to pull from the repo, I'll create similar tags for revisions of this patchset (e.g., '
list_v2').I suppose if I was doing this work I would chunk it up into bigger pieces. I appreciate that you are trying to meticulously show the steps that you took to build the page, but 22 patches does really feel like too much. And I would have combined the "Use man markup" patches into one step at the end, and I'd prefer you do that for future patches (but I can live with things as they are in this patch series).
In terms of fewer patches, how would you feel about squashing the patches as per the blank line separators below (and consequently having bigger commit messages):
Quoted 32 lines
Alejandro Colomar (22):
list.3: New page that will hold the (list) contents of queue.3list.3, queue.3: NAME: Move code from queue.3 to list.3 list.3: NAME: ffix: Use man markup
list.3: NAME: Add descriptionlist.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3 list.3: SYNOPSIS: Copy include from queue.3 list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: Add short description
list.3: DESCRIPTION: Copy description about naming of macros fromqueue.3list.3: DESCRIPTION: Remove unrelated code to adapt to this page list.3: DESCRIPTION: ffix: Use man markup
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3list.3: DESCRIPTION: ffix: Use man markup list.3: DESCRIPTION: Remove line pointing to the EXAMPLES
list.3: CONFORMING TO: Copy from queue.3
list.3: CONFORMING TO: Adapt to this page
list.3: CONFORMING TO: ffix: Use man markuplist.3: SEE ALSO: Add insque(3) and queue(3)
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3 list.3: EXAMPLES: ffix: Use man markup
list.3: BUGS: Note
LIST_FOREACH()limitations
Quoted 7 lines
Quoted 2 lines
list.3: RETURN VALUE: Add details about the return value of those
macros that "return" a valueSquashing as above would yield 10 patches, and I'd kind of prefer that so as to avoid quite so many commits in the history. (For future patches though, I would prefer to split out the "Use man markup" into a single patch at the end of the series.)
I can't find the source
(I think it was some kernel guide for sending patches), but I read some time ago that I should separate code movement from any other changes;
otherwise git might not be able to follow that movement.
So I would reorder and squash the commits as:
Alejandro Colomar (22):
list.3: New page that will hold the (list) contents of queue.3
list.3, queue.3: NAME: Move code from queue.3 to list.3
list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3
list.3: SYNOPSIS: Copy include from queue.3
list.3: DESCRIPTION: Copy description about naming of macros from
queue.3
list.3: CONFORMING TO: Copy from queue.3
list.3: DESCRIPTION: Remove unrelated code to adapt to this page list.3: DESCRIPTION: Remove line pointing to the EXAMPLES list.3: CONFORMING TO: Adapt to this page
squash as list.3: Copy and adapt code from queue.3
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
squash as list.3: ffix: Use man markup
list.3: NAME: Add description
list.3: DESCRIPTION: Add short description
list.3: SEE ALSO: Add insque(3) and queue(3)
list.3: BUGS: Note LIST_FOREACH() limitations
list.3: RETURN VALUE: Add details about the return value of those
macros that "return" a value
squash as list.3: Add details
I'll keep the messages of the squashed commits inside the commit msg. This would mean 8 patches.
Sounds good?
Thanks,
Alex
Quoted 5 lines
Thanks,
Michael
Hi Alex,
Quoted 129 lines · Alejandro Colomar
Quoted 70 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 5 lines · Alejandro Colomar
Hi Michael,
I finished one of the pages: list.3
Would you maybe call the page LIST.3 instead?
I think list.3 is okay.
Quoted 3 lines
I didn't write the link pages yet in case we call it differently.
Please comment any improvements you may find.
Overall, I think the result is fine, but:
Quoted 7 lines
There are too many patches, so you may prefer to pull from my repo, where I created the tag '
list_v1' for this patchset:https://github.com/alejandro-colomar/man-pages.git
list_v1As you can probably guess, if you prefer to pull from the repo, I'll create similar tags for revisions of this patchset (e.g., '
list_v2').I suppose if I was doing this work I would chunk it up into bigger pieces. I appreciate that you are trying to meticulously show the steps that you took to build the page, but 22 patches does really feel like too much. And I would have combined the "Use man markup" patches into one step at the end, and I'd prefer you do that for future patches (but I can live with things as they are in this patch series).
In terms of fewer patches, how would you feel about squashing the patches as per the blank line separators below (and consequently having bigger commit messages):
Quoted 32 lines
Alejandro Colomar (22):
list.3: New page that will hold the (list) contents of queue.3list.3, queue.3: NAME: Move code from queue.3 to list.3 list.3: NAME: ffix: Use man markup
list.3: NAME: Add descriptionlist.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3 list.3: SYNOPSIS: Copy include from queue.3 list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: Add short description
list.3: DESCRIPTION: Copy description about naming of macros fromqueue.3list.3: DESCRIPTION: Remove unrelated code to adapt to this page list.3: DESCRIPTION: ffix: Use man markup
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3list.3: DESCRIPTION: ffix: Use man markup list.3: DESCRIPTION: Remove line pointing to the EXAMPLES
list.3: CONFORMING TO: Copy from queue.3
list.3: CONFORMING TO: Adapt to this page
list.3: CONFORMING TO: ffix: Use man markuplist.3: SEE ALSO: Add insque(3) and queue(3)
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3 list.3: EXAMPLES: ffix: Use man markup
list.3: BUGS: Note
LIST_FOREACH()limitationsQuoted 7 lines
Quoted 2 lines
list.3: RETURN VALUE: Add details about the return value of those
macros that "return" a valueSquashing as above would yield 10 patches, and I'd kind of prefer that so as to avoid quite so many commits in the history. (For future patches though, I would prefer to split out the "Use man markup" into a single patch at the end of the series.)
I can't find the source
(I think it was some kernel guide for sending patches), but I read some time ago that I should separate code movement from any other changes;
otherwise git might not be able to follow that movement.So I would reorder and squash the commits as:
Alejandro Colomar (22):
list.3: New page that will hold the (list) contents of queue.3list.3, queue.3: NAME: Move code from queue.3 to list.3
list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3
list.3: SYNOPSIS: Copy include from queue.3
list.3: DESCRIPTION: Copy description about naming of macros fromqueue.3list.3: CONFORMING TO: Copy from queue.3
list.3: DESCRIPTION: Remove unrelated code to adapt to this page list.3: DESCRIPTION: Remove line pointing to the EXAMPLES list.3: CONFORMING TO: Adapt to this page
squash as list.3: Copy and adapt code from queue.3list.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
squash as list.3: ffix: Use man markuplist.3: NAME: Add description
list.3: DESCRIPTION: Add short description
list.3: SEE ALSO: Add insque(3) and queue(3)
list.3: BUGS: NoteLIST_FOREACH()limitations
list.3: RETURN VALUE: Add details about the return value of those
macros that "return" a value
squash as list.3: Add details
Quoted 4 lines
I'll keep the messages of the squashed commits inside the commit msg. This would mean 8 patches.
Sounds good?
I think that would be fine, but I suspect you might have to fix a lot of conflicts if you reorder the patches so much, I wanted to save you having to do that work. I could live with either way, but I'd prefer to minimize the effort you need to invest to make the change.
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/