[PATCH 01/10] enosys: add the missing arguments of -s and -i to the usage text

[PATCH 01/10] enosys: add the missing arguments of -s and -i to the usage text

[Benno Schulenberg]

Also, add a docstring, drop the redundant double dash from the synopsis,
add the missing -m option, and add a missing word to an error message.

CC: Thomas Weißschuh <thomas@t-8ch.de>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/enosys.c | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/misc-utils/enosys.c b/misc-utils/enosys.c
index 1410676dd..b7469c6bf 100644
--- a/misc-utils/enosys.c
+++ b/misc-utils/enosys.c
@@ -78,13 +78,17 @@ static void __attribute__((__noreturn__)) usage(void)
 	FILE *out = stdout;
 
 	fputs(USAGE_HEADER, out);
-	fprintf(out, _(" %s [options] -- <command>\n"), program_invocation_short_name);
+	fprintf(out, _(" %s [options] <command>\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Block certain system calls while running a command.\n"), out);
 
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -s, --syscall           syscall to block\n"), out);
-	fputs(_(" -i, --ioctl             ioctl to block\n"), out);
-	fputs(_(" -l, --list              list known syscalls\n"), out);
-	fputs(_(" -d, --dump[=<file>]     dump seccomp bytecode\n"), out);
+	fputs(_(" -s, --syscall <name>|<nr>    system call to block\n"), out);
+	fputs(_(" -i, --ioctl <name>|<nr>      ioctl to block\n"), out);
+	fputs(_(" -l, --list                   list known system calls\n"), out);
+	fputs(_(" -m, --list-ioctl             list known ioctls\n"), out);
+	fputs(_(" -d, --dump[=<file>]          dump bytecode of seccomp filter\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
 	fprintf(out, USAGE_HELP_OPTIONS(25));
@@ -297,7 +301,7 @@ int main(int argc, char **argv)
 		err_nosys(EXIT_FAILURE, _("Could not run prctl(PR_SET_NO_NEW_PRIVS)"));
 
 	if (ul_set_seccomp_filter_spec_allow(&prog))
-		err_nosys(EXIT_FAILURE, _("Could not seccomp filter"));
+		err_nosys(EXIT_FAILURE, _("Could not set seccomp filter"));
 
 	if (execvp(argv[optind], argv + optind))
 		err(EXIT_NOTSUPP, _("Could not exec"));
-- 
2.48.1

[PATCH 02/10] uclampset: simplify the synopsis in the --help usage text

[Benno Schulenberg]

The synopsis cannot express all possible forms of the command and still
stay readable, so do not even try.  Giving one, single synopsis is far
clearer.  Also, unabbreviate two words in the option descriptions.

Also, improve the markup and the wording in the man page.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 schedutils/uclampset.1.adoc | 4 ++--
 schedutils/uclampset.c      | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/schedutils/uclampset.1.adoc b/schedutils/uclampset.1.adoc
index 955881907..b3cdb4e7f 100644
--- a/schedutils/uclampset.1.adoc
+++ b/schedutils/uclampset.1.adoc
@@ -38,9 +38,9 @@ manipulate the utilization clamping attributes of the system or a process
 
 == SYNOPSIS
 
-*uclampset* [options] [*-m* _uclamp_min_] [*-M* _uclamp_max] _command argument_
+*uclampset* [options] [*-m* _minimum_] [*-M* _maximum_] *-p* _PID_
 
-*uclampset* [options] [*-m* _uclamp_min_] [*-M* _uclamp_max_] *-p* _PID_
+*uclampset* [options] [*-m* _minimum_] [*-M* _maximum_] _command_ [_argument_...]
 
 == DESCRIPTION
 
diff --git a/schedutils/uclampset.c b/schedutils/uclampset.c
index 4b37557a1..3aa198568 100644
--- a/schedutils/uclampset.c
+++ b/schedutils/uclampset.c
@@ -54,22 +54,22 @@ static void __attribute__((__noreturn__)) usage(void)
 
 	fputs(USAGE_HEADER, out);
 	fprintf(out,
-		_(" %1$s [options]\n"
-		  " %1$s [options] --pid <pid> | --system | <command> <arg>...\n"),
+		_(" %1$s [options] --pid <pid> | <command> [<arg>...] | --system\n"),
 		program_invocation_short_name);
 
 	fputs(USAGE_SEPARATOR, out);
 	fputs(_("Show or change the utilization clamping attributes.\n"), out);
 
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -m <value>           util_min value to set\n"), out);
-	fputs(_(" -M <value>           util_max value to set\n"), out);
+	fputs(_(" -m <value>           minimum utilization value to set\n"), out);
+	fputs(_(" -M <value>           maximum utilization value to set\n"), out);
 	fputs(_(" -a, --all-tasks      operate on all the tasks (threads) for a given pid\n"), out);
 	fputs(_(" -p, --pid <pid>      operate on existing given pid\n"), out);
 	fputs(_(" -s, --system         operate on system\n"), out);
 	fputs(_(" -R, --reset-on-fork  set reset-on-fork flag\n"), out);
 	fputs(_(" -v, --verbose        display status information\n"), out);
 
+	fputs(USAGE_SEPARATOR, out);
 	fprintf(out, USAGE_HELP_OPTIONS(22));
 
 	fputs(USAGE_SEPARATOR, out);
-- 
2.48.1

[PATCH 03/10] last: don't use a tab character in the --help usage text

[Benno Schulenberg]

Also, sort options -p and --time-format alphabetically,
like in the man page.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 login-utils/last.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/login-utils/last.c b/login-utils/last.c
index bdd375063..b7dff30c6 100644
--- a/login-utils/last.c
+++ b/login-utils/last.c
@@ -598,15 +598,15 @@ static void __attribute__((__noreturn__)) usage(const struct last_control *ctl)
 	fputs(_(" -F, --fulltimes      print full login and logout times and dates\n"), out);
 	fputs(_(" -i, --ip             display IP numbers in numbers-and-dots notation\n"), out);
 	fputs(_(" -n, --limit <number> how many lines to show\n"), out);
+	fputs(_(" -p, --present <time> display who were present at the specified time\n"), out);
 	fputs(_(" -R, --nohostname     don't display the hostname field\n"), out);
 	fputs(_(" -s, --since <time>   display the lines since the specified time\n"), out);
 	fputs(_(" -t, --until <time>   display the lines until the specified time\n"), out);
-	fputs(_(" -T, --tab-separated	use tabs as delimiters\n"), out);
-	fputs(_(" -p, --present <time> display who were present at the specified time\n"), out);
-	fputs(_(" -w, --fullnames      display full user and domain names\n"), out);
-	fputs(_(" -x, --system         display system shutdown entries and run level changes\n"), out);
+	fputs(_(" -T, --tab-separated  use tabs as delimiters\n"), out);
 	fputs(_("     --time-format <format>  show timestamps in the specified <format>:\n"
 		"                               notime|short|full|iso\n"), out);
+	fputs(_(" -w, --fullnames      display full user and domain names\n"), out);
+	fputs(_(" -x, --system         display system shutdown entries and run level changes\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
 	fprintf(out, USAGE_HELP_OPTIONS(22));
-- 
2.48.1

[PATCH 04/10] irqtop: improve the description of --batch, and align it with others

[Benno Schulenberg]

Also improve the description of --delay and tweak the one of --json,
and align both descriptions with the preceding ones.

CC: Joe Jin <joe.jin@oracle.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 sys-utils/irqtop.1.adoc | 7 ++++---
 sys-utils/irqtop.c      | 6 +++---
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/sys-utils/irqtop.1.adoc b/sys-utils/irqtop.1.adoc
index 880ee1906..04158a0ef 100644
--- a/sys-utils/irqtop.1.adoc
+++ b/sys-utils/irqtop.1.adoc
@@ -26,7 +26,8 @@ The default output is subject to change. So whenever possible, you should avoid
 Specify which output columns to print. Use *--help* to get a list of all supported columns. The default list of columns may be extended if list is specified in the format _+list_.
 
 *-b*, *--batch*::
-Starts irqtop in batch mode, which could be useful for sending output to other programs or to a file.
+Send the produced tables to stdout instead of to a static screen.
+This can be used for sending the output to other programs or to a file.
 
 *-c*, *--cpu-stat* _mode_::
 Show per-cpu statistics by specified mode. Available modes are: *auto*, *enable*, *disable*. The default option *auto* detects the width of window, then shows the per-cpu statistics if the width of window is large enough to show a full line of statistics.
@@ -35,10 +36,10 @@ Show per-cpu statistics by specified mode. Available modes are: *auto*, *enable*
 Specify cpus in list format to show.
 
 *-d*, *--delay* _seconds_::
-Update interrupt output every _seconds_ intervals.
+Update the tables every this number of seconds.
 
 *-J*, *--json*::
-Use JSON output format. irqtop will run in batch mode.
+Use JSON output format. Implies *--batch*.
 
 *-n*, *--iter* _number_::
 Specifies the maximum iterations before quitting.
diff --git a/sys-utils/irqtop.c b/sys-utils/irqtop.c
index 751e9e19b..e0abddd82 100644
--- a/sys-utils/irqtop.c
+++ b/sys-utils/irqtop.c
@@ -306,11 +306,11 @@ static void __attribute__((__noreturn__)) usage(void)
 	puts(_("Interactive utility to display kernel interrupt information."));
 
 	fputs(USAGE_OPTIONS, stdout);
-	fputs(_(" -b, --batch batch mode\n"), stdout);
+	fputs(_(" -b, --batch           send tables to stdout, not to a static screen\n"), stdout);
 	fputs(_(" -c, --cpu-stat <mode> show per-cpu stat (auto, enable, disable)\n"), stdout);
 	fputs(_(" -C, --cpu-list <list> specify cpus in list format\n"), stdout);
-	fputs(_(" -d, --delay <secs>   delay updates\n"), stdout);
-	fputs(_(" -J, --json  use JSON output format (will run in batch mode)\n"), stdout);
+	fputs(_(" -d, --delay <secs>    wait this number of seconds between updates\n"), stdout);
+	fputs(_(" -J, --json            use JSON output format (implies --batch)\n"), stdout);
 	fputs(_(" -n, --iter <number>  the maximum number of iterations\n"), stdout);
 	fputs(_(" -o, --output <list>  define which output columns to use\n"), stdout);
 	fputs(_(" -s, --sort <column>  specify sort column\n"), stdout);
-- 
2.48.1

[PATCH 05/10] irqtop: improve several more option descriptions, and align them all

[Benno Schulenberg]

Keep at least two spaces between option+argument and its description,
while making sure not to go above 80 columns per line.

Also, improve the docstring (there is no need to mention that irqtop
is a utility) and remove the ugly Q from the list of interactive keys.

CC: Joe Jin <joe.jin@oracle.com>
CC: Zhenwei Pi <pizhenwei@bytedance.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 sys-utils/irqtop.1.adoc |  4 ++--
 sys-utils/irqtop.c      | 26 +++++++++++++-------------
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/sys-utils/irqtop.1.adoc b/sys-utils/irqtop.1.adoc
index 04158a0ef..cf258d085 100644
--- a/sys-utils/irqtop.1.adoc
+++ b/sys-utils/irqtop.1.adoc
@@ -8,7 +8,7 @@
 
 == NAME
 
-irqtop - utility to display kernel interrupt information
+irqtop - display kernel interrupt information
 
 == SYNOPSIS
 
@@ -16,7 +16,7 @@ irqtop - utility to display kernel interrupt information
 
 == DESCRIPTION
 
-Display kernel interrupt counter information in *top*(1) style view.
+Display interrupt-counter information from the kernel in the style of *top*(1).
 
 The default output is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using *--output*.
 
diff --git a/sys-utils/irqtop.c b/sys-utils/irqtop.c
index e0abddd82..3dbd030e0 100644
--- a/sys-utils/irqtop.c
+++ b/sys-utils/irqtop.c
@@ -303,28 +303,28 @@ static void __attribute__((__noreturn__)) usage(void)
 	printf(_(" %s [options]\n"), program_invocation_short_name);
 	fputs(USAGE_SEPARATOR, stdout);
 
-	puts(_("Interactive utility to display kernel interrupt information."));
+	puts(_("Display kernel interrupt information."));
 
 	fputs(USAGE_OPTIONS, stdout);
-	fputs(_(" -b, --batch           send tables to stdout, not to a static screen\n"), stdout);
-	fputs(_(" -c, --cpu-stat <mode> show per-cpu stat (auto, enable, disable)\n"), stdout);
-	fputs(_(" -C, --cpu-list <list> specify cpus in list format\n"), stdout);
-	fputs(_(" -d, --delay <secs>    wait this number of seconds between updates\n"), stdout);
-	fputs(_(" -J, --json            use JSON output format (implies --batch)\n"), stdout);
-	fputs(_(" -n, --iter <number>  the maximum number of iterations\n"), stdout);
-	fputs(_(" -o, --output <list>  define which output columns to use\n"), stdout);
-	fputs(_(" -s, --sort <column>  specify sort column\n"), stdout);
-	fputs(_(" -S, --softirq        show softirqs instead of interrupts\n"), stdout);
-	fputs(_(" -t, --threshold <N>  only IRQs with counters above <N>\n"), stdout);
+	fputs(_(" -b, --batch            send tables to stdout, not to a static screen\n"), stdout);
+	fputs(_(" -c, --cpu-stat <mode>  whether to show the per-cpu stats (auto|enable|disable)\n"), stdout);
+	fputs(_(" -C, --cpu-list <list>  show IRQs only for the specified cpus\n"), stdout);
+	fputs(_(" -d, --delay <secs>     wait this number of seconds between updates\n"), stdout);
+	fputs(_(" -J, --json             use JSON output format (implies --batch)\n"), stdout);
+	fputs(_(" -n, --iter <number>    the maximum number of iterations\n"), stdout);
+	fputs(_(" -o, --output <list>    which columns to show, and in which order\n"), stdout);
+	fputs(_(" -s, --sort <column>    sort the table on this column\n"), stdout);
+	fputs(_(" -S, --softirq          show softirqs instead of interrupts\n"), stdout);
+	fputs(_(" -t, --threshold <num>  show only IRQs with counters above this number\n"), stdout);
 	fputs(USAGE_SEPARATOR, stdout);
-	fprintf(stdout, USAGE_HELP_OPTIONS(22));
+	fprintf(stdout, USAGE_HELP_OPTIONS(24));
 
 	fputs(_("\nThe following interactive key commands are valid:\n"), stdout);
 	fputs(_("  i      sort by IRQ\n"), stdout);
 	fputs(_("  t      sort by TOTAL\n"), stdout);
 	fputs(_("  d      sort by DELTA\n"), stdout);
 	fputs(_("  n      sort by NAME\n"), stdout);
-	fputs(_("  q Q    quit program\n"), stdout);
+	fputs(_("  q      quit program\n"), stdout);
 
 	fputs(USAGE_COLUMNS, stdout);
 	irq_print_columns(stdout, 0);
-- 
2.48.1

[PATCH 06/10] findmnt: (man) remove duplicated option, and correct a description

[Benno Schulenberg]

The page listed both '--shadowed' and '--shadow', while the description
of '--hyperlink' duplicated the possible values of the _mode_ argument
and mistakenly spoke of _when_.

Also, sort the options alphabetically and fix two bits of markup.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/findmnt.8.adoc | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/misc-utils/findmnt.8.adoc b/misc-utils/findmnt.8.adoc
index fe29afe77..8a679153b 100644
--- a/misc-utils/findmnt.8.adoc
+++ b/misc-utils/findmnt.8.adoc
@@ -57,9 +57,6 @@ 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_]::
-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_::
 Search in an alternative file. If used with *--fstab*, *--mtab* or *--kernel*, then it overrides the default paths. If specified more than once, then tree-like output is disabled (see the *--list* option).
 
@@ -69,6 +66,12 @@ Print the first matching filesystem only.
 *-H*, *--list-columns*::
 List the available columns, use with *--json* or *--raw* to get output in machine-readable format.
 
+*--hyperlink*[**=**_mode_]::
+Print mountpoint paths as terminal hyperlinks. The optional _mode_ argument
+can be *always*, *never*, or *auto*. If the argument is omitted, it defaults
+to *auto*, which means that hyperlinks will only be used when the output goes
+to a terminal.
+
 *-I*, *--dfi*::
 Imitate the output of *df*(1) with its *-i* option. This option is equivalent to *-o SOURCE,FSTYPE,INO.TOTAL,INO.USED,INO.AVAIL,INO.USE%,TARGET* but excludes all pseudo filesystems. Use *--all* to print all filesystems.
 
@@ -84,7 +87,7 @@ Select a filesystem using the mount node 64-bit ID, use with *--kernel=listmount
 *-J*, *--json*::
 Use JSON output format.
 
-*-k*, *--kernel*[_=method_]::
+*-k*, *--kernel*[**=**_method_]::
 Reads information about filesystems from the kernel. This is the default output. The format is tree-like and only includes mount options managed by the kernel (see also *--mtab*).
 +
 The optional argument _method_ can be either:
@@ -126,7 +129,7 @@ Produce output in the form of key="value" pairs. All potentially unsafe value ch
 +
 Note that SOURCES column, use multi-line cells. In these cases, the column use an array-like formatting in the output, for example *name=("aaa" "bbb" "ccc")*.
 
-*-p*, *--poll*[_=list_]::
+*-p*, *--poll*[**=**_list_]::
 Monitor changes in the _/proc/self/mountinfo_ file. Supported actions are: mount, umount, remount and move. More than one action may be specified in a comma-separated list. All actions are monitored by default.
 +
 The time for which *--poll* will block can be restricted with the *--timeout* or *--first-only* options.
@@ -143,9 +146,6 @@ available for umount and remount actions
 *--pseudo*::
 Print only pseudo filesystems.
 
-*--shadow*::
-Print only filesystems over-mounted by another filesystem.
-
 *-Q*, *--filter* _expr_::
 Print only the filesystems that meet the conditions specified by the expr.
 +
@@ -172,6 +172,9 @@ Explicitly define the mount source. Supported specifications are _device_, __maj
 *-s*, *--fstab*::
 Search in _/etc/fstab_. The output is in the list format (see *--list*).
 
+*--shadowed*::
+Print only filesystems that are over-mounted by another filesystem.
+
 *-T*, *--target* _path_::
 Define the mount target. If _path_ is not a mountpoint file or directory, then *findmnt* checks the _path_ elements in reverse order to get the mountpoint (this feature is supported only when searching in kernel files and unsupported for *--fstab*). It's recommended to use the option *--mountpoint* when checks of _path_ elements are unwanted and _path_ is a strictly specified mountpoint.
 
@@ -181,9 +184,6 @@ Limit the set of printed filesystems. More than one type may be specified in a c
 *--tree*::
 Enable tree-like output if possible. The options is silently ignored for tables where is missing child-parent relation (e.g., _fstab_).
 
-*--shadowed*::
-Print only filesystems over-mounted by another filesystem.
-
 *-U*, *--uniq*::
 Ignore filesystems with duplicate mount targets, thus effectively skipping over-mounted mount points.
 
@@ -193,18 +193,18 @@ Do not truncate text in columns. The default is to not truncate the *TARGET*, *S
 *-v*, *--nofsroot*::
 Do not print a [/dir] in the SOURCE column for bind mounts or btrfs subvolumes.
 
-*-w*, *--timeout* _milliseconds_::
-Specify an upper limit on the time for which *--poll* will block, in milliseconds.
-
-*-x*, *--verify*::
-Check mount table content. The default is to verify _/etc/fstab_ parsability and usability. It's possible to use this option also with *--tab-file*. It's possible to specify source (device) or target (mountpoint) to filter mount table. The option *--verbose* forces *findmnt* to print more details.
-
 *--verbose*::
 Force *findmnt* to print more information (*--verify* only for now).
 
 *--vfs-all*::
 When used with *VFS-OPTIONS* column, print all VFS (fs-independent) flags. This option is designed for auditing purposes to list also default VFS kernel mount options which are normally not listed.
 
+*-w*, *--timeout* _milliseconds_::
+Specify an upper limit on the time for which *--poll* will block, in milliseconds.
+
+*-x*, *--verify*::
+Check mount table content. The default is to verify _/etc/fstab_ parsability and usability. It's possible to use this option also with *--tab-file*. It's possible to specify source (device) or target (mountpoint) to filter mount table. The option *--verbose* forces *findmnt* to print more details.
+
 *-y*, *--shell*::
 The column name will be modified to contain only characters allowed for shell variable identifiers. This is usable, for example, with *--pairs*. Note that this feature has been automatically enabled for *--pairs* in version 2.37, but due to compatibility issues, now it's necessary to request this behavior by *--shell*.
 
-- 
2.48.1

[PATCH 07/10] hardlink: fix typoed semicolon to colon in error message

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/hardlink.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/misc-utils/hardlink.c b/misc-utils/hardlink.c
index ae8215901..0849f9102 100644
--- a/misc-utils/hardlink.c
+++ b/misc-utils/hardlink.c
@@ -1385,7 +1385,7 @@ static int parse_options(int argc, char *argv[])
 				else if (strcmp(optarg, "never") == 0)
 					reflink_mode = REFLINK_NEVER;
 				else
-					errx(EXIT_FAILURE, _("unsupported reflink mode; %s"), optarg);
+					errx(EXIT_FAILURE, _("unsupported reflink mode: %s"), optarg);
 			}
 			if (reflink_mode != REFLINK_NEVER)
 				reflinks_skip = 1;
-- 
2.48.1

[PATCH 08/10] lsblk: (man) remove the incorrect spaces between the arguments of --ct

[Benno Schulenberg]

Also, unabbreviate some needless abbreviations,
and improve some wordings and markup.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/lsblk.8.adoc | 52 +++++++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git a/misc-utils/lsblk.8.adoc b/misc-utils/lsblk.8.adoc
index 7a0a15d3a..742fe5f68 100644
--- a/misc-utils/lsblk.8.adoc
+++ b/misc-utils/lsblk.8.adoc
@@ -105,45 +105,51 @@ Produce output in the form of key="value" pairs. The output lines are still orde
 *-p*, *--paths*::
 Print full device paths.
 
-*-Q*, *--filter* _expr_::
-Print only the devices that meet the conditions specified by the expr. The
-filter is assessed prior to lsblk collecting data for all output columns. Only
+*-Q*, *--filter* _expression_::
+Print only the devices that meet the conditions specified by _expression_. The
+filter is assessed prior to *lsblk* collecting data for all output columns. Only
 the necessary data for the lazy evaluation of the expression is retrieved from
 the system. This approach can enhance performance when compared to
-post-filtering, as commonly done by tools such as grep(1).
+post-filtering, as commonly done by tools such as *grep*(1).
 +
-This feature is EXPERIMENTAL. See also *scols-filter*(5). For example
-exclude sda  and sdb, but print everything else ('!~' is a negative regular
-expression matching operator):
+This feature is EXPERIMENTAL. See also *scols-filter*(5).
++
+For example, to exclude sda and sdb, but print everything else
+('!~' is a negative regular-expression matching operator):
 ____
  lsblk --filter 'NAME !~ "sd[ab]"'
 ____
 
-*--highlight* _expr_::
-Colorize lines matching the expression.
+*--highlight* _expression_::
+Colorize lines matching _expression_.
++
 This feature is EXPERIMENTAL. See also *scols-filter*(5).
 
-*--ct* _name_ [: _param_ [: _function_ ]]::
-Define a custom counter. The counters are printed after the standard output.
-The _name_ is the custom name of the counter, the optional _param_ is the name of the column
-to be used for the counter, and the optional _function_ specifies
-the aggregation function, supported functions are: count, min, max, or sum. The
-default is count.
+*--ct* _name_[**:**_parameter_[**:**_function_]]::
+Define a custom counter. Custom counters are printed after the standard output.
+The _name_ is the custom name of the counter, the optional _parameter_ is the name
+of the column to be used for the counter, and the optional _function_ specifies
+the aggregation function. Supported functions are: *count*, *min*, *max*, *sum*.
+The default function is *count*. If _parameter_ is not specified, then the counter
+counts the number of lines.
 +
-If the _param_ is not specified, then the counter counts the number of lines. This
-feature is EXPERIMENTAL. See also *--ct-filter*.
+This feature is EXPERIMENTAL. See also *--ct-filter*.
 +
-For example, *--ct MyCounter:SIZE:sum* will count the summary for SIZE from all lines;
-and to count the number of SATA disks, it is possible to use:
+For example, *--ct MyCounter:SIZE:sum* reports the total of the SIZE values.
+To report the number of SATA disks, one can use:
 ____
 
- lsblk --ct-filter 'TYPE=="disk" && TRAN=="sata"' --ct "Number of SATA devices"
+ lsblk --ct-filter 'TYPE=="disk" && TRAN=="sata"' \
+       --ct "Number of SATA devices"
 ____
 
 
-*--ct-filter* _expr_::
-Define a restriction for the next counter. This feature is EXPERIMENTAL. See also *--ct*
-and *scols-filter*(5). For example, aggregate sizes by device type:
+*--ct-filter* _expression_::
+Define a restriction for the next counter.
++
+This feature is EXPERIMENTAL. See also *--ct* and *scols-filter*(5).
++
+For example, to aggregate sizes by device type:
 ____
  lsblk --ct-filter 'TYPE=="part"' --ct Partitions:SIZE:sum \
        --ct-filter 'TYPE=="disk"' --ct WholeDisks:SIZE:sum
-- 
2.48.1

[PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text

[Benno Schulenberg]

Also, use semicolons instead of periods in option descriptions.

And consistently use an uppercased "PID" in feedback messages.

CC: Phil Auld <pauld@redhat.com>
CC: Thijs Raymakers <thijs@raymakers.nl>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 schedutils/coresched.c | 33 +++++++++++++--------------------
 1 file changed, 13 insertions(+), 20 deletions(-)

diff --git a/schedutils/coresched.c b/schedutils/coresched.c
index 9d8be3e12..7634d988c 100644
--- a/schedutils/coresched.c
+++ b/schedutils/coresched.c
@@ -80,31 +80,24 @@ static void __attribute__((__noreturn__)) usage(void)
 		program_invocation_short_name);
 
 	fputs(USAGE_SEPARATOR, stdout);
-	fputsln(_("Manage core scheduling cookies for tasks."), stdout);
+	fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
 
 	fputs(USAGE_FUNCTIONS, stdout);
-	fputsln(_(" get                      retrieve the core scheduling cookie of a PID"),
-		stdout);
-	fputsln(_(" new                      assign a new core scheduling cookie to an existing\n"
-		  "                            PID or execute a program with a new cookie"),
-		stdout);
-	fputsln(_(" copy                     copy the core scheduling cookie from an existing PID\n"
-		  "                            to another PID, or execute a program with that\n"
-		  "                            copied cookie"),
-		stdout);
+	fputsln(_(" get      retrieve the core-scheduling cookie of a PID"), stdout);
+	fputsln(_(" new      assign a new cookie to an existing PID,\n"
+		  "            or execute a program with a new cookie"), stdout);
+	fputsln(_(" copy     copy the cookie from an existing PID to another PID,\n"
+		  "            or execute a program with that copied cookie"), stdout);
 
 	fputs(USAGE_OPTIONS, stdout);
 	fprintf(stdout,
-		_(" -s, --source <PID>       which PID to get the cookie from\n"
-		  "                            If omitted, it is the PID of %s itself\n"),
+		_(" -s, --source <PID>       which PID to get the cookie from; if this option\n"
+		  "                            is omitted, the PID of %s itself is used\n"),
 		program_invocation_short_name);
-	fputsln(_(" -d, --dest <PID>         which PID to modify the cookie of\n"),
-		stdout);
-	fputsln(_(" -t, --dest-type <TYPE>   type of the destination PID, or the type of the PID\n"
-		  "                            when a new core scheduling cookie is created.\n"
-		  "                            Can be one of the following: pid, tgid or pgid.\n"
-		  "                            The default is tgid."),
-		stdout);
+	fputsln(_(" -d, --dest <PID>         which PID to modify the cookie of"), stdout);
+	fputsln(_(" -t, --dest-type <TYPE>   type of the new or destination PID; can be one\n"
+		  "                            of: pid, tgid, pgid; default: tgid"), stdout);
+
 	fputs(USAGE_SEPARATOR, stdout);
 	fputsln(_(" -v, --verbose      verbose"), stdout);
 	fprintf(stdout, USAGE_HELP_OPTIONS(20));
@@ -341,7 +334,7 @@ int main(int argc, char **argv)
 	switch (args.cmd) {
 	case SCHED_CORE_CMD_GET:
 		cookie = core_sched_get_cookie(args.src);
-		printf(_("cookie of pid %d is 0x%llx\n"), args.src, cookie);
+		printf(_("cookie of PID %d is 0x%llx\n"), args.src, cookie);
 		break;
 	case SCHED_CORE_CMD_NEW:
 		if (args.exec_argv_offset) {
-- 
2.48.1

[PATCH 10/10] coresched: rename option '--dest-type' to just '--type'

[Benno Schulenberg]

Long options are nice, but they should be as different from each other
as possible, so that one can abbreviate them to just a few letters.
(Not that abbreviating matters here, but that is the general idea.)

The side effect of this change is that the usage text becomes more
readable.

CC: Phil Auld <pauld@redhat.com>
CC: Thijs Raymakers <thijs@raymakers.nl>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 bash-completion/coresched |  6 +++---
 schedutils/coresched.c    | 19 +++++++++----------
 2 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/bash-completion/coresched b/bash-completion/coresched
index 3a14c5080..a502207e4 100644
--- a/bash-completion/coresched
+++ b/bash-completion/coresched
@@ -18,7 +18,7 @@ _coresched_module()
       COMPREPLY=( $(compgen -W "$sorted_pids" -- "$2") )
       return 0
       ;;
-    "-t"|"--dest-type")
+    "-t"|"--type")
       COMPREPLY=( $(compgen -W "pid tgid pgid" -- "$2") )
       return 0
       ;;
@@ -35,11 +35,11 @@ _coresched_module()
       return 0
       ;;
     'new')
-      COMPREPLY=( $(compgen -W "--dest -- --dest-type --verbose" -- "$2") )
+      COMPREPLY=( $(compgen -W "--dest -- --type --verbose" -- "$2") )
       return 0
       ;;
     'copy')
