[PATCH 1/3] system_data_types.7: time_t: Add Versions note

[PATCH 1/3] system_data_types.7: time_t: Add Versions note

[Alejandro Colomar]

Prior to POSIX.1-2008, POSIX allowed time_t to be a real-floating type.

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

Hi Michael,

I found this thing when writing about clock_t.

BTW, I'm not sure about the .PP before the paragraph
(it feels like "Versions" is too far away from it),
but it's unrelated to the previous Versions note, so I kept it.

Regards,

Alex


 man7/system_data_types.7 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 8a894b2e0..dc5f65c0d 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1236,6 +1236,9 @@ defines
 .I time_t
 since POSIX.1-2008.
+.PP
+Prior to POSIX.1-2008,
+the type was either an integer type or a real-floating type.
 .PP
 Conforming to:
 C99 and later; POSIX.1-2001 and later.
 .PP
-- 
2.28.0

[PATCH 2/3] system_data_types.7: Add 'clock_t'

[Alejandro Colomar]

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

Hi Michael,

Does that dash (in "real-floating") need to be escaped?

In my terminal I see it correctly,
but I've seen you escaping some of them and don't know the reason why.

Should they be escaped always, or is it only sometimes, and when?

Thanks,

Alex


 man7/system_data_types.7 | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index dc5f65c0d..6a1442ccd 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -85,6 +85,28 @@ See also:
 .BR aio_write (3),
 .BR lio_listio (3)
 .RE
+.\"------------------------------------- clock_t ----------------------/
+.TP
+.I clock_t
+.RS
+Include:
+.I <time.h>
+or
+.IR <sys/types.h> .
+Alternatively,
+.IR <sys/time.h> .
+.PP
+Used for system time in clock ticks.
+According to POSIX,
+it shall be an integer type or a real-floating type.
+.PP
+Conforming to:
+C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR times (2),
+.BR clock (3)
+.RE
 .\"------------------------------------- div_t ------------------------/
 .TP
 .I div_t
-- 
2.28.0

[PATCH 3/3] clock_t.3: New link to system_data_types(3)

[Alejandro Colomar]

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

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

Re: [PATCH 1/3] system_data_types.7: time_t: Add Versions note

[Paul Eggert]

On 10/17/20 2:37 PM, Alejandro Colomar via Libc-alpha wrote:
>   since POSIX.1-2008.
> +.PP
> +Prior to POSIX.1-2008,
> +the type was either an integer type or a real-floating type.

No actual POSIXish implementation ever made it a real-floating type, though, and 
that point should be made lest some conscientious programmer worry about a 
nonexistent porting issue.

Re: [PATCH 1/3] system_data_types.7: time_t: Add Versions note

[Zack Weinberg]

On Sat, Oct 17, 2020 at 9:05 PM Paul Eggert <eggert@cs.ucla.edu> wrote:

> On 10/17/20 2:37 PM, Alejandro Colomar via Libc-alpha wrote:
> >   since POSIX.1-2008.
> > +.PP
> > +Prior to POSIX.1-2008,
> > +the type was either an integer type or a real-floating type.
>
> No actual POSIXish implementation ever made it a real-floating type,
> though, and
> that point should be made lest some conscientious programmer worry about a
> nonexistent porting issue.


It should, at this point, be possible to compile an *exhaustive* list of
all the operating systems where time_t wassn’t an integer and/or didn’t
 count from 1 Jan 1970. Perhaps that list would effectively make the point
that this is not a real portability concern.

zw

>

Re: [PATCH 1/3] system_data_types.7: time_t: Add Versions note

[Michael Kerrisk (man-pages)]

On 10/18/20 3:05 AM, Paul Eggert wrote:
> On 10/17/20 2:37 PM, Alejandro Colomar via Libc-alpha wrote:
>>   since POSIX.1-2008.
>> +.PP
>> +Prior to POSIX.1-2008,
>> +the type was either an integer type or a real-floating type.
> 
> No actual POSIXish implementation ever made it a real-floating type, though, and 
> that point should be made lest some conscientious programmer worry about a 
> nonexistent porting issue.

Thanks for catching this, Paul!

Alex, I suggest either we drop this patch, or you could reword as
something like: 

"In POSIX.1-2001, the type was specified as being either an integer 
type or a real-floating type. However, existing implementations
used an integer type, and POSIX.1-2008 tightened the specification
to reflect this."

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/3] system_data_types.7: Add 'clock_t'

