Skip to contentSkip to conversation

Document aiocb, sigevent, siginfo_t

PATCH In review Alejandro Colomar 2 participants 29 messages Sep 18, 2020 – Sep 20, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

cover Document aiocb, sigevent, siginfo_t

Hello Michael,

Here is a bigger patchset documenting a few types + a few fixes. (apply after regmatch_t patches).

Cheers,

Alex

P.S.: Eso es todo por hoy :)

Alejandro Colomar (9):
system_data_types.7: ffix
system_data_types.7: srcfix: Add FIXME note: Add descriptions system_data_types.7: Document sigevent
sigevent.3: New link to new documented type in system_data_types(7) system_data_types.7: srcfix: cosmetic: Visually sparate types system_data_types.7: Document aiocb
aiocb.3: New link to new documented type in system_data_types(7) system_data_types.7: Document siginfo_t
siginfo_t.3: New link to new documented type in system_data_types(7)

 man3/aiocb.3             |   1 +
 man3/sigevent.3          |   1 +
 man3/siginfo_t.3         |   1 +
 man7/system_data_types.7 | 138 ++++++++++++++++++++++++++++++++++++---
 4 files changed, 133 insertions(+), 8 deletions(-)
 create mode 100644 man3/aiocb.3
 create mode 100644 man3/sigevent.3
 create mode 100644 man3/siginfo_t.3
Signature · 1 line
2.28.0
#1 lore raw

PATCH 1/9 system_data_types.7: ffix

---
 man7/system_data_types.7 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
man7/system_data_types.7 +2 -2
index eb4718491..5352f3ef2 100644
@@ -232,9 +232,9 @@ Notes:
 .IR <iconv.h> ,
 .IR <mqueue.h> ,
 .IR <pwd.h> ,
-.IR <signal.h>
+.I <signal.h>
 and
-.IR <sys/socket.h>
+.I <sys/socket.h>
 define
 .I size_t
 since POSIX.1-2008.
Signature · 1 line
2.28.0
#2 lore raw

Re: [PATCH 1/9] system_data_types.7: ffix

Quoted 4 lines · Alejandro Colomar
---
 man7/system_data_types.7 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Thanks, Alex. Patch applied.

Cheers,

Michael

Quoted 17 lines
man7/system_data_types.7 +2 -2
index eb4718491..5352f3ef2 100644
@@ -232,9 +232,9 @@ Notes:
 .IR <iconv.h> ,
 .IR <mqueue.h> ,
 .IR <pwd.h> ,
-.IR <signal.h>
+.I <signal.h>
 and
-.IR <sys/socket.h>
+.I <sys/socket.h>
 define
 .I size_t
 since POSIX.1-2008.
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/
#3 lore raw

PATCH 2/9 system_data_types.7: srcfix: Add FIXME note: Add descriptions

In reply to Alejandro Colomar
---
 man7/system_data_types.7 | 2 ++
 1 file changed, 2 insertions(+)
man7/system_data_types.7 +2 -0
index 5352f3ef2..48871e4eb 100644
@@ -96,6 +96,8 @@ typedef struct {
                         * the end of substring */
 } regmatch_t;
 .EE
+.\".IP
+.\" FIXME: Add a description?
 .IP
 Conforming to: POSIX.1-2001 and later.
 .IP
Signature · 1 line
2.28.0
#4 lore raw

Re: [PATCH 2/9] system_data_types.7: srcfix: Add FIXME note: Add descriptions

Quoted 1 line · Alejandro Colomar

Thanks, Alex. Patch applied.

Cheers,

Michael

Quoted 18 lines
---
 man7/system_data_types.7 | 2 ++
 1 file changed, 2 insertions(+)
man7/system_data_types.7 +2 -0
index 5352f3ef2..48871e4eb 100644
@@ -96,6 +96,8 @@ typedef struct {
                         * the end of substring */
 } regmatch_t;
 .EE
+.\".IP
+.\" FIXME: Add a description?
 .IP
 Conforming to: POSIX.1-2001 and later.
 .IP
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/
#5 lore raw

Re: [PATCH 2/9] system_data_types.7: srcfix: Add FIXME note: Add descriptions

