From 1f00ededc7451933e23a95597804897b37fa88d6 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 26 Jan 2016 19:50:04 +0100
Subject: man: document that unit file globbing only operates on primary unit
 names

See: #2397
---
 man/systemctl.xml | 27 ++++++++++++---------------
 1 file changed, 12 insertions(+), 15 deletions(-)

(limited to 'man/systemctl.xml')

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
-- 
cgit v1.2.3-54-g00ecf