[Michael Kerrisk (man-pages)]

Hi Alex,

On 10/17/20 11:37 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> Does that dash (in "real-floating") need to be escaped?

No.

> In my terminal I see it correctly,
> but I've seen you escaping some of them and don't know the reason why.

See man-pages(7):

   Real minus character
       Where a real minus character is required (e.g., for  numbers  such
       as  -1,  for  man  page cross references such as utf-8(7), or when
       writing options that have a leading dash, such as in  ls -l),  use
       the following form in the man page source:

           \-

       This guideline applies also to code examples.

The point is that a real-minux sign is needed to that code snippets
can be cut and pasted.

> Should they be escaped always, or is it only sometimes, and when?

In normal text, no escape is needed.

>  man7/system_data_types.7 | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)


> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index dc5f65c0d..6a1442ccd 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -85,6 +85,28 @@ See also:
>  .BR aio_write (3),
>  .BR lio_listio (3)
>  .RE
> +.\"------------------------------------- clock_t ----------------------/
> +.TP
> +.I clock_t
> +.RS
> +Include:
> +.I <time.h>
> +or
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <sys/time.h> .
> +.PP
> +Used for system time in clock ticks.

Please make it:
"Used for system time either in clock ticks or CLOCKS_PER_SEC"

This type has a strange history. In my book, I note:

    Although the clock_t return type of clock() is the same
    data type that is used in the times() call, the units of
    measurement employed by these two interfaces are
    different. This is the result of historically conflicting
    definitions of clock_t in POSIX.1 and the C programming
    language standard.

> +According to POSIX,
> +it shall be an integer type or a real-floating type.
> +.PP
> +Conforming to:
> +C99 and later; POSIX.1-2001 and later.
> +.PP
> +See also:
> +.BR times (2),
> +.BR clock (3)
> +.RE
>  .\"------------------------------------- div_t ------------------------/
>  .TP
>  .I div_t

Cheers,

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 1/3] system_data_types.7: time_t: Add Versions note

[Alejandro Colomar]

On 2020-10-18 07:46, Michael Kerrisk (man-pages) wrote:
> On 10/18/20 3:05 AM, Paul Eggert wrote:
>> On 10/17/20 2:37 PM, Alejandro Colomar via Libc-alpha wrote:
>>>    since POSIX.1-2008.
>>> +.PP
>>> +Prior to POSIX.1-2008,
>>> +the type was either an integer type or a real-floating type.
>>
>> No actual POSIXish implementation ever made it a real-floating type, though, and
>> that point should be made lest some conscientious programmer worry about a
>> nonexistent porting issue.
> 
> Thanks for catching this, Paul!
> 
> Alex, I suggest either we drop this patch, or you could reword as
> something like:
> 
> "In POSIX.1-2001, the type was specified as being either an integer
> type or a real-floating type. However, existing implementations
> used an integer type, and POSIX.1-2008 tightened the specification
> to reflect this."
> 
> Thanks,
> 
> Michael
> 

Thanks, Paul!

Michael, I would opt for the simpler: drop the patch.

Thanks,

Alex

Re: [PATCH 2/3] system_data_types.7: Add 'clock_t'

[Alejandro Colomar]

Hi Michael,

On 2020-10-18 07:56, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 10/17/20 11:37 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> Hi Michael,
>>
>> Does that dash (in "real-floating") need to be escaped?
> 
> No.
> 
>> In my terminal I see it correctly,
>> but I've seen you escaping some of them and don't know the reason why.
> 
> See man-pages(7):
> 
>     Real minus character
>         Where a real minus character is required (e.g., for  numbers  such
>         as  -1,  for  man  page cross references such as utf-8(7), or when
>         writing options that have a leading dash, such as in  ls -l),  use
>         the following form in the man page source:
> 
>             \-
> 
>         This guideline applies also to code examples.
> 
> The point is that a real-minux sign is needed to that code snippets
> can be cut and pasted.
> 
>> Should they be escaped always, or is it only sometimes, and when?
> 
> In normal text, no escape is needed.


Thanks.