-      COMPREPLY=( $(compgen -W "--source --dest -- --dest-type --verbose" -- "$2") )
+      COMPREPLY=( $(compgen -W "--source --dest -- --type --verbose" -- "$2") )
       return 0
       ;;
     '-h'|'--help'|'-V'|'--version')
diff --git a/schedutils/coresched.c b/schedutils/coresched.c
index 7634d988c..62eac4b98 100644
--- a/schedutils/coresched.c
+++ b/schedutils/coresched.c
@@ -91,16 +91,16 @@ static void __attribute__((__noreturn__)) usage(void)
 
 	fputs(USAGE_OPTIONS, stdout);
 	fprintf(stdout,
-		_(" -s, --source <PID>       which PID to get the cookie from; if this option\n"
-		  "                            is omitted, the PID of %s itself is used\n"),
+		_(" -s, --source <PID>   which PID to get the cookie from; if this option\n"
+		  "                        is omitted, the PID of %s itself is used\n"),
 		program_invocation_short_name);
-	fputsln(_(" -d, --dest <PID>         which PID to modify the cookie of"), stdout);
-	fputsln(_(" -t, --dest-type <TYPE>   type of the new or destination PID; can be one\n"
-		  "                            of: pid, tgid, pgid; default: tgid"), stdout);
+	fputsln(_(" -d, --dest <PID>     which PID to modify the cookie of"), stdout);
+	fputsln(_(" -t, --type <TYPE>    the type of the new or destination PID; can be\n"
+		  "                        one of: pid, tgid, pgid; default: tgid"), stdout);
 
 	fputs(USAGE_SEPARATOR, stdout);
