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