man2/: punctuate long numeric strings with digit separators
man2/: use C digit separators with \\[aq] to show "'" or ISO/IEC suffixes to clarify long binary, octal, hex, decimal numeric strings; use consistent interval notation for value ranges;
fix minor discrepancies.
[PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC [PATCH 02/11] man2/spu_run.2: fix example comment status code or-ed [PATCH 03/11] man2/: use consistent interval notation for value [PATCH 04/11] man2/open.2: punctuate octal perms with digit [PATCH 05/11] man2/reboot.2: show BCD dates in hex not decimal [PATCH 06/11] man2/reboot.2: punctuate hex in docs with digit [PATCH 07/11] man2/statfs.2: punctuate hex in docs with digit [PATCH 08/11] man2/adjtimex.2: use ISO/IEC suffixes and digit [PATCH 09/11] man2/getrandom.2: change limit to use IEC suffix [PATCH 10/11] man2/futex.2: change limit to use ISO suffix [PATCH 11/11] man2/: punctuate long numeric strings with digit
Brian Inglis (11):
man2/shmget.2: fix limit units suffix from SI to IEC man2/spu_run.2: fix example comment status code or-ed value man2/: use consistent interval notation for value ranges man2/open.2: punctuate octal perms with digit separators man2/reboot.2: show BCD dates in hex not decimal man2/reboot.2: punctuate hex in docs with digit separators man2/statfs.2: punctuate hex in docs with digit separators man2/adjtimex.2: use ISO/IEC suffixes and digit separators in ranges
and example docs
man2/getrandom.2: change limit to use IEC suffix man2/futex.2: change limit to use ISO suffix
man2/: punctuate long numeric strings with digit separators
man2/add_key.2 | 2 +- man2/adjtimex.2 | 12 ++--- man2/clock_getres.2 | 2 +- man2/clock_nanosleep.2 | 2 +- man2/eventfd.2 | 6 +-- man2/execve.2 | 2 +- man2/fcntl.2 | 4 +- man2/futex.2 | 2 +- man2/getitimer.2 | 4 +- man2/getrandom.2 | 2 +- man2/gettimeofday.2 | 2 +- man2/ioctl.2 | 4 +- man2/ioctl_console.2 | 2 +- man2/ioctl_getfsmap.2 | 4 +- man2/ioperm.2 | 2 +- man2/kexec_load.2 | 2 +- man2/link.2 | 4 +- man2/msgget.2 | 2 +- man2/nanosleep.2 | 4 +- man2/open.2 | 32 ++++++------ man2/pciconfig_read.2 | 2 +- man2/perf_event_open.2 | 2 +- man2/personality.2 | 8 +-- man2/prctl.2 | 2 +- man2/read.2 | 2 +- man2/reboot.2 | 24 ++++----- man2/semget.2 | 4 +- man2/sendfile.2 | 2 +- man2/shmget.2 | 2 +- man2/sigaction.2 | 4 +- man2/spu_run.2 | 8 +-- man2/statfs.2 | 110 ++++++++++++++++++++--------------------- man2/statx.2 | 2 +- man2/syscall.2 | 2 +- man2/timer_settime.2 | 4 +- man2/timerfd_create.2 | 2 +- man2/truncate.2 | 4 +- man2/utimensat.2 | 6 +-- man2/write.2 | 2 +- 39 files changed, 144 insertions(+), 144 deletions(-)
Signature · 1 line
2.39.0
PATCH 1/11 man2/shmget.2: fix limit units suffix from SI to IEC
--- man2/shmget.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man2/shmget.2 +1 -1
@@ -354,7 +354,7 @@ for a discussion of why this default value (rather than is used. .IP From Linux 2.2 up to Linux 3.15, the default value of -this limit was 0x2000000 (32\ MB). +this limit was 0x2000000 (32\ MiB). .IP Because it is not possible to map just part of a shared memory segment, the amount of virtual memory places another limit on the maximum size of a
Signature · 1 line
2.39.0
PATCH 2/11 man2/spu_run.2: fix example comment status code or-ed value
--- man2/spu_run.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man2/spu_run.2 +1 -1
@@ -245,7 +245,7 @@ int main(void) err(EXIT_FAILURE, "open"); /* - * We should see a status code of 0x1234002: + * We should see a status code of 0x12340002: * 0x00000002 (spu was stopped due to stop\-and\-signal) * | 0x12340000 (the stop\-and\-signal code) */
Signature · 1 line
2.39.0
PATCH 3/11 man2/: use consistent interval notation for value ranges
In reply to Brian Inglis--- man2/clock_getres.2 | 2 +- man2/clock_nanosleep.2 | 2 +- man2/getitimer.2 | 4 ++-- man2/gettimeofday.2 | 2 +- man2/nanosleep.2 | 4 ++-- man2/utimensat.2 | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-)
man2/clock_getres.2 +1 -1
@@ -272,7 +272,7 @@ does not refer to a valid instance of a clock object. .I tp.tv_sec is negative or .I tp.tv_nsec -is outside the range [0..999,999,999]. +is outside the range [0, 999,999,999]. .TP .B EINVAL The
man2/clock_nanosleep.2 +1 -1
@@ -158,7 +158,7 @@ The sleep was interrupted by a signal handler; see .B EINVAL The value in the .I tv_nsec -field was not in the range 0 to 999999999 or +field was not in the range [0, 999999999] or .I tv_sec was negative. .TP
man2/getitimer.2 +2 -2
@@ -158,7 +158,7 @@ or (since Linux 2.6.22) one of the .I tv_usec fields in the structure pointed to by .I new_value -contains a value outside the range 0 to 999999. +contains a value outside the range [0, 999999]. .SH STANDARDS POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). POSIX.1-2008 marks
@@ -253,7 +253,7 @@ POSIX.1-2001 says that .BR setitimer () should fail if a .I tv_usec -value is specified that is outside of the range 0 to 999999. +value is specified that is outside of the range [0, 999999]. However, up to and including Linux 2.6.21, Linux does not give an error, but instead silently adjusts the corresponding seconds value for the timer.
man2/gettimeofday.2 +1 -1
@@ -152,7 +152,7 @@ is invalid. .I tv.tv_sec is negative or .I tv.tv_usec -is outside the range [0..999,999]. +is outside the range [0, 999999]. .TP .BR EINVAL " (since Linux 4.3)" .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
man2/nanosleep.2 +2 -2
@@ -66,7 +66,7 @@ The structure is used to specify intervals of time with nanosecond precision. .PP -The value of the nanoseconds field must be in the range 0 to 999999999. +The value of the nanoseconds field must be in the range [0, 999999999]. .PP Compared to .BR sleep (3)
@@ -106,7 +106,7 @@ again and continue with the pause. .B EINVAL The value in the .I tv_nsec -field was not in the range 0 to 999999999 or +field was not in the range [0, 999999999] or .I tv_sec was negative. .SH STANDARDS
man2/utimensat.2 +1 -1
@@ -272,7 +272,7 @@ Invalid value in .B EINVAL Invalid value in one of the .I tv_nsec -fields (value outside range 0 to 999,999,999, and not +fields (value outside range [0, 999999999], and not .B UTIME_NOW or .BR UTIME_OMIT );
Signature · 1 line
2.39.0
PATCH 4/11 man2/open.2: punctuate octal perms with digit separators
In reply to Brian Inglis--- man2/open.2 | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-)
man2/open.2 +16 -16
@@ -308,40 +308,40 @@ The following symbolic constants are provided for .RS .TP 9 .B S_IRWXU -00700 user (file owner) has read, write, and execute permission +00\[aq]700 user (file owner) has read, write, and execute permission .TP .B S_IRUSR -00400 user has read permission +00\[aq]400 user has read permission .TP .B S_IWUSR -00200 user has write permission +00\[aq]200 user has write permission .TP .B S_IXUSR -00100 user has execute permission +00\[aq]100 user has execute permission .TP .B S_IRWXG -00070 group has read, write, and execute permission +00\[aq]070 group has read, write, and execute permission .TP .B S_IRGRP -00040 group has read permission +00\[aq]040 group has read permission .TP .B S_IWGRP -00020 group has write permission +00\[aq]020 group has write permission .TP .B S_IXGRP -00010 group has execute permission +00\[aq]010 group has execute permission .TP .B S_IRWXO -00007 others have read, write, and execute permission +00\[aq]007 others have read, write, and execute permission .TP .B S_IROTH -00004 others have read permission +00\[aq]004 others have read permission .TP .B S_IWOTH -00002 others have write permission +00\[aq]002 others have write permission .TP .B S_IXOTH -00001 others have execute permission +00\[aq]001 others have execute permission .RE .IP According to POSIX, the effect when other bits are set in
@@ -352,14 +352,14 @@ On Linux, the following bits are also honored in .RS .TP 9 .B S_ISUID -0004000 set-user-ID bit +0\[aq]004\[aq]000 set-user-ID bit .TP .B S_ISGID -0002000 set-group-ID bit (see +0\[aq]002\[aq]000 set-group-ID bit (see .BR inode (7)). .TP .B S_ISVTX -0001000 sticky bit (see +0\[aq]001\[aq]000 sticky bit (see .BR inode (7)). .RE .TP
@@ -1319,7 +1319,7 @@ flags are not specified in POSIX.1-2001, but are specified in POSIX.1-2008. Since glibc 2.12, one can obtain their definitions by defining either .B _POSIX_C_SOURCE -with a value greater than or equal to 200809L or +with a value greater than or equal to 2008\[aq]09L or .B _XOPEN_SOURCE with a value greater than or equal to 700. In glibc 2.11 and earlier, one obtains the definitions by defining
Signature · 1 line
2.39.0
Re: [PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC
In reply to Brian InglisHi Brian,
The subject is not correct, IMO. The SI also defines the Ki, Mi, ... prefixes for binary multipliers. Also, they are prefixes, not suffixes.
Cheers,
Alex
Quoted 17 lines · Brian Inglis
--- man2/shmget.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)man2/shmget.2 +1
-1@@ -354,7 +354,7 @@ for a discussion of why this default value (rather than is used. .IP From Linux 2.2 up to Linux 3.15, the default value of -this limit was 0x2000000 (32\ MB). +this limit was 0x2000000 (32\ MiB). .IP Because it is not possible to map just part of a shared memory segment, the amount of virtual memory places another limit on the maximum size of a
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Re: [PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC
Hi Alex,
TL;DR: They are bit/byte unit prefixes kibi..., ... but abstract value suffix symbols, which is how I think of them, and mainly how we use them. Perhaps we should just call them all multiples or symbosl, as we only sometimes(/rarely?) use them as unit prefixes (and seldom written out, only to explain the weird Xi notation)? Feel free to change the titles and log messages as you see fit.
[BT;DT: Many discussions about units over the decades, including various *industry* conventions about "accepted" units, values, and conversion factors, invariant regardless of SI and CODATA.
ISO/BIPM etc. uses SI to mean decimal *metric* unit prefixes (and notes that SI does not support non-physical units of information) and IEC to mean binary unit prefixes for bits, bytes, and also allows Hertz so far. See refs from:
https://en.wikipedia.org/wiki/Binary_prefix#cite_note-bipm-book-91
Bureau International des Poids et Mesures. (2006). "§3.1 SI prefixes" (PDF). The International System of Units (SI) (in French and English) (8th ed.). Paris: STEDI Media. p. 127. ISBN 978-92-822-2213-3. Archived (PDF) from the original on 2006-08-13. Retrieved 2007-02-25. [Side note:] These SI prefixes refer strictly to powers of 10. They should not be used to indicate powers of 2 (for example, one kilobit represents 1000 bits and not 1024 bits). The IEC has adopted prefixes for binary powers in the international standard IEC 60027-2: 2005, third edition, Letter symbols to be used in electrical technology – Part 2: Telecommunications and electronics. The names and symbols for the prefixes corresponding to 2^10, 2^20, 2^30, 2^40, 2^50, and 2^60 are, respectively: kibi, Ki; mebi, Mi; gibi, Gi; tebi, Ti; pebi, Pi; and exbi, Ei. Thus, for example, one kibibyte would be written: 1 KiB = 210 B = 1024 B, where B denotes a byte. Although these prefixes are *not part of the SI*, they should be used in the field of information technology to avoid the incorrect usage of the SI prefixes.
BIPM SI Brochure 2022 edition (adding ronna/ronta, quetta/quecto, etc.) English text only p.143 side note (the only uses of "bit" in the document; "byte" is not used; "information" and "word" are used only in the literate senses):
https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf#page=29
"The SI prefixes refer
strictly to powers of 10.
They should not be used to
indicate powers of 2
(for example, one kilobit
represents 1000 bits and
not 1024 bits). The names
and symbols for prefixes to
be used with powers of 2
are recommended as
follows:
kibi Ki 2^10
mebi Mi 2^20
gibi Gi 2^30
tebi Ti 2^40
pebi Pi 2^50
exbi Ei 2^60
zebi Zi 2^70
yobi Yi 2^80"
...no
robi Ri 2^90
qubi Qi 2^100
yet! ;^> ]
Quoted 27 lines · Alejandro Colomar
Hi Brian,
The subject is not correct, IMO. The SI also defines the Ki, Mi, ... prefixes for binary multipliers. Also, they are prefixes, not suffixes.
Cheers,
Alex
Quoted 17 lines · Brian Inglis
--- man2/shmget.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)man2/shmget.2 +1
-1@@ -354,7 +354,7 @@ for a discussion of why this default value (rather than is used. .IP From Linux 2.2 up to Linux 3.15, the default value of -this limit was 0x2000000 (32\ MB). +this limit was 0x2000000 (32\ MiB). .IP Because it is not possible to map just part of a shared memory segment, the amount of virtual memory places another limit on the maximum size of a
Signature · 6 lines
Take care. Thanks, Brian Inglis Calgary, Alberta, Canada La perfection est atteinte Perfection is achieved non pas lorsqu'il n'y a plus rien à ajouter not when there is no more to add mais lorsqu'il n'y a plus rien à retirer but when there is no more to cut -- Antoine de Saint-Exupéry
Re: [PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC
Hi Brian,
Quoted 7 lines · Brian Inglis
Hi Alex,
TL;DR: They are bit/byte unit prefixes kibi..., ... but abstract value suffix symbols, which is how I think of them, and mainly how we use them. Perhaps we should just call them all multiples or symbosl, as we only sometimes(/rarely?) use them as unit prefixes (and seldom written out, only to explain the weird Xi notation)? Feel free to change the titles and log messages as you see fit.
Indeed, I had doubts about using them as suffixes because that's incorrect according to the SI, but it makes sense and improves documentation, so I'm fine with the use as suffixes now. However, I'm still concerned with calling them suffixes. How about multipliers? Does it make sense to you?
Quoted 52 lines
[BT;DT: Many discussions about units over the decades, including various *industry* conventions about "accepted" units, values, and conversion factors, invariant regardless of SI and CODATA.
ISO/BIPM etc. uses SI to mean decimal *metric* unit prefixes (and notes that SI does not support non-physical units of information) and IEC to mean binary unit prefixes for bits, bytes, and also allows Hertz so far. See refs from:
https://en.wikipedia.org/wiki/Binary_prefix#cite_note-bipm-book-91
Bureau International des Poids et Mesures. (2006). "§3.1 SI prefixes" (PDF). The International System of Units (SI) (in French and English) (8th ed.). Paris:
STEDI Media. p. 127. ISBN 978-92-822-2213-3. Archived (PDF) from the original on 2006-08-13. Retrieved 2007-02-25. [Side note:] These SI prefixes refer strictly to powers of 10. They should not be used to indicate powers of 2 (for example, one kilobit represents 1000 bits and not 1024 bits). The IEC has adopted prefixes for binary powers in the international standard IEC 60027-2: 2005, third edition, Letter symbols to be used in electrical technology – Part 2:
Telecommunications and electronics. The names and symbols for the prefixes corresponding to 2^10, 2^20, 2^30, 2^40, 2^50, and 2^60 are, respectively: kibi, Ki; mebi, Mi; gibi, Gi; tebi, Ti; pebi, Pi; and exbi, Ei. Thus, for example, one kibibyte would be written: 1 KiB = 210 B = 1024 B, where B denotes a byte. Although these prefixes are *not part of the SI*, they should be used in the field of information technology to avoid the incorrect usage of the SI prefixes.BIPM SI Brochure 2022 edition (adding ronna/ronta, quetta/quecto, etc.) English text only p.143 side note (the only uses of "bit" in the document; "byte" is not used; "information" and "word" are used only in the literate senses):
https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf#page=29
"The SI prefixes refer
strictly to powers of 10.
They should not be used to
indicate powers of 2
(for example, one kilobit
represents 1000 bits and
not 1024 bits). The names
and symbols for prefixes to
be used with powers of 2
are recommended as
follows:
kibi Ki 2^10
mebi Mi 2^20
gibi Gi 2^30
tebi Ti 2^40
pebi Pi 2^50
exbi Ei 2^60
zebi Zi 2^70
yobi Yi 2^80"
Quoted 4 lines
...no
robi Ri 2^90
qubi Qi 2^100
yet! ;^> ]
Thanks. It now makes sense. Looks like the SI talks about them, but only takes them as defined by IEC, and doesn't incorporate them as their own. So, using IEC seems correct (as SI does itself).
Cheers,
Alex
BTW, this was one of the few patches that I received inline :/
Quoted 30 lines · Alejandro Colomar
Quoted 27 lines
Hi Brian,
The subject is not correct, IMO. The SI also defines the Ki, Mi, ... prefixes for binary multipliers. Also, they are prefixes, not suffixes.
Cheers,
Alex
Quoted 17 lines · Brian Inglis
--- man2/shmget.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)man2/shmget.2 +1
-1@@ -354,7 +354,7 @@ for a discussion of why this default value (rather than is used. .IP From Linux 2.2 up to Linux 3.15, the default value of -this limit was 0x2000000 (32\ MB). +this limit was 0x2000000 (32\ MiB). .IP Because it is not possible to map just part of a shared memory segment, the amount of virtual memory places another limit on the maximum size of a
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Re: [PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC
Quoted 18 lines · Alejandro Colomar
Quoted 5 lines · Brian Inglis
TL;DR: They are bit/byte unit prefixes kibi..., ... but abstract value suffix symbols, which is how I think of them, and mainly how we use them. Perhaps we should just call them all multiples or symbosl, as we only sometimes(/rarely?) use them as unit prefixes (and seldom written out, only to explain the weird Xi notation)? Feel free to change the titles and log messages as you see fit.
Indeed, I had doubts about using them as suffixes because that's incorrect according to the SI, but it makes sense and improves documentation, so I'm fine with the use as suffixes now. However, I'm still concerned with calling
them suffixes. How about multipliers? Does it make sense to you?Quoted 8 lines
[BT;DT: Many discussions about units over the decades, including various *industry* conventions about "accepted" units, values, and conversion factors, invariant regardless of SI and CODATA.
ISO/BIPM etc. uses SI to mean decimal *metric* unit prefixes (and notes that SI does not support non-physical units of information) and IEC to mean binary unit prefixes for bits, bytes, and also allows Hertz so far. See refs from:
Quoted 12 lines
Quoted 3 lines
https://en.wikipedia.org/wiki/Binary_prefix#cite_note-bipm-book-91
https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf#page=29
Thanks. It now makes sense. Looks like the SI talks about them, but only takes them as defined by IEC, and doesn't incorporate them as their own. So, using IEC seems correct (as SI does itself).
BTW, this was one of the few patches that I received inline :/
Quoted 3 lines · Alejandro Colomar
Quoted 2 lines
The subject is not correct, IMO. The SI also defines the Ki, Mi, ... prefixes for binary multipliers. Also, they are prefixes, not suffixes.
Thanks Alex,
I have regenerated with format-patch -v2 --inline and will later edit and resend as suggested and hopefully you will get what you expect to review.
Signature · 6 lines
Take care. Thanks, Brian Inglis Calgary, Alberta, Canada La perfection est atteinte Perfection is achieved non pas lorsqu'il n'y a plus rien à ajouter not when there is no more to add mais lorsqu'il n'y a plus rien à retirer but when there is no more to cut -- Antoine de Saint-Exupéry
Re: [PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC
Quoted 26 lines · Brian Inglis
Quoted 24 lines · Alejandro Colomar
Quoted 5 lines · Brian Inglis
TL;DR: They are bit/byte unit prefixes kibi..., ... but abstract value suffix symbols, which is how I think of them, and mainly how we use them. Perhaps we should just call them all multiples or symbosl, as we only sometimes(/rarely?) use them as unit prefixes (and seldom written out, only to explain the weird Xi notation)? Feel free to change the titles and log messages as you see fit.
Indeed, I had doubts about using them as suffixes because that's incorrect according to the SI, but it makes sense and improves documentation, so I'm fine with the use as suffixes now. However, I'm still concerned with calling
them suffixes. How about multipliers? Does it make sense to you?Quoted 11 lines
[BT;DT: Many discussions about units over the decades, including various *industry* conventions about "accepted" units, values, and conversion factors, invariant regardless of SI and CODATA.
ISO/BIPM etc. uses SI to mean decimal *metric* unit prefixes (and notes that SI does not support non-physical units of information) and IEC to mean binary unit prefixes for bits, bytes, and also allows Hertz so far. See refs from:
https://en.wikipedia.org/wiki/Binary_prefix#cite_note-bipm-book-91
https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf#page=29
Thanks. It now makes sense. Looks like the SI talks about them, but only takes them as defined by IEC, and doesn't incorporate them as their own. So, using IEC seems correct (as SI does itself).
Quoted 7 lines
Quoted 5 lines
BTW, this was one of the few patches that I received inline :/
Quoted 3 lines · Alejandro Colomar
Quoted 2 lines
The subject is not correct, IMO. The SI also defines the Ki, Mi, ... prefixes for binary multipliers. Also, they are prefixes, not suffixes.
I have regenerated with format-patch -v2 --inline and will later edit and resend as suggested and hopefully you will get what you expect to review.
Hi Alex,
I changed send-email to send 1/minute and v2 seems to have succeeded as a series with a cover letter and Content-Disposition: inline in my copies, so hopefully you see them as you expect, and no other project I next send patches to will object to inline. ;^>
Signature · 6 lines
Take care. Thanks, Brian Inglis Calgary, Alberta, Canada La perfection est atteinte Perfection is achieved non pas lorsqu'il n'y a plus rien à ajouter not when there is no more to add mais lorsqu'il n'y a plus rien à retirer but when there is no more to cut -- Antoine de Saint-Exupéry
Re: [PATCH 01/11] man2/shmget.2: fix limit units suffix from SI to IEC
Quoted 1 line · Brian Inglis
Hi Alex,
Hi Brian,
Quoted 5 lines
I changed send-email to send 1/minute and v2 seems to have succeeded as a series with a cover letter and Content-Disposition: inline in my copies, so hopefully you see them as you expect, and no other project I next send patches to will object to inline. ;^>
--inline works. I'm more used to --no-attach, but can live with it. :)
Cheers,
Alex
Quoted 1 line
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5