-	fputsln(_(" -v, --verbose      verbose"), stdout);
-	fprintf(stdout, USAGE_HELP_OPTIONS(20));
+	fputsln(_(" -v, --verbose        say what is being done"), stdout);
+	fprintf(stdout, USAGE_HELP_OPTIONS(22));
 	fprintf(stdout, USAGE_MAN_TAIL("coresched(1)"));
 	exit(EXIT_SUCCESS);
 }
@@ -210,8 +210,7 @@ static sched_core_scope parse_core_sched_type(char *str)
 	else if (!strcmp(str, "pgid"))
 		return PR_SCHED_CORE_SCOPE_PROCESS_GROUP;
 
-	bad_usage(_("'%s' is an invalid option. Must be one of pid/tgid/pgid"),
-		  str);
+	bad_usage(_("'%s' is an invalid type; must be one of pid/tgid/pgid"), str);
 }
 
 static void parse_and_verify_arguments(int argc, char **argv, struct args *args)
@@ -221,7 +220,7 @@ static void parse_and_verify_arguments(int argc, char **argv, struct args *args)
 	static const struct option longopts[] = {
 		{ "source", required_argument, NULL, 's' },
 		{ "dest", required_argument, NULL, 'd' },
-		{ "dest-type", required_argument, NULL, 't' },
+		{ "type", required_argument, NULL, 't' },
 		{ "verbose", no_argument, NULL, 'v' },
 		{ "version", no_argument, NULL, 'V' },
 		{ "help", no_argument, NULL, 'h' },
-- 
2.48.1

Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text

[Phil Auld]

On Mon, Mar 31, 2025 at 11:44:42AM +0200 Benno Schulenberg wrote:
> Also, use semicolons instead of periods in option descriptions.
> 
> And consistently use an uppercased "PID" in feedback messages.
> 
> CC: Phil Auld <pauld@redhat.com>
> CC: Thijs Raymakers <thijs@raymakers.nl>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>

This looks like a reasonble cleanup I guess.


Acked-by; Phil Auld <pauld@redhat.com>


Cheers,
Phil

> ---
>  schedutils/coresched.c | 33 +++++++++++++--------------------
>  1 file changed, 13 insertions(+), 20 deletions(-)
> 
> diff --git a/schedutils/coresched.c b/schedutils/coresched.c
> index 9d8be3e12..7634d988c 100644
> --- a/schedutils/coresched.c
> +++ b/schedutils/coresched.c
> @@ -80,31 +80,24 @@ static void __attribute__((__noreturn__)) usage(void)
>  		program_invocation_short_name);
>  
>  	fputs(USAGE_SEPARATOR, stdout);
> -	fputsln(_("Manage core scheduling cookies for tasks."), stdout);
> +	fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
>  
>  	fputs(USAGE_FUNCTIONS, stdout);
> -	fputsln(_(" get                      retrieve the core scheduling cookie of a PID"),
> -		stdout);
> -	fputsln(_(" new                      assign a new core scheduling cookie to an existing\n"
> -		  "                            PID or execute a program with a new cookie"),
> -		stdout);
> -	fputsln(_(" copy                     copy the core scheduling cookie from an existing PID\n"
> -		  "                            to another PID, or execute a program with that\n"
> -		  "                            copied cookie"),
> -		stdout);
> +	fputsln(_(" get      retrieve the core-scheduling cookie of a PID"), stdout);
> +	fputsln(_(" new      assign a new cookie to an existing PID,\n"
> +		  "            or execute a program with a new cookie"), stdout);
> +	fputsln(_(" copy     copy the cookie from an existing PID to another PID,\n"
> +		  "            or execute a program with that copied cookie"), stdout);
>  
>  	fputs(USAGE_OPTIONS, stdout);
>  	fprintf(stdout,
> -		_(" -s, --source <PID>       which PID to get the cookie from\n"
> -		  "                            If omitted, it is the PID of %s itself\n"),
> +		_(" -s, --source <PID>       which PID to get the cookie from; if this option\n"
> +		  "                            is omitted, the PID of %s itself is used\n"),
>  		program_invocation_short_name);
> -	fputsln(_(" -d, --dest <PID>         which PID to modify the cookie of\n"),
> -		stdout);
> -	fputsln(_(" -t, --dest-type <TYPE>   type of the destination PID, or the type of the PID\n"
> -		  "                            when a new core scheduling cookie is created.\n"
> -		  "                            Can be one of the following: pid, tgid or pgid.\n"
> -		  "                            The default is tgid."),
> -		stdout);
> +	fputsln(_(" -d, --dest <PID>         which PID to modify the cookie of"), stdout);
> +	fputsln(_(" -t, --dest-type <TYPE>   type of the new or destination PID; can be one\n"
> +		  "                            of: pid, tgid, pgid; default: tgid"), stdout);
> +
>  	fputs(USAGE_SEPARATOR, stdout);
>  	fputsln(_(" -v, --verbose      verbose"), stdout);
>  	fprintf(stdout, USAGE_HELP_OPTIONS(20));
> @@ -341,7 +334,7 @@ int main(int argc, char **argv)
>  	switch (args.cmd) {
>  	case SCHED_CORE_CMD_GET:
>  		cookie = core_sched_get_cookie(args.src);
> -		printf(_("cookie of pid %d is 0x%llx\n"), args.src, cookie);
> +		printf(_("cookie of PID %d is 0x%llx\n"), args.src, cookie);
>  		break;
>  	case SCHED_CORE_CMD_NEW:
>  		if (args.exec_argv_offset) {
> -- 
> 2.48.1
> 
> 

-- 

Re: [PATCH 10/10] coresched: rename option '--dest-type' to just '--type'

[Phil Auld]

Hi Benno,

On Mon, Mar 31, 2025 at 11:44:43AM +0200 Benno Schulenberg wrote:
> Long options are nice, but they should be as different from each other
> as possible, so that one can abbreviate them to just a few letters.
> (Not that abbreviating matters here, but that is the general idea.)
> 
> The side effect of this change is that the usage text becomes more
> readable.
>

This one seems a bit more like bike-shedding. We did go around a bit
during development.  I don't remember if a version of util-linux has
shipped with this in it or not yet but this could break users. There
may not be that many yet anyway, of course.


Cheers,
Phil


> CC: Phil Auld <pauld@redhat.com>
> CC: Thijs Raymakers <thijs@raymakers.nl>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> ---
>  bash-completion/coresched |  6 +++---
>  schedutils/coresched.c    | 19 +++++++++----------
>  2 files changed, 12 insertions(+), 13 deletions(-)
> 
> diff --git a/bash-completion/coresched b/bash-completion/coresched
> index 3a14c5080..a502207e4 100644
> --- a/bash-completion/coresched
> +++ b/bash-completion/coresched
> @@ -18,7 +18,7 @@ _coresched_module()
>        COMPREPLY=( $(compgen -W "$sorted_pids" -- "$2") )
>        return 0
>        ;;
> -    "-t"|"--dest-type")
> +    "-t"|"--type")
>        COMPREPLY=( $(compgen -W "pid tgid pgid" -- "$2") )
>        return 0
>        ;;
> @@ -35,11 +35,11 @@ _coresched_module()
>        return 0
>        ;;
>      'new')
> -      COMPREPLY=( $(compgen -W "--dest -- --dest-type --verbose" -- "$2") )
> +      COMPREPLY=( $(compgen -W "--dest -- --type --verbose" -- "$2") )
>        return 0
>        ;;
>      'copy')
> -      COMPREPLY=( $(compgen -W "--source --dest -- --dest-type --verbose" -- "$2") )
> +      COMPREPLY=( $(compgen -W "--source --dest -- --type --verbose" -- "$2") )
>        return 0
>        ;;
>      '-h'|'--help'|'-V'|'--version')
> diff --git a/schedutils/coresched.c b/schedutils/coresched.c
> index 7634d988c..62eac4b98 100644
> --- a/schedutils/coresched.c
> +++ b/schedutils/coresched.c
> @@ -91,16 +91,16 @@ static void __attribute__((__noreturn__)) usage(void)
>  
>  	fputs(USAGE_OPTIONS, stdout);
>  	fprintf(stdout,
> -		_(" -s, --source <PID>       which PID to get the cookie from; if this option\n"
> -		  "                            is omitted, the PID of %s itself is used\n"),
> +		_(" -s, --source <PID>   which PID to get the cookie from; if this option\n"
> +		  "                        is omitted, the PID of %s itself is used\n"),
>  		program_invocation_short_name);
> -	fputsln(_(" -d, --dest <PID>         which PID to modify the cookie of"), stdout);
> -	fputsln(_(" -t, --dest-type <TYPE>   type of the new or destination PID; can be one\n"
> -		  "                            of: pid, tgid, pgid; default: tgid"), stdout);
> +	fputsln(_(" -d, --dest <PID>     which PID to modify the cookie of"), stdout);
> +	fputsln(_(" -t, --type <TYPE>    the type of the new or destination PID; can be\n"
> +		  "                        one of: pid, tgid, pgid; default: tgid"), stdout);
>  
>  	fputs(USAGE_SEPARATOR, stdout);
> -	fputsln(_(" -v, --verbose      verbose"), stdout);
> -	fprintf(stdout, USAGE_HELP_OPTIONS(20));
> +	fputsln(_(" -v, --verbose        say what is being done"), stdout);
> +	fprintf(stdout, USAGE_HELP_OPTIONS(22));
>  	fprintf(stdout, USAGE_MAN_TAIL("coresched(1)"));
>  	exit(EXIT_SUCCESS);
>  }
> @@ -210,8 +210,7 @@ static sched_core_scope parse_core_sched_type(char *str)
>  	else if (!strcmp(str, "pgid"))
>  		return PR_SCHED_CORE_SCOPE_PROCESS_GROUP;
>  
> -	bad_usage(_("'%s' is an invalid option. Must be one of pid/tgid/pgid"),
> -		  str);
> +	bad_usage(_("'%s' is an invalid type; must be one of pid/tgid/pgid"), str);
>  }
>  
>  static void parse_and_verify_arguments(int argc, char **argv, struct args *args)
> @@ -221,7 +220,7 @@ static void parse_and_verify_arguments(int argc, char **argv, struct args *args)
>  	static const struct option longopts[] = {
>  		{ "source", required_argument, NULL, 's' },
>  		{ "dest", required_argument, NULL, 'd' },
> -		{ "dest-type", required_argument, NULL, 't' },
> +		{ "type", required_argument, NULL, 't' },
>  		{ "verbose", no_argument, NULL, 'v' },
>  		{ "version", no_argument, NULL, 'V' },
>  		{ "help", no_argument, NULL, 'h' },
> -- 
> 2.48.1
> 
> 

-- 

Re: [PATCH 04/10] irqtop: improve the description of --batch, and align it with others

[Joe Jin]

Change looks good to me.
Reviewed-by: Joe Jin <joe.jin@oracle.com>

Thanks,
Joe

On 3/31/25 02:44, Benno Schulenberg wrote:
> Also improve the description of --delay and tweak the one of --json,
> and align both descriptions with the preceding ones.
>
> CC: Joe Jin <joe.jin@oracle.com>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> ---
>  sys-utils/irqtop.1.adoc | 7 ++++---
>  sys-utils/irqtop.c      | 6 +++---
>  2 files changed, 7 insertions(+), 6 deletions(-)
>
> diff --git a/sys-utils/irqtop.1.adoc b/sys-utils/irqtop.1.adoc
> index 880ee1906..04158a0ef 100644
> --- a/sys-utils/irqtop.1.adoc
> +++ b/sys-utils/irqtop.1.adoc
> @@ -26,7 +26,8 @@ The default output is subject to change. So whenever possible, you should avoid
>  Specify which output columns to print. Use *--help* to get a list of all supported columns. The default list of columns may be extended if list is specified in the format _+list_.
>  
>  *-b*, *--batch*::
> -Starts irqtop in batch mode, which could be useful for sending output to other programs or to a file.
> +Send the produced tables to stdout instead of to a static screen.
> +This can be used for sending the output to other programs or to a file.
>  
>  *-c*, *--cpu-stat* _mode_::
>  Show per-cpu statistics by specified mode. Available modes are: *auto*, *enable*, *disable*. The default option *auto* detects the width of window, then shows the per-cpu statistics if the width of window is large enough to show a full line of statistics.
> @@ -35,10 +36,10 @@ Show per-cpu statistics by specified mode. Available modes are: *auto*, *enable*
>  Specify cpus in list format to show.
>  
>  *-d*, *--delay* _seconds_::
> -Update interrupt output every _seconds_ intervals.
> +Update the tables every this number of seconds.
>  
>  *-J*, *--json*::
> -Use JSON output format. irqtop will run in batch mode.
> +Use JSON output format. Implies *--batch*.
>  
>  *-n*, *--iter* _number_::
>  Specifies the maximum iterations before quitting.
> diff --git a/sys-utils/irqtop.c b/sys-utils/irqtop.c
> index 751e9e19b..e0abddd82 100644
> --- a/sys-utils/irqtop.c
> +++ b/sys-utils/irqtop.c
> @@ -306,11 +306,11 @@ static void __attribute__((__noreturn__)) usage(void)
>  	puts(_("Interactive utility to display kernel interrupt information."));
>  
>  	fputs(USAGE_OPTIONS, stdout);
> -	fputs(_(" -b, --batch batch mode\n"), stdout);
> +	fputs(_(" -b, --batch           send tables to stdout, not to a static screen\n"), stdout);
>  	fputs(_(" -c, --cpu-stat <mode> show per-cpu stat (auto, enable, disable)\n"), stdout);
>  	fputs(_(" -C, --cpu-list <list> specify cpus in list format\n"), stdout);
> -	fputs(_(" -d, --delay <secs>   delay updates\n"), stdout);
> -	fputs(_(" -J, --json  use JSON output format (will run in batch mode)\n"), stdout);
> +	fputs(_(" -d, --delay <secs>    wait this number of seconds between updates\n"), stdout);
> +	fputs(_(" -J, --json            use JSON output format (implies --batch)\n"), stdout);
>  	fputs(_(" -n, --iter <number>  the maximum number of iterations\n"), stdout);
>  	fputs(_(" -o, --output <list>  define which output columns to use\n"), stdout);
>  	fputs(_(" -s, --sort <column>  specify sort column\n"), stdout);

Re: [PATCH 05/10] irqtop: improve several more option descriptions, and align them all

[Joe Jin]

On 3/31/25 02:44, Benno Schulenberg wrote:
> Keep at least two spaces between option+argument and its description,
> while making sure not to go above 80 columns per line.
>
> Also, improve the docstring (there is no need to mention that irqtop
> is a utility) and remove the ugly Q from the list of interactive keys.
>
> CC: Joe Jin <joe.jin@oracle.com>
> CC: Zhenwei Pi <pizhenwei@bytedance.com>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> ---
>  sys-utils/irqtop.1.adoc |  4 ++--
>  sys-utils/irqtop.c      | 26 +++++++++++++-------------
>  2 files changed, 15 insertions(+), 15 deletions(-)
>
> diff --git a/sys-utils/irqtop.1.adoc b/sys-utils/irqtop.1.adoc
> index 04158a0ef..cf258d085 100644
> --- a/sys-utils/irqtop.1.adoc
> +++ b/sys-utils/irqtop.1.adoc
> @@ -8,7 +8,7 @@
>  
>  == NAME
>  
> -irqtop - utility to display kernel interrupt information
> +irqtop - display kernel interrupt information
>  
>  == SYNOPSIS
>  
> @@ -16,7 +16,7 @@ irqtop - utility to display kernel interrupt information
>  
>  == DESCRIPTION
>  
> -Display kernel interrupt counter information in *top*(1) style view.
> +Display interrupt-counter information from the kernel in the style of *top*(1).
>  
>  The default output is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using *--output*.
>  
> diff --git a/sys-utils/irqtop.c b/sys-utils/irqtop.c
> index e0abddd82..3dbd030e0 100644
> --- a/sys-utils/irqtop.c
> +++ b/sys-utils/irqtop.c
> @@ -303,28 +303,28 @@ static void __attribute__((__noreturn__)) usage(void)
>  	printf(_(" %s [options]\n"), program_invocation_short_name);
>  	fputs(USAGE_SEPARATOR, stdout);
>  
> -	puts(_("Interactive utility to display kernel interrupt information."));
> +	puts(_("Display kernel interrupt information."));
>  
>  	fputs(USAGE_OPTIONS, stdout);
> -	fputs(_(" -b, --batch           send tables to stdout, not to a static screen\n"), stdout);
> -	fputs(_(" -c, --cpu-stat <mode> show per-cpu stat (auto, enable, disable)\n"), stdout);
> -	fputs(_(" -C, --cpu-list <list> specify cpus in list format\n"), stdout);
> -	fputs(_(" -d, --delay <secs>    wait this number of seconds between updates\n"), stdout);
> -	fputs(_(" -J, --json            use JSON output format (implies --batch)\n"), stdout);
> -	fputs(_(" -n, --iter <number>  the maximum number of iterations\n"), stdout);
> -	fputs(_(" -o, --output <list>  define which output columns to use\n"), stdout);
> -	fputs(_(" -s, --sort <column>  specify sort column\n"), stdout);
> -	fputs(_(" -S, --softirq        show softirqs instead of interrupts\n"), stdout);
> -	fputs(_(" -t, --threshold <N>  only IRQs with counters above <N>\n"), stdout);
> +	fputs(_(" -b, --batch            send tables to stdout, not to a static screen\n"), stdout);
> +	fputs(_(" -c, --cpu-stat <mode>  whether to show the per-cpu stats (auto|enable|disable)\n"), stdout);
> +	fputs(_(" -C, --cpu-list <list>  show IRQs only for the specified cpus\n"), stdout);
> +	fputs(_(" -d, --delay <secs>     wait this number of seconds between updates\n"), stdout);
> +	fputs(_(" -J, --json             use JSON output format (implies --batch)\n"), stdout);
> +	fputs(_(" -n, --iter <number>    the maximum number of iterations\n"), stdout);
> +	fputs(_(" -o, --output <list>    which columns to show, and in which order\n"), stdout);
> +	fputs(_(" -s, --sort <column>    sort the table on this column\n"), stdout);
> +	fputs(_(" -S, --softirq          show softirqs instead of interrupts\n"), stdout);
> +	fputs(_(" -t, --threshold <num>  show only IRQs with counters above this number\n"), stdout);
>  	fputs(USAGE_SEPARATOR, stdout);
> -	fprintf(stdout, USAGE_HELP_OPTIONS(22));
> +	fprintf(stdout, USAGE_HELP_OPTIONS(24));
>  
>  	fputs(_("\nThe following interactive key commands are valid:\n"), stdout);
>  	fputs(_("  i      sort by IRQ\n"), stdout);
>  	fputs(_("  t      sort by TOTAL\n"), stdout);
>  	fputs(_("  d      sort by DELTA\n"), stdout);
>  	fputs(_("  n      sort by NAME\n"), stdout);
> -	fputs(_("  q Q    quit program\n"), stdout);
> +	fputs(_("  q      quit program\n"), stdout);

Why remove the "Q"?

Thanks,
Joe

>  
>  	fputs(USAGE_COLUMNS, stdout);
>  	irq_print_columns(stdout, 0);

Re: [PATCH 05/10] irqtop: improve several more option descriptions, and align them all

[Benno Schulenberg]

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


Op 31-03-2025 om 17:02 schreef Joe Jin:
> On 3/31/25 02:44, Benno Schulenberg wrote:
>>   	fputs(_("\nThe following interactive key commands are valid:\n"), stdout);
>>   	fputs(_("  i      sort by IRQ\n"), stdout);
>>   	fputs(_("  t      sort by TOTAL\n"), stdout);
>>   	fputs(_("  d      sort by DELTA\n"), stdout);
>>   	fputs(_("  n      sort by NAME\n"), stdout);
>> -	fputs(_("  q Q    quit program\n"), stdout);
>> +	fputs(_("  q      quit program\n"), stdout);
> 
> Why remove the "Q"?

It looks ugly.  And why would the user want to hold Shift before pressing q,
when just pressing q will do?  Holding Shift has no extra effect.

If the user has CapsLock activated, they will simply press the q key, and
expect it to work -- and it will work, like they know from other tools.
No need to explicitly mention this, because it makes it seem as if it is
something special.


Benno


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

Re: [PATCH 05/10] irqtop: improve several more option descriptions, and align them all

[Joe Jin]

On 3/31/25 08:47, Benno Schulenberg wrote:
>
> Op 31-03-2025 om 17:02 schreef Joe Jin:
>> On 3/31/25 02:44, Benno Schulenberg wrote:
>>>       fputs(_("\nThe following interactive key commands are valid:\n"), stdout);
>>>       fputs(_("  i      sort by IRQ\n"), stdout);
>>>       fputs(_("  t      sort by TOTAL\n"), stdout);
>>>       fputs(_("  d      sort by DELTA\n"), stdout);
>>>       fputs(_("  n      sort by NAME\n"), stdout);
>>> -    fputs(_("  q Q    quit program\n"), stdout);
>>> +    fputs(_("  q      quit program\n"), stdout);
>>
>> Why remove the "Q"?
>
> It looks ugly.  And why would the user want to hold Shift before pressing q,
> when just pressing q will do?  Holding Shift has no extra effect.

Then should it be removed from parse_input() as well?

Thanks,
Joe

>
> If the user has CapsLock activated, they will simply press the q key, and
> expect it to work -- and it will work, like they know from other tools.
> No need to explicitly mention this, because it makes it seem as if it is
> something special.
>
>
> Benno
>

Re: [PATCH 10/10] coresched: rename option '--dest-type' to just '--type'

[Karel Zak]

On Mon, Mar 31, 2025 at 07:09:02AM -0400, Phil Auld wrote:
> Hi Benno,
> 
> On Mon, Mar 31, 2025 at 11:44:43AM +0200 Benno Schulenberg wrote:
> > Long options are nice, but they should be as different from each other
> > as possible, so that one can abbreviate them to just a few letters.
> > (Not that abbreviating matters here, but that is the general idea.)
> > 
> > The side effect of this change is that the usage text becomes more
> > readable.
> >
> 
> This one seems a bit more like bike-shedding. We did go around a bit
> during development.  I don't remember if a version of util-linux has
> shipped with this in it or not yet but this could break users. There
> may not be that many yet anyway, of course.

It's already released, so it is truly a backward-incompatible change.

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 05/10] irqtop: improve several more option descriptions, and align them all

