From 0ec592073bd6a5c9e8bab4fa2f7c163d35d16e94 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:17 +0100 Subject: [PATCH 01/14] setpriv: make message for failing PR_GET_PDEATHSIG the same as the other Signed-off-by: Benno Schulenberg --- sys-utils/setpriv.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sys-utils/setpriv.c b/sys-utils/setpriv.c index 43d72f64c65..daa3ab366b1 100644 --- a/sys-utils/setpriv.c +++ b/sys-utils/setpriv.c @@ -329,7 +329,7 @@ static void dump_pdeathsig(void) int pdeathsig; if (prctl(PR_GET_PDEATHSIG, &pdeathsig) != 0) { - warn(_("get pdeathsig failed")); + warn(_("failed to get parent death signal")); return; } From f0d2f4a37ae880ca2b05e236c9d35215f9166e74 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:18 +0100 Subject: [PATCH 02/14] unshare: don't use "=" before a required option argument The "=" is not needed, is inconsistent with the presentation of the other options that require an argument, and trying to use "=" with the equivalent short option would lead to failure. Signed-off-by: Benno Schulenberg --- sys-utils/unshare.1.adoc | 14 +++++++------- sys-utils/unshare.c | 12 ++++++------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc index 5c2b268b194..db2c07ab277 100644 --- a/sys-utils/unshare.1.adoc +++ b/sys-utils/unshare.1.adoc @@ -93,18 +93,18 @@ Just before running the program, mount the proc filesystem at _mountpoint_ (defa *--mount-binfmt*[**=**__mountpoint__]:: Just before running the program, mount the binfmt_misc filesystem at _mountpoint_ (default is /proc/sys/fs/binfmt_misc). It also implies creating a new mount namespace since the binfmt_misc mount would otherwise mess up existing programs on the system. The new binfmt_misc filesystem is explicitly mounted as private (with *MS_PRIVATE*|*MS_REC*). -**--map-user=**__uid|name__:: +**--map-user** __uid|name__:: Run the program only after the current effective user ID has been mapped to _uid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*. -**--map-users=**__inneruid:outeruid:count__|**auto**|**all**:: +**--map-users** __inneruid:outeruid:count__|**auto**|**all**:: Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. If the range of user IDs overlaps with the mapping specified by *--map-user*, then a "hole" will be removed from the mapping. This may result in the highest user ID of the mapping not being mapped. Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*. + Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid,inneruid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option. -**--map-group=**__gid|name__:: +**--map-group** __gid|name__:: Run the program only after the current effective group ID has been mapped to _gid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--setgroups=deny* and *--user*. -**--map-groups=**__innergid:outergid:count__|**auto**|**all**:: +**--map-groups** __innergid:outergid:count__|**auto**|**all**:: Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. If the range of group IDs overlaps with the mapping specified by *--map-group*, then a "hole" will be removed from the mapping. This may result in the highest group ID of the mapping not being mapped. Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*. + Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid,innergid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option. @@ -129,10 +129,10 @@ Allow or deny the *setgroups*(2) system call in a user namespace. + To be able to call *setgroups*(2), the calling process must at least have *CAP_SETGID*. But since Linux 3.19 a further restriction applies: the kernel gives permission to call *setgroups*(2) only after the GID map (**/proc/**__pid__*/gid_map*) has been set. The GID map is writable by root when *setgroups*(2) is enabled (i.e., *allow*, the default), and the GID map becomes writable by unprivileged processes when *setgroups*(2) is permanently disabled (with *deny*). -*-R*, **--root=**__dir__:: +*-R*, **--root** __dir__:: run the command with root directory set to _dir_. -*-w*, **--wd=**__dir__:: +*-w*, **--wd** __dir__:: change working directory to _dir_. *-S*, *--setuid* _uid_:: @@ -141,7 +141,7 @@ Set the user ID which will be used in the entered namespace. *-G*, *--setgid* _gid_:: Set the group ID which will be used in the entered namespace and drop supplementary groups. -*-l*, **--load-interp=**__string__:: +*-l*, **--load-interp** __string__:: Load binfmt_misc definition in the namespace (implies *--mount-binfmt*). The __string__ argument is ``:name:type:offset:magic:mask:interpreter:flags``. For more details about new binary type registration see https://www.kernel.org/doc/Documentation/admin-guide/binfmt-misc.rst. To manage the F flag in ``flags`` with **--root** parameter, binfmt_misc is mounted twice, once before the chroot to load the interpreter from the caller filesystem and once after to make it available from the chroot userspace. diff --git a/sys-utils/unshare.c b/sys-utils/unshare.c index 9263606c3ed..9b87acd67a0 100644 --- a/sys-utils/unshare.c +++ b/sys-utils/unshare.c @@ -782,14 +782,14 @@ static void __attribute__((__noreturn__)) usage(void) fputs(_(" -T, --time[=] unshare time namespace\n"), out); fputs(USAGE_SEPARATOR, out); fputs(_(" -f, --fork fork before launching \n"), out); - fputs(_(" --map-user=| map current user to uid (implies --user)\n"), out); - fputs(_(" --map-group=| map current group to gid (implies --user)\n"), out); + fputs(_(" --map-user | map current user to uid (implies --user)\n"), out); + fputs(_(" --map-group | map current group to gid (implies --user)\n"), out); fputs(_(" -r, --map-root-user map current user to root (implies --user)\n"), out); fputs(_(" -c, --map-current-user map current user to itself (implies --user)\n"), out); fputs(_(" --map-auto map users and groups automatically (implies --user)\n"), out); - fputs(_(" --map-users=::\n" + fputs(_(" --map-users ::\n" " map count users from outeruid to inneruid (implies --user)\n"), out); - fputs(_(" --map-groups=::\n" + fputs(_(" --map-groups ::\n" " map count groups from outergid to innergid (implies --user)\n"), out); fputs(USAGE_SEPARATOR, out); fputs(_(" --kill-child[=] when dying, kill the forked child (implies --fork)\n" @@ -801,8 +801,8 @@ static void __attribute__((__noreturn__)) usage(void) fputs(_(" --setgroups allow|deny control the setgroups syscall in user namespaces\n"), out); fputs(_(" --keep-caps retain capabilities granted in user namespaces\n"), out); fputs(USAGE_SEPARATOR, out); - fputs(_(" -R, --root= run the command with root directory set to \n"), out); - fputs(_(" -w, --wd= change working directory to \n"), out); + fputs(_(" -R, --root run the command with root directory set to \n"), out); + fputs(_(" -w, --wd change working directory to \n"), out); fputs(_(" -S, --setuid set uid in entered namespace\n"), out); fputs(_(" -G, --setgid set gid in entered namespace\n"), out); fputs(_(" --monotonic set clock monotonic offset (seconds) in time namespaces\n"), out); From 0bdb1cf1f24352fb84338cc9e17bed5789a110ba Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:19 +0100 Subject: [PATCH 03/14] unshare: use single asterisks around long options, double around values Signed-off-by: Benno Schulenberg --- sys-utils/unshare.1.adoc | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc index db2c07ab277..c6973f93856 100644 --- a/sys-utils/unshare.1.adoc +++ b/sys-utils/unshare.1.adoc @@ -93,26 +93,26 @@ Just before running the program, mount the proc filesystem at _mountpoint_ (defa *--mount-binfmt*[**=**__mountpoint__]:: Just before running the program, mount the binfmt_misc filesystem at _mountpoint_ (default is /proc/sys/fs/binfmt_misc). It also implies creating a new mount namespace since the binfmt_misc mount would otherwise mess up existing programs on the system. The new binfmt_misc filesystem is explicitly mounted as private (with *MS_PRIVATE*|*MS_REC*). -**--map-user** __uid|name__:: +*--map-user* __uid|name__:: Run the program only after the current effective user ID has been mapped to _uid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*. -**--map-users** __inneruid:outeruid:count__|**auto**|**all**:: +*--map-users* __inneruid:outeruid:count__|**auto**|**all**:: Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. If the range of user IDs overlaps with the mapping specified by *--map-user*, then a "hole" will be removed from the mapping. This may result in the highest user ID of the mapping not being mapped. Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*. + Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid,inneruid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option. -**--map-group** __gid|name__:: +*--map-group* __gid|name__:: Run the program only after the current effective group ID has been mapped to _gid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--setgroups=deny* and *--user*. -**--map-groups** __innergid:outergid:count__|**auto**|**all**:: +*--map-groups* __innergid:outergid:count__|**auto**|**all**:: Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. If the range of group IDs overlaps with the mapping specified by *--map-group*, then a "hole" will be removed from the mapping. This may result in the highest group ID of the mapping not being mapped. Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*. + Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid,innergid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option. -**--map-auto**:: +*--map-auto*:: Map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. In the same manner, also map the first block of group IDs owned by the effective group from _/etc/subgid_ to a block starting at group ID 0. This option is intended to handle the common case where the first block of subordinate user and group IDs can map the whole user and group ID space. This option is equivalent to specifying *--map-users=auto* and *--map-groups=auto*. -**--map-subids**:: +*--map-subids*:: Identity map the first block of user IDs owned by the effective user from _/etc/subuid_. In the same manner, also identity map the first block of group IDs owned by the effective group from _/etc/subgid_. This option is equivalent to specifying *--map-users=subids* and *--map-groups=subids*. *-r*, *--map-root-user*:: @@ -121,18 +121,18 @@ Run the program only after the current effective user and group IDs have been ma *-c*, *--map-current-user*:: Run the program only after the current effective user and group IDs have been mapped to the same UID and GID in the newly created user namespace. This option implies *--setgroups=deny* and *--user*. This option is equivalent to *--map-user=$(id -ru) --map-group=$(id -rg)*. -**--propagation private**|**shared**|**slave**|*unchanged*:: +*--propagation* **private**|**shared**|**slave**|**unchanged**:: Recursively set the mount propagation flag in the new mount namespace. The default is to set the propagation to _private_. It is possible to disable this feature with the argument *unchanged*. The option is silently ignored when the mount namespace (*--mount*) is not requested. -**--setgroups allow**|*deny*:: +*--setgroups* **allow**|**deny**:: Allow or deny the *setgroups*(2) system call in a user namespace. + To be able to call *setgroups*(2), the calling process must at least have *CAP_SETGID*. But since Linux 3.19 a further restriction applies: the kernel gives permission to call *setgroups*(2) only after the GID map (**/proc/**__pid__*/gid_map*) has been set. The GID map is writable by root when *setgroups*(2) is enabled (i.e., *allow*, the default), and the GID map becomes writable by unprivileged processes when *setgroups*(2) is permanently disabled (with *deny*). -*-R*, **--root** __dir__:: +*-R*, *--root* __dir__:: run the command with root directory set to _dir_. -*-w*, **--wd** __dir__:: +*-w*, *--wd* __dir__:: change working directory to _dir_. *-S*, *--setuid* _uid_:: @@ -141,9 +141,9 @@ Set the user ID which will be used in the entered namespace. *-G*, *--setgid* _gid_:: Set the group ID which will be used in the entered namespace and drop supplementary groups. -*-l*, **--load-interp** __string__:: +*-l*, *--load-interp* __string__:: Load binfmt_misc definition in the namespace (implies *--mount-binfmt*). The __string__ argument is ``:name:type:offset:magic:mask:interpreter:flags``. For more details about new binary type registration see https://www.kernel.org/doc/Documentation/admin-guide/binfmt-misc.rst. -To manage the F flag in ``flags`` with **--root** parameter, binfmt_misc is mounted twice, once before the chroot to load the interpreter from the caller filesystem and once after to make it available from the chroot userspace. +To manage the F flag in ``flags`` with *--root* parameter, binfmt_misc is mounted twice, once before the chroot to load the interpreter from the caller filesystem and once after to make it available from the chroot userspace. *--monotonic* _offset_:: Set the offset of *CLOCK_MONOTONIC* which will be used in the entered time namespace. This option requires unsharing a time namespace with *--time*. From 6277a9c137b2c91a259ba1e8db808335f18c1975 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:20 +0100 Subject: [PATCH 04/14] textual: remove other inconsistent uses of "=" before option argument And remove inconsistent uses of double asterisks too. Signed-off-by: Benno Schulenberg --- login-utils/lslogins.1.adoc | 4 ++-- login-utils/su.1.adoc | 10 +++++----- sys-utils/mount.8.adoc | 2 +- sys-utils/wdctl.8.adoc | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/login-utils/lslogins.1.adoc b/login-utils/lslogins.1.adoc index 6371c2d00ca..4aeef7cf8b2 100644 --- a/login-utils/lslogins.1.adoc +++ b/login-utils/lslogins.1.adoc @@ -46,7 +46,7 @@ Display data about the users' last failed login attempts. *-G*, *--supp-groups*:: Show information about supplementary groups. -*-g*, **--groups**=_groups_:: +*-g*, *--groups* _groups_:: Only show data of users belonging to _groups_. More than one group may be specified; the list has to be comma-separated. Unknown group names are ignored. + Note that the relation between user and group may be invisible for the primary group if the user is not explicitly specified as group member (e.g., in _/etc/group_). If the command *lslogins* scans for groups then it uses the groups database only, and the user database with primary GID is not used at all. @@ -54,7 +54,7 @@ Note that the relation between user and group may be invisible for the primary g *-L*, *--last*:: Display data containing information about the users' last login sessions. -*-l*, **--logins**=_logins_:: +*-l*, *--logins* _logins_:: Only show data of users with a login specified in _logins_ (user names or user IDs). More than one login may be specified; the list has to be comma-separated. Unknown login names are ignored. *-n*, *--newline*:: diff --git a/login-utils/su.1.adoc b/login-utils/su.1.adoc index 33f45833f44..866139755ab 100644 --- a/login-utils/su.1.adoc +++ b/login-utils/su.1.adoc @@ -33,16 +33,16 @@ Since version 2.38 *su* resets process resource limits RLIMIT_NICE, RLIMIT_RTPRI == OPTIONS -*-c*, **--command**=__command__:: +*-c*, *--command* __command__:: Pass _command_ to the shell with the *-c* option. *-f*, *--fast*:: Pass *-f* to the shell, which may or may not be useful, depending on the shell. -*-g*, **--group**=__group__:: +*-g*, *--group* __group__:: Specify the primary group. This option is available to the root user only. -*-G*, **--supp-group**=__group__:: +*-G*, *--supp-group* __group__:: Specify a supplementary group. This option is available to the root user only. The first specified supplementary group is also used as a primary group if the option *--group* is not specified. *-*, *-l*, *--login*:: @@ -68,7 +68,7 @@ Create a pseudo-terminal for the session. The independent terminal provides bett + This feature is mostly designed for interactive sessions. If the standard input is not a terminal, but for example a pipe (e.g., *echo "date" | su --pty*), then the *ECHO* flag for the pseudo-terminal is disabled to avoid messy output. -*-s*, **--shell**=__shell__:: +*-s*, *--shell* __shell__:: Run the specified _shell_ instead of the default. If the target user has a restricted shell (i.e., not listed in _/etc/shells_), the *--shell* option and the *SHELL* environment variables are ignored unless the calling user is root. + The shell to run is selected according to the following rules, in order: @@ -85,7 +85,7 @@ Same as *-c*, but do not create a new session. (Discouraged.) Do not create a pseudo-terminal, opposite of *--pty* and *-P*. Note that running without a pseudo-terminal opens the security risk of privilege escalation through TIOCSTI/TIOCLINUX ioctl command injection. -*-w*, **--whitelist-environment**=__list__:: +*-w*, *--whitelist-environment* __list__:: Don't reset the environment variables specified in the comma-separated _list_ when clearing the environment for *--login*. The whitelist is ignored for the environment variables *HOME*, *SHELL*, *USER*, *LOGNAME*, and *PATH*. include::man-common/help-version.adoc[] diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc index 92ff15dfb5b..08a2e731cf7 100644 --- a/sys-utils/mount.8.adoc +++ b/sys-utils/mount.8.adoc @@ -345,7 +345,7 @@ Add the labels in the mount output. *mount* must have permission to read the dis *-M*, *--move*:: Move a subtree to some other place. See above, the subsection *The move operation*. -*-m*, **--mkdir**[=__mode__]:: +*-m*, *--mkdir*[**=**__mode__]:: Allow to make a target directory (mountpoint) if it does not exist yet. Alias to "-o X-mount.mkdir[=mode]", the default mode is 0755. For more details see *X-mount.mkdir* below. *--map-groups*, *--map-users* _inner_:_outer_:_count_:: diff --git a/sys-utils/wdctl.8.adoc b/sys-utils/wdctl.8.adoc index 6eb44e5d86e..5fec3584eb3 100644 --- a/sys-utils/wdctl.8.adoc +++ b/sys-utils/wdctl.8.adoc @@ -46,7 +46,7 @@ Print all wanted information on one line in key="value" output format. Set the watchdog pre-timeout in seconds. A watchdog pre-timeout is a notification generated by the watchdog before the watchdog reset might occur in the event the watchdog has not been serviced. This notification is handled by -the kernel and can be configured to take an action using sysfs or by **--setpregovernor**. +the kernel and can be configured to take an action using sysfs or by *--setpregovernor*. *-g*, *--setpregovernor* _governor_:: Set pre-timeout governor name. For available governors see default **wdctl** output. From e4b14de33dae8af421dc0bbb2fa48b682525b623 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:21 +0100 Subject: [PATCH 05/14] textual: consistently mark "=" as literal before an optional argument See, for example, how in `man cfdisk` the "=" after --color and after --lock were differently marked. (Basically done with `sed -i 's/\*\[=/\*\[\*\*=\*\*/' *utils/*.adoc`.) Signed-off-by: Benno Schulenberg --- disk-utils/cfdisk.8.adoc | 2 +- disk-utils/fdisk.8.adoc | 8 ++++---- disk-utils/fsck.cramfs.8.adoc | 2 +- disk-utils/mkfs.bfs.8.adoc | 2 +- disk-utils/mkfs.cramfs.8.adoc | 2 +- disk-utils/mkfs.minix.8.adoc | 2 +- disk-utils/mkswap.8.adoc | 2 +- disk-utils/sfdisk.8.adoc | 2 +- login-utils/lslogins.1.adoc | 2 +- misc-utils/cal.1.adoc | 4 ++-- misc-utils/enosys.1.adoc | 2 +- misc-utils/findmnt.8.adoc | 2 +- misc-utils/hardlink.1.adoc | 2 +- misc-utils/lsblk.8.adoc | 2 +- misc-utils/uuidd.8.adoc | 2 +- misc-utils/wipefs.8.adoc | 4 ++-- sys-utils/dmesg.1.adoc | 2 +- sys-utils/lscpu.1.adoc | 8 ++++---- sys-utils/lsmem.1.adoc | 2 +- sys-utils/mount.8.adoc | 4 ++-- sys-utils/nsenter.1.adoc | 22 ++++++++++----------- sys-utils/prlimit.1.adoc | 36 +++++++++++++++++------------------ term-utils/agetty.8.adoc | 2 +- term-utils/script.1.adoc | 2 +- term-utils/setterm.1.adoc | 18 +++++++++--------- text-utils/hexdump.1.adoc | 2 +- 26 files changed, 70 insertions(+), 70 deletions(-) diff --git a/disk-utils/cfdisk.8.adoc b/disk-utils/cfdisk.8.adoc index 759f39f0e1a..5ab560a4a5c 100644 --- a/disk-utils/cfdisk.8.adoc +++ b/disk-utils/cfdisk.8.adoc @@ -49,7 +49,7 @@ include::man-common/help-version.adoc[] *-L*, *--color*[**=**__when__]:: Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled, for the current built-in default see *--help* output. See also the *COLORS* section. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools. *-r*, *--read-only*:: diff --git a/disk-utils/fdisk.8.adoc b/disk-utils/fdisk.8.adoc index 5941aa34968..6c59aa1a46c 100644 --- a/disk-utils/fdisk.8.adoc +++ b/disk-utils/fdisk.8.adoc @@ -45,12 +45,12 @@ Specify the sector size of the disk. Valid values are 512, 1024, 2048, and 4096. *-B*, *--protect-boot*:: Don't erase the beginning of the first disk sector when creating a new disk label. This feature is supported for GPT and MBR. -*-c*, *--compatibility*[=_mode_]:: +*-c*, *--compatibility*[**=**_mode_]:: Specify the compatibility mode, 'dos' or 'nondos'. The default is non-DOS mode. For backward compatibility, it is possible to use the option without the _mode_ argument -- then the default is used. Note that the optional _mode_ argument cannot be separated from the *-c* option by a space, the correct form is for example *-c*=_dos_. include::man-common/help-version.adoc[] -*-L*, *--color*[=_when_]:: +*-L*, *--color*[**=**_when_]:: Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled; for the current built-in default see the *--help* output. See also the *COLORS* section. *-l*, *--list*:: @@ -61,7 +61,7 @@ If no devices are given, the devices mentioned in _/proc/partitions_ (if this fi *-x*, *--list-details*:: Like *--list*, but provides more details. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools. *-n*, *--noauto-pt*:: @@ -79,7 +79,7 @@ Print the size in 512-byte sectors of each given block device. This option is DE *-t*, *--type* _type_:: Enable support only for disklabels of the specified _type_, and disable support for all other types. -*-u*, *--units*[=_unit_]:: +*-u*, *--units*[**=**_unit_]:: When listing partition tables, show sizes in 'sectors' or in 'cylinders'. The default is to show sizes in sectors. For backward compatibility, it is possible to use the option without the _unit_ argument -- then the default is used. Note that the optional _unit_ argument cannot be separated from the *-u* option by a space, the correct form is for example '**-u=**__cylinders__'. *-C*, *--cylinders* _number_:: diff --git a/disk-utils/fsck.cramfs.8.adoc b/disk-utils/fsck.cramfs.8.adoc index ec75262594e..59681fe18f4 100644 --- a/disk-utils/fsck.cramfs.8.adoc +++ b/disk-utils/fsck.cramfs.8.adoc @@ -26,7 +26,7 @@ Enable verbose messaging. *-b*, *--blocksize* _blocksize_:: Use this blocksize, defaults to page size. Must be equal to what was set at creation time. Only used for *--extract*. -*--extract*[=_directory_]:: +*--extract*[**=**_directory_]:: Test to uncompress the whole file system. Optionally extract contents of the _file_ to _directory_. *-a*:: diff --git a/disk-utils/mkfs.bfs.8.adoc b/disk-utils/mkfs.bfs.8.adoc index 198d61f5efa..248013731e2 100644 --- a/disk-utils/mkfs.bfs.8.adoc +++ b/disk-utils/mkfs.bfs.8.adoc @@ -35,7 +35,7 @@ Specify the volume _label_. I have no idea if/where this is used. *-F*, *--fname* _name_:: Specify the filesystem _name_. I have no idea if/where this is used. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools. *-v*, *--verbose*:: diff --git a/disk-utils/mkfs.cramfs.8.adoc b/disk-utils/mkfs.cramfs.8.adoc index c5ffa207339..56e5065b9ea 100644 --- a/disk-utils/mkfs.cramfs.8.adoc +++ b/disk-utils/mkfs.cramfs.8.adoc @@ -62,7 +62,7 @@ This option is ignored. Originally the *-s* turned on directory entry sorting. *-z*:: Make explicit holes. -*-l*[=_mode_]:: +*-l*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be _yes_, _no_ (or 1 and 0) or _nonblock_. If the _mode_ argument is omitted, it defaults to _"yes"_. This option overwrites diff --git a/disk-utils/mkfs.minix.8.adoc b/disk-utils/mkfs.minix.8.adoc index c1628ac03fd..4b8426f3eea 100644 --- a/disk-utils/mkfs.minix.8.adoc +++ b/disk-utils/mkfs.minix.8.adoc @@ -46,7 +46,7 @@ Check the device for bad blocks before creating the filesystem. If any are found *-n*, *--namelength* _length_:: Specify the maximum length of filenames. Currently, the only allowable values are 14 and 30 for file system versions 1 and 2. Version 3 allows only value 60. The default is 30. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools. *-i*, *--inodes* _number_:: diff --git a/disk-utils/mkswap.8.adoc b/disk-utils/mkswap.8.adoc index 70d0fb315b6..974a5af4e21 100644 --- a/disk-utils/mkswap.8.adoc +++ b/disk-utils/mkswap.8.adoc @@ -57,7 +57,7 @@ Suppress output and warning messages. *-L*, *--label* _label_:: Specify a _label_ for the device, to allow *swapon*(8) by label. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools. *-p*, *--pagesize* _size_:: diff --git a/disk-utils/sfdisk.8.adoc b/disk-utils/sfdisk.8.adoc index ce9e97b7682..0bd04ba3eb7 100644 --- a/disk-utils/sfdisk.8.adoc +++ b/disk-utils/sfdisk.8.adoc @@ -162,7 +162,7 @@ Disable all consistency checking. *--Linux*:: Deprecated and ignored option. Partitioning that is compatible with Linux (and other modern operating systems) is the default. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools. *-n*, *--no-act*:: diff --git a/login-utils/lslogins.1.adoc b/login-utils/lslogins.1.adoc index 4aeef7cf8b2..debd87f5acc 100644 --- a/login-utils/lslogins.1.adoc +++ b/login-utils/lslogins.1.adoc @@ -14,7 +14,7 @@ lslogins - display information about known users in the system == SYNOPSIS -*lslogins* [options] [*-s*|*-u*[=_UID_]] [*-g* _groups_] [*-l* _logins_] [_username_] +*lslogins* [options] [*-s*|*-u*[**=**_UID_]] [*-g* _groups_] [*-l* _logins_] [_username_] == DESCRIPTION diff --git a/misc-utils/cal.1.adoc b/misc-utils/cal.1.adoc index fe4f7e6708a..06b4238df12 100644 --- a/misc-utils/cal.1.adoc +++ b/misc-utils/cal.1.adoc @@ -111,7 +111,7 @@ Display a calendar for the whole year. *-Y, --twelve*:: Display a calendar for the next twelve months. -*-w*, *--week*[=_number_]:: +*-w*, *--week*[**=**_number_]:: Display week numbers in the calendar according to the US or ISO-8601 format. If a _number_ is specified, the requested week will be printed in the desired or current year. The _number_ may be overwritten if _day_ and _month_ are also @@ -119,7 +119,7 @@ specified. + See the *NOTES* section for more details. -*--color*[=_when_]:: +*--color*[**=**_when_]:: Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled; for the current built-in default see the *--help* output. See also the *COLORS* section. *-c, --columns*=_columns_:: diff --git a/misc-utils/enosys.1.adoc b/misc-utils/enosys.1.adoc index c8d213a14c2..9ffd9129bda 100644 --- a/misc-utils/enosys.1.adoc +++ b/misc-utils/enosys.1.adoc @@ -38,7 +38,7 @@ List syscalls known to *enosys*. *-m*, *--list-ioctl*:: List ioctls known to *enosys*. -*-d*, *--dump*[=_file_]:: +*-d*, *--dump*[**=**_file_]:: Dump seccomp bytecode filter to standard output. + The dump can for example be used by *setpriv --seccomp-filter*. diff --git a/misc-utils/findmnt.8.adoc b/misc-utils/findmnt.8.adoc index f2d6dbe5c99..fe29afe7773 100644 --- a/misc-utils/findmnt.8.adoc +++ b/misc-utils/findmnt.8.adoc @@ -57,7 +57,7 @@ The search direction, either *forward* or *backward*. *-e*, *--evaluate*:: Convert all tags (LABEL, UUID, PARTUUID, or PARTLABEL) to the corresponding device names for the SOURCE column. It's an unusual situation, but the same tag may be duplicated (used for more devices). For this purpose, there is SOURCES (pl.) column. This column displays by multi-line cell all devices where the tag is detected by libblkid. This option makes sense for _fstab_ only. -*--hyperlink*[=_mode_]:: +*--hyperlink*[**=**_mode_]:: Print mountpoint paths as terminal hyperlinks. The _mode_ can be set to "always", "never", or "auto". The optional argument _when_ can be set to "auto", "never", or "always". If the _when_ argument is omitted, it will default to "auto". The "auto" setting means that hyperlinks will only be used if the output is on a terminal. *-F*, *--tab-file* _path_:: diff --git a/misc-utils/hardlink.1.adoc b/misc-utils/hardlink.1.adoc index 49e7e3e0771..98b29a3b39b 100644 --- a/misc-utils/hardlink.1.adoc +++ b/misc-utils/hardlink.1.adoc @@ -131,7 +131,7 @@ Crypto API is not available. The methods based on checksums are implemented in zero-copy way, in this case file contents are not copied to the userspace and all calculation is done in kernel. -*--reflink*[=_when_]:: +*--reflink*[**=**_when_]:: Create copy-on-write clones (aka reflinks) rather than hardlinks. The reflinked files share only on-disk data, but the file mode and owner can be different. It's recommended to use it with *--ignore-owner* and *--ignore-mode* options. This option implies diff --git a/misc-utils/lsblk.8.adoc b/misc-utils/lsblk.8.adoc index d92d3fb44c7..a67eb292eb0 100644 --- a/misc-utils/lsblk.8.adoc +++ b/misc-utils/lsblk.8.adoc @@ -61,7 +61,7 @@ Exclude the devices specified by the comma-separated _list_ of major device numb *-f*, *--fs*:: Output info about filesystems. This option is equivalent to *-o NAME,FSTYPE,FSVER,LABEL,UUID,FSAVAIL,FSUSE%,MOUNTPOINTS*. The authoritative information about filesystems and raids is provided by the *blkid*(8) command. -*--hyperlink*[=_mode_]:: +*--hyperlink*[**=**_mode_]:: Print mountpoint paths as terminal hyperlinks. The _mode_ can be set to "always", "never", or "auto". The optional argument _when_ can be set to "auto", "never", or "always". If the _when_ argument is omitted, it will default to "auto". The "auto" setting means that hyperlinks will only be used if the output is on a terminal. *-I*, *--include* _list_:: diff --git a/misc-utils/uuidd.8.adoc b/misc-utils/uuidd.8.adoc index 7a2f6ae54f4..f8001f986f0 100644 --- a/misc-utils/uuidd.8.adoc +++ b/misc-utils/uuidd.8.adoc @@ -24,7 +24,7 @@ The *uuidd* daemon is used by the UUID library to generate universally unique id == OPTIONS -*-C*, *--cont-clock*[=_time_]:: +*-C*, *--cont-clock*[**=**_time_]:: Activate continuous clock handling for time based UUIDs. *uuidd* could use all possible clock values, beginning with the daemon's start time. The optional argument can be used to set a value for the max_clock_offset. This guarantees, that a clock value of a UUID will always be within the range of the max_clock_offset. + The option *-C* or *--cont-clock* enables the feature with a default max_clock_offset of 2 hours. diff --git a/misc-utils/wipefs.8.adoc b/misc-utils/wipefs.8.adoc index 886ddb62e21..88efaeca5b3 100644 --- a/misc-utils/wipefs.8.adoc +++ b/misc-utils/wipefs.8.adoc @@ -40,7 +40,7 @@ Note that by default *wipefs* does not erase nested partition tables on non-whol *-a*, *--all*:: Erase all available signatures. The set of erased signatures can be restricted with the *-t* option. -*-b*, *--backup*[=_dir_]:: +*-b*, *--backup*[**=**_dir_]:: Create a signature backup to the file _wipefs--.bak_ in _$HOME_ or the directory specified as the optional argument. For more details see the *EXAMPLE* section. *-f*, *--force*:: @@ -49,7 +49,7 @@ Force erasure, even if the filesystem is mounted. This is required in order to e *-J*, *--json*:: Use JSON output format. -*--lock*[=_mode_]:: +*--lock*[**=**_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *"yes"*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with udevd or other tools. *-i*, *--noheadings*:: diff --git a/sys-utils/dmesg.1.adoc b/sys-utils/dmesg.1.adoc index ccdeefa8f23..364c4aca467 100644 --- a/sys-utils/dmesg.1.adoc +++ b/sys-utils/dmesg.1.adoc @@ -78,7 +78,7 @@ Read the /dev/kmsg messages from the given _file_. Different record as expected *-k*, *--kernel*:: Print kernel messages. -*-L*, *--color*[=_when_]:: +*-L*, *--color*[**=**_when_]:: Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled; for the current built-in default see the *--help* output. See also the *COLORS* section below. *-l*, *--level* _list_:: diff --git a/sys-utils/lscpu.1.adoc b/sys-utils/lscpu.1.adoc index 60c769c0450..f7d9ccf0dd7 100644 --- a/sys-utils/lscpu.1.adoc +++ b/sys-utils/lscpu.1.adoc @@ -39,7 +39,7 @@ include::man-common/in-bytes.adoc[] *-b*, *--online*:: Limit the output to online CPUs (default for *-p*). This option may only be specified together with option *-e* or *-p*. -*-C*, *--caches*[=_list_]:: +*-C*, *--caches*[**=**_list_]:: Display details about CPU caches. For details about available information see *--help* output. + If the _list_ argument is omitted, all columns for which data is available are included in the command output. @@ -51,10 +51,10 @@ The default list of columns may be extended if list is specified in the format + *-c*, *--offline*:: Limit the output to offline CPUs. This option may only be specified together with option *-e* or *-p*. -*--hierarchic*[=_when_]:: +*--hierarchic*[**=**_when_]:: Use subsections in summary output. For backward compatibility, the default is to use subsections only when output on a terminal and flattened output on a non-terminal. The optional argument _when_ can be *never*, *always* or *auto*. If the _when_ argument is omitted, it defaults to "always". -*-e*, *--extended*[=_list_]:: +*-e*, *--extended*[**=**_list_]:: Display the CPU information in human-readable format. + If the _list_ argument is omitted, the default columns are included in the command output. The default output is subject to change. @@ -69,7 +69,7 @@ Use JSON output format for the default summary or extended output (see summary behavior for non-terminals (e.g., pipes) where subsections are missing. See also *--hierarchic*. -*-p*, *--parse*[=_list_]:: +*-p*, *--parse*[**=**_list_]:: Optimize the command output for easy parsing. + If the _list_ argument is omitted, the command output is compatible with earlier versions of *lscpu*. In this compatible format, two commas are used to separate CPU cache columns. If no CPU caches are identified the cache column is omitted. If the _list_ argument is used, cache columns are separated with a colon (:). diff --git a/sys-utils/lsmem.1.adoc b/sys-utils/lsmem.1.adoc index f1ece8f7d00..3e5577ee76c 100644 --- a/sys-utils/lsmem.1.adoc +++ b/sys-utils/lsmem.1.adoc @@ -62,7 +62,7 @@ Gather memory data for a Linux instance other than the instance from which the * include::man-common/help-version.adoc[] -*--summary*[=_when_]:: +*--summary*[**=**_when_]:: This option controls summary lines output. The optional argument _when_ can be *never*, *always* or *only*. If the _when_ argument is omitted, it defaults to *"only"*. The summary output is suppressed for *--raw*, *--pairs* and *--json*. == AUTHORS diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc index 08a2e731cf7..1ec7950565f 100644 --- a/sys-utils/mount.8.adoc +++ b/sys-utils/mount.8.adoc @@ -750,10 +750,10 @@ ____ mount -t auto -o'X-mount.auto-fstypes="noext2,ext3"' /dev/sdc1 /mnt/test ____ -*X-mount.mkdir*[=_mode_]:: +*X-mount.mkdir*[**=**_mode_]:: Allow to make a target directory (mountpoint) if it does not exist yet. The optional argument _mode_ specifies the filesystem access mode used for *mkdir*(2) in octal notation. The default mode is 0755. This functionality is supported only for root users or when *mount* is executed without suid permissions. The option is also supported as *x-mount.mkdir*, but this notation is deprecated since v2.30. See also *--mkdir* command line option. -*X-mount.nocanonicalize*[=_type_]:: +*X-mount.nocanonicalize*[**=**_type_]:: Allows disabling of canonicalization for mount source and target paths. By default, the `mount` command resolves all paths to their absolute paths without symlinks. However, this behavior may not be desired in certain situations, such as when binding a mount over a symlink, or a symlink over a directory or another symlink. The optional argument _type_ can be either "source" or "target" (mountpoint). If no _type_ is specified, then canonicalization is disabled for both types. This mount option does not affect the conversion of source tags (e.g. LABEL= or UUID=) and fstab processing. + The command line option *--no-canonicalize* overrides this mount option and affects all path and tag conversions in all situations, but it does not modify flags for open_tree syscalls. diff --git a/sys-utils/nsenter.1.adoc b/sys-utils/nsenter.1.adoc index 5246daecdf5..cb6419fda21 100644 --- a/sys-utils/nsenter.1.adoc +++ b/sys-utils/nsenter.1.adoc @@ -79,35 +79,35 @@ the root directory _/proc/pid/cwd_;; the working directory respectively -*-m*, *--mount*[=_file_]:: +*-m*, *--mount*[**=**_file_]:: Enter the mount namespace. If no file is specified, enter the mount namespace of the target process. If _file_ is specified, enter the mount namespace specified by _file_. -*-u*, *--uts*[=_file_]:: +*-u*, *--uts*[**=**_file_]:: Enter the UTS namespace. If no file is specified, enter the UTS namespace of the target process. If _file_ is specified, enter the UTS namespace specified by _file_. -*-i*, *--ipc*[=_file_]:: +*-i*, *--ipc*[**=**_file_]:: Enter the IPC namespace. If no file is specified, enter the IPC namespace of the target process. If _file_ is specified, enter the IPC namespace specified by _file_. -*-n*, *--net*[=_file_]:: +*-n*, *--net*[**=**_file_]:: Enter the network namespace. If no file is specified, enter the network namespace of the target process. If _file_ is specified, enter the network namespace specified by _file_. *-N*, *--net-socket* _fd_:: Enter the network namespace of the target process's socket. It requires *--target* process specified. Supported since Linux 5.6. -*-p*, *--pid*[=_file_]:: +*-p*, *--pid*[**=**_file_]:: Enter the PID namespace. If no file is specified, enter the PID namespace of the target process. If _file_ is specified, enter the PID namespace specified by _file_. -*-U*, *--user*[=_file_]:: +*-U*, *--user*[**=**_file_]:: Enter the user namespace. If no file is specified, enter the user namespace of the target process. If _file_ is specified, enter the user namespace specified by _file_. See also the *--setuid* and *--setgid* options. *--user-parent*:: Enter the parent user namespace. Parent user namespace will be acquired from any other enabled namespace. If combined with *--user* option the parent user namespace will be fetched from the user namespace and replace it. -*-C*, *--cgroup*[=_file_]:: +*-C*, *--cgroup*[**=**_file_]:: Enter the cgroup namespace. If no file is specified, enter the cgroup namespace of the target process. If _file_ is specified, enter the cgroup namespace specified by _file_. -*-T*, *--time*[=_file_]:: +*-T*, *--time*[**=**_file_]:: Enter the time namespace. If no file is specified, enter the time namespace of the target process. If _file_ is specified, enter the time namespace specified by _file_. *-G*, *--setgid* _gid_:: @@ -126,13 +126,13 @@ When the *--user* option is given, ensure that capabilities granted in the user *--preserve-credentials*:: Don't modify UID and GID when enter user namespace. The default is to drops supplementary groups and sets GID and UID to 0. -*-r*, *--root*[=_directory_]:: +*-r*, *--root*[**=**_directory_]:: Set the root directory. If no directory is specified, set the root directory to the root directory of the target process. If directory is specified, set the root directory to the specified directory. The specified _directory_ is open before it switches to the requested namespaces. -*-w*, *--wd*[=_directory_]:: +*-w*, *--wd*[**=**_directory_]:: Set the working directory. If no directory is specified, set the working directory to the working directory of the target process. If directory is specified, set the working directory to the specified directory. The specified _directory_ is open before it switches to the requested namespaces, it means the specified directory works as "tunnel" to the current namespace. See also *--wdns*. -*-W*, *--wdns*[=_directory_]:: +*-W*, *--wdns*[**=**_directory_]:: Set the working directory. The _directory_ is open after switch to the requested namespaces and after *chroot*(2) call. The options *--wd* and *--wdns* are mutually exclusive. *-e*, *--env*:: diff --git a/sys-utils/prlimit.1.adoc b/sys-utils/prlimit.1.adoc index 86e06a27934..49534cd52d2 100644 --- a/sys-utils/prlimit.1.adoc +++ b/sys-utils/prlimit.1.adoc @@ -18,9 +18,9 @@ prlimit - get and set process resource limits == SYNOPSIS -*prlimit* [options] [*--resource*[=_limits_]] [*--pid* _PID_] +*prlimit* [options] [*--resource*[**=**_limits_]] [*--pid* _PID_] -*prlimit* [options] [*--resource*[=_limits_]] _command_ [_argument_...] +*prlimit* [options] [*--resource*[**=**_limits_]] _command_ [_argument_...] == DESCRIPTION @@ -59,52 +59,52 @@ include::man-common/help-version.adoc[] == RESOURCE OPTIONS -*-c*, *--core*[=_limits_]:: +*-c*, *--core*[**=**_limits_]:: Maximum size of a core file. -*-d*, *--data*[=_limits_]:: +*-d*, *--data*[**=**_limits_]:: Maximum data size. -*-e*, *--nice*[=_limits_]:: +*-e*, *--nice*[**=**_limits_]:: Maximum nice priority allowed to raise. -*-f*, *--fsize*[=_limits_]:: +*-f*, *--fsize*[**=**_limits_]:: Maximum file size. -*-i*, *--sigpending*[=_limits_]:: +*-i*, *--sigpending*[**=**_limits_]:: Maximum number of pending signals. -*-l*, *--memlock*[=_limits_]:: +*-l*, *--memlock*[**=**_limits_]:: Maximum locked-in-memory address space. -*-m*, *--rss*[=_limits_]:: +*-m*, *--rss*[**=**_limits_]:: Maximum Resident Set Size (RSS). -*-n*, *--nofile*[=_limits_]:: +*-n*, *--nofile*[**=**_limits_]:: Maximum number of open files. -*-q*, *--msgqueue*[=_limits_]:: +*-q*, *--msgqueue*[**=**_limits_]:: Maximum number of bytes in POSIX message queues. -*-r*, *--rtprio*[=_limits_]:: +*-r*, *--rtprio*[**=**_limits_]:: Maximum real-time priority. -*-s*, *--stack*[=_limits_]:: +*-s*, *--stack*[**=**_limits_]:: Maximum size of the stack. -*-t*, *--cpu*[=_limits_]:: +*-t*, *--cpu*[**=**_limits_]:: CPU time, in seconds. -*-u*, *--nproc*[=_limits_]:: +*-u*, *--nproc*[**=**_limits_]:: Maximum number of processes. -*-v*, *--as*[=_limits_]:: +*-v*, *--as*[**=**_limits_]:: Address space limit. -*-x*, *--locks*[=_limits_]:: +*-x*, *--locks*[**=**_limits_]:: Maximum number of file locks held. -*-y*, *--rttime*[=_limits_]:: +*-y*, *--rttime*[**=**_limits_]:: Timeout for real-time tasks. == NOTES diff --git a/term-utils/agetty.8.adoc b/term-utils/agetty.8.adoc index 627f858a2ba..d34bd746c22 100644 --- a/term-utils/agetty.8.adoc +++ b/term-utils/agetty.8.adoc @@ -99,7 +99,7 @@ Do not clear the screen before prompting for the login name. By default the scre *-l*, *--login-program* _login_program_:: Invoke the specified _login_program_ instead of /bin/login. This allows the use of a non-standard login program. Such a program could, for example, ask for a dial-up password or use a different password file. See *--login-options*. -*-L*, *--local-line*[=__mode__]:: +*-L*, *--local-line*[**=**__mode__]:: Control the CLOCAL line flag. The optional _mode_ argument is *auto*, *always* or *never*. If the _mode_ argument is omitted, then the default is *always*. If the *--local-line* option is not given at all, then the default is *auto*. _always_;; diff --git a/term-utils/script.1.adoc b/term-utils/script.1.adoc index d7840cd41a1..7d9fa0eacb4 100644 --- a/term-utils/script.1.adoc +++ b/term-utils/script.1.adoc @@ -115,7 +115,7 @@ Limit the size of the typescript and timing files to _size_ and stop the child p *-q*, *--quiet*:: Be quiet (do not write start and done messages to standard output). -*-t*[_file_], *--timing*[=_file_]:: +*-t*[_file_], *--timing*[**=**_file_]:: Output timing data to standard error, or to _file_ when given. This option is deprecated in favour of *--log-timing* where the _file_ argument is not optional. include::man-common/help-version.adoc[] diff --git a/term-utils/setterm.1.adoc b/term-utils/setterm.1.adoc index 365c4bb0092..38dc81ab5e8 100644 --- a/term-utils/setterm.1.adoc +++ b/term-utils/setterm.1.adoc @@ -46,17 +46,17 @@ Like *--dump*, but appends to the snapshot file instead of overwriting it. Only *--background* __8-color__|default:: Sets the background text color. -*--blank*[=0-60|force|poke]:: +*--blank*[**=**0-60|force|poke]:: Sets the interval of inactivity, in minutes, after which the screen will be automatically blanked (using APM if available). Without an argument, it gets the blank status (returns which vt was blanked, or zero for an unblanked vt). Virtual consoles only. + The *force* argument keeps the screen blank even if a key is pressed. + The *poke* argument unblanks the screen. -*--bfreq*[=_number_]:: +*--bfreq*[**=**_number_]:: Sets the bell frequency in Hertz. Without an argument, it defaults to *0*. Virtual consoles only. -*--blength*[=0-2000]:: +*--blength*[**=**0-2000]:: Sets the bell duration in milliseconds. Without an argument, it defaults to *0*. Virtual consoles only. *--blink* on|off:: @@ -65,10 +65,10 @@ Turns blink mode on or off. Except on a virtual console, *--blink off* turns off *--bold* on|off:: urns bold (extra bright) mode on or off. Except on a virtual console, *--bold off* turns off all attributes (bold, half-brightness, blink, reverse). -*--clear*[=all|rest]:: +*--clear*[**=**all|rest]:: Without an argument or with the argument *all*, the entire screen is cleared and the cursor is set to the home position, just like *clear*(1) does. With the argument *rest*, the screen is cleared from the current cursor position to the end. -*--clrtabs*[=_tab1 tab2 tab3_ ...]:: +*--clrtabs*[**=**_tab1 tab2 tab3_ ...]:: Clears tab stops from the given horizontal cursor positions, in the range *1-160*. Without arguments, it clears all tab stops. Virtual consoles only. *--cursor* on|off:: @@ -77,7 +77,7 @@ Turns the terminal's cursor on or off. *--default*:: Sets the terminal's rendering options to the default values. -*--dump*[=_console_number_]:: +*--dump*[**=**_console_number_]:: Writes a snapshot of the virtual console with the given number to the file specified with the *--file* option, overwriting its contents; the default is _screen.dump_. Without an argument, it dumps the current virtual console. This overrides *--append*. *--file* _filename_:: @@ -109,7 +109,7 @@ Sets the console logging level for kernel *printk()* messages. All messages stri + Virtual consoles only. -*--powerdown*[=0-60]:: +*--powerdown*[**=**0-60]:: Sets the VESA powerdown interval in minutes. Without an argument, it defaults to *0* (disable powerdown). If the console is blanked or the monitor is in suspend mode, then the monitor will go into vsync suspend mode or powerdown mode respectively after this period of time has elapsed. *--powersave* _mode_:: @@ -124,7 +124,7 @@ Puts the monitor into VESA powerdown mode. *off*;; Turns monitor VESA powersaving features. -*--regtabs*[=1-160]:: +*--regtabs*[**=**1-160]:: Clears all tab stops, then sets a regular tab stop pattern, with one tab every specified number of positions. Without an argument, it defaults to *8*. Virtual consoles only. *--repeat* on|off:: @@ -142,7 +142,7 @@ Turns reverse video mode on or off. Except on a virtual console, *--reverse off* *--store*:: Stores the terminal's current rendering options (foreground and background colors) as the values to be used at reset-to-default. Virtual consoles only. -*--tabs*[=_tab1 tab2 tab3_ ...]:: +*--tabs*[**=**_tab1 tab2 tab3_ ...]:: Sets tab stops at the given horizontal cursor positions, in the range *1-160*. Without arguments, it shows the current tab stop settings. *--term* _terminal_name_:: diff --git a/text-utils/hexdump.1.adoc b/text-utils/hexdump.1.adoc index dd6247e3a06..1539538172f 100644 --- a/text-utils/hexdump.1.adoc +++ b/text-utils/hexdump.1.adoc @@ -82,7 +82,7 @@ Specify a format string to be used for displaying data. *-f*, *--format-file* _file_:: Specify a file that contains one or more newline-separated format strings. Empty lines and lines whose first non-blank character is a hash mark (#) are ignored. -*-L*, *--color*[=_when_]:: +*-L*, *--color*[**=**_when_]:: Accept color units for the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled; for the current built-in default see the *--help* output. See also the *Colors* subsection and the *COLORS* section below. *-n*, *--length* _length_:: From 29009a35a4112e1eeb73aafc7a0360094ccf6aad Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:22 +0100 Subject: [PATCH 06/14] mount: properly mark the arguments of the 'ro' and 'rw' extended options The 'fs', 'vfs', and 'recursive' are literal values, not placeholders for something else. Signed-off-by: Benno Schulenberg --- sys-utils/mount.8.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc index 1ec7950565f..1ee70096fca 100644 --- a/sys-utils/mount.8.adoc +++ b/sys-utils/mount.8.adoc @@ -691,19 +691,19 @@ After this call, *mount* reads _fstab_ and merges these options with the options + remounts all already mounted vfat filesystems in read-only mode. Each of the filesystems is remounted by *mount -o remount,ro* _/dir_ semantic. This means the *mount* command reads _fstab_ or _mtab_ and merges these options with the options from the command line. -*ro*[=_recursive_,_vfs_,_fs_]:: +*ro*[**=**(*recursive*|*vfs*|*fs*)]:: Mount the filesystem read-only. The optional argument is an experimental feature supported only by the file-descriptor based kernel mount API and it is silently ignored for the old *mount*(2) syscall. + -The _recursive_ argument forces the VFS attribute to be applied recursively. +The *recursive* argument forces the VFS attribute to be applied recursively. + -The _vfs_ and _fs_ arguments specify the layer where the read-only flag should be applied. The _fs_ specifies -the filesystem superblock (unique filesystem instance in the kernel), and _vfs_ specifies the mount node. If no attribute is specified, then +The *vfs* and *fs* arguments specify the layer where the read-only flag should be applied. The *fs* specifies +the filesystem superblock (unique filesystem instance in the kernel), and *vfs* specifies the mount node. If no attribute is specified, then both layers are set to read-only. + For more details, please refer to the *Read-only Setting Notes* section. -*rw*[=_recursive_,_vfs_,_fs_]:: +*rw*[**=**(*recursive*|*vfs*|*fs*)]:: Mount the filesystem read-write. *sync*:: From 449f208a34fc1aaf0cbc08e8598ca4a0309e9db0 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:23 +0100 Subject: [PATCH 07/14] unshare: don't mark "|" and ":" as part of the placeholders The "|" is a meta-character, and should thus be left unmarked, while the ":" (in the argument of --map-users/--map-groups) is a literal, and should therefore be marked in bold. Also, add the new 'subids' literal value for the above two options. And in the bargain tweak a comment. Signed-off-by: Benno Schulenberg --- sys-utils/unshare.1.adoc | 12 ++++++------ sys-utils/unshare.c | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc index c6973f93856..2bcc193ff85 100644 --- a/sys-utils/unshare.1.adoc +++ b/sys-utils/unshare.1.adoc @@ -93,21 +93,21 @@ Just before running the program, mount the proc filesystem at _mountpoint_ (defa *--mount-binfmt*[**=**__mountpoint__]:: Just before running the program, mount the binfmt_misc filesystem at _mountpoint_ (default is /proc/sys/fs/binfmt_misc). It also implies creating a new mount namespace since the binfmt_misc mount would otherwise mess up existing programs on the system. The new binfmt_misc filesystem is explicitly mounted as private (with *MS_PRIVATE*|*MS_REC*). -*--map-user* __uid|name__:: +*--map-user* __uid__|__name__:: Run the program only after the current effective user ID has been mapped to _uid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*. -*--map-users* __inneruid:outeruid:count__|**auto**|**all**:: +*--map-users* __inneruid__**:**__outeruid__**:**__count__|**auto**|**subids**|**all**:: Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. If the range of user IDs overlaps with the mapping specified by *--map-user*, then a "hole" will be removed from the mapping. This may result in the highest user ID of the mapping not being mapped. Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*. + -Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid,inneruid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option. +Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid_**,**_inneruid_**,**_count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option. -*--map-group* __gid|name__:: +*--map-group* __gid__|__name__:: Run the program only after the current effective group ID has been mapped to _gid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--setgroups=deny* and *--user*. -*--map-groups* __innergid:outergid:count__|**auto**|**all**:: +*--map-groups* __innergid__**:**__outergid__**:**__count__|**auto**|**subids**|**all**:: Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. If the range of group IDs overlaps with the mapping specified by *--map-group*, then a "hole" will be removed from the mapping. This may result in the highest group ID of the mapping not being mapped. Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*. + -Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid,innergid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option. +Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid_**,**_innergid_**,**_count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option. *--map-auto*:: Map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. In the same manner, also map the first block of group IDs owned by the effective group from _/etc/subgid_ to a block starting at group ID 0. This option is intended to handle the common case where the first block of subordinate user and group IDs can map the whole user and group ID space. This option is equivalent to specifying *--map-users=auto* and *--map-groups=auto*. diff --git a/sys-utils/unshare.c b/sys-utils/unshare.c index 9b87acd67a0..4d078e4d585 100644 --- a/sys-utils/unshare.c +++ b/sys-utils/unshare.c @@ -413,7 +413,7 @@ static struct map_range get_map_range(const char *s) * @filename: The file to look up the range from. This should be either * ``/etc/subuid`` or ``/etc/subgid``. * @uid: The uid of the user whose range we should look up. - * @identity: (boolean) If true identity map the range, otherwise map to 0 + * @identity: (boolean) If true, identity map the range, otherwise map to 0. * * This finds the first subid range matching @uid in @filename. */ From 30dee3488c3920f124c36f656455ddcc670f5f8d Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:24 +0100 Subject: [PATCH 08/14] textual: give seven error messages the same form as two others The form with the parentheses is easier for translators: it indicates that the preceding text is not a translatable word. Signed-off-by: Benno Schulenberg --- login-utils/newgrp.c | 6 +++--- sys-utils/nsenter.c | 4 ++-- sys-utils/unshare.c | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/login-utils/newgrp.c b/login-utils/newgrp.c index b9b620ed752..ba3777b36c4 100644 --- a/login-utils/newgrp.c +++ b/login-utils/newgrp.c @@ -219,7 +219,7 @@ int main(int argc, char *argv[]) if (argc <= optind) { if (setgid(pw_entry->pw_gid) < 0) - err(EXIT_FAILURE, _("setgid failed")); + err(EXIT_FAILURE, _("setgid() failed")); } else { errno = 0; if (!(gr_entry = getgrnam(argv[optind++]))) { @@ -231,11 +231,11 @@ int main(int argc, char *argv[]) if (!allow_setgid(pw_entry, gr_entry)) errx(EXIT_FAILURE, _("permission denied")); if (setgid(gr_entry->gr_gid) < 0) - err(EXIT_FAILURE, _("setgid failed")); + err(EXIT_FAILURE, _("setgid() failed")); } if (setuid(getuid()) < 0) - err(EXIT_FAILURE, _("setuid failed")); + err(EXIT_FAILURE, _("setuid() failed")); fflush(NULL); shell = (pw_entry->pw_shell && *pw_entry->pw_shell ? diff --git a/sys-utils/nsenter.c b/sys-utils/nsenter.c index 66ce4b32429..214893d1a94 100644 --- a/sys-utils/nsenter.c +++ b/sys-utils/nsenter.c @@ -836,9 +836,9 @@ int main(int argc, char *argv[]) if (force_gid && setgroups(0, NULL) != 0 && setgroups_nerrs) /* drop supplementary groups */ err(EXIT_FAILURE, _("setgroups failed")); if (force_gid && setgid(gid) < 0) /* change GID */ - err(EXIT_FAILURE, _("setgid failed")); + err(EXIT_FAILURE, _("setgid() failed")); if (force_uid && setuid(uid) < 0) /* change UID */ - err(EXIT_FAILURE, _("setuid failed")); + err(EXIT_FAILURE, _("setuid() failed")); } if (keepcaps && (namespaces & CLONE_NEWUSER)) diff --git a/sys-utils/unshare.c b/sys-utils/unshare.c index 4d078e4d585..b6c2f8b4573 100644 --- a/sys-utils/unshare.c +++ b/sys-utils/unshare.c @@ -1270,10 +1270,10 @@ int main(int argc, char *argv[]) if (setgroups(0, NULL) != 0) /* drop supplementary groups */ err(EXIT_FAILURE, _("setgroups failed")); if (setgid(gid) < 0) /* change GID */ - err(EXIT_FAILURE, _("setgid failed")); + err(EXIT_FAILURE, _("setgid() failed")); } if (force_uid && setuid(uid) < 0) /* change UID */ - err(EXIT_FAILURE, _("setuid failed")); + err(EXIT_FAILURE, _("setuid() failed")); if (keepcaps && (unshare_flags & CLONE_NEWUSER)) cap_permitted_to_ambient(); From 7722cde3d694cb0b3f51931a96e907a23e9b4da0 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:25 +0100 Subject: [PATCH 09/14] blkpr: grammarize the description of the tool and its options Signed-off-by: Benno Schulenberg --- sys-utils/blkpr.8.adoc | 9 +++++---- sys-utils/blkpr.c | 14 +++++++------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/sys-utils/blkpr.8.adoc b/sys-utils/blkpr.8.adoc index 0f71bd0f0dd..db2b8a0a96e 100644 --- a/sys-utils/blkpr.8.adoc +++ b/sys-utils/blkpr.8.adoc @@ -8,7 +8,7 @@ == NAME -blkpr - run persistent reservations command on a device +blkpr - run a persistent-reservations command on a device == SYNOPSIS @@ -16,15 +16,16 @@ blkpr - run persistent reservations command on a device == DESCRIPTION -*blkpr* is used to run persistent reservations command on device that supports Persistent Reservations feature. +*blkpr* is used to run a persistent-reservations command on a device +that supports the Persistent Reservations feature. The _device_ argument is the pathname of the block device. == OPTIONS *-c*, *--command* _command_:: -The command of persistent reservations, supported commands are *register*, *reserve*, *release*, *preempt*, -*preempt-abort*, and *clear*. +The command for managing persistent reservations. Supported commands are: +*register*, *reserve*, *release*, *preempt*, *preempt-abort*, and *clear*. *-k*, *--key* _key_:: The key the command should operate on. diff --git a/sys-utils/blkpr.c b/sys-utils/blkpr.c index 7f88eba50cd..03ca9f7e5fd 100644 --- a/sys-utils/blkpr.c +++ b/sys-utils/blkpr.c @@ -213,12 +213,12 @@ static void __attribute__((__noreturn__)) usage(void) _(" %s [options] \n"), program_invocation_short_name); fputs(USAGE_SEPARATOR, out); - fputs(_("Persistent reservations on a device.\n"), out); + fputs(_("Manage persistent reservations on a device.\n"), out); fputs(USAGE_OPTIONS, out); - fputs(_(" -c, --command command of persistent reservations\n"), out); - fputs(_(" -k, --key key to operate\n"), out); - fputs(_(" -K, --oldkey old key to operate\n"), out); + fputs(_(" -c, --command command for persistent reservations\n"), out); + fputs(_(" -k, --key key to operate on\n"), out); + fputs(_(" -K, --oldkey old key to operate on\n"), out); fputs(_(" -f, --flag command flag\n"), out); fputs(_(" -t, --type command type\n"), out); @@ -227,13 +227,13 @@ static void __attribute__((__noreturn__)) usage(void) fputs(USAGE_ARGUMENTS, out); - fputs(_(" is an command, available command:\n"), out); + fputs(_(" is a command; available commands are:\n"), out); print_pr_command(out); - fputs(_(" is a command flag, available flags:\n"), out); + fputs(_(" is a command flag; available flags are:\n"), out); print_pr_flag(out); - fputs(_(" is a command type, available types:\n"), out); + fputs(_(" is a command type; available types are:\n"), out); print_pr_type(out); fprintf(out, USAGE_MAN_TAIL("blkpr(8)")); From b5bc7d74bf3622e7b48f86b9f472685de9a4bbd5 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:26 +0100 Subject: [PATCH 10/14] blkzone: correct the wording of an error message, from ioctl to function Signed-off-by: Benno Schulenberg --- sys-utils/blkzone.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sys-utils/blkzone.c b/sys-utils/blkzone.c index 843f3c7b0c3..9e648484b0c 100644 --- a/sys-utils/blkzone.c +++ b/sys-utils/blkzone.c @@ -149,7 +149,7 @@ static int init_device(struct blkzone_control *ctl, int mode) errx(EXIT_FAILURE, _("%s: not a block device"), ctl->devname); if (blkdev_get_sectors(fd, (unsigned long long *) &ctl->total_sectors)) - err(EXIT_FAILURE, _("%s: blkdev_get_sectors ioctl failed"), ctl->devname); + err(EXIT_FAILURE, _("%s: blkdev_get_sectors() failed"), ctl->devname); if (blkdev_get_sector_size(fd, &ctl->secsize)) err(EXIT_FAILURE, _("%s: BLKSSZGET ioctl failed"), ctl->devname); From 074fb62726e9ee54d7290d042028174bb881a7cc Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:27 +0100 Subject: [PATCH 11/14] renice: put text that belongs together into a single translatable message Also, use semicolons and no periods in an option description. Signed-off-by: Benno Schulenberg --- sys-utils/renice.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sys-utils/renice.c b/sys-utils/renice.c index 419cef46d80..eac104db306 100644 --- a/sys-utils/renice.c +++ b/sys-utils/renice.c @@ -70,10 +70,10 @@ static void __attribute__((__noreturn__)) usage(void) fputs(_("Alter the priority of running processes.\n"), out); fputs(USAGE_OPTIONS, out); - fputs(_(" -n specify the nice value\n"), out); - fputs(_(" If POSIXLY_CORRECT flag is set in environment\n"), out); - fputs(_(" then the priority is 'relative' to current\n"), out); - fputs(_(" process priority. Otherwise it is 'absolute'.\n"), out); + fputs(_(" -n specify the nice value;\n" + " if POSIXLY_CORRECT flag is set in environment,\n" + " then the priority is 'relative' to current\n" + " process priority; otherwise it is 'absolute'\n"), out); fputs(_(" --priority specify the 'absolute' nice value\n"), out); fputs(_(" --relative specify the 'relative' nice value\n"), out); fputs(_(" -p, --pid interpret arguments as process ID (default)\n"), out); From 97114dcd23a9fbe1cba762dc143a0ed76d85c03e Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:28 +0100 Subject: [PATCH 12/14] man pages: use the same verb for --version as for --help, like in usages Also, avoid duplication of --help/--version in the man page for `chfn`. Signed-off-by: Benno Schulenberg --- login-utils/chfn.1.adoc | 6 +++--- login-utils/chsh.1.adoc | 10 +++++----- man-common/help-version.adoc | 2 +- schedutils/coresched.1.adoc | 6 +----- text-utils/col.1.adoc | 2 +- 5 files changed, 11 insertions(+), 15 deletions(-) diff --git a/login-utils/chfn.1.adoc b/login-utils/chfn.1.adoc index 35a2e82cf07..527c6806c6f 100644 --- a/login-utils/chfn.1.adoc +++ b/login-utils/chfn.1.adoc @@ -50,10 +50,10 @@ Specify your home phone number. Display help text and exit. *-V*, *--version*:: -Print version and exit. The short options *-V* have been used since version 2.39; old versions use -deprecated *-v*. +Display version and exit. (Short option *-V* is used since version 2.39; +older versions used the now-deprecated *-v*). -include::man-common/help-version.adoc[] +// Do not include::man-common/help-version.adoc[] as --help and --version are already given explicitly above. == CONFIG FILE ITEMS diff --git a/login-utils/chsh.1.adoc b/login-utils/chsh.1.adoc index 940ded5aa13..e259b593f13 100644 --- a/login-utils/chsh.1.adoc +++ b/login-utils/chsh.1.adoc @@ -37,14 +37,14 @@ Specify your login shell. Print the list of shells listed in _/etc/shells_ and exit. *-h*, *--help*:: -Display help text and exit. The short options *-h* have been used since version 2.30; old versions use -deprecated *-u*. +Display help text and exit. (Short option *-h* is used since version 2.30; +older versions used the now-deprecated *-u*). *-V*, *--version*:: -Print version and exit. The short options *-V* have been used since version 2.39; old versions use -deprecated *-v*. +Display version and exit. (Short option *-V* is used since version 2.39; +older versions used the now-deprecated *-v*). -// Do not include::man-common/help-version.adoc[] as both -h and -V were already explicitly given above in more detail. +// Do not include::man-common/help-version.adoc[] as both -h and -V are already given explicitly above in more detail. == VALID SHELLS diff --git a/man-common/help-version.adoc b/man-common/help-version.adoc index 7a3c04fb9dc..8bce5760f9b 100644 --- a/man-common/help-version.adoc +++ b/man-common/help-version.adoc @@ -2,4 +2,4 @@ Display help text and exit. *-V*, *--version*:: -Print version and exit. +Display version and exit. diff --git a/schedutils/coresched.1.adoc b/schedutils/coresched.1.adoc index 8a9c28846a6..0d4c211f855 100644 --- a/schedutils/coresched.1.adoc +++ b/schedutils/coresched.1.adoc @@ -67,11 +67,7 @@ The type of the PID whose cookie will be modified. This can be one of three valu *-v*, *--verbose*:: Show extra information when modifying cookies of tasks. -*-h*, *--help*:: -Display help text and exit. - -*-V*, *--version*:: -Print version and exit. +include::man-common/help-version.adoc[] == EXAMPLES Get the core scheduling cookie of the {command} task itself, usually inherited from its parent{colon}:: diff --git a/text-utils/col.1.adoc b/text-utils/col.1.adoc index 46610f0c5bc..bc1913a9136 100644 --- a/text-utils/col.1.adoc +++ b/text-utils/col.1.adoc @@ -81,7 +81,7 @@ Output multiple spaces instead of tabs. Display help text and exit. *-V*, *--version*:: -Print version and exit. +Display version and exit. == CONFORMING TO From aed0aad70eb07761a1314b812cc940e2607a6b38 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:29 +0100 Subject: [PATCH 13/14] usage: mention also the missing KiB and MiB as permissible suffixes Also, slightly reword the phrase to be more grammatical, and make it into a full sentence that ends in a period. (By the way, commit f1970cc557 is somewhat problematic: it requires that the relevant occurrences of "" and "" in the option descriptions are now always translated in the same manner, but the translator may be unaware of this. For Dutch, the latter was the case for `ipcmk` and `zramctl`. :/ ) Signed-off-by: Benno Schulenberg --- include/c.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/c.h b/include/c.h index ec2d32c386b..dcb2d683c70 100644 --- a/include/c.h +++ b/include/c.h @@ -474,8 +474,8 @@ static inline void __attribute__((__noreturn__)) ul_sig_err(int excode, const ch #define USAGE_ARG_SEPARATOR "\n" #define USAGE_ARG_SIZE(_name) \ - _(" %s arguments may be followed by the suffixes for\n" \ - " GiB, TiB, PiB, EiB, ZiB, and YiB (the \"iB\" is optional)\n"), _name + _(" Values for %s may be followed by a suffix: KiB, MiB,\n" \ + " GiB, TiB, PiB, EiB, ZiB, or YiB (where the \"iB\" is optional).\n"), _name #define USAGE_MAN_TAIL(_man) _("\nFor more details see %s.\n"), _man From ca82120f42169d179d66662521055386b98a0358 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Sun, 9 Feb 2025 09:23:30 +0100 Subject: [PATCH 14/14] zramctl: improve grammar in usage and don't gettextize list of algorithms There is no need to translate this list as they are all literal values -- the word "and" is not needed: a comma will do. Signed-off-by: Benno Schulenberg --- sys-utils/zramctl.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sys-utils/zramctl.c b/sys-utils/zramctl.c index bdc3679cf89..dfe752bc4eb 100644 --- a/sys-utils/zramctl.c +++ b/sys-utils/zramctl.c @@ -599,8 +599,8 @@ static void __attribute__((__noreturn__)) usage(void) fputs(USAGE_ARGUMENTS, out); fprintf(out, USAGE_ARG_SIZE(_(""))); - fputs(_(" specify algorithm, supported are:\n"), out); - fputs(_(" lzo, lz4, lz4hc, deflate, 842 and zstd\n"), out); + fputs(_(" is the name of an algorithm; supported are:\n"), out); + fputs( " lzo, lz4, lz4hc, deflate, 842, zstd\n", out); fputs(_(" (List may be inaccurate, consult man page.)\n"), out); fputs(USAGE_COLUMNS, out);