Hi Alex,

Quoted 5 lines · Michael Kerrisk (man-pages)
Quoted 1 line · Alejandro Colomar

Thanks, Alex. Patch applied.

Sorry -- I misspoke. This pach doesn't apply. It wasn't obvious why.

But, yes, I think adding a description would be good.

Thanks,

Michael

Quoted 20 lines
Quoted 18 lines
---
 man7/system_data_types.7 | 2 ++
 1 file changed, 2 insertions(+)
man7/system_data_types.7 +2 -0
index 5352f3ef2..48871e4eb 100644
@@ -96,6 +96,8 @@ typedef struct {
                         * the end of substring */
 } regmatch_t;
 .EE
+.\".IP
+.\" FIXME: Add a description?
 .IP
 Conforming to: POSIX.1-2001 and later.
 .IP
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/
#6 lore raw

Re: [PATCH 2/9] system_data_types.7: srcfix: Add FIXME note: Add descriptions

Hi Michael,

Quoted 21 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 5 lines · Michael Kerrisk (man-pages)
Quoted 1 line · Alejandro Colomar

Thanks, Alex. Patch applied.

Sorry -- I misspoke. This pach doesn't apply. It wasn't obvious why.

But, yes, I think adding a description would be good.

Thanks,

Michael

Quoted 4 lines
Quoted 4 lines
---
  man7/system_data_types.7 | 2 ++
  1 file changed, 2 insertions(+)