[Benno Schulenberg]

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


Op 31-03-2025 om 18:12 schreef Joe Jin:
>>> Why remove the "Q"?
>>
>> It looks ugly.  And why would the user want to hold Shift before pressing q,
>> when just pressing q will do?  Holding Shift has no extra effect.
> 
> Then should it be removed from parse_input() as well?

No, there it should stay, to accommodate users that for some reason
have CapsLock engaged.

I would propose the opposite change: to accept also the uppercase I,
T, D, and N for sorting the table on the corresponding column.


Benno


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

Re: [PATCH 10/10] coresched: rename option '--dest-type' to just '--type'

[Benno Schulenberg]

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


Op 01-04-2025 om 10:35 schreef Karel Zak:
> On Mon, Mar 31, 2025 at 07:09:02AM -0400, Phil Auld wrote:
>> but this could break users. There
>> may not be that many yet anyway, of course.
> 
> It's already released, so it is truly a backward-incompatible change.

Users of a brand-new tool really should expect some iterations in the
next versions to improve the feel of it.  So I don't see a problem in
correcting a poor choice for a long-option name.


Benno


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

Re: [PATCH 10/10] coresched: rename option '--dest-type' to just '--type'

[Karel Zak]

On Tue, Apr 01, 2025 at 11:25:40AM +0200, Benno Schulenberg wrote:
> 
> Op 01-04-2025 om 10:35 schreef Karel Zak:
> > On Mon, Mar 31, 2025 at 07:09:02AM -0400, Phil Auld wrote:
> > > but this could break users. There
> > > may not be that many yet anyway, of course.
> > 
> > It's already released, so it is truly a backward-incompatible change.
> 
> Users of a brand-new tool really should expect some iterations in the
> next versions to improve the feel of it.  So I don't see a problem in
> correcting a poor choice for a long-option name.

