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