* [PATCH 02/10] last: (man) correct the descriptions of --present and --since
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 03/10] last: (man) reduce an inflated table to sane proportions Benno Schulenberg
` (9 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
Doing `last --present -24h` will show who was logged in around this time
yesterday. But when doing (what according to the man page is equivalent)
`last --since -24h --until -24h` nothing will be shown -- unless someone
logged in exactly 24 hours ago to the second.
So, correct the descriptions of --present and --since.
This fixes #1896 (https://github.com/util-linux/util-linux/issues/1896).
Reported-by: Finn Krein-Schuch
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
login-utils/last.1.adoc | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/login-utils/last.1.adoc b/login-utils/last.1.adoc
index 099b281cc..8da52c766 100644
--- a/login-utils/last.1.adoc
+++ b/login-utils/last.1.adoc
@@ -64,13 +64,14 @@ Like *--dns ,* but displays the host's IP number instead of the name.
Tell *last* how many lines to show.
*-p*, *--present* _time_::
-Display the users who were present at the specified time. This is like using the options *--since* and *--until* together with the same _time_.
+Display the users who were present at the specified time.
*-R*, *--nohostname*::
Suppresses the display of the hostname field.
*-s*, *--since* _time_::
-Display the state of logins since the specified _time_. This is useful, e.g., to easily determine who was logged in at a particular time. The option is often combined with *--until*.
+Display the state of logins since the specified _time_.
+The option is often combined with *-t*/*--until* to cover a period.
*-t*, *--until* _time_::
Display the state of logins until the specified _time_.
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 03/10] last: (man) reduce an inflated table to sane proportions
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
2025-04-17 9:48 ` [PATCH 02/10] last: (man) correct the descriptions of --present and --since Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 04/10] rtcwake: " Benno Schulenberg
` (8 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
Also, reword some things for better flow, improve some markup, and
combine username and tty to [username|tty]... in the synopsis, as
this better indicates that the two identifiers can be mixed.
Furthermore, use quotes around the time formats that contain a space,
as otherwise the time would be understood as a user name / tty name.
Drop the "tomorrow" and "+5min" examples, as they don't make sense
here. And change the "-5days" example to a true format that covers
most possibilities, and give a few examples of it after the table.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
login-utils/last.1.adoc | 77 +++++++++++++++++++++++++----------------
1 file changed, 47 insertions(+), 30 deletions(-)
diff --git a/login-utils/last.1.adoc b/login-utils/last.1.adoc
index 8da52c766..adf82ae73 100644
--- a/login-utils/last.1.adoc
+++ b/login-utils/last.1.adoc
@@ -29,15 +29,21 @@ last, lastb - show a listing of last logged in users
== SYNOPSIS
-*last* [options] [_username_...] [_tty_...]
+*last* [options] [_username_|_tty_]...
-*lastb* [options] [_username_...] [_tty_...]
+*lastb* [options] [_username_|_tty_]...
== DESCRIPTION
-*last* searches back through the _/var/log/wtmp_ file (or the file designated by the *-f* option) and displays a list of all users logged in (and out) since that file was created. One or more _usernames_ and/or _ttys_ can be given, in which case *last* will show only the entries matching those arguments. Names of _ttys_ can be abbreviated, thus *last 0* is the same as *last tty0*.
+*last* searches back through the _/var/log/wtmp_ file (or the file given with the *-f* option)
+and displays a list of all users who logged in (and out) since that file was created.
+One or more _usernames_ and/or _ttys_ can be given, in which case *last* will show only
+the entries matching those arguments. (Names of _ttys_ can be abbreviated, thus *last 0*
+is the same as *last tty0*.)
-When catching a *SIGINT* signal (generated by the interrupt key, usually control-C) or a *SIGQUIT* signal, *last* will show how far it has searched through the file; in the case of the *SIGINT* signal *last* will then terminate.
+When catching a *SIGINT* or *SIGQUIT* signal, *last* will show how far it has searched through
+the file, and in case of the *SIGINT* signal (generated by the interrupt key, usually control-C)
+*last* will then terminate.
The pseudo user *reboot* logs in each time the system is rebooted. Thus *last reboot* will show a log of all the reboots since the log file was created.
@@ -46,32 +52,37 @@ The pseudo user *reboot* logs in each time the system is rebooted. Thus *last re
== OPTIONS
*-a*, *--hostlast*::
-Display the hostname in the last column. Useful in combination with the *--dns* option.
+Display the hostname in the last column. Useful in combination with the *-d* option.
*-d*, *--dns*::
For non-local logins, Linux stores not only the host name of the remote host, but its IP number as well. This option translates the IP number back into a hostname.
*-f*, *--file* _file_::
-Tell *last* to use a specific _file_ instead of _/var/log/wtmp_. The *--file* option can be given multiple times, and all of the specified files will be processed.
+Tell *last* to use a specific _file_ instead of _/var/log/wtmp_. The *-f* option
+can be given multiple times, and all of the specified files will be processed.
*-F*, *--fulltimes*::
Print full login and logout times and dates.
*-i*, *--ip*::
-Like *--dns ,* but displays the host's IP number instead of the name.
+Like *-d*, but displays the host's IP number instead of the name.
-**-**__number__; *-n*, *--limit* _number_::
-Tell *last* how many lines to show.
+*-n*, *--limit* _number_::
+The maximum amount of logins to show.
+
+**-**_number_::
+The same as *-n* _number_.
*-p*, *--present* _time_::
-Display the users who were present at the specified time.
+Display the users who were present at the specified _time_.
+For ways to specify _time_, see the section *TIME FORMATS* below.
*-R*, *--nohostname*::
Suppresses the display of the hostname field.
*-s*, *--since* _time_::
Display the state of logins since the specified _time_.
-The option is often combined with *-t*/*--until* to cover a period.
+The option can be combined with *-t* to cover a period.
*-t*, *--until* _time_::
Display the state of logins until the specified _time_.
@@ -80,10 +91,18 @@ Display the state of logins until the specified _time_.
Use ASCII *tab* characters to separate the columns in the output instead of spaces.
*--time-format* _format_::
-Define the output timestamp _format_ to be one of _notime_, _short_, _full_, or _iso_. The _notime_ variant will not print any timestamps at all, _short_ is the default, and _full_ is the same as the *--fulltimes* option. The _iso_ variant will display the timestamp in ISO-8601 format. The ISO format contains timezone information, making it preferable when printouts are investigated outside of the system.
+Define the appearance of the timestamp to be one of: *notime*, *short*, *full*, or *iso*.
+The *notime* variant will not print any timestamps at all, *short* is the default,
+and *full* is the same as the *--fulltimes* option.
+The *iso* variant will display the timestamp in ISO-8601 format.
+The ISO format contains timezone information, making it preferable when
+printouts are investigated outside of the system.
*-w*, *--fullnames*::
-Display full user names and domain names / IP addresses in the output. Domain names and IP addresses are truncated to 16 characters, and user names are truncated to 8 characters when this flag is not specified. An asterisk is set as the last character of truncated fields.
+Display full user names and domain names / IP addresses.
+When this option is not specified, user names are truncated to 8 characters,
+and domain names and IP addresses to 16 characters.
+An asterisk is shown as the last character of truncated fields.
*-x*, *--system*::
Display the system shutdown entries and run level changes.
@@ -92,23 +111,21 @@ include::man-common/help-version.adoc[]
== TIME FORMATS
-The options that take the _time_ argument understand the following formats:
-
-[cols=",",]
-|===
-|YYYYMMDDhhmmss |
-|YYYY-MM-DD hh:mm:ss |
-|YYYY-MM-DD hh:mm |(seconds will be set to 00)
-|YYYY-MM-DD |(time will be set to 00:00:00)
-|hh:mm:ss |(date will be set to today)
-|hh:mm |(date will be set to today, seconds to 00)
-|now |
-|yesterday |(time is set to 00:00:00)
-|today |(time is set to 00:00:00)
-|tomorrow |(time is set to 00:00:00)
-|+5min |
-|-5days |
-|===
+The argument _time_ allows the following forms:
+....
+ YYYYMMDDhhmmss
+ "YYYY-MM-DD hh:mm:ss"
+ "YYYY-MM-DD hh:mm" (seconds is 00)
+ YYYY-MM-DD (time is 00:00:00)
+ hh:mm:ss (date is today)
+ hh:mm (date is today, seconds is 00)
+ now
+ today (time is 00:00:00)
+ yesterday (time is 00:00:00)
+ -number[smhd] (seconds/minutes/hours/days before now)
+....
+Examples of the **-**_number_[*smhd*] format are: *-5m*, *-6h*, *-2d*.
+The unit specifier may be longer: *-5min*, *-6hours*, *-2days*.
== FILES
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 04/10] rtcwake: (man) reduce an inflated table to sane proportions
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
2025-04-17 9:48 ` [PATCH 02/10] last: (man) correct the descriptions of --present and --since Benno Schulenberg
2025-04-17 9:48 ` [PATCH 03/10] last: (man) reduce an inflated table to sane proportions Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 05/10] terminal-colors.d: (man) reduce two tables to succinct lists Benno Schulenberg
` (7 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
Asciidoctor puts an unneeded blank line into every table cell (this
is fixed in git [1], but not released yet), and will unnecessarily
wrap text in a cell when the text is slightly longer than average.
Replace the table with a block of preformatted text, and replace
the "+5min" example with a true format that covers most cases,
and give some examples of that format after the block.
[1] https://github.com/asciidoctor/asciidoctor/commit/9cb73f8c9bee
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/rtcwake.8.adoc | 29 ++++++++++++++++-------------
1 file changed, 16 insertions(+), 13 deletions(-)
diff --git a/sys-utils/rtcwake.8.adoc b/sys-utils/rtcwake.8.adoc
index 481a586c5..b118534c8 100644
--- a/sys-utils/rtcwake.8.adoc
+++ b/sys-utils/rtcwake.8.adoc
@@ -37,19 +37,22 @@ Specify an alternative path to the adjust file.
Read the clock mode (whether the hardware clock is set to UTC or local time) from the _adjtime_ file, where *hwclock*(8) stores that information. This is the default.
*--date* _timestamp_::
-Set the wakeup time to the value of the timestamp. Format of the timestamp can be any of the following:
-
-[cols=",",]
-|===
-|YYYYMMDDhhmmss |
-|YYYY-MM-DD hh:mm:ss |
-|YYYY-MM-DD hh:mm |(seconds will be set to 00)
-|YYYY-MM-DD |(time will be set to 00:00:00)
-|hh:mm:ss |(date will be set to today)
-|hh:mm |(date will be set to today, seconds to 00)
-|tomorrow |(time is set to 00:00:00)
-|+5min |
-|===
+Set the wakeup time to the value of this timestamp.
+The format of _timestamp_ can be any of the following:
++
+....
+ YYYYMMDDhhmmss
+ "YYYY-MM-DD hh:mm:ss"
+ "YYYY-MM-DD hh:mm" (seconds is 00)
+ YYYY-MM-DD (time is 00:00:00)
+ hh:mm:ss (date is today)
+ hh:mm (date is today, seconds is 00)
+ +number[smhd] (seconds/minutes/hours/days after now)
+ tomorrow (time is 00:00:00)
+....
++
+Examples of the **+**_number_[*smhd*] format are: *+5m*, *+6h*, *+2d*.
+The unit specifier may be longer: *+5min*, *+6hours*, *+2days*.
*-d*, *--device* _device_::
Use the specified _device_ instead of *rtc0* as realtime clock. This option is only relevant if your system has more than one RTC. You may specify *rtc1*, *rtc2*, ... here.
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 05/10] terminal-colors.d: (man) reduce two tables to succinct lists
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (2 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 04/10] rtcwake: " Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 06/10] renice: in usage text, condense the oververbose description of option -n Benno Schulenberg
` (6 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
Before the move to asciidoctor, these tables were succinct lists in the
man page. Change the asciidoc text to make them into lists again.
Use {nbsp} on one line to avoid weird groff behavior for \? when .ss
is defined to be zero-width (as asciidoctor does), and reshuffle two
paragraphs to avoid an asciidoctor bug that adds a spurious \fP after
a monospace span defined with double backticks.
Also, correct some markup in a few earlier paragraphs.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
lib/terminal-colors.d.5.adoc | 103 ++++++++++++++++-------------------
1 file changed, 48 insertions(+), 55 deletions(-)
diff --git a/lib/terminal-colors.d.5.adoc b/lib/terminal-colors.d.5.adoc
index ed8c48727..4936947b1 100644
--- a/lib/terminal-colors.d.5.adoc
+++ b/lib/terminal-colors.d.5.adoc
@@ -47,14 +47,15 @@ The user-specific _$XDG_CONFIG_HOME/terminal-colors.d_ or _$HOME/.config/termina
== DEFAULT SCHEME FILES FORMAT
The following statement is recognized:
-
____
-*name color-sequence*
+_name color-sequence_
____
-The *name* is a logical name of color sequence (for example "error"). The names are specific to the utilities. For more details always see the *COLORS* section in the man page for the utility.
+The _name_ is a logical name for the color sequence (for example: *error*).
+The names are specific to the utilities. For more details always see
+the *COLORS* section in the man page for the utility.
-The *color-sequence* is a color name, ASCII color sequences or escape sequences.
+The _color-sequence_ is a color name, ASCII color sequences, or escape sequences.
=== Color names
@@ -63,67 +64,59 @@ black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightb
=== ANSI color sequences
The color sequences are composed of sequences of numbers separated by semicolons. The most common codes are:
-
____
-[cols=",",]
-|===
-|0 |to restore default color
-|1 |for brighter colors
-|4 |for underlined text
-|5 |for flashing text
-|30 |for black foreground
-|31 |for red foreground
-|32 |for green foreground
-|33 |for yellow (or brown) foreground
-|34 |for blue foreground
-|35 |for purple foreground
-|36 |for cyan foreground
-|37 |for white (or gray) foreground
-|40 |for black background
-|41 |for red background
-|42 |for green background
-|43 |for yellow (or brown) background
-|44 |for blue background
-|45 |for purple background
-|46 |for cyan background
-|47 |for white (or gray) background
-|===
+ 0 to restore default color
+ 1 for brighter colors
+ 4 for underlined text
+ 5 for flashing text
+ 30 for black foreground
+ 31 for red foreground
+ 32 for green foreground
+ 33 for yellow (or brown) foreground
+ 34 for blue foreground
+ 35 for purple foreground
+ 36 for cyan foreground
+ 37 for white (or gray) foreground
+ 40 for black background
+ 41 for red background
+ 42 for green background
+ 43 for yellow (or brown) background
+ 44 for blue background
+ 45 for purple background
+ 46 for cyan background
+ 47 for white (or gray) background
____
-=== Escape sequences
-
-To specify control or blank characters in the color sequences, C-style \-escaped notation can be used:
-
-____
-[cols=",",]
-|===
-|*\a* |Bell (ASCII 7)
-|*\b* |Backspace (ASCII 8)
-|*\e* |Escape (ASCII 27)
-|*\f* |Form feed (ASCII 12)
-|*\n* |Newline (ASCII 10)
-|*\r* |Carriage Return (ASCII 13)
-|*\t* |Tab (ASCII 9)
-|*\v* |Vertical Tab (ASCII 11)
-|*\?* |Delete (ASCII 127)
-|*\_* |Space
-|*\\* |Backslash (\)
-|*\^* |Caret (^)
-|*\#* |Hash mark (#)
-|===
-____
-
-Please note that escapes are necessary to enter a space, backslash, caret, or any control character anywhere in the string, as well as a hash mark as the first character.
-
For example, to use a red background for alert messages in the output of *dmesg*(1), use:
+`` *echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme*``
+
+=== Escape sequences
+
+An escape sequence is necessary to enter a space, backslash, caret, or any
+control character anywhere in a string, as well as a hash mark as the first
+character. These C-style backslash-escapes can be used:
+
____
-*echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme*
+`` *\a* Bell (ASCII 7)``
+`` *\b* Backspace (ASCII 8)``
+`` *\e* Escape (ASCII 27)``
+`` *\f* Form feed (ASCII 12)``
+`` *\n* Newline (ASCII 10)``
+`` *\r* Carriage Return (ASCII 13)``
+`` *\t* Tab (ASCII 9)``
+`` *\v* Vertical Tab (ASCII 11)``
+`` *\?*{nbsp}{nbsp}{nbsp}Delete (ASCII 127)``
+`` *\_* Space``
+`` *\\* Backslash (\)``
+`` *\^* Caret (^)``
+`` *\\#* Hash mark (#)``
____
=== Comments
-Lines where the first non-blank character is a # (hash) are ignored. Any other use of the hash character is not interpreted as introducing a comment.
+Lines where the first non-blank character is a *#* (hash) are ignored.
+Any other use of the hash character is not interpreted as introducing a comment.
== ENVIRONMENT
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 06/10] renice: in usage text, condense the oververbose description of option -n
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (3 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 05/10] terminal-colors.d: (man) reduce two tables to succinct lists Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 07/10] renice: (man) reword several things, to be clearer, and improve some markup Benno Schulenberg
` (5 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux; +Cc: David Anes
The --help text should be concise: it serves only as a reminder of how
things work. When a more wordy explanation is needed, there is always
the man page (as every --help text says at the end).
CC: David Anes <david.anes@suse.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/renice.c | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/sys-utils/renice.c b/sys-utils/renice.c
index eac104db3..7872e8fbb 100644
--- a/sys-utils/renice.c
+++ b/sys-utils/renice.c
@@ -70,10 +70,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Alter the priority of running processes.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(_(" -n <num> specify the nice value;\n"
- " if POSIXLY_CORRECT flag is set in environment,\n"
- " then the priority is 'relative' to current\n"
- " process priority; otherwise it is 'absolute'\n"), out);
+ fputs(_(" -n <num> specify the 'absolute' nice value,\n"
+ " but 'relative' when POSIXLY_CORRECT is set\n"), out);
fputs(_(" --priority <num> specify the 'absolute' nice value\n"), out);
fputs(_(" --relative <num> specify the 'relative' nice value\n"), out);
fputs(_(" -p, --pid interpret arguments as process ID (default)\n"), out);
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 07/10] renice: (man) reword several things, to be clearer, and improve some markup
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (4 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 06/10] renice: in usage text, condense the oververbose description of option -n Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 08/10] lscpu: (man) don't refer to a missing section, and improve some wordings Benno Schulenberg
` (4 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux; +Cc: David Anes
Also, remove a reference to ulimit(1p) that doesn't make sense.
CC: David Anes <david.anes@suse.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/renice.1.adoc | 37 ++++++++++++++++++++++++++-----------
1 file changed, 26 insertions(+), 11 deletions(-)
diff --git a/sys-utils/renice.1.adoc b/sys-utils/renice.1.adoc
index e50e1e918..5f2e2a98d 100644
--- a/sys-utils/renice.1.adoc
+++ b/sys-utils/renice.1.adoc
@@ -46,24 +46,30 @@ renice - alter priority of running processes
== SYNOPSIS
-*renice* [*--priority|--relative*] _priority_ [*-g*|*-p*|*-u*] _identifier_...
+*renice* [*-n*|*--priority*|*--relative*] _priority_ [*-g*|*-p*|*-u*] _identifier_...
== DESCRIPTION
*renice* alters the scheduling priority of one or more running processes. The first argument is the _priority_ value to be used. The other arguments are interpreted as process IDs (by default), process group IDs, user IDs, or user names. *renice*'ing a process group causes all processes in the process group to have their scheduling priority altered. *renice*'ing a user causes all processes owned by the user to have their scheduling priority altered.
-If no *-n*, *--priority* or *--relative* option is used, then the priority is set as *absolute*.
+By default, _priority_ is understood as an absolute value. But when option *--relative* is given,
+or when option *-n* is given and the environment variable POSIXLY_CORRECT is set, then _priority_
+is understood as a relative value.
== OPTIONS
-*-n* _priority_::
-Specify the *absolute* or *relative* (depending on environment variable POSIXLY_CORRECT) scheduling _priority_ to be used for the process, process group, or user. Use of the option *-n* is optional, but when used, it must be the first argument. See *NOTES* for more information.
+*-n* _priority_|__delta__::
+Specify the absolute scheduling priority (when POSIXLY_CORRECT is not set) or a relative
+priority (when POSIXLY_CORRECT *is* set). See *NOTES* below for more details.
+Using option *-n* is optional, but when used, it must be the first argument.
*--priority* _priority_::
-Specify an *absolute* scheduling _priority_. _Priority_ is set to the given value. This is the default, when no option is specified.
+Specify the absolute scheduling _priority_ to be used.
+This is the default, when no option is specified.
-*--relative* _priority_::
-Specify a *relative* scheduling _priority_. Same as the standard POSIX *-n* option. _Priority_ gets _incremented/decremented_ by the given value.
+*--relative* _delta_::
+Specify a relative priority. The actual scheduling priority gets incremented/decremented
+by the given _delta_. (This is the same as the *-n* option when POSIXLY_CORRECT is set.)
*-g*, *--pgrp*::
Interpret the succeeding arguments as process group IDs.
@@ -83,21 +89,30 @@ to map user names to user IDs
== NOTES
-Users other than the superuser may only alter the priority of processes they own. Furthermore, an unprivileged user can only _increase_ the "nice value" (i.e., choose a lower priority) and such changes are irreversible unless (since Linux 2.6.12) the user has a suitable "nice" resource limit (see *ulimit*(1p) and *getrlimit*(2)).
+Users other than the superuser may alter the priority only of processes they own.
+Furthermore, an unprivileged user can only _increase_ the "nice value" (that is:
+lower the urgency), and such changes are irreversible unless (since Linux 2.6.12)
+the user has a suitable "nice" resource limit (see *getrlimit*(2)).
The superuser may alter the priority of any process and set the priority to any value in the range -20 to 19. Useful priorities are: 19 (the affected processes will run only when nothing else in the system wants to), 0 (the "base" scheduling priority), anything negative (to make things go very fast).
-For historical reasons in this implementation, the *-n* option did not follow the POSIX specification. Therefore, instead of setting a *relative* priority, it sets an *absolute* priority by default. As this may not be desirable, this behavior can be controlled by setting the environment variable POSIXLY_CORRECT to be fully POSIX compliant. See the *-n* option for details. See *--relative* and *--priority* for options that do not change behavior depending on environment variables.
+For historical reasons, the *-n* option in this implementation does not follow the POSIX
+specification: instead of setting a *relative* priority, it sets an *absolute* priority
+by default. As this may not be desirable, this behavior can be changed by setting the
+environment variable POSIXLY_CORRECT, to be fully POSIX compliant. See *--relative* and
+*--priority* for options that do not change behavior depending on environment variables.
== HISTORY
The *renice* command appeared in 4.0BSD.
-== EXAMPLES
+== EXAMPLE
-The following command would change the priority of the processes with PIDs 987 and 32, plus all processes owned by the users daemon and root:
+The following command changes the priority of the processes with PIDs 987 and 32, plus all processes owned by the users daemon and root:
+____
*renice +1 987 -u daemon root -p 32*
+____
== SEE ALSO
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 08/10] lscpu: (man) don't refer to a missing section, and improve some wordings
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (5 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 07/10] renice: (man) reword several things, to be clearer, and improve some markup Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 09/10] docs: correct misspellings of "may be" and mistaken uses of "overwritten" Benno Schulenberg
` (3 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
Three years ago commit aa049eabb3 removed the COLUMNS section but forgot
to remove the reference to it. Replace the reference with a referral to
the --help text.
In the bargain, join two paragraphs that belong together, improve some
wordings, and sort two options.
This fixes #2590 (https://github.com/util-linux/util-linux/issues/2590).
Reported-by: Fabien Malfoy
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/lscpu.1.adoc | 31 ++++++++++++++++++++-----------
1 file changed, 20 insertions(+), 11 deletions(-)
diff --git a/sys-utils/lscpu.1.adoc b/sys-utils/lscpu.1.adoc
index f86f531fd..940b1bfeb 100644
--- a/sys-utils/lscpu.1.adoc
+++ b/sys-utils/lscpu.1.adoc
@@ -22,8 +22,11 @@ The default output formatting on terminal is subject to change and maybe optimiz
In virtualized environments, the CPU architecture information displayed reflects the configuration of the guest operating system which is typically different from the physical (host) system. On architectures that support retrieving physical topology information, *lscpu* also displays the number of physical sockets, chips, cores in the host system.
-Options that result in an output table have a _list_ argument. Use this argument to customize the command output. Specify a comma-separated list of column labels to limit the output table to only the specified columns, arranged in the specified order. See *COLUMNS* for a list of valid column labels. The column labels are not case sensitive.
-
+Options that produce an output table accept an optional _list_ argument.
+This _list_ is a comma-separated series of column labels to limit the
+table to only the specified columns, arranged in the specified order.
+Use *--help* to see a list of valid column labels.
+The labels are case insensitive.
Not all columns are supported on all architectures. If an unsupported column is specified, *lscpu* prints the column but does not provide any data for it.
The cache sizes are reported as summary from all CPUs. The versions before v2.34 reported per-core sizes, but this output was confusing due to complicated CPUs topology and the way how caches are shared between CPUs. For more details about caches see *--cache*. Since version v2.37 *lscpu* follows cache IDs as provided by Linux kernel and it does not always start from zero.
@@ -44,37 +47,46 @@ Display details about CPU caches. For details about available information see *-
+
If the _list_ argument is omitted, all columns for which data is available are included in the command output.
+
-When specifying the _list_ argument, the string of option, equal sign (=), and _list_ must not contain any blanks or other whitespace. Examples: *-C=NAME,ONE-SIZE* or *--caches=NAME,ONE-SIZE*.
+When specifying the _list_ argument, the option string plus the
+equal sign (=) plus the _list_ may not contain any whitespace.
+Examples: *-C=NAME,ONE-SIZE* or *--caches=NAME,ONE-SIZE*.
+
The default list of columns may be extended if list is specified in the format +list (e.g., **lscpu -C=+ALLOC-POLICY**).
*-c*, *--offline*::
Limit the output to offline CPUs. This option may only be specified together with option *-e* or *-p*.
-*--hierarchic*[**=**_when_]::
-Use subsections in summary output. For backward compatibility, the default is to use subsections only when output on a terminal and flattened output on a non-terminal. The optional argument _when_ can be *never*, *always* or *auto*. If the _when_ argument is omitted, it defaults to "always".
-
*-e*, *--extended*[**=**_list_]::
Display the CPU information in human-readable format.
+
If the _list_ argument is omitted, the default columns are included in the command output. The default output is subject to change.
+
-When specifying the _list_ argument, the string of option, equal sign (=), and _list_ must not contain any blanks or other whitespace. Examples: '*-e=cpu,node*' or '*--extended=cpu,node*'.
+When specifying the _list_ argument, the option string plus the
+equal sign (=) plus the _list_ may not contain any whitespace.
+Examples: *-e=cpu,node* or *--extended=cpu,node*.
+
The default list of columns may be extended if list is specified in the format +list (e.g., lscpu -e=+MHZ).
+*--hierarchic*[**=**_when_]::
+Use subsections in summary output. For backward compatibility, the default is to use subsections only when output on a terminal, and to use flattened output on a non-terminal. The optional argument _when_ can be *never*, *always*, or *auto*. If the _when_ argument is omitted, it defaults to *always*.
+
*-J*, *--json*::
Use JSON output format for the default summary or extended output (see
*--extended*). For backward compatibility, JSON output follows the default
summary behavior for non-terminals (e.g., pipes) where subsections are missing. See
also *--hierarchic*.
+*--output-all*::
+Output all available columns. This option must be combined with either *--extended*, *--parse*, or *--caches*.
+
*-p*, *--parse*[**=**_list_]::
Optimize the command output for easy parsing.
+
If the _list_ argument is omitted, the command output is compatible with earlier versions of *lscpu*. In this compatible format, two commas are used to separate CPU cache columns. If no CPU caches are identified the cache column is omitted. If the _list_ argument is used, cache columns are separated with a colon (:).
+
-When specifying the _list_ argument, the string of option, equal sign (=), and _list_ must not contain any blanks or other whitespace. Examples: '*-p=cpu,node*' or '*--parse=cpu,node*'.
+When specifying the _list_ argument, the option string plus the
+equal sign (=) plus the _list_ may not contain any whitespace.
+Examples: *-p=cpu,online,mhz* or *--parse=cpu,online,mhz*.
+
The default list of columns may be extended if list is specified in the format +list (e.g., lscpu -p=+MHZ).
@@ -92,9 +104,6 @@ Display physical IDs for all columns with topology elements (core, socket, etc.)
+
The CPU logical numbers are not affected by this option.
-*--output-all*::
-Output all available columns. This option must be combined with either *--extended*, *--parse* or *--caches*.
-
include::man-common/help-version.adoc[]
== BUGS
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 09/10] docs: correct misspellings of "may be" and mistaken uses of "overwritten"
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (6 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 08/10] lscpu: (man) don't refer to a missing section, and improve some wordings Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:48 ` [PATCH 10/10] docs: correct mistaken uses of "overwrite" to say "override" instead Benno Schulenberg
` (2 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
disk-utils/sfdisk.8.adoc | 10 ++++++++--
login-utils/lslogins.1.adoc | 8 ++++++--
misc-utils/cal.1.adoc | 8 ++++----
sys-utils/lscpu.1.adoc | 2 +-
sys-utils/nsenter.1.adoc | 4 +++-
term-utils/agetty.8.adoc | 4 +++-
6 files changed, 25 insertions(+), 11 deletions(-)
diff --git a/disk-utils/sfdisk.8.adoc b/disk-utils/sfdisk.8.adoc
index d61a031c2..1ffc61588 100644
--- a/disk-utils/sfdisk.8.adoc
+++ b/disk-utils/sfdisk.8.adoc
@@ -148,7 +148,9 @@ Move GPT backup header behind the last partition. Note that UEFI standard requir
*-a*, *--append*::
Don't create a new partition table, but only append the specified partitions.
+
-Note that unused partition maybe be re-used in this case although it is not the last partition in the partition table. See also *-N* to specify entry in the partition table.
+Note that in this case an unused partition may be re-used even though it is
+not the last partition in the partition table. See also *-N* for addressing a
+specific entry in the partition table.
*-b*, *--backup*::
Back up the current partition table sectors before starting the partitioning. The default backup file name is _~/sfdisk-<device>-<offset>.bak_; to use another name see option *-O*, *--backup-file*. See section *BACKING UP THE PARTITION TABLE* for more details.
@@ -215,7 +217,11 @@ Specify the sector size of the disk. Valid values are 512, 1024, 2048, and 4096.
Deprecated option. Only the sector unit is supported. This option is not supported when using the *--show-size* command.
*-X*, *--label* _type_::
-Specify the disk label type (e.g., *dos*, *gpt*, ...). If this option is not given, then *sfdisk* defaults to the existing label, but if there is no label on the device yet, then the type defaults to *dos*. The default or the current label may be overwritten by the "label: <name>" script header line. The option *--label* does not force *sfdisk* to create empty disk label (see the *EMPTY DISK LABEL* section below).
+Specify the disk-label type (e.g., *dos*, *gpt*, ...). If this option is not given,
+then *sfdisk* defaults to the type of the existing label, but if there is no label
+on the device yet, then the type defaults to *dos*. This default may be overridden
+by the "label: <name>" script-header line. The option *--label* does not force
+*sfdisk* to create an empty disk label (see the *EMPTY DISK LABEL* section below).
*-Y*, *--label-nested* _type_::
Force editing of a nested disk label. The primary disk label has to exist already. This option allows editing for example a hybrid/protective MBR on devices with GPT.
diff --git a/login-utils/lslogins.1.adoc b/login-utils/lslogins.1.adoc
index debd87f5a..7a344a7f4 100644
--- a/login-utils/lslogins.1.adoc
+++ b/login-utils/lslogins.1.adoc
@@ -79,13 +79,17 @@ Display information related to login by password (see also *-afL*).
Raw output (no columnation).
*-s*, *--system-accs*::
-Show system accounts. These are by default all accounts with a UID between 101 and 999 (inclusive), with the exception of either nobody or nfsnobody (UID 65534). This hardcoded default may be overwritten by parameters *SYS_UID_MIN* and *SYS_UID_MAX* in the file _/etc/login.defs_.
+Show system accounts. These are by default all accounts with a UID between 101 and 999 (inclusive),
+with the exception of either nobody or nfsnobody (UID 65534). This hardcoded default may be
+overridden by the parameters *SYS_UID_MIN* and *SYS_UID_MAX* in the file _/etc/login.defs_.
*--time-format* _type_::
Display dates in short, full or iso format. The default is short, this time format is designed to be space efficient and human readable.
*-u*, *--user-accs*::
-Show user accounts. These are by default all accounts with UID above 1000 (inclusive), with the exception of either nobody or nfsnobody (UID 65534). This hardcoded default maybe overwritten by parameters UID_MIN and UID_MAX in the file _/etc/login.defs_.
+Show user accounts. These are by default all accounts with a UID above 1000 (inclusive),
+with the exception of either nobody or nfsnobody (UID 65534). This hardcoded default may be
+overridden by the parameters *UID_MIN* and *UID_MAX* in the file _/etc/login.defs_.
include::man-common/help-version.adoc[]
diff --git a/misc-utils/cal.1.adoc b/misc-utils/cal.1.adoc
index 9f1740620..43a9a3902 100644
--- a/misc-utils/cal.1.adoc
+++ b/misc-utils/cal.1.adoc
@@ -113,10 +113,10 @@ Display a calendar for the whole year.
Display a calendar for the next twelve months.
*-w*, *--week*[**=**_number_]::
-Display week numbers in the calendar according to the US or ISO-8601 format. If
-a _number_ is specified, the requested week will be printed in the desired or
-current year. The _number_ may be overwritten if _day_ and _month_ are also
-specified.
+Display week numbers in the calendar according to the US or ISO-8601 format.
+If a _number_ is specified, the requested week in the desired or current year
+will be printed and its number highlighted.
+The _number_ may be ignored if _month_ is also specified.
+
See the *NOTES* section for more details.
diff --git a/sys-utils/lscpu.1.adoc b/sys-utils/lscpu.1.adoc
index 940b1bfeb..795c3938b 100644
--- a/sys-utils/lscpu.1.adoc
+++ b/sys-utils/lscpu.1.adoc
@@ -18,7 +18,7 @@ lscpu - display information about the CPU architecture
*lscpu* gathers CPU architecture information from _sysfs_, _/proc/cpuinfo_ and any applicable architecture-specific libraries (e.g. *librtas* on Powerpc). The command output can be optimized for parsing or for easy readability by humans. The information includes, for example, the number of CPUs, threads, cores, sockets, and Non-Uniform Memory Access (NUMA) nodes. There is also information about the CPU caches and cache sharing, family, model, bogoMIPS, byte order, and stepping.
-The default output formatting on terminal is subject to change and maybe optimized for better readability. The output for non-terminals (e.g., pipes) is never affected by this optimization and it is always in "Field: data\n" format. Use for example "*lscpu | less*" to see the default output without optimizations.
+The default output formatting on a terminal is subject to change and may be optimized for better readability. The output for non-terminals (e.g., pipes) is never affected by this optimization and it is always in "Field: data\n" format. Use for example "*lscpu | less*" to see the default output without optimizations.
In virtualized environments, the CPU architecture information displayed reflects the configuration of the guest operating system which is typically different from the physical (host) system. On architectures that support retrieving physical topology information, *lscpu* also displays the number of physical sockets, chips, cores in the host system.
diff --git a/sys-utils/nsenter.1.adoc b/sys-utils/nsenter.1.adoc
index cb6419fda..c717d0ceb 100644
--- a/sys-utils/nsenter.1.adoc
+++ b/sys-utils/nsenter.1.adoc
@@ -51,7 +51,9 @@ Various of the options below that relate to namespaces take an optional _file_ a
//TRANSLATORS: Keep {asterisk} untranslated.
*-a*, *--all*::
-Enter all namespaces of the target process by the default _/proc/[pid]/ns/{asterisk}_ namespace paths. The default paths to the target process namespaces may be overwritten by namespace specific options (e.g., *--all --mount*=[_path_]).
+Enter all namespaces of the target process by the default _/proc/<pid>/ns/{asterisk}_
+namespace paths. The default paths to the target process namespaces may be overridden
+by namespace-specific options (e.g., **--all --mount=**_path_).
+
The user namespace will be ignored if the same as the caller's current user namespace. It prevents a caller that has dropped capabilities from regaining those capabilities via a call to setns(). See *setns*(2) for more details.
diff --git a/term-utils/agetty.8.adoc b/term-utils/agetty.8.adoc
index 988915865..a33f12a3f 100644
--- a/term-utils/agetty.8.adoc
+++ b/term-utils/agetty.8.adoc
@@ -237,7 +237,9 @@ Since version 2.35, additional locations for the issue file and directory are su
Note that in versions 2.35 to 2.40, the additional locations were only read if the default _/etc/issue_ file did not exist. However, since version 2.41, the additional locations are always read, regardless of the existence of the _/etc/issue_ file. This change allows for the generation of issue files by default.
-The default paths maybe completely overridden by *--issue-file* option. In this case specified path has to be file or directory and all the default issue file and directory locations are ignored.
+The default paths may be completely overridden by the *--issue-file* option.
+In this case the specified path has to be a file or directory and
+all the default issue file and directory locations are ignored.
The issue file feature can be completely disabled by *--noissue* option.
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 10/10] docs: correct mistaken uses of "overwrite" to say "override" instead
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (7 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 09/10] docs: correct misspellings of "may be" and mistaken uses of "overwritten" Benno Schulenberg
@ 2025-04-17 9:48 ` Benno Schulenberg
2025-04-17 9:58 ` [PATCH 01/10] bits: (man) normalize the markup and improve some layout Robin Jarry
2025-04-24 9:57 ` Karel Zak
10 siblings, 0 replies; 12+ messages in thread
From: Benno Schulenberg @ 2025-04-17 9:48 UTC (permalink / raw)
To: util-linux
This mostly comes down to harmonizing the wording and markup of the
various --lock options.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
disk-utils/cfdisk.8.adoc | 7 ++++++-
disk-utils/fdisk.8.adoc | 7 ++++++-
disk-utils/mkfs.bfs.8.adoc | 7 ++++++-
disk-utils/mkfs.cramfs.8.adoc | 4 ++--
disk-utils/mkfs.minix.8.adoc | 7 ++++++-
disk-utils/mkswap.8.adoc | 7 ++++++-
disk-utils/sfdisk.8.adoc | 7 ++++++-
misc-utils/logger.1.adoc | 2 +-
misc-utils/wipefs.8.adoc | 7 ++++++-
sys-utils/hwclock.8.adoc | 12 ++++++++++--
sys-utils/losetup.8.adoc | 11 +++++++++--
sys-utils/mount.8.adoc | 3 ++-
12 files changed, 66 insertions(+), 15 deletions(-)
diff --git a/disk-utils/cfdisk.8.adoc b/disk-utils/cfdisk.8.adoc
index 0075fd472..121d023ab 100644
--- a/disk-utils/cfdisk.8.adoc
+++ b/disk-utils/cfdisk.8.adoc
@@ -48,7 +48,12 @@ If you want to remove an old partition table from a device, use *wipefs*(8).
Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled, for the current built-in default see *--help* output. See also the *COLORS* section.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-r*, *--read-only*::
Forced open in read-only mode.
diff --git a/disk-utils/fdisk.8.adoc b/disk-utils/fdisk.8.adoc
index c18c38273..13e7147bb 100644
--- a/disk-utils/fdisk.8.adoc
+++ b/disk-utils/fdisk.8.adoc
@@ -60,7 +60,12 @@ If no devices are given, the devices mentioned in _/proc/partitions_ (if this fi
Like *--list*, but provides more details.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-n*, *--noauto-pt*::
Don't automatically create a default partition table on empty device. The partition table has to be explicitly created by user (by command like 'o', 'g', etc.).
diff --git a/disk-utils/mkfs.bfs.8.adoc b/disk-utils/mkfs.bfs.8.adoc
index 248013731..e66f8e0b5 100644
--- a/disk-utils/mkfs.bfs.8.adoc
+++ b/disk-utils/mkfs.bfs.8.adoc
@@ -36,7 +36,12 @@ Specify the volume _label_. I have no idea if/where this is used.
Specify the filesystem _name_. I have no idea if/where this is used.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-v*, *--verbose*::
Explain what is being done.
diff --git a/disk-utils/mkfs.cramfs.8.adoc b/disk-utils/mkfs.cramfs.8.adoc
index 8a2c4a79e..bca5e8f62 100644
--- a/disk-utils/mkfs.cramfs.8.adoc
+++ b/disk-utils/mkfs.cramfs.8.adoc
@@ -67,8 +67,8 @@ Use an exclusive BSD lock for the device or file that is operated upon.
The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
If the _mode_ argument is omitted, it defaults to *yes*.
This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
-The default is to not use any lock at all, but using a lock
-is recommended to avoid collisions with udevd or other tools.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
include::man-common/help-version.adoc[]
diff --git a/disk-utils/mkfs.minix.8.adoc b/disk-utils/mkfs.minix.8.adoc
index 4b8426f3e..f747ee40f 100644
--- a/disk-utils/mkfs.minix.8.adoc
+++ b/disk-utils/mkfs.minix.8.adoc
@@ -47,7 +47,12 @@ Check the device for bad blocks before creating the filesystem. If any are found
Specify the maximum length of filenames. Currently, the only allowable values are 14 and 30 for file system versions 1 and 2. Version 3 allows only value 60. The default is 30.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-i*, *--inodes* _number_::
Specify the number of inodes for the filesystem.
diff --git a/disk-utils/mkswap.8.adoc b/disk-utils/mkswap.8.adoc
index 974a5af4e..a7838ae91 100644
--- a/disk-utils/mkswap.8.adoc
+++ b/disk-utils/mkswap.8.adoc
@@ -58,7 +58,12 @@ Suppress output and warning messages.
Specify a _label_ for the device, to allow *swapon*(8) by label.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-p*, *--pagesize* _size_::
Specify the page _size_ (in bytes) to use. This option is usually unnecessary; *mkswap* reads the size from the kernel.
diff --git a/disk-utils/sfdisk.8.adoc b/disk-utils/sfdisk.8.adoc
index 1ffc61588..ac81ec939 100644
--- a/disk-utils/sfdisk.8.adoc
+++ b/disk-utils/sfdisk.8.adoc
@@ -165,7 +165,12 @@ Disable all consistency checking.
Deprecated and ignored option. Partitioning that is compatible with Linux (and other modern operating systems) is the default.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *yes*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with *systemd-udevd*(8) or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-n*, *--no-act*::
Do everything except writing to the device.
diff --git a/misc-utils/logger.1.adoc b/misc-utils/logger.1.adoc
index 0c4edbeac..e63f5eff8 100644
--- a/misc-utils/logger.1.adoc
+++ b/misc-utils/logger.1.adoc
@@ -73,7 +73,7 @@ Log the PID of the *logger* process with each line.
*--id*[**=**__id__]::
Log the PID of the *logger* process with each line. When the optional argument _id_ is specified, then it is used instead of the *logger* command's PID. The use of *--id=$$* (PPID) is recommended in scripts that send several messages.
+
-Note that the system logging infrastructure (for example *systemd* when listening on _/dev/log_) may follow local socket credentials to overwrite the PID specified in the message. *logger*(1) is able to set those socket credentials to the given _id_, but only if you have root permissions and a process with the specified PID exists, otherwise the socket credentials are not modified and the problem is silently ignored.
+Note that the system logging infrastructure (for example *systemd* when listening on _/dev/log_) may follow local socket credentials to override the PID specified in the message. *logger*(1) is able to set those socket credentials to the given _id_, but only if you have root permissions and a process with the specified PID exists, otherwise the socket credentials are not modified and the problem is silently ignored.
*--journald*[**=**__file__]::
Write a *systemd* journal entry. The entry is read from the given _file_, when specified, otherwise from standard input. Each line must begin with a field that is accepted by *journald*; see *systemd.journal-fields*(7) for details. The use of a MESSAGE_ID field is generally a good idea, as it makes finding entries easy. Examples:
diff --git a/misc-utils/wipefs.8.adoc b/misc-utils/wipefs.8.adoc
index 88efaeca5..5226ea8b4 100644
--- a/misc-utils/wipefs.8.adoc
+++ b/misc-utils/wipefs.8.adoc
@@ -50,7 +50,12 @@ Force erasure, even if the filesystem is mounted. This is required in order to e
Use JSON output format.
*--lock*[**=**_mode_]::
-Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *"yes"*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with udevd or other tools.
+Use an exclusive BSD lock for the device or file that is operated upon.
+The optional argument _mode_ can be *yes* (*1*), *no* (*0*), or *nonblock*.
+If the _mode_ argument is omitted, it defaults to *yes*.
+This option overrides the environment variable *$LOCK_BLOCK_DEVICE*.
+The default is to not use any lock at all, but using a lock is recommended
+to avoid collisions with *systemd-udevd*(8) or other tools.
*-i*, *--noheadings*::
Do not print a header line.
diff --git a/sys-utils/hwclock.8.adoc b/sys-utils/hwclock.8.adoc
index e30fb5e90..3ad02054f 100644
--- a/sys-utils/hwclock.8.adoc
+++ b/sys-utils/hwclock.8.adoc
@@ -124,9 +124,17 @@ This option must be used with the *--set* or *--predict* functions, otherwise it
The argument must be in local time, even if you keep your Hardware Clock in UTC. See the *--localtime* option. Therefore, the argument should not include any timezone information. It also should not be a relative time like "+5 minutes", because *hwclock*'s precision depends upon correlation between the argument's value and when the enter key is pressed. Fractional seconds are silently dropped. This option is capable of understanding many time and date formats, but the previous parameters should be observed.
**--delay=**__seconds__::
-This option can be used to overwrite the internally used delay when setting the clock time. The default is 0.5 (500ms) for rtc_cmos, for another RTC types the delay is 0. If RTC type is impossible to determine (from sysfs) then it defaults also to 0.5 to be backwardly compatible.
+This option overrides the default delay used when setting the clock time.
+The default is *0.5* (500 ms) for rtc_cmos; for other RTC types the delay is *0*.
+If the RTC type cannot be determined (from sysfs), then the delay defaults
+also to *0.5* to be backwardly compatible.
+
-The 500ms default is based on commonly used MC146818A-compatible (x86) hardware clock. This Hardware Clock can only be set to any integer time plus one half second. The integer time is required because there is no interface to set or get a fractional second. The additional half second delay is because the Hardware Clock updates to the following second precisely 500 ms after setting the new time. Unfortunately, this behavior is hardware specific and in some cases another delay is required.
+The 500 ms default is based on the commonly used MC146818A-compatible (x86) hardware clock.
+This Hardware Clock can only be set to an integer time plus one half second.
+The integer time is required because there is no interface to get or set a fractional second.
+The additional half second is because the Hardware Clock updates to the following second
+precisely 500 ms after setting the new time. Unfortunately, this behavior is hardware specific
+and in some cases a different delay is required.
*-D*, *--debug*::
Use *--verbose*. The *--debug* option has been deprecated and may be repurposed or removed in a future release.
diff --git a/sys-utils/losetup.8.adoc b/sys-utils/losetup.8.adoc
index e549ddf1a..48d71ec18 100644
--- a/sys-utils/losetup.8.adoc
+++ b/sys-utils/losetup.8.adoc
@@ -42,7 +42,9 @@ Resize a loop device:
Note that the old output format (i.e., *losetup -a*) with comma-delimited strings is deprecated in favour of the *--list* output format.
-It's possible to create more independent loop devices for the same backing file. *This setup may be dangerous, can cause data loss, corruption and overwrites.* Use *--nooverlap* with *--find* during setup to avoid this problem.
+It is possible to create multiple independent loop devices for the same backing file.
+*This setup may be dangerous, can cause data loss, corruption, and overwrites.*
+Use *--nooverlap* with *--find* during setup to avoid this problem.
The loop device setup is not an atomic operation when used with *--find*, and *losetup* does not protect this operation by any lock. The number of attempts is internally restricted to a maximum of 16. It is recommended to use for example *flock*(1) to avoid a collision in heavily parallel use cases.
@@ -75,7 +77,12 @@ Show the status of all loop devices associated with the given _file_.
The data start is moved _offset_ bytes into the specified file or device. The _offset_ may be followed by the multiplicative suffixes; see above.
*--loop-ref* _string_::
-Set reference string. The backwardly compatible default is to use the backing filename as a reference in loop setup ioctl (aka lo_file_name). This option can overwrite this default behavior and set the reference to the _string_. The reference may be used by udevd in /dev/loop/by-ref. Linux kernel does not use the reference at all, but it could be used by some old utils that cannot read the backing file from sysfs. The reference is readable only for the root user (see *--output* +REF) and it is restricted to 64 bytes.
+Set the reference string. The backwardly compatible default is to use the backing filename
+as a reference in the loop setup ioctl (aka lo_file_name). This option overrides this default
+behavior and sets the reference to the _string_. The reference may be used by udevd in
+/dev/loop/by-ref. The Linux kernel does not use the reference at all, but it could be used
+by some old utils that cannot read the backing file from sysfs. The reference is readable
+only for the root user (see *--output* +REF) and it is restricted to 64 bytes.
*--sizelimit* _size_::
The data end is set to no more than _size_ bytes after the data start. The _size_ may be followed by the multiplicative suffixes; see above.
diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
index 95998ce2a..e827b212a 100644
--- a/sys-utils/mount.8.adoc
+++ b/sys-utils/mount.8.adoc
@@ -385,7 +385,8 @@ Use the specified mount options. The _opts_ argument is a comma-separated list.
+
*mount LABEL=mydisk -o noatime,nodev,nosuid*
+
-Note that the order of the options matters, as the last option wins if there are conflicting ones. The options from the command line also overwrite options from fstab by default.
+Note that the order of the options matters, as the last option wins if there are conflicting ones.
+Also, options on the command line override options from fstab.
+
For more details, see the *FILESYSTEM-INDEPENDENT MOUNT OPTIONS* and *FILESYSTEM-SPECIFIC MOUNT OPTIONS* sections.
--
2.48.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH 01/10] bits: (man) normalize the markup and improve some layout
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (8 preceding siblings ...)
2025-04-17 9:48 ` [PATCH 10/10] docs: correct mistaken uses of "overwrite" to say "override" instead Benno Schulenberg
@ 2025-04-17 9:58 ` Robin Jarry
2025-04-24 9:57 ` Karel Zak
10 siblings, 0 replies; 12+ messages in thread
From: Robin Jarry @ 2025-04-17 9:58 UTC (permalink / raw)
To: Benno Schulenberg, util-linux
Hi Beno,
Benno Schulenberg, Apr 17, 2025 at 11:48:
> The convention in man pages is: to put command arguments in lowercase
> and without angle brackets (these are for --help texts), and without
> unneeded abbreviations. Literal values (as in some examples) should
> be in bold, not in italics.
>
> CC: Robin Jarry <robin@jarry.cc>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
Reviewed-by: Robin Jarry <robin@jarry.cc>
Thanks for the cleanup!
^ permalink raw reply [flat|nested] 12+ messages in thread* Re: [PATCH 01/10] bits: (man) normalize the markup and improve some layout
2025-04-17 9:48 [PATCH 01/10] bits: (man) normalize the markup and improve some layout Benno Schulenberg
` (9 preceding siblings ...)
2025-04-17 9:58 ` [PATCH 01/10] bits: (man) normalize the markup and improve some layout Robin Jarry
@ 2025-04-24 9:57 ` Karel Zak
10 siblings, 0 replies; 12+ messages in thread
From: Karel Zak @ 2025-04-24 9:57 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux, Robin Jarry
On Thu, Apr 17, 2025 at 11:48:15AM +0200, Benno Schulenberg wrote:
> text-utils/bits.1.adoc | 80 ++++++++++++++++++++++--------------------
> 1 file changed, 42 insertions(+), 38 deletions(-)
Applied (all 10 patches), thanks.
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 12+ messages in thread