We've already discussed this, and --dest-type was chosen because
there's --source <pid> and --dest <pid>. We wanted to ensure users
understand the type relates to --dest. It's just an option name, so
let's not get into bike-shedding, please ;-)

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 05/10] irqtop: improve several more option descriptions, and align them all

[Karel Zak]

On Tue, Apr 01, 2025 at 11:17:47AM +0200, Benno Schulenberg wrote:
> 
> Op 31-03-2025 om 18:12 schreef Joe Jin:
> > > > Why remove the "Q"?
> > > 
> > > It looks ugly.  And why would the user want to hold Shift before pressing q,
> > > when just pressing q will do?  Holding Shift has no extra effect.
> > 
> > Then should it be removed from parse_input() as well?
> 
> No, there it should stay, to accommodate users that for some reason
> have CapsLock engaged.
> 
> I would propose the opposite change: to accept also the uppercase I,
> T, D, and N for sorting the table on the corresponding column.

I prefer your current version of the patch (keep Q usable for backward
compatibility, but don't announce it in the docs/help). I don't think
we need to extend support for uppercase letters. The letters are rare, so
save them for the future :-)

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 01/10] enosys: add the missing arguments of -s and -i to the usage text

[Karel Zak]

PR for all patches, except the last one (--dest-type rename), on
GitHub: https://github.com/util-linux/util-linux/pull/3500. 

