[PATCH 0/9] Document aiocb, sigevent, siginfo_t

[PATCH 0/9] Document aiocb, sigevent, siginfo_t

[Alejandro Colomar]

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

-- 
2.28.0

[PATCH 1/9] system_data_types.7: ffix

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index eb4718491..5352f3ef2 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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.
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 5352f3ef2..48871e4eb 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 57 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 48871e4eb..53c289e31 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/sigevent.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/sigevent.3

diff --git a/man3/sigevent.3 b/man3/sigevent.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigevent.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 53c289e31..8c0c78954 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

[PATCH 6/9] system_data_types.7: Document aiocb

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 8c0c78954..f7d25bec9 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/aiocb.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/aiocb.3

diff --git a/man3/aiocb.3 b/man3/aiocb.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/aiocb.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

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

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index f7d25bec9..b705ed5ae 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/siginfo_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/siginfo_t.3

diff --git a/man3/siginfo_t.3 b/man3/siginfo_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/siginfo_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

[Michael Kerrisk (man-pages)]

On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)


Thanks, Alex. Patch applied.

Cheers,

Michael


> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index eb4718491..5352f3ef2 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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.
> 


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

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

[Michael Kerrisk (man-pages)]

On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>


Thanks, Alex. Patch applied.

Cheers,

Michael


> ---
>  man7/system_data_types.7 | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 5352f3ef2..48871e4eb 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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
> 


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

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

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/18/20 10:50 PM, Michael Kerrisk (man-pages) wrote:
> On 9/18/20 7:04 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> 
> 
> 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

>> ---
>>  man7/system_data_types.7 | 2 ++
>>  1 file changed, 2 insertions(+)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 5352f3ef2..48871e4eb 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -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
>>
> 
> 


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

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

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  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


> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 48871e4eb..53c289e31 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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
> 


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

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

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  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


> 
> diff --git a/man3/sigevent.3 b/man3/sigevent.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/sigevent.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


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

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

[Michael Kerrisk (man-pages)]

On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>


Thanks, Alex. Good idea. Patch applied.

Cheers,

Michael


> ---
>  man7/system_data_types.7 | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 53c289e31..8c0c78954 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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
> 


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

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

[Michael Kerrisk (man-pages)]

On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Thanks, Alex. Patch applied.

Cheers,

Michael


> ---
>  man3/aiocb.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/aiocb.3
> 
> diff --git a/man3/aiocb.3 b/man3/aiocb.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/aiocb.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


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

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

[Alejandro Colomar]

Hi Michael,

On 2020-09-18 23:03, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 9/18/20 10:50 PM, Michael Kerrisk (man-pages) wrote:
>> On 9/18/20 7:04 PM, Alejandro Colomar wrote:
>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>>
>>
>> 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
> 
>>> ---
>>>   man7/system_data_types.7 | 2 ++
>>>   1 file changed, 2 insertions(+)
>>>
>>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>>> index 5352f3ef2..48871e4eb 100644
>>> --- a/man7/system_data_types.7
>>> +++ b/man7/system_data_types.7
>>> @@ -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

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

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

[Alejandro Colomar]

On 2020-09-18 23:09, Michael Kerrisk (man-pages) wrote:
> Hello Alex,
> 
> On 9/18/20 7:04 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>   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

Thanks, Michael.

Cheers,

Alex

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

[Alejandro Colomar]

Hi Michael,

On 2020-09-18 23:10, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 9/18/20 7:04 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>   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
> 
> 
>>
>> diff --git a/man3/sigevent.3 b/man3/sigevent.3
>> new file mode 100644
>> index 000000000..db50c0f09
>> --- /dev/null
>> +++ b/man3/sigevent.3
>> @@ -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

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

[Michael Kerrisk (man-pages)]

Hi Alex,

See below.


On 9/18/20 7:04 PM, Alejandro Colomar wrote:
> 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.
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 35 ++++++++++++++++++++++++++++++++---
>  1 file changed, 32 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index f7d25bec9..b705ed5ae 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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)

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

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


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

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

[Michael Kerrisk (man-pages)]

On 9/18/20 11:39 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> On 2020-09-18 23:10, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On 9/18/20 7:04 PM, Alejandro Colomar wrote:
>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>>> ---
>>>   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
>>
>>
>>>
>>> diff --git a/man3/sigevent.3 b/man3/sigevent.3
>>> new file mode 100644
>>> index 000000000..db50c0f09
>>> --- /dev/null
>>> +++ b/man3/sigevent.3
>>> @@ -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?

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

Thanks,

Michael


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

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

[Alejandro Colomar]

Hi Michael,

On 2020-09-18 23:42, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> See below.
> 
> 
> On 9/18/20 7:04 PM, Alejandro Colomar wrote:
>> 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.
>>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>   man7/system_data_types.7 | 35 ++++++++++++++++++++++++++++++++---
>>   1 file changed, 32 insertions(+), 3 deletions(-)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index f7d25bec9..b705ed5ae 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -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)
> 
> 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!

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

> 
> Thanks
> 
> Michael
> 
>>   .\"------------------------------------- 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
>>
> 
> 

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

[Alejandro Colomar]

On 2020-09-18 23:43, Michael Kerrisk (man-pages) wrote:
>> 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

> 
> Thanks,
> 
> Michael
> 
> 

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

[Michael Kerrisk (man-pages)]

On Fri, 18 Sep 2020 at 23:57, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
>
>
> On 2020-09-18 23:43, Michael Kerrisk (man-pages) wrote:
> >> 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.

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

Thanks,

Michael


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

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

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

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index a7955f331..080f0057f 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/siginfo_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/siginfo_t.3

diff --git a/man3/siginfo_t.3 b/man3/siginfo_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/siginfo_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/20/20 8:05 PM, Alejandro Colomar wrote:
> 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.
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hello Michael,
> 
> Clearly I needed the weekend!
> Here's the patch as it should have been.

Thanks! Patch applied. Some notes below.

>  man7/system_data_types.7 | 39 ++++++++++++++++++++++++++++++++++++---
>  1 file changed, 36 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index a7955f331..080f0057f 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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;

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

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

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

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

Thanks,

Michael



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

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

[Michael Kerrisk (man-pages)]

On 9/20/20 8:05 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man3/siginfo_t.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/siginfo_t.3
> 
> diff --git a/man3/siginfo_t.3 b/man3/siginfo_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/siginfo_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 

Thanks, Alex. Patch applied.

Cheers,

Michael


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