escape: add --instance option

Suggested by @keszybz in #4522.

man/systemd-escape.xml

@@ -80,7 +80,8 @@
         <option>--unescape</option>, expects instantiated unit names
         for this template and extracts and unescapes just the instance
         part. May not be used in conjunction with
-        <option>--suffix=</option> or
+        <option>--suffix=</option>,
+        <option>--instance</option> or
         <option>--mangle</option>.</para></listitem>
       </varlistentry>
 
@@ -118,6 +119,19 @@
         <option>--unescape</option>.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--instance</option></term>
+
+        <listitem><para>With <option>--unescape</option>, unescape
+        and print only the instance part of an instantiated unit name
+        template. Results in an error for an uninstantiated template
+        like <filename>ssh@.service</filename> or a non-template name
+        like <filename>ssh.service</filename>.
+        Must be used in conjunction with <option>--unescape</option>
+        and may not be used in conjunction with
+        <option>--template</option>.</para></listitem>
+      </varlistentry>
+
       <xi:include href="standard-options.xml" xpointer="help" />
       <xi:include href="standard-options.xml" xpointer="version" />
     </variablelist>
@@ -144,6 +158,10 @@ tmp-waldi-foobar.mount</programlisting>
 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
 
     <para>To extract the instance part of an instantiated unit:</para>
+    <programlisting>$ systemd-escape -u --instance 'systemd-nspawn@My\x20Container\x201.service'
+My Container 1</programlisting>
+
+    <para>To extract the instance part of an instance of a particular template:</para>
     <programlisting>$ systemd-escape -u --template=systemd-nspawn@.service 'systemd-nspawn@My\x20Container\x201.service'
 My Container 1</programlisting>
   </refsect1>

src/escape/escape.c

@@ -21,6 +21,7 @@ static enum {
 static const char *arg_suffix = NULL;
 static const char *arg_template = NULL;
 static bool arg_path = false;
+static bool arg_instance = false;
 
 static void help(void) {
         printf("%s [OPTIONS...] [NAME...]\n\n"
@@ -29,6 +30,7 @@ static void help(void) {
                "     --version            Show package version\n"
                "     --suffix=SUFFIX      Unit suffix to append to escaped strings\n"
                "     --template=TEMPLATE  Insert strings as instance into template\n"
+               "     --instance           With --unescape, show just the instance part\n"
                "  -u --unescape           Unescape strings\n"
                "  -m --mangle             Mangle strings\n"
                "  -p --path               When escaping/unescaping assume the string is a path\n"
@@ -51,6 +53,7 @@ static int parse_argv(int argc, char *argv[]) {
                 { "unescape",  no_argument,       NULL, 'u'           },
                 { "mangle",    no_argument,       NULL, 'm'           },
                 { "path",      no_argument,       NULL, 'p'           },
+                { "instance",  no_argument,       NULL, 'i'           },
                 {}
         };
 
@@ -102,6 +105,10 @@ static int parse_argv(int argc, char *argv[]) {
                         arg_path = true;
                         break;
 
+                case 'i':
+                        arg_instance = true;
+                        break;
+
                 case '?':
                         return -EINVAL;
 
@@ -134,6 +141,16 @@ static int parse_argv(int argc, char *argv[]) {
                 return -EINVAL;
         }
 
+        if (arg_instance && arg_action != ACTION_UNESCAPE) {
+                log_error("--instance must be used in conjunction with --unescape.");
+                return -EINVAL;
+        }
+
+        if (arg_instance && arg_template) {
+                log_error("--instance may not be combined with --template.");
+                return -EINVAL;
+        }
+
         return 1;
 }
 
@@ -197,7 +214,7 @@ int main(int argc, char *argv[]) {
                 case ACTION_UNESCAPE: {
                         _cleanup_free_ char *name = NULL;
 
-                        if (arg_template) {
+                        if (arg_template || arg_instance) {
                                 _cleanup_free_ char *template = NULL;
 
                                 r = unit_name_to_instance(*i, &name);
@@ -215,7 +232,7 @@ int main(int argc, char *argv[]) {
                                         log_error_errno(r, "Failed to extract template: %m");
                                         goto finish;
                                 }
-                                if (!streq(arg_template, template)) {
+                                if (arg_template && !streq(arg_template, template)) {
                                         log_error("Unit %s template %s does not match specified template %s.", *i, template, arg_template);
                                         r = -EINVAL;
                                         goto finish;