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