Quoted 13 lines
Quoted 5 lines
Quoted 5 lines
man7/system_data_types.7 +0 -0
index 5352f3ef2..48871e4eb 100644
@@ -96,6 +96,8 @@ typedef struct {
Quoted 8 lines

man7/system_data_types.7 typedef struct { · line 103

Quoted 8 lines
man7/system_data_types.7 +2 -0
                          * the end of substring */
  } regmatch_t;
  .EE
+.\".IP
+.\" FIXME: Add a description?
  .IP
  Conforming to: POSIX.1-2001 and later.
  .IP

I added that comment to every type that lacks a description so that we can see them easier. In other types I embedded that comment in the patch with the documentation, but in this case, the type was already documented, so I had to add an extra commit.

Cheers,

Alex

#7 lore raw

PATCH 3/9 system_data_types.7: Document sigevent

In reply to Alejandro Colomar
---
 man7/system_data_types.7 | 57 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 5 deletions(-)
man7/system_data_types.7 +52 -5
index 48871e4eb..53c289e31 100644
@@ -133,6 +133,51 @@ and
 .I ssize_t
 types in this page.
 .TP
+.I sigevent
+.IP
+Include:
+.IR <signal.h> ;
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.IR <time.h> .
+.IP
+.EX
+struct sigevent {
+    int             sigev_notify; /* Notification type */
+    int             sigev_signo;  /* Signal number */
+    union sigval    sigev_value;  /* Signal value */
+    void          (*sigev_notify_function)(union sigval);
+                                  /* Notification function */
+    pthread_attr_t *sigev_notify_attributes;
+                                  /* Notification attributes */
+};
+.EE
+.\".IP
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+Notes:
+.I <aio.h>
+and
+.I <time.h>
+define
+.I sigevent
+since POSIX.1-2008.
+.IP
+See also:
+.BR timer_create (2),
+.BR getaddrinfo_a (3),
+.BR lio_listio (3),
+.BR mq_notify (3)
+.\".IP
+.\"See also the
+.\".I aiocb	FIXME
+.\"structure in this page.
+.TP
 .I sigval
 .IP
 Include:
@@ -153,12 +198,14 @@ See also:
 .BR pthread_sigqueue (3),
 .BR sigqueue (3),
 .BR sigevent (7)
-.\".IP
-.\"See also the
-.\".I sigevent	FIXME
-.\"structure and the
+.IP
+See also the
+.I sigevent
+structure
+.\"and the
 .\".I siginfo_t	FIXME
-.\"type in this page.
+.\"type
+in this page.
 .TP
 .I size_t
 .IP
Signature · 1 line
2.28.0
#8 lore raw

Re: [PATCH 3/9] system_data_types.7: Document sigevent

Hello Alex,

Quoted 4 lines · Alejandro Colomar
---
 man7/system_data_types.7 | 57 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 5 deletions(-)

Thanks, Alex. Patch applied. I added a line re description, deferring to sigevent(7).

Cheers,

Michael

Quoted 77 lines
man7/system_data_types.7 +52 -5
index 48871e4eb..53c289e31 100644
@@ -133,6 +133,51 @@ and
 .I ssize_t
 types in this page.
 .TP
+.I sigevent
+.IP
+Include:
+.IR <signal.h> ;
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.IR <time.h> .
+.IP
+.EX
+struct sigevent {
+    int             sigev_notify; /* Notification type */
+    int             sigev_signo;  /* Signal number */
+    union sigval    sigev_value;  /* Signal value */
+    void          (*sigev_notify_function)(union sigval);
+                                  /* Notification function */
+    pthread_attr_t *sigev_notify_attributes;
+                                  /* Notification attributes */
+};
+.EE
+.\".IP
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+Notes:
+.I <aio.h>
+and
+.I <time.h>
+define
+.I sigevent
+since POSIX.1-2008.
+.IP
+See also:
+.BR timer_create (2),
+.BR getaddrinfo_a (3),
+.BR lio_listio (3),
+.BR mq_notify (3)
+.\".IP
+.\"See also the
+.\".I aiocb	FIXME
+.\"structure in this page.
+.TP
 .I sigval
 .IP
 Include:
@@ -153,12 +198,14 @@ See also:
 .BR pthread_sigqueue (3),
 .BR sigqueue (3),
 .BR sigevent (7)
-.\".IP
-.\"See also the
-.\".I sigevent	FIXME
-.\"structure and the
+.IP
+See also the
+.I sigevent
+structure
+.\"and the
 .\".I siginfo_t	FIXME
-.\"type in this page.
+.\"type
+in this page.
 .TP
 .I size_t
 .IP
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/
#9 lore raw

Re: [PATCH 3/9] system_data_types.7: Document sigevent

Quoted 9 lines · Michael Kerrisk (man-pages)

Hello Alex,

Quoted 4 lines · Alejandro Colomar
---
  man7/system_data_types.7 | 57 ++++++++++++++++++++++++++++++++++++----
  1 file changed, 52 insertions(+), 5 deletions(-)
Quoted 6 lines

Thanks, Alex. Patch applied. I added a line re description, deferring to sigevent(7).

Cheers,

Michael

Thanks, Michael.

Cheers,

Alex

#11 lore raw

Re: [PATCH 4/9] sigevent.3: New link to new documented type in system_data_types(7)

Hi Alex,

Quoted 5 lines · Alejandro Colomar
---
 man3/sigevent.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/sigevent.3

I think that I won't apply this, since it will hide sigevent(7). Okay?

Thanks,

Michael

Quoted 9 lines
man3/sigevent.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
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/
#12 lore raw

Re: [PATCH 4/9] sigevent.3: New link to new documented type in system_data_types(7)

Hi Michael,

Quoted 18 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 5 lines · Alejandro Colomar
---
  man3/sigevent.3 | 1 +
  1 file changed, 1 insertion(+)

create mode 100644 man3/sigevent.3

I think that I won't apply this, since it will hide sigevent(7). Okay?

Thanks,

Michael

Quoted 1 line
Quoted 10 lines

man3/sigevent.3 line 1

Quoted 8 lines
man3/sigevent.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

Fine, sigevent(7) already documents the type, so it's perfect. The type will be documented in system_data_types.7 anyway, so no problem.

I guess you'll add a reference to system_data_types(7) in sigevent(7), right?

Thanks,

Alex

#13 lore raw

Re: [PATCH 4/9] sigevent.3: New link to new documented type in system_data_types(7)

Quoted 33 lines · Alejandro Colomar

Hi Michael,

Quoted 18 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 5 lines · Alejandro Colomar
---
  man3/sigevent.3 | 1 +
  1 file changed, 1 insertion(+)

create mode 100644 man3/sigevent.3

I think that I won't apply this, since it will hide sigevent(7). Okay?

Thanks,

Michael

Quoted 1 line
Quoted 10 lines

man3/sigevent.3 line 1

Quoted 8 lines
man3/sigevent.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Quoted 5 lines

Fine, sigevent(7) already documents the type, so it's perfect. The type will be documented in system_data_types.7 anyway, so no problem.

I guess you'll add a reference to system_data_types(7) in sigevent(7), right?

Do you think it's needed? I"m not so sure...

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/
#14 lore raw

Re: [PATCH 4/9] sigevent.3: New link to new documented type in system_data_types(7)

Quoted 7 lines · Michael Kerrisk (man-pages)
Quoted 5 lines

Fine, sigevent(7) already documents the type, so it's perfect. The type will be documented in system_data_types.7 anyway, so no problem.

I guess you'll add a reference to system_data_types(7) in sigevent(7), right?

Do you think it's needed? I"m not so sure...

Not sure.

There are a few things that are documented in system_data_types but not in sigevent(7), but not too many.

Thanks,

Alex

Quoted 6 lines

Thanks,

Michael

#15 lore raw

Re: [PATCH 4/9] sigevent.3: New link to new documented type in system_data_types(7)

Quoted 10 lines · Alejandro Colomar
Quoted 6 lines · Michael Kerrisk (man-pages)
Quoted 5 lines

Fine, sigevent(7) already documents the type, so it's perfect. The type will be documented in system_data_types.7 anyway, so no problem.

I guess you'll add a reference to system_data_types(7) in sigevent(7), right?

Quoted 6 lines
Quoted 1 line

Do you think it's needed? I"m not so sure...

Not sure.

There are a few things that are documented in system_data_types but not in sigevent(7), but not too many.

For the moment, I think the reference probably isn't needed.

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/
#16 lore raw

PATCH 5/9 system_data_types.7: srcfix: cosmetic: Visually sparate types

In reply to Alejandro Colomar
---
 man7/system_data_types.7 | 12 ++++++++++++
 1 file changed, 12 insertions(+)
man7/system_data_types.7 +12 -0
index 53c289e31..8c0c78954 100644
@@ -61,6 +61,7 @@ system_data_types \- overview of system data types
 .\"		* Notes (optional)
 .\"
 .\"		* See also
+.\"------------------------------------- ptrdiff_t --------------------/
 .TP
 .I ptrdiff_t
 .IP
@@ -81,6 +82,7 @@ See also the
 and
 .I ssize_t
 types in this page.
+.\"------------------------------------- regmatch_t -------------------/
 .TP
 .I regmatch_t
 .IP
@@ -103,6 +105,7 @@ Conforming to: POSIX.1-2001 and later.
 .IP
 See also:
 .BR regexec (3)
+.\"------------------------------------- regoff_t ---------------------/
 .TP
 .I regoff_t
 .IP
@@ -132,6 +135,7 @@ structure and the
 and
 .I ssize_t
 types in this page.
+.\"------------------------------------- sigevent ---------------------/
 .TP
 .I sigevent
 .IP
@@ -177,6 +181,7 @@ See also:
 .\"See also the
 .\".I aiocb	FIXME
 .\"structure in this page.
+.\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
 .IP
@@ -206,6 +211,7 @@ structure
 .\".I siginfo_t	FIXME
 .\"type
 in this page.
+.\"------------------------------------- size_t -----------------------/
 .TP
 .I size_t
 .IP
@@ -301,6 +307,7 @@ See also the
 and
 .I ssize_t
 types in this page.
+.\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
 .IP
@@ -343,6 +350,7 @@ See also the
 and
 .I size_t
 types in this page.
+.\"------------------------------------- suseconds_t ------------------/
 .TP
 .I suseconds_t
 .IP
@@ -362,6 +370,7 @@ Conforming to: POSIX.1-2001 and later.
 See also the
 .I timeval
 structure in this page.
+.\"------------------------------------- time_t -----------------------/
 .TP
 .I time_t
 .IP
@@ -402,6 +411,7 @@ See also:
 .BR time (2),
 .BR ctime (3),
 .BR difftime (3)
+.\"------------------------------------- timer_t ----------------------/
 .TP
 .I timer_t
 .IP
@@ -422,6 +432,7 @@ See also:
 .BR timer_delete (2),
 .BR timer_getoverrun (2),
 .BR timer_settime (2)
+.\"------------------------------------- timespec ---------------------/
 .TP
 .I timespec
 .IP
@@ -457,6 +468,7 @@ See also:
 .BR nanosleep (2),
 .BR timerfd_gettime (2),
 .BR timer_gettime (2)
+.\"------------------------------------- timeval ----------------------/
 .TP
 .I timeval
 .IP
Signature · 1 line
2.28.0
#17 lore raw

Re: [PATCH 5/9] system_data_types.7: srcfix: cosmetic: Visually sparate types

Quoted 1 line · Alejandro Colomar

Thanks, Alex. Good idea. Patch applied.

Cheers,

Michael

Quoted 105 lines
---
 man7/system_data_types.7 | 12 ++++++++++++
 1 file changed, 12 insertions(+)
man7/system_data_types.7 +12 -0
index 53c289e31..8c0c78954 100644
@@ -61,6 +61,7 @@ system_data_types \- overview of system data types
 .\"		* Notes (optional)
 .\"
 .\"		* See also
+.\"------------------------------------- ptrdiff_t --------------------/
 .TP
 .I ptrdiff_t
 .IP
@@ -81,6 +82,7 @@ See also the
 and
 .I ssize_t
 types in this page.
+.\"------------------------------------- regmatch_t -------------------/
 .TP
 .I regmatch_t
 .IP
@@ -103,6 +105,7 @@ Conforming to: POSIX.1-2001 and later.
 .IP
 See also:
 .BR regexec (3)
+.\"------------------------------------- regoff_t ---------------------/
 .TP
 .I regoff_t
 .IP
@@ -132,6 +135,7 @@ structure and the
 and
 .I ssize_t
 types in this page.
+.\"------------------------------------- sigevent ---------------------/
 .TP
 .I sigevent
 .IP
@@ -177,6 +181,7 @@ See also:
 .\"See also the
 .\".I aiocb	FIXME
 .\"structure in this page.
+.\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
 .IP
@@ -206,6 +211,7 @@ structure
 .\".I siginfo_t	FIXME
 .\"type
 in this page.
+.\"------------------------------------- size_t -----------------------/
 .TP
 .I size_t
 .IP
@@ -301,6 +307,7 @@ See also the
 and
 .I ssize_t
 types in this page.
+.\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
 .IP
@@ -343,6 +350,7 @@ See also the
 and
 .I size_t
 types in this page.
+.\"------------------------------------- suseconds_t ------------------/
 .TP
 .I suseconds_t
 .IP
@@ -362,6 +370,7 @@ Conforming to: POSIX.1-2001 and later.
 See also the
 .I timeval
 structure in this page.
+.\"------------------------------------- time_t -----------------------/
 .TP
 .I time_t
 .IP
@@ -402,6 +411,7 @@ See also:
 .BR time (2),
 .BR ctime (3),
 .BR difftime (3)
+.\"------------------------------------- timer_t ----------------------/
 .TP
 .I timer_t
 .IP
@@ -422,6 +432,7 @@ See also:
 .BR timer_delete (2),
 .BR timer_getoverrun (2),
 .BR timer_settime (2)
+.\"------------------------------------- timespec ---------------------/
 .TP
 .I timespec
 .IP
@@ -457,6 +468,7 @@ See also:
 .BR nanosleep (2),
 .BR timerfd_gettime (2),
 .BR timer_gettime (2)
+.\"------------------------------------- timeval ----------------------/
 .TP
 .I timeval
 .IP
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/
#18 lore raw

PATCH 6/9 system_data_types.7: Document aiocb

In reply to Alejandro Colomar
---
 man7/system_data_types.7 | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)
