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.2/docbookx.dtd" >
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   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>
  42 $ gdbus introspect --system \
  43         --dest org.freedesktop.login1 \
  44         --object-path /org/freedesktop/login1
  45
  46 node /org/freedesktop/login1 {
  47   interface org.freedesktop.login1.Manager {
  48     methods:
  49       GetSession(in  s session_id,
  50                  out o object_path);
  51       GetSessionByPID(in  u pid,
  52                       out o object_path);
  53       GetUser(in  u uid,
  54               out o object_path);
  55       GetUserByPID(in  u pid,
  56                    out o object_path);
  57       GetSeat(in  s seat_id,
  58               out o object_path);
  59       ListSessions(out a(susso) sessions);
  60       ListUsers(out a(uso) users);
  61       ListSeats(out a(so) seats);
  62       ListInhibitors(out a(ssssuu) inhibitors);
  63       CreateSession(in  u uid,
  64                     in  u pid,
  65                     in  s service,
  66                     in  s type,
  67                     in  s class,
  68                     in  s desktop,
  69                     in  s seat_id,
  70                     in  u vtnr,
  71                     in  s tty,
  72                     in  s display,
  73                     in  b remote,
  74                     in  s remote_user,
  75                     in  s remote_host,
  76                     in  a(sv) properties,
  77                     out s session_id,
  78                     out o object_path,
  79                     out s runtime_path,
  80                     out h fifo_fd,
  81                     out u uid,
  82                     out s seat_id,
  83                     out u vtnr,
  84                     out b existing);
  85       ReleaseSession(in  s session_id);
  86       ActivateSession(in  s session_id);
  87       ActivateSessionOnSeat(in  s session_id,
  88                             in  s seat_id);
  89       LockSession(in  s session_id);
  90       UnlockSession(in  s session_id);
  91       LockSessions();
  92       UnlockSessions();
  93       KillSession(in  s session_id,
  94                   in  s who,
  95                   in  i signal_number);
  96       KillUser(in  u uid,
  97                in  i signal_number);
  98       TerminateSession(in  s session_id);
  99       TerminateUser(in  u uid);
 100       TerminateSeat(in  s seat_id);
 101       SetUserLinger(in  u uid,
 102                     in  b enable,
 103                     in  b interactive);
 104       AttachDevice(in  s seat_id,
 105                    in  s sysfs_path,
 106                    in  b interactive);
 107       FlushDevices(in  b interactive);
 108       PowerOff(in  b interactive);
 109       Reboot(in  b interactive);
 110       Halt(in  b interactive);
 111       Suspend(in  b interactive);
 112       Hibernate(in  b interactive);
 113       HybridSleep(in  b interactive);
 114       SuspendThenHibernate(in  b interactive);
 115       CanPowerOff(out s result);
 116       CanReboot(out s result);
 117       CanHalt(out s result);
 118       CanSuspend(out s result);
 119       CanHibernate(out s result);
 120       CanHybridSleep(out s result);
 121       CanSuspendThenHibernate(out s result);
 122       ScheduleShutdown(in  s type,
 123                        in  t usec);
 124       CancelScheduledShutdown(out b cancelled);
 125       Inhibit(in  s what,
 126               in  s who,
 127               in  s why,
 128               in  s mode,
 129               out h pipe_fd);
 130       CanRebootParameter(out s result);
 131       SetRebootParameter(in  s parameter);
 132       CanRebootToFirmwareSetup(out s result);
 133       SetRebootToFirmwareSetup(in  b enable);
 134       CanRebootToBootLoaderMenu(out s result);
 135       SetRebootToBootLoaderMenu(in  t timeout);
 136       CanRebootToBootLoaderEntry(out s result);
 137       SetRebootToBootLoaderEntry(in  s boot_loader_entry);
 138       SetWallMessage(in  s wall_message,
 139                      in  b enable);
 140     signals:
 141       SessionNew(s session_id,
 142                  o object_path);
 143       SessionRemoved(s session_id,
 144                      o object_path);
 145       UserNew(u uid,
 146               o object_path);
 147       UserRemoved(u uid,
 148                   o object_path);
 149       SeatNew(s seat_id,
 150               o object_path);
 151       SeatRemoved(s seat_id,
 152                   o object_path);
 153       PrepareForShutdown(b start);
 154       PrepareForSleep(b start);
 155     properties:
 156       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 157       @org.freedesktop.systemd1.Privileged("true")
 158       readwrite b EnableWallMessages = ...;
 159       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 160       @org.freedesktop.systemd1.Privileged("true")
 161       readwrite s WallMessage = '...';
 162       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 163       readonly u NAutoVTs = ...;
 164       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 165       readonly as KillOnlyUsers = ['...', ...];
 166       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 167       readonly as KillExcludeUsers = ['...', ...];
 168       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 169       readonly b KillUserProcesses = ...;
 170       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 171       readonly s RebootParameter = '...';
 172       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 173       readonly b RebootToFirmwareSetup = ...;
 174       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 175       readonly t RebootToBootLoaderMenu = ...;
 176       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 177       readonly s RebootToBootLoaderEntry = '...';
 178       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 179       readonly as BootLoaderEntries = ['...', ...];
 180       readonly b IdleHint = ...;
 181       readonly t IdleSinceHint = ...;
 182       readonly t IdleSinceHintMonotonic = ...;
 183       readonly s BlockInhibited = '...';
 184       readonly s DelayInhibited = '...';
 185       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 186       readonly t InhibitDelayMaxUSec = ...;
 187       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 188       readonly t UserStopDelayUSec = ...;
 189       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 190       readonly s HandlePowerKey = '...';
 191       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 192       readonly s HandleSuspendKey = '...';
 193       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 194       readonly s HandleHibernateKey = '...';
 195       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 196       readonly s HandleLidSwitch = '...';
 197       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 198       readonly s HandleLidSwitchExternalPower = '...';
 199       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 200       readonly s HandleLidSwitchDocked = '...';
 201       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 202       readonly t HoldoffTimeoutUSec = ...;
 203       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 204       readonly s IdleAction = '...';
 205       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 206       readonly t IdleActionUSec = ...;
 207       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 208       readonly b PreparingForShutdown = ...;
 209       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 210       readonly b PreparingForSleep = ...;
 211       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 212       readonly (st) ScheduledShutdown = ...;
 213       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 214       readonly b Docked = ...;
 215       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 216       readonly b LidClosed = ...;
 217       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 218       readonly b OnExternalPower = ...;
 219       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 220       readonly b RemoveIPC = ...;
 221       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 222       readonly t RuntimeDirectorySize = ...;
 223       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 224       readonly t InhibitorsMax = ...;
 225       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 226       readonly t NCurrentInhibitors = ...;
 227       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 228       readonly t SessionsMax = ...;
 229       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 230       readonly t NCurrentSessions = ...;
 231   };
 232   interface org.freedesktop.DBus.Peer { ... };
 233   interface org.freedesktop.DBus.Introspectable { ... };
 234   interface org.freedesktop.DBus.Properties { ... };
 235 };
 236     </programlisting>
 237
 238     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 239
 240     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Manager"/>
 241
 242     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Manager"/>
 243
 244     <variablelist class="dbus-method" generated="True" extra-ref="GetSession()"/>
 245
 246     <variablelist class="dbus-method" generated="True" extra-ref="GetSessionByPID()"/>
 247
 248     <variablelist class="dbus-method" generated="True" extra-ref="GetUser()"/>
 249
 250     <variablelist class="dbus-method" generated="True" extra-ref="GetUserByPID()"/>
 251
 252     <variablelist class="dbus-method" generated="True" extra-ref="GetSeat()"/>
 253
 254     <variablelist class="dbus-method" generated="True" extra-ref="ListSessions()"/>
 255
 256     <variablelist class="dbus-method" generated="True" extra-ref="ListUsers()"/>
 257
 258     <variablelist class="dbus-method" generated="True" extra-ref="ListSeats()"/>
 259
 260     <variablelist class="dbus-method" generated="True" extra-ref="ListInhibitors()"/>
 261
 262     <variablelist class="dbus-method" generated="True" extra-ref="CreateSession()"/>
 263
 264     <variablelist class="dbus-method" generated="True" extra-ref="ReleaseSession()"/>
 265
 266     <variablelist class="dbus-method" generated="True" extra-ref="ActivateSession()"/>
 267
 268     <variablelist class="dbus-method" generated="True" extra-ref="ActivateSessionOnSeat()"/>
 269
 270     <variablelist class="dbus-method" generated="True" extra-ref="LockSession()"/>
 271
 272     <variablelist class="dbus-method" generated="True" extra-ref="UnlockSession()"/>
 273
 274     <variablelist class="dbus-method" generated="True" extra-ref="LockSessions()"/>
 275
 276     <variablelist class="dbus-method" generated="True" extra-ref="UnlockSessions()"/>
 277
 278     <variablelist class="dbus-method" generated="True" extra-ref="KillSession()"/>
 279
 280     <variablelist class="dbus-method" generated="True" extra-ref="KillUser()"/>
 281
 282     <variablelist class="dbus-method" generated="True" extra-ref="TerminateSession()"/>
 283
 284     <variablelist class="dbus-method" generated="True" extra-ref="TerminateUser()"/>
 285
 286     <variablelist class="dbus-method" generated="True" extra-ref="TerminateSeat()"/>
 287
 288     <variablelist class="dbus-method" generated="True" extra-ref="SetUserLinger()"/>
 289
 290     <variablelist class="dbus-method" generated="True" extra-ref="AttachDevice()"/>
 291
 292     <variablelist class="dbus-method" generated="True" extra-ref="FlushDevices()"/>
 293
 294     <variablelist class="dbus-method" generated="True" extra-ref="PowerOff()"/>
 295
 296     <variablelist class="dbus-method" generated="True" extra-ref="Reboot()"/>
 297
 298     <variablelist class="dbus-method" generated="True" extra-ref="Halt()"/>
 299
 300     <variablelist class="dbus-method" generated="True" extra-ref="Suspend()"/>
 301
 302     <variablelist class="dbus-method" generated="True" extra-ref="Hibernate()"/>
 303
 304     <variablelist class="dbus-method" generated="True" extra-ref="HybridSleep()"/>
 305
 306     <variablelist class="dbus-method" generated="True" extra-ref="SuspendThenHibernate()"/>
 307
 308     <variablelist class="dbus-method" generated="True" extra-ref="CanPowerOff()"/>
 309
 310     <variablelist class="dbus-method" generated="True" extra-ref="CanReboot()"/>
 311
 312     <variablelist class="dbus-method" generated="True" extra-ref="CanHalt()"/>
 313
 314     <variablelist class="dbus-method" generated="True" extra-ref="CanSuspend()"/>
 315
 316     <variablelist class="dbus-method" generated="True" extra-ref="CanHibernate()"/>
 317
 318     <variablelist class="dbus-method" generated="True" extra-ref="CanHybridSleep()"/>
 319
 320     <variablelist class="dbus-method" generated="True" extra-ref="CanSuspendThenHibernate()"/>
 321
 322     <variablelist class="dbus-method" generated="True" extra-ref="ScheduleShutdown()"/>
 323
 324     <variablelist class="dbus-method" generated="True" extra-ref="CancelScheduledShutdown()"/>
 325
 326     <variablelist class="dbus-method" generated="True" extra-ref="Inhibit()"/>
 327
 328     <variablelist class="dbus-method" generated="True" extra-ref="CanRebootParameter()"/>
 329
 330     <variablelist class="dbus-method" generated="True" extra-ref="SetRebootParameter()"/>
 331
 332     <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToFirmwareSetup()"/>
 333
 334     <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToFirmwareSetup()"/>
 335
 336     <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToBootLoaderMenu()"/>
 337
 338     <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToBootLoaderMenu()"/>
 339
 340     <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToBootLoaderEntry()"/>
 341
 342     <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToBootLoaderEntry()"/>
 343
 344     <variablelist class="dbus-method" generated="True" extra-ref="SetWallMessage()"/>
 345
 346     <variablelist class="dbus-signal" generated="True" extra-ref="SessionNew"/>
 347
 348     <variablelist class="dbus-signal" generated="True" extra-ref="SessionRemoved"/>
 349
 350     <variablelist class="dbus-signal" generated="True" extra-ref="UserNew"/>
 351
 352     <variablelist class="dbus-signal" generated="True" extra-ref="UserRemoved"/>
 353
 354     <variablelist class="dbus-signal" generated="True" extra-ref="SeatNew"/>
 355
 356     <variablelist class="dbus-signal" generated="True" extra-ref="SeatRemoved"/>
 357
 358     <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForShutdown"/>
 359
 360     <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForSleep"/>
 361
 362     <variablelist class="dbus-property" generated="True" extra-ref="EnableWallMessages"/>
 363
 364     <variablelist class="dbus-property" generated="True" extra-ref="WallMessage"/>
 365
 366     <variablelist class="dbus-property" generated="True" extra-ref="NAutoVTs"/>
 367
 368     <variablelist class="dbus-property" generated="True" extra-ref="KillOnlyUsers"/>
 369
 370     <variablelist class="dbus-property" generated="True" extra-ref="KillExcludeUsers"/>
 371
 372     <variablelist class="dbus-property" generated="True" extra-ref="KillUserProcesses"/>
 373
 374     <variablelist class="dbus-property" generated="True" extra-ref="RebootParameter"/>
 375
 376     <variablelist class="dbus-property" generated="True" extra-ref="RebootToFirmwareSetup"/>
 377
 378     <variablelist class="dbus-property" generated="True" extra-ref="RebootToBootLoaderMenu"/>
 379
 380     <variablelist class="dbus-property" generated="True" extra-ref="RebootToBootLoaderEntry"/>
 381
 382     <variablelist class="dbus-property" generated="True" extra-ref="BootLoaderEntries"/>
 383
 384     <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
 385
 386     <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
 387
 388     <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
 389
 390     <variablelist class="dbus-property" generated="True" extra-ref="BlockInhibited"/>
 391
 392     <variablelist class="dbus-property" generated="True" extra-ref="DelayInhibited"/>
 393
 394     <variablelist class="dbus-property" generated="True" extra-ref="InhibitDelayMaxUSec"/>
 395
 396     <variablelist class="dbus-property" generated="True" extra-ref="UserStopDelayUSec"/>
 397
 398     <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKey"/>
 399
 400     <variablelist class="dbus-property" generated="True" extra-ref="HandleSuspendKey"/>
 401
 402     <variablelist class="dbus-property" generated="True" extra-ref="HandleHibernateKey"/>
 403
 404     <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitch"/>
 405
 406     <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchExternalPower"/>
 407
 408     <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchDocked"/>
 409
 410     <variablelist class="dbus-property" generated="True" extra-ref="HoldoffTimeoutUSec"/>
 411
 412     <variablelist class="dbus-property" generated="True" extra-ref="IdleAction"/>
 413
 414     <variablelist class="dbus-property" generated="True" extra-ref="IdleActionUSec"/>
 415
 416     <variablelist class="dbus-property" generated="True" extra-ref="PreparingForShutdown"/>
 417
 418     <variablelist class="dbus-property" generated="True" extra-ref="PreparingForSleep"/>
 419
 420     <variablelist class="dbus-property" generated="True" extra-ref="ScheduledShutdown"/>
 421
 422     <variablelist class="dbus-property" generated="True" extra-ref="Docked"/>
 423
 424     <variablelist class="dbus-property" generated="True" extra-ref="LidClosed"/>
 425
 426     <variablelist class="dbus-property" generated="True" extra-ref="OnExternalPower"/>
 427
 428     <variablelist class="dbus-property" generated="True" extra-ref="RemoveIPC"/>
 429
 430     <variablelist class="dbus-property" generated="True" extra-ref="RuntimeDirectorySize"/>
 431
 432     <variablelist class="dbus-property" generated="True" extra-ref="InhibitorsMax"/>
 433
 434     <variablelist class="dbus-property" generated="True" extra-ref="NCurrentInhibitors"/>
 435
 436     <variablelist class="dbus-property" generated="True" extra-ref="SessionsMax"/>
 437
 438     <variablelist class="dbus-property" generated="True" extra-ref="NCurrentSessions"/>
 439
 440     <!--End of Autogenerated section-->
 441
 442     <refsect2>
 443       <title>Methods</title>
 444
 445       <para><function>GetSession()</function> may be used to get the session object path for the session with
 446       the specified ID. Similarly, <function>GetUser()</function> and <function>GetSeat()</function> get the
 447       user and seat objects, respectively. <function>GetSessionByPID()</function> and
 448       <function>GetUserByPID()</function> get the session/user object the specified PID belongs to if there
 449       is any.</para>
 450
 451       <para><function>ListSessions()</function> returns an array of all current sessions. The structures in
 452       the array consist of the following fields: session id, user id, user name, seat id, session object
 453       path. If a session does not have a seat attached, the seat id field will be an empty string.</para>
 454
 455       <para><function>ListUsers()</function> returns an array of all currently logged in users. The
 456       structures in the array consist of the following fields: user id, user name, user object path.</para>
 457
 458       <para><function>ListSeats()</function> returns an array of all currently available seats. The
 459       structure in the array consists of the following fields: seat id, seat object path.</para>
 460
 461       <para><function>ListInhibitors()</function> lists all currently active inhibitors. It returns an array of
 462       structures consisting of <varname>what</varname>, <varname>who</varname>, <varname>why</varname>,
 463       <varname>mode</varname>, <varname>uid</varname> (user ID), and <varname>pid</varname> (process ID).</para>
 464
 465       <para><function>CreateSession()</function> and <function>ReleaseSession()</function> may be used to
 466       open or close login sessions. These calls should <emphasis>never</emphasis> be invoked directly by
 467       clients. Creating/closing sessions is exclusively the job of PAM and its
 468       <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 469       module.</para>
 470
 471       <para><function>ActivateSession()</function> brings the session with the specified ID into the
 472       foreground. <function>ActivateSessionOnSeat()</function> does the same, but only if the seat id
 473       matches.</para>
 474
 475       <para><function>LockSession()</function> asks the session with the specified ID to activate the screen
 476       lock. <function>UnlockSession()</function> asks the session with the specified ID to remove an active
 477       screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from
 478       the respective session object which session managers are supposed to listen on.</para>
 479
 480       <para><function>LockSessions()</function> asks all sessions to activate their screen locks. This may be
 481       used to lock access to the entire machine in one action. Similarly, <function>UnlockSessions()</function>
 482       asks all sessions to deactivate their screen locks.</para>
 483
 484       <para><function>KillSession()</function> may be used to send a Unix signal to one or all processes of a
 485       session. As arguments it takes the session id, either the string <literal>leader</literal> or
 486       <literal>all</literal> and a signal number. If <literal>leader</literal> is passed only the session
 487       <literal>leader</literal> is killed. If <literal>all</literal> is passed all processes of the session
 488       are killed.</para>
 489
 490       <para><function>KillUser()</function> may be used to send a Unix signal to all processes of a user. As
 491       arguments it takes the user id and a signal number.</para>
 492
 493       <para><function>TerminateSession()</function>, <function>TerminateUser()</function>,
 494       <function>TerminateSeat()</function> may be used to forcibly terminate one specific session, all
 495       processes of a user, and all sessions attached to a specific seat, respectively. The session, user,
 496       and seat are identified by their respective IDs.</para>
 497
 498       <para><function>SetUserLinger()</function> enables or disables user lingering. If enabled, the runtime
 499       directory of a user is kept around and he may continue to run processes while he is logged out. If
 500       disabled, the runtime directory goes away as soon as they log out. <function>SetUserLinger()</function>
 501       expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the
 502       PolicyKit authorization interactivity (see below). Note that the user linger state is persistently
 503       stored on disk.</para>
 504
 505       <para><function>AttachDevice()</function> may be used to assign a specific device to a specific
 506       seat. The device is identified by its /sys path and must be eligible for seat assignments. <function>AttachDevice()</function> takes three
 507       arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see
 508       below). Device assignments are persistently stored on disk. To create a new seat, simply specify a
 509       previously unused seat id. For more information about the seat assignment logic see
 510       <ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat for Linux</ulink>.
 511       </para>
 512
 513       <para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting
 514       all assignments to the automatic defaults. The only argument it takes is the PolicyKit interactivity
 515       boolean (see below).</para>
 516
 517       <para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Halt()</function>,
 518       <function>Suspend()</function>, and <function>Hibernate()</function> result in the system being powered
 519       off, rebooted, halted (shut down without turning off power), suspended (the system state is
 520       saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and
 521       the machine is powered down). <function>HybridSleep()</function> results in the system entering a
 522       hybrid-sleep mode, i.e. the system is both hibernated and suspended.
 523       <function>SuspendThenHibernate()</function> results in the system being suspended, then later woken
 524       using an RTC timer and hibernated. The only argument is the PolicyKit interactivity boolean
 525       <varname>interactive</varname> (see below). The main purpose of these calls is that they enforce
 526       PolicyKit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged
 527       users. They also enforce inhibition locks. UIs should expose these calls as the primary mechanism to
 528       poweroff/reboot/suspend/hibernate the machine.</para>
 529
 530       <para><function>SetRebootParameter()</function> sets a parameter for a subsequent reboot operation.
 531       See the description of <command>reboot</command> in
 532       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
 533       <citerefentry project="man-pages"><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 534       for more information.</para>
 535
 536       <para><function>SetRebootToFirmwareSetup()</function>,
 537       <function>SetRebootToBootLoaderMenu()</function>, and <function>SetRebootToBootLoaderEntry()</function>
 538       configure the action to be taken from the boot loader after a reboot: respectively entering firmware
 539       setup mode, the boot loader menu, or a specific boot loader entry. See
 540       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the
 541       corresponding command line interface.</para>
 542
 543       <para><function>CanPowerOff()</function>, <function>CanReboot()</function>,
 544       <function>CanHalt()</function>, <function>CanSuspend()</function>, <function>CanHibernate()</function>,
 545       <function>CanHybridSleep()</function>, <function>CanSuspendThenHibernate()</function>,
 546       <function>CanRebootParameter()</function>, <function>CanRebootToFirmwareSetup()</function>,
 547       <function>CanRebootToBootLoaderMenu()</function>, and
 548       <function>CanRebootToBootLoaderEntry()</function> test whether the system supports the respective
 549       operation and whether the calling user is allowed to execute it. Returns one of <literal>na</literal>,
 550       <literal>yes</literal>, <literal>no</literal>, and <literal>challenge</literal>. If
 551       <literal>na</literal> is returned, the operation is not available because hardware, kernel, or drivers
 552       do not support it. If <literal>yes</literal> is returned, the operation is supported and the user may
 553       execute the operation without further authentication. If <literal>no</literal> is returned, the
 554       operation is available but the user is not allowed to execute the operation. If
 555       <literal>challenge</literal> is returned, the operation is available but only after
 556       authorization.</para>
 557
 558       <para><function>ScheduleShutdown()</function> schedules a shutdown operation <varname>type</varname> at
 559       time <varname>usec</varname> in microseconds since the UNIX epoch. <varname>type</varname> can be one
 560       of <literal>poweroff</literal>, <literal>dry-poweroff</literal>, <literal>reboot</literal>,
 561       <literal>dry-reboot</literal>, <literal>halt</literal>, and <literal>dry-halt</literal>. (The
 562       <literal>dry-</literal> variants do not actually execute the shutdown action.)
 563       <function>CancelScheduledShutdown()</function> cancels a scheduled shutdown. The output parameter
 564       <varname>cancelled</varname> is true if a shutdown operation was scheduled.</para>
 565
 566       <para><function>SetWallMessage()</function> sets the wall message (the message that will be sent out to
 567       all terminals and stored in a
 568       <citerefentry><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a
 569       subsequent scheduled shutdown operation. The parameter <varname>wall_message</varname> specifies the
 570       shutdown reason (and may be empty) which will be included in the shutdown message. The parameter
 571       <varname>enable</varname> specifies whether to print a wall message on shutdown.</para>
 572
 573       <para><function>Inhibit()</function> creates an inhibition lock. It takes four parameters:
 574       <varname>what</varname>, <varname>who</varname>, <varname>why</varname>, and
 575       <varname>mode</varname>. <varname>what</varname> is one or more of <literal>shutdown</literal>,
 576       <literal>sleep</literal>, <literal>idle</literal>, <literal>handle-power-key</literal>,
 577       <literal>handle-suspend-key</literal>, <literal>handle-hibernate-key</literal>,
 578       <literal>handle-lid-switch</literal>, separated by colons, for inhibiting poweroff/reboot,
 579       suspend/hibernate, the automatic idle logic, or hardware key handling. <varname>who</varname> should be
 580       a short human readable string identifying the application taking the lock. <varname>why</varname>
 581       should be a short human readable string identifying the reason why the lock is taken. Finally,
 582       <varname>mode</varname> is either <literal>block</literal> or <literal>delay</literal> which encodes
 583       whether the inhibit shall be consider mandatory or whether it should just delay the operation to a
 584       certain maximum time. The method returns a file descriptor. The lock is released the moment this file
 585       descriptor and all its duplicates are closed. For more information on the inhibition logic see
 586       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
 587       </para>
 588     </refsect2>
 589
 590     <refsect2>
 591       <title>Signals</title>
 592
 593       <para>Whenever the inhibition state or idle hint changes, <function>PropertyChanged</function>
 594       signals are sent out to which clients can subscribe.</para>
 595
 596       <para>The <function>SessionNew</function>, <function>SessionRemoved</function>,
 597       <function>UserNew</function>, <function>UserRemoved</function>, <function>SeatNew</function>, and
 598       <function>SeatRemoved</function> signals are sent each time a session is created or removed, a user
 599       logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object
 600       path.</para>
 601
 602       <para>The <function>PrepareForShutdown()</function> and <function>PrepareForSleep()</function> signals
 603       are sent right before (with the argument <literal>true</literal>) or after (with the argument
 604       <literal>false</literal>) the system goes down for reboot/poweroff and suspend/hibernate,
 605       respectively. This may be used by applications to save data on disk, release memory, or do other jobs
 606       that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After
 607       completion of this work they should release their inhibition locks in order to not delay the operation
 608       any further. For more information see
 609       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
 610       </para>
 611     </refsect2>
 612
 613     <refsect2>
 614       <title>Properties</title>
 615
 616       <para>Most properties simply reflect the configuration, see
 617       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 618       includes: <varname>NAutoVTs</varname>, <varname>KillOnlyUsers</varname>,
 619       <varname>KillExcludeUsers</varname>, <varname>KillUserProcesses</varname>, <varname>IdleAction</varname>,
 620       <varname>InhibitDelayMaxUSec</varname>,
 621       <varname>InhibitorsMax</varname>,
 622       <varname>UserStopDelayUSec</varname>,
 623       <varname>HandlePowerKey</varname>, <varname>HandleSuspendKey</varname>,
 624       <varname>HandleHibernateKey</varname>, <varname>HandleLidSwitch</varname>,
 625       <varname>HandleLidSwitchExternalPower</varname>, <varname>HandleLidSwitchDocked</varname>,
 626       <varname>IdleActionUSec</varname>, <varname>HoldoffTimeoutUSec</varname>,
 627       <varname>RemoveIPC</varname>, <varname>RuntimeDirectorySize</varname>,
 628       <varname>InhibitorsMax</varname>, and <varname>SessionsMax</varname>.
 629       </para>
 630
 631       <para>The <varname>IdleHint</varname> property reflects the idle hint state of the system. If the
 632       system is idle it might get into automatic suspend or shutdown depending on the configuration.</para>
 633
 634       <para><varname>IdleSinceHint</varname> and <varname>IdleSinceHintMonotonic</varname> encode the
 635       timestamps of the last change of the idle hint boolean, in <constant>CLOCK_REALTIME</constant> and
 636       <constant>CLOCK_MONOTONIC</constant> timestamps, respectively, in microseconds since the epoch.</para>
 637
 638       <para>The <varname>BlockInhibited</varname> and <varname>DelayInhibited</varname> properties encode
 639       the currently active locks of the respective modes. They are colon separated lists of
 640       <literal>shutdown</literal>, <literal>sleep</literal>, and <literal>idle</literal> (see above).</para>
 641
 642       <para><varname>NCurrentSessions</varname> and <varname>NCurrentInhibitors</varname> contain the number
 643       of currently registered sessions and inhibitors.</para>
 644
 645       <para>The <varname>BootLoaderEntries</varname> property contains a list of boot loader entries.
 646       This includes boot loader entries defined in configuration and any additional loader entries
 647       reported by the boot loader. See
 648       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 649       for more information.</para>
 650
 651       <para>The <varname>PreparingForShutdown</varname> and <varname>PreparingForSleep</varname> boolean
 652       properties are true during the interval between the two <function>PrepareForShutdown</function> and
 653       <function>PrepareForSleep</function> signals respectively. Note that these properties do not
 654       send out <function>PropertyChanged</function> signals.</para>
 655
 656       <para>The <varname>RebootParameter</varname> property shows the value set with the
 657       <function>SetRebootParameter()</function> method described above.</para>
 658
 659       <para><varname>ScheduledShutdown</varname> shows the value pair set with the
 660       <function>ScheduleShutdown()</function> method described above.</para>
 661
 662       <para><varname>RebootToFirmwareSetup</varname>, <varname>RebootToBootLoaderMenu</varname>, and
 663       <varname>RebootToBootLoaderEntry</varname> are true when the resprective post-reboot operation was
 664       selected with <function>SetRebootToFirmwareSetup</function>,
 665       <function>SetRebootToBootLoaderMenu</function>, or
 666       <function>SetRebootToBootLoaderEntry</function>.</para>
 667
 668       <para>The <varname>WallMessage</varname> and <varname>EnableWallMessages</varname> properties reflect the
 669       shutdown reason and wall message enablement switch which can be set with the
 670       <function>SetWallMessage()</function> method described above.</para>
 671
 672       <para><varname>Docked</varname> is true if the machine is connected to a dock.
 673       <varname>LidClosed</varname> is true when the lid (of a laptop) is closed.
 674       <varname>OnExternalPower</varname> is true when the machine is connected to an external power supply.
 675       </para>
 676     </refsect2>
 677
 678     <refsect2>
 679       <title>Security</title>
 680
 681       <para>A number of operations are protected via the PolicyKit privilege
 682       system. <function>SetUserLinger()</function> requires the
 683       <interfacename>org.freedesktop.login1.set-user-linger</interfacename>
 684       privilege. <function>AttachDevice()</function> requires
 685       <interfacename>org.freedesktop.login1.attach-device</interfacename> and
 686       <function>FlushDevices()</function> requires
 687       <interfacename>org.freedesktop.login1.flush-devices</interfacename>. <function>PowerOff()</function>,
 688       <function>Reboot()</function>, <function>Halt()</function>, <function>Suspend()</function>,
 689       <function>Hibernate()</function> require
 690       <interfacename>org.freedesktop.login1.power-off</interfacename>,
 691       <interfacename>org.freedesktop.login1.power-off-multiple-sessions</interfacename>,
 692       <interfacename>org.freedesktop.login1.power-off-ignore-inhibit</interfacename>,
 693       <interfacename>org.freedesktop.login1.reboot</interfacename>,
 694       <interfacename>org.freedesktop.login1.reboot-multiple-sessions</interfacename>,
 695       <interfacename>org.freedesktop.login1.reboot-ignore-inhibit</interfacename>,
 696       <interfacename>org.freedesktop.login1.halt</interfacename>,
 697       <interfacename>org.freedesktop.login1.halt-multiple-sessions</interfacename>,
 698       <interfacename>org.freedesktop.login1.halt-ignore-inhibit</interfacename>,
 699       <interfacename>org.freedesktop.login1.suspend</interfacename>,
 700       <interfacename>org.freedesktop.login1.suspend-multiple-sessions</interfacename>,
 701       <interfacename>org.freedesktop.login1.suspend-ignore-inhibit</interfacename>,
 702       <interfacename>org.freedesktop.login1.hibernate</interfacename>,
 703       <interfacename>org.freedesktop.login1.hibernate-multiple-sessions</interfacename>,
 704       <interfacename>org.freedesktop.login1.hibernate-ignore-inhibit</interfacename>,
 705       respectively depending on whether there are other sessions around or active inhibits are present.
 706       <function>HybridSleep()</function> and <function>SuspendThenHibernate()</function>
 707       use the same privileges as <function>Hibernate()</function>.
 708       <function>SetRebootParameter()</function> requires
 709       <interfacename>org.freedesktop.login1.set-reboot-parameter</interfacename>.</para>
 710
 711       <para><function>SetRebootToFirmwareSetup</function> requires
 712       <interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup</interfacename>.
 713       <function>SetRebootToBootLoaderMenu</function> requires
 714       <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu</interfacename>.
 715       <function>SetRebootToBootLoaderEntry</function> requires
 716       <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-entry</interfacename>.
 717       </para>
 718
 719       <para><function>ScheduleShutdown</function> and <function>CancelScheduledShutdown</function> require
 720       the same privileges (listed above) as the immediate poweroff/reboot/halt operations.</para>
 721
 722       <para><function>Inhibit()</function> is protected via one of
 723       <interfacename>org.freedesktop.login1.inhibit-block-shutdown</interfacename>,
 724       <interfacename>org.freedesktop.login1.inhibit-delay-shutdown</interfacename>,
 725       <interfacename>org.freedesktop.login1.inhibit-block-sleep</interfacename>,
 726       <interfacename>org.freedesktop.login1.inhibit-delay-sleep</interfacename>,
 727       <interfacename>org.freedesktop.login1.inhibit-block-idle</interfacename>,
 728       <interfacename>org.freedesktop.login1.inhibit-handle-power-key</interfacename>,
 729       <interfacename>org.freedesktop.login1.inhibit-handle-suspend-key</interfacename>,
 730       <interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key</interfacename>,
 731       <interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock
 732       type and mode taken.</para>
 733
 734       <para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
 735       should interactively ask the user for authentication credentials if required.</para>
 736     </refsect2>
 737   </refsect1>
 738
 739   <refsect1>
 740     <title>Seat Objects</title>
 741
 742     <programlisting>
 743 $ gdbus introspect --system --dest org.freedesktop.login1 \
 744       --object-path /org/freedesktop/login1/seat/seat0
 745
 746 node /org/freedesktop/login1/seat/seat0 {
 747   interface org.freedesktop.login1.Seat {
 748     methods:
 749       Terminate();
 750       ActivateSession(in  s session_id);
 751       SwitchTo(in  u vtnr);
 752       SwitchToNext();
 753       SwitchToPrevious();
 754     properties:
 755       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 756       readonly s Id = '...';
 757       readonly (so) ActiveSession = ...;
 758       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 759       readonly b CanMultiSession = ...;
 760       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 761       readonly b CanTTY = ...;
 762       readonly b CanGraphical = ...;
 763       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 764       readonly a(so) Sessions = [...];
 765       readonly b IdleHint = ...;
 766       readonly t IdleSinceHint = ...;
 767       readonly t IdleSinceHintMonotonic = ...;
 768   };
 769   interface org.freedesktop.DBus.Peer { ... };
 770   interface org.freedesktop.DBus.Introspectable { ... };
 771   interface org.freedesktop.DBus.Properties { ... };
 772 };
 773     </programlisting>
 774
 775     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 776
 777     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Seat"/>
 778
 779     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Seat"/>
 780
 781     <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
 782
 783     <variablelist class="dbus-method" generated="True" extra-ref="ActivateSession()"/>
 784
 785     <variablelist class="dbus-method" generated="True" extra-ref="SwitchTo()"/>
 786
 787     <variablelist class="dbus-method" generated="True" extra-ref="SwitchToNext()"/>
 788
 789     <variablelist class="dbus-method" generated="True" extra-ref="SwitchToPrevious()"/>
 790
 791     <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
 792
 793     <variablelist class="dbus-property" generated="True" extra-ref="ActiveSession"/>
 794
 795     <variablelist class="dbus-property" generated="True" extra-ref="CanMultiSession"/>
 796
 797     <variablelist class="dbus-property" generated="True" extra-ref="CanTTY"/>
 798
 799     <variablelist class="dbus-property" generated="True" extra-ref="CanGraphical"/>
 800
 801     <variablelist class="dbus-property" generated="True" extra-ref="Sessions"/>
 802
 803     <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
 804
 805     <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
 806
 807     <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
 808
 809     <!--End of Autogenerated section-->
 810
 811     <refsect2>
 812       <title>Methods</title>
 813
 814       <para><function>Terminate()</function> and <function>ActivateSession()</function> work similar to
 815       TerminateSeat(), ActivationSessionOnSeat() on the Manager object.</para>
 816
 817       <para><function>SwitchTo()</function> switches to the session on the virtual terminal
 818       <varname>vtnr</varname>. <function>SwitchToNext()</function> and
 819       <function>SwitchToPrevious()</function> switch to, respectively, the next and previous sessions on the
 820       seat in the order of virtual terminals. If there is no active session, they switch to, respectively,
 821       the first and last session on the seat.</para>
 822     </refsect2>
 823
 824     <refsect2>
 825       <title>Signals</title>
 826
 827       <para>Whenever <function>ActiveSession</function>, <function>Sessions</function>,
 828       <function>CanGraphical</function>, <function>CanMultiSession</function> and <function>CanTTY</function>
 829       or the idle state changes, <function>PropertyChanged</function> signals are sent out to which clients
 830       can subscribe.</para>
 831     </refsect2>
 832
 833     <refsect2>
 834       <title>Properties</title>
 835
 836       <para>The <varname>Id</varname> property encodes the ID of the seat.</para>
 837
 838       <para><varname>ActiveSession</varname> encodes the currently active session if there is one. It is a
 839       structure consisting of the session id and the object path.</para>
 840
 841       <para><varname>CanMultiSession</varname> encodes whether the session is multi-session capable,
 842       <varname>CanTTY</varname> whether it is suitable for text logins, <varname>CanGraphical</varname>
 843       whether it is suitable for graphical sessions.</para>
 844
 845       <para>The <varname>Sessions</varname> property is an array of all current sessions of this seat, each
 846       encoded in a structure consisting of the ID and the object path.</para>
 847
 848       <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
 849       <varname>IdleSinceHint</varname> properties encode the idle state, similar to the one exposed on the
 850       Manager object, but specific for this seat.</para>
 851     </refsect2>
 852   </refsect1>
 853
 854   <refsect1>
 855     <title>User Objects</title>
 856
 857     <programlisting>
 858 $ gdbus introspect --system --dest org.freedesktop.login1 \
 859         --object-path /org/freedesktop/login1/user/_1000
 860
 861 node /org/freedesktop/login1/user/_1000 {
 862   interface org.freedesktop.login1.User {
 863     methods:
 864       Terminate();
 865       Kill(in  i signal_number);
 866     properties:
 867       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 868       readonly u UID = ...;
 869       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 870       readonly u GID = ...;
 871       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 872       readonly s Name = '...';
 873       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 874       readonly t Timestamp = ...;
 875       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 876       readonly t TimestampMonotonic = ...;
 877       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 878       readonly s RuntimePath = '...';
 879       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 880       readonly s Service = '...';
 881       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 882       readonly s Slice = '...';
 883       readonly (so) Display = ...;
 884       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 885       readonly s State = '...';
 886       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 887       readonly a(so) Sessions = [...];
 888       readonly b IdleHint = ...;
 889       readonly t IdleSinceHint = ...;
 890       readonly t IdleSinceHintMonotonic = ...;
 891       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 892       readonly b Linger = ...;
 893   };
 894   interface org.freedesktop.DBus.Peer { ... };
 895   interface org.freedesktop.DBus.Introspectable { ... };
 896   interface org.freedesktop.DBus.Properties { ... };
 897 };
 898     </programlisting>
 899
 900     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 901
 902     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.User"/>
 903
 904     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.User"/>
 905
 906     <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
 907
 908     <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/>
 909
 910     <variablelist class="dbus-property" generated="True" extra-ref="UID"/>
 911
 912     <variablelist class="dbus-property" generated="True" extra-ref="GID"/>
 913
 914     <variablelist class="dbus-property" generated="True" extra-ref="Name"/>
 915
 916     <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/>
 917
 918     <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/>
 919
 920     <variablelist class="dbus-property" generated="True" extra-ref="RuntimePath"/>
 921
 922     <variablelist class="dbus-property" generated="True" extra-ref="Service"/>
 923
 924     <variablelist class="dbus-property" generated="True" extra-ref="Slice"/>
 925
 926     <variablelist class="dbus-property" generated="True" extra-ref="Display"/>
 927
 928     <variablelist class="dbus-property" generated="True" extra-ref="State"/>
 929
 930     <variablelist class="dbus-property" generated="True" extra-ref="Sessions"/>
 931
 932     <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
 933
 934     <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
 935
 936     <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
 937
 938     <variablelist class="dbus-property" generated="True" extra-ref="Linger"/>
 939
 940     <!--End of Autogenerated section-->
 941
 942     <refsect2>
 943       <title>Methods</title>
 944
 945       <para><function>Terminate()</function> and <function>Kill()</function> work similar to the
 946       <function>TerminateUser()</function> and <function>KillUser()</function> methods on the manager
 947       object.</para>
 948     </refsect2>
 949
 950     <refsect2>
 951       <title>Signals</title>
 952
 953       <para>Whenever <varname>Sessions</varname> or the idle state changes,
 954       <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
 955     </refsect2>
 956
 957     <refsect2>
 958       <title>Properties</title>
 959
 960       <para>The <varname>UID</varname> and <varname>GID</varname> properties encode the Unix UID and primary
 961       GID of the user.</para>
 962
 963       <para>The <varname>Name</varname> property encodes the user name.</para>
 964
 965       <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the login time of
 966       the user in microseconds since the epoch, in the <constant>CLOCK_REALTIME</constant> and
 967       <constant>CLOCK_MONOTONIC</constant> clocks, respectively.</para>
 968
 969       <para><varname>RuntimePath</varname> encodes the runtime path of the user,
 970       i.e. <varname>$XDG_RUNTIME_DIR</varname>. For details see the
 971       <ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
 972         XDG Basedir Specification
 973       </ulink>.</para>
 974
 975       <para><varname>Service</varname> contains the unit name of the user systemd service of this
 976       user. Each logged in user is assigned a user service that runs a user systemd instance. This is
 977       usually an instance of <filename>user@.service</filename>.</para>
 978
 979       <para><varname>Slice</varname> contains the unit name of the user systemd slice of this user. Each
 980       logged in user gets a private slice.</para>
 981
 982       <para><varname>Display</varname> encodes which graphical session should be used as the primary UI display
 983       for the user. It is a structure encoding the session ID and the object path of the session to use.</para>
 984
 985       <para><varname>State</varname> encodes the user state and is one of <literal>offline</literal>,
 986       <literal>lingering</literal>, <literal>online</literal>, <literal>active</literal>, or
 987       <literal>closing</literal>. See
 988       <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 989       for more information about the states.</para>
 990
 991       <para><varname>Sessions</varname> is an array of structures encoding all current sessions of the
 992       user. Each structure consists of the ID and object path.</para>
 993
 994       <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
 995       <varname>IdleSinceHintMonotonic</varname> properties encode the idle hint state of the user, similar to
 996       the <interfacename>Manager</interfacename>'s properties, but specific for this user.</para>
 997
 998       <para>The <varname>Linger</varname> property shows whether lingering is enabled for this user.</para>
 999     </refsect2>
1000   </refsect1>
1001
1002   <refsect1>
1003     <title>Session Objects</title>
1004
1005     <programlisting>
1006 $ gdbus introspect --system --dest org.freedesktop.login1 \
1007         --object-path /org/freedesktop/login1/session/45
1008
1009 node /org/freedesktop/login1/session/45 {
1010   interface org.freedesktop.login1.Session {
1011     methods:
1012       Terminate();
1013       Activate();
1014       Lock();
1015       Unlock();
1016       SetIdleHint(in  b idle);
1017       SetLockedHint(in  b locked);
1018       Kill(in  s who,
1019            in  i signal_number);
1020       TakeControl(in  b force);
1021       ReleaseControl();
1022       TakeDevice(in  u major,
1023                  in  u minor,
1024                  out h fd,
1025                  out b inactive);
1026       ReleaseDevice(in  u major,
1027                     in  u minor);
1028       PauseDeviceComplete(in  u major,
1029                           in  u minor);
1030       SetBrightness(in  s subsystem,
1031                     in  s name,
1032                     in  u brightness);
1033     signals:
1034       PauseDevice(u major,
1035                   u minor,
1036                   s type);
1037       ResumeDevice(u major,
1038                    u minor,
1039                    h fd);
1040       Lock();
1041       Unlock();
1042     properties:
1043       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1044       readonly s Id = '...';
1045       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1046       readonly (uo) User = ...;
1047       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1048       readonly s Name = '...';
1049       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1050       readonly t Timestamp = ...;
1051       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1052       readonly t TimestampMonotonic = ...;
1053       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1054       readonly u VTNr = ...;
1055       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1056       readonly (so) Seat = ...;
1057       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1058       readonly s TTY = '...';
1059       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1060       readonly s Display = '...';
1061       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1062       readonly b Remote = ...;
1063       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1064       readonly s RemoteHost = '...';
1065       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1066       readonly s RemoteUser = '...';
1067       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1068       readonly s Service = '...';
1069       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1070       readonly s Desktop = '...';
1071       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1072       readonly s Scope = '...';
1073       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1074       readonly u Leader = ...;
1075       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1076       readonly u Audit = ...;
1077       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1078       readonly s Type = '...';
1079       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
1080       readonly s Class = '...';
1081       readonly b Active = ...;
1082       readonly s State = '...';
1083       readonly b IdleHint = ...;
1084       readonly t IdleSinceHint = ...;
1085       readonly t IdleSinceHintMonotonic = ...;
1086       readonly b LockedHint = ...;
1087   };
1088   interface org.freedesktop.DBus.Peer { ... };
1089   interface org.freedesktop.DBus.Introspectable { ... };
1090   interface org.freedesktop.DBus.Properties { ... };
1091 };
1092     </programlisting>
1093
1094     <refsect2>
1095       <title>Methods</title>
1096
1097       <para><function>Terminate()</function>, <function>Activate()</function>, <function>Lock()</function>,
1098       <function>Unlock()</function>, and <function>Kill()</function> work similarly to the respective calls on
1099       the <interfacename>Manager</interfacename> object.</para>
1100
1101       <para><function>SetIdleHint()</function> is called by the session object to update the idle state
1102       of the session whenever it changes.</para>
1103
1104       <para><function>TakeControl()</function> allows a process to take exclusive managed device
1105       access-control for that session. Only one D-Bus connection can be a controller for a given session at any
1106       time. If the <varname>force</varname> argument is set (root only), an existing controller is kicked
1107       out and replaced. Otherwise, this method fails if there is already a controller. Note that this method is
1108       limited to D-Bus users with the effective UID set to the user of the session or root.</para>
1109
1110       <para><function>ReleaseControl()</function> drops control of a given session. Closing the
1111       D-Bus connection implicitly releases control as well. See <function>TakeControl()</function> for more information. This
1112       method also releases all devices for which the controller requested ownership via <function>TakeDevice()</function>.
1113       </para>
1114
1115       <para><function>TakeDevice()</function> allows a session controller to get a file descriptor for a
1116       specific device. Pass in the major and minor numbers of the character device and
1117       <filename>systemd-logind</filename> will return a file descriptor for the device. Only a limited set of
1118       device-types is currently supported (but may be extended). <filename>systemd-logind</filename>
1119       automatically mutes the file descriptor if the session is inactive and resumes it once the session is
1120       activated again. This guarantees that a session can only access session devices if the session is
1121       active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time.  This
1122       only works on devices that are attached to the seat of the given session. A process is not required to
1123       have direct access to the device node. <filename>systemd-logind</filename> only requires you to be the
1124       active session controller (see <function>TakeControl()</function>). Also note that any device can only
1125       be requested once. As long as you don't release it, further <function>TakeDevice()</function> calls
1126       will fail.</para>
1127
1128       <para><function>ReleaseDevice()</function> releases a device again (see
1129       <function>TakeDevice()</function>). This is also implicitly done by
1130       <function>ReleaseControl()</function> or when closing the D-Bus connection.</para>
1131
1132       <para><function>PauseDeviceComplete()</function> allows a session controller to synchronously pause a
1133       device after receiving a <function>PauseDevice(<literal>pause</literal>)</function> signal. Forced
1134       signals (or after an internal timeout) are automatically completed by
1135       <filename>systemd-logind</filename> asynchronously.</para>
1136
1137       <para><function>SetLockedHint()</function> may be used to set the "idle hint" to
1138       <varname>locked</varname>, i.e. information whether the session is locked. This is intended to be used
1139       by the desktop environment to tell <command>systemd-logind</command> when the session is locked and
1140       unlocked.</para>
1141
1142       <para><function>SetBrightness()</function> may be used to set the display brightness. This is intended
1143       to be used by the desktop environment and allows unprivileged programs to access hardware settings in
1144       a controlled way. The <varname>subsystem</varname> parameter specifies a kernel subsystem, either
1145       <literal>backlight</literal> or <literal>leds</literal>. The <varname>name</varname> parameter
1146       specifies a device name under the specified subsystem. The <varname>brightness</varname> parameter
1147       specifies the brightness. The range is defined by individual drivers, see
1148       <filename>/sys/class/<varname>subsystem</varname>/<varname>name</varname>/max_brightness</filename>.
1149       </para>
1150     </refsect2>
1151
1152     <refsect2>
1153       <title>Signals</title>
1154
1155       <para>The active session controller exclusively gets <function>PauseDevice</function> and
1156       <function>ResumeDevice</function> events for any device it requested via
1157       <function>TakeDevice()</function>. They notify the controller whenever a device is paused or resumed. A
1158       device is never resumed if its session is inactive. Also note that <function>PauseDevice</function>
1159       signals are sent before the <function>PropertyChanged</function> signal for the
1160       <function>Active</function> state. The inverse is true for <function>ResumeDevice</function>. A device
1161       may remain paused for unknown reasons even though the <interfacename>Session</interfacename> is active.
1162       </para>
1163
1164       <para>A <function>PauseDevice</function> signal carries the major and minor numbers and a string describing the
1165       type as arguments. <function>force</function> means the device was already paused by
1166       <filename>systemd-logind</filename> and the signal is only an asynchronous
1167       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
1168       <function>PauseDeviceComplete()</function>. This synchronous pausing mechanism is used for
1169       backwards-compatibility to VTs and <filename>systemd-logind</filename> is free to not make use of
1170       it. It is also free to send a forced <function>PauseDevice</function> if you don't respond in a timely
1171       manner (or for any other reason). <function>gone</function> means the device was unplugged from the
1172       system and you will no longer get any notifications about it. There is no need to call
1173       <function>ReleaseDevice()</function>. You may call <function>TakeDevice()</function> again if a new
1174       device is assigned the major+minor combination.</para>
1175
1176       <para><function>ResumeDevice</function> is sent whenever a session is active and a device is
1177       resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should
1178       switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying
1179       open file descriptor in the kernel (except for a limited set of device types).</para>
1180
1181       <para>Whenever <function>Active</function> or the idle state changes,
1182       <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
1183
1184       <para><function>Lock</function>/<function>Unlock</function> is sent when the session is asked to be
1185       screen-locked/unlocked. A session manager of the session should listen to this signal and act
1186       accordingly. This signal is sent out as a result of the <function>Lock()</function> and
1187       <function>Unlock()</function> methods, respectively.</para>
1188     </refsect2>
1189
1190     <refsect2>
1191       <title>Properties</title>
1192
1193       <para><varname>Id</varname> encodes the session ID.</para>
1194
1195       <para><varname>User</varname> encodes the user ID of the user this session belongs to. This is a
1196       structure consisting of the Unix UID and the object path.</para>
1197
1198       <para><varname>Name</varname> encodes the user name.</para>
1199
1200       <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the microseconds
1201       since the epoch when the session was created, in <constant>CLOCK_REALTIME</constant> or
1202       <constant>CLOCK_MONOTONIC</constant>, respectively.</para>
1203
1204       <para><varname>VTNr</varname> encodes the virtual terminal number of the session if there is any, 0
1205       otherwise.</para>
1206
1207       <para><varname>Seat</varname> encodes the seat this session belongs to if there is any. This is a
1208       structure consisting of the ID and the seat object path.</para>
1209
1210       <para><varname>TTY</varname> encodes the kernel TTY path of the session if this is a text login. If not
1211       this is an empty string.</para>
1212
1213       <para><varname>Display</varname> encodes the X11 display name if this is a graphical login. If not,
1214       this is an empty string.</para>
1215
1216       <para><varname>Remote</varname> encodes whether the session is local or remote.</para>
1217
1218       <para><varname>RemoteHost</varname> and <varname>RemoteUser</varname> encode the remote host and user
1219       if this is a remote session, or an empty string otherwise.</para>
1220
1221       <para><varname>Service</varname> encodes the PAM service name that registered the session.</para>
1222
1223       <para><varname>Desktop</varname> describes the desktop environment running in the session (if
1224       known).</para>
1225
1226       <para><varname>Scope</varname> contains the systemd scope unit name of this session.</para>
1227
1228       <para><varname>Leader</varname> encodes the PID of the process that registered the session.</para>
1229
1230       <para><varname>Audit</varname> encodes the Kernel Audit session ID of the session if auditing is
1231       available.</para>
1232
1233       <para><varname>Type</varname> encodes the session type. It's one of <literal>unspecified</literal> (for
1234       cron PAM sessions and suchlike), <literal>tty</literal> (for text logins) or
1235       <literal>x11</literal>/<literal>mir</literal>/<literal>wayland</literal> (for graphical logins).</para>
1236
1237       <para><varname>Class</varname> encodes the session class. It's one of <literal>user</literal> (for
1238       normal user sessions), <literal>greeter</literal> (for display manager pseudo-sessions), or
1239       <literal>lock-screen</literal> (for display lock screens).</para>
1240
1241       <para><varname>Active</varname> is a boolean that is true if the session is active, i.e. currently in the
1242       foreground. This field is semi-redundant due to <varname>State</varname>.</para>
1243
1244       <para><varname>State</varname> encodes the session state and one of <literal>online</literal>,
1245       <literal>active</literal>, or <literal>closing</literal>. See
1246       <citerefentry><refentrytitle>sd_session_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
1247       for more information about the states.</para>
1248
1249       <para><varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
1250       <varname>IdleSinceHintMonotonic</varname> encapsulate the idle hint state of this session, similarly to
1251       how the respective properties on the manager object do it for the whole system.</para>
1252
1253       <para><varname>LockedHint</varname> shows the locked hint state of this session, as set by the
1254       <function>SetLockedHint()</function> method described above.</para>
1255     </refsect2>
1256   </refsect1>
1257
1258   <refsect1>
1259     <title>Versioning</title>
1260
1261     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
1262     the usual interface versioning guidelines</ulink>.</para>
1263   </refsect1>
1264 </refentry>