[PATCH 0/4] Document regoff_t (and a few minor patches)

[PATCH 0/4] Document regoff_t (and a few minor patches)

[Alejandro Colomar]

Hi Michael,

Documentation for regoff_t + a few minor patches.
(apply after ptrdiff_t patches)

I removed the reference from ptrdiff_t to regoff_t, as it is not really
relevant to ptrdiff_t.

I see this is fast, so maybe I'll start sending bigger patchsets.
That way it'll be easier for you to apply them sorted.

Cheers,

Alex.


Alejandro Colomar (4):
  system_data_types.7: wfix
  system_data_types.7: Document regoff_t
  regoff_t.3: New link to new documented type in system_data_types(7)
  system_data_types.7: srcfix: Add FIXME notes

 man3/regoff_t.3          |  1 +
 man7/system_data_types.7 | 38 +++++++++++++++++++++++++++++++++-----
 2 files changed, 34 insertions(+), 5 deletions(-)
 create mode 100644 man3/regoff_t.3

-- 
2.28.0

[PATCH 1/4] system_data_types.7: wfix

[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 dba80cf6f..8969ee966 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -350,7 +350,7 @@ struct timespec {
 };
 .EE
 .IP
-Describes times in seconds and nanoseconds.
+Describes elapsed time in seconds and nanoseconds.
 .IP
 Conforming to: C11 and later; POSIX.1-2001 and later.
 .IP
@@ -379,7 +379,7 @@ struct timeval {
 };
 .EE
 .IP
-Describes times in seconds and microseconds.
+Describes elapsed time in seconds and microseconds.
 .IP
 Conforming to: POSIX.1-2001 and later.
 .IP
-- 
2.28.0

[PATCH 2/4] system_data_types.7: Document regoff_t

[Alejandro Colomar]

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 8969ee966..d96703b1d 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -77,12 +77,40 @@ capable of storing values in the range
 Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also the
-.\".I regoff_t ,	FIXME: uncomment when regoff_t is documented.
 .I size_t
 and
 .I ssize_t
 types in this page.
 .TP
+.I regoff_t
+.IP
+Include:
+.I <regex.h>.
+.IP
+According to POSIX, it shall be a signed integer type
+capable of storing the largest value that can be stored in either a
+.I ptrdiff_t
+type or a
+.I ssize_t
+type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+Notes: Prior to POSIX.1-2008, the type was capable of storing
+the largest value that can be stored in either an
+.I off_t
+type or a
+.I ssize_t
+type.
+.IP
+See also the
+.\".I regmatch_t	FIXME
+.\"structure and the
+.I ptrdiff_t
+and
+.I ssize_t
+types in this page.
+.TP
 .I sigval
 .IP
 Include:
-- 
2.28.0

[PATCH 3/4] regoff_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/regoff_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/regoff_t.3

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

[PATCH 4/4] system_data_types.7: srcfix: Add FIXME notes

[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 d96703b1d..16dcb7d66 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -133,9 +133,9 @@ See also:
 .BR sigevent (7)
 .\".IP
 .\"See also the
-.\".I sigevent
+.\".I sigevent	FIXME
 .\"structure and the
-.\".I siginfo_t
+.\".I siginfo_t	FIXME
 .\"type in this page.
 .TP
 .I size_t
-- 
2.28.0

Re: [PATCH 1/4] system_data_types.7: wfix

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/18/20 2:45 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(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index dba80cf6f..8969ee966 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -350,7 +350,7 @@ struct timespec {
>  };
>  .EE
>  .IP
> -Describes times in seconds and nanoseconds.
> +Describes elapsed time in seconds and nanoseconds.
>  .IP
>  Conforming to: C11 and later; POSIX.1-2001 and later.
>  .IP
> @@ -379,7 +379,7 @@ struct timeval {
>  };
>  .EE
>  .IP
> -Describes times in seconds and microseconds.
> +Describes elapsed time in seconds and microseconds.
>  .IP
>  Conforming to: POSIX.1-2001 and later.
>  .IP

I don;t think this patch is correct. At the least, it needs 
more explanation. As far as I can see, 'timespec' is not just 
about elapsed time. It really is just time, expressed as secs + 
nanosecs. For example, see utimensat(2), which set file timestamps
with nanosec precision.

For the moment, I'm not applying this (and I hope not doing so
doesn't break any following patch).

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 2/4] system_data_types.7: Document regoff_t

[Michael Kerrisk (man-pages)]

Hello Alex,

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

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man7/system_data_types.7 | 30 +++++++++++++++++++++++++++++-
>  1 file changed, 29 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 8969ee966..d96703b1d 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -77,12 +77,40 @@ capable of storing values in the range
>  Conforming to: C99 and later; POSIX.1-2001 and later.
>  .IP
>  See also the
> -.\".I regoff_t ,	FIXME: uncomment when regoff_t is documented.
>  .I size_t
>  and
>  .I ssize_t
>  types in this page.
>  .TP
> +.I regoff_t
> +.IP
> +Include:
> +.I <regex.h>.
> +.IP
> +According to POSIX, it shall be a signed integer type
> +capable of storing the largest value that can be stored in either a
> +.I ptrdiff_t
> +type or a
> +.I ssize_t
> +type.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +Notes: Prior to POSIX.1-2008, the type was capable of storing
> +the largest value that can be stored in either an
> +.I off_t
> +type or a
> +.I ssize_t
> +type.
> +.IP
> +See also the
> +.\".I regmatch_t	FIXME
> +.\"structure and the
> +.I ptrdiff_t
> +and
> +.I ssize_t
> +types in this page.
> +.TP
>  .I sigval
>  .IP
>  Include:
> 


-- 
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/4] regoff_t.3: New link to new documented type in system_data_types(7)

[Michael Kerrisk (man-pages)]

Hi Alex,

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

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man3/regoff_t.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/regoff_t.3
> 
> diff --git a/man3/regoff_t.3 b/man3/regoff_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/regoff_t.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 4/4] system_data_types.7: srcfix: Add FIXME notes

[Michael Kerrisk (man-pages)]

On 9/18/20 2:45 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 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index d96703b1d..16dcb7d66 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -133,9 +133,9 @@ See also:
>  .BR sigevent (7)
>  .\".IP
>  .\"See also the
> -.\".I sigevent
> +.\".I sigevent	FIXME
>  .\"structure and the
> -.\".I siginfo_t
> +.\".I siginfo_t	FIXME
>  .\"type in this page.
>  .TP
>  .I size_t
> 


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

Re: [PATCH 1/4] system_data_types.7: wfix

[Alejandro Colomar]

Hello Michael,

On 2020-09-18 22:27, Michael Kerrisk (man-pages) wrote:
>> -Describes times in seconds and microseconds.
>> +Describes elapsed time in seconds and microseconds.
>>   .IP
>>   Conforming to: POSIX.1-2001 and later.
>>   .IP
> 
> I don;t think this patch is correct. At the least, it needs
> more explanation. As far as I can see, 'timespec' is not just
> about elapsed time. It really is just time, expressed as secs +
> nanosecs. For example, see utimensat(2), which set file timestamps
> with nanosec precision.

I took that wording from timeval.3bsd. But I think you're correct.

> 
> For the moment, I'm not applying this (and I hope not doing so
> doesn't break any following patch).

That's fine.  It shouldn't break anything.

> 
> Thanks,
> 
> Michael
> 


Cheers,

Alex