man7/system_data_types.7 +36 -4
index 8c0c78954..f7d25bec9 100644
@@ -61,6 +61,38 @@ system_data_types \- overview of system data types
 .\"		* Notes (optional)
 .\"
 .\"		* See also
+.\"------------------------------------- aiocb ------------------------/
+.TP
+.I aiocb
+.IP
+Include:
+.IR <aio.h> .
+.IP
+.EX
+struct aiocb {
+    int             aio_fildes;    /* File descriptor */
+    off_t           aio_offset;    /* File offset */
+    volatile void  *aio_buf;       /* Location of buffer */
+    size_t          aio_nbytes;    /* Length of transfer */
+    int             aio_reqprio;   /* Request priority offset */
+    struct sigevent aio_sigevent;  /* Signal number and value */
+    int             aio_lio_opcode;/* Operation to be performed */
+};
+.EE
+.\".IP
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR aio_cancel (3),
+.BR aio_error (3),
+.BR aio_fsync (3),
+.BR aio_read (3),
+.BR aio_return (3),
+.BR aio_suspend (3),
+.BR aio_write (3),
+.BR lio_listio (3)
 .\"------------------------------------- ptrdiff_t --------------------/
 .TP
 .I ptrdiff_t
@@ -177,10 +209,10 @@ See also:
 .BR getaddrinfo_a (3),
 .BR lio_listio (3),
 .BR mq_notify (3)
