Skip to contentSkip to conversation

list.3: New page forked from queue.3

PATCH Superseded Alejandro Colomar 2 participants 38 messages Oct 20, 2020 – Oct 21, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
new file mode 100644
index 000000000..127c391f1
@@ -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
#2 lore raw

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
index 127c391f1..340b24f7c 100644
@@ -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
index c48b4ba9f..17adfcf3b 100644
@@ -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
#3 lore raw

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
index 340b24f7c..d26ac8971 100644
@@ -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
#4 lore raw

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
index d26ac8971..21ea42fa4 100644
@@ -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
#5 lore raw

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
index 21ea42fa4..c43832098 100644
@@ -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
index 17adfcf3b..a3a2eb2b0 100644
@@ -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
#6 lore raw

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
index c43832098..0ea135900 100644
@@ -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
#7 lore raw

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
index 0ea135900..8af4ccfd6 100644
@@ -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
#8 lore raw

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
index 8af4ccfd6..ae6590fdb 100644
@@ -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
#9 lore raw

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
index ae6590fdb..70f32a384 100644
@@ -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
#10 lore raw

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
index 70f32a384..36d259a63 100644
@@ -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
#11 lore raw

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
index 36d259a63..39c1d4b4d 100644
@@ -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
#12 lore raw

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
index 39c1d4b4d..3c25b3e55 100644
@@ -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
#13 lore raw

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
index 3c25b3e55..5b2a72fdb 100644
@@ -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
#14 lore raw

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
index 5b2a72fdb..71b35c26d 100644
@@ -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
#15 lore raw

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
index 71b35c26d..64f94197a 100644
@@ -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
#16 lore raw

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
index 64f94197a..2a873deab 100644
@@ -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
#17 lore raw

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
index 2a873deab..478fa2bf3 100644
@@ -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
#19 lore raw

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
index 82ab4dae4..b22453ab9 100644
@@ -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
#20 lore raw

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
index b22453ab9..bb64fff92 100644
@@ -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
#21 lore raw

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
index bb64fff92..4aec14cc8 100644
@@ -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
#22 lore raw

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
index 4aec14cc8..8233c3b3e 100644
@@ -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
#23 lore raw

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
#24 lore raw

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 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 · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#25 lore raw

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
new file mode 100644
index 000000000..127c391f1
@@ -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
#26 lore raw

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
index 127c391f1..340b24f7c 100644
@@ -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
index c48b4ba9f..17adfcf3b 100644
@@ -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
#27 lore raw

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
index 340b24f7c..020f66200 100644
@@ -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
index 17adfcf3b..a3a2eb2b0 100644
@@ -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
#28 lore raw

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
index 020f66200..1a197fe31 100644
@@ -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
#29 lore raw

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
index 1a197fe31..6252aaf6a 100644
@@ -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
#30 lore raw

PATCH v2 6/10 list.3: Copy and adapt code from queue.3

In reply to Alejandro Colomar

list.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
index 6252aaf6a..4c36b0846 100644
@@ -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
#31 lore raw

PATCH v2 7/10 list.3: ffix: Use man markup

In reply to Alejandro Colomar

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

---
 man3/list.3 | 261 ++++++++++++++++++++++++++++------------------------
 1 file changed, 141 insertions(+), 120 deletions(-)
man3/list.3 +141 -120
index 4c36b0846..0f9b20d26 100644
@@ -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
#32 lore raw

PATCH v2 8/10 list.3: Add details

In reply to Alejandro Colomar

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

---
 man3/list.3 | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
man3/list.3 +33 -0
index 0f9b20d26..8233c3b3e 100644
@@ -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
#33 lore raw

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
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_ENTRY.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_FIRST.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_FOREACH.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_HEAD.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_HEAD_INITIALIZER.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_INIT.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_INSERT_AFTER.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_INSERT_BEFORE.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_INSERT_HEAD.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_NEXT.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
man3/LIST_REMOVE.3 +1 -1
index c2956c9fc..dfafea85d 100644
@@ -1 +1 @@
-.so man3/queue.3
+.so man3/list.3
Signature · 1 line
2.28.0
#35 lore raw
In reply to Alejandro Colomar

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_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').

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.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)

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() limitations

list.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/
#36 lore raw
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_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').

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.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

Quoted 7 lines
Quoted 2 lines

list.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.)

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

#37 lore raw

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_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').

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.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

Quoted 7 lines
Quoted 2 lines

list.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.)

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

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/