[PATCH 1/7] unshare: make the wording of a message identical to that of three others

[PATCH 1/7] unshare: make the wording of a message identical to that of three others

[Benno Schulenberg]

That is: spare translators having to translate different strings that
mean the exact same thing.

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

diff --git a/sys-utils/unshare.c b/sys-utils/unshare.c
index 05db627be..fe140a0c7 100644
--- a/sys-utils/unshare.c
+++ b/sys-utils/unshare.c
@@ -1241,7 +1241,7 @@ int main(int argc, char *argv[])
 		newdir = newdir ?: "/";
 	}
 	if (newdir && chdir(newdir))
-		err(EXIT_FAILURE, _("cannot chdir to '%s'"), newdir);
+		err(EXIT_FAILURE, _("cannot change directory to %s"), newdir);
 
 	if (procmnt) {
 		/* When not changing root and using the default propagation flags
-- 
2.48.1

[PATCH 2/7] irqtop: make the wording of an error message identical to that of another

[Benno Schulenberg]

(Besides: the original looked like a statement, not like an error message.)

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

diff --git a/sys-utils/irqtop.c b/sys-utils/irqtop.c
index 3dbd030e0..a42ece070 100644
--- a/sys-utils/irqtop.c
+++ b/sys-utils/irqtop.c
@@ -465,7 +465,7 @@ int main(int argc, char **argv)
 	if (!ctl.batch) {
 		is_tty = isatty(STDIN_FILENO);
 		if (is_tty && tcgetattr(STDIN_FILENO, &saved_tty) == -1)
-			fputs(_("terminal setting retrieval"), stdout);
+			fputs(_("failed to get terminal attributes"), stdout);
 
 		ctl.win = initscr();
 		get_terminal_dimension(&ctl.cols, &ctl.rows);
-- 
2.48.1

[PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word

[Benno Schulenberg]

Also, use dots instead of "(s)" to indicate possible multiple arguments,
and don't use "<when>" when the possible arguments differ from "always",
"never", "auto".

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 lsfd-cmd/lsfd.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lsfd-cmd/lsfd.c b/lsfd-cmd/lsfd.c
index 2eb53935c..3610de8dd 100644
--- a/lsfd-cmd/lsfd.c
+++ b/lsfd-cmd/lsfd.c
@@ -2190,14 +2190,14 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -o, --output <list>          output columns (see --list-columns)\n"), out);
 	fputs(_(" -r, --raw                    use raw output format\n"), out);
 	fputs(_(" -u, --notruncate             don't truncate text in columns\n"), out);
-	fputs(_(" -p, --pid  <pid(s)>          collect information only specified processes\n"), out);
+	fputs(_(" -p, --pid <pid>...           collect information only for specified processes\n"), out);
 	fputs(_(" -i[4|6], --inet[=4|=6]       list only IPv4 and/or IPv6 sockets\n"), out);
 	fputs(_(" -Q, --filter <expr>          apply display filter\n"), out);
 	fputs(_("     --debug-filter           dump the internal data structure of filter and exit\n"), out);
 	fputs(_(" -C, --counter <name>:<expr>  define custom counter for --summary output\n"), out);
 	fputs(_("     --dump-counters          dump counter definitions\n"), out);
-	fputs(_("     --hyperlink[=mode]       print paths as terminal hyperlinks (always, never, or auto)\n"), out);
-	fputs(_("     --summary[=<when>]       print summary information (only, append, or never)\n"), out);
+	fputs(_("     --hyperlink[=<when>]     print paths as terminal hyperlinks (always|never|auto)\n"), out);
+	fputs(_("     --summary[=<mode>]       print summary information (append|only|never)\n"), out);
 	fputs(_("     --_drop-privilege        (testing purpose) do setuid(1) just after starting\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
-- 
2.48.1

Re: [PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word

[Masatake YAMATO]

> Also, use dots instead of "(s)" to indicate possible multiple arguments,
> and don't use "<when>" when the possible arguments differ from "always",
> "never", "auto".
> 
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> ---
>  lsfd-cmd/lsfd.c | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/lsfd-cmd/lsfd.c b/lsfd-cmd/lsfd.c
> index 2eb53935c..3610de8dd 100644
> --- a/lsfd-cmd/lsfd.c
> +++ b/lsfd-cmd/lsfd.c
> @@ -2190,14 +2190,14 @@ static void __attribute__((__noreturn__)) usage(void)
>  	fputs(_(" -o, --output <list>          output columns (see --list-columns)\n"), out);
>  	fputs(_(" -r, --raw                    use raw output format\n"), out);
>  	fputs(_(" -u, --notruncate             don't truncate text in columns\n"), out);
> -	fputs(_(" -p, --pid  <pid(s)>          collect information only specified processes\n"), out);
> +	fputs(_(" -p, --pid <pid>...           collect information only for specified processes\n"), out);

This change implies that --pid 1 2 3 works.
However, specifying multiple pids to one --pid doesn't work.

   # lsfd --pid 1 $$
   Try 'lsfd --help' for more information.

Only --pid "1 2 3"  or works. See double-quote chars.

   # lsfd --pid "1 $$"

Maybe a correct fix is rename --pid to --pids.

Masatake YAMATO

>  	fputs(_(" -i[4|6], --inet[=4|=6]       list only IPv4 and/or IPv6 sockets\n"), out);
>  	fputs(_(" -Q, --filter <expr>          apply display filter\n"), out);
>  	fputs(_("     --debug-filter           dump the internal data structure of filter and exit\n"), out);
>  	fputs(_(" -C, --counter <name>:<expr>  define custom counter for --summary output\n"), out);
>  	fputs(_("     --dump-counters          dump counter definitions\n"), out);
> -	fputs(_("     --hyperlink[=mode]       print paths as terminal hyperlinks (always, never, or auto)\n"), out);
> -	fputs(_("     --summary[=<when>]       print summary information (only, append, or never)\n"), out);
> +	fputs(_("     --hyperlink[=<when>]     print paths as terminal hyperlinks (always|never|auto)\n"), out);
> +	fputs(_("     --summary[=<mode>]       print summary information (append|only|never)\n"), out);
>  	fputs(_("     --_drop-privilege        (testing purpose) do setuid(1) just after starting\n"), out);
>  
>  	fputs(USAGE_SEPARATOR, out);
> -- 
> 2.48.1
> 
> 

Re: [PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word

[Karel Zak]

On Thu, Apr 24, 2025 at 06:55:05PM +0900, Masatake YAMATO wrote:
> > Also, use dots instead of "(s)" to indicate possible multiple arguments,
> > and don't use "<when>" when the possible arguments differ from "always",
> > "never", "auto".
> > 
> > Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> > ---
> >  lsfd-cmd/lsfd.c | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> > 
> > diff --git a/lsfd-cmd/lsfd.c b/lsfd-cmd/lsfd.c
> > index 2eb53935c..3610de8dd 100644
> > --- a/lsfd-cmd/lsfd.c
> > +++ b/lsfd-cmd/lsfd.c
> > @@ -2190,14 +2190,14 @@ static void __attribute__((__noreturn__)) usage(void)
> >  	fputs(_(" -o, --output <list>          output columns (see --list-columns)\n"), out);
> >  	fputs(_(" -r, --raw                    use raw output format\n"), out);
> >  	fputs(_(" -u, --notruncate             don't truncate text in columns\n"), out);
> > -	fputs(_(" -p, --pid  <pid(s)>          collect information only specified processes\n"), out);
> > +	fputs(_(" -p, --pid <pid>...           collect information only for specified processes\n"), out);
> 
> This change implies that --pid 1 2 3 works.
> However, specifying multiple pids to one --pid doesn't work.
> 
>    # lsfd --pid 1 $$
>    Try 'lsfd --help' for more information.
> 
> Only --pid "1 2 3"  or works. See double-quote chars.
> 
>    # lsfd --pid "1 $$"

It also supports comma, it means --pid 1,2,3

It would be better to not announce that space is possible to use as
separator, and use comma in the help and man page

  fputs(_(" -p, --pid <list>           restrict to specified processes (command separated pids)\nn"), out);

or so ...

    Karel

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

Re: [PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word

[Benno Schulenberg]

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


Op 24-04-2025 om 12:05 schreef Karel Zak:
> It would be better to not announce that space is possible to use as
> separator, and use comma in the help and man page

Agreed.  Revised patch has been sent.

>    fputs(_(" -p, --pid <list>           restrict to specified processes (command separated pids)\nn"), out);

This is too long (more than 80 characters wide) and gives unneeded details
-- from other options people will already know what <list> means.


Benno


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

Re: [PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word

[Masatake YAMATO]

From: Karel Zak <kzak@redhat.com>
Subject: Re: [PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word
Date: Thu, 24 Apr 2025 12:05:07 +0200
> On Thu, Apr 24, 2025 at 06:55:05PM +0900, Masatake YAMATO wrote:
>> > Also, use dots instead of "(s)" to indicate possible multiple arguments,
>> > and don't use "<when>" when the possible arguments differ from "always",
>> > "never", "auto".
>> > 
>> > Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
>> > ---
>> >  lsfd-cmd/lsfd.c | 6 +++---
>> >  1 file changed, 3 insertions(+), 3 deletions(-)
>> > 
>> > diff --git a/lsfd-cmd/lsfd.c b/lsfd-cmd/lsfd.c
>> > index 2eb53935c..3610de8dd 100644
>> > --- a/lsfd-cmd/lsfd.c
>> > +++ b/lsfd-cmd/lsfd.c
>> > @@ -2190,14 +2190,14 @@ static void __attribute__((__noreturn__)) usage(void)
>> >  	fputs(_(" -o, --output <list>          output columns (see --list-columns)\n"), out);
>> >  	fputs(_(" -r, --raw                    use raw output format\n"), out);
>> >  	fputs(_(" -u, --notruncate             don't truncate text in columns\n"), out);
>> > -	fputs(_(" -p, --pid  <pid(s)>          collect information only specified processes\n"), out);
>> > +	fputs(_(" -p, --pid <pid>...           collect information only for specified processes\n"), out);
>> 
>> This change implies that --pid 1 2 3 works.
>> However, specifying multiple pids to one --pid doesn't work.
>> 
>>    # lsfd --pid 1 $$
>>    Try 'lsfd --help' for more information.
>> 
>> Only --pid "1 2 3"  or works. See double-quote chars.
>> 
>>    # lsfd --pid "1 $$"
> 
> It also supports comma, it means --pid 1,2,3
> 
> It would be better to not announce that space is possible to use as
> separator, and use comma in the help and man page
> 
>   fputs(_(" -p, --pid <list>           restrict to specified processes (command separated pids)\nn"), out);
> 
> or so ...

I added code supporting whitespace as a separator for combining lsfd with
pidof, as I wrote as an example in lsfd(1):

       # lsfd --pid "$(pidof firefox)"

The idea combining with pidof comes from strace.

The -p option of strace supported whitespace as a separator.
So we can run strace with pidof like:

       # strace -p "$(pidof firefox)"

I didn't know this smart feature.
So I added -S option, an option for specifying separator to pidof ago.

    $ pidof -S ' -p ' zsh
    4185021 -p 4161716 -p 4156470 -p 4155385
    $ strace -p $(pidof -S ' -p ' zsh)

https://gitlab.com/procps-ng/procps/-/commit/73492b182dc60c1605d1b0d62de651fad97807af
https://lists.strace.io/pipermail/strace-devel/2018-March/007950.html
https://lists.strace.io/pipermail/strace-devel/2018-March/007951.html
https://lists.strace.io/pipermail/strace-devel/2018-March/007952.html

That was a small thing but impressive study for me.

Simplifying the output of --help is nice
However, from the man page, I want to keep the description of -p
supporting whitespace as a separator.

Masatake YAMATO

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

Re: [PATCH 3/7] lsfd: improve grammar, and use angular brackets around placeholder word

[Benno Schulenberg]

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


Op 29-04-2025 om 21:54 schreef Masatake YAMATO:
> Simplifying the output of --help is nice
> However, from the man page, I want to keep the description of -p
> supporting whitespace as a separator.

Okay.  I will add that back when the current PR has been merged.


Benno


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

[PATCH 4/7] docs,usage: harmonize description of --hyperlink, and add 2 missing ones

[Benno Schulenberg]

Also, consistently use _when_/<when> as the optional argument,
since the possible values are: "always", "never", "auto".

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 lsfd-cmd/lsfd.1.adoc      | 6 ++++--
 lsfd-cmd/lsfd.c           | 2 +-
 misc-utils/findmnt.8.adoc | 9 ++++-----
 misc-utils/findmnt.c      | 2 ++
 misc-utils/lsblk.8.adoc   | 6 ++++--
 misc-utils/lsblk.c        | 2 ++
 6 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/lsfd-cmd/lsfd.1.adoc b/lsfd-cmd/lsfd.1.adoc
index b0ba2ba53..db228a09e 100644
--- a/lsfd-cmd/lsfd.1.adoc
+++ b/lsfd-cmd/lsfd.1.adoc
@@ -110,8 +110,10 @@ only for *lsfd* developers.
 *--dump-counters*::
 Dump the definition of counters used in *--summary* output.
 
-*--hyperlink*[=_mode_]::
-Print 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.
+*--hyperlink*[**=**_when_]::
+Print paths as terminal hyperlinks. The optional _when_ 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.
 
 *-H*, *--list-columns*::
 List the columns that can be specified with the *--output* option.
diff --git a/lsfd-cmd/lsfd.c b/lsfd-cmd/lsfd.c
index 3610de8dd..847a0ac8a 100644
--- a/lsfd-cmd/lsfd.c
+++ b/lsfd-cmd/lsfd.c
@@ -2196,7 +2196,7 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_("     --debug-filter           dump the internal data structure of filter and exit\n"), out);
 	fputs(_(" -C, --counter <name>:<expr>  define custom counter for --summary output\n"), out);
 	fputs(_("     --dump-counters          dump counter definitions\n"), out);
-	fputs(_("     --hyperlink[=<when>]     print paths as terminal hyperlinks (always|never|auto)\n"), out);
+	fputs(_("     --hyperlink[=<when>]     print paths as hyperlinks (always|never|auto)\n"), out);
 	fputs(_("     --summary[=<mode>]       print summary information (append|only|never)\n"), out);
 	fputs(_("     --_drop-privilege        (testing purpose) do setuid(1) just after starting\n"), out);
 
diff --git a/misc-utils/findmnt.8.adoc b/misc-utils/findmnt.8.adoc
index a26fb8ca2..025a311e9 100644
--- a/misc-utils/findmnt.8.adoc
+++ b/misc-utils/findmnt.8.adoc
@@ -67,11 +67,10 @@ Print the first matching filesystem only.
 List the columns that can be specified with the *--output* option.
 Can be used with *--json* or *--raw* to get the list in a 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.
+*--hyperlink*[**=**_when_]::
+Print mountpoint paths as terminal hyperlinks. The optional _when_ 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.
diff --git a/misc-utils/findmnt.c b/misc-utils/findmnt.c
index 86258dfd3..862f00c63 100644
--- a/misc-utils/findmnt.c
+++ b/misc-utils/findmnt.c
@@ -1567,6 +1567,8 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -D, --df               imitate the output of df(1)\n"), out);
 	fputs(_(" -e, --evaluate         convert tags (LABEL,UUID,PARTUUID,PARTLABEL) \n"
 	        "                          to device names\n"), out);
+	fputs(_("     --hyperlink[=<when>]\n"
+		"                        print paths as hyperlinks (always|never|auto)\n"), out);
 	fputs(_(" -I, --dfi              imitate the output of df(1) with -i option\n"), out);
 	fputs(_(" -J, --json             use JSON output format\n"), out);
 	fputs(_(" -l, --list             use list format output\n"), out);
diff --git a/misc-utils/lsblk.8.adoc b/misc-utils/lsblk.8.adoc
index 8151525af..0e9734247 100644
--- a/misc-utils/lsblk.8.adoc
+++ b/misc-utils/lsblk.8.adoc
@@ -62,8 +62,10 @@ 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_]::
-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.
+*--hyperlink*[**=**_when_]::
+Print mountpoint paths as terminal hyperlinks. The optional _when_ 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*, *--include* _list_::
 Include devices specified by the comma-separated _list_ of major device numbers. The filter is applied to the top-level devices only. This may be confusing for *--list* output format where hierarchy of the devices is not obvious.
diff --git a/misc-utils/lsblk.c b/misc-utils/lsblk.c
index 9f252d079..128217d62 100644
--- a/misc-utils/lsblk.c
+++ b/misc-utils/lsblk.c
@@ -2329,6 +2329,8 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -d, --nodeps         don't print slaves or holders\n"), out);
 	fputs(_(" -e, --exclude <list> exclude devices by major number (default: RAM disks)\n"), out);
 	fputs(_(" -f, --fs             output info about filesystems\n"), out);
+	fputs(_("     --hyperlink[=<when>]\n"
+		"                      print paths as hyperlinks (always|never|auto)\n"), out);
 	fputs(_(" -i, --ascii          use ascii characters only\n"), out);
 	fputs(_(" -l, --list           use list format output\n"), out);
 	fputs(_(" -m, --perms          output info about permissions\n"), out);
-- 
2.48.1

Re: [PATCH 4/7] docs,usage: harmonize description of --hyperlink, and add 2 missing ones

[Karel Zak]

On Thu, Apr 24, 2025 at 11:32:34AM +0200, Benno Schulenberg wrote:
> -*--hyperlink*[=_mode_]::
> -Print 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.
> +*--hyperlink*[**=**_when_]::
> +Print paths as terminal hyperlinks. The optional _when_ 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.

How about adding man-common/hyperlink and including it in the man pages?

    Karel

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

Re: [PATCH 4/7] docs,usage: harmonize description of --hyperlink, and add 2 missing ones

[Benno Schulenberg]

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


Op 24-04-2025 om 12:08 schreef Karel Zak:
> How about adding man-common/hyperlink and including it in the man pages?

Done.  Although there was a slight wording difference between `lsfd` on
the one hand, and `findmnt` and `lsblk` on the other hand: the first said
just "paths" instead of "mountpoint paths".  Probably the word "mountpoint"
can be dropped to make the description fit for all three?


Benno


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

Re: [PATCH 4/7] docs,usage: harmonize description of --hyperlink, and add 2 missing ones

[Karel Zak]

On Fri, Apr 25, 2025 at 12:43:56PM +0200, Benno Schulenberg wrote:
> 
> Op 24-04-2025 om 12:08 schreef Karel Zak:
> > How about adding man-common/hyperlink and including it in the man pages?
> 
> Done.  Although there was a slight wording difference between `lsfd` on
> the one hand, and `findmnt` and `lsblk` on the other hand: the first said
> just "paths" instead of "mountpoint paths".  Probably the word "mountpoint"
> can be dropped to make the description fit for all three?

I think using "paths" for everything is sufficient.

    Karel


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

[PATCH 5/7] pipesz: (man) improve the markup and some wordings

[Benno Schulenberg]

CC: Nathan Sharp <nwsharp@live.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/pipesz.1.adoc | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/misc-utils/pipesz.1.adoc b/misc-utils/pipesz.1.adoc
index b51de5887..6bc9e46c3 100644
--- a/misc-utils/pipesz.1.adoc
+++ b/misc-utils/pipesz.1.adoc
@@ -12,15 +12,15 @@ pipesz - set or examine pipe and FIFO buffer sizes
 
 == SYNOPSIS
 
-*pipesz* [options] [--set _size_] [--] [_command_ [argument] ...]
+*pipesz* [options] [*--set* _size_] [--] [_command_ [_argument_...]]
 
-*pipesz* [options] --get
+*pipesz* [options] *--get*
 
 == DESCRIPTION
 
 Pipes and FIFOs maintain an internal buffer used to transfer data between the read end and the write end. In some cases, the default size of this internal buffer may not be appropriate. This program provides facilities to set and examine the size of these buffers.
 
-The *--set* operation sets pipe buffer sizes. If it is specified, it must be specified with an explicit _size_. Otherwise, it is implied and the size is read from */proc/sys/fs/pipe-max-size*. The kernel may adjust _size_ as described in *fcntl*(2). To determine the actual buffer sizes set, use the *--verbose* option. If neither *--file* nor *--fd* are specified, *--set* acts on standard output.
+The *--set* operation sets pipe buffer sizes. If it is specified, it must be specified with an explicit _size_. Otherwise, it is implied and the size is read from */proc/sys/fs/pipe-max-size*. The kernel may adjust _size_ as described in *fcntl*(2). To see the actual buffer sizes that get set, use the *--verbose* option. If neither *--file* nor *--fd* are specified, *--set* acts on standard output.
 
 The *--set* operation permits an optional _command_ to execute after setting the pipe buffer sizes. This command is executed with the adjusted pipes.
 
@@ -38,13 +38,13 @@ The kernel imposes limits on the amount of pipe buffer space unprivileged proces
 Report the size of pipe buffers to standard output and exit. As a special behavior, if neither *--file* nor *--fd* are specified, standard input is examined. It is an error to specify this option in combination with *--set*.
 
 *-s*, *--set* _size_::
-Set the size of the pipe buffers, in bytes. This option may be suffixed by _K_, _M_, _G_, _KiB_, _MiB_, or _GiB_ to indicate multiples of 1024. Fractional values are supported in this case. Additional suffixes are supported but are unlikely to be useful. If this option is not specified, a default value is used, as described above. If this option is specified multiple times, a warning is emitted and only the last-specified _size_ is used. As a special behavior, if neither *--file* nor *--fd* are specified, standard output is adjusted. It is an error to specify this option in combination with *--get*.
+Set the size of the pipe buffers, in bytes. This option may be suffixed by *K*, *M*, *G*, *KiB*, *MiB*, or *GiB* to indicate multiples of 1024. Fractional values are supported in this case. Additional suffixes are supported but are unlikely to be useful. If this option is not specified, a default value is used, as described above. If this option is specified multiple times, a warning is emitted and only the last-specified _size_ is used. As a special behavior, if neither *--file* nor *--fd* are specified, standard output is adjusted. It is an error to specify this option in combination with *--get*.
 
 *-f*, *--file* _path_::
 Set the buffer size of the FIFO or pipe at _path_, relative to the current working directory. You may specify this option multiple times to affect different files, and you may do so in combination with *--fd*. Generally, this option is used with FIFOs, but it will also operate on anonymous pipes such as those found in */proc/PID/fd*. Changes to the buffer size of FIFOs are not preserved across system restarts.
 
-*-n*, *--fd* _fd_::
-Set the buffer size of the pipe or FIFO passed to *pipesz* as the specified file descriptor number. You may specify this option multiple times to affect different file descriptors, and you may do so in combination with *--file*. Shorthand options are provided for the common cases of fd 0 (stdin), fd 1 (stdout), and fd 2 (stderr). These should suffice in most cases.
+*-n*, *--fd* _number_::
+Set the buffer size of the pipe or FIFO corresponding to file descriptor _number_. You may specify this option multiple times to affect different file descriptors, and you may do so in combination with *--file*. Shorthand options are provided for the common cases of fd 0 (stdin), fd 1 (stdout), and fd 2 (stderr). These should suffice in most cases.
 
 *-i*, *--stdin*::
 Shorthand for *--fd 0*.
@@ -59,7 +59,7 @@ Shorthand for *--fd 2*.
 Exit, without executing _command_, in case of any error while manipulating a file or file descriptor. The default behavior if this is not specified is to emit a warning to standard error and continue.
 
 *-q*, *--quiet*::
-Do not diagnose non-fatal errors to standard error. This option does not affect the normal output of *--get*, *--verbose*, *--help*, or *--version*.
+Do not report non-fatal errors to standard error. This option does not affect the normal output of *--get*, *--verbose*, *--help*, or *--version*.
 
 *-v*, *--verbose*::
 If specified with *--get*, *pipesz* will emit a descriptive header above the table. Otherwise, if specified, *pipesz* will print the actual buffer sizes set by the kernel to standard error.
-- 
2.48.1

[PATCH 6/7] pipesz: report default size in --help, instead of referring the user

[Benno Schulenberg]

The man page says where this default size can be found.  In the --help
text it is more useful to directly say what this default size is.

CC: Nathan Sharp <nwsharp@live.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/pipesz.c | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/misc-utils/pipesz.c b/misc-utils/pipesz.c
index 48f07aed7..c317959e4 100644
--- a/misc-utils/pipesz.c
+++ b/misc-utils/pipesz.c
@@ -71,11 +71,8 @@ static void __attribute__((__noreturn__)) usage(void)
 
 	fputs(USAGE_OPTIONS, stdout);
 	fputsln(_(" -g, --get          examine pipe buffers"), stdout);
-	/* TRANSLATORS: '%s' refers to a system file */
 	fprintf(stdout,
-	     _(" -s, --set <size>   set pipe buffer sizes\n"
-	       "                      size defaults to %s\n"),
-		PIPESZ_DEFAULT_SIZE_FILE);
+		_(" -s, --set <size>   the buffer size to be used (default: %u)\n"), opt_size);
 
 	fputs(USAGE_SEPARATOR, stdout);
 	fputsln(_(" -f, --file <path>  act on a file"), stdout);