It will be merged if it passes the relevant tests.

Thanks!

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text

[Karel Zak]

On Mon, Mar 31, 2025 at 11:44:42AM +0200, Benno Schulenberg wrote:
> Also, use semicolons instead of periods in option descriptions.
> 
> And consistently use an uppercased "PID" in feedback messages.
> 
> CC: Phil Auld <pauld@redhat.com>
> CC: Thijs Raymakers <thijs@raymakers.nl>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> ---
>  schedutils/coresched.c | 33 +++++++++++++--------------------
>  1 file changed, 13 insertions(+), 20 deletions(-)
> 
> diff --git a/schedutils/coresched.c b/schedutils/coresched.c
> index 9d8be3e12..7634d988c 100644
> --- a/schedutils/coresched.c
> +++ b/schedutils/coresched.c
> @@ -80,31 +80,24 @@ static void __attribute__((__noreturn__)) usage(void)
>  		program_invocation_short_name);
>  
>  	fputs(USAGE_SEPARATOR, stdout);
> -	fputsln(_("Manage core scheduling cookies for tasks."), stdout);
> +	fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
>  
>  	fputs(USAGE_FUNCTIONS, stdout);
> -	fputsln(_(" get                      retrieve the core scheduling cookie of a PID"),
> -		stdout);
> -	fputsln(_(" new                      assign a new core scheduling cookie to an existing\n"
> -		  "                            PID or execute a program with a new cookie"),
> -		stdout);
> -	fputsln(_(" copy                     copy the core scheduling cookie from an existing PID\n"
> -		  "                            to another PID, or execute a program with that\n"
> -		  "                            copied cookie"),
> -		stdout);
> +	fputsln(_(" get      retrieve the core-scheduling cookie of a PID"), stdout);

