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 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2014 Lennart Poettering
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id=
"systemd-escape"
28 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
31 <title>systemd-escape
</title>
32 <productname>systemd
</productname>
36 <contrib>Developer
</contrib>
37 <firstname>Lennart
</firstname>
38 <surname>Poettering
</surname>
39 <email>lennart@poettering.net
</email>
45 <refentrytitle>systemd-escape
</refentrytitle>
46 <manvolnum>1</manvolnum>
50 <refname>systemd-escape
</refname>
51 <refpurpose>Escape strings for usage in system unit names
</refpurpose>
56 <command>systemd-escape
</command>
57 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
58 <arg choice=
"opt" rep=
"repeat">STRING
</arg>
63 <title>Description
</title>
65 <para><command>systemd-escape
</command> may be used to escape
66 strings for inclusion in systemd unit names. The command may be
67 used to escape and to undo escaping of strings.
</para>
69 <para>The command takes any number of strings on the command line,
70 and will process them individually, one after the other. It will
71 output them separated by spaces to stdout.
</para>
73 <para>By default this command will escape the strings passed,
74 unless
<option>--unescape
</option> is passed which results in the
75 inverse operation being applied. If
<option>--mangle
</option> a
76 special mode of escaping is applied instead, which assumes a
77 string to be already escaped but will escape everything that
78 appears obviously non-escaped.
</para>
82 <title>Options
</title>
84 <para>The following options are understood:
</para>
88 <term><option>--suffix=
</option></term>
90 <listitem><para>Appends the specified unit type suffix to the
91 escaped string. Takes one of the unit types supported by
92 systemd, such as
<literal>.service
</literal> or
93 <literal>.mount
</literal>. May not be used in conjunction with
94 <option>--template=
</option>,
<option>--unescape
</option> or
95 <option>--mangle
</option>.
</para></listitem>
99 <term><option>--template=
</option></term>
101 <listitem><para>Inserts the escaped strings in a unit name
102 template. Takes a unit name template such as
103 <filename>foobar@.service
</filename> May not be used in
104 conjunction with
<option>--suffix=
</option>,
105 <option>--unescape
</option> or
106 <option>--mangle
</option>.
</para></listitem>
110 <term><option>--path
</option></term>
111 <term><option>-p
</option></term>
113 <listitem><para>When escaping or unescaping a string, assume
114 it refers to a file system path. This enables special
115 processing of the initial
<literal>/
</literal> of the
116 path.
</para></listitem>
120 <term><option>--unescape
</option></term>
122 <listitem><para>Instead of escaping the specified strings,
123 undo the escaping, reversing the operation. May not be used in
124 conjunction with
<option>--suffix=
</option>,
125 <option>--template=
</option> or
126 <option>--mangle
</option>.
</para></listitem>
130 <term><option>--mangle
</option></term>
132 <listitem><para>Like
<option>--escape
</option>, but only
133 escape characters that are obviously not escaped yet, and
134 possibly automatically append an appropriate unit type suffix
135 to the string. May not be used in conjunction with
136 <option>--suffix=
</option>,
<option>--template=
</option> or
137 <option>--unescape
</option>.
</para></listitem>
140 <xi:include href=
"standard-options.xml" xpointer=
"help" />
141 <xi:include href=
"standard-options.xml" xpointer=
"version" />
147 <title>Examples
</title>
149 <para>Escape a single string:
</para>
150 <programlisting>$ systemd-escape 'Hallöchen, Meister'
151 Hall\xc3\xb6chen\x2c\x20Meister
</programlisting>
153 <para>To undo escaping on a single string:
</para>
154 <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
155 Hallöchen, Meister
</programlisting>
157 <para>To generate the mount unit for a path:
</para>
158 <programlisting>$ systemd-escape -p --suffix=mount
"/tmp//waldi/foobar/"
159 tmp-waldi-foobar.mount
</programlisting>
161 <para>To generate instance names of three strings
</para>
162 <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container
1' 'containerb' 'container/III'
163 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service
</programlisting>
167 <title>Exit status
</title>
169 <para>On success,
0 is returned, a non-zero failure code
174 <title>See Also
</title>
176 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>