@@ -232,6 +229,8 @@ int main(int argc, char **argv)
 	while ((c = getopt_long(argc, argv, shortopts, longopts, NULL)) != -1) {
 		switch (c) {
 		case 'h':
+			if (ul_path_read_s32(NULL, &opt_size, PIPESZ_DEFAULT_SIZE_FILE))
+				warn(_("cannot parse %s"), PIPESZ_DEFAULT_SIZE_FILE);
 			usage();
 		case 'V':
 			print_version(EXIT_SUCCESS);
-- 
2.48.1

Re: [PATCH 6/7] pipesz: report default size in --help, instead of referring the user

[Nathan Sharp]

Hello Benno Schulenberg,

    I do not think that this change is a good idea, especially in this location. If it is to be done at all, it MUST be done inside the usage() function; so that it is unlikely that future changes will introduce a read of an uninitialized global variable.
 
    However, I do not think this is a good idea in isolation, as it deprives the user of the knowledge of where the default size comes from, and additionally could cause the help message to print a warning! A path forwards that I would support is to keep the existing text but include the value read from the file as a parenthetical, if and only if the parse was successful.

    Kind regards,
        Nathan Sharp
        Principal Consultant
        Scherpzinnige Oplossingen, B.V.

________________________________________
From: Benno Schulenberg <bensberg@telfort.nl>
Sent: Thursday, April 24, 2025 11:32 AM
To: util-linux@vger.kernel.org <util-linux@vger.kernel.org>
Cc: Nathan Sharp <nwsharp@live.com>
Subject: [PATCH 6/7] pipesz: report default size in --help, instead of referring the user
 
The man page says where this default size can be found.  In the --help
text it is more useful to directly say what this default size is.

CC: Nathan Sharp <nwsharp@live.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/pipesz.c | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/misc-utils/pipesz.c b/misc-utils/pipesz.c
index 48f07aed7..c317959e4 100644
--- a/misc-utils/pipesz.c
+++ b/misc-utils/pipesz.c
@@ -71,11 +71,8 @@ static void __attribute__((__noreturn__)) usage(void)
 
         fputs(USAGE_OPTIONS, stdout);
         fputsln(_(" -g, --get          examine pipe buffers"), stdout);
-       /* TRANSLATORS: '%s' refers to a system file */
         fprintf(stdout,
-            _(" -s, --set <size>   set pipe buffer sizes\n"
-              "                      size defaults to %s\n"),
-               PIPESZ_DEFAULT_SIZE_FILE);
+               _(" -s, --set <size>   the buffer size to be used (default: %u)\n"), opt_size);
 
         fputs(USAGE_SEPARATOR, stdout);
         fputsln(_(" -f, --file <path>  act on a file"), stdout);
@@ -232,6 +229,8 @@ int main(int argc, char **argv)
         while ((c = getopt_long(argc, argv, shortopts, longopts, NULL)) != -1) {
                 switch (c) {
                 case 'h':
+                       if (ul_path_read_s32(NULL, &opt_size, PIPESZ_DEFAULT_SIZE_FILE))
+                               warn(_("cannot parse %s"), PIPESZ_DEFAULT_SIZE_FILE);
                         usage();
                 case 'V':
                         print_version(EXIT_SUCCESS);
--
2.48.1

Re: [PATCH 6/7] pipesz: report default size in --help, instead of referring the user

[Benno Schulenberg]

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


Op 24-04-2025 om 13:24 schreef Nathan Sharp:
>      If it is to be done at all, it MUST be done inside the usage() function; 
> so that it is unlikely that future changes will introduce a read of an 
> uninitialized global variable.

Which variable would be uninitialized?  Global variable 'opt_size' gets
initialized to -1 in the beginning.  But okay, moving the two lines
before the call of usage() to the start of usage() itself is fine.

>      However, I do not think this is a good idea in isolation, as it deprives 
> the user of the knowledge of where the default size comes from,

Not at all: where the value comes from is mentioned in the man page.
The usage text is not meant to include _all_ details about the program
-- that is what the man page is for.  And, unlike the man page, the
usage text _can_ include the actual value of the thing.  And if it can,
it should, in my opinion, as the value itself is much more useful than
saying "go look there".

> and additionally could cause the help message to print a warning!

That is actually better than referring to a file that happens to be
unreadable/unparsable, because then the help text would be lying.


Benno


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

[PATCH 7/7] uuidd: put an option and its description in a single message

[Benno Schulenberg]

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

CC: Michael Trapp <michael.trapp@sap.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/uuidd.8.adoc | 16 ++++++++++++----
 misc-utils/uuidd.c      |  4 ++--
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/misc-utils/uuidd.8.adoc b/misc-utils/uuidd.8.adoc
index f8001f986..f15d7b631 100644
--- a/misc-utils/uuidd.8.adoc
+++ b/misc-utils/uuidd.8.adoc
@@ -24,12 +24,20 @@ The *uuidd* daemon is used by the UUID library to generate universally unique id
 
 == OPTIONS
 
-*-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.
+*-C*, *--cont-clock*[**=**_number_[*hd*]]::
+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 'max_clock_offset'.
+This guarantees that a clock value of a UUID will always be within the
+range of 'max_clock_offset'.
 +
-The option *-C* or *--cont-clock* enables the feature with a default max_clock_offset of 2 hours.
+The option *-C* or *--cont-clock* (without an argument) enables the
+feature with a default 'max_clock_offset' of 2 hours.
 +
-The option *-C<NUM>[hd]* or *--cont-clock=<NUM>[hd]* enables the feature with a max_clock_offset of NUM seconds. In case of an appended h or d, the NUM value is read in hours or days. The minimum value is 60 seconds, the maximum value is 365 days.
+The option **-C**_number_ or **--cont-clock=**_number_ enables the
+feature with a 'max_clock_offset' of _number_ seconds.
+In case of an appended *h* or *d*, _number_ is understood in hours or days.
+The minimum value is 60 seconds, the maximum value is 365 days.
 
 *-d*, *--debug*::
 Run *uuidd* in debugging mode. This prevents *uuidd* from running as a daemon.
diff --git a/misc-utils/uuidd.c b/misc-utils/uuidd.c
index 961c3a5fa..74e950307 100644
--- a/misc-utils/uuidd.c
+++ b/misc-utils/uuidd.c
@@ -108,8 +108,8 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -P, --no-pid            do not create pid file\n"), out);
 	fputs(_(" -F, --no-fork           do not daemonize using double-fork\n"), out);
 	fputs(_(" -S, --socket-activation do not create listening socket\n"), out);
-	fputs(_(" -C, --cont-clock[=<NUM>[hd]]\n"), out);
-	fputs(_("                         activate continuous clock handling\n"), out);
+	fputs(_(" -C, --cont-clock[=<number>[hd]]\n"
+		"                         activate continuous clock handling\n"), out);
 	fputs(_(" -d, --debug             run in debugging mode\n"), out);
 	fputs(_(" -q, --quiet             turn on quiet mode\n"), out);
 	fputs(USAGE_SEPARATOR, out);
-- 
2.48.1

Re: [PATCH 1/7] unshare: make the wording of a message identical to that of three others

[Karel Zak]

Created a pull request at
https://github.com/util-linux/util-linux/pull/3550 to test the patches
via CI. I hope I have applied the correct versions of the patches :)

    Karel

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

Re: [PATCH 1/7] unshare: make the wording of a message identical to that of three others

[Benno Schulenberg]

[-- Attachment #1.1.1: Type: text/plain, Size: 440 bytes --]


Op 29-04-2025 om 13:11 schreef Karel Zak:
> Created a pull request at
> https://github.com/util-linux/util-linux/pull/3550 to test the patches
> via CI. I hope I have applied the correct versions of the patches :)

The last patch ("docs,usage") probably needs the attached extra diff to
pass the tests.

(I'm surprised that the build system does not automatically make rules
for all the .adoc files in man-common.)


Benno


[-- Attachment #1.1.2: po4a-hyperlink.diff --]
[-- Type: text/x-patch, Size: 785 bytes --]

diff --git a/po-man/po4a.cfg b/po-man/po4a.cfg
index 25df538a3..959ddb8bf 100644
--- a/po-man/po4a.cfg
+++ b/po-man/po4a.cfg
@@ -7,6 +7,7 @@
 [type:asciidoc] ../man-common/footer-lib.adoc    $lang:$lang/man-common/footer-lib.adoc    opt:"--keep 0"
 [type:asciidoc] ../man-common/footer.adoc        $lang:$lang/man-common/footer.adoc        opt:"--keep 0"
 [type:asciidoc] ../man-common/help-version.adoc  $lang:$lang/man-common/help-version.adoc  opt:"--keep 0"
+[type:asciidoc] ../man-common/hyperlink.adoc     $lang:$lang/man-common/hyperlink.adoc     opt:"--keep 0"
 [type:asciidoc] ../man-common/in-bytes.adoc      $lang:$lang/man-common/in-bytes.adoc      opt:"--keep 0"
 [type:asciidoc] ../man-common/translation.adoc   $lang:$lang/man-common/translation.adoc   opt:"--keep 0"
 

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

Re: [PATCH 1/7] unshare: make the wording of a message identical to that of three others

[Karel Zak]

On Tue, Apr 29, 2025 at 03:55:28PM +0200, Benno Schulenberg wrote:
> 
> Op 29-04-2025 om 13:11 schreef Karel Zak:
> > Created a pull request at
> > https://github.com/util-linux/util-linux/pull/3550 to test the patches
> > via CI. I hope I have applied the correct versions of the patches :)
> 
> The last patch ("docs,usage") probably needs the attached extra diff to
> pass the tests.
 
Yes, po4a.cfg needs to be updated too.

> (I'm surprised that the build system does not automatically make rules
> for all the .adoc files in man-common.)
 
This is config file for po/asciidocs converter.

    Karel

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

Re: [PATCH 1/7] unshare: make the wording of a message identical to that of three others

[Karel Zak]

On Wed, Apr 30, 2025 at 01:18:25PM +0200, Karel Zak wrote:
> On Tue, Apr 29, 2025 at 03:55:28PM +0200, Benno Schulenberg wrote:
> > 
> > Op 29-04-2025 om 13:11 schreef Karel Zak:
> > > Created a pull request at
> > > https://github.com/util-linux/util-linux/pull/3550 to test the patches
> > > via CI. I hope I have applied the correct versions of the patches :)
> > 
> > The last patch ("docs,usage") probably needs the attached extra diff to
> > pass the tests.
>  
> Yes, po4a.cfg needs to be updated too.

updated: https://github.com/util-linux/util-linux/pull/3550/commits/18e5242e0cb6ad8e98e89975e2553b327d169863

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