-.\".IP
-.\"See also the
-.\".I aiocb	FIXME
-.\"structure in this page.
+.IP
+See also the
+.I aiocb
+structure in this page.
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
Signature · 1 line
2.28.0
#20 lore raw

Re: [PATCH 7/9] aiocb.3: New link to new documented type in system_data_types(7)

Quoted 1 line · Alejandro Colomar

Thanks, Alex. Patch applied.

Cheers,

Michael

Quoted 13 lines
---
 man3/aiocb.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/aiocb.3
man3/aiocb.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
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/
#21 lore raw

PATCH 8/9 system_data_types.7: Document siginfo_t

In reply to Alejandro Colomar

Note: There are a few members off this structure that are not required by POSIX (XSI extensions, and such).

I simply chose to not document them at all.

---
 man7/system_data_types.7 | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)
man7/system_data_types.7 +32 -3
index f7d25bec9..b705ed5ae 100644
@@ -213,6 +213,35 @@ See also:
 See also the
 .I aiocb
 structure in this page.
+.\"------------------------------------- siginfo_t --------------------/
+.TP
+.I siginfo_t
+.IP
+Include:
+.IR <signal.h> ;
+or
+.IR <sys/wait.h> .
+.IP
+.EX
+typedef struct {
+    int             si_signo; /* Signal number */
+    int             si_code; /* Signal code */
+
+    pid_t           si_pid; /* Sending process ID */
+    uid_t           si_uid; /* Real user ID of sending process */
+    void           *si_addr; /* Address of faulting instruction */
+    int             si_status; /* Exit value or signal */
+
+    union sigval    si_value; /* Signal value */
+} siginfo_t;
+.EE
+.\".IP
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR regexec (3)
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
@@ -239,9 +268,9 @@ See also:
 See also the
 .I sigevent
 structure
