chiark / gitweb /
update TODO
[elogind.git] / 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</command>
54       <arg choice="opt" rep="repeat">OPTIONS</arg>
55       <arg choice="opt" rep="repeat">STRING</arg>
56     </cmdsynopsis>
57   </refsynopsisdiv>
58
59   <refsect1>
60     <title>Description</title>
61
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>
65
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>
69
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>
76   </refsect1>
77
78   <refsect1>
79     <title>Options</title>
80
81     <para>The following options are understood:</para>
82
83     <variablelist>
84       <varlistentry>
85         <term><option>--suffix=</option></term>
86
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>
93       </varlistentry>
94
95       <varlistentry>
96         <term><option>--template=</option></term>
97
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>
104       </varlistentry>
105
106       <varlistentry>
107         <term><option>--path</option></term>
108         <term><option>-p</option></term>
109
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>
114       </varlistentry>
115
116       <varlistentry>
117         <term><option>--unescape</option></term>
118
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>
124       </varlistentry>
125
126       <varlistentry>
127         <term><option>--mangle</option></term>
128
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>
135       </varlistentry>
136
137       <xi:include href="standard-options.xml" xpointer="help" />
138       <xi:include href="standard-options.xml" xpointer="version" />
139     </variablelist>
140
141   </refsect1>
142
143   <refsect1>
144     <title>Examples</title>
145
146     <para>Escape a single string:</para>
147     <programlisting>$ systemd-escape 'Hallöchen, Meister'
148 Hall\xc3\xb6chen\x2c\x20Meister</programlisting>
149
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>
153
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>
157
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>
161   </refsect1>
162
163   <refsect1>
164     <title>Exit status</title>
165
166     <para>On success, 0 is returned, a non-zero failure code
167     otherwise.</para>
168   </refsect1>
169
170   <refsect1>
171     <title>See Also</title>
172     <para>
173       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
174       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
175     </para>
176   </refsect1>
177
178 </refentry>