Skip to contentSkip to conversation

circleq.3, list.3, slist.3, stailq.3, tailq.3: Use the 'struct' keyword when appropriate

PATCH In review Alejandro Colomar 2 participants 3 messages Oct 25, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 circleq.3, list.3, slist.3, stailq.3, tailq.3: Use the 'struct' keyword when appropriate

This helps differentiate 'TYPE' in some arguments
from 'struct TYPE *var' in others,
and is technically more correct.

---

Hi Michael,

This should be the last patch for queue.3 and its forks.

Cheers,

Alex

 man3/circleq.3 | 32 ++++++++++++++++----------------
 man3/list.3    | 33 ++++++++++++++++++---------------
 man3/slist.3   | 28 +++++++++++++++-------------
 man3/stailq.3  | 34 ++++++++++++++++++----------------
 man3/tailq.3   | 45 ++++++++++++++++++++++++---------------------
 5 files changed, 91 insertions(+), 81 deletions(-)
man3/circleq.3 +16 -16
index a70a22079..ff028b72d 100644
@@ -58,11 +58,11 @@ CIRCLEQ_REMOVE
 .PP
 .B CIRCLEQ_ENTRY(TYPE);
 .PP
-.BI "TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ");"
+.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ");"
 .PP
-.BI "CIRCLEQ_FOREACH(TYPE *" var ", CIRCLEQ_HEAD *" head ", CIRCLEQ_ENTRY " NAME ");"
+.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ", CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "CIRCLEQ_FOREACH_REVERSE(TYPE *" var ", CIRCLEQ_HEAD *" head ","
+.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
 .B CIRCLEQ_HEAD(HEADNAME, TYPE);
@@ -71,31 +71,31 @@ CIRCLEQ_REMOVE
 .PP
 .BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ");"
 .PP
-.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", TYPE *" listelm ", TYPE *" elm ","
+.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ", struct TYPE *" elm ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", TYPE *" listelm ", TYPE *" elm ","
+.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ", struct TYPE *" elm ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
+.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
+.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ");"
+.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ");"
 .PP
-.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
+.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ", TYPE *" elm ","
+.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
 .BI "                CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "TYPE *CIRCLEQ_NEXT(TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "TYPE *CIRCLEQ_PREV(TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
 .PP
-.BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly-linked circular queues.
@@ -135,9 +135,9 @@ CIRCLEQ_HEAD(HEADNAME, TYPE) head;
 .in
 .PP
 where
-.I HEADNAME
-is the name of the structure to be defined, and
-.I TYPE
+.I struct HEADNAME
+is the structure to be defined, and
+.I struct TYPE
 is the type of the elements to be linked into the circular queue.
 A pointer to the head of the circular queue can later be declared as:
 .PP
man3/list.3 +18 -15
index cbe8b8d1c..94ccc5c39 100644
@@ -57,15 +57,15 @@ LIST_REMOVE
 .PP
 .B LIST_ENTRY(TYPE);
 .PP
-.BI "TYPE *LIST_FIRST(LIST_HEAD *" head ");"
+.BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head ");"
 .PP
-.BI "LIST_FOREACH(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
+.BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "LIST_FOREACH_FROM(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
+.\".BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "LIST_FOREACH_FROM_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");"
+.\".BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
 .\".PP
-.\".BI "LIST_FOREACH_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");"
+.\".BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
 .PP
 .B LIST_HEAD(HEADNAME, TYPE);
 .PP
@@ -73,19 +73,22 @@ LIST_REMOVE
 .PP
 .BI "void LIST_INIT(LIST_HEAD *" head ");"
 .PP
-.BI "void LIST_INSERT_AFTER(TYPE *" listelm ", TYPE *" elm ", LIST_ENTRY " NAME ");"
+.BI "void LIST_INSERT_AFTER(struct TYPE *" listelm ", struct TYPE *" elm ","
+.BI "                LIST_ENTRY " NAME ");"
 .PP
-.BI "void LIST_INSERT_BEFORE(TYPE *" listelm ", TYPE *" elm ", LIST_ENTRY " NAME ");"
+.BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm ", struct TYPE *" elm ","
+.BI "                LIST_ENTRY " NAME ");"
 .PP
-.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ", TYPE *" elm ", LIST_ENTRY " NAME ");"
+.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ", struct TYPE *" elm ","
+.BI "                LIST_ENTRY " NAME ");"
 .PP
-.BI "TYPE *LIST_NEXT(TYPE *" elm ", LIST_ENTRY " NAME ");"
+.BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "TYPE *LIST_PREV(TYPE *" elm ", LIST_HEAD *" head ", TYPE, LIST_ENTRY " NAME ");"
+.\".BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head ", struct TYPE, LIST_ENTRY " NAME ");"
 .PP
-.BI "void LIST_REMOVE(TYPE *" elm ", LIST_ENTRY " NAME ");"
+.BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", TYPE, LIST_ENTRY " NAME ");"
+.\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", struct TYPE, LIST_ENTRY " NAME ");"
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly-linked lists.
@@ -123,9 +126,9 @@ LIST_HEAD(HEADNAME, TYPE) head;
 .in
 .PP
 where
-.I HEADNAME
-is the name of the structure to be defined, and
-.I TYPE
+.I struct HEADNAME
+is the structure to be defined, and
+.I struct 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:
 .PP
man3/slist.3 +15 -13
index b514f3576..3ca9ea0d8 100644
@@ -57,15 +57,15 @@ SLIST_REMOVE_HEAD
 .PP
 .B SLIST_ENTRY(TYPE);
 .PP
-.BI "TYPE *SLIST_FIRST(SLIST_HEAD *" head ");"
+.BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head ");"
 .PP
-.BI "SLIST_FOREACH(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
+.BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "SLIST_FOREACH_FROM(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
+.\".BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "SLIST_FOREACH_FROM_SAFE(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", TYPE *" temp_var ");"
+.\".BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
 .\".PP
-.\".BI "SLIST_FOREACH_SAFE(TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", TYPE *" temp_var ");"
+.\".BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
 .PP
 .B SLIST_HEAD(HEADNAME, TYPE);
 .PP
@@ -73,15 +73,17 @@ SLIST_REMOVE_HEAD
 .PP
 .BI "void SLIST_INIT(SLIST_HEAD *" head ");"
 .PP
-.BI "void SLIST_INSERT_AFTER(TYPE *" listelm ", TYPE *" elm ", SLIST_ENTRY " NAME ");"
+.BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm ", struct TYPE *" elm ","
+.BI "                SLIST_ENTRY " NAME ");"
 .PP
-.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head ", TYPE *" elm ", SLIST_ENTRY " NAME ");"
+.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head ", struct TYPE *" elm ","
+.BI "                SLIST_ENTRY " NAME ");"
 .PP
-.BI "TYPE *SLIST_NEXT(TYPE *" elm ", SLIST_ENTRY " NAME ");"
+.BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME ");"
 .PP
-.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", TYPE *" elm ", SLIST_ENTRY " NAME ");"
+.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm ", SLIST_ENTRY " NAME ");"
 .\".PP
-.\".BI "void SLIST_REMOVE_AFTER(TYPE *" elm ", SLIST_ENTRY " NAME ");"
+.\".BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm ", SLIST_ENTRY " NAME ");"
 .PP
 .BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
 .\".PP
@@ -123,9 +125,9 @@ SLIST_HEAD(HEADNAME, TYPE) head;
 .in
 .PP
 where
-.I HEADNAME
-is the name of the structure to be defined, and
-.I TYPE
+.I struct HEADNAME
+is the structure to be defined, and
+.I struct 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:
 .PP
man3/stailq.3 +18 -16
index 01b6107b5..b7f472136 100644
@@ -62,15 +62,15 @@ STAILQ_REMOVE_HEAD,
 .PP
 .B STAILQ_ENTRY(TYPE);
 .PP
-.BI "TYPE *STAILQ_FIRST(STAILQ_HEAD *" head ");"
+.BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head ");"
 .PP
-.BI "STAILQ_FOREACH(TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
+.BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
 .\" .PP
-.\" .BI "STAILQ_FOREACH_FROM(TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
+.\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
 .\" .PP
-.\" .BI "STAILQ_FOREACH_FROM_SAFE(TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ", TYPE *" temp_var ");"
+.\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
 .\" .PP
-.\" .BI "STAILQ_FOREACH_SAFE(TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ", TYPE *" temp_var ");"
+.\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
 .PP
 .B STAILQ_HEAD(HEADNAME, TYPE);
 .PP
@@ -78,21 +78,23 @@ STAILQ_REMOVE_HEAD,
 .PP
 .BI "void STAILQ_INIT(STAILQ_HEAD *" head ");"
 .PP
-.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", TYPE *" listelm ", TYPE *" elm ","
-.BI "                STAILQ_ENTRY " NAME ");"
+.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm ","
+.BI "                struct TYPE *" elm ", STAILQ_ENTRY " NAME ");"
 .PP
-.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head ", TYPE *" elm ", STAILQ_ENTRY " NAME ");"
+.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head ", struct TYPE *" elm ","
+.BI "                STAILQ_ENTRY " NAME ");"
 .PP
-.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head ", TYPE *" elm ", STAILQ_ENTRY " NAME ");"
+.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head ", struct TYPE *" elm ","
+.BI "                STAILQ_ENTRY " NAME ");"
 .\" .PP
-.\" .BI "TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", TYPE *" elm ", STAILQ_ENTRY " NAME ");"
+.\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm ", STAILQ_ENTRY " NAME ");"
 .PP
-.BI "TYPE *STAILQ_NEXT(TYPE *" elm ", STAILQ_ENTRY " NAME ");"
+.BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME ");"
 .PP
-.BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", TYPE *" elm ", TYPE,"
+.BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", struct TYPE *" elm ", TYPE,"
 .BI "                STAILQ_ENTRY " NAME ");"
 .\" .PP
-.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", TYPE *" elm ","
+.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm ","
 .\" .BI "                STAILQ_ENTRY " NAME ");"
 .PP
 .BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
@@ -138,9 +140,9 @@ STAILQ_HEAD(HEADNAME, TYPE) head;
 .in
 .PP
 where
-.I HEADNAME
-is the name of the structure to be defined, and
-.I TYPE
+.I struct HEADNAME
+is the structure to be defined, and
+.I struct TYPE
 is the type of the elements to be linked into the tail queue.
 A pointer to the head of the tail queue can later be declared as:
 .PP
man3/tailq.3 +24 -21

79 lines not on this page · raw message

Signature · 1 line
2.28.0
#1 lore raw

Hi Alex,

Quoted 6 lines · Alejandro Colomar

This helps differentiate 'TYPE' in some arguments
from 'struct TYPE *var' in others,
and is technically more correct.

Thanks. Patch applied. Everything is not pushed.

Quoted 5 lines

---

Hi Michael,

This should be the last patch for queue.3 and its forks.

Thanks for all the work!!

Could you please check my commit 9484d926f to make sure it's the right correction.

Thanks,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

#2 lore raw
Quoted 14 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 6 lines · Alejandro Colomar

This helps differentiate 'TYPE' in some arguments
from 'struct TYPE *var' in others,
and is technically more correct.

Thanks. Patch applied. Everything is not pushed.

Quoted 2 lines

---

Quoted 8 lines
Quoted 3 lines

Hi Michael,

This should be the last patch for queue.3 and its forks.

Thanks for all the work!!

Could you please check my commit 9484d926f to make sure it's the right correction.

Yes, it's correct. Thanks for all the fixes.

Thanks,

Alex

Quoted 12 lines

Thanks,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/