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">
6 This file is part of systemd.
8 Copyright 2014 Lennart Poettering
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.
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.
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/>.
24 <refentry id="systemd-escape"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>systemd-escape</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>systemd-escape</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>systemd-escape</refname>
48 <refpurpose>Escape strings for usage in system unit names</refpurpose>
53 <command>systemd-escape</command>
54 <arg choice="opt" rep="repeat">OPTIONS</arg>
55 <arg choice="opt" rep="repeat">STRING</arg>
60 <title>Description</title>
62 <para><command>systemd-escape</command> may be used to escape
63 strings for inclusion in systemd unit names. The command may be
64 used to escape and to undo escaping of strings.</para>
66 <para>The command takes any number of strings on the command line,
67 and will process them individually, one after the other. It will
68 output them separated by spaces to stdout.</para>
70 <para>By default this command will escape the strings passed,
71 unless <option>--unescape</option> is passed which results in the
72 inverse operation being applied. If <option>--mangle</option> a
73 special mode of escaping is applied instead, which assumes a
74 string to be already escaped but will escape everything that
75 appears obviously non-escaped.</para>
79 <title>Options</title>
81 <para>The following options are understood:</para>
85 <term><option>--suffix=</option></term>
87 <listitem><para>Appends the specified unit type suffix to the
88 escaped string. Takes one of the unit types supported by
89 systemd, such as <literal>.service</literal> or
90 <literal>.mount</literal>. May not be used in conjunction with
91 <option>--template=</option>, <option>--unescape</option> or
92 <option>--mangle</option>.</para></listitem>
96 <term><option>--template=</option></term>
98 <listitem><para>Inserts the escaped strings in a unit name
99 template. Takes a unit name template such as
100 <filename>foobar@.service</filename> May not be used in
101 conjunction with <option>--suffix=</option>,
102 <option>--unescape</option> or
103 <option>--mangle</option>.</para></listitem>
107 <term><option>--path</option></term>
108 <term><option>-p</option></term>
110 <listitem><para>When escaping or unescaping a string, assume
111 it refers to a file system path. This enables special
112 processing of the initial <literal>/</literal> of the
113 path.</para></listitem>
117 <term><option>--unescape</option></term>
119 <listitem><para>Instead of escaping the specified strings,
120 undo the escaping, reversing the operation. May not be used in
121 conjunction with <option>--suffix=</option>,
122 <option>--template=</option> or
123 <option>--mangle</option>.</para></listitem>
127 <term><option>--mangle</option></term>
129 <listitem><para>Like <option>--escape</option>, but only
130 escape characters that are obviously not escaped yet, and
131 possibly automatically append an appropriate unit type suffix
132 to the string. May not be used in conjunction with
133 <option>--suffix=</option>, <option>--template=</option> or
134 <option>--unescape</option>.</para></listitem>
137 <xi:include href="standard-options.xml" xpointer="help" />
138 <xi:include href="standard-options.xml" xpointer="version" />
144 <title>Examples</title>
146 <para>Escape a single string:</para>
147 <programlisting>$ systemd-escape 'Hallöchen, Meister'
148 Hall\xc3\xb6chen\x2c\x20Meister</programlisting>
150 <para>To undo escaping on a single string:</para>
151 <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
152 Hallöchen, Meister</programlisting>
154 <para>To generate the mount unit for a path:</para>
155 <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
156 tmp-waldi-foobar.mount</programlisting>
158 <para>To generate instance names of three strings</para>
159 <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
160 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
164 <title>Exit status</title>
166 <para>On success, 0 is returned, a non-zero failure code
171 <title>See Also</title>
173 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>