There is a comment from Thijs that kernel docs does not use hyphen, it
means "core scheduling" rather than "core-scheduling". Maybe it would
be better to follow kernel.
https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/core-scheduling.html

https://github.com/util-linux/util-linux/pull/3500

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text

[Benno Schulenberg]

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


Op 03-04-2025 om 10:11 schreef Karel Zak:
> On Mon, Mar 31, 2025 at 11:44:42AM +0200, Benno Schulenberg wrote:
>> -	fputsln(_("Manage core scheduling cookies for tasks."), stdout);
>> +	fputsln(_("Manage core-scheduling cookies for tasks."), stdout);

>> -	fputsln(_(" get                      retrieve the core scheduling cookie of a PID"),
>> +	fputsln(_(" get      retrieve the core-scheduling cookie of a PID"), stdout);


> There is a comment from Thijs that kernel docs does not use hyphen, it
> means "core scheduling" rather than "core-scheduling". Maybe it would
> be better to follow kernel.

When speaking of the scheduling itself, it is indeed "core scheduling",
but when using this compound word as an adjective, then it is much
clearer to hyphenate it, to avoid the impression that it is talking
about a _core_, deep, central scheduling cookie.

> https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/core-scheduling.html

In that first paragraph, I would write "Core-scheduling support...".

https://www.grammarly.com/blog/punctuation-capitalization/hyphen-with-compound-modifiers/


Benno


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

Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text

[Karel Zak]

On Thu, Apr 03, 2025 at 11:55:12AM +0200, Benno Schulenberg wrote:
> 
> Op 03-04-2025 om 10:11 schreef Karel Zak:
> > On Mon, Mar 31, 2025 at 11:44:42AM +0200, Benno Schulenberg wrote:
> > > -	fputsln(_("Manage core scheduling cookies for tasks."), stdout);
> > > +	fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
> 
> > > -	fputsln(_(" get                      retrieve the core scheduling cookie of a PID"),
> > > +	fputsln(_(" get      retrieve the core-scheduling cookie of a PID"), stdout);
> 
> 
> > There is a comment from Thijs that kernel docs does not use hyphen, it
> > means "core scheduling" rather than "core-scheduling". Maybe it would
> > be better to follow kernel.
> 
> When speaking of the scheduling itself, it is indeed "core scheduling",
> but when using this compound word as an adjective, then it is much
> clearer to hyphenate it, to avoid the impression that it is talking
> about a _core_, deep, central scheduling cookie.

OK, merged :-)

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com