]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/org.freedesktop.login1.xml
projects / thirdparty / systemd.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge pull request #32677 from keszybz/wording-fixes
[thirdparty/systemd.git] / man / org.freedesktop.login1.xml
CommitLineData
44fd44f1
ZJS		 1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
db9ecf05 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
44fd44f1
ZJS		 5
6<refentry id="org.freedesktop.login1" conditional='ENABLE_LOGIND'
7 xmlns:xi="http://www.w3.org/2001/XInclude">
8 <refentryinfo>
9 <title>org.freedesktop.login1</title>
10 <productname>systemd</productname>
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>org.freedesktop.login1</refentrytitle>
15 <manvolnum>5</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>org.freedesktop.login1</refname>
20 <refpurpose>The D-Bus interface of systemd-logind</refpurpose>
21 </refnamediv>
22
23 <refsect1>
24 <title>Introduction</title>
25
26 <para><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
ca264f7d 27 is a system service that keeps track of user logins and seats.</para>
44fd44f1
ZJS		 28
29 <para>The daemon provides both a C library interface as well as a D-Bus interface. The library interface
30 may be used to introspect and watch the state of user logins and seats. The bus interface provides the
ca264f7d 31 same functionality but in addition may also be used to make changes to the system state. For more information please
44fd44f1
ZJS		 32 consult <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
33 </para>
34 </refsect1>
35
36 <refsect1>
37 <title>The Manager Object</title>
38
39 <para>The service exposes the following interfaces on the Manager object on the bus:</para>
40
48f99d7c 41 <programlisting executable="systemd-logind" node="/org/freedesktop/login1" interface="org.freedesktop.login1.Manager">
44fd44f1
ZJS		 42node /org/freedesktop/login1 {
43 interface org.freedesktop.login1.Manager {
44 methods:
45 GetSession(in s session_id,
46 out o object_path);
47 GetSessionByPID(in u pid,
48 out o object_path);
49 GetUser(in u uid,
50 out o object_path);
51 GetUserByPID(in u pid,
52 out o object_path);
53 GetSeat(in s seat_id,
54 out o object_path);
4fb222c4 55 ListSessions(out a(susso) sessions);
b3cb952c 56 ListSessionsEx(out a(sussussbto) sessions);
4fb222c4
ZJS		 57 ListUsers(out a(uso) users);
58 ListSeats(out a(so) seats);
59 ListInhibitors(out a(ssssuu) inhibitors);
34b56848 60 @org.freedesktop.systemd1.Privileged("true")
44fd44f1
ZJS		 61 CreateSession(in u uid,
62 in u pid,
63 in s service,
64 in s type,
65 in s class,
66 in s desktop,
67 in s seat_id,
68 in u vtnr,
69 in s tty,
70 in s display,
71 in b remote,
72 in s remote_user,
73 in s remote_host,
74 in a(sv) properties,
75 out s session_id,
76 out o object_path,
77 out s runtime_path,
78 out h fifo_fd,
79 out u uid,
80 out s seat_id,
81 out u vtnr,
82 out b existing);
34b56848 83 @org.freedesktop.systemd1.Privileged("true")
76f2191d
MS		 84 CreateSessionWithPIDFD(in u uid,
85 in h pidfd,
86 in s service,
87 in s type,
88 in s class,
89 in s desktop,
90 in s seat_id,
91 in u vtnr,
92 in s tty,
93 in s display,
94 in b remote,
95 in s remote_user,
96 in s remote_host,
97 in t flags,
98 in a(sv) properties,
99 out s session_id,
100 out o object_path,
101 out s runtime_path,
102 out h fifo_fd,
103 out u uid,
104 out s seat_id,
105 out u vtnr,
106 out b existing);
107 @org.freedesktop.systemd1.Privileged("true")
44fd44f1
ZJS		 108 ReleaseSession(in s session_id);
109 ActivateSession(in s session_id);
110 ActivateSessionOnSeat(in s session_id,
111 in s seat_id);
112 LockSession(in s session_id);
113 UnlockSession(in s session_id);
114 LockSessions();
115 UnlockSessions();
116 KillSession(in s session_id,
117 in s who,
4fb222c4 118 in i signal_number);
44fd44f1 119 KillUser(in u uid,
4fb222c4 120 in i signal_number);
44fd44f1
ZJS		 121 TerminateSession(in s session_id);
122 TerminateUser(in u uid);
123 TerminateSeat(in s seat_id);
124 SetUserLinger(in u uid,
4fb222c4 125 in b enable,
44fd44f1
ZJS		 126 in b interactive);
127 AttachDevice(in s seat_id,
4fb222c4 128 in s sysfs_path,
44fd44f1
ZJS		 129 in b interactive);
130 FlushDevices(in b interactive);
131 PowerOff(in b interactive);
8885fed4 132 PowerOffWithFlags(in t flags);
44fd44f1 133 Reboot(in b interactive);
8885fed4 134 RebootWithFlags(in t flags);
4fb222c4 135 Halt(in b interactive);
8885fed4 136 HaltWithFlags(in t flags);
44fd44f1 137 Suspend(in b interactive);
8885fed4 138 SuspendWithFlags(in t flags);
44fd44f1 139 Hibernate(in b interactive);
8885fed4 140 HibernateWithFlags(in t flags);
44fd44f1 141 HybridSleep(in b interactive);
8885fed4 142 HybridSleepWithFlags(in t flags);
4fb222c4 143 SuspendThenHibernate(in b interactive);
8885fed4 144 SuspendThenHibernateWithFlags(in t flags);
cd4dd90b 145 Sleep(in t flags);
44fd44f1
ZJS		 146 CanPowerOff(out s result);
147 CanReboot(out s result);
4fb222c4 148 CanHalt(out s result);
44fd44f1
ZJS		 149 CanSuspend(out s result);
150 CanHibernate(out s result);
151 CanHybridSleep(out s result);
4fb222c4 152 CanSuspendThenHibernate(out s result);
cd4dd90b 153 CanSleep(out s result);
44fd44f1
ZJS		 154 ScheduleShutdown(in s type,
155 in t usec);
156 CancelScheduledShutdown(out b cancelled);
157 Inhibit(in s what,
158 in s who,
159 in s why,
160 in s mode,
161 out h pipe_fd);
4fb222c4
ZJS		 162 CanRebootParameter(out s result);
163 SetRebootParameter(in s parameter);
44fd44f1
ZJS		 164 CanRebootToFirmwareSetup(out s result);
165 SetRebootToFirmwareSetup(in b enable);
4fb222c4
ZJS		 166 CanRebootToBootLoaderMenu(out s result);
167 SetRebootToBootLoaderMenu(in t timeout);
168 CanRebootToBootLoaderEntry(out s result);
169 SetRebootToBootLoaderEntry(in s boot_loader_entry);
44fd44f1
ZJS		 170 SetWallMessage(in s wall_message,
171 in b enable);
172 signals:
173 SessionNew(s session_id,
174 o object_path);
175 SessionRemoved(s session_id,
176 o object_path);
177 UserNew(u uid,
178 o object_path);
179 UserRemoved(u uid,
180 o object_path);
181 SeatNew(s seat_id,
182 o object_path);
183 SeatRemoved(s seat_id,
184 o object_path);
185 PrepareForShutdown(b start);
e4aab5cf
LB		 186 PrepareForShutdownWithMetadata(b start,
187 a{sv} metadata);
44fd44f1
ZJS		 188 PrepareForSleep(b start);
189 properties:
4fb222c4
ZJS		 190 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
191 @org.freedesktop.systemd1.Privileged("true")
192 readwrite b EnableWallMessages = ...;
193 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
194 @org.freedesktop.systemd1.Privileged("true")
195 readwrite s WallMessage = '...';
196 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
197 readonly u NAutoVTs = ...;
198 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
199 readonly as KillOnlyUsers = ['...', ...];
200 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
201 readonly as KillExcludeUsers = ['...', ...];
202 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
203 readonly b KillUserProcesses = ...;
204 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
205 readonly s RebootParameter = '...';
206 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
207 readonly b RebootToFirmwareSetup = ...;
208 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
209 readonly t RebootToBootLoaderMenu = ...;
210 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
211 readonly s RebootToBootLoaderEntry = '...';
212 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
213 readonly as BootLoaderEntries = ['...', ...];
214 readonly b IdleHint = ...;
215 readonly t IdleSinceHint = ...;
216 readonly t IdleSinceHintMonotonic = ...;
217 readonly s BlockInhibited = '...';
218 readonly s DelayInhibited = '...';
219 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
220 readonly t InhibitDelayMaxUSec = ...;
221 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
222 readonly t UserStopDelayUSec = ...;
223 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
cd4dd90b
MY		 224 readonly as SleepOperation = ['...', ...];
225 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
4fb222c4
ZJS		 226 readonly s HandlePowerKey = '...';
227 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
c4db78fc
LP		 228 readonly s HandlePowerKeyLongPress = '...';
229 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
230 readonly s HandleRebootKey = '...';
231 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
232 readonly s HandleRebootKeyLongPress = '...';
233 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
4fb222c4
ZJS		 234 readonly s HandleSuspendKey = '...';
235 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
c4db78fc
LP		 236 readonly s HandleSuspendKeyLongPress = '...';
237 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
4fb222c4
ZJS		 238 readonly s HandleHibernateKey = '...';
239 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
c4db78fc
LP		 240 readonly s HandleHibernateKeyLongPress = '...';
241 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
4fb222c4
ZJS		 242 readonly s HandleLidSwitch = '...';
243 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
244 readonly s HandleLidSwitchExternalPower = '...';
245 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
246 readonly s HandleLidSwitchDocked = '...';
247 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
248 readonly t HoldoffTimeoutUSec = ...;
249 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
250 readonly s IdleAction = '...';
251 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
252 readonly t IdleActionUSec = ...;
253 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
254 readonly b PreparingForShutdown = ...;
255 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
256 readonly b PreparingForSleep = ...;
257 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
258 readonly (st) ScheduledShutdown = ...;
259 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
260 readonly b Docked = ...;
4fb222c4
ZJS		 261 readonly b LidClosed = ...;
262 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
263 readonly b OnExternalPower = ...;
264 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
265 readonly b RemoveIPC = ...;
266 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
267 readonly t RuntimeDirectorySize = ...;
268 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
cc1c85fb
TM		 269 readonly t RuntimeDirectoryInodesMax = ...;
270 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
4fb222c4
ZJS		 271 readonly t InhibitorsMax = ...;
272 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
273 readonly t NCurrentInhibitors = ...;
274 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
275 readonly t SessionsMax = ...;
276 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
277 readonly t NCurrentSessions = ...;
82325af3
MS		 278 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
279 readonly t StopIdleSessionUSec = ...;
44fd44f1 280 };
4fb222c4
ZJS		 281 interface org.freedesktop.DBus.Peer { ... };
282 interface org.freedesktop.DBus.Introspectable { ... };
283 interface org.freedesktop.DBus.Properties { ... };
44fd44f1
ZJS		 284};
285 </programlisting>
286
cd4dd90b
MY		 287 <!--property SleepOperation is not documented!-->
288
c4db78fc
LP		 289 <!--property HandlePowerKeyLongPress is not documented!-->
290
291 <!--property HandleRebootKey is not documented!-->
292
293 <!--property HandleRebootKeyLongPress is not documented!-->
294
295 <!--property HandleSuspendKeyLongPress is not documented!-->
296
297 <!--property HandleHibernateKeyLongPress is not documented!-->
298
82325af3
MS		 299 <!--property StopIdleSessionUSec is not documented!-->
300
00bb75d7
ZJS		 301 <!--Autogenerated cross-references for systemd.directives, do not edit-->
302
303 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Manager"/>
304
305 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Manager"/>
306
307 <variablelist class="dbus-method" generated="True" extra-ref="GetSession()"/>
308
309 <variablelist class="dbus-method" generated="True" extra-ref="GetSessionByPID()"/>
310
311 <variablelist class="dbus-method" generated="True" extra-ref="GetUser()"/>
312
313 <variablelist class="dbus-method" generated="True" extra-ref="GetUserByPID()"/>
314
315 <variablelist class="dbus-method" generated="True" extra-ref="GetSeat()"/>
316
317 <variablelist class="dbus-method" generated="True" extra-ref="ListSessions()"/>
318
b3cb952c
MY		 319 <variablelist class="dbus-method" generated="True" extra-ref="ListSessionsEx()"/>
320
00bb75d7
ZJS		 321 <variablelist class="dbus-method" generated="True" extra-ref="ListUsers()"/>
322
323 <variablelist class="dbus-method" generated="True" extra-ref="ListSeats()"/>
324
325 <variablelist class="dbus-method" generated="True" extra-ref="ListInhibitors()"/>
326
327 <variablelist class="dbus-method" generated="True" extra-ref="CreateSession()"/>
328
76f2191d
MS		 329 <variablelist class="dbus-method" generated="True" extra-ref="CreateSessionWithPIDFD()"/>
330
00bb75d7
ZJS		 331 <variablelist class="dbus-method" generated="True" extra-ref="ReleaseSession()"/>
332
333 <variablelist class="dbus-method" generated="True" extra-ref="ActivateSession()"/>
334
335 <variablelist class="dbus-method" generated="True" extra-ref="ActivateSessionOnSeat()"/>
336
337 <variablelist class="dbus-method" generated="True" extra-ref="LockSession()"/>
338
339 <variablelist class="dbus-method" generated="True" extra-ref="UnlockSession()"/>
340
341 <variablelist class="dbus-method" generated="True" extra-ref="LockSessions()"/>
342
343 <variablelist class="dbus-method" generated="True" extra-ref="UnlockSessions()"/>
344
345 <variablelist class="dbus-method" generated="True" extra-ref="KillSession()"/>
346
347 <variablelist class="dbus-method" generated="True" extra-ref="KillUser()"/>
348
349 <variablelist class="dbus-method" generated="True" extra-ref="TerminateSession()"/>
350
351 <variablelist class="dbus-method" generated="True" extra-ref="TerminateUser()"/>
352
353 <variablelist class="dbus-method" generated="True" extra-ref="TerminateSeat()"/>
354
355 <variablelist class="dbus-method" generated="True" extra-ref="SetUserLinger()"/>
356
357 <variablelist class="dbus-method" generated="True" extra-ref="AttachDevice()"/>
358
359 <variablelist class="dbus-method" generated="True" extra-ref="FlushDevices()"/>
360
361 <variablelist class="dbus-method" generated="True" extra-ref="PowerOff()"/>
362
8885fed4
DR		 363 <variablelist class="dbus-method" generated="True" extra-ref="PowerOffWithFlags()"/>
364
00bb75d7
ZJS		 365 <variablelist class="dbus-method" generated="True" extra-ref="Reboot()"/>
366
8885fed4
DR		 367 <variablelist class="dbus-method" generated="True" extra-ref="RebootWithFlags()"/>
368
00bb75d7
ZJS		 369 <variablelist class="dbus-method" generated="True" extra-ref="Halt()"/>
370
8885fed4
DR		 371 <variablelist class="dbus-method" generated="True" extra-ref="HaltWithFlags()"/>
372
00bb75d7
ZJS		 373 <variablelist class="dbus-method" generated="True" extra-ref="Suspend()"/>
374
8885fed4
DR		 375 <variablelist class="dbus-method" generated="True" extra-ref="SuspendWithFlags()"/>
376
00bb75d7
ZJS		 377 <variablelist class="dbus-method" generated="True" extra-ref="Hibernate()"/>
378
8885fed4
DR		 379 <variablelist class="dbus-method" generated="True" extra-ref="HibernateWithFlags()"/>
380
00bb75d7
ZJS		 381 <variablelist class="dbus-method" generated="True" extra-ref="HybridSleep()"/>
382
8885fed4
DR		 383 <variablelist class="dbus-method" generated="True" extra-ref="HybridSleepWithFlags()"/>
384
00bb75d7
ZJS		 385 <variablelist class="dbus-method" generated="True" extra-ref="SuspendThenHibernate()"/>
386
8885fed4
DR		 387 <variablelist class="dbus-method" generated="True" extra-ref="SuspendThenHibernateWithFlags()"/>
388
cd4dd90b
MY		 389 <variablelist class="dbus-method" generated="True" extra-ref="Sleep()"/>
390
00bb75d7
ZJS		 391 <variablelist class="dbus-method" generated="True" extra-ref="CanPowerOff()"/>
392
393 <variablelist class="dbus-method" generated="True" extra-ref="CanReboot()"/>
394
395 <variablelist class="dbus-method" generated="True" extra-ref="CanHalt()"/>
396
397 <variablelist class="dbus-method" generated="True" extra-ref="CanSuspend()"/>
398
399 <variablelist class="dbus-method" generated="True" extra-ref="CanHibernate()"/>
400
401 <variablelist class="dbus-method" generated="True" extra-ref="CanHybridSleep()"/>
402
403 <variablelist class="dbus-method" generated="True" extra-ref="CanSuspendThenHibernate()"/>
404
cd4dd90b
MY		 405 <variablelist class="dbus-method" generated="True" extra-ref="CanSleep()"/>
406
00bb75d7
ZJS		 407 <variablelist class="dbus-method" generated="True" extra-ref="ScheduleShutdown()"/>
408
409 <variablelist class="dbus-method" generated="True" extra-ref="CancelScheduledShutdown()"/>
410
411 <variablelist class="dbus-method" generated="True" extra-ref="Inhibit()"/>
412
413 <variablelist class="dbus-method" generated="True" extra-ref="CanRebootParameter()"/>
414
415 <variablelist class="dbus-method" generated="True" extra-ref="SetRebootParameter()"/>
416
417 <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToFirmwareSetup()"/>
418
419 <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToFirmwareSetup()"/>
420
421 <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToBootLoaderMenu()"/>
422
423 <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToBootLoaderMenu()"/>
424
425 <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToBootLoaderEntry()"/>
426
427 <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToBootLoaderEntry()"/>
428
429 <variablelist class="dbus-method" generated="True" extra-ref="SetWallMessage()"/>
430
43b238f1 431 <variablelist class="dbus-signal" generated="True" extra-ref="SessionNew()"/>
00bb75d7 432
43b238f1 433 <variablelist class="dbus-signal" generated="True" extra-ref="SessionRemoved()"/>
00bb75d7 434
43b238f1 435 <variablelist class="dbus-signal" generated="True" extra-ref="UserNew()"/>
00bb75d7 436
43b238f1 437 <variablelist class="dbus-signal" generated="True" extra-ref="UserRemoved()"/>
00bb75d7 438
43b238f1 439 <variablelist class="dbus-signal" generated="True" extra-ref="SeatNew()"/>
00bb75d7 440
43b238f1 441 <variablelist class="dbus-signal" generated="True" extra-ref="SeatRemoved()"/>
00bb75d7 442
43b238f1 443 <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForShutdown()"/>
00bb75d7 444
43b238f1 445 <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForShutdownWithMetadata()"/>
e4aab5cf 446
43b238f1 447 <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForSleep()"/>
00bb75d7
ZJS		 448
449 <variablelist class="dbus-property" generated="True" extra-ref="EnableWallMessages"/>
450
451 <variablelist class="dbus-property" generated="True" extra-ref="WallMessage"/>
452
453 <variablelist class="dbus-property" generated="True" extra-ref="NAutoVTs"/>
454
455 <variablelist class="dbus-property" generated="True" extra-ref="KillOnlyUsers"/>
456
457 <variablelist class="dbus-property" generated="True" extra-ref="KillExcludeUsers"/>
458
459 <variablelist class="dbus-property" generated="True" extra-ref="KillUserProcesses"/>
460
461 <variablelist class="dbus-property" generated="True" extra-ref="RebootParameter"/>
462
463 <variablelist class="dbus-property" generated="True" extra-ref="RebootToFirmwareSetup"/>
464
465 <variablelist class="dbus-property" generated="True" extra-ref="RebootToBootLoaderMenu"/>
466
467 <variablelist class="dbus-property" generated="True" extra-ref="RebootToBootLoaderEntry"/>
468
469 <variablelist class="dbus-property" generated="True" extra-ref="BootLoaderEntries"/>
470
471 <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
472
473 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
474
475 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
476
477 <variablelist class="dbus-property" generated="True" extra-ref="BlockInhibited"/>
478
479 <variablelist class="dbus-property" generated="True" extra-ref="DelayInhibited"/>
480
481 <variablelist class="dbus-property" generated="True" extra-ref="InhibitDelayMaxUSec"/>
482
483 <variablelist class="dbus-property" generated="True" extra-ref="UserStopDelayUSec"/>
484
cd4dd90b
MY		 485 <variablelist class="dbus-property" generated="True" extra-ref="SleepOperation"/>
486
00bb75d7
ZJS		 487 <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKey"/>
488
c4db78fc
LP		 489 <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKeyLongPress"/>
490
491 <variablelist class="dbus-property" generated="True" extra-ref="HandleRebootKey"/>
492
493 <variablelist class="dbus-property" generated="True" extra-ref="HandleRebootKeyLongPress"/>
494
00bb75d7
ZJS		 495 <variablelist class="dbus-property" generated="True" extra-ref="HandleSuspendKey"/>
496
c4db78fc
LP		 497 <variablelist class="dbus-property" generated="True" extra-ref="HandleSuspendKeyLongPress"/>
498
00bb75d7
ZJS		 499 <variablelist class="dbus-property" generated="True" extra-ref="HandleHibernateKey"/>
500
c4db78fc
LP		 501 <variablelist class="dbus-property" generated="True" extra-ref="HandleHibernateKeyLongPress"/>
502
00bb75d7
ZJS		 503 <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitch"/>
504
505 <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchExternalPower"/>
506
507 <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchDocked"/>
508
509 <variablelist class="dbus-property" generated="True" extra-ref="HoldoffTimeoutUSec"/>
510
511 <variablelist class="dbus-property" generated="True" extra-ref="IdleAction"/>
512
513 <variablelist class="dbus-property" generated="True" extra-ref="IdleActionUSec"/>
514
515 <variablelist class="dbus-property" generated="True" extra-ref="PreparingForShutdown"/>
516
517 <variablelist class="dbus-property" generated="True" extra-ref="PreparingForSleep"/>
518
519 <variablelist class="dbus-property" generated="True" extra-ref="ScheduledShutdown"/>
520
521 <variablelist class="dbus-property" generated="True" extra-ref="Docked"/>
522
523 <variablelist class="dbus-property" generated="True" extra-ref="LidClosed"/>
524
525 <variablelist class="dbus-property" generated="True" extra-ref="OnExternalPower"/>
526
527 <variablelist class="dbus-property" generated="True" extra-ref="RemoveIPC"/>
528
529 <variablelist class="dbus-property" generated="True" extra-ref="RuntimeDirectorySize"/>
530
cc1c85fb
TM		 531 <variablelist class="dbus-property" generated="True" extra-ref="RuntimeDirectoryInodesMax"/>
532
00bb75d7
ZJS		 533 <variablelist class="dbus-property" generated="True" extra-ref="InhibitorsMax"/>
534
535 <variablelist class="dbus-property" generated="True" extra-ref="NCurrentInhibitors"/>
536
537 <variablelist class="dbus-property" generated="True" extra-ref="SessionsMax"/>
538
539 <variablelist class="dbus-property" generated="True" extra-ref="NCurrentSessions"/>
540
82325af3
MS		 541 <variablelist class="dbus-property" generated="True" extra-ref="StopIdleSessionUSec"/>
542
00bb75d7
ZJS		 543 <!--End of Autogenerated section-->
544
44fd44f1
ZJS		 545 <refsect2>
546 <title>Methods</title>
547
548 <para><function>GetSession()</function> may be used to get the session object path for the session with
549 the specified ID. Similarly, <function>GetUser()</function> and <function>GetSeat()</function> get the
550 user and seat objects, respectively. <function>GetSessionByPID()</function> and
551 <function>GetUserByPID()</function> get the session/user object the specified PID belongs to if there
552 is any.</para>
553
ca264f7d 554 <para><function>ListSessions()</function> returns an array of all current sessions. The structures in
b3cb952c
MY		 555 the array consist of the following fields: <varname>session id</varname>, <varname>user id</varname>,
556 <varname>user name</varname>, <varname>seat id</varname>, and <varname>session object path</varname>.
557 If a session does not have a seat attached, the seat id field will be an empty string.</para>
558
559 <para><function>ListSessionsEx()</function> returns an array of all current sessions with more metadata
560 than <function>ListSessions()</function>. The structures in the array consist of the following fields:
561 <varname>session id</varname>, <varname>user id</varname>, <varname>user name</varname>,
562 <varname>seat id</varname>, <varname>leader pid</varname>, <varname>session class</varname>,
563 <varname>tty name</varname>, <varname>idle hint</varname>, <varname>idle hint monotonic timestamp</varname>,
564 and <varname>session object path</varname>. <varname>tty</varname> and <varname>seat id</varname> fields
565 could be empty, if the session has no associated tty or session has no seat attached, respectively.</para>
44fd44f1 566
ca264f7d 567 <para><function>ListUsers()</function> returns an array of all currently logged in users. The
44fd44f1
ZJS		 568 structures in the array consist of the following fields: user id, user name, user object path.</para>
569
ca264f7d 570 <para><function>ListSeats()</function> returns an array of all currently available seats. The
44fd44f1
ZJS		 571 structure in the array consists of the following fields: seat id, seat object path.</para>
572
ca264f7d 573 <para><function>ListInhibitors()</function> lists all currently active inhibitors. It returns an array of
7592871e 574 structures consisting of <varname>what</varname>, <varname>who</varname>, <varname>why</varname>,
ca264f7d 575 <varname>mode</varname>, <varname>uid</varname> (user ID), and <varname>pid</varname> (process ID).</para>
7592871e 576
76f2191d
MS		 577 <para><function>CreateSession()</function>, <function>CreateSessionWithPIDFD()</function>, and
578 <function>ReleaseSession()</function> may be used to open or close login sessions. These calls should
579 <emphasis>never</emphasis> be invoked directly by clients. Creating/closing sessions is exclusively the job
580 of PAM and its <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
44fd44f1
ZJS		 581 module.</para>
582
583 <para><function>ActivateSession()</function> brings the session with the specified ID into the
584 foreground. <function>ActivateSessionOnSeat()</function> does the same, but only if the seat id
585 matches.</para>
586
587 <para><function>LockSession()</function> asks the session with the specified ID to activate the screen
588 lock. <function>UnlockSession()</function> asks the session with the specified ID to remove an active
589 screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from
590 the respective session object which session managers are supposed to listen on.</para>
591
ca264f7d
DDM		 592 <para><function>LockSessions()</function> asks all sessions to activate their screen locks. This may be
593 used to lock access to the entire machine in one action. Similarly, <function>UnlockSessions()</function>
44fd44f1
ZJS		 594 asks all sessions to deactivate their screen locks.</para>
595
596 <para><function>KillSession()</function> may be used to send a Unix signal to one or all processes of a
597 session. As arguments it takes the session id, either the string <literal>leader</literal> or
598 <literal>all</literal> and a signal number. If <literal>leader</literal> is passed only the session
599 <literal>leader</literal> is killed. If <literal>all</literal> is passed all processes of the session
600 are killed.</para>
601
602 <para><function>KillUser()</function> may be used to send a Unix signal to all processes of a user. As
ca264f7d 603 arguments it takes the user id and a signal number.</para>
44fd44f1
ZJS		 604
605 <para><function>TerminateSession()</function>, <function>TerminateUser()</function>,
606 <function>TerminateSeat()</function> may be used to forcibly terminate one specific session, all
607 processes of a user, and all sessions attached to a specific seat, respectively. The session, user,
608 and seat are identified by their respective IDs.</para>
609
ca264f7d 610 <para><function>SetUserLinger()</function> enables or disables user lingering. If enabled, the runtime
beb1d286 611 directory of a user is kept around and they may continue to run processes while logged out. If
ca264f7d
DDM		 612 disabled, the runtime directory goes away as soon as they log out. <function>SetUserLinger()</function>
613 expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the
98ab0dae
ZJS		 614 <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
615 authorization interactivity (see below). Note that the user linger state is persistently
ca264f7d 616 stored on disk.</para>
44fd44f1
ZJS		 617
618 <para><function>AttachDevice()</function> may be used to assign a specific device to a specific
3b121157 619 seat. The device is identified by its <filename>/sys/</filename> path and must be eligible for seat
beb1d286
ZJS		 620 assignments. <function>AttachDevice()</function> takes three arguments: the seat id, the sysfs path,
621 and a boolean for controlling polkit interactivity (see below). Device assignments are persistently
622 stored on disk. To create a new seat, simply specify a previously unused seat id. For more information
623 about the seat assignment logic see
515736d0 624 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
44fd44f1
ZJS		 625
626 <para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting
98ab0dae 627 all assignments to the automatic defaults. The only argument it takes is the polkit interactivity
ca264f7d 628 boolean (see below).</para>
44fd44f1 629
7592871e 630 <para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Halt()</function>,
ca264f7d 631 <function>Suspend()</function>, and <function>Hibernate()</function> result in the system being powered
4de66581
LP		 632 off, rebooted, halted (shut down without turning off power), suspended (the system state is saved to
633 RAM and the CPU is turned off), or hibernated (the system state is saved to disk and the machine is
634 powered down). <function>HybridSleep()</function> results in the system entering a hybrid-sleep mode,
cd4dd90b 635 i.e. the system is both hibernated and suspended. <function>SuspendThenHibernate()</function> results
4de66581
LP		 636 in the system being suspended, then later woken using an RTC timer and hibernated. The only argument is
637 the polkit interactivity boolean <varname>interactive</varname> (see below). The main purpose of these
638 calls is that they enforce polkit policy and hence allow powering off/rebooting/suspending/hibernating
cd4dd90b
MY		 639 even by unprivileged users. They also enforce inhibition locks for non-privileged users.
640 <function>Sleep()</function> automatically selects the most suitable sleep operation supported by the
641 machine. The candidate sleep operations to check for support can be configured through <varname>SleepOperation=</varname>
642 setting in <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
643 UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. Methods
8885fed4
DR		 644 <function>PowerOffWithFlags()</function>, <function>RebootWithFlags()</function>,
645 <function>HaltWithFlags()</function>, <function>SuspendWithFlags()</function>,
cd4dd90b
MY		 646 <function>HibernateWithFlags()</function>, <function>HybridSleepWithFlags()</function>,
647 <function>SuspendThenHibernateWithFlags()</function>, and <function>Sleep()</function> take
648 <varname>flags</varname> to allow for extendability, defined as follows:</para>
8885fed4 649 <programlisting>
665a3d6d
LB		 650#define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) &lt;&lt; 0)
651#define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) &lt;&lt; 1)
652#define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) &lt;&lt; 2)
653#define SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP (UINT64_C(1) &lt;&lt; 3)
8885fed4 654 </programlisting>
4de66581
LP		 655 <para>When the <varname>flags</varname> is 0 then these methods behave just like the versions without
656 flags. When <constant>SD_LOGIND_ROOT_CHECK_INHIBITORS</constant> (0x01) is set, active inhibitors are
665a3d6d
LB		 657 honoured for privileged users too. When <constant>SD_LOGIND_KEXEC_REBOOT</constant> (0x02) is set,
658 then <function>RebootWithFlags()</function> performs a kexec reboot if kexec kernel is loaded. When
659 <constant>SD_LOGIND_SOFT_REBOOT</constant> (0x04) is set, or
660 <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> (0x08) is set and a new root file system
661 has been set up on <literal>/run/nextroot/</literal>, then <function>RebootWithFlags()</function>
662 performs a userspace reboot only. <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> and
663 <constant>SD_LOGIND_KEXEC_REBOOT</constant> can be combined, with soft-reboot having precedence.</para>
7592871e 664
ca264f7d 665 <para><function>SetRebootParameter()</function> sets a parameter for a subsequent reboot operation.
7592871e
ZJS		 666 See the description of <command>reboot</command> in
667 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
668 <citerefentry project="man-pages"><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
669 for more information.</para>
670
671 <para><function>SetRebootToFirmwareSetup()</function>,
672 <function>SetRebootToBootLoaderMenu()</function>, and <function>SetRebootToBootLoaderEntry()</function>
673 configure the action to be taken from the boot loader after a reboot: respectively entering firmware
ca264f7d 674 setup mode, the boot loader menu, or a specific boot loader entry. See
7592871e 675 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the
ca264f7d 676 corresponding command line interface.</para>
44fd44f1 677
cd4dd90b
MY		 678 <para><function>CanPowerOff()</function>, <function>CanReboot()</function>, <function>CanHalt()</function>,
679 <function>CanSuspend()</function>, <function>CanHibernate()</function>, <function>CanHybridSleep()</function>,
680 <function>CanSuspendThenHibernate()</function>, <function>CanSleep()</function>,
7592871e 681 <function>CanRebootParameter()</function>, <function>CanRebootToFirmwareSetup()</function>,
cd4dd90b
MY		 682 <function>CanRebootToBootLoaderMenu()</function>, and <function>CanRebootToBootLoaderEntry()</function>
683 test whether the system supports the respective operation and whether the calling user is allowed to
684 execute it. Returns one of <literal>na</literal>, <literal>yes</literal>, <literal>no</literal>, and
685 <literal>challenge</literal>. If <literal>na</literal> is returned, the operation is not available because
686 hardware, kernel, or drivers do not support it. If <literal>yes</literal> is returned, the operation is
687 supported and the user may execute the operation without further authentication. If <literal>no</literal>
688 is returned, the operation is available but the user is not allowed to execute the operation. If
689 <literal>challenge</literal> is returned, the operation is available but only after authorization.</para>
7592871e
ZJS		 690
691 <para><function>ScheduleShutdown()</function> schedules a shutdown operation <varname>type</varname> at
692 time <varname>usec</varname> in microseconds since the UNIX epoch. <varname>type</varname> can be one
693 of <literal>poweroff</literal>, <literal>dry-poweroff</literal>, <literal>reboot</literal>,
694 <literal>dry-reboot</literal>, <literal>halt</literal>, and <literal>dry-halt</literal>. (The
695 <literal>dry-</literal> variants do not actually execute the shutdown action.)
696 <function>CancelScheduledShutdown()</function> cancels a scheduled shutdown. The output parameter
697 <varname>cancelled</varname> is true if a shutdown operation was scheduled.</para>
698
699 <para><function>SetWallMessage()</function> sets the wall message (the message that will be sent out to
ca264f7d 700 all terminals and stored in a
d3fcecf3 701 <citerefentry project="man-pages"><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a
7592871e
ZJS		 702 subsequent scheduled shutdown operation. The parameter <varname>wall_message</varname> specifies the
703 shutdown reason (and may be empty) which will be included in the shutdown message. The parameter
704 <varname>enable</varname> specifies whether to print a wall message on shutdown.</para>
44fd44f1
ZJS		 705
706 <para><function>Inhibit()</function> creates an inhibition lock. It takes four parameters:
7592871e
ZJS		 707 <varname>what</varname>, <varname>who</varname>, <varname>why</varname>, and
708 <varname>mode</varname>. <varname>what</varname> is one or more of <literal>shutdown</literal>,
44fd44f1
ZJS		 709 <literal>sleep</literal>, <literal>idle</literal>, <literal>handle-power-key</literal>,
710 <literal>handle-suspend-key</literal>, <literal>handle-hibernate-key</literal>,
711 <literal>handle-lid-switch</literal>, separated by colons, for inhibiting poweroff/reboot,
7592871e
ZJS		 712 suspend/hibernate, the automatic idle logic, or hardware key handling. <varname>who</varname> should be
713 a short human readable string identifying the application taking the lock. <varname>why</varname>
44fd44f1 714 should be a short human readable string identifying the reason why the lock is taken. Finally,
7592871e 715 <varname>mode</varname> is either <literal>block</literal> or <literal>delay</literal> which encodes
44fd44f1 716 whether the inhibit shall be consider mandatory or whether it should just delay the operation to a
89fc6fd3 717 certain maximum time. The method returns a file descriptor. The lock is released the moment this file
ca264f7d 718 descriptor and all its duplicates are closed. For more information on the inhibition logic see
931bc195 719 <ulink url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
44fd44f1 720 </para>
44fd44f1
ZJS		 721 </refsect2>
722
723 <refsect2>
724 <title>Signals</title>
725
ca264f7d 726 <para>Whenever the inhibition state or idle hint changes, <function>PropertyChanged</function>
44fd44f1
ZJS		 727 signals are sent out to which clients can subscribe.</para>
728
43b238f1
FS		 729 <para>The <function>SessionNew()</function>, <function>SessionRemoved()</function>,
730 <function>UserNew()</function>, <function>UserRemoved()</function>, <function>SeatNew()</function>, and
731 <function>SeatRemoved()</function> signals are sent each time a session is created or removed, a user
44fd44f1
ZJS		 732 logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object
733 path.</para>
734
43b238f1
FS		 735 <para>The <function>PrepareForShutdown()</function>,
736 <function>PrepareForShutdownWithMetadata()</function>, and <function>PrepareForSleep()</function>
e4aab5cf 737 signals are sent right before (with the argument <literal>true</literal>) or after (with the argument
44fd44f1 738 <literal>false</literal>) the system goes down for reboot/poweroff and suspend/hibernate,
ca264f7d
DDM		 739 respectively. This may be used by applications to save data on disk, release memory, or do other jobs
740 that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After
741 completion of this work they should release their inhibition locks in order to not delay the operation
44fd44f1 742 any further. For more information see
e4aab5cf
LB		 743 <ulink url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>. The
744 <function>PrepareForShutdownWithMetadata()</function> signal additionally sends a list of key/value
745 pair metadata fields. Currently it sends a <varname>type</varname> string which defines the type of
746 shutdown. The type can be one of <literal>power-off</literal>, <literal>reboot</literal>,
747 <literal>halt</literal>, <literal>kexec</literal> or <literal>soft-reboot</literal>. This signal is
43b238f1 748 sent first, followed by <function>PrepareForShutdown()</function> (for backward compatibility).</para>
44fd44f1
ZJS		 749 </refsect2>
750
751 <refsect2>
752 <title>Properties</title>
753
7592871e
ZJS		 754 <para>Most properties simply reflect the configuration, see
755 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
756 includes: <varname>NAutoVTs</varname>, <varname>KillOnlyUsers</varname>,
757 <varname>KillExcludeUsers</varname>, <varname>KillUserProcesses</varname>, <varname>IdleAction</varname>,
758 <varname>InhibitDelayMaxUSec</varname>,
759 <varname>InhibitorsMax</varname>,
760 <varname>UserStopDelayUSec</varname>,
761 <varname>HandlePowerKey</varname>, <varname>HandleSuspendKey</varname>,
762 <varname>HandleHibernateKey</varname>, <varname>HandleLidSwitch</varname>,
763 <varname>HandleLidSwitchExternalPower</varname>, <varname>HandleLidSwitchDocked</varname>,
764 <varname>IdleActionUSec</varname>, <varname>HoldoffTimeoutUSec</varname>,
765 <varname>RemoveIPC</varname>, <varname>RuntimeDirectorySize</varname>,
cc1c85fb
TM		 766 <varname>RuntimeDirectoryInodesMax</varname>, <varname>InhibitorsMax</varname>, and
767 <varname>SessionsMax</varname>.
44fd44f1
ZJS		 768 </para>
769
7592871e 770 <para>The <varname>IdleHint</varname> property reflects the idle hint state of the system. If the
ca264f7d 771 system is idle it might get into automatic suspend or shutdown depending on the configuration.</para>
44fd44f1 772
7592871e 773 <para><varname>IdleSinceHint</varname> and <varname>IdleSinceHintMonotonic</varname> encode the
44fd44f1
ZJS		 774 timestamps of the last change of the idle hint boolean, in <constant>CLOCK_REALTIME</constant> and
775 <constant>CLOCK_MONOTONIC</constant> timestamps, respectively, in microseconds since the epoch.</para>
776
7592871e 777 <para>The <varname>BlockInhibited</varname> and <varname>DelayInhibited</varname> properties encode
44fd44f1 778 the currently active locks of the respective modes. They are colon separated lists of
ca264f7d 779 <literal>shutdown</literal>, <literal>sleep</literal>, and <literal>idle</literal> (see above).</para>
44fd44f1 780
7592871e
ZJS		 781 <para><varname>NCurrentSessions</varname> and <varname>NCurrentInhibitors</varname> contain the number
782 of currently registered sessions and inhibitors.</para>
783
784 <para>The <varname>BootLoaderEntries</varname> property contains a list of boot loader entries.
ca264f7d 785 This includes boot loader entries defined in configuration and any additional loader entries
7592871e
ZJS		 786 reported by the boot loader. See
787 <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
788 for more information.</para>
789
790 <para>The <varname>PreparingForShutdown</varname> and <varname>PreparingForSleep</varname> boolean
43b238f1
FS		 791 properties are true during the interval between the two <function>PrepareForShutdown()</function> and
792 <function>PrepareForSleep()</function> signals respectively. Note that these properties do not
44fd44f1 793 send out <function>PropertyChanged</function> signals.</para>
7592871e 794
ca264f7d 795 <para>The <varname>RebootParameter</varname> property shows the value set with the
7592871e
ZJS		 796 <function>SetRebootParameter()</function> method described above.</para>
797
ca264f7d 798 <para><varname>ScheduledShutdown</varname> shows the value pair set with the
7592871e
ZJS		 799 <function>ScheduleShutdown()</function> method described above.</para>
800
801 <para><varname>RebootToFirmwareSetup</varname>, <varname>RebootToBootLoaderMenu</varname>, and
802 <varname>RebootToBootLoaderEntry</varname> are true when the resprective post-reboot operation was
43b238f1
FS		 803 selected with <function>SetRebootToFirmwareSetup()</function>,
804 <function>SetRebootToBootLoaderMenu()</function>, or
805 <function>SetRebootToBootLoaderEntry()</function>.</para>
7592871e 806
ca264f7d
DDM		 807 <para>The <varname>WallMessage</varname> and <varname>EnableWallMessages</varname> properties reflect the
808 shutdown reason and wall message enablement switch which can be set with the
809 <function>SetWallMessage()</function> method described above.</para>
7592871e 810
ca264f7d 811 <para><varname>Docked</varname> is true if the machine is connected to a dock.
7592871e
ZJS		 812 <varname>LidClosed</varname> is true when the lid (of a laptop) is closed.
813 <varname>OnExternalPower</varname> is true when the machine is connected to an external power supply.
814 </para>
815 </refsect2>
816
817 <refsect2>
818 <title>Security</title>
819
98ab0dae 820 <para>A number of operations are protected via the polkit privilege
7592871e
ZJS		 821 system. <function>SetUserLinger()</function> requires the
822 <interfacename>org.freedesktop.login1.set-user-linger</interfacename>
823 privilege. <function>AttachDevice()</function> requires
824 <interfacename>org.freedesktop.login1.attach-device</interfacename> and
ca264f7d 825 <function>FlushDevices()</function> requires
7592871e
ZJS		 826 <interfacename>org.freedesktop.login1.flush-devices</interfacename>. <function>PowerOff()</function>,
827 <function>Reboot()</function>, <function>Halt()</function>, <function>Suspend()</function>,
828 <function>Hibernate()</function> require
829 <interfacename>org.freedesktop.login1.power-off</interfacename>,
830 <interfacename>org.freedesktop.login1.power-off-multiple-sessions</interfacename>,
831 <interfacename>org.freedesktop.login1.power-off-ignore-inhibit</interfacename>,
832 <interfacename>org.freedesktop.login1.reboot</interfacename>,
833 <interfacename>org.freedesktop.login1.reboot-multiple-sessions</interfacename>,
834 <interfacename>org.freedesktop.login1.reboot-ignore-inhibit</interfacename>,
835 <interfacename>org.freedesktop.login1.halt</interfacename>,
836 <interfacename>org.freedesktop.login1.halt-multiple-sessions</interfacename>,
837 <interfacename>org.freedesktop.login1.halt-ignore-inhibit</interfacename>,
838 <interfacename>org.freedesktop.login1.suspend</interfacename>,
839 <interfacename>org.freedesktop.login1.suspend-multiple-sessions</interfacename>,
840 <interfacename>org.freedesktop.login1.suspend-ignore-inhibit</interfacename>,
841 <interfacename>org.freedesktop.login1.hibernate</interfacename>,
842 <interfacename>org.freedesktop.login1.hibernate-multiple-sessions</interfacename>,
843 <interfacename>org.freedesktop.login1.hibernate-ignore-inhibit</interfacename>,
ca264f7d 844 respectively depending on whether there are other sessions around or active inhibits are present.
7592871e 845 <function>HybridSleep()</function> and <function>SuspendThenHibernate()</function>
cd4dd90b
MY		 846 use the same privileges as <function>Hibernate()</function>. <function>Sleep()</function> uses
847 the inhibits of the auto-selected sleep operation. <function>SetRebootParameter()</function> requires
7592871e
ZJS		 848 <interfacename>org.freedesktop.login1.set-reboot-parameter</interfacename>.</para>
849
43b238f1 850 <para><function>SetRebootToFirmwareSetup()</function> requires
7592871e 851 <interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup</interfacename>.
43b238f1 852 <function>SetRebootToBootLoaderMenu()</function> requires
7592871e 853 <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu</interfacename>.
43b238f1 854 <function>SetRebootToBootLoaderEntry()</function> requires
7592871e
ZJS		 855 <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-entry</interfacename>.
856 </para>
857
43b238f1 858 <para><function>ScheduleShutdown()</function> and <function>CancelScheduledShutdown()</function> require
7592871e
ZJS		 859 the same privileges (listed above) as the immediate poweroff/reboot/halt operations.</para>
860
ca264f7d 861 <para><function>Inhibit()</function> is protected via one of
7592871e
ZJS		 862 <interfacename>org.freedesktop.login1.inhibit-block-shutdown</interfacename>,
863 <interfacename>org.freedesktop.login1.inhibit-delay-shutdown</interfacename>,
864 <interfacename>org.freedesktop.login1.inhibit-block-sleep</interfacename>,
865 <interfacename>org.freedesktop.login1.inhibit-delay-sleep</interfacename>,
866 <interfacename>org.freedesktop.login1.inhibit-block-idle</interfacename>,
867 <interfacename>org.freedesktop.login1.inhibit-handle-power-key</interfacename>,
868 <interfacename>org.freedesktop.login1.inhibit-handle-suspend-key</interfacename>,
869 <interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key</interfacename>,
870 <interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock
871 type and mode taken.</para>
872
98ab0dae 873 <para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit
ca264f7d 874 should interactively ask the user for authentication credentials if required.</para>
44fd44f1
ZJS		 875 </refsect2>
876 </refsect1>
877
878 <refsect1>
879 <title>Seat Objects</title>
880
48f99d7c 881 <programlisting executable="systemd-logind" node="/org/freedesktop/login1/seat/seat0" interface="org.freedesktop.login1.Seat">
44fd44f1
ZJS		 882node /org/freedesktop/login1/seat/seat0 {
883 interface org.freedesktop.login1.Seat {
884 methods:
885 Terminate();
886 ActivateSession(in s session_id);
887 SwitchTo(in u vtnr);
888 SwitchToNext();
889 SwitchToPrevious();
890 properties:
4fb222c4
ZJS		 891 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
892 readonly s Id = '...';
893 readonly (so) ActiveSession = ...;
894 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
4fb222c4
ZJS		 895 readonly b CanTTY = ...;
896 readonly b CanGraphical = ...;
897 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
898 readonly a(so) Sessions = [...];
899 readonly b IdleHint = ...;
900 readonly t IdleSinceHint = ...;
901 readonly t IdleSinceHintMonotonic = ...;
44fd44f1 902 };
4fb222c4
ZJS		 903 interface org.freedesktop.DBus.Peer { ... };
904 interface org.freedesktop.DBus.Introspectable { ... };
905 interface org.freedesktop.DBus.Properties { ... };
44fd44f1
ZJS		 906};
907 </programlisting>
908
00bb75d7
ZJS		 909 <!--Autogenerated cross-references for systemd.directives, do not edit-->
910
911 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Seat"/>
912
913 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Seat"/>
914
915 <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
916
917 <variablelist class="dbus-method" generated="True" extra-ref="ActivateSession()"/>
918
919 <variablelist class="dbus-method" generated="True" extra-ref="SwitchTo()"/>
920
921 <variablelist class="dbus-method" generated="True" extra-ref="SwitchToNext()"/>
922
923 <variablelist class="dbus-method" generated="True" extra-ref="SwitchToPrevious()"/>
924
925 <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
926
927 <variablelist class="dbus-property" generated="True" extra-ref="ActiveSession"/>
928
00bb75d7
ZJS		 929 <variablelist class="dbus-property" generated="True" extra-ref="CanTTY"/>
930
931 <variablelist class="dbus-property" generated="True" extra-ref="CanGraphical"/>
932
933 <variablelist class="dbus-property" generated="True" extra-ref="Sessions"/>
934
935 <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
936
937 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
938
939 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
940
941 <!--End of Autogenerated section-->
942
44fd44f1
ZJS		 943 <refsect2>
944 <title>Methods</title>
945
15102ced
ZJS		 946 <para><function>Terminate()</function> and <function>ActivateSession()</function> work similarly to
947 <function>TerminateSeat()</function> and <function>ActivationSessionOnSeat()</function> on the Manager
948 object.</para>
7592871e
ZJS		 949
950 <para><function>SwitchTo()</function> switches to the session on the virtual terminal
951 <varname>vtnr</varname>. <function>SwitchToNext()</function> and
952 <function>SwitchToPrevious()</function> switch to, respectively, the next and previous sessions on the
953 seat in the order of virtual terminals. If there is no active session, they switch to, respectively,
954 the first and last session on the seat.</para>
44fd44f1
ZJS		 955 </refsect2>
956
957 <refsect2>
958 <title>Signals</title>
959
960 <para>Whenever <function>ActiveSession</function>, <function>Sessions</function>,
38b52b69 961 <function>CanGraphical</function>, <function>CanTTY</function>,
ca264f7d 962 or the idle state changes, <function>PropertyChanged</function> signals are sent out to which clients
44fd44f1
ZJS		 963 can subscribe.</para>
964 </refsect2>
965
966 <refsect2>
967 <title>Properties</title>
968
969 <para>The <varname>Id</varname> property encodes the ID of the seat.</para>
970
971 <para><varname>ActiveSession</varname> encodes the currently active session if there is one. It is a
ca264f7d 972 structure consisting of the session id and the object path.</para>
44fd44f1 973
38b52b69
ZJS		 974 <para><varname>CanTTY</varname> encodes whether the session is suitable for text logins, and
975 <varname>CanGraphical</varname> whether it is suitable for graphical sessions.</para>
44fd44f1 976
7592871e 977 <para>The <varname>Sessions</varname> property is an array of all current sessions of this seat, each
44fd44f1
ZJS		 978 encoded in a structure consisting of the ID and the object path.</para>
979
ca264f7d 980 <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
15102ced
ZJS		 981 <varname>IdleSinceHintMonotonic</varname> properties encode the idle state, similarly to the ones
982 exposed on the <interfacename>Manager</interfacename> object, but specific for this seat.</para>
44fd44f1
ZJS		 983 </refsect2>
984 </refsect1>
985
986 <refsect1>
987 <title>User Objects</title>
988
48f99d7c 989 <programlisting executable="systemd-logind" node="/org/freedesktop/login1/user/_1000" interface="org.freedesktop.login1.User">
44fd44f1
ZJS		 990node /org/freedesktop/login1/user/_1000 {
991 interface org.freedesktop.login1.User {
992 methods:
993 Terminate();
4fb222c4 994 Kill(in i signal_number);
44fd44f1 995 properties:
4fb222c4
ZJS		 996 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
997 readonly u UID = ...;
998 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
999 readonly u GID = ...;
1000 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1001 readonly s Name = '...';
1002 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1003 readonly t Timestamp = ...;
1004 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1005 readonly t TimestampMonotonic = ...;
1006 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1007 readonly s RuntimePath = '...';
1008 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1009 readonly s Service = '...';
1010 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1011 readonly s Slice = '...';
1012 readonly (so) Display = ...;
1013 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
1014 readonly s State = '...';
1015 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
1016 readonly a(so) Sessions = [...];
1017 readonly b IdleHint = ...;
1018 readonly t IdleSinceHint = ...;
1019 readonly t IdleSinceHintMonotonic = ...;
1020 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
1021 readonly b Linger = ...;
44fd44f1 1022 };
4fb222c4
ZJS		 1023 interface org.freedesktop.DBus.Peer { ... };
1024 interface org.freedesktop.DBus.Introspectable { ... };
1025 interface org.freedesktop.DBus.Properties { ... };
44fd44f1
ZJS		 1026};
1027 </programlisting>
1028
00bb75d7
ZJS		 1029 <!--Autogenerated cross-references for systemd.directives, do not edit-->
1030
1031 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.User"/>
1032
1033 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.User"/>
1034
1035 <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
1036
1037 <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/>
1038
1039 <variablelist class="dbus-property" generated="True" extra-ref="UID"/>
1040
1041 <variablelist class="dbus-property" generated="True" extra-ref="GID"/>
1042
1043 <variablelist class="dbus-property" generated="True" extra-ref="Name"/>
1044
1045 <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/>
1046
1047 <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/>
1048
1049 <variablelist class="dbus-property" generated="True" extra-ref="RuntimePath"/>
1050
1051 <variablelist class="dbus-property" generated="True" extra-ref="Service"/>
1052
1053 <variablelist class="dbus-property" generated="True" extra-ref="Slice"/>
1054
1055 <variablelist class="dbus-property" generated="True" extra-ref="Display"/>
1056
1057 <variablelist class="dbus-property" generated="True" extra-ref="State"/>
1058
1059 <variablelist class="dbus-property" generated="True" extra-ref="Sessions"/>
1060
1061 <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
1062
1063 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
1064
1065 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
1066
1067 <variablelist class="dbus-property" generated="True" extra-ref="Linger"/>
1068
1069 <!--End of Autogenerated section-->
1070
44fd44f1
ZJS		 1071 <refsect2>
1072 <title>Methods</title>
1073
15102ced 1074 <para><function>Terminate()</function> and <function>Kill()</function> work similarly to the
ca264f7d 1075 <function>TerminateUser()</function> and <function>KillUser()</function> methods on the manager
44fd44f1
ZJS		 1076 object.</para>
1077 </refsect2>
1078
1079 <refsect2>
1080 <title>Signals</title>
1081
ca264f7d 1082 <para>Whenever <varname>Sessions</varname> or the idle state changes,
44fd44f1
ZJS		 1083 <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
1084 </refsect2>
1085
1086 <refsect2>
1087 <title>Properties</title>
1088
1089 <para>The <varname>UID</varname> and <varname>GID</varname> properties encode the Unix UID and primary
1090 GID of the user.</para>
1091
1092 <para>The <varname>Name</varname> property encodes the user name.</para>
1093
1094 <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the login time of
ca264f7d 1095 the user in microseconds since the epoch, in the <constant>CLOCK_REALTIME</constant> and
44fd44f1
ZJS		 1096 <constant>CLOCK_MONOTONIC</constant> clocks, respectively.</para>
1097
1098 <para><varname>RuntimePath</varname> encodes the runtime path of the user,
ca264f7d 1099 i.e. <varname>$XDG_RUNTIME_DIR</varname>. For details see the
44fd44f1
ZJS		 1100 <ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
1101 XDG Basedir Specification
1102 </ulink>.</para>
1103
ca264f7d
DDM		 1104 <para><varname>Service</varname> contains the unit name of the user systemd service of this
1105 user. Each logged in user is assigned a user service that runs a user systemd instance. This is
44fd44f1
ZJS		 1106 usually an instance of <filename>user@.service</filename>.</para>
1107
ca264f7d 1108 <para><varname>Slice</varname> contains the unit name of the user systemd slice of this user. Each
44fd44f1
ZJS		 1109 logged in user gets a private slice.</para>
1110
ca264f7d
DDM		 1111 <para><varname>Display</varname> encodes which graphical session should be used as the primary UI display
1112 for the user. It is a structure encoding the session ID and the object path of the session to use.</para>
44fd44f1 1113
ca264f7d
DDM		 1114 <para><varname>State</varname> encodes the user state and is one of <literal>offline</literal>,
1115 <literal>lingering</literal>, <literal>online</literal>, <literal>active</literal>, or
44fd44f1
ZJS		 1116 <literal>closing</literal>. See
1117 <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
1118 for more information about the states.</para>
1119
1120 <para><varname>Sessions</varname> is an array of structures encoding all current sessions of the
ca264f7d 1121 user. Each structure consists of the ID and object path.</para>
44fd44f1 1122
ca264f7d 1123 <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
15102ced
ZJS		 1124 <varname>IdleSinceHintMonotonic</varname> properties encode the idle hint state of the user, similarly
1125 to the <interfacename>Manager</interfacename>'s properties, but specific for this user.</para>
7592871e 1126
ca264f7d 1127 <para>The <varname>Linger</varname> property shows whether lingering is enabled for this user.</para>
44fd44f1
ZJS		 1128 </refsect2>
1129 </refsect1>
1130
1131 <refsect1>
1132 <title>Session Objects</title>
1133
48f99d7c
ZJS		 1134 <programlisting executable="systemd-logind" node="/org/freedesktop/login1/session/1" interface="org.freedesktop.login1.Session">
1135node /org/freedesktop/login1/session/1 {
44fd44f1
ZJS		 1136 interface org.freedesktop.login1.Session {
1137 methods:
1138 Terminate();
1139 Activate();
1140 Lock();
1141 Unlock();
1142 SetIdleHint(in b idle);
4fb222c4 1143 SetLockedHint(in b locked);
44fd44f1 1144 Kill(in s who,
4fb222c4 1145 in i signal_number);
44fd44f1
ZJS		 1146 TakeControl(in b force);
1147 ReleaseControl();
b61cc5fd 1148 SetType(in s type);
95550212 1149 SetClass(in s class);
4885d749 1150 SetDisplay(in s display);
092e6cd1 1151 SetTTY(in h tty_fd);
44fd44f1
ZJS		 1152 TakeDevice(in u major,
1153 in u minor,
1154 out h fd,
1155 out b inactive);
1156 ReleaseDevice(in u major,
1157 in u minor);
1158 PauseDeviceComplete(in u major,
1159 in u minor);
4fb222c4
ZJS		 1160 SetBrightness(in s subsystem,
1161 in s name,
1162 in u brightness);
44fd44f1
ZJS		 1163 signals:
1164 PauseDevice(u major,
1165 u minor,
1166 s type);
1167 ResumeDevice(u major,
1168 u minor,
1169 h fd);
1170 Lock();
1171 Unlock();
1172 properties:
4fb222c4
ZJS		 1173 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1174 readonly s Id = '...';
1175 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1176 readonly (uo) User = ...;
1177 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1178 readonly s Name = '...';
1179 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1180 readonly t Timestamp = ...;
1181 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1182 readonly t TimestampMonotonic = ...;
1183 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1184 readonly u VTNr = ...;
1185 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1186 readonly (so) Seat = ...;
4fb222c4 1187 readonly s TTY = '...';
4fb222c4
ZJS		 1188 readonly s Display = '...';
1189 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1190 readonly b Remote = ...;
1191 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1192 readonly s RemoteHost = '...';
1193 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1194 readonly s RemoteUser = '...';
1195 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1196 readonly s Service = '...';
1197 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1198 readonly s Desktop = '...';
1199 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1200 readonly s Scope = '...';
1201 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1202 readonly u Leader = ...;
1203 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1204 readonly u Audit = ...;
4fb222c4 1205 readonly s Type = '...';
4fb222c4
ZJS		 1206 readonly s Class = '...';
1207 readonly b Active = ...;
1208 readonly s State = '...';
1209 readonly b IdleHint = ...;
1210 readonly t IdleSinceHint = ...;
1211 readonly t IdleSinceHintMonotonic = ...;
1212 readonly b LockedHint = ...;
44fd44f1 1213 };
4fb222c4
ZJS		 1214 interface org.freedesktop.DBus.Peer { ... };
1215 interface org.freedesktop.DBus.Introspectable { ... };
1216 interface org.freedesktop.DBus.Properties { ... };
44fd44f1
ZJS		 1217};
1218 </programlisting>
1219
48f99d7c
ZJS		 1220 <!--Autogenerated cross-references for systemd.directives, do not edit-->
1221
1222 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Session"/>
1223
1224 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Session"/>
1225
1226 <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
1227
1228 <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
1229
1230 <variablelist class="dbus-method" generated="True" extra-ref="Lock()"/>
1231
1232 <variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/>
1233
1234 <variablelist class="dbus-method" generated="True" extra-ref="SetIdleHint()"/>
1235
1236 <variablelist class="dbus-method" generated="True" extra-ref="SetLockedHint()"/>
1237
1238 <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/>
1239
1240 <variablelist class="dbus-method" generated="True" extra-ref="TakeControl()"/>
1241
1242 <variablelist class="dbus-method" generated="True" extra-ref="ReleaseControl()"/>
1243
b61cc5fd
ZJS		 1244 <variablelist class="dbus-method" generated="True" extra-ref="SetType()"/>
1245
95550212
LP		 1246 <variablelist class="dbus-method" generated="True" extra-ref="SetClass()"/>
1247
4885d749
DT		 1248 <variablelist class="dbus-method" generated="True" extra-ref="SetDisplay()"/>
1249
092e6cd1
TK		 1250 <variablelist class="dbus-method" generated="True" extra-ref="SetTTY()"/>
1251
48f99d7c
ZJS		 1252 <variablelist class="dbus-method" generated="True" extra-ref="TakeDevice()"/>
1253
1254 <variablelist class="dbus-method" generated="True" extra-ref="ReleaseDevice()"/>
1255
1256 <variablelist class="dbus-method" generated="True" extra-ref="PauseDeviceComplete()"/>
1257
1258 <variablelist class="dbus-method" generated="True" extra-ref="SetBrightness()"/>
1259
43b238f1 1260 <variablelist class="dbus-signal" generated="True" extra-ref="PauseDevice()"/>
48f99d7c 1261
43b238f1 1262 <variablelist class="dbus-signal" generated="True" extra-ref="ResumeDevice()"/>
48f99d7c 1263
43b238f1 1264 <variablelist class="dbus-signal" generated="True" extra-ref="Lock()"/>
48f99d7c 1265
43b238f1 1266 <variablelist class="dbus-signal" generated="True" extra-ref="Unlock()"/>
48f99d7c
ZJS		 1267
1268 <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
1269
1270 <variablelist class="dbus-property" generated="True" extra-ref="User"/>
1271
1272 <variablelist class="dbus-property" generated="True" extra-ref="Name"/>
1273
1274 <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/>
1275
1276 <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/>
1277
1278 <variablelist class="dbus-property" generated="True" extra-ref="VTNr"/>
1279
1280 <variablelist class="dbus-property" generated="True" extra-ref="Seat"/>
1281
1282 <variablelist class="dbus-property" generated="True" extra-ref="TTY"/>
1283
1284 <variablelist class="dbus-property" generated="True" extra-ref="Display"/>
1285
1286 <variablelist class="dbus-property" generated="True" extra-ref="Remote"/>
1287
1288 <variablelist class="dbus-property" generated="True" extra-ref="RemoteHost"/>
1289
1290 <variablelist class="dbus-property" generated="True" extra-ref="RemoteUser"/>
1291
1292 <variablelist class="dbus-property" generated="True" extra-ref="Service"/>
1293
1294 <variablelist class="dbus-property" generated="True" extra-ref="Desktop"/>
1295
1296 <variablelist class="dbus-property" generated="True" extra-ref="Scope"/>
1297
1298 <variablelist class="dbus-property" generated="True" extra-ref="Leader"/>
1299
1300 <variablelist class="dbus-property" generated="True" extra-ref="Audit"/>
1301
1302 <variablelist class="dbus-property" generated="True" extra-ref="Type"/>
1303
1304 <variablelist class="dbus-property" generated="True" extra-ref="Class"/>
1305
1306 <variablelist class="dbus-property" generated="True" extra-ref="Active"/>
1307
1308 <variablelist class="dbus-property" generated="True" extra-ref="State"/>
1309
1310 <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
1311
1312 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
1313
1314 <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
1315
1316 <variablelist class="dbus-property" generated="True" extra-ref="LockedHint"/>
1317
1318 <!--End of Autogenerated section-->
1319
44fd44f1
ZJS		 1320 <refsect2>
1321 <title>Methods</title>
1322
1323 <para><function>Terminate()</function>, <function>Activate()</function>, <function>Lock()</function>,
ca264f7d 1324 <function>Unlock()</function>, and <function>Kill()</function> work similarly to the respective calls on
44fd44f1
ZJS		 1325 the <interfacename>Manager</interfacename> object.</para>
1326
ca264f7d
DDM		 1327 <para><function>SetIdleHint()</function> is called by the session object to update the idle state
1328 of the session whenever it changes.</para>
44fd44f1
ZJS		 1329
1330 <para><function>TakeControl()</function> allows a process to take exclusive managed device
ca264f7d
DDM		 1331 access-control for that session. Only one D-Bus connection can be a controller for a given session at any
1332 time. If the <varname>force</varname> argument is set (root only), an existing controller is kicked
89fc6fd3 1333 out and replaced. Otherwise, this method fails if there is already a controller. Note that this method is
ca264f7d
DDM		 1334 limited to D-Bus users with the effective UID set to the user of the session or root.</para>
1335
b61cc5fd
ZJS		 1336 <para><function>ReleaseControl()</function> drops control of a given session. Closing the D-Bus
1337 connection implicitly releases control as well. See <function>TakeControl()</function> for more
1338 information. This method also releases all devices for which the controller requested ownership via
1339 <function>TakeDevice()</function>.</para>
1340
1341 <para><function>SetType()</function> allows the type of the session to be changed dynamically. It can
1342 only be called by session's current controller. If <function>TakeControl()</function> has not been
1343 called, this method will fail. In addition, the session type will be reset to its original value once
1344 control is released, either by calling <function>ReleaseControl()</function> or closing the D-Bus
1345 connection. This should help prevent a session from entering an inconsistent state, for example if the
1346 controller crashes. The only argument <varname>type</varname> is the new session type.</para>
44fd44f1 1347
95550212
LP		 1348 <para><function>SetClass()</function> allows the caller to change the class of the session dynamically.
1349 It may only be called by session's owening user. Currently, this call may be exclusively used to change
1350 the class from <literal>user-incomplete</literal> to <literal>user</literal>. The call is synchronous,
1351 and will return only once the user's service manager has successfully been started, if necessary. The
1352 only argument <varname>type</varname> is the new session type.</para>
1353
4885d749
DT		 1354 <para><function>SetDisplay()</function> allows the display name of the graphical session to be changed. This is
1355 useful if the display server is started as part of the session. It can only be called by session's current
1356 controller. If <function>TakeControl()</function> has not been called, this method will fail. The only argument
1357 <varname>display</varname> is the new display name.</para>
1358
092e6cd1
TK		 1359 <para><function>SetTTY()</function> allows the device name of the session to be changed. This is
1360 useful if the tty device is only known after authentication. It can only be called by session's
1361 current controller. If <function>TakeControl()</function> has not been called, this method will fail.
1362 The only argument <varname>tty_fd</varname> is a file handle to the new tty device.</para>
1363
ca264f7d
DDM		 1364 <para><function>TakeDevice()</function> allows a session controller to get a file descriptor for a
1365 specific device. Pass in the major and minor numbers of the character device and
1366 <filename>systemd-logind</filename> will return a file descriptor for the device. Only a limited set of
44fd44f1 1367 device-types is currently supported (but may be extended). <filename>systemd-logind</filename>
ca264f7d
DDM		 1368 automatically mutes the file descriptor if the session is inactive and resumes it once the session is
1369 activated again. This guarantees that a session can only access session devices if the session is
44fd44f1
ZJS		 1370 active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This
1371 only works on devices that are attached to the seat of the given session. A process is not required to
ca264f7d 1372 have direct access to the device node. <filename>systemd-logind</filename> only requires you to be the
44fd44f1
ZJS		 1373 active session controller (see <function>TakeControl()</function>). Also note that any device can only
1374 be requested once. As long as you don't release it, further <function>TakeDevice()</function> calls
1375 will fail.</para>
1376
1377 <para><function>ReleaseDevice()</function> releases a device again (see
1378 <function>TakeDevice()</function>). This is also implicitly done by
ca264f7d 1379 <function>ReleaseControl()</function> or when closing the D-Bus connection.</para>
44fd44f1 1380
ca264f7d 1381 <para><function>PauseDeviceComplete()</function> allows a session controller to synchronously pause a
44fd44f1
ZJS		 1382 device after receiving a <function>PauseDevice(<literal>pause</literal>)</function> signal. Forced
1383 signals (or after an internal timeout) are automatically completed by
1384 <filename>systemd-logind</filename> asynchronously.</para>
7592871e 1385
07b4f449 1386 <para><function>SetLockedHint()</function> may be used to set the "locked hint" to
7592871e
ZJS		 1387 <varname>locked</varname>, i.e. information whether the session is locked. This is intended to be used
1388 by the desktop environment to tell <command>systemd-logind</command> when the session is locked and
1389 unlocked.</para>
1390
1391 <para><function>SetBrightness()</function> may be used to set the display brightness. This is intended
ca264f7d 1392 to be used by the desktop environment and allows unprivileged programs to access hardware settings in
7592871e
ZJS		 1393 a controlled way. The <varname>subsystem</varname> parameter specifies a kernel subsystem, either
1394 <literal>backlight</literal> or <literal>leds</literal>. The <varname>name</varname> parameter
1395 specifies a device name under the specified subsystem. The <varname>brightness</varname> parameter
1396 specifies the brightness. The range is defined by individual drivers, see
1397 <filename>/sys/class/<varname>subsystem</varname>/<varname>name</varname>/max_brightness</filename>.
1398 </para>
44fd44f1
ZJS		 1399 </refsect2>
1400
1401 <refsect2>
1402 <title>Signals</title>
1403
43b238f1
FS		 1404 <para>The active session controller exclusively gets <function>PauseDevice()</function> and
1405 <function>ResumeDevice()</function> events for any device it requested via
44fd44f1 1406 <function>TakeDevice()</function>. They notify the controller whenever a device is paused or resumed. A
43b238f1 1407 device is never resumed if its session is inactive. Also note that <function>PauseDevice()</function>
44fd44f1 1408 signals are sent before the <function>PropertyChanged</function> signal for the
43b238f1 1409 <function>Active</function> state. The inverse is true for <function>ResumeDevice()</function>. A device
44fd44f1
ZJS		 1410 may remain paused for unknown reasons even though the <interfacename>Session</interfacename> is active.
1411 </para>
1412
43b238f1 1413 <para>A <function>PauseDevice()</function> signal carries the major and minor numbers and a string describing the
ca264f7d
DDM		 1414 type as arguments. <function>force</function> means the device was already paused by
1415 <filename>systemd-logind</filename> and the signal is only an asynchronous
1416 notification. <function>pause</function> means <filename>systemd-logind</filename> grants you a limited amount of time to pause the device. You must respond to this via
1417 <function>PauseDeviceComplete()</function>. This synchronous pausing mechanism is used for
44fd44f1 1418 backwards-compatibility to VTs and <filename>systemd-logind</filename> is free to not make use of
43b238f1 1419 it. It is also free to send a forced <function>PauseDevice()</function> if you don't respond in a timely
44fd44f1 1420 manner (or for any other reason). <function>gone</function> means the device was unplugged from the
ca264f7d 1421 system and you will no longer get any notifications about it. There is no need to call
44fd44f1 1422 <function>ReleaseDevice()</function>. You may call <function>TakeDevice()</function> again if a new
ca264f7d 1423 device is assigned the major+minor combination.</para>
44fd44f1 1424
43b238f1 1425 <para><function>ResumeDevice()</function> is sent whenever a session is active and a device is
ca264f7d 1426 resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should
44fd44f1 1427 switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying
ca264f7d 1428 open file descriptor in the kernel (except for a limited set of device types).</para>
44fd44f1 1429
ca264f7d 1430 <para>Whenever <function>Active</function> or the idle state changes,
44fd44f1
ZJS		 1431 <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
1432
43b238f1 1433 <para><function>Lock()</function>/<function>Unlock()</function> is sent when the session is asked to be
44fd44f1
ZJS		 1434 screen-locked/unlocked. A session manager of the session should listen to this signal and act
1435 accordingly. This signal is sent out as a result of the <function>Lock()</function> and
1436 <function>Unlock()</function> methods, respectively.</para>
1437 </refsect2>
1438
1439 <refsect2>
1440 <title>Properties</title>
1441
1442 <para><varname>Id</varname> encodes the session ID.</para>
1443
1444 <para><varname>User</varname> encodes the user ID of the user this session belongs to. This is a
ca264f7d 1445 structure consisting of the Unix UID and the object path.</para>
44fd44f1
ZJS		 1446
1447 <para><varname>Name</varname> encodes the user name.</para>
1448
ca264f7d 1449 <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the microseconds
44fd44f1
ZJS		 1450 since the epoch when the session was created, in <constant>CLOCK_REALTIME</constant> or
1451 <constant>CLOCK_MONOTONIC</constant>, respectively.</para>
1452
1453 <para><varname>VTNr</varname> encodes the virtual terminal number of the session if there is any, 0
1454 otherwise.</para>
1455
ca264f7d 1456 <para><varname>Seat</varname> encodes the seat this session belongs to if there is any. This is a
44fd44f1
ZJS		 1457 structure consisting of the ID and the seat object path.</para>
1458
1459 <para><varname>TTY</varname> encodes the kernel TTY path of the session if this is a text login. If not
1460 this is an empty string.</para>
1461
1462 <para><varname>Display</varname> encodes the X11 display name if this is a graphical login. If not,
1463 this is an empty string.</para>
1464
1465 <para><varname>Remote</varname> encodes whether the session is local or remote.</para>
1466
1467 <para><varname>RemoteHost</varname> and <varname>RemoteUser</varname> encode the remote host and user
1468 if this is a remote session, or an empty string otherwise.</para>
1469
1470 <para><varname>Service</varname> encodes the PAM service name that registered the session.</para>
1471
7592871e
ZJS		 1472 <para><varname>Desktop</varname> describes the desktop environment running in the session (if
1473 known).</para>
1474
44fd44f1
ZJS		 1475 <para><varname>Scope</varname> contains the systemd scope unit name of this session.</para>
1476
1477 <para><varname>Leader</varname> encodes the PID of the process that registered the session.</para>
1478
ca264f7d 1479 <para><varname>Audit</varname> encodes the Kernel Audit session ID of the session if auditing is
44fd44f1
ZJS		 1480 available.</para>
1481
1482 <para><varname>Type</varname> encodes the session type. It's one of <literal>unspecified</literal> (for
1483 cron PAM sessions and suchlike), <literal>tty</literal> (for text logins) or
1484 <literal>x11</literal>/<literal>mir</literal>/<literal>wayland</literal> (for graphical logins).</para>
1485
1486 <para><varname>Class</varname> encodes the session class. It's one of <literal>user</literal> (for
ca264f7d 1487 normal user sessions), <literal>greeter</literal> (for display manager pseudo-sessions), or
44fd44f1
ZJS		 1488 <literal>lock-screen</literal> (for display lock screens).</para>
1489
1490 <para><varname>Active</varname> is a boolean that is true if the session is active, i.e. currently in the
ca264f7d 1491 foreground. This field is semi-redundant due to <varname>State</varname>.</para>
44fd44f1
ZJS		 1492
1493 <para><varname>State</varname> encodes the session state and one of <literal>online</literal>,
ca264f7d 1494 <literal>active</literal>, or <literal>closing</literal>. See
44fd44f1
ZJS		 1495 <citerefentry><refentrytitle>sd_session_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
1496 for more information about the states.</para>
1497
ca264f7d 1498 <para><varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
44fd44f1
ZJS		 1499 <varname>IdleSinceHintMonotonic</varname> encapsulate the idle hint state of this session, similarly to
1500 how the respective properties on the manager object do it for the whole system.</para>
7592871e 1501
ca264f7d
DDM		 1502 <para><varname>LockedHint</varname> shows the locked hint state of this session, as set by the
1503 <function>SetLockedHint()</function> method described above.</para>
44fd44f1
ZJS		 1504 </refsect2>
1505 </refsect1>
1506
48f99d7c
ZJS		 1507 <refsect1>
1508 <title>Examples</title>
1509
1510 <example>
01942823 1511 <title>Introspect the logind manager on the bus</title>
48f99d7c
ZJS		 1512
1513 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1514 --object-path /org/freedesktop/login1
1515 </programlisting>
01942823
ZJS		 1516
1517 <para>or</para>
1518
1519 <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1
1520 </programlisting>
48f99d7c
ZJS		 1521 </example>
1522
1523 <example>
01942823 1524 <title>Introspect the default seat on the bus</title>
48f99d7c
ZJS		 1525
1526 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1527 --object-path /org/freedesktop/login1/seat/seat0
1528 </programlisting>
01942823
ZJS		 1529
1530 <para>or</para>
1531
1532 <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/seat/seat0
1533 </programlisting>
1534
3c606438 1535 <para>Seat <literal>seat0</literal> is the default seat, so it'll be present unless local configuration
01942823
ZJS		 1536 is made to reassign all devices to a different seat. The list of seats and users can be acquired with
1537 <command>loginctl list-sessions</command>.</para>
48f99d7c
ZJS		 1538 </example>
1539
1540 <example>
01942823 1541 <title>Introspect a single user on the bus</title>
48f99d7c
ZJS		 1542
1543 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1544 --object-path /org/freedesktop/login1/user/_1000
1545 </programlisting>
01942823
ZJS		 1546
1547 <para>or</para>
1548
1549 <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/user/_1000
1550 </programlisting>
48f99d7c
ZJS		 1551 </example>
1552
1553 <example>
1554 <title>Introspect <interfacename>org.freedesktop.login1.Session</interfacename> on the bus</title>
1555
1556 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1557 --object-path /org/freedesktop/login1/session/45
1558 </programlisting>
01942823
ZJS		 1559
1560 <para>or</para>
1561
1562 <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/session/45
1563 </programlisting>
48f99d7c
ZJS		 1564 </example>
1565 </refsect1>
1566
e4239a34 1567 <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
d9d2d16a
AK		 1568
1569 <refsect1>
1570 <title>History</title>
1571 <refsect2>
1572 <title>The Manager Object</title>
1573 <para><varname>HandlePowerKeyLongPress</varname>,
1574 <varname>HandleRebootKey</varname>,
1575 <varname>HandleRebootKeyLongPress</varname>,
1576 <varname>HandleSuspendKeyLongPress</varname>, and
1577 <varname>HandleHibernateKeyLongPress</varname> were added in version 251.</para>
1578 <para><varname>StopIdleSessionUSec</varname> was added in version 252.</para>
43b238f1 1579 <para><function>PrepareForShutdownWithMetadata()</function> and
76f2191d 1580 <function>CreateSessionWithPIDFD()</function> were added in version 255.</para>
cd4dd90b 1581 <para><function>Sleep()</function>,
b3cb952c
MY		 1582 <function>CanSleep()</function>,
1583 <varname>SleepOperation</varname>, and
1584 <function>ListSessionsEx()</function> were added in version 256.</para>
d9d2d16a
AK		 1585 </refsect2>
1586 <refsect2>
1587 <title>Session Objects</title>
1588 <para><function>SetDisplay()</function> was added in version 252.</para>
1589 <para><function>SetTTY()</function> was added in version 254.</para>
95550212 1590 <para><function>SetClass()</function> was added in version 256.</para>
d9d2d16a
AK		 1591 </refsect2>
1592 </refsect1>
44fd44f1 1593</refentry>
Unnamed repository; edit this file 'description' to name the repository.