-.\"and the
-.\".I siginfo_t	FIXME
-.\"type
+and the
+.I siginfo_t
+type
 in this page.
 .\"------------------------------------- size_t -----------------------/
 .TP
Signature · 1 line
2.28.0
#22 lore raw

Re: [PATCH 8/9] system_data_types.7: Document siginfo_t

Hi Alex,

See below.

Quoted 37 lines · Alejandro Colomar

Note: There are a few members off this structure that are not required by POSIX (XSI extensions, and such).

I simply chose to not document them at all.

---
 man7/system_data_types.7 | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)
man7/system_data_types.7 +19 -0
index f7d25bec9..b705ed5ae 100644
@@ -213,6 +213,35 @@ See also:
 See also the
 .I aiocb
 structure in this page.
+.\"------------------------------------- siginfo_t --------------------/
+.TP
+.I siginfo_t
+.IP
+Include:
+.IR <signal.h> ;
+or
+.IR <sys/wait.h> .
+.IP
+.EX
+typedef struct {
+    int             si_signo; /* Signal number */
+    int             si_code; /* Signal code */
+
+    pid_t           si_pid; /* Sending process ID */
+    uid_t           si_uid; /* Real user ID of sending process */
+    void           *si_addr; /* Address of faulting instruction */
+    int             si_status; /* Exit value or signal */
+

man7/system_data_types.7 See also: · line 244

Quoted 10 lines
man7/system_data_types.7 +10 -0
+    union sigval    si_value; /* Signal value */
+} siginfo_t;
+.EE
+.\".IP
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR regexec (3)

