summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormulkieran <mulkieran@users.noreply.github.com>2016-07-19 23:15:22 -0400
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2016-07-19 23:15:22 -0400
commit13317a22e5cf8f7c458616a971e60e84255bc364 (patch)
tree0cc4b74c38142526a3b7396d7dddb5e97205be34
parentdfc6109fcd7cd8987ca77326eef25c0deb25abd9 (diff)
man: revise entry about specifying a file path (#3739)
* Specifying a device node has an effect much larger than a simple shortcut for a field/value match, so the original sentence is no longer a good way to start the paragraph. * Specifying a device node causes matches to be generated for all ancestor devices of the device specified, not just its parents. * Indicates that the path must be absolute, but that it may be a link. * Eliminates a few typos.
-rw-r--r--man/journalctl.xml32
1 files changed, 20 insertions, 12 deletions
diff --git a/man/journalctl.xml b/man/journalctl.xml
index 29239c6315..e77621d7b3 100644
--- a/man/journalctl.xml
+++ b/man/journalctl.xml
@@ -87,18 +87,26 @@
causes all matches before and after to be combined in a
disjunction (i.e. logical OR).</para>
- <para>As shortcuts for a few types of field/value matches, file
- paths may be specified. If a file path refers to an executable
- file, this is equivalent to an <literal>_EXE=</literal> match
- for the canonicalized binary path. Similarly, if a path refers
- to a device node then match is added for the kernel name of the
- device (<literal>_KERNEL_DEVICE=</literal>). Also, matches for the
- kernel names of all the parent devices are added automatically.
- Device node paths are not stable across reboots, therefore match
- for the current boot id (<literal>_BOOT_ID=</literal>) is
- always added as well. Note that only the log entries for
- the existing device nodes maybe queried by providing path to
- the device node.</para>
+ <para>It is also possible to filter the entries by specifying an
+ absolute file path as an argument. The file path may be a file or
+ a symbolic link and the file must exist at the time of the query. If a
+ file path refers to an executable binary, an <literal>_EXE=</literal>
+ match for the canonicalized binary path is added to the query. If a
+ file path refers to an executable script, a <literal>_COMM=</literal>
+ match for the script name is added to the query. If a file path
+ refers to a device node, <literal>_KERNEL_DEVICE=</literal> matches for
+ the kernel name of the device and for each of its ancestor devices is
+ added to the query. Symbolic links are dereferenced, kernel names are
+ synthesized, and parent devices are identified from the environment at
+ the time of the query. In general, a device node is the best proxy for
+ an actual device, as log entries do not usually contain fields that
+ identify an actual device. For the resulting log entries to be correct
+ for the actual device, the relevant parts of the environment at the time
+ the entry was logged, in particular the actual device corresponding to
+ the device node, must have been the same as those at the time of the
+ query. Because device nodes generally change their corresponding devices
+ across reboots, specifying a device node path causes the resulting
+ entries to be restricted to those from the current boot.</para>
<para>Additional constraints may be added using options
<option>--boot</option>, <option>--unit=</option>, etc., to