man/org.freedesktop.login1.xml

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