| 1 |
'\" t |
| 2 |
.TH "ORG\&.FREEDESKTOP\&.LOCALE1" "5" "" "systemd 261~rc3" "org.freedesktop.locale1" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
org.freedesktop.locale1 \- The D\-Bus interface of systemd\-localed |
| 24 |
.SH "INTRODUCTION" |
| 25 |
.PP |
| 26 |
\fBsystemd-localed.service\fR(8) |
| 27 |
is a system service that can be used to control the system locale and keyboard mapping from user programs\&. This page describes the D\-Bus interface\&. |
| 28 |
.SH "THE D\-BUS API" |
| 29 |
.PP |
| 30 |
The service exposes the following interfaces on the bus: |
| 31 |
.sp |
| 32 |
.if n \{\ |
| 33 |
.RS 4 |
| 34 |
.\} |
| 35 |
.nf |
| 36 |
node /org/freedesktop/locale1 { |
| 37 |
interface org\&.freedesktop\&.locale1 { |
| 38 |
methods: |
| 39 |
SetLocale(in as locale, |
| 40 |
in b interactive); |
| 41 |
SetVConsoleKeyboard(in s keymap, |
| 42 |
in s keymap_toggle, |
| 43 |
in b convert, |
| 44 |
in b interactive); |
| 45 |
SetX11Keyboard(in s layout, |
| 46 |
in s model, |
| 47 |
in s variant, |
| 48 |
in s options, |
| 49 |
in b convert, |
| 50 |
in b interactive); |
| 51 |
properties: |
| 52 |
readonly as Locale = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; |
| 53 |
readonly s X11Layout = \*(Aq\&.\&.\&.\*(Aq; |
| 54 |
readonly s X11Model = \*(Aq\&.\&.\&.\*(Aq; |
| 55 |
readonly s X11Variant = \*(Aq\&.\&.\&.\*(Aq; |
| 56 |
readonly s X11Options = \*(Aq\&.\&.\&.\*(Aq; |
| 57 |
readonly s VConsoleKeymap = \*(Aq\&.\&.\&.\*(Aq; |
| 58 |
readonly s VConsoleKeymapToggle = \*(Aq\&.\&.\&.\*(Aq; |
| 59 |
}; |
| 60 |
interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; |
| 61 |
interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; |
| 62 |
interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; |
| 63 |
}; |
| 64 |
.fi |
| 65 |
.if n \{\ |
| 66 |
.RE |
| 67 |
.\} |
| 68 |
|
| 69 |
|
| 70 |
|
| 71 |
|
| 72 |
|
| 73 |
|
| 74 |
|
| 75 |
|
| 76 |
|
| 77 |
|
| 78 |
|
| 79 |
.SS "Methods" |
| 80 |
.PP |
| 81 |
If you set a new system locale all old system locale settings will be dropped and the new settings will be saved to disk\&. The locale will also be passed to the system manager, and subsequently started daemons will inherit the new system locale\&. Note that already running daemons will not learn about the new value\&. |
| 82 |
.PP |
| 83 |
The |
| 84 |
\fBSetVConsoleKeyboard()\fR |
| 85 |
method may be used to set the key mapping for the virtual console\&. Similarly, |
| 86 |
\fBSetX11Keyboard()\fR |
| 87 |
may be used to set the default key mapping of any X11 servers\&. |
| 88 |
.PP |
| 89 |
Note that |
| 90 |
\fBSetVConsoleKeyboard()\fR |
| 91 |
instantly applies the new key mapping to the console, while |
| 92 |
\fBSetX11Keyboard()\fR |
| 93 |
simply sets a default that may be used by later sessions\&. |
| 94 |
.PP |
| 95 |
The boolean argument |
| 96 |
\fIconvert\fR |
| 97 |
may be set to optionally convert the console keyboard configuration to X11 keyboard mappings and vice versa\&. If true and |
| 98 |
\fBSetVConsoleKeyboard()\fR |
| 99 |
is used, the nearest X11 keyboard setting for the chosen console setting is set\&. If true and |
| 100 |
\fBSetX11Keyboard()\fR |
| 101 |
is used, the nearest console keyboard setting for the chosen X11 setting is set\&. Hence, it is usually sufficient to call only one of the two functions\&. |
| 102 |
.PP |
| 103 |
For graphical UIs that need to set the system keyboard mapping simply invoke |
| 104 |
\fBSetX11Keyboard()\fR, set |
| 105 |
\fIconvert=true\fR |
| 106 |
and ignore |
| 107 |
\fBSetVConsoleKeyboard()\fR\&. |
| 108 |
.PP |
| 109 |
Use the empty string for the keymap parameters you wish not to set\&. |
| 110 |
.PP |
| 111 |
The |
| 112 |
\fIinteractive\fR |
| 113 |
boolean parameters can be used to control whether |
| 114 |
\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2 |
| 115 |
should interactively ask the user for authentication credentials if required\&. |
| 116 |
.SS "Signals" |
| 117 |
.PP |
| 118 |
Whenever the system locale or keymap is changed via the daemon, |
| 119 |
\fBPropertyChanged\fR |
| 120 |
signals are sent out to clients which have subscribed\&. |
| 121 |
.SS "Properties" |
| 122 |
.PP |
| 123 |
The system locale is shown in the |
| 124 |
\fILocale\fR |
| 125 |
property\&. It is an array containing environment\-variable\-assignment\-like strings\&. The following strings are known: |
| 126 |
\fILANG=\fR, |
| 127 |
\fILC_CTYPE=\fR, |
| 128 |
\fILC_NUMERIC=\fR, |
| 129 |
\fILC_TIME=\fR, |
| 130 |
\fILC_COLLATE=\fR, |
| 131 |
\fILC_MONETARY=\fR, |
| 132 |
\fILC_MESSAGES=\fR, |
| 133 |
\fILC_PAPER=\fR, |
| 134 |
\fILC_NAME=\fR, |
| 135 |
\fILC_ADDRESS=\fR, |
| 136 |
\fILC_TELEPHONE=\fR, |
| 137 |
\fILC_MEASUREMENT=\fR, |
| 138 |
\fILC_IDENTIFICATION=\fR\&. |
| 139 |
.PP |
| 140 |
The |
| 141 |
\fIX11Layout\fR, |
| 142 |
\fIX11Model\fR, |
| 143 |
\fIX11Variant\fR, and |
| 144 |
\fIX11Options\fR |
| 145 |
properties show values configurable with |
| 146 |
\fBSetX11Keyboard()\fR |
| 147 |
described above (or |
| 148 |
\fBSetVConsoleKeyboard()\fR |
| 149 |
with |
| 150 |
\fIconvert=true\fR)\&. The |
| 151 |
\fIVConsoleKeymap\fR |
| 152 |
and |
| 153 |
\fIVConsoleKeymapToggle\fR |
| 154 |
properties show values configurable with |
| 155 |
\fBSetVConsoleKeyboard()\fR |
| 156 |
(or |
| 157 |
\fBSetX11Keyboard()\fR |
| 158 |
with |
| 159 |
\fIconvert=true\fR)\&. |
| 160 |
.SS "Security" |
| 161 |
.PP |
| 162 |
Changing the system locale or keymap using this interface is authenticated via polkit\&. The polkit action for |
| 163 |
\fBSetLocale()\fR |
| 164 |
is |
| 165 |
\fBorg\&.freedesktop\&.locale1\&.set\-locale\fR\&. The polkit action for |
| 166 |
\fBSetX11Keyboard()\fR |
| 167 |
and |
| 168 |
\fBSetVConsoleKeyboard()\fR |
| 169 |
is |
| 170 |
\fBorg\&.freedesktop\&.locale1\&.set\-keyboard\fR\&. |
| 171 |
.SH "EXAMPLES" |
| 172 |
.PP |
| 173 |
\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.locale1 on the bus\fR |
| 174 |
.sp |
| 175 |
.if n \{\ |
| 176 |
.RS 4 |
| 177 |
.\} |
| 178 |
.nf |
| 179 |
$ gdbus introspect \-\-system \e |
| 180 |
\-\-dest org\&.freedesktop\&.locale1 \e |
| 181 |
\-\-object\-path /org/freedesktop/locale1 |
| 182 |
.fi |
| 183 |
.if n \{\ |
| 184 |
.RE |
| 185 |
.\} |
| 186 |
.SH "VERSIONING" |
| 187 |
.PP |
| 188 |
These D\-Bus interfaces follow |
| 189 |
\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. |
| 190 |
.SH "SEE ALSO" |
| 191 |
.PP |
| 192 |
\fBsystemd\fR(1), \fBsystemd-localed.service\fR(8), \fBlocalectl\fR(1) |
| 193 |
.SH "NOTES" |
| 194 |
.IP " 1." 4 |
| 195 |
polkit |
| 196 |
.RS 4 |
| 197 |
\%https://www.freedesktop.org/software/polkit/docs/latest/ |
| 198 |
.RE |
| 199 |
.IP " 2." 4 |
| 200 |
the usual interface versioning guidelines |
| 201 |
.RS 4 |
| 202 |
\%https://0pointer.de/blog/projects/versioning-dbus.html |
| 203 |
.RE |