On 2023-01-29 14:19, Alejandro Colomar wrote:
On 1/29/23 22:04, Brian Inglis wrote:
On 2023-01-29 07:38, Alejandro Colomar wrote:
On 1/28/23 21:40, Brian Inglis wrote:
Seeing the recent tv_nsec patches drop the standard locale digit grouping
characters "," from the member range [0-999,999,999] made me regret the loss
of the punctuation which provides better and quicker comprehension of long
strings of digits.
Nice! Didn't remember about that separator. It makes a lot of sense to use
it in comments and the likes in the pages. Maybe we should be a bit more
cautious in source code examples, but definitely for big numbers outside of
running code should have them.
Since most people would be compiling on default settings, I prefer avoiding
that. When c23 is finally released, and GCC switches to gnu23 by default, I'd
also use it in example programs. Does it make sense to you?
It may be time to consider using the locale independent C23 digit
separator characters "'" wherever more than a handful of digits occur,
possibly convert grouping character uses in existing man pages as they are
changed, and specify a future standard policy approach to provide better
and quicker comprehension of long strings of digits: perhaps using a new
digit separator register and glyph escape sequence \*ds \*[ds] \[ds] \(ds
if not in use by base groff?
The sequence for the unslanted single quote is \(aq.
We have little semantic things in man(7), as opposed to mdoc(7). I think it
will be simpler to just use \(aq.
We could add somewhere in man-pages(7) that decimal numbers should use a
and octal e.g. perms
separator every 3 digits, and hex and binary should use it every 4 digits >> As well as the 3 decimal, 4 binary/hex, we could use yyyy'mm['dd]L for POSIX
and similar date digit strings, and 0x10'ffff for Unicode code points,
distinguishing between the Basic and Supplementary Multilingual Plane indices
and codes, just as examples from what I've seen so far.
I've also noticed a lot of apparently random decimal digit strings that are
binary powers or close deltas: those would be more comprehensible if rendered
in text as Ki/Mi/Gi[+/-n], so would that be preferable, using the IEC i suffix
to avoid ambiguity?
In running text, I'd do it case by case. In some cases I guess that'll make
sense. In others, 2^32 will make more sense... But yes, big magic fatnums are
not nice.
Hi Alex,
Took your views on board and changed man2 pages.
Attached summary only has file names and changed lines.
Would like feedback on what to continue doing and what to forget doing before
starting man3?
Of note for review are open.2 octal perms, reboot.2 LINUX_REBOOT_MAGIC* adding
hex birth dates (arguably should remove the decimals, or all values, and cryptic
comment from doc?), statsf.2 hex *_MAGIC, changing large arbitrary values to
SI/IEC suffix forms (as the exact decimal values are not as informative or
useful), and feature docs using yyyy\(aqmmL (no example *code* was changed,
although comments were).
--
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
diff --git a/man2/add_key.2 b/man2/add_key.2
-of up to 32,767 bytes.
+of up to 32\(aq767 bytes.
diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
-the supplied value is clamped to the range (\-32768000, +32768000).
+the supplied value is clamped to the range (\-31.25Mi, +31.25Mi).
-to a value outside the range (\-33554432, +33554432).
+to a value outside the range (\-32Mi, +32Mi).
-Before Linux 2.0, the permitted range was (\-131072, +131072).
-From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
+Before Linux 2.0, the permitted range was (\-128Ki, +128Ki).
+From Linux 2.0 onwards, the permitted range was (\-512k, +512k).
-.RB 900000/ HZ
+.RB 900k/ HZ
-.RB 1100000/ HZ ,
+.RB 1\(aq100k/ HZ ,
diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
-is outside the range [0..999,999,999].
+is outside the range [0..999\(aq999\(aq999].
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
-field was not in the range 0 to 999999999 or
+field was not in the range 0 to 999\(aq999\(aq999 or
diff --git a/man2/eventfd.2 b/man2/eventfd.2
-unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
+unsigned 64-bit value minus 1 (i.e., 0xffff\(aqffff\(aqffff\(aqfffe).
-or if an attempt is made to write the value 0xffffffffffffffff.
+or if an attempt is made to write the value 0xffff\(aqffff\(aqffff\(aqffff.
-value (i.e., 0xffffffffffffffff).
+value (i.e., 0xffff\(aqffff\(aqffff\(aqffff).
diff --git a/man2/execve.2 b/man2/execve.2
-and the maximum number of strings is 0x7FFFFFFF.
+and the maximum number of strings is 0x7FFF\(aqFFFF.
diff --git a/man2/fcntl.2 b/man2/fcntl.2
-with the value 200809L or greater.)
+with the value 2008\(aq09L or greater.)
-with the value 200809L or greater, or
+with the value 2008\(aq09L or greater, or
diff --git a/man2/futex.2 b/man2/futex.2
-was not less than 1,000,000,000).
+was not less than 1\(aq000\(aq000\(aq000).
diff --git a/man2/getitimer.2 b/man2/getitimer.2
-contains a value outside the range 0 to 999999.
+contains a value outside the range 0 to 999\(aq999.
-value is specified that is outside of the range 0 to 999999.
+value is specified that is outside of the range 0 to 999\(aq999.
diff --git a/man2/getrandom.2 b/man2/getrandom.2
-source, a maximum of 33554431 bytes is returned by a single call to
+source, a maximum of 32Mi-1 bytes is returned by a single call to
diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2
-is outside the range [0..999,999].
+is outside the range [0..999\(aq999].
diff --git a/man2/ioctl.2 b/man2/ioctl.2
-0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and
+0x00\(aq00\(aq54\(aq01, with 0x54 = \(aqT\(aq indicating the terminal driver, and
-has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
+has value 0x00\(aq43\(aq59\(aq06, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
-= 1193180/frequency).
+= 1\(aq193\(aq180/frequency).
diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
-For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will
+For example, if the low key is set to (8:0, 36\(aq864, 0, 0, 0), the filesystem will
-If the high key is set to (8:0, 1048576, 0, 0, 0),
+If the high key is set to (8:0, 1\(aq048\(aq576, 0, 0, 0),
diff --git a/man2/ioperm.2 b/man2/ioperm.2
-Since Linux 2.6.8, 65,536 I/O ports can be specified.
+Since Linux 2.6.8, 65\(aq536 I/O ports can be specified.
diff --git a/man2/kexec_load.2 b/man2/kexec_load.2
-The high-order bits (corresponding to the mask 0xffff0000) of
+The high-order bits (corresponding to the mask 0xffff\(aq0000) of
diff --git a/man2/link.2 b/man2/link.2
-feature, the limit on the number of hard links to a file is 65,000; on
+feature, the limit on the number of hard links to a file is 65\(aq000; on
-the limit is 65,535 links.
+the limit is 65\(aq535 links.
diff --git a/man2/msgget.2 b/man2/msgget.2
-Since Linux 3.19, the default value is 32,000.
+Since Linux 3.19, the default value is 32\(aq000.
diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
-The value of the nanoseconds field must be in the range 0 to 999999999.
+The value of the nanoseconds field must be in the range 0 to 999\(aq999\(aq999.
-field was not in the range 0 to 999999999 or
+field was not in the range 0 to 999\(aq999\(aq999 or
diff --git a/man2/open.2 b/man2/open.2
-00700 user (file owner) has read, write, and execute permission
+00\(aq700 user (file owner) has read, write, and execute permission
-00400 user has read permission
+00\(aq400 user has read permission
-00200 user has write permission
+00\(aq200 user has write permission
-00100 user has execute permission
+00\(aq100 user has execute permission
-00070 group has read, write, and execute permission
+00\(aq070 group has read, write, and execute permission
-00040 group has read permission
+00\(aq040 group has read permission
-00020 group has write permission
+00\(aq020 group has write permission
-00010 group has execute permission
+00\(aq010 group has execute permission
-00007 others have read, write, and execute permission
+00\(aq007 others have read, write, and execute permission
-00004 others have read permission
+00\(aq004 others have read permission
-00002 others have write permission
+00\(aq002 others have write permission
-00001 others have execute permission
+00\(aq001 others have execute permission
-0004000 set-user-ID bit
+0\(aq004\(aq000 set-user-ID bit
-0002000 set-group-ID bit (see
+0\(aq002\(aq000 set-group-ID bit (see
-0001000 sticky bit (see
+0\(aq001\(aq000 sticky bit (see
-with a value greater than or equal to 200809L or
+with a value greater than or equal to 2008\(aq09L or
diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2
-memory offset (for things like prep, this is 0xc0000000),
+memory offset (for things like prep, this is 0xc000\(aq0000),
diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
-100000 (samples per second).
+100\(aq000 (samples per second).
diff --git a/man2/personality.2 b/man2/personality.2
-0xffffffff, then
+0xffff\(aqffff, then
-as 0xffffffff provides a way of retrieving
+as 0xffff\(aqffff provides a way of retrieving
-With this flag set, use 0xc0000000 as the offset at which to search
+With this flag set, use 0xc000\(aq0000 as the offset at which to search
-otherwise use 0xffffe000.
+otherwise use 0xffff\(aqe000.
diff --git a/man2/prctl.2 b/man2/prctl.2
-are 50,000 nanoseconds (50 microseconds).
+are 50\(aq000 nanoseconds (50 microseconds).
diff --git a/man2/read.2 b/man2/read.2
-0x7ffff000 (2,147,479,552) bytes,
+0x7fff\(aqf000 (2\(aq147\(aq479\(aq552) bytes,
diff --git a/man2/reboot.2 b/man2/reboot.2
-(that is, 0xfee1dead) and
+(that is, 0xfee1\(aqdead) and
-(that is, 672274793).
+(that is, 672\(aq274\(aq793 0x2812\(aq1969).
-(that is, 85072278)
+(that is, 85\(aq072\(aq278 0x0512\(aq1996)
-(that is, 369367448)
+(that is, 369\(aq367\(aq448 0x1604\(aq1998)
-(that is, 537993216)
+(that is, 537\(aq993\(aq216 0x2011\(aq2000)
-0x89abcdef).
+0x89ab\(aqcdef).
-0xcdef0123; since Linux 1.1.76).
+0xcdef\(aq0123; since Linux 1.1.76).
-0x45584543, since Linux 2.6.13).
+0x4558\(aq4543, since Linux 2.6.13).
-0x4321fedc; since Linux 2.1.30).
+0x4321\(aqfedc; since Linux 2.1.30).
-0x1234567).
+0x0123\(aq4567).
-(0xa1b2c3d4; since Linux 2.1.30).
+(0xa1b2\(aqc3d4; since Linux 2.1.30).
-0xd000fce1; since Linux 2.5.18).
+0xd000\(aqfce1; since Linux 2.5.18).
diff --git a/man2/semget.2 b/man2/semget.2
-the default value is 32,000.
+the default value is 32\(aq000.
-the default value is 32,000.
+the default value is 32\(aq000.
diff --git a/man2/sendfile.2 b/man2/sendfile.2
-will transfer at most 0x7ffff000 (2,147,479,552) bytes,
+will transfer at most 0x7fff\(aqf000 (2\(aq147\(aq479\(aq552) bytes,
diff --git a/man2/shmget.2 b/man2/shmget.2
-this limit was 0x2000000 (32\ MB).
+this limit was 0x200\(aq0000 (32\ MiB).
diff --git a/man2/sigaction.2 b/man2/sigaction.2
- _POSIX_C_SOURCE >= 199309L
+ _POSIX_C_SOURCE >= 1993\(aq09L
-with the value 200809L or greater.
+with the value 2008\(aq09L or greater.
diff --git a/man2/spu_run.2 b/man2/spu_run.2
-.B 0x3fff0000
+.B 0x3fff\(aq0000
- * We should see a status code of 0x1234002:
- * 0x00000002 (spu was stopped due to stop\-and\-signal)
- * | 0x12340000 (the stop\-and\-signal code)
+ * We should see a status code of 0x1234\(aq0002:
+ * 0x0000\(aq0002 (spu was stopped due to stop\-and\-signal)
+ * | 0x1234\(aq0000 (the stop\-and\-signal code)
diff --git a/man2/statfs.2 b/man2/statfs.2
-AFS_SUPER_MAGIC 0x5346414f
-ANON_INODE_FS_MAGIC 0x09041934 /* Anonymous inode FS (for
+AFS_SUPER_MAGIC 0x5346\(aq414f
+ANON_INODE_FS_MAGIC 0x0904\(aq1934 /* Anonymous inode FS (for
-BDEVFS_MAGIC 0x62646576
-BEFS_SUPER_MAGIC 0x42465331
-BFS_MAGIC 0x1badface
-BINFMTFS_MAGIC 0x42494e4d
-BPF_FS_MAGIC 0xcafe4a11
-BTRFS_SUPER_MAGIC 0x9123683e
-BTRFS_TEST_MAGIC 0x73727279
-CGROUP_SUPER_MAGIC 0x27e0eb /* Cgroup pseudo FS */
-CGROUP2_SUPER_MAGIC 0x63677270 /* Cgroup v2 pseudo FS */
-CIFS_MAGIC_NUMBER 0xff534d42
-CODA_SUPER_MAGIC 0x73757245
-COH_SUPER_MAGIC 0x012ff7b7
-CRAMFS_MAGIC 0x28cd3d45
-DEBUGFS_MAGIC 0x64626720
+BDEVFS_MAGIC 0x6264\(aq6576
+BEFS_SUPER_MAGIC 0x4246\(aq5331
+BFS_MAGIC 0x1bad\(aqface
+BINFMTFS_MAGIC 0x4249\(aq4e4d
+BPF_FS_MAGIC 0xcafe\(aq4a11
+BTRFS_SUPER_MAGIC 0x9123\(aq683e
+BTRFS_TEST_MAGIC 0x7372\(aq7279
+CGROUP_SUPER_MAGIC 0x27\(aqe0eb /* Cgroup pseudo FS */
+CGROUP2_SUPER_MAGIC 0x6367\(aq7270 /* Cgroup v2 pseudo FS */
+CIFS_MAGIC_NUMBER 0xff53\(aq4d42
+CODA_SUPER_MAGIC 0x7375\(aq7245
+COH_SUPER_MAGIC 0x012f\(aqf7b7
+CRAMFS_MAGIC 0x28cd\(aq3d45
+DEBUGFS_MAGIC 0x6462\(aq6720
-EFIVARFS_MAGIC 0xde5e81e4
-EFS_SUPER_MAGIC 0x00414a53
+EFIVARFS_MAGIC 0xde5e\(aq81e4
+EFS_SUPER_MAGIC 0x0041\(aq4a53
-F2FS_SUPER_MAGIC 0xf2f52010
-FUSE_SUPER_MAGIC 0x65735546
-FUTEXFS_SUPER_MAGIC 0xbad1dea /* Unused */
+F2FS_SUPER_MAGIC 0xf2f5\(aq2010
+FUSE_SUPER_MAGIC 0x6573\(aq5546
+FUTEXFS_SUPER_MAGIC 0xbad\(aq1dea /* Unused */
-HOSTFS_SUPER_MAGIC 0x00c0ffee
-HPFS_SUPER_MAGIC 0xf995e849
-HUGETLBFS_MAGIC 0x958458f6
+HOSTFS_SUPER_MAGIC 0x00c0\(aqffee
+HPFS_SUPER_MAGIC 0xf995\(aqe849
+HUGETLBFS_MAGIC 0x9584\(aq58f6
-JFS_SUPER_MAGIC 0x3153464a
+JFS_SUPER_MAGIC 0x3153\(aq464a
-MQUEUE_MAGIC 0x19800202 /* POSIX message queue FS */
+MQUEUE_MAGIC 0x1980\(aq0202 /* POSIX message queue FS */
-MTD_INODE_FS_MAGIC 0x11307854
+MTD_INODE_FS_MAGIC 0x1130\(aq7854
-NSFS_MAGIC 0x6e736673
-NTFS_SB_MAGIC 0x5346544e
-OCFS2_SUPER_MAGIC 0x7461636f
+NSFS_MAGIC 0x6e73\(aq6673
+NTFS_SB_MAGIC 0x5346\(aq544e
+OCFS2_SUPER_MAGIC 0x7461\(aq636f
-OVERLAYFS_SUPER_MAGIC 0x794c7630
-PIPEFS_MAGIC 0x50495045
+OVERLAYFS_SUPER_MAGIC 0x794c\(aq7630
+PIPEFS_MAGIC 0x5049\(aq5045
-PSTOREFS_MAGIC 0x6165676c
+PSTOREFS_MAGIC 0x6165\(aq676c
-QNX6_SUPER_MAGIC 0x68191122
-RAMFS_MAGIC 0x858458f6
-REISERFS_SUPER_MAGIC 0x52654973
+QNX6_SUPER_MAGIC 0x6819\(aq1122
+RAMFS_MAGIC 0x8584\(aq58f6
+REISERFS_SUPER_MAGIC 0x5265\(aq4973
-SECURITYFS_MAGIC 0x73636673
-SELINUX_MAGIC 0xf97cff8c
-SMACK_MAGIC 0x43415d53
+SECURITYFS_MAGIC 0x7363\(aq6673
+SELINUX_MAGIC 0xf97c\(aqff8c
+SMACK_MAGIC 0x4341\(aq5d53
-SMB2_MAGIC_NUMBER 0xfe534d42
-SOCKFS_MAGIC 0x534f434b
-SQUASHFS_MAGIC 0x73717368
-SYSFS_MAGIC 0x62656572
-SYSV2_SUPER_MAGIC 0x012ff7b6
-SYSV4_SUPER_MAGIC 0x012ff7b5
-TMPFS_MAGIC 0x01021994
-TRACEFS_MAGIC 0x74726163
-UDF_SUPER_MAGIC 0x15013346
-UFS_MAGIC 0x00011954
+SMB2_MAGIC_NUMBER 0xfe53\(aq4d42
+SOCKFS_MAGIC 0x534f\(aq434b
+SQUASHFS_MAGIC 0x7371\(aq7368
+SYSFS_MAGIC 0x6265\(aq6572
+SYSV2_SUPER_MAGIC 0x012f\(aqf7b6
+SYSV4_SUPER_MAGIC 0x012f\(aqf7b5
+TMPFS_MAGIC 0x0102\(aq1994
+TRACEFS_MAGIC 0x7472\(aq6163
+UDF_SUPER_MAGIC 0x1501\(aq3346
+UFS_MAGIC 0x0001\(aq1954
-V9FS_MAGIC 0x01021997
-VXFS_SUPER_MAGIC 0xa501fcf5
-XENFS_SUPER_MAGIC 0xabba1974
-XENIX_SUPER_MAGIC 0x012ff7b4
-XFS_SUPER_MAGIC 0x58465342
-_XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */
+V9FS_MAGIC 0x0102\(aq1997
+VXFS_SUPER_MAGIC 0xa501\(aqfcf5
+XENFS_SUPER_MAGIC 0xabba\(aq1974
+XENIX_SUPER_MAGIC 0x012f\(aqf7b4
+XFS_SUPER_MAGIC 0x5846\(aq5342
+_XIAFS_SUPER_MAGIC 0x012f\(aqd16d /* Linux 2.0 and earlier */
diff --git a/man2/statx.2 b/man2/statx.2
-with the value 0x80000000U.)
+with the value 0x8000\(aq0000U.)
diff --git a/man2/syscall.2 b/man2/syscall.2
-ia64 break 0x100000 r15 r8 r9 r10 1, 6
+ia64 break 0x10\(aq0000 r15 r8 r9 r10 1, 6
diff --git a/man2/timer_settime.2 b/man2/timer_settime.2
- _POSIX_C_SOURCE >= 199309L
+ _POSIX_C_SOURCE >= 1993\(aq09L
-is negative or greater than 999,999,999.
+is negative or greater than 999\(aq999\(aq999.
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
-falls outside the range zero to 999,999,999).
+falls outside the range zero to 999\(aq999\(aq999).
diff --git a/man2/truncate.2 b/man2/truncate.2
-or an entire pathname exceeded 1023 characters.
+or an entire pathname exceeded 1\(aq023 characters.
-was 200809L instead of 200112L.
+was 2008\(aq09L instead of 2001\(aq12L.
diff --git a/man2/utimensat.2 b/man2/utimensat.2
- _POSIX_C_SOURCE >= 200809L
+ _POSIX_C_SOURCE >= 2008\(aq09L
- _POSIX_C_SOURCE >= 200809L
+ _POSIX_C_SOURCE >= 2008\(aq09L
-fields (value outside range 0 to 999,999,999, and not
+fields (value outside range 0 to 999\(aq999\(aq999, and not
diff --git a/man2/write.2 b/man2/write.2
-0x7ffff000 (2,147,479,552) bytes,
+0x7fff\(aqf000 (2\(aq147\(aq479\(aq552) bytes,
