man/systemd-escape.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2014 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-escape"
  25           xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27         <refentryinfo>
  28                 <title>systemd-escape</title>
  29                 <productname>systemd</productname>
  30
  31                 <authorgroup>
  32                         <author>
  33                                 <contrib>Developer</contrib>
  34                                 <firstname>Lennart</firstname>
  35                                 <surname>Poettering</surname>
  36                                 <email>lennart@poettering.net</email>
  37                         </author>
  38                 </authorgroup>
  39         </refentryinfo>
  40
  41         <refmeta>
  42                 <refentrytitle>systemd-escape</refentrytitle>
  43                 <manvolnum>1</manvolnum>
  44         </refmeta>
  45
  46         <refnamediv>
  47                 <refname>systemd-escape</refname>
  48                 <refpurpose>Escape strings for usage in system unit names</refpurpose>
  49         </refnamediv>
  50
  51         <refsynopsisdiv>
  52                 <cmdsynopsis>
  53                         <command>systemd-escape <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">STRING</arg></command>
  54                 </cmdsynopsis>
  55         </refsynopsisdiv>
  56
  57         <refsect1>
  58                 <title>Description</title>
  59
  60                 <para><command>systemd-escape</command> may be used to
  61                 escape strings for inclusion in systemd unit
  62                 names. The command may be used to escape and to undo
  63                 escaping of strings.</para>
  64
  65                 <para>The command takes any number of strings on the
  66                 command line, and will process them individually, one
  67                 after the other. It will output them separated by
  68                 spaces to stdout.</para>
  69
  70                 <para>By default this command will escape the strings
  71                 passed, unless <option>--unescape</option> is passed
  72                 which results in the inverse operation being
  73                 applied. If <option>--mangle</option> a special mode
  74                 of escaping is applied instead, which assumes a string
  75                 to be already escaped but will escape everything that
  76                 appears obviously non-escaped.</para>
  77         </refsect1>
  78
  79         <refsect1>
  80                 <title>Options</title>
  81
  82                 <para>The following options are understood:</para>
  83
  84                 <variablelist>
  85                         <varlistentry>
  86                                 <term><option>--suffix=</option></term>
  87
  88                                 <listitem><para>Appends the specified
  89                                 unit type suffix to the escaped
  90                                 string. Takes one of the unit types
  91                                 supported by systemd, such as
  92                                 <literal>.service</literal> or
  93                                 <literal>.mount</literal>. May not be
  94                                 used in conjunction with
  95                                 <option>--template=</option>,
  96                                 <option>--unescape</option> or
  97                                 <option>--mangle</option>.</para></listitem>
  98                         </varlistentry>
  99
 100                         <varlistentry>
 101                                 <term><option>--template=</option></term>
 102
 103                                 <listitem><para>Inserts the escaped
 104                                 strings in a unit name template. Takes
 105                                 a unit name template such as
 106                                 <filename>foobar@.service</filename>
 107                                 May not be used in conjunction with
 108                                 <option>--suffix=</option>,
 109                                 <option>--unescape</option> or
 110                                 <option>--mangle</option>.</para></listitem>
 111                         </varlistentry>
 112
 113                         <varlistentry>
 114                                 <term><option>--path</option></term>
 115                                 <term><option>-p</option></term>
 116
 117                                 <listitem><para>When escaping or
 118                                 unescaping a string, assume it refers
 119                                 to a file system path. This enables
 120                                 special processing of the initial
 121                                 <literal>/</literal> of the
 122                                 path.</para></listitem>
 123                         </varlistentry>
 124
 125                         <varlistentry>
 126                                 <term><option>--unescape</option></term>
 127
 128                                 <listitem><para>Instead of escaping
 129                                 the specified strings, undo the
 130                                 escaping, reversing the operation. May
 131                                 not be used in conjunction with
 132                                 <option>--suffix=</option>,
 133                                 <option>--template=</option> or
 134                                 <option>--mangle</option>.</para></listitem>
 135                         </varlistentry>
 136
 137                         <varlistentry>
 138                                 <term><option>--mangle</option></term>
 139
 140                                 <listitem><para>Like
 141                                 <option>--escape</option>, but only
 142                                 escape characters that are obviously
 143                                 not escaped yet, and possibly
 144                                 automatically append an appropriate
 145                                 unit type suffix to the string. May
 146                                 not be used in conjunction with
 147                                 <option>--suffix=</option>,
 148                                 <option>--template=</option> or
 149                                 <option>--unescape</option>.</para></listitem>
 150                         </varlistentry>
 151
 152                         <xi:include href="standard-options.xml" xpointer="help" />
 153                         <xi:include href="standard-options.xml" xpointer="version" />
 154                 </variablelist>
 155
 156         </refsect1>
 157
 158         <refsect1>
 159                 <title>Examples</title>
 160
 161                 <para>Escape a single string:</para>
 162                 <programlisting>$ systemd-escape 'Hallöchen, Meister'
 163 Hall\xc3\xb6chen\x2c\x20Meister</programlisting>
 164
 165                 <para>To undo escaping on a single string:</para>
 166                 <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
 167 Hallöchen, Meister</programlisting>
 168
 169                 <para>To generate the mount unit for a path:</para>
 170                 <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
 171 tmp-waldi-foobar.mount</programlisting>
 172
 173                 <para>To generate instance names of three strings</para>
 174                 <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
 175 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
 176         </refsect1>
 177
 178         <refsect1>
 179                 <title>Exit status</title>
 180
 181                 <para>On success, 0 is returned, a non-zero failure
 182                 code otherwise.</para>
 183         </refsect1>
 184
 185         <refsect1>
 186                 <title>See Also</title>
 187                 <para>
 188                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 189                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 190                 </para>
 191         </refsect1>
 192
 193 </refentry>