Earlier, I patched various pages to consistently use EXAMPLE as a
section heading, rather than EXAMPLES. (At that time, both headings
occurred in util-linux, with roughly equal frequency.)
Since then, I've observed that EXAMPLES is the more common usage
across a large corpus of manual pages. So, in Linux the man-pages
project, I switched to using EXAMPLES also. This patch makes the same
change for util-linux.
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 NOTES, HISTORY, BUGS, and EXAMPLE
sections are always placed near the end of the page, just above
AUTHORS, COPYRIGHT, SEE ALSO, and AVAILABILITY.
One page is not fixed by this patch: term-utils/agetty.8. This page
is a mess of unusual section names, and probably requires an individual
edit.
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>
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.
Currently we have STANDARDS (3) or CONFORMING TO (6).
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>
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 EXAMPLE (10) or EXAMPLES (23).
Let's standardize on the EXAMPLE (which is also what is
suggested in man-pages(7)) and used consistently across
a large number of pages in the Linux man-pages project.
(I realize the choice to go EXAMPLE, rather than EXAMPLES,
may be debatable. If necessary, I'd write a patch that instead
goes the other way, but I'd prefer to follow man-pages(7).)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
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>
this is deemed a useful special case since journalctl will only show
either the first or last element of the message array if the field
appears multiple times.
Based on patch from: Kjetil Torgrim Homme <kjetil.homme@redpill-linpro.com>
https://github.com/karelzak/util-linux/pull/743
Addresses: https://github.com/karelzak/util-linux/issues/742
Signed-off-by: Karel Zak <kzak@redhat.com>
Define the allowed length of the last (second) column to use the
whole line for text.
Use text blocks for long lines.
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
A developmental version of "groff" issued a warning, for example with
"test-groff -b -e -mandoc -T utf8 -rF0 -t -w w -z":
troff: <logger.1>:299: warning: can't find font 't'
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Use the correct macro (I, B) for the font change of one argument, not
those that are used for alternating two fonts, like "BR", "IR", "RB",
or "RI".
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
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>
If you have really paranoid syslog (or systemd who listens on /dev/log)
then it replaces in the message PID with a real PID from socket header
credentials:
# echo $PPID
1550
# logger -p info --stderr --id=$PPID "This is message baby!"
<14>Oct 29 11:22:13 kzak[1550]: This is message baby!
# journald -n 1
Oct 29 11:22:13 ws kzak[22100]: This is message baby!
^^^^^
This patch forces kernel to accept another *valid* PID if logger(1)
executed with root permissions; improved version:
# logger -p info --stderr --id=$PPID "This is message baby!"
<14>Oct 29 11:26:00 kzak[1550]: This is message baby!
# journald -n 1
Oct 29 11:26:00 ws kzak[1550]: This is message baby!
Signed-off-by: Karel Zak <kzak@redhat.com>
The example use of logger --journald in the man page has a couple of flaws:
- It's missing a "MESSAGE=" field. This is supposed to be the primary
human readable text. Without it the log entry is invisible in a
plain "journalctl" output.
- The MESSAGE_ID is supposed to be a 128-bit hexadecimal string that
globally uniquely identifies the message type.
One can generate such an id with "journalctl --new-id".
This patches fixes the above and also changes the example to use a
here-document instead of printf. In my opinion it makes the expected
multi-line data format more obvious.
Signed-off-by: Michal Schmidt <mschmidt@redhat.com>
This patch adds support to logger for RFC6587 octet counting.
RFC6587 provides support for two sorts of framing:
1. Octet counting (at RFC6587 s3.4.1)
In essence each frame is preceded by a decimal length and a
space.
2. Non-transparent framing (at RFC6587 s3.4.2), also called
'octet stuffing'
In essence each frame is terminated by a `\n`
Prior to this patch, logger used option 2 (non-transparent framing)
on TCP, and used no framing on UDP. After this patch, the default
behaviour is unchanged, but if the '--octet-count' option is supplied,
option 1 is used for both TCP and UDP. Arguably octet count framing
makes little sense on UDP, but some servers provide it and this
allows testing of those servers.
Signed-off-by: Alex Bligh <alex@alex.org.uk>
* force --journal mode to also output to stderr when the option
--stderr specified on command line
* add --no-act to avoid all write() operations to make it possible to
write tests without "spam" system logs
Signed-off-by: Karel Zak <kzak@redhat.com>
Empty log messages are generally considered useless. This option
enables to turn them off when processing files (including stdin).
[kzak@redhat.com: - rename --skip-empty-lines to --skip-empty,
- add the option to getopt_long(),
- add the option to bash-completion]
Signed-off-by: Karel Zak <kzak@redhat.com>
This is an important capability that has been specified in RFC5424.
However, messages larger than 1024 chars are being accepted for years
now by at least rsyslog and syslog-ng.
This patch adds the option --size to permit setting a new max
size, with 1024 being the default.
Note that the size limit is only approximative, as we do not take the
header size in account (RFC talks about total message length).
[[kzak@redhat.com: - add 'S' to getopt_long(),
- rename --message-size to --size
- add the option to bash-completion]
Signed-off-by: Karel Zak <kzak@redhat.com>
With earlier logger it's possible to combine the option -i with other
options, such as -s. But currently:
$:~> logger -is
logger: failed to parse id: 's'
The changed behaviour breaks existing scripts like dhcpcd-run-hooks from
dhcpcd.
Broken-since: aab5b44405
Reference: http://comments.gmane.org/gmane.linux.utilities.util-linux-ng/9683
Reported-by: Juergen Daubert <jue@jue.li>
Reviewed-by: Benno Schulenberg <bensberg@justemail.net>
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
Hello,
Depending viewpoint this change is either regression fix, or
re-regression in context of none-systemd init. I ack the change is sent
very late to be part of v2.26, but then again the excess noise was found
only because of -rc1 was tested in sysvinit environment. IMHO it would
contradict purpose of having rc's if faults will not lead to fixes.
I also want to point out the sysvinit scripts are broken, not the
logger(1), but getting them corrected is practically impossible.
Assuming sysvinit script are further developed by various teams and
distributions who maintain them they should use --socket-error=on in
future, and write scripts that pass without noise. Meanwhile trying to
be clever when to silence errors seems like a reasonable thing to do.
--->8----
From: Sami Kerola <kerolasa@iki.fi>
Date: Sat, 14 Feb 2015 19:05:55 +0000
Subject: [PATCH] logger: add --socket-errors compatibility option
Now when logger(1) has stopped using openlog() for Unix sockets, in
commit mentioned in reference, the lack of /dev/log detected will report
error accordingly. According to Gabriele Balducci this makes sysvinit
style boot scripts to print a lot of errors. So make the logger to
detect whether it should be in compatibility mode, and not report errors
if logging device is missing. That imitates behavior of glibc openlog().
To allow full control to users the /dev/log error messages can be forced
to on or off. The automatic error messaging is explained in manual page.
Reference: 1d57503378
Reported-by: Gabriele Balducci <balducci@units.it>
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
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 message argument is not an option and should not be listed among
those. Describe the optional argument of --rfc5424 better. Use the
= and no space for optional option arguments. Don't italicize words
unnecessarily. Use bold for literal things. And sort the options
alphabetically (apart from -V and -h).
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
As per the convention shown in Documentation/howto-man-page.txt.
Also make a few other tiny adjustments along the way.
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
The fact that 'syslog tcp/514' does not exist in RFS's, which has lead
to 'syslog-conn 601/tcp' be used in place could be a suprice and should
be told in manual.
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
Michael Kerrisk (man-pages)
Bjarni Ingi Gislason
Karel Zak
Sébastien Helleu
Sebastian Rasmussen
Mike Frysinger
Benno Schulenberg
Michal Schmidt
Alex Bligh
Rainer Gerhards
Sami Kerola
J William Piggott
Ville Skyttä