Long day for both of us, and I think the line above shows that :-).

I'm not applying this patch (or the corresponding link patch)...

For "description" (in the next iteration of this patch), I think you should defer to sigaction(2).

Thanks

Michael

Quoted 17 lines
man7/system_data_types.7 +3 -3
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
@@ -239,9 +268,9 @@ See also:
 See also the
 .I sigevent
 structure
-.\"and the
-.\".I siginfo_t	FIXME
-.\"type
+and the
+.I siginfo_t
+type
 in this page.
 .\"------------------------------------- size_t -----------------------/
 .TP
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/
#23 lore raw

Re: [PATCH 8/9] system_data_types.7: Document siginfo_t

Hi Michael,

Quoted 47 lines · Michael Kerrisk (man-pages)

Hi Alex,

See below.

Quoted 41 lines · Alejandro Colomar

Note: There are a few members off this structure that are not required by POSIX (XSI extensions, and such).

I simply chose to not document them at all.

---
  man7/system_data_types.7 | 35 ++++++++++++++++++++++++++++++++---
  1 file changed, 32 insertions(+), 3 deletions(-)
man7/system_data_types.7 +23 -0
index f7d25bec9..b705ed5ae 100644
@@ -213,6 +213,35 @@ See also:
  See also the
  .I aiocb
  structure in this page.
+.\"------------------------------------- siginfo_t --------------------/
+.TP
+.I siginfo_t
+.IP
+Include:
+.IR <signal.h> ;
+or
+.IR <sys/wait.h> .
+.IP
+.EX
+typedef struct {
+    int             si_signo; /* Signal number */
+    int             si_code; /* Signal code */
+
+    pid_t           si_pid; /* Sending process ID */
+    uid_t           si_uid; /* Real user ID of sending process */
+    void           *si_addr; /* Address of faulting instruction */
+    int             si_status; /* Exit value or signal */
+
+    union sigval    si_value; /* Signal value */
+} siginfo_t;
+.EE
+.\".IP
Quoted 8 lines

man7/system_data_types.7 See also: · line 244

Quoted 6 lines
man7/system_data_types.7 +6 -0
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR regexec (3)

Long day for both of us, and I think the line above shows that :-).

Ooooooooops! :p

I'll rebase tomorrow, and then I'll start fixing things...

Too many patches for today!

Quoted 5 lines

I'm not applying this patch (or the corresponding link patch)...

For "description" (in the next iteration of this patch), I think you should defer to sigaction(2).

Ok, thanks!

Cheers,

Alex

Quoted 24 lines

Thanks

Michael

Quoted 17 lines
man7/system_data_types.7 +3 -3
  .\"------------------------------------- sigval -----------------------/
  .TP
  .I sigval
@@ -239,9 +268,9 @@ See also:
  See also the
  .I sigevent
  structure
-.\"and the
-.\".I siginfo_t	FIXME
-.\"type
+and the
+.I siginfo_t
+type
  in this page.
  .\"------------------------------------- size_t -----------------------/
  .TP
#24 lore raw

PATCH v2 8/9 system_data_types.7: Document siginfo_t

In reply to Michael Kerrisk (man-pages)

Note: There are a few members off this structure that are not required by POSIX (XSI extensions, and such).

I simply chose to not document them at all.

---

Hello Michael,

Clearly I needed the weekend!
Here's the patch as it should have been.

Cheers,

Alex

 man7/system_data_types.7 | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)
man7/system_data_types.7 +36 -3
index a7955f331..080f0057f 100644
@@ -213,6 +213,39 @@ See also:
 See also the
 .I aiocb
 structure in this page.