> 
>>   man7/system_data_types.7 | 22 ++++++++++++++++++++++
>>   1 file changed, 22 insertions(+)
> 
> 
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index dc5f65c0d..6a1442ccd 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -85,6 +85,28 @@ See also:
>>   .BR aio_write (3),
>>   .BR lio_listio (3)
>>   .RE
>> +.\"------------------------------------- clock_t ----------------------/
>> +.TP
>> +.I clock_t
>> +.RS
>> +Include:
>> +.I <time.h>
>> +or
>> +.IR <sys/types.h> .
>> +Alternatively,
>> +.IR <sys/time.h> .
>> +.PP
>> +Used for system time in clock ticks.
> 
> Please make it:
> "Used for system time either in clock ticks or CLOCKS_PER_SEC"
> 
> This type has a strange history. In my book, I note:
> 
>      Although the clock_t return type of clock() is the same
>      data type that is used in the times() call, the units of
>      measurement employed by these two interfaces are
>      different. This is the result of historically conflicting
>      definitions of clock_t in POSIX.1 and the C programming
>      language standard.


Ahhh now I get it.  So CLOCKS_PER_SEC doesn't mean CLOCK_TICKS_PER_SEC, 
right?  I always thought that it really was that, and clock() simply 
returned clock ticks.  But it looks like it returns an arbitrary 
division of the second called CLOCKS_PER_SEC.

I'll add " or CLOCKS_PER_SEC"

> 
>> +According to POSIX,
>> +it shall be an integer type or a real-floating type.
>> +.PP
>> +Conforming to:
>> +C99 and later; POSIX.1-2001 and later.
>> +.PP
>> +See also:
>> +.BR times (2),
>> +.BR clock (3)
>> +.RE
>>   .\"------------------------------------- div_t ------------------------/
>>   .TP
>>   .I div_t
> 
> Cheers,
> 
> Michael
> 
> 
> 

Thanks,

Alex

Re: [PATCH 1/3] system_data_types.7: time_t: Add Versions note

[Michael Kerrisk (man-pages)]

>> Alex, I suggest either we drop this patch, or you could reword as
>> something like:
>>
>> "In POSIX.1-2001, the type was specified as being either an integer
>> type or a real-floating type. However, existing implementations
>> used an integer type, and POSIX.1-2008 tightened the specification
>> to reflect this."
>>
>> Thanks,
>>
>> Michael
>>
> 
> Thanks, Paul!
> 
> Michael, I would opt for the simpler: drop the patch.

Okay.

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/3] system_data_types.7: Add 'clock_t'

[Michael Kerrisk (man-pages)]

Hello Alex,

>> This type has a strange history. In my book, I note:
>>
>>      Although the clock_t return type of clock() is the same
>>      data type that is used in the times() call, the units of
>>      measurement employed by these two interfaces are
>>      different. This is the result of historically conflicting
>>      definitions of clock_t in POSIX.1 and the C programming
>>      language standard.
> 
> 
> Ahhh now I get it.  So CLOCKS_PER_SEC doesn't mean CLOCK_TICKS_PER_SEC, 
> right?  I always thought that it really was that, and clock() simply 
> returned clock ticks.  But it looks like it returns an arbitrary 
> division of the second called CLOCKS_PER_SEC.

More or less. But the standard also says (in the <time.h> spec):

   The value of CLOCKS_PER_SEC shall be 1 million on 
   XSI-conformant systems.

(Yes, it is odd.)

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 3/3] clock_t.3: New link to system_data_types(3)

[Michael Kerrisk (man-pages)]

Hi Alex,

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

Patch applied. (I nearly missed this, because you didn't
resend with the V2.)

Thanks,

Michael



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

\- vs - (Was [Re: [PATCH 2/3] system_data_types.7: Add 'clock_t'])

[Alejandro Colomar]

On 2020-10-18 07:56, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 10/17/20 11:37 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> Hi Michael,
>>
>> Does that dash (in "real-floating") need to be escaped?
> 
> No.
> 
>> In my terminal I see it correctly,
>> but I've seen you escaping some of them and don't know the reason why.
> 
> See man-pages(7):
> 
>     Real minus character
>         Where a real minus character is required (e.g., for  numbers  such
>         as  -1,  for  man  page cross references such as utf-8(7), or when
>         writing options that have a leading dash, such as in  ls -l),  use
>         the following form in the man page source:
> 
>             \-
> 
>         This guideline applies also to code examples.
> 
> The point is that a real-minux sign is needed to that code snippets
> can be cut and pasted.
> 
>> Should they be escaped always, or is it only sometimes, and when?
> 
> In normal text, no escape is needed.


Hi Michael,

Then, in the following code (taken from printf.3)
the escape is wrong (unneeded) by those guidelines?:

[[
.SH NAME
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
vsprintf, vsnprintf \- formatted output conversion
]]

Thanks,

Alex