chiark / gitweb /
hashmap: return more information from resize_buckets()
[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 <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>