chiark / gitweb /
build: check for build/link flags harder
[elogind.git] / man / localectl.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 2012 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="localectl" conditional='ENABLE_LOCALED'>
25
26         <refentryinfo>
27                 <title>localectl</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>localectl</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>localectl</refname>
47                 <refpurpose>Control the system locale and keyboard layout settings</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>localectl</command>
53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
54                         <arg choice="req">COMMAND</arg>
55                 </cmdsynopsis>
56         </refsynopsisdiv>
57
58         <refsect1>
59                 <title>Description</title>
60
61                 <para><command>localectl</command> may be used to
62                 query and change the system locale and keyboard layout
63                 settings.</para>
64
65                 <para>The system locale controls the language settings
66                 of system services and of the UI before the user logs
67                 in, such as the display manager, as well as the
68                 default for users after login.</para>
69
70                 <para>The keyboard settings control the keyboard
71                 layout used on the text console and of the graphical
72                 UI before the user logs in, such as the display
73                 manager, as well as the default for users after
74                 login.</para>
75         </refsect1>
76
77         <refsect1>
78                 <title>Options</title>
79
80                 <para>The following options are understood:</para>
81
82                 <variablelist>
83                         <varlistentry>
84                                 <term><option>-h</option></term>
85                                 <term><option>--help</option></term>
86
87                                 <listitem><para>Prints a short help
88                                 text and exits.</para></listitem>
89                         </varlistentry>
90
91                         <varlistentry>
92                                 <term><option>--version</option></term>
93
94                                 <listitem><para>Prints a short version
95                                 string and exits.</para></listitem>
96                         </varlistentry>
97
98                         <varlistentry>
99                                 <term><option>--no-pager</option></term>
100
101                                 <listitem><para>Do not pipe output into a
102                                 pager.</para></listitem>
103                         </varlistentry>
104
105                         <varlistentry>
106                                 <term><option>--no-ask-password</option></term>
107
108                                 <listitem><para>Do not query the user
109                                 for authentication for privileged
110                                 operations.</para></listitem>
111                         </varlistentry>
112
113                         <varlistentry>
114                                 <term><option>-P</option></term>
115                                 <term><option>--privileged</option></term>
116
117                                 <listitem><para>Acquire privileges via PolicyKit
118                                 before executing the operation.</para></listitem>
119                         </varlistentry>
120
121                         <varlistentry>
122                                 <term><option>-H</option></term>
123                                 <term><option>--host</option></term>
124
125                                 <listitem><para>Execute the operation
126                                 remotely. Specify a hostname, or
127                                 username and hostname separated by <literal>@</literal>,
128                                 to connect to. This will use SSH to
129                                 talk to a remote
130                                 system.</para></listitem>
131                         </varlistentry>
132
133                         <varlistentry>
134                                 <term><option>--no-convert</option></term>
135
136                                 <listitem><para>If
137                                 <command>set-keymap</command> or
138                                 <command>set-x11-keymap</command> is
139                                 invoked and this option is passed, then
140                                 the keymap will not be converted from
141                                 the console to X11, or X11 to console,
142                                 respectively.</para></listitem>
143                         </varlistentry>
144                 </variablelist>
145
146                 <para>The following commands are understood:</para>
147
148                 <variablelist>
149                         <varlistentry>
150                                 <term><command>status</command></term>
151
152                                 <listitem><para>Show current settings
153                                 of the system locale and keyboard
154                                 mapping.</para></listitem>
155                         </varlistentry>
156
157                         <varlistentry>
158                                 <term><command>set-locale LOCALE...</command></term>
159
160                                 <listitem><para>Set the system
161                                 locale. This takes one or more
162                                 assignments such as "LANG=de_DE.utf8",
163                                 "LC_MESSAGES=en_GB.utf8", and so
164                                 on. See
165                                 <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>
166                                 for details on the available settings
167                                 and their meanings. Use
168                                 <command>list-locales</command> for a
169                                 list of available locales (see below).
170                                 </para></listitem>
171                         </varlistentry>
172
173                         <varlistentry>
174                                 <term><command>list-locales</command></term>
175
176                                 <listitem><para>List available locales
177                                 useful for configuration with
178                                 <command>set-locale</command>.</para></listitem>
179                         </varlistentry>
180
181                         <varlistentry>
182                                 <term><command>set-keymap MAP [TOGGLEMAP]</command></term>
183
184                                 <listitem><para>Set the system
185                                 keyboard mapping for the console. This
186                                 takes a keyboard mapping name (such as
187                                 "de" or "us"), and possibly a second
188                                 one to define a toggle keyboard
189                                 mapping. Unless
190                                 <option>--no-convert</option> is
191                                 passed, the selected setting is also
192                                 applied to the default keyboard
193                                 mapping of X11, after converting it to
194                                 the closest matching X11 keyboard
195                                 mapping. Use
196                                 <command>list-keymaps</command> for a
197                                 list of available keyboard mappings
198                                 (see below).</para></listitem>
199                         </varlistentry>
200
201                         <varlistentry>
202                                 <term><command>list-keymaps</command></term>
203
204                                 <listitem><para>List available
205                                 keyboard mappings for the console,
206                                 useful for configuration with
207                                 <command>set-keymap</command>.</para></listitem>
208                         </varlistentry>
209
210                         <varlistentry>
211                                 <term><command>set-x11-keymap LAYOUT [MODEL] [VARIANT] [OPTIONS]</command></term>
212
213                                 <listitem><para>Set the system default
214                                 keyboard mapping for X11. This takes a
215                                 keyboard mapping name (such as "de" or
216                                 "us"), and possibly a model, variant
217                                 and options, see
218                                 <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>
219                                 for details. Unless
220                                 <option>--no-convert</option> is
221                                 passed, the selected setting is also
222                                 applied to the system console keyboard
223                                 mapping, after converting it to the
224                                 closest matching console keyboard
225                                 mapping.</para></listitem>
226                         </varlistentry>
227
228                         <varlistentry>
229                                 <term><command>list-x11-keymap-models</command></term>
230                                 <term><command>list-x11-keymap-layouts</command></term>
231                                 <term><command>list-x11-keymap-variants [LAYOUT]</command></term>
232                                 <term><command>list-x11-keymap-options</command></term>
233
234                                 <listitem><para>List available X11
235                                 keymap models, layouts, variants and
236                                 options, useful for configuration with
237                                 <command>set-keymap</command>. The
238                                 command
239                                 <command>list-x11-keymap-variants</command>
240                                 optionally takes a layout parameter to
241                                 limit the output to the variants
242                                 suitable for the specific
243                                 layout.</para></listitem>
244                         </varlistentry>
245                 </variablelist>
246
247         </refsect1>
248
249         <refsect1>
250                 <title>Exit status</title>
251
252                 <para>On success, 0 is returned, a non-zero failure
253                 code otherwise.</para>
254         </refsect1>
255
256         <refsect1>
257                 <title>Environment</title>
258
259                 <variablelist class='environment-variables'>
260                         <varlistentry>
261                                 <term><varname>$SYSTEMD_PAGER</varname></term>
262                                 <listitem><para>Pager to use when
263                                 <option>--no-pager</option> is not given;
264                                 overrides <varname>$PAGER</varname>.  Setting
265                                 this to an empty string or the value
266                                 <literal>cat</literal> is equivalent to passing
267                                 <option>--no-pager</option>.</para></listitem>
268                         </varlistentry>
269                 </variablelist>
270         </refsect1>
271
272         <refsect1>
273                 <title>See Also</title>
274                 <para>
275                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
276                         <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
277                         <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
278                         <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
279                         <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
280                         <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
281                         <ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html">
282                           The XKB Configuration Guide
283                         </ulink>,
284                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
285                         <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
286                 </para>
287         </refsect1>
288
289 </refentry>