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