summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2016-01-26 19:50:04 +0100
committerLennart Poettering <lennart@poettering.net>2016-01-27 02:21:28 +0100
commit1f00ededc7451933e23a95597804897b37fa88d6 (patch)
treeefbc9f8e7580c4a9abeba4d04521244ffa92fc1f
parent1b53f64b001d2a8acb398eb8d546ec4570c1f235 (diff)
man: document that unit file globbing only operates on primary unit names
See: #2397
-rw-r--r--man/systemctl.xml27
1 files changed, 12 insertions, 15 deletions
diff --git a/man/systemctl.xml b/man/systemctl.xml
index a55e06059a..7d98c73fe1 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -683,14 +683,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
<para>Start (activate) one or more units specified on the
command line.</para>
- <para>Note that glob patterns operate on a list of currently
- loaded units. Units which are not active and are not in a
- failed state usually are not loaded, and would not be
- matched by any pattern. In addition, in case of
- instantiated units, systemd is often unaware of the
- instance name until the instance has been started. Therefore,
- using glob patterns with <command>start</command>
- has limited usefulness.</para>
+ <para>Note that glob patterns operate on the set of primary names of currently loaded units. Units which
+ are not active and are not in a failed state usually are not loaded, and will not be matched by any
+ pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until
+ the instance has been started. Therefore, using glob patterns with <command>start</command> has limited
+ usefulness. Also, secondary alias names of units are not considered.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -1724,11 +1721,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
are equivalent to:
<programlisting># systemctl status dev-sda.device
# systemctl status home.mount</programlisting>
- In the second case, shell-style globs will be matched against
- currently loaded units; literal unit names, with or without
- a suffix, will be treated as in the first case. This means that
- literal unit names always refer to exactly one unit, but globs
- may match zero units and this is not considered an error.</para>
+ In the second case, shell-style globs will be matched against the primary names of all currently loaded units;
+ literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit
+ names always refer to exactly one unit, but globs may match zero units and this is not considered an
+ error.</para>
<para>Glob patterns use
<citerefentry project='man-pages'><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
@@ -1736,11 +1732,12 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
<literal>*</literal>, <literal>?</literal>,
<literal>[]</literal> may be used. See
<citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for more details. The patterns are matched against the names of
+ for more details. The patterns are matched against the primary names of
currently loaded units, and patterns which do not match anything
are silently skipped. For example:
<programlisting># systemctl stop sshd@*.service</programlisting>
- will stop all <filename>sshd@.service</filename> instances.
+ will stop all <filename>sshd@.service</filename> instances. Note that alias names of units, and units that aren't
+ loaded are not considered for glob expansion.
</para>
<para>For unit file commands, the specified