+.\"------------------------------------- siginfo_t --------------------/
+.TP
+.I siginfo_t
+.IP
+Include:
+.IR <signal.h> ;
+or
+.IR <sys/wait.h> .
+.IP
+.EX
+typedef struct {
+    int             si_signo; /* Signal number */
+    int             si_code; /* Signal code */
+
+    pid_t           si_pid; /* Sending process ID */
+    uid_t           si_uid; /* Real user ID of sending process */
+    void           *si_addr; /* Address of faulting instruction */
+    int             si_status; /* Exit value or signal */
+
+    union sigval    si_value; /* Signal value */
+} siginfo_t;
+.EE
+.\".IP
+.\" FIXME: Add a description?
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR pidfd_send_signal (2),
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR sigwaitinfo (2),
+.BR psiginfo (3)
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
@@ -239,9 +272,9 @@ See also:
 See also the
 .I sigevent
 structure
-.\"and the
-.\".I siginfo_t	FIXME
-.\"type
+and the
+.I siginfo_t
+type
 in this page.
 .\"------------------------------------- size_t -----------------------/
 .TP
Signature · 1 line
2.28.0
#25 lore raw

Re: [PATCH v2 8/9] system_data_types.7: Document siginfo_t

Hello Alex,

Quoted 5 lines · Alejandro Colomar

Note: There are a few members off this structure that are not required by POSIX (XSI extensions, and such).

I simply chose to not document them at all.

Quoted 7 lines

---

Hello Michael,

Clearly I needed the weekend!
Here's the patch as it should have been.

Thanks! Patch applied. Some notes below.

Quoted 22 lines
 man7/system_data_types.7 | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)
man7/system_data_types.7 +11 -0
index a7955f331..080f0057f 100644
@@ -213,6 +213,39 @@ See also:
 See also the
 .I aiocb
 structure in this page.
+.\"------------------------------------- siginfo_t --------------------/
+.TP
+.I siginfo_t
+.IP
+Include:
+.IR <signal.h> ;
+or
+.IR <sys/wait.h> .
+.IP
+.EX
+typedef struct {

man7/system_data_types.7 See also: · line 236

Quoted 10 lines
man7/system_data_types.7 +10 -0
+    int             si_signo; /* Signal number */
+    int             si_code; /* Signal code */
+
+    pid_t           si_pid; /* Sending process ID */
+    uid_t           si_uid; /* Real user ID of sending process */
+    void           *si_addr; /* Address of faulting instruction */
+    int             si_status; /* Exit value or signal */
+
+    union sigval    si_value; /* Signal value */
+} siginfo_t;

Some minor white space issues in the above structure (blank lines, misaligned comments); I fixed them.

man7/system_data_types.7 See also: · line 239

Quoted 3 lines
man7/system_data_types.7 +3 -0
+.EE
+.\".IP
+.\" FIXME: Add a description?

Generally, I think we always should have a description, even if very short. I added one, mainly in the form of a reference to sigaction(2).

man7/system_data_types.7 See also: · line 248

Quoted 9 lines
man7/system_data_types.7 +9 -0
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR pidfd_send_signal (2),
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR sigwaitinfo (2),
+.BR psiginfo (3)

That list is "just right"; thanks.

Quoted 6 lines
man7/system_data_types.7 +0 -0
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
@@ -239,9 +272,9 @@ See also:
 See also the
 .I sigevent

man7/system_data_types.7 See also: · line 280

Quoted 10 lines
man7/system_data_types.7 +3 -3
 structure
-.\"and the
-.\".I siginfo_t	FIXME
-.\"type
+and the
+.I siginfo_t
+type
 in this page.
 .\"------------------------------------- size_t -----------------------/
 .TP

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/
#27 lore raw

Re: [PATCH v2 9/9] siginfo_t.3: New link to new documented type in system_data_types(7)

Quoted 13 lines · Alejandro Colomar
---
 man3/siginfo_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/siginfo_t.3
man3/siginfo_t.3 new file +0 -0
new file mode 100644
index 000000000..db50c0f09

man3/siginfo_t.3 line 1

Quoted 1 line
man3/siginfo_t.3 new file +1 -0
@@ -0,0 +1 @@
+.so man7/system_data_types.7

Thanks, Alex. Patch applied.

Cheers,

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/