As mentioned in 'Generating optimal glyphs' title in the manual page
mentioned in reference:
Where a proper caret (^) that renders well in both a terminal and PDF is
required, use "\(ha".
Using a naked "~" character results in a poor rendering in PDF. Instead
use "\(ti".
Reference: https://man7.org/linux/man-pages/man7/man-pages.7.html#STYLE_GUIDE
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
In several pages, there is a consistent wording problem: "another"
where "other" should be used. This wording problem can be
surprisingly confusing for native speakers, especially those
unaware that in some other languages, "another" and "other" can be
expressed with the same word.
Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
There is value in ensuring that manual page sections use consistently
named sections, as far as possible, and also that sections have a
consistent order within manual pages. This is one of a series of patches
to place manual page sections in a consistent order.
In this patch, we ensure that the AUTHORS, COPYRIGHT, SEE ALSO, and
AVAILABILITY sections are always placed at the end of the page.
Testing that no gross editing mistake (causing accidental loss or addition
of text) was performed as follows:
$ cat $(grep '\.SH' -l $(find . -name '*.[1-9]') |sort) | sort > a
[Apply patch]
$ cat $(grep '\.SH' -l $(find . -name '*.[1-9]') |sort) | sort > b
$ diff a b
$ echo $?
0
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The manual pages currently use a multitude of terms--"exit code",
"error code", "return code", "exit code", and so on--when what
is always meant is "exit status" (the POSIX term). This patch fixes
as many of these erroneous terms as I could find.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There is quite some value (in terms of readability and user
expectations) if consistent names are used for the sections
within manual pages. This patch is one of a series to bring
about this consistency.
Currently we have EXIT STATUS (18), EXIT CODES (3), RETURN CODE (7),
RETURN CODES (1), or RETURN VALUE (4 instances in pages that document
commands, rather than functions).
Let's standardize on the EXIT STATUS (which is also what is
suggested in man-pages(7), and is the POSIX terminology).
A subsequent patch will clean up corresponding miswordings in
manual page text.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There is quite some value (in terms of readability and user
expectations) if consistent names are used for the sections
within manual pages. This patch is one of a series to bring
about this consistency.
In the Linux man-pages project, I long ago did away with the
AUTHOR(S) section, but I realize some projects like to keep this.
But, let's make sure that the section is consistently titled
across pages. Currently we have AUTHOR (47) or AUTHORS (41).
Let's standardize on the latter (which is also what is
suggested in man-pages(7)).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Using double quotes in .SH lines containing multiple words is unneeded,
and in any case is not consistently done in the util-linux manual pages,
where double quotes are used in only around half of the cases.
(This usage was long ago elminated in the man-pages project, with
no ill effects reported to date.)
Remove these quotes, so that .SH lines are more uniform, in preparation
for some (more easily) scripted doiscovery of consistency problems in
(and possibly global fixes to) the manual pages.
Other than stripping the double quotes, this patch makes no changes to
the content of the manual pages.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Change a HYPHEN-MINUS (code 0x55, 2D) to a minus (\-), if in front of
1) a name of an option
2) a negative number to be printed.
See man-pages(7) [Debian package "manpages"].
The output from "nroff" is unchanged.
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Add a comma (,) after "e.g." and "i.e.", or use English words
(man-pages(7) [package "manpages"]).
Abbreviation points should be protected (usually with the
non-printing, zero width character '\&') from being interpreted as an
end of sentence, if they are not, and that independent of their current
place on the line.
This is important when typing, as one does not usually know in
advance when the editor jumps to a new line.
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Sorry detail-oriented people tend to wipe these out if they notice them.
Add in automated tools and lots of excess end-of-line spaces get wiped
out.
Addresses: https://github.com/karelzak/util-linux/pull/849
Signed-off-by: Karel Zak <kzak@redhat.com>
blkid(8) in high-level mode checks partitions and unpartitioned
whole-disk devices from the file /proc/partitions.
The current heuristic assumes that partition name ends with a digit.
Unfortunately, this is not correct -- for example md0 or nvme0n1 are
whole-disk devices.
This commit uses sysfs_devno_is_wholedisk() to make sure the device is
a partition (according to kernel or DM). It's probably more expensive,
because this way requires more syscalls (to read stuff from /sys etc.).
The patch also adds more information to the blkid(8) man page.
Addresses: https://github.com/karelzak/util-linux/issues/728
Signed-off-by: Karel Zak <kzak@redhat.com>
blkid(8) returns information from partition table also for empty
partitions. This is necessary for example for udev, but it could be
confusing if you care about on-device content only.
Default:
# blkid -p /dev/md0p1; echo $?
/dev/md0p1: PART_ENTRY_SCHEME="dos" PART_ENTRY_UUID="6d8796b1-01" PART_ENTRY_TYPE="0x83" PART_ENTRY_NUMBER="1" PART_ENTRY_OFFSET="2048" PART_ENTRY_SIZE="204800" PART_ENTRY_DISK="9:0"
0
With --no-part-details:
# blkid -p /dev/md0p1 --no-part-details; echo $?
2
Addresses: https://bugzilla.redhat.com/show_bug.cgi?id=1653413
Signed-off-by: Karel Zak <kzak@redhat.com>
This change attempts to make tab completion more reasonable by alloging
memorizable option names. That also has positive impact to manual page, in
which referrals to other options are now easier to understand.
All short options are kept exactly as they were to avoid ABI breakage. The
only exception is -f option that getopt(3) recognized, but was not found
from anywhere else. The -f has been part of blkid since the initial commit.
Commit: 51410fc6de
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
This patch does only the following:
* Order SEE ALSO entries first by section name, then alphabetically
within section
* Adds one or two missing commas in SEE ALSO lists
* Removes one or two periods that were (inconsistently) used
at the end of SEE ALSO lists.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Transform some of them into copyright lines.
Also fix three header lines and snip some trailing whitespace.
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
The high-level libblkid API uses /run/blkid/blkid.tab cache to
store probing results. The cache format is
<device NAME="value" ...>devname</device>
and unfortunately the cache code does not escape quotation marks:
# mkfs.ext4 -L 'AAA"BBB'
# cat /run/blkid/blkid.tab
...
<device ... LABEL="AAA"BBB" ...>/dev/sdb1</device>
such string is later incorrectly parsed and blkid(8) returns
nonsenses. And for use-cases like
# eval $(blkid -o export /dev/sdb1)
it's also insecure.
Note that mount, udevd and blkid -p are based on low-level libblkid
API, it bypass the cache and directly read data from the devices.
The current udevd upstream does not depend on blkid(8) output at all,
it's directly linked with the library and all unsafe chars are encoded by
\x<hex> notation.
# mkfs.ext4 -L 'X"`/tmp/foo` "' /dev/sdb1
# udevadm info --export-db | grep LABEL
...
E: ID_FS_LABEL=X__/tmp/foo___
E: ID_FS_LABEL_ENC=X\x22\x60\x2ftmp\x2ffoo\x60\x20\x22
Signed-off-by: Karel Zak <kzak@redhat.com>
The standard format is to seperate each entry with a comma, and
for each one to be on a line by itself. Most util-linux pages
follow this, but a few do not.
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Furthermore, explain the device argument right at the beginning,
since it is not an option, and alphabetize -k.
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
Now libblkid (the cache based part) tries to probe for the cached
filesystem firstly. This optimization is broken, because:
* new another superblock could be on the device and the original
is already obsolete
* we still need to probe for partitions and raids
* the code was too fragile
The patch also suggests lsblk --fs in blkid.8 for end users. lsblk
read information from used db.
Reported-by: Andreas Hofmeister <andi@collax.com>
Signed-off-by: Karel Zak <kzak@redhat.com>
The tool misspellings (https://github.com/lyda/misspell-check)
detected several typos. Command used:
$ git ls-files | grep -v ^po/ | misspellings -f -
* isosize: Fix typo in usage string.
* configure.ac: Fix typo in help string of --enable-most-builds option.
* fdisk: Fix typo in man page.
* libblkid, blkid, mount: Likewise.
* Fix various typos in docs and in source code comments.
Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
Update the man pages of blkid, wipefs, fallocate, fstrim, losetup
and hexdump to clarify the suffixes for the numerical values of the
offset and size/length arguments regarding KiB=1024 vs KB=1000.
Also mention the ZiB/YiB and ZB/YB suffixes supported by strtosize().
Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
Why?
* read-only root
* /etc is pretty bad place for caches
* all is usually cached by udev in /dev/disk/by-* and libblkid
is able to use these symlinks
* boot persistent cache is attractive for very small subset of
Linux machines (and they already need extra udev tunning otherwise
udev will probe all block devices during boot)
* the default is possible to override in /etc/blkid.conf
The systems without /run directory will not be affected by this
change.
Signed-off-by: Karel Zak <kzak@redhat.com>
The option does not have any effect, the original functionality was
removed from e2fsprogs in year 2003 by
commit 50b380b4d4ab668bad45033e3a8aaf93c7f42844
git://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git
So.. don't propagate the option to users in year 2012 :-)
Signed-off-by: Karel Zak <kzak@redhat.com>
Use dates without the day, use the full month name, put "util-linux" in
the lower left corner, and "User Commands" or "System Administration"
at the top center.
Also improve here and there the one-line program description.
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
Sami Kerola
Michael Kerrisk (man-pages)
Bjarni Ingi Gislason
Elliott Mitchell
Karel Zak
Sébastien Helleu
Benno Schulenberg
Mike Frysinger
Gilles Espinasse
Davidlohr Bueso
Bernhard Voelker
Dave Reisner