[PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings

public inbox for linux-man@vger.kernel.org
 help / color / mirror / Atom feed

* [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings
@ 2023-02-15 20:15 Brian Inglis
  2023-02-15 20:17 ` Brian Inglis
                   ` (7 more replies)
  0 siblings, 8 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:15 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

man2/: use C digit separators "'" \[aq], IEC, or ISO multiples
to clarify long binary, octal, hex, decimal numeric digit strings

Brian Inglis (6):
  man2/: use IEC/ISO multiples to clarify long numeric digit strings
  man2/keyctl.2: use IEC/ISO multiples to clarify long numeric digit
    strings or add digit separators
  man2/: add digit separators to clarify POSIX feature release dates
  man2/select.2: add digit separators to clarify POSIX feature release
    dates and use IEC/ISO multiples to clarify long numeric digit strings
  man2/chmod.2: add digit separators to clarify POSIX feature release
    dates and long numeric digit strings
  man2/: add digit separators to clarify long numeric digit strings

 man2/access.2            |  2 +-
 man2/add_key.2           |  2 +-
 man2/brk.2               |  4 ++--
 man2/capget.2            |  6 +++---
 man2/chdir.2             |  2 +-
 man2/chmod.2             | 30 +++++++++++++++---------------
 man2/chown.2             |  4 ++--
 man2/clock_getres.2      |  2 +-
 man2/clock_nanosleep.2   |  2 +-
 man2/epoll_wait.2        |  2 +-
 man2/fcntl.2             |  2 +-
 man2/fsync.2             |  4 ++--
 man2/getgroups.2         |  2 +-
 man2/gethostname.2       |  2 +-
 man2/getpagesize.2       |  4 ++--
 man2/getsid.2            |  2 +-
 man2/ioctl.2             |  4 ++--
 man2/ioctl_console.2     |  4 ++--
 man2/iopl.2              |  2 +-
 man2/keyctl.2            | 14 +++++++-------
 man2/link.2              |  2 +-
 man2/madvise.2           |  4 ++--
 man2/mkdir.2             |  4 ++--
 man2/mmap2.2             |  8 ++++----
 man2/msgctl.2            | 14 +++++++-------
 man2/nanosleep.2         |  2 +-
 man2/open.2              |  4 ++--
 man2/openat2.2           |  4 ++--
 man2/posix_fadvise.2     |  2 +-
 man2/pread.2             |  2 +-
 man2/process_vm_readv.2  |  2 +-
 man2/readlink.2          |  4 ++--
 man2/reboot.2            |  2 +-
 man2/rename.2            |  2 +-
 man2/request_key.2       |  2 +-
 man2/sched_setaffinity.2 |  4 ++--
 man2/seccomp.2           |  4 ++--
 man2/select.2            |  8 ++++----
 man2/semctl.2            | 16 ++++++++--------
 man2/semop.2             |  4 ++--
 man2/sendmmsg.2          |  2 +-
 man2/seteuid.2           |  2 +-
 man2/setpgid.2           |  2 +-
 man2/shmctl.2            | 14 +++++++-------
 man2/shmget.2            |  4 ++--
 man2/sigaltstack.2       |  2 +-
 man2/sigwaitinfo.2       |  2 +-
 man2/stat.2              |  4 ++--
 man2/symlink.2           |  4 ++--
 man2/syslog.2            |  6 +++---
 man2/timer_create.2      |  2 +-
 man2/timer_delete.2      |  2 +-
 man2/timer_getoverrun.2  |  2 +-
 man2/truncate.2          |  4 ++--
 man2/umask.2             |  8 ++++----
 man2/unlink.2            |  2 +-
 man2/utimensat.2         |  2 +-
 man2/vfork.2             |  2 +-
 man2/vmsplice.2          |  2 +-
 man2/wait.2              |  4 ++--
 man2/wait4.2             |  2 +-
 61 files changed, 132 insertions(+), 132 deletions(-)

-- 
2.39.0


^ permalink raw reply	[flat|nested] 39+ messages in thread

* [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 20:17 ` [PATCH v3 1/6] man2/: use IEC " Brian Inglis
                   ` (6 subsequent siblings)
  7 siblings, 0 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

man2/: use C digit separators "'" \[aq], IEC, or ISO multiples
to clarify long binary, octal, hex, decimal numeric digit strings

Brian Inglis (6):
  man2/: use IEC/ISO multiples to clarify long numeric digit strings
  man2/keyctl.2: use IEC/ISO multiples to clarify long numeric digit
    strings or add digit separators
  man2/: add digit separators to clarify POSIX feature release dates
  man2/select.2: add digit separators to clarify POSIX feature release
    dates and use IEC/ISO multiples to clarify long numeric digit strings
  man2/chmod.2: add digit separators to clarify POSIX feature release
    dates and long numeric digit strings
  man2/: add digit separators to clarify long numeric digit strings

 man2/access.2            |  2 +-
 man2/add_key.2           |  2 +-
 man2/brk.2               |  4 ++--
 man2/capget.2            |  6 +++---
 man2/chdir.2             |  2 +-
 man2/chmod.2             | 30 +++++++++++++++---------------
 man2/chown.2             |  4 ++--
 man2/clock_getres.2      |  2 +-
 man2/clock_nanosleep.2   |  2 +-
 man2/epoll_wait.2        |  2 +-
 man2/fcntl.2             |  2 +-
 man2/fsync.2             |  4 ++--
 man2/getgroups.2         |  2 +-
 man2/gethostname.2       |  2 +-
 man2/getpagesize.2       |  4 ++--
 man2/getsid.2            |  2 +-
 man2/ioctl.2             |  4 ++--
 man2/ioctl_console.2     |  4 ++--
 man2/iopl.2              |  2 +-
 man2/keyctl.2            | 14 +++++++-------
 man2/link.2              |  2 +-
 man2/madvise.2           |  4 ++--
 man2/mkdir.2             |  4 ++--
 man2/mmap2.2             |  8 ++++----
 man2/msgctl.2            | 14 +++++++-------
 man2/nanosleep.2         |  2 +-
 man2/open.2              |  4 ++--
 man2/openat2.2           |  4 ++--
 man2/posix_fadvise.2     |  2 +-
 man2/pread.2             |  2 +-
 man2/process_vm_readv.2  |  2 +-
 man2/readlink.2          |  4 ++--
 man2/reboot.2            |  2 +-
 man2/rename.2            |  2 +-
 man2/request_key.2       |  2 +-
 man2/sched_setaffinity.2 |  4 ++--
 man2/seccomp.2           |  4 ++--
 man2/select.2            |  8 ++++----
 man2/semctl.2            | 16 ++++++++--------
 man2/semop.2             |  4 ++--
 man2/sendmmsg.2          |  2 +-
 man2/seteuid.2           |  2 +-
 man2/setpgid.2           |  2 +-
 man2/shmctl.2            | 14 +++++++-------
 man2/shmget.2            |  4 ++--
 man2/sigaltstack.2       |  2 +-
 man2/sigwaitinfo.2       |  2 +-
 man2/stat.2              |  4 ++--
 man2/symlink.2           |  4 ++--
 man2/syslog.2            |  6 +++---
 man2/timer_create.2      |  2 +-
 man2/timer_delete.2      |  2 +-
 man2/timer_getoverrun.2  |  2 +-
 man2/truncate.2          |  4 ++--
 man2/umask.2             |  8 ++++----
 man2/unlink.2            |  2 +-
 man2/utimensat.2         |  2 +-
 man2/vfork.2             |  2 +-
 man2/vmsplice.2          |  2 +-
 man2/wait.2              |  4 ++--
 man2/wait4.2             |  2 +-
 61 files changed, 132 insertions(+), 132 deletions(-)

-- 
2.39.0


^ permalink raw reply	[flat|nested] 39+ messages in thread

* [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
  2023-02-15 20:17 ` Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 21:05   ` Alejandro Colomar
                     ` (2 more replies)
  2023-02-15 20:17 ` [PATCH v3 2/6] man2/keyctl.2: use IEC or ISO multiples or add C digit separators " Brian Inglis
                   ` (5 subsequent siblings)
  7 siblings, 3 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

---
 man2/add_key.2           | 2 +-
 man2/epoll_wait.2        | 2 +-
 man2/fcntl.2             | 2 +-
 man2/getgroups.2         | 2 +-
 man2/ioctl_console.2     | 4 ++--
 man2/iopl.2              | 2 +-
 man2/madvise.2           | 4 ++--
 man2/mmap2.2             | 8 ++++----
 man2/request_key.2       | 2 +-
 man2/sched_setaffinity.2 | 4 ++--
 man2/seccomp.2           | 4 ++--
 man2/semop.2             | 4 ++--
 man2/sendmmsg.2          | 2 +-
 man2/shmget.2            | 4 ++--
 man2/syslog.2            | 6 +++---
 man2/vmsplice.2          | 2 +-
 16 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/man2/add_key.2 b/man2/add_key.2
index 56fc6d198d21..215de20baeae 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
 .I type
 or
 .I description
-exceeded the limit (32 bytes and 4096 bytes respectively).
+exceeded the limit (32 bytes and 4Ki bytes respectively).
 .TP
 .B EINVAL
 The payload data was invalid.
diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
index 1620cff9dfcc..4863ae4a43fa 100644
--- a/man2/epoll_wait.2
+++ b/man2/epoll_wait.2
@@ -283,7 +283,7 @@ Thus, for example, on a system where
 .I sizeof(long)
 is 4 and the kernel
 .I HZ
-value is 1000,
+value is 1k,
 this means that timeouts greater than 35.79 minutes are treated as infinity.
 .SH SEE ALSO
 .BR epoll_create (2),
diff --git a/man2/fcntl.2 b/man2/fcntl.2
index 3ec52dc4dc03..630fc55888bc 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -2004,7 +2004,7 @@ A limitation of the Linux system call conventions on some
 architectures (notably i386) means that if a (negative)
 process group ID to be returned by
 .B F_GETOWN
-falls in the range \-1 to \-4095, then the return value is wrongly
+falls in the range \-1 to \-4Ki-1, then the return value is wrongly
 interpreted by glibc as an error in the system call;
 .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
 that is, the return value of
diff --git a/man2/getgroups.2 b/man2/getgroups.2
index 36300bf61b6a..f01af687ccbd 100644
--- a/man2/getgroups.2
+++ b/man2/getgroups.2
@@ -119,7 +119,7 @@ can additionally fail with the following errors:
 .I size
 is greater than
 .B NGROUPS_MAX
-(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
+(32 before Linux 2.6.4; 64Ki since Linux 2.6.4).
 .TP
 .B ENOMEM
 Out of memory.
diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
index 89f794c1956c..477e6fd1a7e1 100644
--- a/man2/ioctl_console.2
+++ b/man2/ioctl_console.2
@@ -171,7 +171,7 @@ bright cyan, and white.
 .B GIO_FONT
 Gets 256-character screen font in expanded form.
 .I argp
-points to an 8192-byte array.
+points to an 8Ki-byte array.
 Fails with error code
 .B EINVAL
 if the
@@ -211,7 +211,7 @@ Sets 256-character screen font.
 Load font into the EGA/VGA character
 generator.
 .I argp
-points to an 8192-byte map, with 32 bytes per
+points to an 8Ki-byte map, with 32 bytes per
 character.
 Only the first
 .I N
diff --git a/man2/iopl.2 b/man2/iopl.2
index abf1bef675fd..c967296157b7 100644
--- a/man2/iopl.2
+++ b/man2/iopl.2
@@ -34,7 +34,7 @@ Permissions are inherited from parents to children.
 This call is deprecated, is significantly slower than
 .BR ioperm (2),
 and is only provided for older X servers which require
-access to all 65536 I/O ports.
+access to all 64Ki I/O ports.
 It is mostly for the i386 architecture.
 On many other architectures it does not exist or will always
 return an error.
diff --git a/man2/madvise.2 b/man2/madvise.2
index 9b4652a635d3..e05e9c5de4a7 100644
--- a/man2/madvise.2
+++ b/man2/madvise.2
@@ -329,8 +329,8 @@ naturally aligned to the huge page size (see
 This feature is primarily aimed at applications that use large mappings of
 data and access large regions of that memory at a time (e.g., virtualization
 systems such as QEMU).
-It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
-1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
+It can very easily waste memory (e.g., a 2\ MiB mapping that only ever accesses
+1 byte will result in 2\ MiB of wired memory instead of one 4\ KiB page).
 See the Linux kernel source file
 .I Documentation/admin\-guide/mm/transhuge.rst
 for more details.
diff --git a/man2/mmap2.2 b/man2/mmap2.2
index 1fd5732ad41b..f975c1388a77 100644
--- a/man2/mmap2.2
+++ b/man2/mmap2.2
@@ -32,7 +32,7 @@ The
 system call provides the same interface as
 .BR mmap (2),
 except that the final argument specifies the offset into the
-file in 4096-byte units (instead of bytes, as is done by
+file in 4Ki-byte units (instead of bytes, as is done by
 .BR mmap (2)).
 This enables applications that use a 32-bit
 .I off_t
@@ -50,8 +50,8 @@ is set to indicate the error.
 Problem with getting the data from user space.
 .TP
 .B EINVAL
-(Various platforms where the page size is not 4096 bytes.)
-.I "offset\ *\ 4096"
+(Various platforms where the page size is not 4Ki bytes.)
+.I "offset\ *\ 4Ki"
 is not a multiple of the system page size.
 .PP
 .BR mmap2 ()
@@ -74,7 +74,7 @@ This system call does not exist on x86-64.
 .PP
 On ia64, the unit for
 .I offset
-is actually the system page size, rather than 4096 bytes.
+is actually the system page size, rather than 4Ki bytes.
 .\" ia64 can have page sizes ranging from 4 kB to 64 kB.
 .\" On cris, it looks like the unit might also be the page size,
 .\" which is 8192 bytes. -- mtk, June 2007
diff --git a/man2/request_key.2 b/man2/request_key.2
index e78321e3c23f..dacc5282f3d8 100644
--- a/man2/request_key.2
+++ b/man2/request_key.2
@@ -399,7 +399,7 @@ The size of the string (including the terminating null byte) specified in
 .I type
 or
 .I description
-exceeded the limit (32 bytes and 4096 bytes respectively).
+exceeded the limit (32 bytes and 4Ki bytes respectively).
 .TP
 .B EINVAL
 The size of the string (including the terminating null byte) specified in
diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2
index 86a93539137d..9e7a26293e73 100644
--- a/man2/sched_setaffinity.2
+++ b/man2/sched_setaffinity.2
@@ -243,10 +243,10 @@ impose no restriction on the size of the CPU mask.
 However, the
 .I cpu_set_t
 data type used by glibc has a fixed size of 128 bytes,
-meaning that the maximum CPU number that can be represented is 1023.
+meaning that the maximum CPU number that can be represented is 1\[aq]023.
 .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
 .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
-If the kernel CPU affinity mask is larger than 1024,
+If the kernel CPU affinity mask is larger than 1Ki,
 then calls of the form:
 .PP
 .in +4n
diff --git a/man2/seccomp.2 b/man2/seccomp.2
index 32706397f03e..0bb8caa75698 100644
--- a/man2/seccomp.2
+++ b/man2/seccomp.2
@@ -836,7 +836,7 @@ but the filter program pointed to by
 .I args
 was not valid or the length of the filter program was zero or exceeded
 .B BPF_MAXINSNS
-(4096) instructions.
+(4Ki) instructions.
 .TP
 .B ENOMEM
 Out of memory.
@@ -846,7 +846,7 @@ Out of memory.
 The total length of all filter programs attached
 to the calling thread would exceed
 .B MAX_INSNS_PER_PATH
-(32768) instructions.
+(32Ki) instructions.
 Note that for the purposes of calculating this limit,
 each already existing filter program incurs an
 overhead penalty of 4 instructions.
diff --git a/man2/semop.2 b/man2/semop.2
index 7a1416a26894..a0027e0706c5 100644
--- a/man2/semop.2
+++ b/man2/semop.2
@@ -434,7 +434,7 @@ On Linux, this limit can be read and modified via the third field of
 .IR /proc/sys/kernel/sem .
 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 .IR Note :
-this limit should not be raised above 1000,
+this limit should not be raised above 1\[aq]000,
 .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
 because of the risk of that
 .BR semop ()
@@ -445,7 +445,7 @@ array.
 .B SEMVMX
 Maximum allowable value for
 .IR semval :
-implementation dependent (32767).
+implementation dependent (32Ki-1).
 .PP
 The implementation has no intrinsic limits for
 the adjust on exit maximum value
diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
index 4e5475c45a09..3f355382ebf6 100644
--- a/man2/sendmmsg.2
+++ b/man2/sendmmsg.2
@@ -139,7 +139,7 @@ The value specified in
 .I vlen
 is capped to
 .B UIO_MAXIOV
-(1024).
+(1Ki).
 .\" commit 98382f419f32d2c12d021943b87dea555677144b
 .\"     net: Cap number of elements for sendmmsg
 .\"
diff --git a/man2/shmget.2 b/man2/shmget.2
index c4d8df8ed619..5421fd4bf3e9 100644
--- a/man2/shmget.2
+++ b/man2/shmget.2
@@ -360,7 +360,7 @@ 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
 usable segment:
 for example, on i386 the largest segments that can be mapped have a
-size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
+size of around 2.8\ GB, and on x86-64 the limit is around 127\ TB.
 .TP
 .B SHMMIN
 Minimum size in bytes for a shared memory segment: implementation
@@ -371,7 +371,7 @@ is the effective minimum size).
 .B SHMMNI
 System-wide limit on the number of shared memory segments.
 In Linux 2.2, the default value for this limit was 128;
-since Linux 2.4, the default value is 4096.
+since Linux 2.4, the default value is 4Ki.
 .IP
 On Linux, this limit can be read and modified via
 .IR /proc/sys/kernel/shmmni .
diff --git a/man2/syslog.2 b/man2/syslog.2
index 09c086f181e3..7d76e8cd9658 100644
--- a/man2/syslog.2
+++ b/man2/syslog.2
@@ -54,9 +54,9 @@ in which messages given as arguments to the kernel function
 are stored (regardless of their log level).
 In early kernels,
 .B LOG_BUF_LEN
-had the value 4096;
-from Linux 1.3.54, it was 8192;
-from Linux 2.1.113, it was 16384;
+had the value 4Ki;
+from Linux 1.3.54, it was 8Ki;
+from Linux 2.1.113, it was 16Ki;
 since Linux 2.4.23/2.6, the value is a kernel configuration option
 .RB ( CONFIG_LOG_BUF_SHIFT ,
 default value dependent on the architecture).
diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
index 01ac37b3584f..08ede47361ae 100644
--- a/man2/vmsplice.2
+++ b/man2/vmsplice.2
@@ -149,7 +149,7 @@ as defined in
 .IR <limits.h> .
 Currently,
 .\" UIO_MAXIOV in kernel source
-this limit is 1024.
+this limit is 1Ki.
 .PP
 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
 .BR vmsplice ()
-- 
2.39.0


^ permalink raw reply related	[flat|nested] 39+ messages in thread

* [PATCH v3 2/6] man2/keyctl.2: use IEC or ISO multiples or add C digit separators to clarify long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
  2023-02-15 20:17 ` Brian Inglis
  2023-02-15 20:17 ` [PATCH v3 1/6] man2/: use IEC " Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 21:06   ` Alejandro Colomar
  2023-02-15 20:17 ` [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates Brian Inglis
                   ` (4 subsequent siblings)
  7 siblings, 1 reply; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

---
 man2/keyctl.2 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 4ce87dcf31af..0c27aaa44d7f 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -729,7 +729,7 @@ including the terminating null byte), and
 (cast as
 .IR char\~* )
 contains the description of the key
-(a null-terminated character string up to 4096 bytes in size,
+(a null-terminated character string up to 4Ki bytes in size,
 including the terminating null byte).
 .IP
 The source keyring must grant
@@ -1742,7 +1742,7 @@ was
 .B KEYCTL_SEARCH
 and the size of the description in
 .I arg4
-(including the terminating null byte) exceeded 4096 bytes.
+(including the terminating null byte) exceeded 4Ki bytes.
 .TP
 .B EINVAL
 size of the string (including the terminating null byte) specified in
@@ -1751,7 +1751,7 @@ size of the string (including the terminating null byte) specified in
 or
 .I arg4
 (the key description)
-exceeded the limit (32 bytes and 4096 bytes respectively).
+exceeded the limit (32 bytes and 4Ki bytes respectively).
 .TP
 .BR EINVAL " (before Linux 4.12)"
 .I operation
@@ -1822,7 +1822,7 @@ was
 .B KEYCTL_DH_COMPUTE
 and the buffer length exceeds
 .B KEYCTL_KDF_MAX_OUTPUT_LEN
-(which is 1024 currently)
+(which is 1Ki currently)
 or the
 .I otherinfolen
 field of the
@@ -2047,7 +2047,7 @@ and
 the description of the authorization key,
 where we can see that the name of the authorization key matches
 the ID of the key that is to be instantiated
-.RI ( 20d035bf ).
+.RI ( 20d0\[aq]35bf ).
 .PP
 The example program in
 .BR request_key (2)
@@ -2056,12 +2056,12 @@ specified the destination keyring as
 By examining the contents of
 .IR /proc/keys ,
 we can see that this was translated to the ID of the destination keyring
-.RI ( 0256e6a6 )
+.RI ( 0256\[aq]e6a6 )
 shown in the log output above;
 we can also see the newly created key with the name
 .I mykey
 and ID
-.IR 20d035bf .
+.IR 20d0\[aq]35bf .
 .PP
 .in +4n
 .EX
-- 
2.39.0


^ permalink raw reply related	[flat|nested] 39+ messages in thread

* [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
                   ` (2 preceding siblings ...)
  2023-02-15 20:17 ` [PATCH v3 2/6] man2/keyctl.2: use IEC or ISO multiples or add C digit separators " Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 21:08   ` Alejandro Colomar
  2023-02-16 21:11   ` Stefan Puiu
  2023-02-15 20:17 ` [PATCH v3 4/6] man2/select.2: add C digit separators to clarify POSIX feature release dates or use IEC or ISO multiples to clarify long numeric digit strings Brian Inglis
                   ` (3 subsequent siblings)
  7 siblings, 2 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

---
 man2/access.2           | 2 +-
 man2/brk.2              | 4 ++--
 man2/chdir.2            | 2 +-
 man2/chown.2            | 4 ++--
 man2/clock_getres.2     | 2 +-
 man2/clock_nanosleep.2  | 2 +-
 man2/fsync.2            | 4 ++--
 man2/gethostname.2      | 2 +-
 man2/getpagesize.2      | 4 ++--
 man2/getsid.2           | 2 +-
 man2/link.2             | 2 +-
 man2/mkdir.2            | 4 ++--
 man2/nanosleep.2        | 2 +-
 man2/open.2             | 4 ++--
 man2/posix_fadvise.2    | 2 +-
 man2/pread.2            | 2 +-
 man2/readlink.2         | 4 ++--
 man2/rename.2           | 2 +-
 man2/seteuid.2          | 2 +-
 man2/setpgid.2          | 2 +-
 man2/sigaltstack.2      | 2 +-
 man2/sigwaitinfo.2      | 2 +-
 man2/stat.2             | 4 ++--
 man2/symlink.2          | 4 ++--
 man2/timer_create.2     | 2 +-
 man2/timer_delete.2     | 2 +-
 man2/timer_getoverrun.2 | 2 +-
 man2/truncate.2         | 4 ++--
 man2/unlink.2           | 2 +-
 man2/vfork.2            | 2 +-
 man2/wait.2             | 4 ++--
 man2/wait4.2            | 2 +-
 32 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/man2/access.2 b/man2/access.2
index d3deeecba0c7..4c93a132b209 100644
--- a/man2/access.2
+++ b/man2/access.2
@@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see
 .BR faccessat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/brk.2 b/man2/brk.2
index 31c167c56955..298fd006d742 100644
--- a/man2/brk.2
+++ b/man2/brk.2
@@ -32,13 +32,13 @@ Feature Test Macro Requirements for glibc (see
     Since glibc 2.19:
         _DEFAULT_SOURCE
             || ((_XOPEN_SOURCE >= 500) &&
-                ! (_POSIX_C_SOURCE >= 200112L))
+                ! (_POSIX_C_SOURCE >= 2001\[aq]12L))
 .\"    (_XOPEN_SOURCE >= 500 ||
 .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
     From glibc 2.12 to glibc 2.19:
         _BSD_SOURCE || _SVID_SOURCE
             || ((_XOPEN_SOURCE >= 500) &&
-                ! (_POSIX_C_SOURCE >= 200112L))
+                ! (_POSIX_C_SOURCE >= 2001\[aq]12L))
 .\"    (_XOPEN_SOURCE >= 500 ||
 .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
     Before glibc 2.12:
diff --git a/man2/chdir.2 b/man2/chdir.2
index 0bbff4e87842..cca6a568871c 100644
--- a/man2/chdir.2
+++ b/man2/chdir.2
@@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
     _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
         || /* glibc up to and including 2.19: */ _BSD_SOURCE
 .fi
 .SH DESCRIPTION
diff --git a/man2/chown.2 b/man2/chown.2
index d66b66f544cb..5c87dfa6aa9b 100644
--- a/man2/chown.2
+++ b/man2/chown.2
@@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see
 .BR fchown (),
 .BR lchown ():
 .nf
-    /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+    /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
         || _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
         || /* glibc <= 2.19: */ _BSD_SOURCE
@@ -53,7 +53,7 @@ Feature Test Macro Requirements for glibc (see
 .BR fchownat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 8d90baaaabd6..b6a3bedbd944 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -39,7 +39,7 @@ Feature Test Macro Requirements for glibc (see
 .BR clock_gettime (),
 .BR clock_settime ():
 .nf
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\[aq]09L
 .fi
 .SH DESCRIPTION
 The function
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
index 5da8d15699c2..fe78d6bedb11 100644
--- a/man2/clock_nanosleep.2
+++ b/man2/clock_nanosleep.2
@@ -30,7 +30,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR clock_nanosleep ():
 .nf
-    _POSIX_C_SOURCE >= 200112L
+    _POSIX_C_SOURCE >= 2001\[aq]12L
 .fi
 .SH DESCRIPTION
 Like
diff --git a/man2/fsync.2 b/man2/fsync.2
index 9dc99a15a20e..78fc6013b773 100644
--- a/man2/fsync.2
+++ b/man2/fsync.2
@@ -41,12 +41,12 @@ Feature Test Macro Requirements for glibc (see
         No feature test macros need be defined
     glibc up to and including 2.15:
         _BSD_SOURCE || _XOPEN_SOURCE
-            || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
+            || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 2001\[aq]12L
 .fi
 .PP
 .BR fdatasync ():
 .nf
-    _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
+    _POSIX_C_SOURCE >= 1993\[aq]09L || _XOPEN_SOURCE >= 500
 .fi
 .SH DESCRIPTION
 .BR fsync ()
diff --git a/man2/gethostname.2 b/man2/gethostname.2
index bc74610c9c5d..e6d3b5837c2c 100644
--- a/man2/gethostname.2
+++ b/man2/gethostname.2
@@ -30,7 +30,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR gethostname ():
 .nf
-    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
+    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
         || /* glibc 2.19 and earlier */ _BSD_SOURCE
 .\" The above is something of a simplification
 .\" also before glibc 2.3 there was a bit churn
diff --git a/man2/getpagesize.2 b/man2/getpagesize.2
index 39af55619be4..356bb42f08f1 100644
--- a/man2/getpagesize.2
+++ b/man2/getpagesize.2
@@ -23,9 +23,9 @@ Feature Test Macro Requirements for glibc (see
 .BR getpagesize ():
 .nf
     Since glibc 2.20:
-        _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 200112L)
+        _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 2001\[aq]12L)
     glibc 2.12 to glibc 2.19:
-        _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 200112L)
+        _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 2001\[aq]12L)
     Before glibc 2.12:
         _BSD_SOURCE || _XOPEN_SOURCE >= 500
 .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
diff --git a/man2/getsid.2 b/man2/getsid.2
index 3afccbd9d6bf..355c4df2601a 100644
--- a/man2/getsid.2
+++ b/man2/getsid.2
@@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
     _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR getsid ()
diff --git a/man2/link.2 b/man2/link.2
index 60b739eba152..49526bfe36d4 100644
--- a/man2/link.2
+++ b/man2/link.2
@@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
 .BR linkat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/mkdir.2 b/man2/mkdir.2
index b1339a49a513..68539ab7e1ab 100644
--- a/man2/mkdir.2
+++ b/man2/mkdir.2
@@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see
 .BR mkdirat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
@@ -49,7 +49,7 @@ It is modified by the process's
 .I umask
 in the usual way: in the absence of a default ACL, the mode of the
 created directory is
-.RI ( mode " & \[ti]" umask " & 0777)."
+.RI ( mode " & \[ti]" umask " & 0\[aq]777)."
 Whether other
 .I mode
 bits are honored for the created directory depends on the operating system.
diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
index 12e0cee84b85..4732ef705fe0 100644
--- a/man2/nanosleep.2
+++ b/man2/nanosleep.2
@@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR nanosleep ():
 .nf
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR nanosleep ()
diff --git a/man2/open.2 b/man2/open.2
index aefcae1e601e..1bb3640014e6 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -60,7 +60,7 @@ Feature Test Macro Requirements for glibc (see
 .BR openat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
@@ -1772,7 +1772,7 @@ In Linux 2.4,
 most filesystems based on block devices require that
 the file offset and the length and memory address of all I/O segments
 be multiples of the filesystem block size
-(typically 4096 bytes).
+(typically 4Ki bytes).
 In Linux 2.6.0,
 this was relaxed to the logical block size of the block device
 (typically 512 bytes).
diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2
index 57c65c810791..cb9b6ea24dd8 100644
--- a/man2/posix_fadvise.2
+++ b/man2/posix_fadvise.2
@@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR posix_fadvise ():
 .nf
-    _POSIX_C_SOURCE >= 200112L
+    _POSIX_C_SOURCE >= 2001\[aq]12L
 .fi
 .SH DESCRIPTION
 Programs can use
diff --git a/man2/pread.2 b/man2/pread.2
index 9a9763323518..7a8fce5764d5 100644
--- a/man2/pread.2
+++ b/man2/pread.2
@@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
 .BR pwrite ():
 .nf
     _XOPEN_SOURCE >= 500
-        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR pread ()
diff --git a/man2/readlink.2 b/man2/readlink.2
index de158da7e355..e23564450af2 100644
--- a/man2/readlink.2
+++ b/man2/readlink.2
@@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR readlink ():
 .nf
-    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
+    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
         || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
@@ -48,7 +48,7 @@ Feature Test Macro Requirements for glibc (see
 .BR readlinkat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/rename.2 b/man2/rename.2
index 08e7958f3220..7e4b33cdb9d8 100644
--- a/man2/rename.2
+++ b/man2/rename.2
@@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
 .BR renameat ():
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .PP
diff --git a/man2/seteuid.2 b/man2/seteuid.2
index 14b23b3f40b0..4dd30ecfc012 100644
--- a/man2/seteuid.2
+++ b/man2/seteuid.2
@@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
 .BR seteuid (),
 .BR setegid ():
 .nf
-    _POSIX_C_SOURCE >= 200112L
+    _POSIX_C_SOURCE >= 2001\[aq]12L
         || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
 .SH DESCRIPTION
diff --git a/man2/setpgid.2 b/man2/setpgid.2
index 52c5bd5fcc10..4cf35c3a0c03 100644
--- a/man2/setpgid.2
+++ b/man2/setpgid.2
@@ -46,7 +46,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
     _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
 .fi
 .PP
 .BR setpgrp "() (POSIX.1):"
diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2
index cdc8a8e39f70..45d6db43a0c8 100644
--- a/man2/sigaltstack.2
+++ b/man2/sigaltstack.2
@@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
     _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
         || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
 .SH DESCRIPTION
diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2
index 42209c1806e9..791dc418d6c4 100644
--- a/man2/sigwaitinfo.2
+++ b/man2/sigwaitinfo.2
@@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
 .BR sigwaitinfo (),
 .BR sigtimedwait ():
 .nf
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR sigwaitinfo ()
diff --git a/man2/stat.2 b/man2/stat.2
index 8479befccd8d..4bd67667b5c2 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -49,14 +49,14 @@ Feature Test Macro Requirements for glibc (see
     /* Since glibc 2.20 */ _DEFAULT_SOURCE
         || _XOPEN_SOURCE >= 500
 .\"   _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
+        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 2001\[aq]12L
         || /* glibc 2.19 and earlier */ _BSD_SOURCE
 .fi
 .PP
 .BR fstatat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/symlink.2 b/man2/symlink.2
index 13b2ed1ccd5b..34078fabfe01 100644
--- a/man2/symlink.2
+++ b/man2/symlink.2
@@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR symlink ():
 .nf
-    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
+    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
         || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
@@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see
 .BR symlinkat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/timer_create.2 b/man2/timer_create.2
index 6d49da17f89a..0f26075e457c 100644
--- a/man2/timer_create.2
+++ b/man2/timer_create.2
@@ -26,7 +26,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR timer_create ():
 .nf
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR timer_create ()
diff --git a/man2/timer_delete.2 b/man2/timer_delete.2
index c489d9ec0dff..e0397af5bf4f 100644
--- a/man2/timer_delete.2
+++ b/man2/timer_delete.2
@@ -23,7 +23,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR timer_delete ():
 .nf
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR timer_delete ()
diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2
index 3591e5de5df5..690c19937799 100644
--- a/man2/timer_getoverrun.2
+++ b/man2/timer_getoverrun.2
@@ -23,7 +23,7 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR timer_getoverrun ():
 .nf
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\[aq]09L
 .fi
 .SH DESCRIPTION
 .BR timer_getoverrun ()
diff --git a/man2/truncate.2 b/man2/truncate.2
index 8a00ec3ffba2..bb57666e64b1 100644
--- a/man2/truncate.2
+++ b/man2/truncate.2
@@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
     _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
         || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
 .PP
@@ -43,7 +43,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
     _XOPEN_SOURCE >= 500
 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L
+        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 2001\[aq]12L
         || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
 .SH DESCRIPTION
diff --git a/man2/unlink.2 b/man2/unlink.2
index 954a19f1534a..4c296e73086b 100644
--- a/man2/unlink.2
+++ b/man2/unlink.2
@@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
 .BR unlinkat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
diff --git a/man2/vfork.2 b/man2/vfork.2
index 5e6b8226c301..e3c82f1d6bc4 100644
--- a/man2/vfork.2
+++ b/man2/vfork.2
@@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
 .BR vfork ():
 .nf
     Since glibc 2.12:
-        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
+        (_XOPEN_SOURCE >= 500)         (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) ! (_POSIX_C_SOURCE >= 2008\[aq]09L)
             || /* Since glibc 2.19: */ _DEFAULT_SOURCE
             || /* glibc <= 2.19: */ _BSD_SOURCE
     Before glibc 2.12:
diff --git a/man2/wait.2 b/man2/wait.2
index e2dcd59bda09..ad031d40ca07 100644
--- a/man2/wait.2
+++ b/man2/wait.2
@@ -53,11 +53,11 @@ Feature Test Macro Requirements for glibc (see
 .BR waitid ():
 .nf
     Since glibc 2.26:
-        _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
+        _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2008\[aq]09L
 .\"    (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
     glibc 2.25 and earlier:
         _XOPEN_SOURCE
-            || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+            || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
             || /* glibc <= 2.19: */ _BSD_SOURCE
 .fi
 .SH DESCRIPTION
diff --git a/man2/wait4.2 b/man2/wait4.2
index a5b38108d318..703df0797f80 100644
--- a/man2/wait4.2
+++ b/man2/wait4.2
@@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
     Since glibc 2.26:
         _DEFAULT_SOURCE
             || (_XOPEN_SOURCE >= 500 &&
-                ! (_POSIX_C_SOURCE >= 200112L
+                ! (_POSIX_C_SOURCE >= 2001\[aq]12L
                    || _XOPEN_SOURCE >= 600))
     From glibc 2.19 to glibc 2.25:
         _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500
-- 
2.39.0


^ permalink raw reply related	[flat|nested] 39+ messages in thread

* [PATCH v3 4/6] man2/select.2: add C digit separators to clarify POSIX feature release dates or use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
                   ` (3 preceding siblings ...)
  2023-02-15 20:17 ` [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 21:09   ` Alejandro Colomar
  2023-02-15 20:17 ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and " Brian Inglis
                   ` (2 subsequent siblings)
  7 siblings, 1 reply; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

---
 man2/select.2 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man2/select.2 b/man2/select.2
index 7718b75067ab..bb7a252ade80 100644
--- a/man2/select.2
+++ b/man2/select.2
@@ -54,14 +54,14 @@ Feature Test Macro Requirements for glibc (see
 .PP
 .BR pselect ():
 .nf
-    _POSIX_C_SOURCE >= 200112L
+    _POSIX_C_SOURCE >= 2001\[aq]12L
 .fi
 .SH DESCRIPTION
 .BR "WARNING" :
 .BR select ()
 can monitor only file descriptors numbers that are less than
 .B FD_SETSIZE
-(1024)\[em]an unreasonably low limit for many modern applications\[em]and
+(1Ki)\[em]an unreasonably low limit for many modern applications\[em]and
 this limitation will not change.
 All modern applications should instead use
 .BR poll (2)
@@ -639,10 +639,10 @@ The Linux kernel imposes no fixed limit, but the glibc implementation makes
 .I fd_set
 a fixed-size type, with
 .B FD_SETSIZE
-defined as 1024, and the
+defined as 1Ki, and the
 .BR FD_* ()
 macros operating according to that limit.
-To monitor file descriptors greater than 1023, use
+To monitor file descriptors greater than 1Ki-1, use
 .BR poll (2)
 or
 .BR epoll (7)
-- 
2.39.0


^ permalink raw reply related	[flat|nested] 39+ messages in thread

* [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
                   ` (4 preceding siblings ...)
  2023-02-15 20:17 ` [PATCH v3 4/6] man2/select.2: add C digit separators to clarify POSIX feature release dates or use IEC or ISO multiples to clarify long numeric digit strings Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 21:10   ` Alejandro Colomar
  2023-02-15 20:17 ` [PATCH v3 6/6] man2/: add C digit separators to clarify " Brian Inglis
  2023-02-15 22:51 ` [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples " Brian Inglis
  7 siblings, 1 reply; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

---
 man2/chmod.2 | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/man2/chmod.2 b/man2/chmod.2
index 8b5db74ed7e3..674b54368314 100644
--- a/man2/chmod.2
+++ b/man2/chmod.2
@@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see
 .nf
 .BR fchmod ():
     Since glibc 2.24:
-        _POSIX_C_SOURCE >= 199309L
+        _POSIX_C_SOURCE >= 1993\[aq]09L
 .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
     glibc 2.19 to glibc 2.23
         _POSIX_C_SOURCE
@@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see
         _BSD_SOURCE || _POSIX_C_SOURCE
     glibc 2.12 to glibc 2.16:
         _BSD_SOURCE || _XOPEN_SOURCE >= 500
-            || _POSIX_C_SOURCE >= 200809L
+            || _POSIX_C_SOURCE >= 2008\[aq]09L
     glibc 2.11 and earlier:
         _BSD_SOURCE || _XOPEN_SOURCE >= 500
 .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
@@ -54,7 +54,7 @@ Feature Test Macro Requirements for glibc (see
 .BR fchmodat ():
 .nf
     Since glibc 2.10:
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\[aq]09L
     Before glibc 2.10:
         _ATFILE_SOURCE
 .fi
@@ -82,11 +82,11 @@ The new file mode is specified in
 which is a bit mask created by ORing together zero or
 more of the following:
 .TP 18
-.BR S_ISUID "  (04000)"
+.BR S_ISUID "  (04\[aq]000)"
 set-user-ID (set process effective user ID on
 .BR execve (2))
 .TP
-.BR S_ISGID "  (02000)"
+.BR S_ISGID "  (02\[aq]000)"
 set-group-ID (set process effective group ID on
 .BR execve (2);
 mandatory locking, as described in
@@ -96,36 +96,36 @@ take a new file's group from parent directory, as described in
 and
 .BR mkdir (2))
 .TP
-.BR S_ISVTX "  (01000)"
+.BR S_ISVTX "  (01\[aq]000)"
 sticky bit (restricted deletion flag, as described in
 .BR unlink (2))
 .TP
-.BR S_IRUSR "  (00400)"
+.BR S_IRUSR "  (00\[aq]400)"
 read by owner
 .TP
-.BR S_IWUSR "  (00200)"
+.BR S_IWUSR "  (00\[aq]200)"
 write by owner
 .TP
-.BR S_IXUSR "  (00100)"
+.BR S_IXUSR "  (00\[aq]100)"
 execute/search by owner ("search" applies for directories,
 and means that entries within the directory can be accessed)
 .TP
-.BR S_IRGRP "  (00040)"
+.BR S_IRGRP "  (00\[aq]040)"
 read by group
 .TP
-.BR S_IWGRP "  (00020)"
+.BR S_IWGRP "  (00\[aq]020)"
 write by group
 .TP
-.BR S_IXGRP "  (00010)"
+.BR S_IXGRP "  (00\[aq]010)"
 execute/search by group
 .TP
-.BR S_IROTH "  (00004)"
+.BR S_IROTH "  (00\[aq]004)"
 read by others
 .TP
-.BR S_IWOTH "  (00002)"
+.BR S_IWOTH "  (00\[aq]002)"
 write by others
 .TP
-.BR S_IXOTH "  (00001)"
+.BR S_IXOTH "  (00\[aq]001)"
 execute/search by others
 .PP
 The effective UID of the calling process must match the owner of the file,
-- 
2.39.0


^ permalink raw reply related	[flat|nested] 39+ messages in thread

* [PATCH v3 6/6] man2/: add C digit separators to clarify long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
                   ` (5 preceding siblings ...)
  2023-02-15 20:17 ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and " Brian Inglis
@ 2023-02-15 20:17 ` Brian Inglis
  2023-02-15 21:14   ` Alejandro Colomar
  2023-02-15 22:51 ` [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples " Brian Inglis
  7 siblings, 1 reply; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 20:17 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

---
 man2/capget.2           |  6 +++---
 man2/ioctl.2            |  4 ++--
 man2/msgctl.2           | 14 +++++++-------
 man2/openat2.2          |  4 ++--
 man2/process_vm_readv.2 |  2 +-
 man2/reboot.2           |  2 +-
 man2/semctl.2           | 16 ++++++++--------
 man2/shmctl.2           | 14 +++++++-------
 man2/umask.2            |  8 ++++----
 man2/utimensat.2        |  2 +-
 10 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/man2/capget.2 b/man2/capget.2
index 909f8bfe0de0..7c0e5b414d5d 100644
--- a/man2/capget.2
+++ b/man2/capget.2
@@ -56,17 +56,17 @@ The structures are defined as follows.
 .PP
 .in +4n
 .EX
-#define _LINUX_CAPABILITY_VERSION_1  0x19980330
+#define _LINUX_CAPABILITY_VERSION_1  0x1998\[aq]03\[aq]30
 #define _LINUX_CAPABILITY_U32S_1     1
 
         /* V2 added in Linux 2.6.25; deprecated */
-#define _LINUX_CAPABILITY_VERSION_2  0x20071026
+#define _LINUX_CAPABILITY_VERSION_2  0x2007\[aq]10\[aq]26
 .\" commit e338d263a76af78fe8f38a72131188b58fceb591
 .\" Added 64 bit capability support
 #define _LINUX_CAPABILITY_U32S_2     2
 
         /* V3 added in Linux 2.6.26 */
-#define _LINUX_CAPABILITY_VERSION_3  0x20080522
+#define _LINUX_CAPABILITY_VERSION_3  0x2008\[aq]05\[aq]22
 .\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f
 #define _LINUX_CAPABILITY_U32S_3     2
 
diff --git a/man2/ioctl.2 b/man2/ioctl.2
index f33f2c57c103..36e1ff4e041f 100644
--- a/man2/ioctl.2
+++ b/man2/ioctl.2
@@ -134,9 +134,9 @@ one or more ASCII letters were used.
 For example,
 .B TCGETS
 has value
-0x00005401, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and
+0x00\[aq]00\[aq]54\[aq]01, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and
 .B CYGETTIMEOUT
-has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
+has value 0x00\[aq]43\[aq]59\[aq]06, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
 indicating the cyclades driver.
 .PP
 Later (0.98p5) some more information was built into the number.
diff --git a/man2/msgctl.2 b/man2/msgctl.2
index ce534dc2abd5..f49b8a951d29 100644
--- a/man2/msgctl.2
+++ b/man2/msgctl.2
@@ -131,15 +131,15 @@ structure define the access permissions for the message queue.
 The permission bits are as follows:
 .TS
 l l.
-0400	Read by user
-0200	Write by user
-0040	Read by group
-0020	Write by group
-0004	Read by others
-0002	Write by others
+0\[aq]400	Read by user
+0\[aq]200	Write by user
+0\[aq]040	Read by group
+0\[aq]020	Write by group
+0\[aq]004	Read by others
+0\[aq]002	Write by others
 .TE
 .PP
-Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
+Bits 0\[aq]100, 0\[aq]010, and 0\[aq]001 (the execute bits) are unused by the system.
 .PP
 Valid values for
 .I cmd
diff --git a/man2/openat2.2 b/man2/openat2.2
index 3ffd06ae7298..8b6cd5781b11 100644
--- a/man2/openat2.2
+++ b/man2/openat2.2
@@ -140,7 +140,7 @@ argument of
 Whereas
 .BR openat (2)
 ignores bits other than those in the range
-.I 07777
+.I 07\[aq]777
 in its
 .I mode
 argument,
@@ -148,7 +148,7 @@ argument,
 returns an error if
 .I how.mode
 contains bits other than
-.IR 07777 .
+.IR 07\[aq]777 .
 Similarly, an error is returned if
 .BR openat2 ()
 is called with a nonzero
diff --git a/man2/process_vm_readv.2 b/man2/process_vm_readv.2
index 712a19dd2212..d6b865878162 100644
--- a/man2/process_vm_readv.2
+++ b/man2/process_vm_readv.2
@@ -271,7 +271,7 @@ when using, for example, shared memory or pipes).
 .SH EXAMPLES
 The following code sample demonstrates the use of
 .BR process_vm_readv ().
-It reads 20 bytes at the address 0x10000 from the process with PID 10
+It reads 20 bytes at the address 0x1\[aq]0000 from the process with PID 10
 and writes the first 10 bytes into
 .I buf1
 and the second 10 bytes into
diff --git a/man2/reboot.2 b/man2/reboot.2
index 6fed0a076c77..d032ef70aafa 100644
--- a/man2/reboot.2
+++ b/man2/reboot.2
@@ -123,7 +123,7 @@ If not preceded by a
 data will be lost.
 .TP
 .B LINUX_REBOOT_CMD_RESTART2
-(0xa1b2c3d4; since Linux 2.1.30).
+(0xa1b2\[aq]c3d4; since Linux 2.1.30).
 The message "Restarting system with command \[aq]%s\[aq]" is printed,
 and a restart (using the command string given in
 .IR arg )
diff --git a/man2/semctl.2 b/man2/semctl.2
index 619062858212..7d6115aa006f 100644
--- a/man2/semctl.2
+++ b/man2/semctl.2
@@ -137,16 +137,16 @@ structure define the access permissions for the shared memory segment.
 The permission bits are as follows:
 .TS
 l l.
-0400	Read by user
-0200	Write by user
-0040	Read by group
-0020	Write by group
-0004	Read by others
-0002	Write by others
+0\[aq]400	Read by user
+0\[aq]200	Write by user
+0\[aq]040	Read by group
+0\[aq]020	Write by group
+0\[aq]004	Read by others
+0\[aq]002	Write by others
 .TE
 .PP
 In effect, "write" means "alter" for a semaphore set.
-Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
+Bits 0\[aq]100, 0\[aq]010, and 0\[aq]001 (the execute bits) are unused by the system.
 .PP
 Valid values for
 .I cmd
@@ -561,7 +561,7 @@ call:
 .B SEMVMX
 Maximum value for
 .BR semval :
-implementation dependent (32767).
+implementation dependent (32Ki-1).
 .PP
 For greater portability, it is best to always call
 .BR semctl ()
diff --git a/man2/shmctl.2 b/man2/shmctl.2
index bc456849d3bd..88d91767dc59 100644
--- a/man2/shmctl.2
+++ b/man2/shmctl.2
@@ -136,15 +136,15 @@ structure define the access permissions for the shared memory segment.
 The permission bits are as follows:
 .TS
 l l.
-0400	Read by user
-0200	Write by user
-0040	Read by group
-0020	Write by group
-0004	Read by others
-0002	Write by others
+0\[aq]400	Read by user
+0\[aq]200	Write by user
+0\[aq]040	Read by group
+0\[aq]020	Write by group
+0\[aq]004	Read by others
+0\[aq]002	Write by others
 .TE
 .PP
-Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
+Bits 0\[aq]100, 0\[aq]010, and 0\[aq]001 (the execute bits) are unused by the system.
 (It is not necessary to have execute permission on a segment
 in order to perform a
 .BR shmat (2)
diff --git a/man2/umask.2 b/man2/umask.2
index 541d81c665ff..7100f6cb8535 100644
--- a/man2/umask.2
+++ b/man2/umask.2
@@ -27,7 +27,7 @@ Standard C library
 .BR umask ()
 sets the calling process's file mode creation mask (umask) to
 .I mask
-& 0777 (i.e., only the file permission bits of
+& 0777 (i.e., only the file permission bits of 0\[aq]777 (i.e., only the file permission bits of
 .I mask
 are used), and returns the previous value of the mask.
 .PP
@@ -63,7 +63,7 @@ u::rwx,g::r-x,o::r-x
 .PP
 Combining the effect of this default ACL with a
 .I mode
-argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644
+argument of 0\[aq]666 (rw-rw-rw-), the resulting file permissions would be 0\[aq]644
 (rw-r--r--).
 .PP
 The constants that should be used to specify
@@ -86,7 +86,7 @@ is specified as:
 .EE
 .in
 .PP
-(octal 0666) when creating a new file, the permissions on the
+(octal 0\[aq]666) when creating a new file, the permissions on the
 resulting file will be:
 .PP
 .in +4n
@@ -95,7 +95,7 @@ resulting file will be:
 .EE
 .in
 .PP
-(because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-).
+(because 0\[aq]666 (because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-). \[ti]022 = 0\[aq]644; i.e. rw\-r\-\-r\-\-).
 .SH RETURN VALUE
 This system call always succeeds and the previous value of the mask
 is returned.
diff --git a/man2/utimensat.2 b/man2/utimensat.2
index c2e6a9164917..90ef97f3c070 100644
--- a/man2/utimensat.2
+++ b/man2/utimensat.2
@@ -272,7 +272,7 @@ Invalid value in
 .B EINVAL
 Invalid value in one of the
 .I tv_nsec
-fields (value outside range [0, 999,999,999], and not
+fields (value outside range [0, 999\[aq]999\[aq]999], and not
 .B UTIME_NOW
 or
 .BR UTIME_OMIT );
-- 
2.39.0


^ permalink raw reply related	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 1/6] man2/: use IEC " Brian Inglis
@ 2023-02-15 21:05   ` Alejandro Colomar
  2023-02-16 21:06   ` Stefan Puiu
  2023-02-16 21:40   ` Jakub Wilk
  2 siblings, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-15 21:05 UTC (permalink / raw)
  To: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 11715 bytes --]

Hi Brian,

On 2/15/23 21:17, Brian Inglis wrote:
> ---
>  man2/add_key.2           | 2 +-
>  man2/epoll_wait.2        | 2 +-
>  man2/fcntl.2             | 2 +-
>  man2/getgroups.2         | 2 +-
>  man2/ioctl_console.2     | 4 ++--
>  man2/iopl.2              | 2 +-
>  man2/madvise.2           | 4 ++--
>  man2/mmap2.2             | 8 ++++----
>  man2/request_key.2       | 2 +-
>  man2/sched_setaffinity.2 | 4 ++--
>  man2/seccomp.2           | 4 ++--
>  man2/semop.2             | 4 ++--
>  man2/sendmmsg.2          | 2 +-
>  man2/shmget.2            | 4 ++--
>  man2/syslog.2            | 6 +++---
>  man2/vmsplice.2          | 2 +-
>  16 files changed, 27 insertions(+), 27 deletions(-)

This time, the patch is exactly as I expected it.  Did you use --no-attach?

> 
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 56fc6d198d21..215de20baeae 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
>  .I type
>  or
>  .I description
> -exceeded the limit (32 bytes and 4096 bytes respectively).
> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>  .TP
>  .B EINVAL
>  The payload data was invalid.
> diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
> index 1620cff9dfcc..4863ae4a43fa 100644
> --- a/man2/epoll_wait.2
> +++ b/man2/epoll_wait.2
> @@ -283,7 +283,7 @@ Thus, for example, on a system where
>  .I sizeof(long)
>  is 4 and the kernel
>  .I HZ
> -value is 1000,
> +value is 1k,
>  this means that timeouts greater than 35.79 minutes are treated as infinity.
>  .SH SEE ALSO
>  .BR epoll_create (2),
> diff --git a/man2/fcntl.2 b/man2/fcntl.2
> index 3ec52dc4dc03..630fc55888bc 100644
> --- a/man2/fcntl.2
> +++ b/man2/fcntl.2
> @@ -2004,7 +2004,7 @@ A limitation of the Linux system call conventions on some
>  architectures (notably i386) means that if a (negative)
>  process group ID to be returned by
>  .B F_GETOWN
> -falls in the range \-1 to \-4095, then the return value is wrongly
> +falls in the range \-1 to \-4Ki-1, then the return value is wrongly

This is incorrect.  It should rather be \-4Ki+1 [or \-(4Ki\-1)].

>  interpreted by glibc as an error in the system call;
>  .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
>  that is, the return value of
> diff --git a/man2/getgroups.2 b/man2/getgroups.2
> index 36300bf61b6a..f01af687ccbd 100644
> --- a/man2/getgroups.2
> +++ b/man2/getgroups.2
> @@ -119,7 +119,7 @@ can additionally fail with the following errors:
>  .I size
>  is greater than
>  .B NGROUPS_MAX
> -(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
> +(32 before Linux 2.6.4; 64Ki since Linux 2.6.4).
>  .TP
>  .B ENOMEM
>  Out of memory.
> diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
> index 89f794c1956c..477e6fd1a7e1 100644
> --- a/man2/ioctl_console.2
> +++ b/man2/ioctl_console.2
> @@ -171,7 +171,7 @@ bright cyan, and white.
>  .B GIO_FONT
>  Gets 256-character screen font in expanded form.
>  .I argp
> -points to an 8192-byte array.
> +points to an 8Ki-byte array.

Heh, this seems to be an 8\ KiB array.

See <https://lore.kernel.org/linux-man/c2ef3b9c-97d1-2733-df27-542c9eacad17@gmail.com/>

Similarly in many cases below.

Cheers,

Alex

>  Fails with error code
>  .B EINVAL
>  if the
> @@ -211,7 +211,7 @@ Sets 256-character screen font.
>  Load font into the EGA/VGA character
>  generator.
>  .I argp
> -points to an 8192-byte map, with 32 bytes per
> +points to an 8Ki-byte map, with 32 bytes per
>  character.
>  Only the first
>  .I N
> diff --git a/man2/iopl.2 b/man2/iopl.2
> index abf1bef675fd..c967296157b7 100644
> --- a/man2/iopl.2
> +++ b/man2/iopl.2
> @@ -34,7 +34,7 @@ Permissions are inherited from parents to children.
>  This call is deprecated, is significantly slower than
>  .BR ioperm (2),
>  and is only provided for older X servers which require
> -access to all 65536 I/O ports.
> +access to all 64Ki I/O ports.
>  It is mostly for the i386 architecture.
>  On many other architectures it does not exist or will always
>  return an error.
> diff --git a/man2/madvise.2 b/man2/madvise.2
> index 9b4652a635d3..e05e9c5de4a7 100644
> --- a/man2/madvise.2
> +++ b/man2/madvise.2
> @@ -329,8 +329,8 @@ naturally aligned to the huge page size (see
>  This feature is primarily aimed at applications that use large mappings of
>  data and access large regions of that memory at a time (e.g., virtualization
>  systems such as QEMU).
> -It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
> -1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
> +It can very easily waste memory (e.g., a 2\ MiB mapping that only ever accesses
> +1 byte will result in 2\ MiB of wired memory instead of one 4\ KiB page).
>  See the Linux kernel source file
>  .I Documentation/admin\-guide/mm/transhuge.rst
>  for more details.
> diff --git a/man2/mmap2.2 b/man2/mmap2.2
> index 1fd5732ad41b..f975c1388a77 100644
> --- a/man2/mmap2.2
> +++ b/man2/mmap2.2
> @@ -32,7 +32,7 @@ The
>  system call provides the same interface as
>  .BR mmap (2),
>  except that the final argument specifies the offset into the
> -file in 4096-byte units (instead of bytes, as is done by
> +file in 4Ki-byte units (instead of bytes, as is done by
>  .BR mmap (2)).
>  This enables applications that use a 32-bit
>  .I off_t
> @@ -50,8 +50,8 @@ is set to indicate the error.
>  Problem with getting the data from user space.
>  .TP
>  .B EINVAL
> -(Various platforms where the page size is not 4096 bytes.)
> -.I "offset\ *\ 4096"
> +(Various platforms where the page size is not 4Ki bytes.)
> +.I "offset\ *\ 4Ki"
>  is not a multiple of the system page size.
>  .PP
>  .BR mmap2 ()
> @@ -74,7 +74,7 @@ This system call does not exist on x86-64.
>  .PP
>  On ia64, the unit for
>  .I offset
> -is actually the system page size, rather than 4096 bytes.
> +is actually the system page size, rather than 4Ki bytes.
>  .\" ia64 can have page sizes ranging from 4 kB to 64 kB.
>  .\" On cris, it looks like the unit might also be the page size,
>  .\" which is 8192 bytes. -- mtk, June 2007
> diff --git a/man2/request_key.2 b/man2/request_key.2
> index e78321e3c23f..dacc5282f3d8 100644
> --- a/man2/request_key.2
> +++ b/man2/request_key.2
> @@ -399,7 +399,7 @@ The size of the string (including the terminating null byte) specified in
>  .I type
>  or
>  .I description
> -exceeded the limit (32 bytes and 4096 bytes respectively).
> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>  .TP
>  .B EINVAL
>  The size of the string (including the terminating null byte) specified in
> diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2
> index 86a93539137d..9e7a26293e73 100644
> --- a/man2/sched_setaffinity.2
> +++ b/man2/sched_setaffinity.2
> @@ -243,10 +243,10 @@ impose no restriction on the size of the CPU mask.
>  However, the
>  .I cpu_set_t
>  data type used by glibc has a fixed size of 128 bytes,
> -meaning that the maximum CPU number that can be represented is 1023.
> +meaning that the maximum CPU number that can be represented is 1\[aq]023.
>  .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
>  .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
> -If the kernel CPU affinity mask is larger than 1024,
> +If the kernel CPU affinity mask is larger than 1Ki,
>  then calls of the form:
>  .PP
>  .in +4n
> diff --git a/man2/seccomp.2 b/man2/seccomp.2
> index 32706397f03e..0bb8caa75698 100644
> --- a/man2/seccomp.2
> +++ b/man2/seccomp.2
> @@ -836,7 +836,7 @@ but the filter program pointed to by
>  .I args
>  was not valid or the length of the filter program was zero or exceeded
>  .B BPF_MAXINSNS
> -(4096) instructions.
> +(4Ki) instructions.
>  .TP
>  .B ENOMEM
>  Out of memory.
> @@ -846,7 +846,7 @@ Out of memory.
>  The total length of all filter programs attached
>  to the calling thread would exceed
>  .B MAX_INSNS_PER_PATH
> -(32768) instructions.
> +(32Ki) instructions.
>  Note that for the purposes of calculating this limit,
>  each already existing filter program incurs an
>  overhead penalty of 4 instructions.
> diff --git a/man2/semop.2 b/man2/semop.2
> index 7a1416a26894..a0027e0706c5 100644
> --- a/man2/semop.2
> +++ b/man2/semop.2
> @@ -434,7 +434,7 @@ On Linux, this limit can be read and modified via the third field of
>  .IR /proc/sys/kernel/sem .
>  .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
>  .IR Note :
> -this limit should not be raised above 1000,
> +this limit should not be raised above 1\[aq]000,
>  .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
>  because of the risk of that
>  .BR semop ()
> @@ -445,7 +445,7 @@ array.
>  .B SEMVMX
>  Maximum allowable value for
>  .IR semval :
> -implementation dependent (32767).
> +implementation dependent (32Ki-1).
>  .PP
>  The implementation has no intrinsic limits for
>  the adjust on exit maximum value
> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
> index 4e5475c45a09..3f355382ebf6 100644
> --- a/man2/sendmmsg.2
> +++ b/man2/sendmmsg.2
> @@ -139,7 +139,7 @@ The value specified in
>  .I vlen
>  is capped to
>  .B UIO_MAXIOV
> -(1024).
> +(1Ki).
>  .\" commit 98382f419f32d2c12d021943b87dea555677144b
>  .\"     net: Cap number of elements for sendmmsg
>  .\"
> diff --git a/man2/shmget.2 b/man2/shmget.2
> index c4d8df8ed619..5421fd4bf3e9 100644
> --- a/man2/shmget.2
> +++ b/man2/shmget.2
> @@ -360,7 +360,7 @@ 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
>  usable segment:
>  for example, on i386 the largest segments that can be mapped have a
> -size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
> +size of around 2.8\ GB, and on x86-64 the limit is around 127\ TB.
>  .TP
>  .B SHMMIN
>  Minimum size in bytes for a shared memory segment: implementation
> @@ -371,7 +371,7 @@ is the effective minimum size).
>  .B SHMMNI
>  System-wide limit on the number of shared memory segments.
>  In Linux 2.2, the default value for this limit was 128;
> -since Linux 2.4, the default value is 4096.
> +since Linux 2.4, the default value is 4Ki.
>  .IP
>  On Linux, this limit can be read and modified via
>  .IR /proc/sys/kernel/shmmni .
> diff --git a/man2/syslog.2 b/man2/syslog.2
> index 09c086f181e3..7d76e8cd9658 100644
> --- a/man2/syslog.2
> +++ b/man2/syslog.2
> @@ -54,9 +54,9 @@ in which messages given as arguments to the kernel function
>  are stored (regardless of their log level).
>  In early kernels,
>  .B LOG_BUF_LEN
> -had the value 4096;
> -from Linux 1.3.54, it was 8192;
> -from Linux 2.1.113, it was 16384;
> +had the value 4Ki;
> +from Linux 1.3.54, it was 8Ki;
> +from Linux 2.1.113, it was 16Ki;
>  since Linux 2.4.23/2.6, the value is a kernel configuration option
>  .RB ( CONFIG_LOG_BUF_SHIFT ,
>  default value dependent on the architecture).
> diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
> index 01ac37b3584f..08ede47361ae 100644
> --- a/man2/vmsplice.2
> +++ b/man2/vmsplice.2
> @@ -149,7 +149,7 @@ as defined in
>  .IR <limits.h> .
>  Currently,
>  .\" UIO_MAXIOV in kernel source
> -this limit is 1024.
> +this limit is 1Ki.
>  .PP
>  .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
>  .BR vmsplice ()

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 2/6] man2/keyctl.2: use IEC or ISO multiples or add C digit separators to clarify long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 2/6] man2/keyctl.2: use IEC or ISO multiples or add C digit separators " Brian Inglis
@ 2023-02-15 21:06   ` Alejandro Colomar
  0 siblings, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-15 21:06 UTC (permalink / raw)
  To: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 2408 bytes --]

Hi Brian,

On 2/15/23 21:17, Brian Inglis wrote:
> ---
>  man2/keyctl.2 | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index 4ce87dcf31af..0c27aaa44d7f 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -729,7 +729,7 @@ including the terminating null byte), and
>  (cast as
>  .IR char\~* )
>  contains the description of the key
> -(a null-terminated character string up to 4096 bytes in size,
> +(a null-terminated character string up to 4Ki bytes in size,

4\ KiB

(and similarly below).

Cheers,

Alex

>  including the terminating null byte).
>  .IP
>  The source keyring must grant
> @@ -1742,7 +1742,7 @@ was
>  .B KEYCTL_SEARCH
>  and the size of the description in
>  .I arg4
> -(including the terminating null byte) exceeded 4096 bytes.
> +(including the terminating null byte) exceeded 4Ki bytes.
>  .TP
>  .B EINVAL
>  size of the string (including the terminating null byte) specified in
> @@ -1751,7 +1751,7 @@ size of the string (including the terminating null byte) specified in
>  or
>  .I arg4
>  (the key description)
> -exceeded the limit (32 bytes and 4096 bytes respectively).
> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>  .TP
>  .BR EINVAL " (before Linux 4.12)"
>  .I operation
> @@ -1822,7 +1822,7 @@ was
>  .B KEYCTL_DH_COMPUTE
>  and the buffer length exceeds
>  .B KEYCTL_KDF_MAX_OUTPUT_LEN
> -(which is 1024 currently)
> +(which is 1Ki currently)
>  or the
>  .I otherinfolen
>  field of the
> @@ -2047,7 +2047,7 @@ and
>  the description of the authorization key,
>  where we can see that the name of the authorization key matches
>  the ID of the key that is to be instantiated
> -.RI ( 20d035bf ).
> +.RI ( 20d0\[aq]35bf ).
>  .PP
>  The example program in
>  .BR request_key (2)
> @@ -2056,12 +2056,12 @@ specified the destination keyring as
>  By examining the contents of
>  .IR /proc/keys ,
>  we can see that this was translated to the ID of the destination keyring
> -.RI ( 0256e6a6 )
> +.RI ( 0256\[aq]e6a6 )
>  shown in the log output above;
>  we can also see the newly created key with the name
>  .I mykey
>  and ID
> -.IR 20d035bf .
> +.IR 20d0\[aq]35bf .
>  .PP
>  .in +4n
>  .EX

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates
  2023-02-15 20:17 ` [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates Brian Inglis
@ 2023-02-15 21:08   ` Alejandro Colomar
  2023-02-16 21:11   ` Stefan Puiu
  1 sibling, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-15 21:08 UTC (permalink / raw)
  To: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 19241 bytes --]

Hi Brian,

On 2/15/23 21:17, Brian Inglis wrote:
> ---
>  man2/access.2           | 2 +-
>  man2/brk.2              | 4 ++--
>  man2/chdir.2            | 2 +-
>  man2/chown.2            | 4 ++--
>  man2/clock_getres.2     | 2 +-
>  man2/clock_nanosleep.2  | 2 +-
>  man2/fsync.2            | 4 ++--
>  man2/gethostname.2      | 2 +-
>  man2/getpagesize.2      | 4 ++--
>  man2/getsid.2           | 2 +-
>  man2/link.2             | 2 +-
>  man2/mkdir.2            | 4 ++--
>  man2/nanosleep.2        | 2 +-
>  man2/open.2             | 4 ++--
>  man2/posix_fadvise.2    | 2 +-
>  man2/pread.2            | 2 +-
>  man2/readlink.2         | 4 ++--
>  man2/rename.2           | 2 +-
>  man2/seteuid.2          | 2 +-
>  man2/setpgid.2          | 2 +-
>  man2/sigaltstack.2      | 2 +-
>  man2/sigwaitinfo.2      | 2 +-
>  man2/stat.2             | 4 ++--
>  man2/symlink.2          | 4 ++--
>  man2/timer_create.2     | 2 +-
>  man2/timer_delete.2     | 2 +-
>  man2/timer_getoverrun.2 | 2 +-
>  man2/truncate.2         | 4 ++--
>  man2/unlink.2           | 2 +-
>  man2/vfork.2            | 2 +-
>  man2/wait.2             | 4 ++--
>  man2/wait4.2            | 2 +-
>  32 files changed, 43 insertions(+), 43 deletions(-)
> 
> diff --git a/man2/access.2 b/man2/access.2
> index d3deeecba0c7..4c93a132b209 100644
> --- a/man2/access.2
> +++ b/man2/access.2
> @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR faccessat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/brk.2 b/man2/brk.2
> index 31c167c56955..298fd006d742 100644
> --- a/man2/brk.2
> +++ b/man2/brk.2
> @@ -32,13 +32,13 @@ Feature Test Macro Requirements for glibc (see
>      Since glibc 2.19:
>          _DEFAULT_SOURCE
>              || ((_XOPEN_SOURCE >= 500) &&
> -                ! (_POSIX_C_SOURCE >= 200112L))
> +                ! (_POSIX_C_SOURCE >= 2001\[aq]12L))
>  .\"    (_XOPEN_SOURCE >= 500 ||
>  .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
>      From glibc 2.12 to glibc 2.19:
>          _BSD_SOURCE || _SVID_SOURCE
>              || ((_XOPEN_SOURCE >= 500) &&
> -                ! (_POSIX_C_SOURCE >= 200112L))
> +                ! (_POSIX_C_SOURCE >= 2001\[aq]12L))
>  .\"    (_XOPEN_SOURCE >= 500 ||
>  .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
>      Before glibc 2.12:
> diff --git a/man2/chdir.2 b/man2/chdir.2
> index 0bbff4e87842..cca6a568871c 100644
> --- a/man2/chdir.2
> +++ b/man2/chdir.2
> @@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || /* glibc up to and including 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/chown.2 b/man2/chown.2
> index d66b66f544cb..5c87dfa6aa9b 100644
> --- a/man2/chown.2
> +++ b/man2/chown.2
> @@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR fchown (),
>  .BR lchown ():
>  .nf
> -    /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +    /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
>          || /* glibc <= 2.19: */ _BSD_SOURCE
> @@ -53,7 +53,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR fchownat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index 8d90baaaabd6..b6a3bedbd944 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -39,7 +39,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR clock_gettime (),
>  .BR clock_settime ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  The function
> diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
> index 5da8d15699c2..fe78d6bedb11 100644
> --- a/man2/clock_nanosleep.2
> +++ b/man2/clock_nanosleep.2
> @@ -30,7 +30,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR clock_nanosleep ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L
>  .fi
>  .SH DESCRIPTION
>  Like
> diff --git a/man2/fsync.2 b/man2/fsync.2
> index 9dc99a15a20e..78fc6013b773 100644
> --- a/man2/fsync.2
> +++ b/man2/fsync.2
> @@ -41,12 +41,12 @@ Feature Test Macro Requirements for glibc (see
>          No feature test macros need be defined
>      glibc up to and including 2.15:
>          _BSD_SOURCE || _XOPEN_SOURCE
> -            || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
> +            || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 2001\[aq]12L
>  .fi
>  .PP
>  .BR fdatasync ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
> +    _POSIX_C_SOURCE >= 1993\[aq]09L || _XOPEN_SOURCE >= 500
>  .fi
>  .SH DESCRIPTION
>  .BR fsync ()
> diff --git a/man2/gethostname.2 b/man2/gethostname.2
> index bc74610c9c5d..e6d3b5837c2c 100644
> --- a/man2/gethostname.2
> +++ b/man2/gethostname.2
> @@ -30,7 +30,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR gethostname ():
>  .nf
> -    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
> +    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc 2.19 and earlier */ _BSD_SOURCE
>  .\" The above is something of a simplification
>  .\" also before glibc 2.3 there was a bit churn
> diff --git a/man2/getpagesize.2 b/man2/getpagesize.2
> index 39af55619be4..356bb42f08f1 100644
> --- a/man2/getpagesize.2
> +++ b/man2/getpagesize.2
> @@ -23,9 +23,9 @@ Feature Test Macro Requirements for glibc (see
>  .BR getpagesize ():
>  .nf
>      Since glibc 2.20:
> -        _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 200112L)
> +        _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 2001\[aq]12L)
>      glibc 2.12 to glibc 2.19:
> -        _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 200112L)
> +        _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 2001\[aq]12L)
>      Before glibc 2.12:
>          _BSD_SOURCE || _XOPEN_SOURCE >= 500
>  .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> diff --git a/man2/getsid.2 b/man2/getsid.2
> index 3afccbd9d6bf..355c4df2601a 100644
> --- a/man2/getsid.2
> +++ b/man2/getsid.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR getsid ()
> diff --git a/man2/link.2 b/man2/link.2
> index 60b739eba152..49526bfe36d4 100644
> --- a/man2/link.2
> +++ b/man2/link.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR linkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/mkdir.2 b/man2/mkdir.2
> index b1339a49a513..68539ab7e1ab 100644
> --- a/man2/mkdir.2
> +++ b/man2/mkdir.2
> @@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR mkdirat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> @@ -49,7 +49,7 @@ It is modified by the process's
>  .I umask
>  in the usual way: in the absence of a default ACL, the mode of the
>  created directory is
> -.RI ( mode " & \[ti]" umask " & 0777)."
> +.RI ( mode " & \[ti]" umask " & 0\[aq]777)."

This seems an accident in the patch :)

>  Whether other
>  .I mode
>  bits are honored for the created directory depends on the operating system.
> diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
> index 12e0cee84b85..4732ef705fe0 100644
> --- a/man2/nanosleep.2
> +++ b/man2/nanosleep.2
> @@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR nanosleep ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR nanosleep ()
> diff --git a/man2/open.2 b/man2/open.2
> index aefcae1e601e..1bb3640014e6 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -60,7 +60,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR openat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> @@ -1772,7 +1772,7 @@ In Linux 2.4,
>  most filesystems based on block devices require that
>  the file offset and the length and memory address of all I/O segments
>  be multiples of the filesystem block size
> -(typically 4096 bytes).
> +(typically 4Ki bytes).
>  In Linux 2.6.0,
>  this was relaxed to the logical block size of the block device
>  (typically 512 bytes).
> diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2
> index 57c65c810791..cb9b6ea24dd8 100644
> --- a/man2/posix_fadvise.2
> +++ b/man2/posix_fadvise.2
> @@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR posix_fadvise ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L
>  .fi
>  .SH DESCRIPTION
>  Programs can use
> diff --git a/man2/pread.2 b/man2/pread.2
> index 9a9763323518..7a8fce5764d5 100644
> --- a/man2/pread.2
> +++ b/man2/pread.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR pwrite ():
>  .nf
>      _XOPEN_SOURCE >= 500
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR pread ()
> diff --git a/man2/readlink.2 b/man2/readlink.2
> index de158da7e355..e23564450af2 100644
> --- a/man2/readlink.2
> +++ b/man2/readlink.2
> @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR readlink ():
>  .nf
> -    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
> +    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
> @@ -48,7 +48,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR readlinkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/rename.2 b/man2/rename.2
> index 08e7958f3220..7e4b33cdb9d8 100644
> --- a/man2/rename.2
> +++ b/man2/rename.2
> @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>  .BR renameat ():
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .PP
> diff --git a/man2/seteuid.2 b/man2/seteuid.2
> index 14b23b3f40b0..4dd30ecfc012 100644
> --- a/man2/seteuid.2
> +++ b/man2/seteuid.2
> @@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR seteuid (),
>  .BR setegid ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/setpgid.2 b/man2/setpgid.2
> index 52c5bd5fcc10..4cf35c3a0c03 100644
> --- a/man2/setpgid.2
> +++ b/man2/setpgid.2
> @@ -46,7 +46,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>  .fi
>  .PP
>  .BR setpgrp "() (POSIX.1):"
> diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2
> index cdc8a8e39f70..45d6db43a0c8 100644
> --- a/man2/sigaltstack.2
> +++ b/man2/sigaltstack.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2
> index 42209c1806e9..791dc418d6c4 100644
> --- a/man2/sigwaitinfo.2
> +++ b/man2/sigwaitinfo.2
> @@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR sigwaitinfo (),
>  .BR sigtimedwait ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR sigwaitinfo ()
> diff --git a/man2/stat.2 b/man2/stat.2
> index 8479befccd8d..4bd67667b5c2 100644
> --- a/man2/stat.2
> +++ b/man2/stat.2
> @@ -49,14 +49,14 @@ Feature Test Macro Requirements for glibc (see
>      /* Since glibc 2.20 */ _DEFAULT_SOURCE
>          || _XOPEN_SOURCE >= 500
>  .\"   _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
> +        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc 2.19 and earlier */ _BSD_SOURCE
>  .fi
>  .PP
>  .BR fstatat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/symlink.2 b/man2/symlink.2
> index 13b2ed1ccd5b..34078fabfe01 100644
> --- a/man2/symlink.2
> +++ b/man2/symlink.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR symlink ():
>  .nf
> -    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
> +    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
> @@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR symlinkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/timer_create.2 b/man2/timer_create.2
> index 6d49da17f89a..0f26075e457c 100644
> --- a/man2/timer_create.2
> +++ b/man2/timer_create.2
> @@ -26,7 +26,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR timer_create ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR timer_create ()
> diff --git a/man2/timer_delete.2 b/man2/timer_delete.2
> index c489d9ec0dff..e0397af5bf4f 100644
> --- a/man2/timer_delete.2
> +++ b/man2/timer_delete.2
> @@ -23,7 +23,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR timer_delete ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR timer_delete ()
> diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2
> index 3591e5de5df5..690c19937799 100644
> --- a/man2/timer_getoverrun.2
> +++ b/man2/timer_getoverrun.2
> @@ -23,7 +23,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR timer_getoverrun ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR timer_getoverrun ()
> diff --git a/man2/truncate.2 b/man2/truncate.2
> index 8a00ec3ffba2..bb57666e64b1 100644
> --- a/man2/truncate.2
> +++ b/man2/truncate.2
> @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .PP
> @@ -43,7 +43,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L
> +        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/unlink.2 b/man2/unlink.2
> index 954a19f1534a..4c296e73086b 100644
> --- a/man2/unlink.2
> +++ b/man2/unlink.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR unlinkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/vfork.2 b/man2/vfork.2
> index 5e6b8226c301..e3c82f1d6bc4 100644
> --- a/man2/vfork.2
> +++ b/man2/vfork.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR vfork ():
>  .nf
>      Since glibc 2.12:
> -        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
> +        (_XOPEN_SOURCE >= 500)         (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) ! (_POSIX_C_SOURCE >= 2008\[aq]09L)

Something is weird in this change.

Cheers,
Alex

>              || /* Since glibc 2.19: */ _DEFAULT_SOURCE
>              || /* glibc <= 2.19: */ _BSD_SOURCE
>      Before glibc 2.12:
> diff --git a/man2/wait.2 b/man2/wait.2
> index e2dcd59bda09..ad031d40ca07 100644
> --- a/man2/wait.2
> +++ b/man2/wait.2
> @@ -53,11 +53,11 @@ Feature Test Macro Requirements for glibc (see
>  .BR waitid ():
>  .nf
>      Since glibc 2.26:
> -        _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
> +        _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2008\[aq]09L
>  .\"    (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
>      glibc 2.25 and earlier:
>          _XOPEN_SOURCE
> -            || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +            || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>              || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/wait4.2 b/man2/wait4.2
> index a5b38108d318..703df0797f80 100644
> --- a/man2/wait4.2
> +++ b/man2/wait4.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>      Since glibc 2.26:
>          _DEFAULT_SOURCE
>              || (_XOPEN_SOURCE >= 500 &&
> -                ! (_POSIX_C_SOURCE >= 200112L
> +                ! (_POSIX_C_SOURCE >= 2001\[aq]12L
>                     || _XOPEN_SOURCE >= 600))
>      From glibc 2.19 to glibc 2.25:
>          _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 4/6] man2/select.2: add C digit separators to clarify POSIX feature release dates or use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 4/6] man2/select.2: add C digit separators to clarify POSIX feature release dates or use IEC or ISO multiples to clarify long numeric digit strings Brian Inglis
@ 2023-02-15 21:09   ` Alejandro Colomar
  0 siblings, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-15 21:09 UTC (permalink / raw)
  To: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 1493 bytes --]

Hi Brian,

On 2/15/23 21:17, Brian Inglis wrote:
> ---
>  man2/select.2 | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/man2/select.2 b/man2/select.2
> index 7718b75067ab..bb7a252ade80 100644
> --- a/man2/select.2
> +++ b/man2/select.2
> @@ -54,14 +54,14 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR pselect ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L

I expect that this would go in patch 3/6.  Why is it separate?

Thanks,

Alex

>  .fi
>  .SH DESCRIPTION
>  .BR "WARNING" :
>  .BR select ()
>  can monitor only file descriptors numbers that are less than
>  .B FD_SETSIZE
> -(1024)\[em]an unreasonably low limit for many modern applications\[em]and
> +(1Ki)\[em]an unreasonably low limit for many modern applications\[em]and
>  this limitation will not change.
>  All modern applications should instead use
>  .BR poll (2)
> @@ -639,10 +639,10 @@ The Linux kernel imposes no fixed limit, but the glibc implementation makes
>  .I fd_set
>  a fixed-size type, with
>  .B FD_SETSIZE
> -defined as 1024, and the
> +defined as 1Ki, and the
>  .BR FD_* ()
>  macros operating according to that limit.
> -To monitor file descriptors greater than 1023, use
> +To monitor file descriptors greater than 1Ki-1, use
>  .BR poll (2)
>  or
>  .BR epoll (7)

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and " Brian Inglis
@ 2023-02-15 21:10   ` Alejandro Colomar
  2023-02-18 17:42     ` Tom Schwindl
  0 siblings, 1 reply; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-15 21:10 UTC (permalink / raw)
  To: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 3293 bytes --]

Hi Brian,

On 2/15/23 21:17, Brian Inglis wrote:
> ---
>  man2/chmod.2 | 30 +++++++++++++++---------------
>  1 file changed, 15 insertions(+), 15 deletions(-)
> 
> diff --git a/man2/chmod.2 b/man2/chmod.2
> index 8b5db74ed7e3..674b54368314 100644
> --- a/man2/chmod.2
> +++ b/man2/chmod.2
> @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>  .BR fchmod ():
>      Since glibc 2.24:
> -        _POSIX_C_SOURCE >= 199309L
> +        _POSIX_C_SOURCE >= 1993\[aq]09L

Please keep all POSIX dates in a single separate patch
(unless there's another reason that I'm not seeing).

Cheers,

Alex

>  .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
>      glibc 2.19 to glibc 2.23
>          _POSIX_C_SOURCE
> @@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see
>          _BSD_SOURCE || _POSIX_C_SOURCE
>      glibc 2.12 to glibc 2.16:
>          _BSD_SOURCE || _XOPEN_SOURCE >= 500
> -            || _POSIX_C_SOURCE >= 200809L
> +            || _POSIX_C_SOURCE >= 2008\[aq]09L
>      glibc 2.11 and earlier:
>          _BSD_SOURCE || _XOPEN_SOURCE >= 500
>  .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
> @@ -54,7 +54,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR fchmodat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> @@ -82,11 +82,11 @@ The new file mode is specified in
>  which is a bit mask created by ORing together zero or
>  more of the following:
>  .TP 18
> -.BR S_ISUID "  (04000)"
> +.BR S_ISUID "  (04\[aq]000)"
>  set-user-ID (set process effective user ID on
>  .BR execve (2))
>  .TP
> -.BR S_ISGID "  (02000)"
> +.BR S_ISGID "  (02\[aq]000)"
>  set-group-ID (set process effective group ID on
>  .BR execve (2);
>  mandatory locking, as described in
> @@ -96,36 +96,36 @@ take a new file's group from parent directory, as described in
>  and
>  .BR mkdir (2))
>  .TP
> -.BR S_ISVTX "  (01000)"
> +.BR S_ISVTX "  (01\[aq]000)"
>  sticky bit (restricted deletion flag, as described in
>  .BR unlink (2))
>  .TP
> -.BR S_IRUSR "  (00400)"
> +.BR S_IRUSR "  (00\[aq]400)"
>  read by owner
>  .TP
> -.BR S_IWUSR "  (00200)"
> +.BR S_IWUSR "  (00\[aq]200)"
>  write by owner
>  .TP
> -.BR S_IXUSR "  (00100)"
> +.BR S_IXUSR "  (00\[aq]100)"
>  execute/search by owner ("search" applies for directories,
>  and means that entries within the directory can be accessed)
>  .TP
> -.BR S_IRGRP "  (00040)"
> +.BR S_IRGRP "  (00\[aq]040)"
>  read by group
>  .TP
> -.BR S_IWGRP "  (00020)"
> +.BR S_IWGRP "  (00\[aq]020)"
>  write by group
>  .TP
> -.BR S_IXGRP "  (00010)"
> +.BR S_IXGRP "  (00\[aq]010)"
>  execute/search by group
>  .TP
> -.BR S_IROTH "  (00004)"
> +.BR S_IROTH "  (00\[aq]004)"
>  read by others
>  .TP
> -.BR S_IWOTH "  (00002)"
> +.BR S_IWOTH "  (00\[aq]002)"
>  write by others
>  .TP
> -.BR S_IXOTH "  (00001)"
> +.BR S_IXOTH "  (00\[aq]001)"
>  execute/search by others
>  .PP
>  The effective UID of the calling process must match the owner of the file,

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 6/6] man2/: add C digit separators to clarify long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 6/6] man2/: add C digit separators to clarify " Brian Inglis
@ 2023-02-15 21:14   ` Alejandro Colomar
  0 siblings, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-15 21:14 UTC (permalink / raw)
  To: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 8844 bytes --]

Hi Brian,

On 2/15/23 21:17, Brian Inglis wrote:
> ---
>  man2/capget.2           |  6 +++---
>  man2/ioctl.2            |  4 ++--
>  man2/msgctl.2           | 14 +++++++-------
>  man2/openat2.2          |  4 ++--
>  man2/process_vm_readv.2 |  2 +-
>  man2/reboot.2           |  2 +-
>  man2/semctl.2           | 16 ++++++++--------
>  man2/shmctl.2           | 14 +++++++-------
>  man2/umask.2            |  8 ++++----
>  man2/utimensat.2        |  2 +-
>  10 files changed, 36 insertions(+), 36 deletions(-)
> 
> diff --git a/man2/capget.2 b/man2/capget.2
> index 909f8bfe0de0..7c0e5b414d5d 100644
> --- a/man2/capget.2
> +++ b/man2/capget.2
> @@ -56,17 +56,17 @@ The structures are defined as follows.
>  .PP
>  .in +4n
>  .EX
> -#define _LINUX_CAPABILITY_VERSION_1  0x19980330
> +#define _LINUX_CAPABILITY_VERSION_1  0x1998\[aq]03\[aq]30
>  #define _LINUX_CAPABILITY_U32S_1     1
>  
>          /* V2 added in Linux 2.6.25; deprecated */
> -#define _LINUX_CAPABILITY_VERSION_2  0x20071026
> +#define _LINUX_CAPABILITY_VERSION_2  0x2007\[aq]10\[aq]26
>  .\" commit e338d263a76af78fe8f38a72131188b58fceb591
>  .\" Added 64 bit capability support
>  #define _LINUX_CAPABILITY_U32S_2     2
>  
>          /* V3 added in Linux 2.6.26 */
> -#define _LINUX_CAPABILITY_VERSION_3  0x20080522
> +#define _LINUX_CAPABILITY_VERSION_3  0x2008\[aq]05\[aq]22
>  .\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f
>  #define _LINUX_CAPABILITY_U32S_3     2
>  
> diff --git a/man2/ioctl.2 b/man2/ioctl.2
> index f33f2c57c103..36e1ff4e041f 100644
> --- a/man2/ioctl.2
> +++ b/man2/ioctl.2
> @@ -134,9 +134,9 @@ one or more ASCII letters were used.
>  For example,
>  .B TCGETS
>  has value
> -0x00005401, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and
> +0x00\[aq]00\[aq]54\[aq]01, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and
>  .B CYGETTIMEOUT
> -has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
> +has value 0x00\[aq]43\[aq]59\[aq]06, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
>  indicating the cyclades driver.
>  .PP
>  Later (0.98p5) some more information was built into the number.
> diff --git a/man2/msgctl.2 b/man2/msgctl.2
> index ce534dc2abd5..f49b8a951d29 100644
> --- a/man2/msgctl.2
> +++ b/man2/msgctl.2
> @@ -131,15 +131,15 @@ structure define the access permissions for the message queue.
>  The permission bits are as follows:
>  .TS
>  l l.
> -0400	Read by user
> -0200	Write by user
> -0040	Read by group
> -0020	Write by group
> -0004	Read by others
> -0002	Write by others
> +0\[aq]400	Read by user
> +0\[aq]200	Write by user
> +0\[aq]040	Read by group
> +0\[aq]020	Write by group
> +0\[aq]004	Read by others
> +0\[aq]002	Write by others

Please break this into several patches.  At least one for dates (which are special),
other for normal hex numbers, and another for octals.

I expect this patch set to be around 15 patches, and that's fine.  It will be easier
to review.


Cheers,

Alex

>  .TE
>  .PP
> -Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
> +Bits 0\[aq]100, 0\[aq]010, and 0\[aq]001 (the execute bits) are unused by the system.
>  .PP
>  Valid values for
>  .I cmd
> diff --git a/man2/openat2.2 b/man2/openat2.2
> index 3ffd06ae7298..8b6cd5781b11 100644
> --- a/man2/openat2.2
> +++ b/man2/openat2.2
> @@ -140,7 +140,7 @@ argument of
>  Whereas
>  .BR openat (2)
>  ignores bits other than those in the range
> -.I 07777
> +.I 07\[aq]777
>  in its
>  .I mode
>  argument,
> @@ -148,7 +148,7 @@ argument,
>  returns an error if
>  .I how.mode
>  contains bits other than
> -.IR 07777 .
> +.IR 07\[aq]777 .
>  Similarly, an error is returned if
>  .BR openat2 ()
>  is called with a nonzero
> diff --git a/man2/process_vm_readv.2 b/man2/process_vm_readv.2
> index 712a19dd2212..d6b865878162 100644
> --- a/man2/process_vm_readv.2
> +++ b/man2/process_vm_readv.2
> @@ -271,7 +271,7 @@ when using, for example, shared memory or pipes).
>  .SH EXAMPLES
>  The following code sample demonstrates the use of
>  .BR process_vm_readv ().
> -It reads 20 bytes at the address 0x10000 from the process with PID 10
> +It reads 20 bytes at the address 0x1\[aq]0000 from the process with PID 10
>  and writes the first 10 bytes into
>  .I buf1
>  and the second 10 bytes into
> diff --git a/man2/reboot.2 b/man2/reboot.2
> index 6fed0a076c77..d032ef70aafa 100644
> --- a/man2/reboot.2
> +++ b/man2/reboot.2
> @@ -123,7 +123,7 @@ If not preceded by a
>  data will be lost.
>  .TP
>  .B LINUX_REBOOT_CMD_RESTART2
> -(0xa1b2c3d4; since Linux 2.1.30).
> +(0xa1b2\[aq]c3d4; since Linux 2.1.30).
>  The message "Restarting system with command \[aq]%s\[aq]" is printed,
>  and a restart (using the command string given in
>  .IR arg )
> diff --git a/man2/semctl.2 b/man2/semctl.2
> index 619062858212..7d6115aa006f 100644
> --- a/man2/semctl.2
> +++ b/man2/semctl.2
> @@ -137,16 +137,16 @@ structure define the access permissions for the shared memory segment.
>  The permission bits are as follows:
>  .TS
>  l l.
> -0400	Read by user
> -0200	Write by user
> -0040	Read by group
> -0020	Write by group
> -0004	Read by others
> -0002	Write by others
> +0\[aq]400	Read by user
> +0\[aq]200	Write by user
> +0\[aq]040	Read by group
> +0\[aq]020	Write by group
> +0\[aq]004	Read by others
> +0\[aq]002	Write by others
>  .TE
>  .PP
>  In effect, "write" means "alter" for a semaphore set.
> -Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
> +Bits 0\[aq]100, 0\[aq]010, and 0\[aq]001 (the execute bits) are unused by the system.
>  .PP
>  Valid values for
>  .I cmd
> @@ -561,7 +561,7 @@ call:
>  .B SEMVMX
>  Maximum value for
>  .BR semval :
> -implementation dependent (32767).
> +implementation dependent (32Ki-1).
>  .PP
>  For greater portability, it is best to always call
>  .BR semctl ()
> diff --git a/man2/shmctl.2 b/man2/shmctl.2
> index bc456849d3bd..88d91767dc59 100644
> --- a/man2/shmctl.2
> +++ b/man2/shmctl.2
> @@ -136,15 +136,15 @@ structure define the access permissions for the shared memory segment.
>  The permission bits are as follows:
>  .TS
>  l l.
> -0400	Read by user
> -0200	Write by user
> -0040	Read by group
> -0020	Write by group
> -0004	Read by others
> -0002	Write by others
> +0\[aq]400	Read by user
> +0\[aq]200	Write by user
> +0\[aq]040	Read by group
> +0\[aq]020	Write by group
> +0\[aq]004	Read by others
> +0\[aq]002	Write by others
>  .TE
>  .PP
> -Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
> +Bits 0\[aq]100, 0\[aq]010, and 0\[aq]001 (the execute bits) are unused by the system.
>  (It is not necessary to have execute permission on a segment
>  in order to perform a
>  .BR shmat (2)
> diff --git a/man2/umask.2 b/man2/umask.2
> index 541d81c665ff..7100f6cb8535 100644
> --- a/man2/umask.2
> +++ b/man2/umask.2
> @@ -27,7 +27,7 @@ Standard C library
>  .BR umask ()
>  sets the calling process's file mode creation mask (umask) to
>  .I mask
> -& 0777 (i.e., only the file permission bits of
> +& 0777 (i.e., only the file permission bits of 0\[aq]777 (i.e., only the file permission bits of
>  .I mask
>  are used), and returns the previous value of the mask.
>  .PP
> @@ -63,7 +63,7 @@ u::rwx,g::r-x,o::r-x
>  .PP
>  Combining the effect of this default ACL with a
>  .I mode
> -argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644
> +argument of 0\[aq]666 (rw-rw-rw-), the resulting file permissions would be 0\[aq]644
>  (rw-r--r--).
>  .PP
>  The constants that should be used to specify
> @@ -86,7 +86,7 @@ is specified as:
>  .EE
>  .in
>  .PP
> -(octal 0666) when creating a new file, the permissions on the
> +(octal 0\[aq]666) when creating a new file, the permissions on the
>  resulting file will be:
>  .PP
>  .in +4n
> @@ -95,7 +95,7 @@ resulting file will be:
>  .EE
>  .in
>  .PP
> -(because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-).
> +(because 0\[aq]666 (because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-). \[ti]022 = 0\[aq]644; i.e. rw\-r\-\-r\-\-).
>  .SH RETURN VALUE
>  This system call always succeeds and the previous value of the mask
>  is returned.
> diff --git a/man2/utimensat.2 b/man2/utimensat.2
> index c2e6a9164917..90ef97f3c070 100644
> --- a/man2/utimensat.2
> +++ b/man2/utimensat.2
> @@ -272,7 +272,7 @@ Invalid value in
>  .B EINVAL
>  Invalid value in one of the
>  .I tv_nsec
> -fields (value outside range [0, 999,999,999], and not
> +fields (value outside range [0, 999\[aq]999\[aq]999], and not
>  .B UTIME_NOW
>  or
>  .BR UTIME_OMIT );

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
                   ` (6 preceding siblings ...)
  2023-02-15 20:17 ` [PATCH v3 6/6] man2/: add C digit separators to clarify " Brian Inglis
@ 2023-02-15 22:51 ` Brian Inglis
  7 siblings, 0 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-15 22:51 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar

On 2023-02-15 13:15, Brian Inglis wrote:
> man2/: use C digit separators "'" \[aq], IEC, or ISO multiples
> to clarify long binary, octal, hex, decimal numeric digit strings
Replying here rather than individually - made your mind up about some things and 
changing the goal posts again on me - eh! ;^>
Will post v4 after reorg and check the weird sedit!
Should have picked the section with the fewest long numeric digit strings to 
start ;^p

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


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 1/6] man2/: use IEC " Brian Inglis
  2023-02-15 21:05   ` Alejandro Colomar
@ 2023-02-16 21:06   ` Stefan Puiu
  2023-02-16 23:01     ` Alejandro Colomar
  2023-02-16 21:40   ` Jakub Wilk
  2 siblings, 1 reply; 39+ messages in thread
From: Stefan Puiu @ 2023-02-16 21:06 UTC (permalink / raw)
  To: Brian Inglis; +Cc: Linux Man Pages, Alejandro Colomar

Hi Brian,

On Wed, Feb 15, 2023 at 10:21 PM Brian Inglis <Brian.Inglis@shaw.ca> wrote:
>
> ---
>  man2/add_key.2           | 2 +-
>  man2/epoll_wait.2        | 2 +-
>  man2/fcntl.2             | 2 +-
>  man2/getgroups.2         | 2 +-
>  man2/ioctl_console.2     | 4 ++--
>  man2/iopl.2              | 2 +-
>  man2/madvise.2           | 4 ++--
>  man2/mmap2.2             | 8 ++++----
>  man2/request_key.2       | 2 +-
>  man2/sched_setaffinity.2 | 4 ++--
>  man2/seccomp.2           | 4 ++--
>  man2/semop.2             | 4 ++--
>  man2/sendmmsg.2          | 2 +-
>  man2/shmget.2            | 4 ++--
>  man2/syslog.2            | 6 +++---
>  man2/vmsplice.2          | 2 +-
>  16 files changed, 27 insertions(+), 27 deletions(-)
>
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 56fc6d198d21..215de20baeae 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
>  .I type
>  or
>  .I description
> -exceeded the limit (32 bytes and 4096 bytes respectively).
> +exceeded the limit (32 bytes and 4Ki bytes respectively).

For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?

>  .TP
>  .B EINVAL
>  The payload data was invalid.
> diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
> index 1620cff9dfcc..4863ae4a43fa 100644
> --- a/man2/epoll_wait.2
> +++ b/man2/epoll_wait.2
> @@ -283,7 +283,7 @@ Thus, for example, on a system where
>  .I sizeof(long)
>  is 4 and the kernel
>  .I HZ
> -value is 1000,
> +value is 1k,

I still prefer the old version, my impression is that 1k and friends
are used in informal contexts. Of course, it could be only my
impression.

Just my 2 cents,
Stefan.

>  this means that timeouts greater than 35.79 minutes are treated as infinity.
>  .SH SEE ALSO
>  .BR epoll_create (2),
> diff --git a/man2/fcntl.2 b/man2/fcntl.2
> index 3ec52dc4dc03..630fc55888bc 100644
> --- a/man2/fcntl.2
> +++ b/man2/fcntl.2
> @@ -2004,7 +2004,7 @@ A limitation of the Linux system call conventions on some
>  architectures (notably i386) means that if a (negative)
>  process group ID to be returned by
>  .B F_GETOWN
> -falls in the range \-1 to \-4095, then the return value is wrongly
> +falls in the range \-1 to \-4Ki-1, then the return value is wrongly
>  interpreted by glibc as an error in the system call;
>  .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
>  that is, the return value of
> diff --git a/man2/getgroups.2 b/man2/getgroups.2
> index 36300bf61b6a..f01af687ccbd 100644
> --- a/man2/getgroups.2
> +++ b/man2/getgroups.2
> @@ -119,7 +119,7 @@ can additionally fail with the following errors:
>  .I size
>  is greater than
>  .B NGROUPS_MAX
> -(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
> +(32 before Linux 2.6.4; 64Ki since Linux 2.6.4).
>  .TP
>  .B ENOMEM
>  Out of memory.
> diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
> index 89f794c1956c..477e6fd1a7e1 100644
> --- a/man2/ioctl_console.2
> +++ b/man2/ioctl_console.2
> @@ -171,7 +171,7 @@ bright cyan, and white.
>  .B GIO_FONT
>  Gets 256-character screen font in expanded form.
>  .I argp
> -points to an 8192-byte array.
> +points to an 8Ki-byte array.
>  Fails with error code
>  .B EINVAL
>  if the
> @@ -211,7 +211,7 @@ Sets 256-character screen font.
>  Load font into the EGA/VGA character
>  generator.
>  .I argp
> -points to an 8192-byte map, with 32 bytes per
> +points to an 8Ki-byte map, with 32 bytes per
>  character.
>  Only the first
>  .I N
> diff --git a/man2/iopl.2 b/man2/iopl.2
> index abf1bef675fd..c967296157b7 100644
> --- a/man2/iopl.2
> +++ b/man2/iopl.2
> @@ -34,7 +34,7 @@ Permissions are inherited from parents to children.
>  This call is deprecated, is significantly slower than
>  .BR ioperm (2),
>  and is only provided for older X servers which require
> -access to all 65536 I/O ports.
> +access to all 64Ki I/O ports.
>  It is mostly for the i386 architecture.
>  On many other architectures it does not exist or will always
>  return an error.
> diff --git a/man2/madvise.2 b/man2/madvise.2
> index 9b4652a635d3..e05e9c5de4a7 100644
> --- a/man2/madvise.2
> +++ b/man2/madvise.2
> @@ -329,8 +329,8 @@ naturally aligned to the huge page size (see
>  This feature is primarily aimed at applications that use large mappings of
>  data and access large regions of that memory at a time (e.g., virtualization
>  systems such as QEMU).
> -It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
> -1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
> +It can very easily waste memory (e.g., a 2\ MiB mapping that only ever accesses
> +1 byte will result in 2\ MiB of wired memory instead of one 4\ KiB page).
>  See the Linux kernel source file
>  .I Documentation/admin\-guide/mm/transhuge.rst
>  for more details.
> diff --git a/man2/mmap2.2 b/man2/mmap2.2
> index 1fd5732ad41b..f975c1388a77 100644
> --- a/man2/mmap2.2
> +++ b/man2/mmap2.2
> @@ -32,7 +32,7 @@ The
>  system call provides the same interface as
>  .BR mmap (2),
>  except that the final argument specifies the offset into the
> -file in 4096-byte units (instead of bytes, as is done by
> +file in 4Ki-byte units (instead of bytes, as is done by
>  .BR mmap (2)).
>  This enables applications that use a 32-bit
>  .I off_t
> @@ -50,8 +50,8 @@ is set to indicate the error.
>  Problem with getting the data from user space.
>  .TP
>  .B EINVAL
> -(Various platforms where the page size is not 4096 bytes.)
> -.I "offset\ *\ 4096"
> +(Various platforms where the page size is not 4Ki bytes.)
> +.I "offset\ *\ 4Ki"
>  is not a multiple of the system page size.
>  .PP
>  .BR mmap2 ()
> @@ -74,7 +74,7 @@ This system call does not exist on x86-64.
>  .PP
>  On ia64, the unit for
>  .I offset
> -is actually the system page size, rather than 4096 bytes.
> +is actually the system page size, rather than 4Ki bytes.
>  .\" ia64 can have page sizes ranging from 4 kB to 64 kB.
>  .\" On cris, it looks like the unit might also be the page size,
>  .\" which is 8192 bytes. -- mtk, June 2007
> diff --git a/man2/request_key.2 b/man2/request_key.2
> index e78321e3c23f..dacc5282f3d8 100644
> --- a/man2/request_key.2
> +++ b/man2/request_key.2
> @@ -399,7 +399,7 @@ The size of the string (including the terminating null byte) specified in
>  .I type
>  or
>  .I description
> -exceeded the limit (32 bytes and 4096 bytes respectively).
> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>  .TP
>  .B EINVAL
>  The size of the string (including the terminating null byte) specified in
> diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2
> index 86a93539137d..9e7a26293e73 100644
> --- a/man2/sched_setaffinity.2
> +++ b/man2/sched_setaffinity.2
> @@ -243,10 +243,10 @@ impose no restriction on the size of the CPU mask.
>  However, the
>  .I cpu_set_t
>  data type used by glibc has a fixed size of 128 bytes,
> -meaning that the maximum CPU number that can be represented is 1023.
> +meaning that the maximum CPU number that can be represented is 1\[aq]023.
>  .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
>  .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
> -If the kernel CPU affinity mask is larger than 1024,
> +If the kernel CPU affinity mask is larger than 1Ki,
>  then calls of the form:
>  .PP
>  .in +4n
> diff --git a/man2/seccomp.2 b/man2/seccomp.2
> index 32706397f03e..0bb8caa75698 100644
> --- a/man2/seccomp.2
> +++ b/man2/seccomp.2
> @@ -836,7 +836,7 @@ but the filter program pointed to by
>  .I args
>  was not valid or the length of the filter program was zero or exceeded
>  .B BPF_MAXINSNS
> -(4096) instructions.
> +(4Ki) instructions.
>  .TP
>  .B ENOMEM
>  Out of memory.
> @@ -846,7 +846,7 @@ Out of memory.
>  The total length of all filter programs attached
>  to the calling thread would exceed
>  .B MAX_INSNS_PER_PATH
> -(32768) instructions.
> +(32Ki) instructions.
>  Note that for the purposes of calculating this limit,
>  each already existing filter program incurs an
>  overhead penalty of 4 instructions.
> diff --git a/man2/semop.2 b/man2/semop.2
> index 7a1416a26894..a0027e0706c5 100644
> --- a/man2/semop.2
> +++ b/man2/semop.2
> @@ -434,7 +434,7 @@ On Linux, this limit can be read and modified via the third field of
>  .IR /proc/sys/kernel/sem .
>  .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
>  .IR Note :
> -this limit should not be raised above 1000,
> +this limit should not be raised above 1\[aq]000,
>  .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
>  because of the risk of that
>  .BR semop ()
> @@ -445,7 +445,7 @@ array.
>  .B SEMVMX
>  Maximum allowable value for
>  .IR semval :
> -implementation dependent (32767).
> +implementation dependent (32Ki-1).
>  .PP
>  The implementation has no intrinsic limits for
>  the adjust on exit maximum value
> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
> index 4e5475c45a09..3f355382ebf6 100644
> --- a/man2/sendmmsg.2
> +++ b/man2/sendmmsg.2
> @@ -139,7 +139,7 @@ The value specified in
>  .I vlen
>  is capped to
>  .B UIO_MAXIOV
> -(1024).
> +(1Ki).
>  .\" commit 98382f419f32d2c12d021943b87dea555677144b
>  .\"     net: Cap number of elements for sendmmsg
>  .\"
> diff --git a/man2/shmget.2 b/man2/shmget.2
> index c4d8df8ed619..5421fd4bf3e9 100644
> --- a/man2/shmget.2
> +++ b/man2/shmget.2
> @@ -360,7 +360,7 @@ 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
>  usable segment:
>  for example, on i386 the largest segments that can be mapped have a
> -size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
> +size of around 2.8\ GB, and on x86-64 the limit is around 127\ TB.
>  .TP
>  .B SHMMIN
>  Minimum size in bytes for a shared memory segment: implementation
> @@ -371,7 +371,7 @@ is the effective minimum size).
>  .B SHMMNI
>  System-wide limit on the number of shared memory segments.
>  In Linux 2.2, the default value for this limit was 128;
> -since Linux 2.4, the default value is 4096.
> +since Linux 2.4, the default value is 4Ki.
>  .IP
>  On Linux, this limit can be read and modified via
>  .IR /proc/sys/kernel/shmmni .
> diff --git a/man2/syslog.2 b/man2/syslog.2
> index 09c086f181e3..7d76e8cd9658 100644
> --- a/man2/syslog.2
> +++ b/man2/syslog.2
> @@ -54,9 +54,9 @@ in which messages given as arguments to the kernel function
>  are stored (regardless of their log level).
>  In early kernels,
>  .B LOG_BUF_LEN
> -had the value 4096;
> -from Linux 1.3.54, it was 8192;
> -from Linux 2.1.113, it was 16384;
> +had the value 4Ki;
> +from Linux 1.3.54, it was 8Ki;
> +from Linux 2.1.113, it was 16Ki;
>  since Linux 2.4.23/2.6, the value is a kernel configuration option
>  .RB ( CONFIG_LOG_BUF_SHIFT ,
>  default value dependent on the architecture).
> diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
> index 01ac37b3584f..08ede47361ae 100644
> --- a/man2/vmsplice.2
> +++ b/man2/vmsplice.2
> @@ -149,7 +149,7 @@ as defined in
>  .IR <limits.h> .
>  Currently,
>  .\" UIO_MAXIOV in kernel source
> -this limit is 1024.
> +this limit is 1Ki.
>  .PP
>  .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
>  .BR vmsplice ()
> --
> 2.39.0
>

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates
  2023-02-15 20:17 ` [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates Brian Inglis
  2023-02-15 21:08   ` Alejandro Colomar
@ 2023-02-16 21:11   ` Stefan Puiu
  2023-02-16 23:04     ` Alejandro Colomar
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Puiu @ 2023-02-16 21:11 UTC (permalink / raw)
  To: Brian Inglis; +Cc: Linux Man Pages, Alejandro Colomar

Hi Brian,

On Wed, Feb 15, 2023 at 10:28 PM Brian Inglis <Brian.Inglis@shaw.ca> wrote:
>
> ---
>  man2/access.2           | 2 +-
>  man2/brk.2              | 4 ++--
>  man2/chdir.2            | 2 +-
>  man2/chown.2            | 4 ++--
>  man2/clock_getres.2     | 2 +-
>  man2/clock_nanosleep.2  | 2 +-
>  man2/fsync.2            | 4 ++--
>  man2/gethostname.2      | 2 +-
>  man2/getpagesize.2      | 4 ++--
>  man2/getsid.2           | 2 +-
>  man2/link.2             | 2 +-
>  man2/mkdir.2            | 4 ++--
>  man2/nanosleep.2        | 2 +-
>  man2/open.2             | 4 ++--
>  man2/posix_fadvise.2    | 2 +-
>  man2/pread.2            | 2 +-
>  man2/readlink.2         | 4 ++--
>  man2/rename.2           | 2 +-
>  man2/seteuid.2          | 2 +-
>  man2/setpgid.2          | 2 +-
>  man2/sigaltstack.2      | 2 +-
>  man2/sigwaitinfo.2      | 2 +-
>  man2/stat.2             | 4 ++--
>  man2/symlink.2          | 4 ++--
>  man2/timer_create.2     | 2 +-
>  man2/timer_delete.2     | 2 +-
>  man2/timer_getoverrun.2 | 2 +-
>  man2/truncate.2         | 4 ++--
>  man2/unlink.2           | 2 +-
>  man2/vfork.2            | 2 +-
>  man2/wait.2             | 4 ++--
>  man2/wait4.2            | 2 +-
>  32 files changed, 43 insertions(+), 43 deletions(-)
>
> diff --git a/man2/access.2 b/man2/access.2
> index d3deeecba0c7..4c93a132b209 100644
> --- a/man2/access.2
> +++ b/man2/access.2
> @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR faccessat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L

Not sure how \[aq] renders, but if people want to copy / paste some of
these snippets (for use in their code, or for searching), wouldn't
they need to then remove the separator? I think that can cause
confusion, which you probably don't want documentation to do.

Again, just my 2 cents,
Stefan.

>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/brk.2 b/man2/brk.2
> index 31c167c56955..298fd006d742 100644
> --- a/man2/brk.2
> +++ b/man2/brk.2
> @@ -32,13 +32,13 @@ Feature Test Macro Requirements for glibc (see
>      Since glibc 2.19:
>          _DEFAULT_SOURCE
>              || ((_XOPEN_SOURCE >= 500) &&
> -                ! (_POSIX_C_SOURCE >= 200112L))
> +                ! (_POSIX_C_SOURCE >= 2001\[aq]12L))
>  .\"    (_XOPEN_SOURCE >= 500 ||
>  .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
>      From glibc 2.12 to glibc 2.19:
>          _BSD_SOURCE || _SVID_SOURCE
>              || ((_XOPEN_SOURCE >= 500) &&
> -                ! (_POSIX_C_SOURCE >= 200112L))
> +                ! (_POSIX_C_SOURCE >= 2001\[aq]12L))
>  .\"    (_XOPEN_SOURCE >= 500 ||
>  .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
>      Before glibc 2.12:
> diff --git a/man2/chdir.2 b/man2/chdir.2
> index 0bbff4e87842..cca6a568871c 100644
> --- a/man2/chdir.2
> +++ b/man2/chdir.2
> @@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || /* glibc up to and including 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/chown.2 b/man2/chown.2
> index d66b66f544cb..5c87dfa6aa9b 100644
> --- a/man2/chown.2
> +++ b/man2/chown.2
> @@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR fchown (),
>  .BR lchown ():
>  .nf
> -    /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +    /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
>          || /* glibc <= 2.19: */ _BSD_SOURCE
> @@ -53,7 +53,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR fchownat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index 8d90baaaabd6..b6a3bedbd944 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -39,7 +39,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR clock_gettime (),
>  .BR clock_settime ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  The function
> diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
> index 5da8d15699c2..fe78d6bedb11 100644
> --- a/man2/clock_nanosleep.2
> +++ b/man2/clock_nanosleep.2
> @@ -30,7 +30,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR clock_nanosleep ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L
>  .fi
>  .SH DESCRIPTION
>  Like
> diff --git a/man2/fsync.2 b/man2/fsync.2
> index 9dc99a15a20e..78fc6013b773 100644
> --- a/man2/fsync.2
> +++ b/man2/fsync.2
> @@ -41,12 +41,12 @@ Feature Test Macro Requirements for glibc (see
>          No feature test macros need be defined
>      glibc up to and including 2.15:
>          _BSD_SOURCE || _XOPEN_SOURCE
> -            || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
> +            || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 2001\[aq]12L
>  .fi
>  .PP
>  .BR fdatasync ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
> +    _POSIX_C_SOURCE >= 1993\[aq]09L || _XOPEN_SOURCE >= 500
>  .fi
>  .SH DESCRIPTION
>  .BR fsync ()
> diff --git a/man2/gethostname.2 b/man2/gethostname.2
> index bc74610c9c5d..e6d3b5837c2c 100644
> --- a/man2/gethostname.2
> +++ b/man2/gethostname.2
> @@ -30,7 +30,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR gethostname ():
>  .nf
> -    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
> +    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc 2.19 and earlier */ _BSD_SOURCE
>  .\" The above is something of a simplification
>  .\" also before glibc 2.3 there was a bit churn
> diff --git a/man2/getpagesize.2 b/man2/getpagesize.2
> index 39af55619be4..356bb42f08f1 100644
> --- a/man2/getpagesize.2
> +++ b/man2/getpagesize.2
> @@ -23,9 +23,9 @@ Feature Test Macro Requirements for glibc (see
>  .BR getpagesize ():
>  .nf
>      Since glibc 2.20:
> -        _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 200112L)
> +        _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 2001\[aq]12L)
>      glibc 2.12 to glibc 2.19:
> -        _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 200112L)
> +        _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 2001\[aq]12L)
>      Before glibc 2.12:
>          _BSD_SOURCE || _XOPEN_SOURCE >= 500
>  .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> diff --git a/man2/getsid.2 b/man2/getsid.2
> index 3afccbd9d6bf..355c4df2601a 100644
> --- a/man2/getsid.2
> +++ b/man2/getsid.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR getsid ()
> diff --git a/man2/link.2 b/man2/link.2
> index 60b739eba152..49526bfe36d4 100644
> --- a/man2/link.2
> +++ b/man2/link.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR linkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/mkdir.2 b/man2/mkdir.2
> index b1339a49a513..68539ab7e1ab 100644
> --- a/man2/mkdir.2
> +++ b/man2/mkdir.2
> @@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR mkdirat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> @@ -49,7 +49,7 @@ It is modified by the process's
>  .I umask
>  in the usual way: in the absence of a default ACL, the mode of the
>  created directory is
> -.RI ( mode " & \[ti]" umask " & 0777)."
> +.RI ( mode " & \[ti]" umask " & 0\[aq]777)."
>  Whether other
>  .I mode
>  bits are honored for the created directory depends on the operating system.
> diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
> index 12e0cee84b85..4732ef705fe0 100644
> --- a/man2/nanosleep.2
> +++ b/man2/nanosleep.2
> @@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR nanosleep ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR nanosleep ()
> diff --git a/man2/open.2 b/man2/open.2
> index aefcae1e601e..1bb3640014e6 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -60,7 +60,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR openat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> @@ -1772,7 +1772,7 @@ In Linux 2.4,
>  most filesystems based on block devices require that
>  the file offset and the length and memory address of all I/O segments
>  be multiples of the filesystem block size
> -(typically 4096 bytes).
> +(typically 4Ki bytes).
>  In Linux 2.6.0,
>  this was relaxed to the logical block size of the block device
>  (typically 512 bytes).
> diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2
> index 57c65c810791..cb9b6ea24dd8 100644
> --- a/man2/posix_fadvise.2
> +++ b/man2/posix_fadvise.2
> @@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR posix_fadvise ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L
>  .fi
>  .SH DESCRIPTION
>  Programs can use
> diff --git a/man2/pread.2 b/man2/pread.2
> index 9a9763323518..7a8fce5764d5 100644
> --- a/man2/pread.2
> +++ b/man2/pread.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR pwrite ():
>  .nf
>      _XOPEN_SOURCE >= 500
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR pread ()
> diff --git a/man2/readlink.2 b/man2/readlink.2
> index de158da7e355..e23564450af2 100644
> --- a/man2/readlink.2
> +++ b/man2/readlink.2
> @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR readlink ():
>  .nf
> -    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
> +    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
> @@ -48,7 +48,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR readlinkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/rename.2 b/man2/rename.2
> index 08e7958f3220..7e4b33cdb9d8 100644
> --- a/man2/rename.2
> +++ b/man2/rename.2
> @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>  .BR renameat ():
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .PP
> diff --git a/man2/seteuid.2 b/man2/seteuid.2
> index 14b23b3f40b0..4dd30ecfc012 100644
> --- a/man2/seteuid.2
> +++ b/man2/seteuid.2
> @@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR seteuid (),
>  .BR setegid ():
>  .nf
> -    _POSIX_C_SOURCE >= 200112L
> +    _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/setpgid.2 b/man2/setpgid.2
> index 52c5bd5fcc10..4cf35c3a0c03 100644
> --- a/man2/setpgid.2
> +++ b/man2/setpgid.2
> @@ -46,7 +46,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>  .fi
>  .PP
>  .BR setpgrp "() (POSIX.1):"
> diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2
> index cdc8a8e39f70..45d6db43a0c8 100644
> --- a/man2/sigaltstack.2
> +++ b/man2/sigaltstack.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2
> index 42209c1806e9..791dc418d6c4 100644
> --- a/man2/sigwaitinfo.2
> +++ b/man2/sigwaitinfo.2
> @@ -28,7 +28,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR sigwaitinfo (),
>  .BR sigtimedwait ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR sigwaitinfo ()
> diff --git a/man2/stat.2 b/man2/stat.2
> index 8479befccd8d..4bd67667b5c2 100644
> --- a/man2/stat.2
> +++ b/man2/stat.2
> @@ -49,14 +49,14 @@ Feature Test Macro Requirements for glibc (see
>      /* Since glibc 2.20 */ _DEFAULT_SOURCE
>          || _XOPEN_SOURCE >= 500
>  .\"   _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
> +        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc 2.19 and earlier */ _BSD_SOURCE
>  .fi
>  .PP
>  .BR fstatat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/symlink.2 b/man2/symlink.2
> index 13b2ed1ccd5b..34078fabfe01 100644
> --- a/man2/symlink.2
> +++ b/man2/symlink.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR symlink ():
>  .nf
> -    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
> +    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2001\[aq]12L
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
> @@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR symlinkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/timer_create.2 b/man2/timer_create.2
> index 6d49da17f89a..0f26075e457c 100644
> --- a/man2/timer_create.2
> +++ b/man2/timer_create.2
> @@ -26,7 +26,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR timer_create ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR timer_create ()
> diff --git a/man2/timer_delete.2 b/man2/timer_delete.2
> index c489d9ec0dff..e0397af5bf4f 100644
> --- a/man2/timer_delete.2
> +++ b/man2/timer_delete.2
> @@ -23,7 +23,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR timer_delete ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR timer_delete ()
> diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2
> index 3591e5de5df5..690c19937799 100644
> --- a/man2/timer_getoverrun.2
> +++ b/man2/timer_getoverrun.2
> @@ -23,7 +23,7 @@ Feature Test Macro Requirements for glibc (see
>  .PP
>  .BR timer_getoverrun ():
>  .nf
> -    _POSIX_C_SOURCE >= 199309L
> +    _POSIX_C_SOURCE >= 1993\[aq]09L
>  .fi
>  .SH DESCRIPTION
>  .BR timer_getoverrun ()
> diff --git a/man2/truncate.2 b/man2/truncate.2
> index 8a00ec3ffba2..bb57666e64b1 100644
> --- a/man2/truncate.2
> +++ b/man2/truncate.2
> @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .PP
> @@ -43,7 +43,7 @@ Feature Test Macro Requirements for glibc (see
>  .nf
>      _XOPEN_SOURCE >= 500
>  .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
> -        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L
> +        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 2001\[aq]12L
>          || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/unlink.2 b/man2/unlink.2
> index 954a19f1534a..4c296e73086b 100644
> --- a/man2/unlink.2
> +++ b/man2/unlink.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR unlinkat ():
>  .nf
>      Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> +        _POSIX_C_SOURCE >= 2008\[aq]09L
>      Before glibc 2.10:
>          _ATFILE_SOURCE
>  .fi
> diff --git a/man2/vfork.2 b/man2/vfork.2
> index 5e6b8226c301..e3c82f1d6bc4 100644
> --- a/man2/vfork.2
> +++ b/man2/vfork.2
> @@ -27,7 +27,7 @@ Feature Test Macro Requirements for glibc (see
>  .BR vfork ():
>  .nf
>      Since glibc 2.12:
> -        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
> +        (_XOPEN_SOURCE >= 500)         (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) ! (_POSIX_C_SOURCE >= 2008\[aq]09L)
>              || /* Since glibc 2.19: */ _DEFAULT_SOURCE
>              || /* glibc <= 2.19: */ _BSD_SOURCE
>      Before glibc 2.12:
> diff --git a/man2/wait.2 b/man2/wait.2
> index e2dcd59bda09..ad031d40ca07 100644
> --- a/man2/wait.2
> +++ b/man2/wait.2
> @@ -53,11 +53,11 @@ Feature Test Macro Requirements for glibc (see
>  .BR waitid ():
>  .nf
>      Since glibc 2.26:
> -        _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
> +        _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 2008\[aq]09L
>  .\"    (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
>      glibc 2.25 and earlier:
>          _XOPEN_SOURCE
> -            || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
> +            || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 2008\[aq]09L
>              || /* glibc <= 2.19: */ _BSD_SOURCE
>  .fi
>  .SH DESCRIPTION
> diff --git a/man2/wait4.2 b/man2/wait4.2
> index a5b38108d318..703df0797f80 100644
> --- a/man2/wait4.2
> +++ b/man2/wait4.2
> @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see
>      Since glibc 2.26:
>          _DEFAULT_SOURCE
>              || (_XOPEN_SOURCE >= 500 &&
> -                ! (_POSIX_C_SOURCE >= 200112L
> +                ! (_POSIX_C_SOURCE >= 2001\[aq]12L
>                     || _XOPEN_SOURCE >= 600))
>      From glibc 2.19 to glibc 2.25:
>          _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500
> --
> 2.39.0
>

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-15 20:17 ` [PATCH v3 1/6] man2/: use IEC " Brian Inglis
  2023-02-15 21:05   ` Alejandro Colomar
  2023-02-16 21:06   ` Stefan Puiu
@ 2023-02-16 21:40   ` Jakub Wilk
  2 siblings, 0 replies; 39+ messages in thread
From: Jakub Wilk @ 2023-02-16 21:40 UTC (permalink / raw)
  To: Brian Inglis; +Cc: linux-man, Alejandro Colomar

I'm afaird most of this patch makes the text less readable.

Moreover:

>-meaning that the maximum CPU number that can be represented is 1023.
>+meaning that the maximum CPU number that can be represented is 1\[aq]023.

This does not match the patch subject.

>-this limit should not be raised above 1000,
>+this limit should not be raised above 1\[aq]000,

Ditto.

-- 
Jakub Wilk

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-16 21:06   ` Stefan Puiu
@ 2023-02-16 23:01     ` Alejandro Colomar
  2023-02-16 23:40       ` Brian Inglis
  2023-02-17 14:05       ` Stefan Puiu
  0 siblings, 2 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-16 23:01 UTC (permalink / raw)
  To: Stefan Puiu, Brian Inglis; +Cc: Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 12465 bytes --]

Hi Stefan and Brian,

On 2/16/23 22:06, Stefan Puiu wrote:
> Hi Brian,
> 
> On Wed, Feb 15, 2023 at 10:21 PM Brian Inglis <Brian.Inglis@shaw.ca> wrote:
>>
>> ---
>>  man2/add_key.2           | 2 +-
>>  man2/epoll_wait.2        | 2 +-
>>  man2/fcntl.2             | 2 +-
>>  man2/getgroups.2         | 2 +-
>>  man2/ioctl_console.2     | 4 ++--
>>  man2/iopl.2              | 2 +-
>>  man2/madvise.2           | 4 ++--
>>  man2/mmap2.2             | 8 ++++----
>>  man2/request_key.2       | 2 +-
>>  man2/sched_setaffinity.2 | 4 ++--
>>  man2/seccomp.2           | 4 ++--
>>  man2/semop.2             | 4 ++--
>>  man2/sendmmsg.2          | 2 +-
>>  man2/shmget.2            | 4 ++--
>>  man2/syslog.2            | 6 +++---
>>  man2/vmsplice.2          | 2 +-
>>  16 files changed, 27 insertions(+), 27 deletions(-)
>>
>> diff --git a/man2/add_key.2 b/man2/add_key.2
>> index 56fc6d198d21..215de20baeae 100644
>> --- a/man2/add_key.2
>> +++ b/man2/add_key.2
>> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
>>  .I type
>>  or
>>  .I description
>> -exceeded the limit (32 bytes and 4096 bytes respectively).
>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
> 
> For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
> anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?

In this case, we should rather use 4\ KiB, which is standard.

In general, let's divide the patches so that we can apply those that
use standard syntax more easily, and then discuss more those that
are more informal.

> 
>>  .TP
>>  .B EINVAL
>>  The payload data was invalid.
>> diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
>> index 1620cff9dfcc..4863ae4a43fa 100644
>> --- a/man2/epoll_wait.2
>> +++ b/man2/epoll_wait.2
>> @@ -283,7 +283,7 @@ Thus, for example, on a system where
>>  .I sizeof(long)
>>  is 4 and the kernel
>>  .I HZ
>> -value is 1000,
>> +value is 1k,
> 
> I still prefer the old version, my impression is that 1k and friends
> are used in informal contexts. Of course, it could be only my
> impression.

Thanks for sharing your impression.  I'll take it into consideration.

Cheers,

Alex

> 
> Just my 2 cents,
> Stefan.
> 
>>  this means that timeouts greater than 35.79 minutes are treated as infinity.
>>  .SH SEE ALSO
>>  .BR epoll_create (2),
>> diff --git a/man2/fcntl.2 b/man2/fcntl.2
>> index 3ec52dc4dc03..630fc55888bc 100644
>> --- a/man2/fcntl.2
>> +++ b/man2/fcntl.2
>> @@ -2004,7 +2004,7 @@ A limitation of the Linux system call conventions on some
>>  architectures (notably i386) means that if a (negative)
>>  process group ID to be returned by
>>  .B F_GETOWN
>> -falls in the range \-1 to \-4095, then the return value is wrongly
>> +falls in the range \-1 to \-4Ki-1, then the return value is wrongly
>>  interpreted by glibc as an error in the system call;
>>  .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
>>  that is, the return value of
>> diff --git a/man2/getgroups.2 b/man2/getgroups.2
>> index 36300bf61b6a..f01af687ccbd 100644
>> --- a/man2/getgroups.2
>> +++ b/man2/getgroups.2
>> @@ -119,7 +119,7 @@ can additionally fail with the following errors:
>>  .I size
>>  is greater than
>>  .B NGROUPS_MAX
>> -(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
>> +(32 before Linux 2.6.4; 64Ki since Linux 2.6.4).
>>  .TP
>>  .B ENOMEM
>>  Out of memory.
>> diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
>> index 89f794c1956c..477e6fd1a7e1 100644
>> --- a/man2/ioctl_console.2
>> +++ b/man2/ioctl_console.2
>> @@ -171,7 +171,7 @@ bright cyan, and white.
>>  .B GIO_FONT
>>  Gets 256-character screen font in expanded form.
>>  .I argp
>> -points to an 8192-byte array.
>> +points to an 8Ki-byte array.
>>  Fails with error code
>>  .B EINVAL
>>  if the
>> @@ -211,7 +211,7 @@ Sets 256-character screen font.
>>  Load font into the EGA/VGA character
>>  generator.
>>  .I argp
>> -points to an 8192-byte map, with 32 bytes per
>> +points to an 8Ki-byte map, with 32 bytes per
>>  character.
>>  Only the first
>>  .I N
>> diff --git a/man2/iopl.2 b/man2/iopl.2
>> index abf1bef675fd..c967296157b7 100644
>> --- a/man2/iopl.2
>> +++ b/man2/iopl.2
>> @@ -34,7 +34,7 @@ Permissions are inherited from parents to children.
>>  This call is deprecated, is significantly slower than
>>  .BR ioperm (2),
>>  and is only provided for older X servers which require
>> -access to all 65536 I/O ports.
>> +access to all 64Ki I/O ports.
>>  It is mostly for the i386 architecture.
>>  On many other architectures it does not exist or will always
>>  return an error.
>> diff --git a/man2/madvise.2 b/man2/madvise.2
>> index 9b4652a635d3..e05e9c5de4a7 100644
>> --- a/man2/madvise.2
>> +++ b/man2/madvise.2
>> @@ -329,8 +329,8 @@ naturally aligned to the huge page size (see
>>  This feature is primarily aimed at applications that use large mappings of
>>  data and access large regions of that memory at a time (e.g., virtualization
>>  systems such as QEMU).
>> -It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
>> -1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
>> +It can very easily waste memory (e.g., a 2\ MiB mapping that only ever accesses
>> +1 byte will result in 2\ MiB of wired memory instead of one 4\ KiB page).
>>  See the Linux kernel source file
>>  .I Documentation/admin\-guide/mm/transhuge.rst
>>  for more details.
>> diff --git a/man2/mmap2.2 b/man2/mmap2.2
>> index 1fd5732ad41b..f975c1388a77 100644
>> --- a/man2/mmap2.2
>> +++ b/man2/mmap2.2
>> @@ -32,7 +32,7 @@ The
>>  system call provides the same interface as
>>  .BR mmap (2),
>>  except that the final argument specifies the offset into the
>> -file in 4096-byte units (instead of bytes, as is done by
>> +file in 4Ki-byte units (instead of bytes, as is done by
>>  .BR mmap (2)).
>>  This enables applications that use a 32-bit
>>  .I off_t
>> @@ -50,8 +50,8 @@ is set to indicate the error.
>>  Problem with getting the data from user space.
>>  .TP
>>  .B EINVAL
>> -(Various platforms where the page size is not 4096 bytes.)
>> -.I "offset\ *\ 4096"
>> +(Various platforms where the page size is not 4Ki bytes.)
>> +.I "offset\ *\ 4Ki"
>>  is not a multiple of the system page size.
>>  .PP
>>  .BR mmap2 ()
>> @@ -74,7 +74,7 @@ This system call does not exist on x86-64.
>>  .PP
>>  On ia64, the unit for
>>  .I offset
>> -is actually the system page size, rather than 4096 bytes.
>> +is actually the system page size, rather than 4Ki bytes.
>>  .\" ia64 can have page sizes ranging from 4 kB to 64 kB.
>>  .\" On cris, it looks like the unit might also be the page size,
>>  .\" which is 8192 bytes. -- mtk, June 2007
>> diff --git a/man2/request_key.2 b/man2/request_key.2
>> index e78321e3c23f..dacc5282f3d8 100644
>> --- a/man2/request_key.2
>> +++ b/man2/request_key.2
>> @@ -399,7 +399,7 @@ The size of the string (including the terminating null byte) specified in
>>  .I type
>>  or
>>  .I description
>> -exceeded the limit (32 bytes and 4096 bytes respectively).
>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>>  .TP
>>  .B EINVAL
>>  The size of the string (including the terminating null byte) specified in
>> diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2
>> index 86a93539137d..9e7a26293e73 100644
>> --- a/man2/sched_setaffinity.2
>> +++ b/man2/sched_setaffinity.2
>> @@ -243,10 +243,10 @@ impose no restriction on the size of the CPU mask.
>>  However, the
>>  .I cpu_set_t
>>  data type used by glibc has a fixed size of 128 bytes,
>> -meaning that the maximum CPU number that can be represented is 1023.
>> +meaning that the maximum CPU number that can be represented is 1\[aq]023.
>>  .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
>>  .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
>> -If the kernel CPU affinity mask is larger than 1024,
>> +If the kernel CPU affinity mask is larger than 1Ki,
>>  then calls of the form:
>>  .PP
>>  .in +4n
>> diff --git a/man2/seccomp.2 b/man2/seccomp.2
>> index 32706397f03e..0bb8caa75698 100644
>> --- a/man2/seccomp.2
>> +++ b/man2/seccomp.2
>> @@ -836,7 +836,7 @@ but the filter program pointed to by
>>  .I args
>>  was not valid or the length of the filter program was zero or exceeded
>>  .B BPF_MAXINSNS
>> -(4096) instructions.
>> +(4Ki) instructions.
>>  .TP
>>  .B ENOMEM
>>  Out of memory.
>> @@ -846,7 +846,7 @@ Out of memory.
>>  The total length of all filter programs attached
>>  to the calling thread would exceed
>>  .B MAX_INSNS_PER_PATH
>> -(32768) instructions.
>> +(32Ki) instructions.
>>  Note that for the purposes of calculating this limit,
>>  each already existing filter program incurs an
>>  overhead penalty of 4 instructions.
>> diff --git a/man2/semop.2 b/man2/semop.2
>> index 7a1416a26894..a0027e0706c5 100644
>> --- a/man2/semop.2
>> +++ b/man2/semop.2
>> @@ -434,7 +434,7 @@ On Linux, this limit can be read and modified via the third field of
>>  .IR /proc/sys/kernel/sem .
>>  .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
>>  .IR Note :
>> -this limit should not be raised above 1000,
>> +this limit should not be raised above 1\[aq]000,
>>  .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
>>  because of the risk of that
>>  .BR semop ()
>> @@ -445,7 +445,7 @@ array.
>>  .B SEMVMX
>>  Maximum allowable value for
>>  .IR semval :
>> -implementation dependent (32767).
>> +implementation dependent (32Ki-1).
>>  .PP
>>  The implementation has no intrinsic limits for
>>  the adjust on exit maximum value
>> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
>> index 4e5475c45a09..3f355382ebf6 100644
>> --- a/man2/sendmmsg.2
>> +++ b/man2/sendmmsg.2
>> @@ -139,7 +139,7 @@ The value specified in
>>  .I vlen
>>  is capped to
>>  .B UIO_MAXIOV
>> -(1024).
>> +(1Ki).
>>  .\" commit 98382f419f32d2c12d021943b87dea555677144b
>>  .\"     net: Cap number of elements for sendmmsg
>>  .\"
>> diff --git a/man2/shmget.2 b/man2/shmget.2
>> index c4d8df8ed619..5421fd4bf3e9 100644
>> --- a/man2/shmget.2
>> +++ b/man2/shmget.2
>> @@ -360,7 +360,7 @@ 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
>>  usable segment:
>>  for example, on i386 the largest segments that can be mapped have a
>> -size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
>> +size of around 2.8\ GB, and on x86-64 the limit is around 127\ TB.
>>  .TP
>>  .B SHMMIN
>>  Minimum size in bytes for a shared memory segment: implementation
>> @@ -371,7 +371,7 @@ is the effective minimum size).
>>  .B SHMMNI
>>  System-wide limit on the number of shared memory segments.
>>  In Linux 2.2, the default value for this limit was 128;
>> -since Linux 2.4, the default value is 4096.
>> +since Linux 2.4, the default value is 4Ki.
>>  .IP
>>  On Linux, this limit can be read and modified via
>>  .IR /proc/sys/kernel/shmmni .
>> diff --git a/man2/syslog.2 b/man2/syslog.2
>> index 09c086f181e3..7d76e8cd9658 100644
>> --- a/man2/syslog.2
>> +++ b/man2/syslog.2
>> @@ -54,9 +54,9 @@ in which messages given as arguments to the kernel function
>>  are stored (regardless of their log level).
>>  In early kernels,
>>  .B LOG_BUF_LEN
>> -had the value 4096;
>> -from Linux 1.3.54, it was 8192;
>> -from Linux 2.1.113, it was 16384;
>> +had the value 4Ki;
>> +from Linux 1.3.54, it was 8Ki;
>> +from Linux 2.1.113, it was 16Ki;
>>  since Linux 2.4.23/2.6, the value is a kernel configuration option
>>  .RB ( CONFIG_LOG_BUF_SHIFT ,
>>  default value dependent on the architecture).
>> diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
>> index 01ac37b3584f..08ede47361ae 100644
>> --- a/man2/vmsplice.2
>> +++ b/man2/vmsplice.2
>> @@ -149,7 +149,7 @@ as defined in
>>  .IR <limits.h> .
>>  Currently,
>>  .\" UIO_MAXIOV in kernel source
>> -this limit is 1024.
>> +this limit is 1Ki.
>>  .PP
>>  .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
>>  .BR vmsplice ()
>> --
>> 2.39.0
>>

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates
  2023-02-16 21:11   ` Stefan Puiu
@ 2023-02-16 23:04     ` Alejandro Colomar
  2023-02-17 14:16       ` Stefan Puiu
  0 siblings, 1 reply; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-16 23:04 UTC (permalink / raw)
  To: Stefan Puiu, Brian Inglis; +Cc: Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 1268 bytes --]

Hi Stefan,

On 2/16/23 22:11, Stefan Puiu wrote:
> Hi Brian,

[...]

>> diff --git a/man2/access.2 b/man2/access.2
>> index d3deeecba0c7..4c93a132b209 100644
>> --- a/man2/access.2
>> +++ b/man2/access.2
>> @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see
>>  .BR faccessat ():
>>  .nf
>>      Since glibc 2.10:
>> -        _POSIX_C_SOURCE >= 200809L
>> +        _POSIX_C_SOURCE >= 2008\[aq]09L
> 
> Not sure how \[aq] renders,

\[aq] is equivalent to \(aq, which renders as ', the single quote character.

> but if people want to copy / paste some of
> these snippets (for use in their code, or for searching), wouldn't
> they need to then remove the separator?

It depends on your compiler version and language version.
ISO C23 will add support for this.  What we could do is prepare the patches,
and leave them in a branch until C23 is made official.

Right now, you can already get recent enough versions of GCC to
accept that code, if you use -std=c2x.

> I think that can cause
> confusion, which you probably don't want documentation to do.> 
> Again, just my 2 cents,
> Stefan.
> 

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-16 23:01     ` Alejandro Colomar
@ 2023-02-16 23:40       ` Brian Inglis
  2023-02-16 23:51         ` Alejandro Colomar
  2023-02-17 14:05       ` Stefan Puiu
  1 sibling, 1 reply; 39+ messages in thread
From: Brian Inglis @ 2023-02-16 23:40 UTC (permalink / raw)
  To: Linux Man Pages; +Cc: Alejandro Colomar, Stefan Puiu

Hi Alex,

Should we leave some of these POSIX doc strings and short numbers as they are?
I have been careful to use digit separators in POSIX feature docs only not code.

I see *those* as less formal, digit separators and ISO decimal multipliers as 
more formal, and IEC binary multipliers more accurate and informative than 
decimal digits where used.

I think hex values are 50/50 depending on counts of zero and non-zero digits and 
context; IEC binary multipliers are more informative for amounts or sizes in 
appropriate contexts.

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


On 2023-02-16 16:01, Alejandro Colomar wrote:
> Hi Stefan and Brian,
> 
> On 2/16/23 22:06, Stefan Puiu wrote:
>> Hi Brian,
>>
>> On Wed, Feb 15, 2023 at 10:21 PM Brian Inglis <Brian.Inglis@shaw.ca> wrote:
>>>
>>> ---
>>>   man2/add_key.2           | 2 +-
>>>   man2/epoll_wait.2        | 2 +-
>>>   man2/fcntl.2             | 2 +-
>>>   man2/getgroups.2         | 2 +-
>>>   man2/ioctl_console.2     | 4 ++--
>>>   man2/iopl.2              | 2 +-
>>>   man2/madvise.2           | 4 ++--
>>>   man2/mmap2.2             | 8 ++++----
>>>   man2/request_key.2       | 2 +-
>>>   man2/sched_setaffinity.2 | 4 ++--
>>>   man2/seccomp.2           | 4 ++--
>>>   man2/semop.2             | 4 ++--
>>>   man2/sendmmsg.2          | 2 +-
>>>   man2/shmget.2            | 4 ++--
>>>   man2/syslog.2            | 6 +++---
>>>   man2/vmsplice.2          | 2 +-
>>>   16 files changed, 27 insertions(+), 27 deletions(-)
>>>
>>> diff --git a/man2/add_key.2 b/man2/add_key.2
>>> index 56fc6d198d21..215de20baeae 100644
>>> --- a/man2/add_key.2
>>> +++ b/man2/add_key.2
>>> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
>>>   .I type
>>>   or
>>>   .I description
>>> -exceeded the limit (32 bytes and 4096 bytes respectively).
>>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>>
>> For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
>> anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?
> 
> In this case, we should rather use 4\ KiB, which is standard.
> 
> In general, let's divide the patches so that we can apply those that
> use standard syntax more easily, and then discuss more those that
> are more informal.
> 
>>
>>>   .TP
>>>   .B EINVAL
>>>   The payload data was invalid.
>>> diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
>>> index 1620cff9dfcc..4863ae4a43fa 100644
>>> --- a/man2/epoll_wait.2
>>> +++ b/man2/epoll_wait.2
>>> @@ -283,7 +283,7 @@ Thus, for example, on a system where
>>>   .I sizeof(long)
>>>   is 4 and the kernel
>>>   .I HZ
>>> -value is 1000,
>>> +value is 1k,
>>
>> I still prefer the old version, my impression is that 1k and friends
>> are used in informal contexts. Of course, it could be only my
>> impression.
> 
> Thanks for sharing your impression.  I'll take it into consideration.
> 
> Cheers,
> 
> Alex
> 
>>
>> Just my 2 cents,
>> Stefan.
>>
>>>   this means that timeouts greater than 35.79 minutes are treated as infinity.
>>>   .SH SEE ALSO
>>>   .BR epoll_create (2),
>>> diff --git a/man2/fcntl.2 b/man2/fcntl.2
>>> index 3ec52dc4dc03..630fc55888bc 100644
>>> --- a/man2/fcntl.2
>>> +++ b/man2/fcntl.2
>>> @@ -2004,7 +2004,7 @@ A limitation of the Linux system call conventions on some
>>>   architectures (notably i386) means that if a (negative)
>>>   process group ID to be returned by
>>>   .B F_GETOWN
>>> -falls in the range \-1 to \-4095, then the return value is wrongly
>>> +falls in the range \-1 to \-4Ki-1, then the return value is wrongly
>>>   interpreted by glibc as an error in the system call;
>>>   .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
>>>   that is, the return value of
>>> diff --git a/man2/getgroups.2 b/man2/getgroups.2
>>> index 36300bf61b6a..f01af687ccbd 100644
>>> --- a/man2/getgroups.2
>>> +++ b/man2/getgroups.2
>>> @@ -119,7 +119,7 @@ can additionally fail with the following errors:
>>>   .I size
>>>   is greater than
>>>   .B NGROUPS_MAX
>>> -(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
>>> +(32 before Linux 2.6.4; 64Ki since Linux 2.6.4).
>>>   .TP
>>>   .B ENOMEM
>>>   Out of memory.
>>> diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
>>> index 89f794c1956c..477e6fd1a7e1 100644
>>> --- a/man2/ioctl_console.2
>>> +++ b/man2/ioctl_console.2
>>> @@ -171,7 +171,7 @@ bright cyan, and white.
>>>   .B GIO_FONT
>>>   Gets 256-character screen font in expanded form.
>>>   .I argp
>>> -points to an 8192-byte array.
>>> +points to an 8Ki-byte array.
>>>   Fails with error code
>>>   .B EINVAL
>>>   if the
>>> @@ -211,7 +211,7 @@ Sets 256-character screen font.
>>>   Load font into the EGA/VGA character
>>>   generator.
>>>   .I argp
>>> -points to an 8192-byte map, with 32 bytes per
>>> +points to an 8Ki-byte map, with 32 bytes per
>>>   character.
>>>   Only the first
>>>   .I N
>>> diff --git a/man2/iopl.2 b/man2/iopl.2
>>> index abf1bef675fd..c967296157b7 100644
>>> --- a/man2/iopl.2
>>> +++ b/man2/iopl.2
>>> @@ -34,7 +34,7 @@ Permissions are inherited from parents to children.
>>>   This call is deprecated, is significantly slower than
>>>   .BR ioperm (2),
>>>   and is only provided for older X servers which require
>>> -access to all 65536 I/O ports.
>>> +access to all 64Ki I/O ports.
>>>   It is mostly for the i386 architecture.
>>>   On many other architectures it does not exist or will always
>>>   return an error.
>>> diff --git a/man2/madvise.2 b/man2/madvise.2
>>> index 9b4652a635d3..e05e9c5de4a7 100644
>>> --- a/man2/madvise.2
>>> +++ b/man2/madvise.2
>>> @@ -329,8 +329,8 @@ naturally aligned to the huge page size (see
>>>   This feature is primarily aimed at applications that use large mappings of
>>>   data and access large regions of that memory at a time (e.g., virtualization
>>>   systems such as QEMU).
>>> -It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
>>> -1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
>>> +It can very easily waste memory (e.g., a 2\ MiB mapping that only ever accesses
>>> +1 byte will result in 2\ MiB of wired memory instead of one 4\ KiB page).
>>>   See the Linux kernel source file
>>>   .I Documentation/admin\-guide/mm/transhuge.rst
>>>   for more details.
>>> diff --git a/man2/mmap2.2 b/man2/mmap2.2
>>> index 1fd5732ad41b..f975c1388a77 100644
>>> --- a/man2/mmap2.2
>>> +++ b/man2/mmap2.2
>>> @@ -32,7 +32,7 @@ The
>>>   system call provides the same interface as
>>>   .BR mmap (2),
>>>   except that the final argument specifies the offset into the
>>> -file in 4096-byte units (instead of bytes, as is done by
>>> +file in 4Ki-byte units (instead of bytes, as is done by
>>>   .BR mmap (2)).
>>>   This enables applications that use a 32-bit
>>>   .I off_t
>>> @@ -50,8 +50,8 @@ is set to indicate the error.
>>>   Problem with getting the data from user space.
>>>   .TP
>>>   .B EINVAL
>>> -(Various platforms where the page size is not 4096 bytes.)
>>> -.I "offset\ *\ 4096"
>>> +(Various platforms where the page size is not 4Ki bytes.)
>>> +.I "offset\ *\ 4Ki"
>>>   is not a multiple of the system page size.
>>>   .PP
>>>   .BR mmap2 ()
>>> @@ -74,7 +74,7 @@ This system call does not exist on x86-64.
>>>   .PP
>>>   On ia64, the unit for
>>>   .I offset
>>> -is actually the system page size, rather than 4096 bytes.
>>> +is actually the system page size, rather than 4Ki bytes.
>>>   .\" ia64 can have page sizes ranging from 4 kB to 64 kB.
>>>   .\" On cris, it looks like the unit might also be the page size,
>>>   .\" which is 8192 bytes. -- mtk, June 2007
>>> diff --git a/man2/request_key.2 b/man2/request_key.2
>>> index e78321e3c23f..dacc5282f3d8 100644
>>> --- a/man2/request_key.2
>>> +++ b/man2/request_key.2
>>> @@ -399,7 +399,7 @@ The size of the string (including the terminating null byte) specified in
>>>   .I type
>>>   or
>>>   .I description
>>> -exceeded the limit (32 bytes and 4096 bytes respectively).
>>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>>>   .TP
>>>   .B EINVAL
>>>   The size of the string (including the terminating null byte) specified in
>>> diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2
>>> index 86a93539137d..9e7a26293e73 100644
>>> --- a/man2/sched_setaffinity.2
>>> +++ b/man2/sched_setaffinity.2
>>> @@ -243,10 +243,10 @@ impose no restriction on the size of the CPU mask.
>>>   However, the
>>>   .I cpu_set_t
>>>   data type used by glibc has a fixed size of 128 bytes,
>>> -meaning that the maximum CPU number that can be represented is 1023.
>>> +meaning that the maximum CPU number that can be represented is 1\[aq]023.
>>>   .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
>>>   .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
>>> -If the kernel CPU affinity mask is larger than 1024,
>>> +If the kernel CPU affinity mask is larger than 1Ki,
>>>   then calls of the form:
>>>   .PP
>>>   .in +4n
>>> diff --git a/man2/seccomp.2 b/man2/seccomp.2
>>> index 32706397f03e..0bb8caa75698 100644
>>> --- a/man2/seccomp.2
>>> +++ b/man2/seccomp.2
>>> @@ -836,7 +836,7 @@ but the filter program pointed to by
>>>   .I args
>>>   was not valid or the length of the filter program was zero or exceeded
>>>   .B BPF_MAXINSNS
>>> -(4096) instructions.
>>> +(4Ki) instructions.
>>>   .TP
>>>   .B ENOMEM
>>>   Out of memory.
>>> @@ -846,7 +846,7 @@ Out of memory.
>>>   The total length of all filter programs attached
>>>   to the calling thread would exceed
>>>   .B MAX_INSNS_PER_PATH
>>> -(32768) instructions.
>>> +(32Ki) instructions.
>>>   Note that for the purposes of calculating this limit,
>>>   each already existing filter program incurs an
>>>   overhead penalty of 4 instructions.
>>> diff --git a/man2/semop.2 b/man2/semop.2
>>> index 7a1416a26894..a0027e0706c5 100644
>>> --- a/man2/semop.2
>>> +++ b/man2/semop.2
>>> @@ -434,7 +434,7 @@ On Linux, this limit can be read and modified via the third field of
>>>   .IR /proc/sys/kernel/sem .
>>>   .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
>>>   .IR Note :
>>> -this limit should not be raised above 1000,
>>> +this limit should not be raised above 1\[aq]000,
>>>   .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
>>>   because of the risk of that
>>>   .BR semop ()
>>> @@ -445,7 +445,7 @@ array.
>>>   .B SEMVMX
>>>   Maximum allowable value for
>>>   .IR semval :
>>> -implementation dependent (32767).
>>> +implementation dependent (32Ki-1).
>>>   .PP
>>>   The implementation has no intrinsic limits for
>>>   the adjust on exit maximum value
>>> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
>>> index 4e5475c45a09..3f355382ebf6 100644
>>> --- a/man2/sendmmsg.2
>>> +++ b/man2/sendmmsg.2
>>> @@ -139,7 +139,7 @@ The value specified in
>>>   .I vlen
>>>   is capped to
>>>   .B UIO_MAXIOV
>>> -(1024).
>>> +(1Ki).
>>>   .\" commit 98382f419f32d2c12d021943b87dea555677144b
>>>   .\"     net: Cap number of elements for sendmmsg
>>>   .\"
>>> diff --git a/man2/shmget.2 b/man2/shmget.2
>>> index c4d8df8ed619..5421fd4bf3e9 100644
>>> --- a/man2/shmget.2
>>> +++ b/man2/shmget.2
>>> @@ -360,7 +360,7 @@ 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
>>>   usable segment:
>>>   for example, on i386 the largest segments that can be mapped have a
>>> -size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
>>> +size of around 2.8\ GB, and on x86-64 the limit is around 127\ TB.
>>>   .TP
>>>   .B SHMMIN
>>>   Minimum size in bytes for a shared memory segment: implementation
>>> @@ -371,7 +371,7 @@ is the effective minimum size).
>>>   .B SHMMNI
>>>   System-wide limit on the number of shared memory segments.
>>>   In Linux 2.2, the default value for this limit was 128;
>>> -since Linux 2.4, the default value is 4096.
>>> +since Linux 2.4, the default value is 4Ki.
>>>   .IP
>>>   On Linux, this limit can be read and modified via
>>>   .IR /proc/sys/kernel/shmmni .
>>> diff --git a/man2/syslog.2 b/man2/syslog.2
>>> index 09c086f181e3..7d76e8cd9658 100644
>>> --- a/man2/syslog.2
>>> +++ b/man2/syslog.2
>>> @@ -54,9 +54,9 @@ in which messages given as arguments to the kernel function
>>>   are stored (regardless of their log level).
>>>   In early kernels,
>>>   .B LOG_BUF_LEN
>>> -had the value 4096;
>>> -from Linux 1.3.54, it was 8192;
>>> -from Linux 2.1.113, it was 16384;
>>> +had the value 4Ki;
>>> +from Linux 1.3.54, it was 8Ki;
>>> +from Linux 2.1.113, it was 16Ki;
>>>   since Linux 2.4.23/2.6, the value is a kernel configuration option
>>>   .RB ( CONFIG_LOG_BUF_SHIFT ,
>>>   default value dependent on the architecture).
>>> diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
>>> index 01ac37b3584f..08ede47361ae 100644
>>> --- a/man2/vmsplice.2
>>> +++ b/man2/vmsplice.2
>>> @@ -149,7 +149,7 @@ as defined in
>>>   .IR <limits.h> .
>>>   Currently,
>>>   .\" UIO_MAXIOV in kernel source
>>> -this limit is 1024.
>>> +this limit is 1Ki.
>>>   .PP
>>>   .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
>>>   .BR vmsplice ()

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-16 23:40       ` Brian Inglis
@ 2023-02-16 23:51         ` Alejandro Colomar
  0 siblings, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-16 23:51 UTC (permalink / raw)
  To: Brian.Inglis, Linux Man Pages; +Cc: Stefan Puiu


[-- Attachment #1.1: Type: text/plain, Size: 1115 bytes --]

Hi Brian,

On 2/17/23 00:40, Brian Inglis wrote:
> Hi Alex,
> 
> Should we leave some of these POSIX doc strings and short numbers as they are?
> I have been careful to use digit separators in POSIX feature docs only not code.
> 
> I see *those* as less formal, digit separators and ISO decimal multipliers as 
> more formal, and IEC binary multipliers more accurate and informative than 
> decimal digits where used.
> 
> I think hex values are 50/50 depending on counts of zero and non-zero digits and 
> context; IEC binary multipliers are more informative for amounts or sizes in 
> appropriate contexts.

I'm in favor of using the separators (almost) everywhere, so I prefer having patches
for all cases.  Just make many small patches, so we can apply them selectively and
discuss them separately.  Maybe we want to apply some now, some others maybe for after
C23, and maybe others we don't want them.  But I'd like to discuss all of them.

Thanks for your work!

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-16 23:01     ` Alejandro Colomar
  2023-02-16 23:40       ` Brian Inglis
@ 2023-02-17 14:05       ` Stefan Puiu
  2023-02-19 21:10         ` Alejandro Colomar
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Puiu @ 2023-02-17 14:05 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: Brian Inglis, Linux Man Pages

Hi Alex,

On Fri, Feb 17, 2023 at 1:01 AM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Stefan and Brian,
>
> On 2/16/23 22:06, Stefan Puiu wrote:
> > Hi Brian,
> >
> > On Wed, Feb 15, 2023 at 10:21 PM Brian Inglis <Brian.Inglis@shaw.ca> wrote:
> >>
> >> ---
> >>  man2/add_key.2           | 2 +-
> >>  man2/epoll_wait.2        | 2 +-
> >>  man2/fcntl.2             | 2 +-
> >>  man2/getgroups.2         | 2 +-
> >>  man2/ioctl_console.2     | 4 ++--
> >>  man2/iopl.2              | 2 +-
> >>  man2/madvise.2           | 4 ++--
> >>  man2/mmap2.2             | 8 ++++----
> >>  man2/request_key.2       | 2 +-
> >>  man2/sched_setaffinity.2 | 4 ++--
> >>  man2/seccomp.2           | 4 ++--
> >>  man2/semop.2             | 4 ++--
> >>  man2/sendmmsg.2          | 2 +-
> >>  man2/shmget.2            | 4 ++--
> >>  man2/syslog.2            | 6 +++---
> >>  man2/vmsplice.2          | 2 +-
> >>  16 files changed, 27 insertions(+), 27 deletions(-)
> >>
> >> diff --git a/man2/add_key.2 b/man2/add_key.2
> >> index 56fc6d198d21..215de20baeae 100644
> >> --- a/man2/add_key.2
> >> +++ b/man2/add_key.2
> >> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
> >>  .I type
> >>  or
> >>  .I description
> >> -exceeded the limit (32 bytes and 4096 bytes respectively).
> >> +exceeded the limit (32 bytes and 4Ki bytes respectively).
> >
> > For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
> > anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?
>
> In this case, we should rather use 4\ KiB, which is standard.

Maybe it is standard, but why is 4 KiB better / more suitable than 4096?

Stefan.

>
> In general, let's divide the patches so that we can apply those that
> use standard syntax more easily, and then discuss more those that
> are more informal.
>
> >
> >>  .TP
> >>  .B EINVAL
> >>  The payload data was invalid.
> >> diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
> >> index 1620cff9dfcc..4863ae4a43fa 100644
> >> --- a/man2/epoll_wait.2
> >> +++ b/man2/epoll_wait.2
> >> @@ -283,7 +283,7 @@ Thus, for example, on a system where
> >>  .I sizeof(long)
> >>  is 4 and the kernel
> >>  .I HZ
> >> -value is 1000,
> >> +value is 1k,
> >
> > I still prefer the old version, my impression is that 1k and friends
> > are used in informal contexts. Of course, it could be only my
> > impression.
>
> Thanks for sharing your impression.  I'll take it into consideration.
>
> Cheers,
>
> Alex
>
> >
> > Just my 2 cents,
> > Stefan.
> >
> >>  this means that timeouts greater than 35.79 minutes are treated as infinity.
> >>  .SH SEE ALSO
> >>  .BR epoll_create (2),
> >> diff --git a/man2/fcntl.2 b/man2/fcntl.2
> >> index 3ec52dc4dc03..630fc55888bc 100644
> >> --- a/man2/fcntl.2
> >> +++ b/man2/fcntl.2
> >> @@ -2004,7 +2004,7 @@ A limitation of the Linux system call conventions on some
> >>  architectures (notably i386) means that if a (negative)
> >>  process group ID to be returned by
> >>  .B F_GETOWN
> >> -falls in the range \-1 to \-4095, then the return value is wrongly
> >> +falls in the range \-1 to \-4Ki-1, then the return value is wrongly
> >>  interpreted by glibc as an error in the system call;
> >>  .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
> >>  that is, the return value of
> >> diff --git a/man2/getgroups.2 b/man2/getgroups.2
> >> index 36300bf61b6a..f01af687ccbd 100644
> >> --- a/man2/getgroups.2
> >> +++ b/man2/getgroups.2
> >> @@ -119,7 +119,7 @@ can additionally fail with the following errors:
> >>  .I size
> >>  is greater than
> >>  .B NGROUPS_MAX
> >> -(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
> >> +(32 before Linux 2.6.4; 64Ki since Linux 2.6.4).
> >>  .TP
> >>  .B ENOMEM
> >>  Out of memory.
> >> diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
> >> index 89f794c1956c..477e6fd1a7e1 100644
> >> --- a/man2/ioctl_console.2
> >> +++ b/man2/ioctl_console.2
> >> @@ -171,7 +171,7 @@ bright cyan, and white.
> >>  .B GIO_FONT
> >>  Gets 256-character screen font in expanded form.
> >>  .I argp
> >> -points to an 8192-byte array.
> >> +points to an 8Ki-byte array.
> >>  Fails with error code
> >>  .B EINVAL
> >>  if the
> >> @@ -211,7 +211,7 @@ Sets 256-character screen font.
> >>  Load font into the EGA/VGA character
> >>  generator.
> >>  .I argp
> >> -points to an 8192-byte map, with 32 bytes per
> >> +points to an 8Ki-byte map, with 32 bytes per
> >>  character.
> >>  Only the first
> >>  .I N
> >> diff --git a/man2/iopl.2 b/man2/iopl.2
> >> index abf1bef675fd..c967296157b7 100644
> >> --- a/man2/iopl.2
> >> +++ b/man2/iopl.2
> >> @@ -34,7 +34,7 @@ Permissions are inherited from parents to children.
> >>  This call is deprecated, is significantly slower than
> >>  .BR ioperm (2),
> >>  and is only provided for older X servers which require
> >> -access to all 65536 I/O ports.
> >> +access to all 64Ki I/O ports.
> >>  It is mostly for the i386 architecture.
> >>  On many other architectures it does not exist or will always
> >>  return an error.
> >> diff --git a/man2/madvise.2 b/man2/madvise.2
> >> index 9b4652a635d3..e05e9c5de4a7 100644
> >> --- a/man2/madvise.2
> >> +++ b/man2/madvise.2
> >> @@ -329,8 +329,8 @@ naturally aligned to the huge page size (see
> >>  This feature is primarily aimed at applications that use large mappings of
> >>  data and access large regions of that memory at a time (e.g., virtualization
> >>  systems such as QEMU).
> >> -It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
> >> -1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
> >> +It can very easily waste memory (e.g., a 2\ MiB mapping that only ever accesses
> >> +1 byte will result in 2\ MiB of wired memory instead of one 4\ KiB page).
> >>  See the Linux kernel source file
> >>  .I Documentation/admin\-guide/mm/transhuge.rst
> >>  for more details.
> >> diff --git a/man2/mmap2.2 b/man2/mmap2.2
> >> index 1fd5732ad41b..f975c1388a77 100644
> >> --- a/man2/mmap2.2
> >> +++ b/man2/mmap2.2
> >> @@ -32,7 +32,7 @@ The
> >>  system call provides the same interface as
> >>  .BR mmap (2),
> >>  except that the final argument specifies the offset into the
> >> -file in 4096-byte units (instead of bytes, as is done by
> >> +file in 4Ki-byte units (instead of bytes, as is done by
> >>  .BR mmap (2)).
> >>  This enables applications that use a 32-bit
> >>  .I off_t
> >> @@ -50,8 +50,8 @@ is set to indicate the error.
> >>  Problem with getting the data from user space.
> >>  .TP
> >>  .B EINVAL
> >> -(Various platforms where the page size is not 4096 bytes.)
> >> -.I "offset\ *\ 4096"
> >> +(Various platforms where the page size is not 4Ki bytes.)
> >> +.I "offset\ *\ 4Ki"
> >>  is not a multiple of the system page size.
> >>  .PP
> >>  .BR mmap2 ()
> >> @@ -74,7 +74,7 @@ This system call does not exist on x86-64.
> >>  .PP
> >>  On ia64, the unit for
> >>  .I offset
> >> -is actually the system page size, rather than 4096 bytes.
> >> +is actually the system page size, rather than 4Ki bytes.
> >>  .\" ia64 can have page sizes ranging from 4 kB to 64 kB.
> >>  .\" On cris, it looks like the unit might also be the page size,
> >>  .\" which is 8192 bytes. -- mtk, June 2007
> >> diff --git a/man2/request_key.2 b/man2/request_key.2
> >> index e78321e3c23f..dacc5282f3d8 100644
> >> --- a/man2/request_key.2
> >> +++ b/man2/request_key.2
> >> @@ -399,7 +399,7 @@ The size of the string (including the terminating null byte) specified in
> >>  .I type
> >>  or
> >>  .I description
> >> -exceeded the limit (32 bytes and 4096 bytes respectively).
> >> +exceeded the limit (32 bytes and 4Ki bytes respectively).
> >>  .TP
> >>  .B EINVAL
> >>  The size of the string (including the terminating null byte) specified in
> >> diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2
> >> index 86a93539137d..9e7a26293e73 100644
> >> --- a/man2/sched_setaffinity.2
> >> +++ b/man2/sched_setaffinity.2
> >> @@ -243,10 +243,10 @@ impose no restriction on the size of the CPU mask.
> >>  However, the
> >>  .I cpu_set_t
> >>  data type used by glibc has a fixed size of 128 bytes,
> >> -meaning that the maximum CPU number that can be represented is 1023.
> >> +meaning that the maximum CPU number that can be represented is 1\[aq]023.
> >>  .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
> >>  .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
> >> -If the kernel CPU affinity mask is larger than 1024,
> >> +If the kernel CPU affinity mask is larger than 1Ki,
> >>  then calls of the form:
> >>  .PP
> >>  .in +4n
> >> diff --git a/man2/seccomp.2 b/man2/seccomp.2
> >> index 32706397f03e..0bb8caa75698 100644
> >> --- a/man2/seccomp.2
> >> +++ b/man2/seccomp.2
> >> @@ -836,7 +836,7 @@ but the filter program pointed to by
> >>  .I args
> >>  was not valid or the length of the filter program was zero or exceeded
> >>  .B BPF_MAXINSNS
> >> -(4096) instructions.
> >> +(4Ki) instructions.
> >>  .TP
> >>  .B ENOMEM
> >>  Out of memory.
> >> @@ -846,7 +846,7 @@ Out of memory.
> >>  The total length of all filter programs attached
> >>  to the calling thread would exceed
> >>  .B MAX_INSNS_PER_PATH
> >> -(32768) instructions.
> >> +(32Ki) instructions.
> >>  Note that for the purposes of calculating this limit,
> >>  each already existing filter program incurs an
> >>  overhead penalty of 4 instructions.
> >> diff --git a/man2/semop.2 b/man2/semop.2
> >> index 7a1416a26894..a0027e0706c5 100644
> >> --- a/man2/semop.2
> >> +++ b/man2/semop.2
> >> @@ -434,7 +434,7 @@ On Linux, this limit can be read and modified via the third field of
> >>  .IR /proc/sys/kernel/sem .
> >>  .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
> >>  .IR Note :
> >> -this limit should not be raised above 1000,
> >> +this limit should not be raised above 1\[aq]000,
> >>  .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
> >>  because of the risk of that
> >>  .BR semop ()
> >> @@ -445,7 +445,7 @@ array.
> >>  .B SEMVMX
> >>  Maximum allowable value for
> >>  .IR semval :
> >> -implementation dependent (32767).
> >> +implementation dependent (32Ki-1).
> >>  .PP
> >>  The implementation has no intrinsic limits for
> >>  the adjust on exit maximum value
> >> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
> >> index 4e5475c45a09..3f355382ebf6 100644
> >> --- a/man2/sendmmsg.2
> >> +++ b/man2/sendmmsg.2
> >> @@ -139,7 +139,7 @@ The value specified in
> >>  .I vlen
> >>  is capped to
> >>  .B UIO_MAXIOV
> >> -(1024).
> >> +(1Ki).
> >>  .\" commit 98382f419f32d2c12d021943b87dea555677144b
> >>  .\"     net: Cap number of elements for sendmmsg
> >>  .\"
> >> diff --git a/man2/shmget.2 b/man2/shmget.2
> >> index c4d8df8ed619..5421fd4bf3e9 100644
> >> --- a/man2/shmget.2
> >> +++ b/man2/shmget.2
> >> @@ -360,7 +360,7 @@ 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
> >>  usable segment:
> >>  for example, on i386 the largest segments that can be mapped have a
> >> -size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
> >> +size of around 2.8\ GB, and on x86-64 the limit is around 127\ TB.
> >>  .TP
> >>  .B SHMMIN
> >>  Minimum size in bytes for a shared memory segment: implementation
> >> @@ -371,7 +371,7 @@ is the effective minimum size).
> >>  .B SHMMNI
> >>  System-wide limit on the number of shared memory segments.
> >>  In Linux 2.2, the default value for this limit was 128;
> >> -since Linux 2.4, the default value is 4096.
> >> +since Linux 2.4, the default value is 4Ki.
> >>  .IP
> >>  On Linux, this limit can be read and modified via
> >>  .IR /proc/sys/kernel/shmmni .
> >> diff --git a/man2/syslog.2 b/man2/syslog.2
> >> index 09c086f181e3..7d76e8cd9658 100644
> >> --- a/man2/syslog.2
> >> +++ b/man2/syslog.2
> >> @@ -54,9 +54,9 @@ in which messages given as arguments to the kernel function
> >>  are stored (regardless of their log level).
> >>  In early kernels,
> >>  .B LOG_BUF_LEN
> >> -had the value 4096;
> >> -from Linux 1.3.54, it was 8192;
> >> -from Linux 2.1.113, it was 16384;
> >> +had the value 4Ki;
> >> +from Linux 1.3.54, it was 8Ki;
> >> +from Linux 2.1.113, it was 16Ki;
> >>  since Linux 2.4.23/2.6, the value is a kernel configuration option
> >>  .RB ( CONFIG_LOG_BUF_SHIFT ,
> >>  default value dependent on the architecture).
> >> diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
> >> index 01ac37b3584f..08ede47361ae 100644
> >> --- a/man2/vmsplice.2
> >> +++ b/man2/vmsplice.2
> >> @@ -149,7 +149,7 @@ as defined in
> >>  .IR <limits.h> .
> >>  Currently,
> >>  .\" UIO_MAXIOV in kernel source
> >> -this limit is 1024.
> >> +this limit is 1Ki.
> >>  .PP
> >>  .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
> >>  .BR vmsplice ()
> >> --
> >> 2.39.0
> >>
>
> --
> <http://www.alejandro-colomar.es/>
> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates
  2023-02-16 23:04     ` Alejandro Colomar
@ 2023-02-17 14:16       ` Stefan Puiu
  0 siblings, 0 replies; 39+ messages in thread
From: Stefan Puiu @ 2023-02-17 14:16 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: Brian Inglis, Linux Man Pages

Hi Alex,

On Fri, Feb 17, 2023 at 1:04 AM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Stefan,
>
> On 2/16/23 22:11, Stefan Puiu wrote:
> > Hi Brian,
>
> [...]
>
> >> diff --git a/man2/access.2 b/man2/access.2
> >> index d3deeecba0c7..4c93a132b209 100644
> >> --- a/man2/access.2
> >> +++ b/man2/access.2
> >> @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see
> >>  .BR faccessat ():
> >>  .nf
> >>      Since glibc 2.10:
> >> -        _POSIX_C_SOURCE >= 200809L
> >> +        _POSIX_C_SOURCE >= 2008\[aq]09L
> >
> > Not sure how \[aq] renders,
>
> \[aq] is equivalent to \(aq, which renders as ', the single quote character.
>
> > but if people want to copy / paste some of
> > these snippets (for use in their code, or for searching), wouldn't
> > they need to then remove the separator?
>
> It depends on your compiler version and language version.
> ISO C23 will add support for this.  What we could do is prepare the patches,
> and leave them in a branch until C23 is made official.
>
> Right now, you can already get recent enough versions of GCC to
> accept that code, if you use -std=c2x.

Good to know. If this were a few years old, it would probably be a
no-brainer, but if this is valid code only for the latest and greatest
gcc, then yes, maybe these changes can wait. There are many projects
that take a while to adapt to newer compiler versions, and not
everybody runs distros with new compilers.

Just my 2 cents,
Stefan.

>
> > I think that can cause
> > confusion, which you probably don't want documentation to do.>
> > Again, just my 2 cents,
> > Stefan.
> >
>
> Cheers,
>
> Alex
>
> --
> <http://www.alejandro-colomar.es/>
> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-15 21:10   ` Alejandro Colomar
@ 2023-02-18 17:42     ` Tom Schwindl
  2023-02-18 18:08       ` G. Branden Robinson
  2023-02-18 18:41       ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings Brian Inglis
  0 siblings, 2 replies; 39+ messages in thread
From: Tom Schwindl @ 2023-02-18 17:42 UTC (permalink / raw)
  To: Alejandro Colomar, Brian Inglis; +Cc: Linux Man Pages

Hi Alex,

On Wed Feb 15, 2023 at 10:10 PM CET, Alejandro Colomar wrote:
> Hi Brian,
>
> On 2/15/23 21:17, Brian Inglis wrote:
> > ---
> >  man2/chmod.2 | 30 +++++++++++++++---------------
> >  1 file changed, 15 insertions(+), 15 deletions(-)
> > 
> > diff --git a/man2/chmod.2 b/man2/chmod.2
> > index 8b5db74ed7e3..674b54368314 100644
> > --- a/man2/chmod.2
> > +++ b/man2/chmod.2
> > @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see
> >  .nf
> >  .BR fchmod ():
> >      Since glibc 2.24:
> > -        _POSIX_C_SOURCE >= 199309L
> > +        _POSIX_C_SOURCE >= 1993\[aq]09L
>
> Please keep all POSIX dates in a single separate patch
> (unless there's another reason that I'm not seeing).

As long as I'm not completely lost, those values are often passed on the command
line via `-D`. Wouldn't a random \[aq] interfere with shell quoting and result in
hard to find bugs and unexpected bahavior? So is it really a good idea to present
those values in such a way in the manpage? Or am I simply underestimating the
intelligence of the readers? :-)

-- 
Best Regards,
Tom Schwindl

>
> Cheers,
>
> Alex

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-18 17:42     ` Tom Schwindl
@ 2023-02-18 18:08       ` G. Branden Robinson
  2023-02-18 18:31         ` Tom Schwindl
  2023-02-18 18:41       ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings Brian Inglis
  1 sibling, 1 reply; 39+ messages in thread
From: G. Branden Robinson @ 2023-02-18 18:08 UTC (permalink / raw)
  To: Tom Schwindl; +Cc: Alejandro Colomar, Brian Inglis, Linux Man Pages

[-- Attachment #1: Type: text/plain, Size: 1069 bytes --]

Hi Tom,

At 2023-02-18T17:42:05+0000, Tom Schwindl wrote:
> > > diff --git a/man2/chmod.2 b/man2/chmod.2
> > > index 8b5db74ed7e3..674b54368314 100644
> > > --- a/man2/chmod.2
> > > +++ b/man2/chmod.2
> > > @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see
> > >  .nf
> > >  .BR fchmod ():
> > >      Since glibc 2.24:
> > > -        _POSIX_C_SOURCE >= 199309L
> > > +        _POSIX_C_SOURCE >= 1993\[aq]09L
[...]
> As long as I'm not completely lost, those values are often passed on
> the command line via `-D`. Wouldn't a random \[aq] interfere with
> shell quoting and result in hard to find bugs and unexpected bahavior?
> So is it really a good idea to present those values in such a way in
> the manpage? Or am I simply underestimating the intelligence of the
> readers? :-)

Do you expect C programmers to be more likely to copy and paste from the
man page source document or from the rendered page (probably in a
terminal window, but possibly from a PDF)?

The answer to the questions you posed depends on your answer to mine.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-18 18:08       ` G. Branden Robinson
@ 2023-02-18 18:31         ` Tom Schwindl
  2023-02-18 19:03           ` G. Branden Robinson
  0 siblings, 1 reply; 39+ messages in thread
From: Tom Schwindl @ 2023-02-18 18:31 UTC (permalink / raw)
  To: G. Branden Robinson; +Cc: Alejandro Colomar, Brian Inglis, Linux Man Pages

Hi Branden,

On Sat Feb 18, 2023 at 7:08 PM CET, G. Branden Robinson wrote:
> Hi Tom,
>
> At 2023-02-18T17:42:05+0000, Tom Schwindl wrote:
> > > > diff --git a/man2/chmod.2 b/man2/chmod.2
> > > > index 8b5db74ed7e3..674b54368314 100644
> > > > --- a/man2/chmod.2
> > > > +++ b/man2/chmod.2
> > > > @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see
> > > >  .nf
> > > >  .BR fchmod ():
> > > >      Since glibc 2.24:
> > > > -        _POSIX_C_SOURCE >= 199309L
> > > > +        _POSIX_C_SOURCE >= 1993\[aq]09L
> [...]
> > As long as I'm not completely lost, those values are often passed on
> > the command line via `-D`. Wouldn't a random \[aq] interfere with
> > shell quoting and result in hard to find bugs and unexpected bahavior?
> > So is it really a good idea to present those values in such a way in
> > the manpage? Or am I simply underestimating the intelligence of the
> > readers? :-)
>
> Do you expect C programmers to be more likely to copy and paste from the
> man page source document or from the rendered page (probably in a
> terminal window, but possibly from a PDF)?
>

I expect them to copy & paste from the rendered page but I thought writing out
"'" is a bit cumbersome so I refer to it as \[aq]. My "worry" with this was
that new programmers could potentially execute a command like the following:

  $ cc -D_POSIX_C_SOURCE=1993'09L test.c

and wonder what they did wrong.
But thinking about it a bit longer, copy & pasting from the rendered manpage
might be the bigger issue. Or not, depending on the answer you'll give me :)

-- 
Best Regards,
Tom Schwindl

> The answer to the questions you posed depends on your answer to mine.
>
> Regards,
> Branden


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-18 17:42     ` Tom Schwindl
  2023-02-18 18:08       ` G. Branden Robinson
@ 2023-02-18 18:41       ` Brian Inglis
  1 sibling, 0 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-18 18:41 UTC (permalink / raw)
  To: Tom Schwindl; +Cc: Linux Man Pages, Alejandro Colomar

On 2023-02-18 10:42, Tom Schwindl wrote:
> On Wed Feb 15, 2023 at 10:10 PM CET, Alejandro Colomar wrote:
>> On 2/15/23 21:17, Brian Inglis wrote:
>>> ---
>>>   man2/chmod.2 | 30 +++++++++++++++---------------
>>>   1 file changed, 15 insertions(+), 15 deletions(-)
>>>
>>> diff --git a/man2/chmod.2 b/man2/chmod.2
>>> index 8b5db74ed7e3..674b54368314 100644
>>> --- a/man2/chmod.2
>>> +++ b/man2/chmod.2
>>> @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see
>>>   .nf
>>>   .BR fchmod ():
>>>       Since glibc 2.24:
>>> -        _POSIX_C_SOURCE >= 199309L
>>> +        _POSIX_C_SOURCE >= 1993\[aq]09L
>>
>> Please keep all POSIX dates in a single separate patch
>> (unless there's another reason that I'm not seeing).
> 
> As long as I'm not completely lost, those values are often passed on the command
> line via `-D`. Wouldn't a random \[aq] interfere with shell quoting and result in
> hard to find bugs and unexpected bahavior? So is it really a good idea to present
> those values in such a way in the manpage? Or am I simply underestimating the
> intelligence of the readers? :-)

Hi Tom,

As \[aq] renders as aprostrophe/single-quote "'" the value can be "1993'09L" 
quoted if required.

I would expect these values to most often be set and tested in headers and 
sources, mainly from systems, compilers, or libraries, to indicate support of 
certain features or enable their interfaces to be defined.

I would expect these to be rarely set nowadays in hopes of enabling otherwise 
disabled features required to build a package or application, more likely to 
change or disable undesired interfaces, and instead expect them to be configured 
by compiler options e.g. -std=gnu23 and/or in library headers, and tested by 
application or package sources.

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

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-18 18:31         ` Tom Schwindl
@ 2023-02-18 19:03           ` G. Branden Robinson
  2023-02-18 23:32             ` Brian Inglis
  2023-02-19 11:50             ` ADA and base prefix for numbers Alejandro Colomar
  0 siblings, 2 replies; 39+ messages in thread
From: G. Branden Robinson @ 2023-02-18 19:03 UTC (permalink / raw)
  To: Tom Schwindl; +Cc: Alejandro Colomar, Brian Inglis, Linux Man Pages

[-- Attachment #1: Type: text/plain, Size: 3865 bytes --]

Hi Tom,

At 2023-02-18T18:31:25+0000, Tom Schwindl wrote:
> > Do you expect C programmers to be more likely to copy and paste from
> > the man page source document or from the rendered page (probably in
> > a terminal window, but possibly from a PDF)?
> >
> 
> I expect them to copy & paste from the rendered page but I thought
> writing out "'" is a bit cumbersome so I refer to it as \[aq].

Ahh, that can be a bit confusing without clear context.  :D

> My "worry" with this was that new programmers could potentially
> execute a command like the following:
> 
>   $ cc -D_POSIX_C_SOURCE=1993'09L test.c
> 
> and wonder what they did wrong.

I see--that is a good point.  But I don't know that there is much the
man pages can do about that issue, apart from having a better intro(1)
page.  The scenario you imagine is an unfortunate consequence of the
grouping character WG14 selected.

New C programmers on *nix are going to have to develop some
sophistication with the POSIX shell language as well, and that will be
even more the case now--a cost of letting the Swiss win battles...

Mainly because Alex is reading, I will point out that Ada did this, and
several other aspects of numeric literals, right--40 years ago.

>> Numeric literals are all introduced by an initial digit. A
>> requirement that has long been recognized when printing numeric
>> tables is for a character to break up long sequences of digits: in
>> Ada, the underline character serves this purpose. In contrast to
>> identifiers, underlines in numeric literals do not alter the meaning,
>> so that 12_000 naturally has the same value as 12000.
>>
>> A simple sequence of digits is an integer literal written in decimal
>> notation. For other bases from 2 up to 16, the base is given first
>> and is followed by a sequence of digits enclosed by sharp characters
>> (#) or by colons (:), the colon being used as replacement character
>> for the sharp, but only when the sharp is not available. The enclosed
>> digits may include the letters A to F for bases greater than ten.
>> Thus, the conventional ways of expressing bit patterns in binary,
>> octal, or hexadecimal are provided.
>>
>> Real literals must contain a period, which represents the radix
>> point. They may be expressed in decimal notation or with other bases.
>> Finally, both integer and real literals may include the letter E
>> followed by an exponent.

http://archive.adaic.com/standards/83rat/html/ratl-02-01.html#2.1

But C programmers have long indulged in the sport of ignoring every
lesson any other programming language had to teach, whether through
careful design or blundering mistake.[1]  C'est la vie.

> But thinking about it a bit longer, copy & pasting from the rendered
> manpage might be the bigger issue.

This prospect was a major factor in my efforts to get groff's own man
pages much more fastidious in this respect, and to promulgate the usage
of appropriate special characters in man page sources, an initiative
that I'm not sure has yet taken flight, although Linux man-pages is
rapidly improving in this regard.  The real test is whether such careful
practice percolates elsewhere, where disinterest in (or outright
resentment of) writing documentation, in man(7), mdoc(7), or any other
form, is rampant.

Regards,
Branden

[1] Thompson discarded type checking and "//" comments from BCPL; the
    latter came back relatively painlessly (though only in C99, which
    Ritchie refused to endorse).  The former has been resurrected in
    fitful stages, and only where the suffering imposed by careless
    typing can be discerned as imposing engineering costs in defect
    resolution greater than in initial implementation by a factor of
    1,000 or more.

    https://www.bell-labs.com/usr/dmr/www/chist.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings
  2023-02-18 19:03           ` G. Branden Robinson
@ 2023-02-18 23:32             ` Brian Inglis
  2023-02-19 11:50             ` ADA and base prefix for numbers Alejandro Colomar
  1 sibling, 0 replies; 39+ messages in thread
From: Brian Inglis @ 2023-02-18 23:32 UTC (permalink / raw)
  To: G. Branden Robinson; +Cc: Alejandro Colomar, Linux Man Pages, Tom Schwindl

On 2023-02-18 12:03, G. Branden Robinson wrote:
> Hi Tom,
> At 2023-02-18T18:31:25+0000, Tom Schwindl wrote:
>>> Do you expect C programmers to be more likely to copy and paste from
>>> the man page source document or from the rendered page (probably in
>>> a terminal window, but possibly from a PDF)?

>> I expect them to copy & paste from the rendered page but I thought
>> writing out "'" is a bit cumbersome so I refer to it as \[aq].

> Ahh, that can be a bit confusing without clear context.  :D

>> My "worry" with this was that new programmers could potentially
>> execute a command like the following:
>>    $ cc -D_POSIX_C_SOURCE=1993'09L test.c
>> and wonder what they did wrong.

> I see--that is a good point.  But I don't know that there is much the
> man pages can do about that issue, apart from having a better intro(1)
> page.  The scenario you imagine is an unfortunate consequence of the
> grouping character WG14 selected.
> New C programmers on *nix are going to have to develop some
> sophistication with the POSIX shell language as well, and that will be
> even more the case now--a cost of letting the Swiss win battles...
> Mainly because Alex is reading, I will point out that Ada did this, and
> several other aspects of numeric literals, right--40 years ago.

>>> Numeric literals are all introduced by an initial digit. A
>>> requirement that has long been recognized when printing numeric
>>> tables is for a character to break up long sequences of digits: in
>>> Ada, the underline character serves this purpose. In contrast to
>>> identifiers, underlines in numeric literals do not alter the meaning,
>>> so that 12_000 naturally has the same value as 12000.
>>> A simple sequence of digits is an integer literal written in decimal
>>> notation. For other bases from 2 up to 16, the base is given first
>>> and is followed by a sequence of digits enclosed by sharp characters
>>> (#) or by colons (:), the colon being used as replacement character
>>> for the sharp, but only when the sharp is not available. The enclosed
>>> digits may include the letters A to F for bases greater than ten.
>>> Thus, the conventional ways of expressing bit patterns in binary,
>>> octal, or hexadecimal are provided.
>>> Real literals must contain a period, which represents the radix
>>> point. They may be expressed in decimal notation or with other bases.
>>> Finally, both integer and real literals may include the letter E
>>> followed by an exponent.

> http://archive.adaic.com/standards/83rat/html/ratl-02-01.html#2.1
> But C programmers have long indulged in the sport of ignoring every
> lesson any other programming language had to teach, whether through
> careful design or blundering mistake.[1]  C'est la vie.

>> But thinking about it a bit longer, copy & pasting from the rendered
>> manpage might be the bigger issue.

> This prospect was a major factor in my efforts to get groff's own man
> pages much more fastidious in this respect, and to promulgate the usage
> of appropriate special characters in man page sources, an initiative
> that I'm not sure has yet taken flight, although Linux man-pages is
> rapidly improving in this regard.  The real test is whether such careful
> practice percolates elsewhere, where disinterest in (or outright
> resentment of) writing documentation, in man(7), mdoc(7), or any other
> form, is rampant.
It is sad that the documentation tools, other than man, were not made freely and 
widely available, so that the attitudes of many of the original developers 
towards providing documentation, propagated alongside the system, language, 
tools, and idioms.

We have the deliberations of IEC/ISO JTC1/SC22/WG21 C++ to thank for the 
decision a decade ago, as well as the earlier addition of user defined type 
constants, and other features, imposing restrictions on the preprocessor token 
parser capabilities, and the strong desires of the WG14 C and WG21 C++ 
committees to keep as many base features in the languages as possible in sync.
Papers on digit separators:

	https://open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3499.html
	https://open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3661.html
	https://open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf

which C took up only in 2020-2021:

	https://open-std.org/JTC1/SC22/WG14/www/docs/n2606.pdf
	https://open-std.org/JTC1/SC22/WG14/www/docs/n2626.pdf

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

^ permalink raw reply	[flat|nested] 39+ messages in thread

* ADA and base prefix for numbers
  2023-02-18 19:03           ` G. Branden Robinson
  2023-02-18 23:32             ` Brian Inglis
@ 2023-02-19 11:50             ` Alejandro Colomar
  1 sibling, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-19 11:50 UTC (permalink / raw)
  To: G. Branden Robinson; +Cc: Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 2996 bytes --]

[CC trimmed]

Hi Branden,

On 2/18/23 20:03, G. Branden Robinson wrote:
> Mainly because Alex is reading, I will point out that Ada did this, and
> several other aspects of numeric literals, right--40 years ago.
> 
>>> Numeric literals are all introduced by an initial digit. A
>>> requirement that has long been recognized when printing numeric
>>> tables is for a character to break up long sequences of digits: in
>>> Ada, the underline character serves this purpose. In contrast to
>>> identifiers, underlines in numeric literals do not alter the meaning,
>>> so that 12_000 naturally has the same value as 12000.
>>>
>>> A simple sequence of digits is an integer literal written in decimal
>>> notation. For other bases from 2 up to 16, the base is given first
>>> and is followed by a sequence of digits enclosed by sharp characters
>>> (#) or by colons (:), the colon being used as replacement character
>>> for the sharp, but only when the sharp is not available. The enclosed
>>> digits may include the letters A to F for bases greater than ten.
>>> Thus, the conventional ways of expressing bit patterns in binary,
>>> octal, or hexadecimal are provided.
>>>
>>> Real literals must contain a period, which represents the radix
>>> point. They may be expressed in decimal notation or with other bases.
>>> Finally, both integer and real literals may include the letter E
>>> followed by an exponent.

I like Ada's base selection :-)
Even if one will rarely use anything other than 2, 8, 10, and 16,
it's interesting to be able to.  C's is not completely broken, and
I'd like it to follow Python and add 0o for octal (and deprecate 0
as a prefix), which would fix the most aberrant thing I hate from
C's numeric literals.
  
> 
> http://archive.adaic.com/standards/83rat/html/ratl-02-01.html#2.1

[I still didn't finish reading it, but am doing :)]

> 
> But C programmers have long indulged in the sport of ignoring every
> lesson any other programming language had to teach, whether through
> careful design or blundering mistake.[1]  C'est la vie.

[...]

> 
> Regards,
> Branden
> 
> [1] Thompson discarded type checking and "//" comments from BCPL; the
>     latter came back relatively painlessly (though only in C99, which
>     Ritchie refused to endorse).  The former has been resurrected in
>     fitful stages, and only where the suffering imposed by careless
>     typing can be discerned as imposing engineering costs in defect
>     resolution greater than in initial implementation by a factor of
>     1,000 or more.
> 
>     https://www.bell-labs.com/usr/dmr/www/chist.html

I have some consistency fixes pending for the Linux man-pages:

-  Use // where the comment is a single line _and_ affects only
   the code in the same line (not below, not above).
-  Use /**/ elsewhere.

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-17 14:05       ` Stefan Puiu
@ 2023-02-19 21:10         ` Alejandro Colomar
  2023-02-19 21:12           ` Alejandro Colomar
  2023-02-20 14:29           ` Stefan Puiu
  0 siblings, 2 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-19 21:10 UTC (permalink / raw)
  To: Stefan Puiu; +Cc: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 1115 bytes --]

Hi Stefan,

On 2/17/23 15:05, Stefan Puiu wrote:
[...]

>>>> diff --git a/man2/add_key.2 b/man2/add_key.2
>>>> index 56fc6d198d21..215de20baeae 100644
>>>> --- a/man2/add_key.2
>>>> +++ b/man2/add_key.2
>>>> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
>>>>  .I type
>>>>  or
>>>>  .I description
>>>> -exceeded the limit (32 bytes and 4096 bytes respectively).
>>>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>>>
>>> For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
>>> anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?
>>
>> In this case, we should rather use 4\ KiB, which is standard.
> 
> Maybe it is standard, but why is 4 KiB better / more suitable than 4096?

4 KiB is not that much better than 4096, since 4096 is easy to read.
For higher numbers such as 33554432, it becomes more important to use 32 KiB.
For consistency, using 4 KiB seems reasonable.

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-19 21:10         ` Alejandro Colomar
@ 2023-02-19 21:12           ` Alejandro Colomar
  2023-02-20 14:29           ` Stefan Puiu
  1 sibling, 0 replies; 39+ messages in thread
From: Alejandro Colomar @ 2023-02-19 21:12 UTC (permalink / raw)
  To: Stefan Puiu; +Cc: Brian Inglis, Linux Man Pages


[-- Attachment #1.1: Type: text/plain, Size: 1243 bytes --]



On 2/19/23 22:10, Alejandro Colomar wrote:
> Hi Stefan,
> 
> On 2/17/23 15:05, Stefan Puiu wrote:
> [...]
> 
>>>>> diff --git a/man2/add_key.2 b/man2/add_key.2
>>>>> index 56fc6d198d21..215de20baeae 100644
>>>>> --- a/man2/add_key.2
>>>>> +++ b/man2/add_key.2
>>>>> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
>>>>>  .I type
>>>>>  or
>>>>>  .I description
>>>>> -exceeded the limit (32 bytes and 4096 bytes respectively).
>>>>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
>>>>
>>>> For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
>>>> anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?
>>>
>>> In this case, we should rather use 4\ KiB, which is standard.
>>
>> Maybe it is standard, but why is 4 KiB better / more suitable than 4096?
> 
> 4 KiB is not that much better than 4096, since 4096 is easy to read.
> For higher numbers such as 33554432, it becomes more important to use 32 KiB.

I meant 32 MiB, of course :)

> For consistency, using 4 KiB seems reasonable.
> 
> Cheers,
> 
> Alex
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-19 21:10         ` Alejandro Colomar
  2023-02-19 21:12           ` Alejandro Colomar
@ 2023-02-20 14:29           ` Stefan Puiu
  2023-02-20 15:35             ` Alex Colomar
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Puiu @ 2023-02-20 14:29 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: Brian Inglis, Linux Man Pages

Hi Alex,

On Sun, Feb 19, 2023 at 11:10 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Stefan,
>
> On 2/17/23 15:05, Stefan Puiu wrote:
> [...]
>
> >>>> diff --git a/man2/add_key.2 b/man2/add_key.2
> >>>> index 56fc6d198d21..215de20baeae 100644
> >>>> --- a/man2/add_key.2
> >>>> +++ b/man2/add_key.2
> >>>> @@ -167,7 +167,7 @@ The size of the string (including the terminating null byte) specified in
> >>>>  .I type
> >>>>  or
> >>>>  .I description
> >>>> -exceeded the limit (32 bytes and 4096 bytes respectively).
> >>>> +exceeded the limit (32 bytes and 4Ki bytes respectively).
> >>>
> >>> For what it's worth, I find 4096 much clearer over 4Ki (what is Ki
> >>> anyway?). Ditto for 32768 / 32Ki etc. What are we trying to achieve?
> >>
> >> In this case, we should rather use 4\ KiB, which is standard.
> >
> > Maybe it is standard, but why is 4 KiB better / more suitable than 4096?
>
> 4 KiB is not that much better than 4096, since 4096 is easy to read.
> For higher numbers such as 33554432, it becomes more important to use 32 KiB.
> For consistency, using 4 KiB seems reasonable.

How about using KiB / MiB over a certain number of digits? It seems
excessive to use them everywhere.

Also, for the record, I had no idea what KiB / MiB means and how it's
different from KB/MB until this discussion. I googled it before
writing this reply, and found this among the first hits:
https://ux.stackexchange.com/a/13850.

I would say making the docs easy to understand for users is more
important than adhering to some specs users might not be familiar
with.

Thanks,
Stefan.

>
> Cheers,
>
> Alex
>
> --
> <http://www.alejandro-colomar.es/>
> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-20 14:29           ` Stefan Puiu
@ 2023-02-20 15:35             ` Alex Colomar
  2023-02-21 17:00               ` Rob Landley
  0 siblings, 1 reply; 39+ messages in thread
From: Alex Colomar @ 2023-02-20 15:35 UTC (permalink / raw)
  To: Stefan Puiu, coreutils, Debian Install System Team
  Cc: Brian Inglis, Linux Man Pages, 1031275

[-- Attachment #1.1: Type: text/plain, Size: 2748 bytes --]

On 2/20/23 15:29, Stefan Puiu wrote:
> Hi Alex,

Hi Stefan,

>> 4 KiB is not that much better than 4096, since 4096 is easy to read.
>> For higher numbers such as 33554432, it becomes more important to use 32 KiB.
>> For consistency, using 4 KiB seems reasonable.
> 
> How about using KiB / MiB over a certain number of digits? It seems
> excessive to use them everywhere.

We might do that.  So far, I prefer having the patches change 
everything, and then we can later discuss about discarding part of them.

> 
> Also, for the record, I had no idea what KiB / MiB means and how it's
> different from KB/MB until this discussion. I googled it before
> writing this reply, and found this among the first hits:
> https://ux.stackexchange.com/a/13850.

That answer was written more than a decade ago.  These days, binary 
prefixes are more common.  In fact, I'd say most GNU/Linux commands 
respect them (an important exception being GNU coreutils (for example 
ls(1)).  But many programs use prefixes accurately, such as fdisk(8).

In the Linux man-pages we have units(7), which documents these.  Maybe 
that page should be more known.

BTW, that answer is inaccurate (at least today): drive manufacturers 
have the distinction pretty clear, and use it precisely (with lawsuits 
won thanks to this); they use metric prefixes, because they mean it. 
They can sell you 1 TB instead of 1 TiB, and most people won't even 
know, but those who know, will know that 1 TB is 1'000'000'000'000 B, 
which is what you get.  They have no incentives to sell 1 TiB drives, 
because they are visually almost the same, but there's around 9.95% more 
bytes, so it's more expensive to produce.  It's not worth it for them.

> 
> I would say making the docs easy to understand for users is more
> important than adhering to some specs users might not be familiar
> with.

Well, using MiB prompts readers to use their search engine to learn what 
that is (that's how I learnt it the first time; and that's what one does 
when reading a book and finding a new word).  I think that shouldn't be 
considered an impediment, but an opportunity to learn something new.

Once you know the difference, you appreciate the preciseness.  I hate 
when I see some software that uses the metric prefixes for meaning 
binary multipliers.  I also hate software that operates on bytes, when 
you almost always want binary multipliers but only have metric 
multipliers (hey partman, I mean you!).  I reported a bug to the Debian 
installer recently because it's very painful to partition a drive from it.

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-20 15:35             ` Alex Colomar
@ 2023-02-21 17:00               ` Rob Landley
  2023-02-22  1:34                 ` Alex Colomar
  0 siblings, 1 reply; 39+ messages in thread
From: Rob Landley @ 2023-02-21 17:00 UTC (permalink / raw)
  To: Alex Colomar, Stefan Puiu, coreutils, Debian Install System Team
  Cc: Brian Inglis, Linux Man Pages, 1031275

On 2/20/23 09:35, Alex Colomar wrote:
> On 2/20/23 15:29, Stefan Puiu wrote:
>> Hi Alex,
> 
> Hi Stefan,
> 
>>> 4 KiB is not that much better than 4096, since 4096 is easy to read.
>>> For higher numbers such as 33554432, it becomes more important to use 32 KiB.
>>> For consistency, using 4 KiB seems reasonable.
>> 
>> How about using KiB / MiB over a certain number of digits? It seems
>> excessive to use them everywhere.
> 
> We might do that.  So far, I prefer having the patches change 
> everything, and then we can later discuss about discarding part of them.

If you're going to tell people to learn something new: 1<<10 is a kilobyte,
1<<20 is a megabyte, 1<<30 is a gigabyte, and so on. I've sometimes used
16*(1<<30) for clarity.

>> Also, for the record, I had no idea what KiB / MiB means and how it's
>> different from KB/MB until this discussion.

Very few people do. Some people have been trying to make "fetch" happen for many
years, but it didn't. (Part of the reason is kibybyte/mebibyte/gibibyte are
minor tongue twisters, they're physically harder to say, so nobody does.)

>> I googled it before
>> writing this reply, and found this among the first hits:
>> https://ux.stackexchange.com/a/13850.
> 
> That answer was written more than a decade ago.  These days, binary 
> prefixes are more common.  In fact, I'd say most GNU/Linux commands

"First off, I'd suggest printing out a copy of the GNU coding standards,
and NOT read it.  Burn them, it's a great symbolic gesture." - Linus Torvalds

(Still there in Documentation/process/coding-style.rst.)

GNU has nothing to do with Linux, and never did. Stallman has a history of
taking credit for other people's work:

https://functional.cafe/@tfb/109897415359142549

> respect them (an important exception being GNU coreutils (for example 
> ls(1)).  But many programs use prefixes accurately, such as fdisk(8).
> 
> In the Linux man-pages we have units(7), which documents these.  Maybe 
> that page should be more known.

FYI Michael Kerrisk last updated https://github.com/mkerrisk in 2021. It is now
2023. He still posts monthly proof-of-life to
https://twitter.com/mkerrisk/with_replies but hasn't replied to man-pages email
in the past year that I am aware of?

Dunno why. I emailed to ask, but...

> BTW, that answer is inaccurate (at least today): drive manufacturers 
> have the distinction pretty clear, and use it precisely (with lawsuits 
> won thanks to this); they use metric prefixes, because they mean it. 
> They can sell you 1 TB instead of 1 TiB, and most people won't even 
> know, but those who know, will know that 1 TB is 1'000'000'000'000 B, 
> which is what you get.

Remember when the dictionaries gave in on "literally" meaning "an emphatic form
of figuratively"? What's the "kibybyte" equivalent we all switched to there for
clarity?

We say "metric ton" and "imperial ton". We say "degrees farenheit" and "degrees
celsius". The celsius people didn't come up with a different word for degree,
yet somehow we all survived...

> They have no incentives to sell 1 TiB drives, 
> because they are visually almost the same, but there's around 9.95% more 
> bytes, so it's more expensive to produce.  It's not worth it for them.

"No, a _bud_ lite..."

>> I would say making the docs easy to understand for users is more
>> important than adhering to some specs users might not be familiar
>> with.
> 
> Well, using MiB prompts readers to use their search engine to learn what 
> that is (that's how I learnt it the first time; and that's what one does 
> when reading a book and finding a new word).

"They'll google it" is the modern version of "they'll read the documentation".
They will not, you're just delegating blame.

Rob

P.S. Maybe this is a generational thing? Are the kids saying "kibibyte" in high
school these days? I know that "hacker means computer breakin specialist" is
something a small number of boomers will resist to the death despite a google
news search only pulling up one meaning in general usage. And the "two spaces
after period" thing old hands cling to will only end when they die despite the
chicago manual of style, the AP stylebook, the MLA handbook, and the APA
publication manual all agreeing its' been one space after a period for decades
now. But maybe "kibibyte" is more than a shibboleth to somebody somewhere...

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-21 17:00               ` Rob Landley
@ 2023-02-22  1:34                 ` Alex Colomar
  2023-02-22 22:18                   ` Rob Landley
  0 siblings, 1 reply; 39+ messages in thread
From: Alex Colomar @ 2023-02-22  1:34 UTC (permalink / raw)
  To: Rob Landley, coreutils, Debian Install System Team
  Cc: Brian Inglis, Linux Man Pages, 1031275, Stefan Puiu


[-- Attachment #1.1: Type: text/plain, Size: 9287 bytes --]

Hi Rob,

On 2/21/23 18:00, Rob Landley wrote:
> If you're going to tell people to learn something new: 1<<10 is a kilobyte,
> 1<<20 is a megabyte, 1<<30 is a gigabyte, and so on. I've sometimes used
> 16*(1<<30) for clarity.

That's nice, and for code it might be a good idea (although you have to 
be careful, since those are all ints, and 16*(1<<30) is going to 
overflow, so you'll need 16L).  For documentation, I don't think I like 
it that much.

> 
>>> Also, for the record, I had no idea what KiB / MiB means and how it's
>>> different from KB/MB until this discussion.
> 
> Very few people do. Some people have been trying to make "fetch" happen for many
> years, but it didn't.

What's "fetch"?

> (Part of the reason is kibybyte/mebibyte/gibibyte are
> minor tongue twisters, they're physically harder to say, so nobody does.)

I rarely talk about this stuff; more often, I write about it.  When I 
write, the shorthand MiB is nice (I never write mebibyte).  For talking, 
I say "megs" (or rather the Spanish equivalent "megas"), so being 
colloquial I can't be blamed, since I didn't really say megabytes.  If I 
say the technical term, which is rare, I try to be precise, and say 
mebibytes instead of megabytes.

> 
>>> I googled it before
>>> writing this reply, and found this among the first hits:
>>> https://ux.stackexchange.com/a/13850.
>>
>> That answer was written more than a decade ago.  These days, binary
>> prefixes are more common.  In fact, I'd say most GNU/Linux commands
> 
> "First off, I'd suggest printing out a copy of the GNU coding standards,
> and NOT read it.  Burn them, it's a great symbolic gesture." - Linus Torvalds

The GNU coding standards for writing C programs are horrible.  But they 
have very nice things in their standards.  Their standardization of 
Makefile targets and variables is quite nice, and I try to follow it 
closely.

> 
> (Still there in Documentation/process/coding-style.rst.)
> 
> GNU has nothing to do with Linux, and never did. Stallman has a history of
> taking credit for other people's work:

I never said so.  GNU is a set of userspace programs, Linux is a kernel, 
and GNU/Linux is the entire OS (or more precisely a relatively important 
part of it).  Most Linux distros are GNU/Linux distros, since user space 
is mostly GNU.  Since I was talking about user-space programs, GNU is 
even more appropriate than Linux, although I'm not sure about how much 
GNU conforms to these IEC prefixes, which is why I used GNU/Linux as 
more generic, referring to the entire set of programs that are included 
in such distros (e.g. Debian).

I CCed GNU coreutils so that they feel alluded and maybe improve their 
utils :)

> 
> https://functional.cafe/@tfb/109897415359142549
> 
>> respect them (an important exception being GNU coreutils (for example
>> ls(1)).  But many programs use prefixes accurately, such as fdisk(8).
>>
>> In the Linux man-pages we have units(7), which documents these.  Maybe
>> that page should be more known.
> 
> FYI Michael Kerrisk last updated https://github.com/mkerrisk in 2021.

That repo is just a mirror of the official repo at
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/>,
which I maintain.

> It is now
> 2023. He still posts monthly proof-of-life to
> https://twitter.com/mkerrisk/with_replies but hasn't replied to man-pages email
> in the past year that I am aware of?
> 
> Dunno why.

He's busy with his own business, and doesn't have time to continue 
maintaining the project.  It's a voluntary thing, so it's reasonable to 
be able to step out at any time.

Since 2020, I comaintained the project with Michael, and now I'm the 
only maintainer of the project.  To be more precise, let's quote the README:

Maintainers
        Alejandro Colomar <alx@kernel.org> 
<http://www.alejandro-colomar.es/>
              2020 - present (5.09 - HEAD)
        Michael Kerrisk <mtk.manpages@gmail.com> <https://man7.org/>
              2004 - 2021 (2.00 - 5.13)
        Andries Brouwer <aeb@cwi.nl> <https://www.win.tue.nl/~aeb>
              1995 - 2004    (1.6  - 1.70)
        Rik Faith <https://www.cs.unc.edu/~faith/>
              1993 - 1995    (1.0  - 1.5)


> I emailed to ask, but...
> 
>> BTW, that answer is inaccurate (at least today): drive manufacturers
>> have the distinction pretty clear, and use it precisely (with lawsuits
>> won thanks to this); they use metric prefixes, because they mean it.
>> They can sell you 1 TB instead of 1 TiB, and most people won't even
>> know, but those who know, will know that 1 TB is 1'000'000'000'000 B,
>> which is what you get.
> 
> Remember when the dictionaries gave in on "literally" meaning "an emphatic form
> of figuratively"? What's the "kibybyte" equivalent we all switched to there for
> clarity?
> 
> We say "metric ton" and "imperial ton". We say "degrees farenheit" and "degrees
> celsius". The celsius people didn't come up with a different word for degree,
> yet somehow we all survived...

Or you can say Kelvin ;)
In colloquial texts, or more appropriately in colloquial talking, 
degrees (without specifying), tons (same), or "megs", are fine, but for 
a manual, where we want precision (especially since we do mix decimal 
and binary multipliers often), I would strongly avoid misusing terms.

> 
>> They have no incentives to sell 1 TiB drives,
>> because they are visually almost the same, but there's around 9.95% more
>> bytes, so it's more expensive to produce.  It's not worth it for them.
> 
> "No, a _bud_ lite..."
> 
>>> I would say making the docs easy to understand for users is more
>>> important than adhering to some specs users might not be familiar
>>> with.
>>
>> Well, using MiB prompts readers to use their search engine to learn what
>> that is (that's how I learnt it the first time; and that's what one does
>> when reading a book and finding a new word).
> 
> "They'll google it" is the modern version of "they'll read the documentation".
> They will not, you're just delegating blame.

I can't imagine someone reading MiB in a manual page and not searching 
what that means (unless the reader doesn't care about that specific value).

> 
> Rob
> 
> P.S. Maybe this is a generational thing? Are the kids saying "kibibyte" in high
> school these days?

I don't think so.  Teachers usually don't know these prefixes either, I 
guess.

> I know that "hacker means computer breakin specialist" is
> something a small number of boomers will resist to the death despite a google
> news search only pulling up one meaning in general usage. And the "two spaces
> after period" thing old hands cling to will only end when they die despite the
> chicago manual of style, the AP stylebook, the MLA handbook, and the APA
> publication manual all agreeing its' been one space after a period for decades
> now.

They'll have to remove the second space from my cold dead fingers.  All 
those style guides are plain wrong.  I've read their rationales, and 
they make no sense at all.  Using one space is discarding information, 
and that is bad.  Let's list their reasons (AFAICS):

-  "It [2 spaces] doesn't look good."
	Subjective, and I disagree.

-  "We don't use monospace anymore, so it's not necessary to recognize 
the end of a sentence."
	It may be less necessary, but that doesn't make it bad.
	BTW, does that implicitly recognize that monospace should _always_ use 
2 spaces?  Thanks.
	Still with proportional font you can confuse sentence endings with 
initials in some cases (depending on the context), so 2 spaces is still 
necessary.

-  "2 spaces only increase reading speed for those used to them, and 
only marginally (according to studies)."
	Having a very small benefit is better than not having it.
	The fact that one-spacers are slower readers should raise questions.

-  "introducing two spaces after a sentence-ending period—and only after 
those periods—causes problems. Absolute consistency is easy to monitor 
when double spaces are never allowed, but less easy when some spaces 
after periods are double and others single"
	I guess the "problems" are the consistency thing referred in the second 
sentence...  Well, it's not inconsistency, it's just that different 
things are different.  I don't like oranges and tomatoes because they're 
inconsistent; one fruit is red and the other is orange...  Nonsense.

-  "Old English used 3-em space after period, but old Spanish or French 
didn't, in fact they often used 0 spaces after punctuation".
	So what?  Were they more readable thanks to that?  No.
	I've had to read old Spanish, and it's pretty painful.
	In fact, 3-em after period old English is quite readable.

-  "2-spacers are just imitating previous writers; they don't know what 
they're doing".
	Imitating wise old customs without knowing the rationale is not bad per 
se.  Deviating from them without a rationale is even worse.

...

Cheers,

Alex

> But maybe "kibibyte" is more than a shibboleth to somebody somewhere...

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-22  1:34                 ` Alex Colomar
@ 2023-02-22 22:18                   ` Rob Landley
  2023-02-24  1:05                     ` Alex Colomar
  0 siblings, 1 reply; 39+ messages in thread
From: Rob Landley @ 2023-02-22 22:18 UTC (permalink / raw)
  To: Alex Colomar, coreutils, Debian Install System Team
  Cc: Brian Inglis, Linux Man Pages, 1031275, Stefan Puiu

On 2/21/23 19:34, Alex Colomar wrote:
> Hi Rob,
> 
> On 2/21/23 18:00, Rob Landley wrote:
>> If you're going to tell people to learn something new: 1<<10 is a kilobyte,
>> 1<<20 is a megabyte, 1<<30 is a gigabyte, and so on. I've sometimes used
>> 16*(1<<30) for clarity.
> 
> That's nice, and for code it might be a good idea (although you have to 
> be careful, since those are all ints, and 16*(1<<30) is going to 
> overflow, so you'll need 16L).  For documentation, I don't think I like 
> it that much.

16LL on 32 bit systems, but from an "explain what the number is" perspective it
neatly avoids needing to specify a base or units. :)

>>>> Also, for the record, I had no idea what KiB / MiB means and how it's
>>>> different from KB/MB until this discussion.
>> 
>> Very few people do. Some people have been trying to make "fetch" happen for many
>> years, but it didn't.
> 
> What's "fetch"?

A pop culture reference: https://www.youtube.com/watch?v=Pubd-spHN-0

>> (Part of the reason is kibybyte/mebibyte/gibibyte are
>> minor tongue twisters, they're physically harder to say, so nobody does.)
> 
> I rarely talk about this stuff; more often, I write about it.  When I 
> write, the shorthand MiB is nice (I never write mebibyte).

I always read that TLA as "Men in Black", but I know what you mean.

> For talking, 
> I say "megs" (or rather the Spanish equivalent "megas"), so being 
> colloquial I can't be blamed, since I didn't really say megabytes.  If I 
> say the technical term, which is rare, I try to be precise, and say 
> mebibytes instead of megabytes.

I say "binary megabytes" the same way I say "degrees celsius".

>>>> I googled it before
>>>> writing this reply, and found this among the first hits:
>>>> https://ux.stackexchange.com/a/13850.
>>>
>>> That answer was written more than a decade ago.  These days, binary
>>> prefixes are more common.  In fact, I'd say most GNU/Linux commands
>> 
>> "First off, I'd suggest printing out a copy of the GNU coding standards,
>> and NOT read it.  Burn them, it's a great symbolic gesture." - Linus Torvalds
> 
> The GNU coding standards for writing C programs are horrible.  But they 
> have very nice things in their standards.  Their standardization of 
> Makefile targets and variables is quite nice, and I try to follow it 
> closely.

Hence cmake and ninja and so on.

>> (Still there in Documentation/process/coding-style.rst.)
>> 
>> GNU has nothing to do with Linux, and never did. Stallman has a history of
>> taking credit for other people's work:
> 
> I never said so. GNU is a set of userspace programs, Linux is a kernel, 
> and GNU/Linux is the entire OS (or more precisely a relatively important 
> part of it).

A busybox system isn't gnu, which means alpine linux isn't. Android using toybox
with a "no GPL in userspace policy" and built with llvm to avoid even the FSF's
compiler isn't gnu. So Linux on phones, and one of the standard docker distros,
actively _avoid_ using gnu. (These days, "systemd/linux" is probably at least as
accurate as "gnu/linux". I type that from devuan...)

> Most Linux distros are GNU/Linux distros, since user space 
> is mostly GNU.

Not really, no. Stallman constantly takes credit for other people's work (ala
the James Gosling interview video from last time). Here's the glibc maintainer
accusing stallman of a "hostile takeover of glibc development" 20 years ago:

https://sourceware.org/legacy-ml/libc-announce/2001/msg00000.html#:~:text=And%20now

There were similar political shenanigans to bring EGCS back under FSF control
back in the day (resulting in bad blood at the time), which is why projects like
LLVM carefully avoid having any FSF contamination in them.

When I was researching for a computer history book back in 2001 (ala
https://landley.net/history/mirror) I drove to Boston and interviewed Stallman
at MIT. He claimed credit for BSD having defended itself from AT&T's lawsuits,
which is not something anybody who was actually involved wrote in any of their
histories:

  https://www.oreilly.com/library/view/open-sources/1565925823/ch04.html

Free software was the NORM before 1983. 1970s computer magazines had BASIC
source code listings in the back, the CP/M users group northwest started its
public domain library in 1981 (ala
https://landley.net/history/mirror/cpm/cpmug.html), I learned C to participate
in the WWIV modding community (we didn't even have "patch", we had english
descriptions of what to do (really! https://landley.net/history/wwiv/ ). Project
Gutenberg was founded in 1971. The Hercules emultor runs that last public domain
release of OS/360 ala http://www.hercules-390.eu/hercfaq.html#2.02

In reality, copyright was extended to cover source code by the Berne convention
in 1976... which meant people published MORE source because binaries weren't
copyrightable and source had at least a little traction. Copyright was extended
to cover binaries by the 1983 Apple vs Franklin lawsuit, before which there WAS
no non-free software. (There was bespoke software, but that's not the same
thing.) Everybody suddenly closed up after that because the law had changed.
Here's IBM's 1983 "Object Code Only" announcement for example:

https://www.ibm.com/common/ssi/ShowDoc.wss?docURL=/common/ssi/rep_ca/6/897/ENUS283-016/index.html

Here's a 1980 audio recording of Bill Gates whining at a journalist that his
lobbying of congress to change copyright law hadn't produced results:

Context: http://maltedmedia.com/books/papers/sf-gates.html
transcript:
https://features.slashdot.org/story/00/01/20/1316236/b-gates-rants-about-software-copyrights---in-1980
Audio: https://landley.net/history/mirror/ms/gates.mp3

Gates couldn't do it (despite his widely mocked 1976 "letter to hobbyists"
trying to bluff people into doing what he wanted), but Steve Jobs could, and
then Gates benefitted more than  Jobs...

(The main difference between Gates and Jobs is William H Gates III had rich
parents and his mom was on the board of director of the Red Cross with the CEO
of IBM, so it was ok to give a lucrative contract to "Mary's Boy", but Steve was
an adopted kid working out of a garage who had to take venture capital to get
manufacturing off the ground, meaning Jobs lost control of his company within 5
years and Gates still owned 45% of microsoft's shared after the IPO. Also, Jobs
was good at industrial design and William H Gates III ("Trey" to his friends)
was a harvard law school dropout who specialized in negotiating exploitative
business contracts and monopoly leverage, so it didn't matter how terrible their
software was if motherboard manufacturers literally couldn't sell hardware that
did NOT come bundled with DOS+Windows.)

Anyway, Unix had already been cloned by then. The first clone passed an IP
challenge by AT&T's legal department somewhere around 1980:

  https://en.wikipedia.org/wiki/Coherent_(operating_system)
  https://groups.google.com/g/alt.folklore.computers/c/_ZaYeY46eb4/m/5B41Uym6d4QJ

AT&T's breakup shortly after Apple vs Franklin (to escape the 1953 consent
decree it operated under and thus commercialize its non-phone technology,
prominently including Unix) also denied Andrew Tanenbaum access to Unix V6 and
the Lions Book as a teaching tool (more or less following in Ken Thompson's
footsteps from his year off to teach at Berkeley in 1975 that gave rise to BSD),
so Tanenbaum wrote his own from-scratch clone called Minix was was not just
ready but self-hosting (including a kernel, compiler, shell, and command line
utilities, and it could rebuild itself under itself) in 3 years. And of course
the complete source code was on a floppy in the back of the textbook, because
that was the POINT...

Stallman's me-too announcement that he was gonna do the same thing as Coherent
and Minix and BSD-Tahoe and so on didn't really make much of a splash? Minix 1.0
came out in 1987, BSD-Tahoe came out in 1988, and a zillion others like
https://en.wikipedia.org/wiki/UNETix and https://en.wikipedia.org/wiki/DNIX and
so on happened long before Linux. GNU never shipped anything usable. Linux was
designed and built under Minix, its first filesystem format was minix, etc.

What stallman DID have was ftp.ai.mit.edu, back when commercial access to the
internet was forbidden due to the DARPA funding, and thus hosting a site
required a government, military, or educational connection. That's why Larry
wall handed over his "patch" program to gnu, despite happily supporting perl on
windows for decades. He didn't care about Stallman's crusade, he just jumped
through the hoops necessary to get hosting back when that wasn't something you
could purchase.

When the NSF's 1993 change to its Acceptable Use Policy allowed commercial
access to the internet (resulting in AOL jumping online and the "september that
never ended"), Stallman's importance RAPIDLY receded. The FSF has collapsed like
a balloon since 1993 because it turns out most people just wanted their code on
an FTP server, and all that nonsense about signing over your copyrights wasn't
worth it once geocities existed. (Let alone sourceforge. Let alone github.)

The "Cathedral" in the 1997 usenix paper "The Cathedral And The Bazaar" was the
FSF's GNU project. No really, the abstract of the paper says as much
(https://www.usenix.org/conference/1998-usenix-annual-technical-conference/software-development-models-cathedral-and-bazaar)
and the paper's author was the maintainer of the Emacs LISP library, who found
himself on the "outside" of the project and unable to sufficiently participate
because he hadn't gone to MIT and didn't live in Boston.

> I CCed GNU coreutils so that they feel alluded and maybe improve their 
> utils :)

I'm still on that mailing list until they merge cut -DF.

I'm not generally trying to improve coreutils, I'm working to replace it. I have
some history here myself: I used to maintain busybox, currently maintain toybox
(which became Android's command line in 2015), started the first GPL enforcement
suits in the USA, got invited by Eben Moglen to come to NYC to speak with a
bunch of lawyers about copyleft licensing in 2008, have spoken on this topic at
various conferences (Kirk McKusick was in the audience for
https://archive.org/details/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.flac
and said he quite enjoyed it)...

I wince at people saying "gnu/linux" because I still feel a somewhat responsible
for the gnu/linux crusade that Stallman's been on since I tried to explain
marketing to him back in 1998 and it... didn't go in the direction I expected:
http://www.kerneltraffic.org/kernel-traffic/kt20020805_178.html#1

At least three times in my career I basically yodeled and could not control the
resulting avalanche...

>> https://functional.cafe/@tfb/109897415359142549
>> 
>>> respect them (an important exception being GNU coreutils (for example
>>> ls(1)).  But many programs use prefixes accurately, such as fdisk(8).
>>>
>>> In the Linux man-pages we have units(7), which documents these.  Maybe
>>> that page should be more known.
>> 
>> FYI Michael Kerrisk last updated https://github.com/mkerrisk in 2021.
> 
> That repo is just a mirror of the official repo at
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/>,
> which I maintain.

You've taken over from Michael Kerrisk then? I should inform
https://www.openwall.com/lists/musl/2022/11/30/2#:~:text=biggest%20problem and
friends...

>> It is now
>> 2023. He still posts monthly proof-of-life to
>> https://twitter.com/mkerrisk/with_replies but hasn't replied to man-pages email
>> in the past year that I am aware of?
>> 
>> Dunno why.
> 
> He's busy with his own business, and doesn't have time to continue 
> maintaining the project.  It's a voluntary thing, so it's reasonable to 
> be able to step out at any time.
> 
> Since 2020, I comaintained the project with Michael, and now I'm the 
> only maintainer of the project.  To be more precise, let's quote the README:
> 
> Maintainers
>         Alejandro Colomar <alx@kernel.org> 
> <http://www.alejandro-colomar.es/>
>               2020 - present (5.09 - HEAD)
>         Michael Kerrisk <mtk.manpages@gmail.com> <https://man7.org/>
>               2004 - 2021 (2.00 - 5.13)
>         Andries Brouwer <aeb@cwi.nl> <https://www.win.tue.nl/~aeb>
>               1995 - 2004    (1.6  - 1.70)
>         Rik Faith <https://www.cs.unc.edu/~faith/>
>               1993 - 1995    (1.0  - 1.5)

Good to know. (I just randomly stopped getting the emailed updates...)

Ah, there you are on https://www.kernel.org/doc/man-pages/maintaining.html

>> I emailed to ask, but...
>> 
>>> BTW, that answer is inaccurate (at least today): drive manufacturers
>>> have the distinction pretty clear, and use it precisely (with lawsuits
>>> won thanks to this); they use metric prefixes, because they mean it.
>>> They can sell you 1 TB instead of 1 TiB, and most people won't even
>>> know, but those who know, will know that 1 TB is 1'000'000'000'000 B,
>>> which is what you get.
>> 
>> Remember when the dictionaries gave in on "literally" meaning "an emphatic form
>> of figuratively"? What's the "kibybyte" equivalent we all switched to there for
>> clarity?
>> 
>> We say "metric ton" and "imperial ton". We say "degrees farenheit" and "degrees
>> celsius". The celsius people didn't come up with a different word for degree,
>> yet somehow we all survived...
> 
> Or you can say Kelvin ;)

And when the weather reports start giving temperatures in kelvin... they would
still say "degrees", wouldn't they? It's 267 degrees in Minneapolis today...

Gigabytes can be in base 10 or base 2. They're still gigabytes.

> In colloquial texts, or more appropriately in colloquial talking, 
> degrees (without specifying), tons (same), or "megs", are fine, but for 
> a manual, where we want precision (especially since we do mix decimal 
> and binary multipliers often), I would strongly avoid misusing terms.

*shrug* If you're maintainer, it's your call. I've said my piece.

>> "They'll google it" is the modern version of "they'll read the documentation".
>> They will not, you're just delegating blame.
> 
> I can't imagine someone reading MiB in a manual page and not searching 
> what that means (unless the reader doesn't care about that specific value).

It's _possible_ the man page maintainer is not, in isolation, a fully rounded
representative sample on this issue?

>> Rob
>> 
>> P.S. Maybe this is a generational thing? Are the kids saying "kibibyte" in high
>> school these days?
> 
> I don't think so.  Teachers usually don't know these prefixes either, I 
> guess.

Do you expect to change global language usage patterns or just make the man
pages less relevant to their intended audience?

>> I know that "hacker means computer breakin specialist" is
>> something a small number of boomers will resist to the death despite a google
>> news search only pulling up one meaning in general usage. And the "two spaces
>> after period" thing old hands cling to will only end when they die despite the
>> chicago manual of style, the AP stylebook, the MLA handbook, and the APA
>> publication manual all agreeing its' been one space after a period for decades
>> now.
> 
> They'll have to remove the second space from my cold dead fingers.

That's exactly how the change will happen, yes. This was published 9 years ago:

https://www.cultofpedagogy.com/two-spaces-after-period/

> All 
> those style guides are plain wrong.  I've read their rationales, and 
> they make no sense at all.  Using one space is discarding information, 
> and that is bad.

Blame Tim Berners-Lee. The cultural shift started when HTML rendered all runs of
whitespace as a single space back in 1991. People write what they read.

The web's S-curve of adoption went vertical by 1993 (the NSF AUP switch was
actually a trailing indicator by at least a year, "the well" and such were
already doing grey-zone dialup ISPs as "nonprofits with donations to cover
expenses", and lots of people maintained alumni accounts at college or dialed in
to work after work; AOL suddenly becoming the biggest ISP was noticeable, but
not causative), kellog's started putting its URL on its cereal boxes in 1995.
Shortly before McNeil retired from the McNeil/Lehrer news hour, the ending
credits about sending letters to the editor apologized for having said "snail
mail" the previous day when introducing their email address as a way to contact
them, that was also 1995 I believe? The first phone with web access was the
Nokia 9000 in 1996, Yahoo went public in 1996. (I was apparently the first
financial journalist to cover Google in 1998 and I still have the stickers they
sent me.) The dot-com crash was big news in 2001. The "one billion people
online" articles were ~2005. The first modern smartphones ~2008. The UN report
about more people having smartphones than flush toilets was 2013.

People who learned to type before Y2K had two spaces drilled into them, often on
a manual typewriter, but that stopped being the case about the start of the
dubyah administration, and the standards bodies caught up to normal practice a
few years later. I had to retrain myself to stop doing it in... let's see,
https://landley.net/notes-2011.html has two spaces in the last entry, and
https://landley.net/notes-2012.html had one. So just over 10 years ago. And I am
a VERY late adopter of this sort of thing...

*shrug* Computer history's been a hobby of mine since the 1990s. I like to root
cause things, and dig up WHY they happened, to have proper context to decide
what to do about them.

> Let's list their reasons (AFAICS):

People got used to reading web pages, which rendered with one space.

There may have been additional justifications for the decision already made, but
those were basically excuses.

> 	I guess the "problems" are the consistency thing referred in the second 
> sentence...  Well, it's not inconsistency, it's just that different 
> things are different.  I don't like oranges and tomatoes because they're 
> inconsistent; one fruit is red and the other is orange...  Nonsense.

I got an english minor in college, and one of the things it drilled into me is
if it's correct and nobody does it, it's not correct. The divergence between
"proper" and "common usage" only persists when it's a class-based indicator used
to exclude "those people" from "polite society". You could or couldn't afford to
get the silver ring with the skull on it, and thus know how to point your pinky
and sort forks when having tea with toffs.

Sometimes there were reasons: Latin physically CAN'T split infinitives (they're
not multiple words), so anything translated from latin looks more like the latin
when it keeps the two words together, and when reading things in "the original
latin" is a valuable skill splitting infinitives sticks out as uneducated in a
"you don't know how it works" way, and is held in place by inertia for a while
after that...

Then a single television show goes "to boldly split infinitives that no man has
split before" and goes into constant reruns (desilu productions = desi arnez +
lucille ball, VERY good at the syndication thing) and then has a hit movie come
out where a character who just died recites it as a poignant memorial to himself
just before the closing credits, and THEN a successor/revival series changes
"man" to "one" but does not move the "boldly"... and the rule is quietly retired
because it _lost_.

English! It's a mess. We jettisoned the second person singular because british
nobility started copying the queen (who spoke for the nation, thus always in the
"we are not amused" plural) and it moved downhill until eventually addressing
someone else as thou was fighting words because it meant you considered the
person you were addressing your social inferior (yes the Amish got physically
attacked for this, it's part of the reason they moved). This is also one of
those subtleties in shakespeare, the way he uses "thou" as an insult, because
the transition was ongoing in his time:

https://drmarkwomack.com/engl-3306/handouts/shakespeares-language/thou-and-you-in-shakespeare/

The "great vowel shift" was similar (albeit less well documented) class-based
shenanigans.

> -  "Old English used 3-em space after period, but old Spanish or French 
> didn't, in fact they often used 0 spaces after punctuation".
> 	So what?  Were they more readable thanks to that?  No.

https://en.wikipedia.org/wiki/Scriptio_continua

It was an invention.

> -  "2-spacers are just imitating previous writers; they don't know what 
> they're doing".
> 	Imitating wise old customs without knowing the rationale is not bad per 
> se.  Deviating from them without a rationale is even worse.

Which is why I study history.

And I go back and correct my old stuff when I learn better:
https://www.osnews.com/story/25556/understanding-the-bin-sbin-usrbin-usrsbin-split/
was written off the top of my head and I got a couple details wrong (the fast
system disk was 0.5 mb, the 2 rk05 disk packs were 2.5 mb each), and when
https://landley.net/writing/hackermonthly-issue022-pg33.pdf asked to republish
the article I sent them an updated version with bibliographic references. :)

But when I can say WHY something shifted, and that what's already happened at
_best_ underwent a hysteresis transition between metastable states and is now
firmly entrenched in a different local minima... I generally don't waste TOO
much effort trying to push it back all by myself?

I cannot stop people from saying "nucyoolar".
(https://www.nytimes.com/2002/10/13/weekinreview/confronting-noo-kyuh-luhr-proliferation.html
blames eisenhower but he learned it from classified military briefings, meaning
there's a specific military idiot who broke it and we dunno who. Oh well. I
haven't found a recording of Truman saying nuclear, he said "atomic".) Then
again Gigabyte beat out "jigawatt". Gif and Jif are basically soda vs pop
regional variants. Linus Torvalds literally sent people a RECORDING to move
"lienux" to "linux" (which was Red Hat's audio test during setup back when they
had over 50% desktop market share, before the people brought in for the IPO
explained how to eat Sun's lunch).

But do I expect kibibytes to take off? Not really, no. Could be wrong, but...

Rob

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [PATCH v3 1/6] man2/: use IEC or ISO multiples to clarify long numeric digit strings
  2023-02-22 22:18                   ` Rob Landley
@ 2023-02-24  1:05                     ` Alex Colomar
  0 siblings, 0 replies; 39+ messages in thread
From: Alex Colomar @ 2023-02-24  1:05 UTC (permalink / raw)
  To: Rob Landley, coreutils, Debian Install System Team
  Cc: Brian Inglis, Linux Man Pages, 1031275, Stefan Puiu


[-- Attachment #1.1: Type: text/plain, Size: 9160 bytes --]

Hi Rob,

On 2/22/23 23:18, Rob Landley wrote:
> 16LL on 32 bit systems, but from an "explain what the number is" perspective it
> neatly avoids needing to specify a base or units. :)

Right.

>> What's "fetch"?
> 
> A pop culture reference: https://www.youtube.com/watch?v=Pubd-spHN-0

:p

>>> (Part of the reason is kibybyte/mebibyte/gibibyte are
>>> minor tongue twisters, they're physically harder to say, so nobody does.)
>>
>> I rarely talk about this stuff; more often, I write about it.  When I
>> write, the shorthand MiB is nice (I never write mebibyte).
> 
> I always read that TLA as "Men in Black", but I know what you mean.
$ wtf is TLA
TLA: three letter acronym
true love always

:)

> 
> I say "binary megabytes"

That's valid, I think.  And if it's not, everyone would understand.

 > the same way I say "degrees celsius".


>> The GNU coding standards for writing C programs are horrible.  But they
>> have very nice things in their standards.  Their standardization of
>> Makefile targets and variables is quite nice, and I try to follow it
>> closely.
> 
> Hence cmake and ninja and so on.

Uhh, no, thanks!

> 
>>> (Still there in Documentation/process/coding-style.rst.)
>>>
>>> GNU has nothing to do with Linux, and never did. Stallman has a history of
>>> taking credit for other people's work:
>>
>> I never said so. GNU is a set of userspace programs, Linux is a kernel,
>> and GNU/Linux is the entire OS (or more precisely a relatively important
>> part of it).
> 
> A busybox system isn't gnu, which means alpine linux isn't. Android using toybox
> with a "no GPL in userspace policy" and built with llvm to avoid even the FSF's
> compiler isn't gnu. So Linux on phones, and one of the standard docker distros,
> actively _avoid_ using gnu. (These days, "systemd/linux" is probably at least as
> accurate as "gnu/linux".

Yeah, any of them is fine IMO.  I write from a GNU/Linux distro, but I 
admit that I should have maybe said "most programs in Unix-like systems 
these days use IEC prefixes".

> I type that from devuan...)

Me too :)

>> I CCed GNU coreutils so that they feel alluded and maybe improve their
>> utils :)
> 
> I'm still on that mailing list until they merge cut -DF.

What would that do?


> You've taken over from Michael Kerrisk then? I should inform
> https://www.openwall.com/lists/musl/2022/11/30/2#:~:text=biggest%20problem and
> friends...

I guess many should already know.  But yes, feel free to inform.

>> Since 2020, I comaintained the project with Michael, and now I'm the
>> only maintainer of the project.  To be more precise, let's quote the README:
>>
>> Maintainers
>>          Alejandro Colomar <alx@kernel.org>
>> <http://www.alejandro-colomar.es/>
>>                2020 - present (5.09 - HEAD)
>>          Michael Kerrisk <mtk.manpages@gmail.com> <https://man7.org/>
>>                2004 - 2021 (2.00 - 5.13)
>>          Andries Brouwer <aeb@cwi.nl> <https://www.win.tue.nl/~aeb>
>>                1995 - 2004    (1.6  - 1.70)
>>          Rik Faith <https://www.cs.unc.edu/~faith/>
>>                1993 - 1995    (1.0  - 1.5)
> 
> Good to know. (I just randomly stopped getting the emailed updates...)
> 
> Ah, there you are on https://www.kernel.org/doc/man-pages/maintaining.html

Yep :)


>> Or you can say Kelvin ;)
> 
> And when the weather reports start giving temperatures in kelvin... they would
> still say "degrees", wouldn't they? It's 267 degrees in Minneapolis today...

To be pedantic, and quoting the SI brochure v9: "* The unit name “degree
kelvin” was changed to “kelvin” in 1967 by the 13th CGPM (Resolution 3,
see p. 169)."

So you should say kelvins, not degrees kelvin.

<https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf/2d2b50bf-f2b4-9661-f402-5f9d66e4b507?version=1.11&t=1671101192839&download=true#%5B%7B%22num%22%3A372%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22Fit%22%7D%5D>
Page 163 (49 in the PDF).

> 
> Gigabytes can be in base 10 or base 2. They're still gigabytes.
> 
>> In colloquial texts, or more appropriately in colloquial talking,
>> degrees (without specifying), tons (same), or "megs", are fine, but for
>> a manual, where we want precision (especially since we do mix decimal
>> and binary multipliers often), I would strongly avoid misusing terms.
> 
> *shrug* If you're maintainer, it's your call. I've said my piece.
> 
>>> "They'll google it" is the modern version of "they'll read the documentation".
>>> They will not, you're just delegating blame.
>>
>> I can't imagine someone reading MiB in a manual page and not searching
>> what that means (unless the reader doesn't care about that specific value).
> 
> It's _possible_ the man page maintainer is not, in isolation, a fully rounded
> representative sample on this issue?

It's possible, but I have my doubts in this case.

By chance, I was having a look at a computer that had RedHat Openshift 
open, and the system resources usage view used IEC multipliers (men in 
black units).

`free -h` also uses them.  The top(1) manual page also uses "kibibytes" 
and other such expanded words.

> 
>>> Rob
>>>
>>> P.S. Maybe this is a generational thing? Are the kids saying "kibibyte" in high
>>> school these days?
>>
>> I don't think so.  Teachers usually don't know these prefixes either, I
>> guess.
> 
> Do you expect to change global language usage patterns or just make the man
> pages less relevant to their intended audience?

Honestly, I expect the former.  Not single-handedly, but rather I feel 
supported by a lot of (very common) software out there.  I understand 
it's not everywhere, but also it's not as if it didn't exist prior to me.

As for the Linux man-pages, at least a few already use these (prior to 
me, I believe, since I don't remember changing that):

$ grep -rl -e KiB -e MiB -e GiB man*/
man2/ioctl_getfsmap.2
man2/process_vm_readv.2
man2/add_key.2
man2/execve.2
man2/getrlimit.2
man2/ioctl_fideduperange.2
man2/kexec_load.2
man2/alloc_hugepages.2
man3/btree.3
man4/fd.4
man4/loop.4
man5/proc.5
man7/pipe.7
man7/keyrings.7
man7/units.7

$ grep -rn kibi
man5/tmpfs.5:60:suffix for Ki, Mi, Gi (binary kilo (kibi), binary mega 
(mebi), and binary giga
man2/msgctl.2:216:    int msgpool; /* Size in kibibytes of buffer pool
man7/units.7:58:Ki	kibi	2^10 = 1024
man7/units.7:104:the MB are megabytes and the KiB are kibibytes.

>> They'll have to remove the second space from my cold dead fingers.
> 
> That's exactly how the change will happen, yes. This was published 9 years ago:
> 
> https://www.cultofpedagogy.com/two-spaces-after-period/

It's funny, I'm still in my twenties.  :p

> 
>> All
>> those style guides are plain wrong.  I've read their rationales, and
>> they make no sense at all.  Using one space is discarding information,
>> and that is bad.
> 
> Blame Tim Berners-Lee. The cultural shift started when HTML rendered all runs of
> whitespace as a single space back in 1991. People write what they read.

Actually, it comes from much earlier than that.  Have a look at
<https://web.archive.org/web/20171107164742/http://www.heracliteanriver.com/?p=324>

The real reason seems to be that single spaces lowered the quality of 
required editors, and thus prices.  It's all about the money.

>> 	I guess the "problems" are the consistency thing referred in the second
>> sentence...  Well, it's not inconsistency, it's just that different
>> things are different.  I don't like oranges and tomatoes because they're
>> inconsistent; one fruit is red and the other is orange...  Nonsense.
> 
> I got an english minor in college, and one of the things it drilled into me is
> if it's correct and nobody does it, it's not correct.

I do agree with that.  The thing here is that I disagree about it not 
being used.  If you look at many commonly-used programs, you'll see it 
all over the place: top(1), free(1), fdisk(1), ...

> 
> English! It's a mess. We jettisoned the second person singular because british
> nobility started copying the queen (who spoke for the nation, thus always in the
> "we are not amused" plural) and it moved downhill until eventually addressing
> someone else as thou was fighting words because it meant you considered the
> person you were addressing your social inferior (yes the Amish got physically
> attacked for this, it's part of the reason they moved). This is also one of
> those subtleties in shakespeare, the way he uses "thou" as an insult, because
> the transition was ongoing in his time:

Ahhh, thou is 2nd singular!  That explains many things :).  I learnt 
something new today.

> 
> https://drmarkwomack.com/engl-3306/handouts/shakespeares-language/thou-and-you-in-shakespeare/

> 
> But do I expect kibibytes to take off? Not really, no. Could be wrong, but...

I hope you're wrong in this one.  ;)

> 
> Rob

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

end of thread, other threads:[~2023-02-24  1:05 UTC | newest]

Thread overview: 39+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-02-15 20:15 [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples to clarify long numeric digit strings Brian Inglis
2023-02-15 20:17 ` Brian Inglis
2023-02-15 20:17 ` [PATCH v3 1/6] man2/: use IEC " Brian Inglis
2023-02-15 21:05   ` Alejandro Colomar
2023-02-16 21:06   ` Stefan Puiu
2023-02-16 23:01     ` Alejandro Colomar
2023-02-16 23:40       ` Brian Inglis
2023-02-16 23:51         ` Alejandro Colomar
2023-02-17 14:05       ` Stefan Puiu
2023-02-19 21:10         ` Alejandro Colomar
2023-02-19 21:12           ` Alejandro Colomar
2023-02-20 14:29           ` Stefan Puiu
2023-02-20 15:35             ` Alex Colomar
2023-02-21 17:00               ` Rob Landley
2023-02-22  1:34                 ` Alex Colomar
2023-02-22 22:18                   ` Rob Landley
2023-02-24  1:05                     ` Alex Colomar
2023-02-16 21:40   ` Jakub Wilk
2023-02-15 20:17 ` [PATCH v3 2/6] man2/keyctl.2: use IEC or ISO multiples or add C digit separators " Brian Inglis
2023-02-15 21:06   ` Alejandro Colomar
2023-02-15 20:17 ` [PATCH v3 3/6] man2/: add C digit separators to clarify POSIX feature release dates Brian Inglis
2023-02-15 21:08   ` Alejandro Colomar
2023-02-16 21:11   ` Stefan Puiu
2023-02-16 23:04     ` Alejandro Colomar
2023-02-17 14:16       ` Stefan Puiu
2023-02-15 20:17 ` [PATCH v3 4/6] man2/select.2: add C digit separators to clarify POSIX feature release dates or use IEC or ISO multiples to clarify long numeric digit strings Brian Inglis
2023-02-15 21:09   ` Alejandro Colomar
2023-02-15 20:17 ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and " Brian Inglis
2023-02-15 21:10   ` Alejandro Colomar
2023-02-18 17:42     ` Tom Schwindl
2023-02-18 18:08       ` G. Branden Robinson
2023-02-18 18:31         ` Tom Schwindl
2023-02-18 19:03           ` G. Branden Robinson
2023-02-18 23:32             ` Brian Inglis
2023-02-19 11:50             ` ADA and base prefix for numbers Alejandro Colomar
2023-02-18 18:41       ` [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings Brian Inglis
2023-02-15 20:17 ` [PATCH v3 6/6] man2/: add C digit separators to clarify " Brian Inglis
2023-02-15 21:14   ` Alejandro Colomar
2023-02-15 22:51 ` [PATCH v3 0/6] man2/: use C digit separators, IEC, or ISO multiples " Brian Inglis

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox