diff options
Diffstat (limited to 'man/org.freedesktop.login1.xml')
| -rw-r--r-- | man/org.freedesktop.login1.xml | 1489 |
1 files changed, 1489 insertions, 0 deletions
diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml new file mode 100644 index 0000000..639b09a --- /dev/null +++ b/man/org.freedesktop.login1.xml @@ -0,0 +1,1489 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="org.freedesktop.login1" conditional='ENABLE_LOGIND' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>org.freedesktop.login1</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>org.freedesktop.login1</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>org.freedesktop.login1</refname> + <refpurpose>The D-Bus interface of systemd-logind</refpurpose> + </refnamediv> + + <refsect1> + <title>Introduction</title> + + <para><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is a system service that keeps track of user logins and seats.</para> + + <para>The daemon provides both a C library interface as well as a D-Bus interface. The library interface + may be used to introspect and watch the state of user logins and seats. The bus interface provides the + same functionality but in addition may also be used to make changes to the system state. For more information please + consult <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>The Manager Object</title> + + <para>The service exposes the following interfaces on the Manager object on the bus:</para> + + <programlisting executable="systemd-logind" node="/org/freedesktop/login1" interface="org.freedesktop.login1.Manager"> +node /org/freedesktop/login1 { + interface org.freedesktop.login1.Manager { + methods: + GetSession(in s session_id, + out o object_path); + GetSessionByPID(in u pid, + out o object_path); + GetUser(in u uid, + out o object_path); + GetUserByPID(in u pid, + out o object_path); + GetSeat(in s seat_id, + out o object_path); + ListSessions(out a(susso) sessions); + ListUsers(out a(uso) users); + ListSeats(out a(so) seats); + ListInhibitors(out a(ssssuu) inhibitors); + @org.freedesktop.systemd1.Privileged("true") + CreateSession(in u uid, + in u pid, + in s service, + in s type, + in s class, + in s desktop, + in s seat_id, + in u vtnr, + in s tty, + in s display, + in b remote, + in s remote_user, + in s remote_host, + in a(sv) properties, + out s session_id, + out o object_path, + out s runtime_path, + out h fifo_fd, + out u uid, + out s seat_id, + out u vtnr, + out b existing); + @org.freedesktop.systemd1.Privileged("true") + ReleaseSession(in s session_id); + ActivateSession(in s session_id); + ActivateSessionOnSeat(in s session_id, + in s seat_id); + LockSession(in s session_id); + UnlockSession(in s session_id); + LockSessions(); + UnlockSessions(); + KillSession(in s session_id, + in s who, + in i signal_number); + KillUser(in u uid, + in i signal_number); + TerminateSession(in s session_id); + TerminateUser(in u uid); + TerminateSeat(in s seat_id); + SetUserLinger(in u uid, + in b enable, + in b interactive); + AttachDevice(in s seat_id, + in s sysfs_path, + in b interactive); + FlushDevices(in b interactive); + PowerOff(in b interactive); + PowerOffWithFlags(in t flags); + Reboot(in b interactive); + RebootWithFlags(in t flags); + Halt(in b interactive); + HaltWithFlags(in t flags); + Suspend(in b interactive); + SuspendWithFlags(in t flags); + Hibernate(in b interactive); + HibernateWithFlags(in t flags); + HybridSleep(in b interactive); + HybridSleepWithFlags(in t flags); + SuspendThenHibernate(in b interactive); + SuspendThenHibernateWithFlags(in t flags); + CanPowerOff(out s result); + CanReboot(out s result); + CanHalt(out s result); + CanSuspend(out s result); + CanHibernate(out s result); + CanHybridSleep(out s result); + CanSuspendThenHibernate(out s result); + ScheduleShutdown(in s type, + in t usec); + CancelScheduledShutdown(out b cancelled); + Inhibit(in s what, + in s who, + in s why, + in s mode, + out h pipe_fd); + CanRebootParameter(out s result); + SetRebootParameter(in s parameter); + CanRebootToFirmwareSetup(out s result); + SetRebootToFirmwareSetup(in b enable); + CanRebootToBootLoaderMenu(out s result); + SetRebootToBootLoaderMenu(in t timeout); + CanRebootToBootLoaderEntry(out s result); + SetRebootToBootLoaderEntry(in s boot_loader_entry); + SetWallMessage(in s wall_message, + in b enable); + signals: + SessionNew(s session_id, + o object_path); + SessionRemoved(s session_id, + o object_path); + UserNew(u uid, + o object_path); + UserRemoved(u uid, + o object_path); + SeatNew(s seat_id, + o object_path); + SeatRemoved(s seat_id, + o object_path); + PrepareForShutdown(b start); + PrepareForSleep(b start); + properties: + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + @org.freedesktop.systemd1.Privileged("true") + readwrite b EnableWallMessages = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + @org.freedesktop.systemd1.Privileged("true") + readwrite s WallMessage = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u NAutoVTs = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as KillOnlyUsers = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as KillExcludeUsers = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b KillUserProcesses = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s RebootParameter = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b RebootToFirmwareSetup = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t RebootToBootLoaderMenu = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s RebootToBootLoaderEntry = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as BootLoaderEntries = ['...', ...]; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + readonly s BlockInhibited = '...'; + readonly s DelayInhibited = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t InhibitDelayMaxUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t UserStopDelayUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandlePowerKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandlePowerKeyLongPress = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleRebootKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleRebootKeyLongPress = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleSuspendKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleSuspendKeyLongPress = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleHibernateKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleHibernateKeyLongPress = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleLidSwitch = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleLidSwitchExternalPower = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleLidSwitchDocked = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t HoldoffTimeoutUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s IdleAction = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t IdleActionUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b PreparingForShutdown = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b PreparingForSleep = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly (st) ScheduledShutdown = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b Docked = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b LidClosed = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b OnExternalPower = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b RemoveIPC = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t RuntimeDirectorySize = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t RuntimeDirectoryInodesMax = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t InhibitorsMax = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t NCurrentInhibitors = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t SessionsMax = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t NCurrentSessions = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t StopIdleSessionUSec = ...; + }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; +}; + </programlisting> + + <!--property HandlePowerKeyLongPress is not documented!--> + + <!--property HandleRebootKey is not documented!--> + + <!--property HandleRebootKeyLongPress is not documented!--> + + <!--property HandleSuspendKeyLongPress is not documented!--> + + <!--property HandleHibernateKeyLongPress is not documented!--> + + <!--property StopIdleSessionUSec is not documented!--> + + <!--Autogenerated cross-references for systemd.directives, do not edit--> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Manager"/> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Manager"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetSessionByPID()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetUser()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetUserByPID()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetSeat()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ListSessions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ListUsers()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ListSeats()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ListInhibitors()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CreateSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ReleaseSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ActivateSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ActivateSessionOnSeat()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="LockSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="UnlockSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="LockSessions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="UnlockSessions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="KillSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="KillUser()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="TerminateSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="TerminateUser()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="TerminateSeat()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetUserLinger()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="AttachDevice()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="FlushDevices()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="PowerOff()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="PowerOffWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Reboot()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="RebootWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Halt()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="HaltWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Suspend()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SuspendWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Hibernate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="HibernateWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="HybridSleep()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="HybridSleepWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SuspendThenHibernate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SuspendThenHibernateWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanPowerOff()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanReboot()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanHalt()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanSuspend()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanHibernate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanHybridSleep()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanSuspendThenHibernate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ScheduleShutdown()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CancelScheduledShutdown()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Inhibit()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanRebootParameter()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetRebootParameter()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToFirmwareSetup()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToFirmwareSetup()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToBootLoaderMenu()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToBootLoaderMenu()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CanRebootToBootLoaderEntry()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetRebootToBootLoaderEntry()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetWallMessage()"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="SessionNew"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="SessionRemoved"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="UserNew"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="UserRemoved"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="SeatNew"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="SeatRemoved"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForShutdown"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForSleep"/> + + <variablelist class="dbus-property" generated="True" extra-ref="EnableWallMessages"/> + + <variablelist class="dbus-property" generated="True" extra-ref="WallMessage"/> + + <variablelist class="dbus-property" generated="True" extra-ref="NAutoVTs"/> + + <variablelist class="dbus-property" generated="True" extra-ref="KillOnlyUsers"/> + + <variablelist class="dbus-property" generated="True" extra-ref="KillExcludeUsers"/> + + <variablelist class="dbus-property" generated="True" extra-ref="KillUserProcesses"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RebootParameter"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RebootToFirmwareSetup"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RebootToBootLoaderMenu"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RebootToBootLoaderEntry"/> + + <variablelist class="dbus-property" generated="True" extra-ref="BootLoaderEntries"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/> + + <variablelist class="dbus-property" generated="True" extra-ref="BlockInhibited"/> + + <variablelist class="dbus-property" generated="True" extra-ref="DelayInhibited"/> + + <variablelist class="dbus-property" generated="True" extra-ref="InhibitDelayMaxUSec"/> + + <variablelist class="dbus-property" generated="True" extra-ref="UserStopDelayUSec"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKey"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKeyLongPress"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleRebootKey"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleRebootKeyLongPress"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleSuspendKey"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleSuspendKeyLongPress"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleHibernateKey"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleHibernateKeyLongPress"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitch"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchExternalPower"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchDocked"/> + + <variablelist class="dbus-property" generated="True" extra-ref="HoldoffTimeoutUSec"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleAction"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleActionUSec"/> + + <variablelist class="dbus-property" generated="True" extra-ref="PreparingForShutdown"/> + + <variablelist class="dbus-property" generated="True" extra-ref="PreparingForSleep"/> + + <variablelist class="dbus-property" generated="True" extra-ref="ScheduledShutdown"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Docked"/> + + <variablelist class="dbus-property" generated="True" extra-ref="LidClosed"/> + + <variablelist class="dbus-property" generated="True" extra-ref="OnExternalPower"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RemoveIPC"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RuntimeDirectorySize"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RuntimeDirectoryInodesMax"/> + + <variablelist class="dbus-property" generated="True" extra-ref="InhibitorsMax"/> + + <variablelist class="dbus-property" generated="True" extra-ref="NCurrentInhibitors"/> + + <variablelist class="dbus-property" generated="True" extra-ref="SessionsMax"/> + + <variablelist class="dbus-property" generated="True" extra-ref="NCurrentSessions"/> + + <variablelist class="dbus-property" generated="True" extra-ref="StopIdleSessionUSec"/> + + <!--End of Autogenerated section--> + + <refsect2> + <title>Methods</title> + + <para><function>GetSession()</function> may be used to get the session object path for the session with + the specified ID. Similarly, <function>GetUser()</function> and <function>GetSeat()</function> get the + user and seat objects, respectively. <function>GetSessionByPID()</function> and + <function>GetUserByPID()</function> get the session/user object the specified PID belongs to if there + is any.</para> + + <para><function>ListSessions()</function> returns an array of all current sessions. The structures in + the array consist of the following fields: session id, user id, user name, seat id, session object + path. If a session does not have a seat attached, the seat id field will be an empty string.</para> + + <para><function>ListUsers()</function> returns an array of all currently logged in users. The + structures in the array consist of the following fields: user id, user name, user object path.</para> + + <para><function>ListSeats()</function> returns an array of all currently available seats. The + structure in the array consists of the following fields: seat id, seat object path.</para> + + <para><function>ListInhibitors()</function> lists all currently active inhibitors. It returns an array of + structures consisting of <varname>what</varname>, <varname>who</varname>, <varname>why</varname>, + <varname>mode</varname>, <varname>uid</varname> (user ID), and <varname>pid</varname> (process ID).</para> + + <para><function>CreateSession()</function> and <function>ReleaseSession()</function> may be used to + open or close login sessions. These calls should <emphasis>never</emphasis> be invoked directly by + clients. Creating/closing sessions is exclusively the job of PAM and its + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + module.</para> + + <para><function>ActivateSession()</function> brings the session with the specified ID into the + foreground. <function>ActivateSessionOnSeat()</function> does the same, but only if the seat id + matches.</para> + + <para><function>LockSession()</function> asks the session with the specified ID to activate the screen + lock. <function>UnlockSession()</function> asks the session with the specified ID to remove an active + screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from + the respective session object which session managers are supposed to listen on.</para> + + <para><function>LockSessions()</function> asks all sessions to activate their screen locks. This may be + used to lock access to the entire machine in one action. Similarly, <function>UnlockSessions()</function> + asks all sessions to deactivate their screen locks.</para> + + <para><function>KillSession()</function> may be used to send a Unix signal to one or all processes of a + session. As arguments it takes the session id, either the string <literal>leader</literal> or + <literal>all</literal> and a signal number. If <literal>leader</literal> is passed only the session + <literal>leader</literal> is killed. If <literal>all</literal> is passed all processes of the session + are killed.</para> + + <para><function>KillUser()</function> may be used to send a Unix signal to all processes of a user. As + arguments it takes the user id and a signal number.</para> + + <para><function>TerminateSession()</function>, <function>TerminateUser()</function>, + <function>TerminateSeat()</function> may be used to forcibly terminate one specific session, all + processes of a user, and all sessions attached to a specific seat, respectively. The session, user, + and seat are identified by their respective IDs.</para> + + <para><function>SetUserLinger()</function> enables or disables user lingering. If enabled, the runtime + directory of a user is kept around and they may continue to run processes while logged out. If + disabled, the runtime directory goes away as soon as they log out. <function>SetUserLinger()</function> + expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the + <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink> + authorization interactivity (see below). Note that the user linger state is persistently + stored on disk.</para> + + <para><function>AttachDevice()</function> may be used to assign a specific device to a specific + seat. The device is identified by its <filename>/sys/</filename> path and must be eligible for seat + assignments. <function>AttachDevice()</function> takes three arguments: the seat id, the sysfs path, + and a boolean for controlling polkit interactivity (see below). Device assignments are persistently + stored on disk. To create a new seat, simply specify a previously unused seat id. For more information + about the seat assignment logic see + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting + all assignments to the automatic defaults. The only argument it takes is the polkit interactivity + boolean (see below).</para> + + <para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Halt()</function>, + <function>Suspend()</function>, and <function>Hibernate()</function> result in the system being powered + off, rebooted, halted (shut down without turning off power), suspended (the system state is + saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and + the machine is powered down). <function>HybridSleep()</function> results in the system entering a + hybrid-sleep mode, i.e. the system is both hibernated and suspended. + <function>SuspendThenHibernate()</function> results in the system being suspended, then later woken + using an RTC timer and hibernated. The only argument is the polkit interactivity boolean + <varname>interactive</varname> (see below). The main purpose of these calls is that they enforce + polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged + users. They also enforce inhibition locks for non-privileged users. UIs should expose these calls + as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. Methods + <function>PowerOffWithFlags()</function>, <function>RebootWithFlags()</function>, + <function>HaltWithFlags()</function>, <function>SuspendWithFlags()</function>, + <function>HibernateWithFlags()</function>, <function>HybridSleepWithFlags()</function> and + <function>SuspendThenHibernateWithFlags()</function> add <varname>flags</varname> to allow for + extendability, defined as follows:</para> + <programlisting> +#define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0) +#define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1) + </programlisting> + <para> When the <varname>flags</varname> is 0 then these methods behave just like the versions + without flags. When <constant>SD_LOGIND_ROOT_CHECK_INHIBITORS</constant> (0x01) is set, active + inhibitors are honoured for privileged users too. When <constant>SD_LOGIND_KEXEC_REBOOT</constant> + (0x02) is set, then <function>RebootWithFlags()</function> perform kexec reboot if kexec + kernel is loaded.</para> + + <para><function>SetRebootParameter()</function> sets a parameter for a subsequent reboot operation. + See the description of <command>reboot</command> in + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and + <citerefentry project="man-pages"><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information.</para> + + <para><function>SetRebootToFirmwareSetup()</function>, + <function>SetRebootToBootLoaderMenu()</function>, and <function>SetRebootToBootLoaderEntry()</function> + configure the action to be taken from the boot loader after a reboot: respectively entering firmware + setup mode, the boot loader menu, or a specific boot loader entry. See + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the + corresponding command line interface.</para> + + <para><function>CanPowerOff()</function>, <function>CanReboot()</function>, + <function>CanHalt()</function>, <function>CanSuspend()</function>, <function>CanHibernate()</function>, + <function>CanHybridSleep()</function>, <function>CanSuspendThenHibernate()</function>, + <function>CanRebootParameter()</function>, <function>CanRebootToFirmwareSetup()</function>, + <function>CanRebootToBootLoaderMenu()</function>, and + <function>CanRebootToBootLoaderEntry()</function> test whether the system supports the respective + operation and whether the calling user is allowed to execute it. Returns one of <literal>na</literal>, + <literal>yes</literal>, <literal>no</literal>, and <literal>challenge</literal>. If + <literal>na</literal> is returned, the operation is not available because hardware, kernel, or drivers + do not support it. If <literal>yes</literal> is returned, the operation is supported and the user may + execute the operation without further authentication. If <literal>no</literal> is returned, the + operation is available but the user is not allowed to execute the operation. If + <literal>challenge</literal> is returned, the operation is available but only after + authorization.</para> + + <para><function>ScheduleShutdown()</function> schedules a shutdown operation <varname>type</varname> at + time <varname>usec</varname> in microseconds since the UNIX epoch. <varname>type</varname> can be one + of <literal>poweroff</literal>, <literal>dry-poweroff</literal>, <literal>reboot</literal>, + <literal>dry-reboot</literal>, <literal>halt</literal>, and <literal>dry-halt</literal>. (The + <literal>dry-</literal> variants do not actually execute the shutdown action.) + <function>CancelScheduledShutdown()</function> cancels a scheduled shutdown. The output parameter + <varname>cancelled</varname> is true if a shutdown operation was scheduled.</para> + + <para><function>SetWallMessage()</function> sets the wall message (the message that will be sent out to + all terminals and stored in a + <citerefentry project="man-pages"><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a + subsequent scheduled shutdown operation. The parameter <varname>wall_message</varname> specifies the + shutdown reason (and may be empty) which will be included in the shutdown message. The parameter + <varname>enable</varname> specifies whether to print a wall message on shutdown.</para> + + <para><function>Inhibit()</function> creates an inhibition lock. It takes four parameters: + <varname>what</varname>, <varname>who</varname>, <varname>why</varname>, and + <varname>mode</varname>. <varname>what</varname> is one or more of <literal>shutdown</literal>, + <literal>sleep</literal>, <literal>idle</literal>, <literal>handle-power-key</literal>, + <literal>handle-suspend-key</literal>, <literal>handle-hibernate-key</literal>, + <literal>handle-lid-switch</literal>, separated by colons, for inhibiting poweroff/reboot, + suspend/hibernate, the automatic idle logic, or hardware key handling. <varname>who</varname> should be + a short human readable string identifying the application taking the lock. <varname>why</varname> + should be a short human readable string identifying the reason why the lock is taken. Finally, + <varname>mode</varname> is either <literal>block</literal> or <literal>delay</literal> which encodes + whether the inhibit shall be consider mandatory or whether it should just delay the operation to a + certain maximum time. The method returns a file descriptor. The lock is released the moment this file + descriptor and all its duplicates are closed. For more information on the inhibition logic see + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>. + </para> + </refsect2> + + <refsect2> + <title>Signals</title> + + <para>Whenever the inhibition state or idle hint changes, <function>PropertyChanged</function> + signals are sent out to which clients can subscribe.</para> + + <para>The <function>SessionNew</function>, <function>SessionRemoved</function>, + <function>UserNew</function>, <function>UserRemoved</function>, <function>SeatNew</function>, and + <function>SeatRemoved</function> signals are sent each time a session is created or removed, a user + logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object + path.</para> + + <para>The <function>PrepareForShutdown()</function> and <function>PrepareForSleep()</function> signals + are sent right before (with the argument <literal>true</literal>) or after (with the argument + <literal>false</literal>) the system goes down for reboot/poweroff and suspend/hibernate, + respectively. This may be used by applications to save data on disk, release memory, or do other jobs + that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After + completion of this work they should release their inhibition locks in order to not delay the operation + any further. For more information see + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>. + </para> + </refsect2> + + <refsect2> + <title>Properties</title> + + <para>Most properties simply reflect the configuration, see + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This + includes: <varname>NAutoVTs</varname>, <varname>KillOnlyUsers</varname>, + <varname>KillExcludeUsers</varname>, <varname>KillUserProcesses</varname>, <varname>IdleAction</varname>, + <varname>InhibitDelayMaxUSec</varname>, + <varname>InhibitorsMax</varname>, + <varname>UserStopDelayUSec</varname>, + <varname>HandlePowerKey</varname>, <varname>HandleSuspendKey</varname>, + <varname>HandleHibernateKey</varname>, <varname>HandleLidSwitch</varname>, + <varname>HandleLidSwitchExternalPower</varname>, <varname>HandleLidSwitchDocked</varname>, + <varname>IdleActionUSec</varname>, <varname>HoldoffTimeoutUSec</varname>, + <varname>RemoveIPC</varname>, <varname>RuntimeDirectorySize</varname>, + <varname>RuntimeDirectoryInodesMax</varname>, <varname>InhibitorsMax</varname>, and + <varname>SessionsMax</varname>. + </para> + + <para>The <varname>IdleHint</varname> property reflects the idle hint state of the system. If the + system is idle it might get into automatic suspend or shutdown depending on the configuration.</para> + + <para><varname>IdleSinceHint</varname> and <varname>IdleSinceHintMonotonic</varname> encode the + timestamps of the last change of the idle hint boolean, in <constant>CLOCK_REALTIME</constant> and + <constant>CLOCK_MONOTONIC</constant> timestamps, respectively, in microseconds since the epoch.</para> + + <para>The <varname>BlockInhibited</varname> and <varname>DelayInhibited</varname> properties encode + the currently active locks of the respective modes. They are colon separated lists of + <literal>shutdown</literal>, <literal>sleep</literal>, and <literal>idle</literal> (see above).</para> + + <para><varname>NCurrentSessions</varname> and <varname>NCurrentInhibitors</varname> contain the number + of currently registered sessions and inhibitors.</para> + + <para>The <varname>BootLoaderEntries</varname> property contains a list of boot loader entries. + This includes boot loader entries defined in configuration and any additional loader entries + reported by the boot loader. See + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information.</para> + + <para>The <varname>PreparingForShutdown</varname> and <varname>PreparingForSleep</varname> boolean + properties are true during the interval between the two <function>PrepareForShutdown</function> and + <function>PrepareForSleep</function> signals respectively. Note that these properties do not + send out <function>PropertyChanged</function> signals.</para> + + <para>The <varname>RebootParameter</varname> property shows the value set with the + <function>SetRebootParameter()</function> method described above.</para> + + <para><varname>ScheduledShutdown</varname> shows the value pair set with the + <function>ScheduleShutdown()</function> method described above.</para> + + <para><varname>RebootToFirmwareSetup</varname>, <varname>RebootToBootLoaderMenu</varname>, and + <varname>RebootToBootLoaderEntry</varname> are true when the resprective post-reboot operation was + selected with <function>SetRebootToFirmwareSetup</function>, + <function>SetRebootToBootLoaderMenu</function>, or + <function>SetRebootToBootLoaderEntry</function>.</para> + + <para>The <varname>WallMessage</varname> and <varname>EnableWallMessages</varname> properties reflect the + shutdown reason and wall message enablement switch which can be set with the + <function>SetWallMessage()</function> method described above.</para> + + <para><varname>Docked</varname> is true if the machine is connected to a dock. + <varname>LidClosed</varname> is true when the lid (of a laptop) is closed. + <varname>OnExternalPower</varname> is true when the machine is connected to an external power supply. + </para> + </refsect2> + + <refsect2> + <title>Security</title> + + <para>A number of operations are protected via the polkit privilege + system. <function>SetUserLinger()</function> requires the + <interfacename>org.freedesktop.login1.set-user-linger</interfacename> + privilege. <function>AttachDevice()</function> requires + <interfacename>org.freedesktop.login1.attach-device</interfacename> and + <function>FlushDevices()</function> requires + <interfacename>org.freedesktop.login1.flush-devices</interfacename>. <function>PowerOff()</function>, + <function>Reboot()</function>, <function>Halt()</function>, <function>Suspend()</function>, + <function>Hibernate()</function> require + <interfacename>org.freedesktop.login1.power-off</interfacename>, + <interfacename>org.freedesktop.login1.power-off-multiple-sessions</interfacename>, + <interfacename>org.freedesktop.login1.power-off-ignore-inhibit</interfacename>, + <interfacename>org.freedesktop.login1.reboot</interfacename>, + <interfacename>org.freedesktop.login1.reboot-multiple-sessions</interfacename>, + <interfacename>org.freedesktop.login1.reboot-ignore-inhibit</interfacename>, + <interfacename>org.freedesktop.login1.halt</interfacename>, + <interfacename>org.freedesktop.login1.halt-multiple-sessions</interfacename>, + <interfacename>org.freedesktop.login1.halt-ignore-inhibit</interfacename>, + <interfacename>org.freedesktop.login1.suspend</interfacename>, + <interfacename>org.freedesktop.login1.suspend-multiple-sessions</interfacename>, + <interfacename>org.freedesktop.login1.suspend-ignore-inhibit</interfacename>, + <interfacename>org.freedesktop.login1.hibernate</interfacename>, + <interfacename>org.freedesktop.login1.hibernate-multiple-sessions</interfacename>, + <interfacename>org.freedesktop.login1.hibernate-ignore-inhibit</interfacename>, + respectively depending on whether there are other sessions around or active inhibits are present. + <function>HybridSleep()</function> and <function>SuspendThenHibernate()</function> + use the same privileges as <function>Hibernate()</function>. + <function>SetRebootParameter()</function> requires + <interfacename>org.freedesktop.login1.set-reboot-parameter</interfacename>.</para> + + <para><function>SetRebootToFirmwareSetup</function> requires + <interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup</interfacename>. + <function>SetRebootToBootLoaderMenu</function> requires + <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu</interfacename>. + <function>SetRebootToBootLoaderEntry</function> requires + <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-entry</interfacename>. + </para> + + <para><function>ScheduleShutdown</function> and <function>CancelScheduledShutdown</function> require + the same privileges (listed above) as the immediate poweroff/reboot/halt operations.</para> + + <para><function>Inhibit()</function> is protected via one of + <interfacename>org.freedesktop.login1.inhibit-block-shutdown</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-delay-shutdown</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-block-sleep</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-delay-sleep</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-block-idle</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-handle-power-key</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-handle-suspend-key</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key</interfacename>, + <interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock + type and mode taken.</para> + + <para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit + should interactively ask the user for authentication credentials if required.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Seat Objects</title> + + <programlisting executable="systemd-logind" node="/org/freedesktop/login1/seat/seat0" interface="org.freedesktop.login1.Seat"> +node /org/freedesktop/login1/seat/seat0 { + interface org.freedesktop.login1.Seat { + methods: + Terminate(); + ActivateSession(in s session_id); + SwitchTo(in u vtnr); + SwitchToNext(); + SwitchToPrevious(); + properties: + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Id = '...'; + readonly (so) ActiveSession = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b CanTTY = ...; + readonly b CanGraphical = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(so) Sessions = [...]; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; +}; + </programlisting> + + <!--Autogenerated cross-references for systemd.directives, do not edit--> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Seat"/> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Seat"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ActivateSession()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SwitchTo()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SwitchToNext()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SwitchToPrevious()"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Id"/> + + <variablelist class="dbus-property" generated="True" extra-ref="ActiveSession"/> + + <variablelist class="dbus-property" generated="True" extra-ref="CanTTY"/> + + <variablelist class="dbus-property" generated="True" extra-ref="CanGraphical"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Sessions"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/> + + <!--End of Autogenerated section--> + + <refsect2> + <title>Methods</title> + + <para><function>Terminate()</function> and <function>ActivateSession()</function> work similarly to + <function>TerminateSeat()</function> and <function>ActivationSessionOnSeat()</function> on the Manager + object.</para> + + <para><function>SwitchTo()</function> switches to the session on the virtual terminal + <varname>vtnr</varname>. <function>SwitchToNext()</function> and + <function>SwitchToPrevious()</function> switch to, respectively, the next and previous sessions on the + seat in the order of virtual terminals. If there is no active session, they switch to, respectively, + the first and last session on the seat.</para> + </refsect2> + + <refsect2> + <title>Signals</title> + + <para>Whenever <function>ActiveSession</function>, <function>Sessions</function>, + <function>CanGraphical</function>, <function>CanTTY</function>, + or the idle state changes, <function>PropertyChanged</function> signals are sent out to which clients + can subscribe.</para> + </refsect2> + + <refsect2> + <title>Properties</title> + + <para>The <varname>Id</varname> property encodes the ID of the seat.</para> + + <para><varname>ActiveSession</varname> encodes the currently active session if there is one. It is a + structure consisting of the session id and the object path.</para> + + <para><varname>CanTTY</varname> encodes whether the session is suitable for text logins, and + <varname>CanGraphical</varname> whether it is suitable for graphical sessions.</para> + + <para>The <varname>Sessions</varname> property is an array of all current sessions of this seat, each + encoded in a structure consisting of the ID and the object path.</para> + + <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and + <varname>IdleSinceHintMonotonic</varname> properties encode the idle state, similarly to the ones + exposed on the <interfacename>Manager</interfacename> object, but specific for this seat.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>User Objects</title> + + <programlisting executable="systemd-logind" node="/org/freedesktop/login1/user/_1000" interface="org.freedesktop.login1.User"> +node /org/freedesktop/login1/user/_1000 { + interface org.freedesktop.login1.User { + methods: + Terminate(); + Kill(in i signal_number); + properties: + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u UID = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u GID = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Name = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t Timestamp = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t TimestampMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RuntimePath = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Service = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Slice = '...'; + readonly (so) Display = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s State = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(so) Sessions = [...]; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b Linger = ...; + }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; +}; + </programlisting> + + <!--Autogenerated cross-references for systemd.directives, do not edit--> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.User"/> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.User"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/> + + <variablelist class="dbus-property" generated="True" extra-ref="UID"/> + + <variablelist class="dbus-property" generated="True" extra-ref="GID"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Name"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/> + + <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RuntimePath"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Service"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Slice"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Display"/> + + <variablelist class="dbus-property" generated="True" extra-ref="State"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Sessions"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Linger"/> + + <!--End of Autogenerated section--> + + <refsect2> + <title>Methods</title> + + <para><function>Terminate()</function> and <function>Kill()</function> work similarly to the + <function>TerminateUser()</function> and <function>KillUser()</function> methods on the manager + object.</para> + </refsect2> + + <refsect2> + <title>Signals</title> + + <para>Whenever <varname>Sessions</varname> or the idle state changes, + <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para> + </refsect2> + + <refsect2> + <title>Properties</title> + + <para>The <varname>UID</varname> and <varname>GID</varname> properties encode the Unix UID and primary + GID of the user.</para> + + <para>The <varname>Name</varname> property encodes the user name.</para> + + <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the login time of + the user in microseconds since the epoch, in the <constant>CLOCK_REALTIME</constant> and + <constant>CLOCK_MONOTONIC</constant> clocks, respectively.</para> + + <para><varname>RuntimePath</varname> encodes the runtime path of the user, + i.e. <varname>$XDG_RUNTIME_DIR</varname>. For details see the + <ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html"> + XDG Basedir Specification + </ulink>.</para> + + <para><varname>Service</varname> contains the unit name of the user systemd service of this + user. Each logged in user is assigned a user service that runs a user systemd instance. This is + usually an instance of <filename>user@.service</filename>.</para> + + <para><varname>Slice</varname> contains the unit name of the user systemd slice of this user. Each + logged in user gets a private slice.</para> + + <para><varname>Display</varname> encodes which graphical session should be used as the primary UI display + for the user. It is a structure encoding the session ID and the object path of the session to use.</para> + + <para><varname>State</varname> encodes the user state and is one of <literal>offline</literal>, + <literal>lingering</literal>, <literal>online</literal>, <literal>active</literal>, or + <literal>closing</literal>. See + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the states.</para> + + <para><varname>Sessions</varname> is an array of structures encoding all current sessions of the + user. Each structure consists of the ID and object path.</para> + + <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and + <varname>IdleSinceHintMonotonic</varname> properties encode the idle hint state of the user, similarly + to the <interfacename>Manager</interfacename>'s properties, but specific for this user.</para> + + <para>The <varname>Linger</varname> property shows whether lingering is enabled for this user.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Session Objects</title> + + <programlisting executable="systemd-logind" node="/org/freedesktop/login1/session/1" interface="org.freedesktop.login1.Session"> +node /org/freedesktop/login1/session/1 { + interface org.freedesktop.login1.Session { + methods: + Terminate(); + Activate(); + Lock(); + Unlock(); + SetIdleHint(in b idle); + SetLockedHint(in b locked); + Kill(in s who, + in i signal_number); + TakeControl(in b force); + ReleaseControl(); + SetType(in s type); + SetDisplay(in s display); + TakeDevice(in u major, + in u minor, + out h fd, + out b inactive); + ReleaseDevice(in u major, + in u minor); + PauseDeviceComplete(in u major, + in u minor); + SetBrightness(in s subsystem, + in s name, + in u brightness); + signals: + PauseDevice(u major, + u minor, + s type); + ResumeDevice(u major, + u minor, + h fd); + Lock(); + Unlock(); + properties: + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Id = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly (uo) User = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Name = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t Timestamp = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t TimestampMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u VTNr = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly (so) Seat = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s TTY = '...'; + readonly s Display = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b Remote = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RemoteHost = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RemoteUser = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Service = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Desktop = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Scope = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u Leader = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u Audit = ...; + readonly s Type = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Class = '...'; + readonly b Active = ...; + readonly s State = '...'; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + readonly b LockedHint = ...; + }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; +}; + </programlisting> + + <!--Autogenerated cross-references for systemd.directives, do not edit--> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Session"/> + + <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Session"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Lock()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetIdleHint()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetLockedHint()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="TakeControl()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ReleaseControl()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetType()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetDisplay()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="TakeDevice()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ReleaseDevice()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="PauseDeviceComplete()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="SetBrightness()"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="PauseDevice"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="ResumeDevice"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="Lock"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="Unlock"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Id"/> + + <variablelist class="dbus-property" generated="True" extra-ref="User"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Name"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/> + + <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/> + + <variablelist class="dbus-property" generated="True" extra-ref="VTNr"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Seat"/> + + <variablelist class="dbus-property" generated="True" extra-ref="TTY"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Display"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Remote"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RemoteHost"/> + + <variablelist class="dbus-property" generated="True" extra-ref="RemoteUser"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Service"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Desktop"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Scope"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Leader"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Audit"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Type"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Class"/> + + <variablelist class="dbus-property" generated="True" extra-ref="Active"/> + + <variablelist class="dbus-property" generated="True" extra-ref="State"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/> + + <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/> + + <variablelist class="dbus-property" generated="True" extra-ref="LockedHint"/> + + <!--End of Autogenerated section--> + + <refsect2> + <title>Methods</title> + + <para><function>Terminate()</function>, <function>Activate()</function>, <function>Lock()</function>, + <function>Unlock()</function>, and <function>Kill()</function> work similarly to the respective calls on + the <interfacename>Manager</interfacename> object.</para> + + <para><function>SetIdleHint()</function> is called by the session object to update the idle state + of the session whenever it changes.</para> + + <para><function>TakeControl()</function> allows a process to take exclusive managed device + access-control for that session. Only one D-Bus connection can be a controller for a given session at any + time. If the <varname>force</varname> argument is set (root only), an existing controller is kicked + out and replaced. Otherwise, this method fails if there is already a controller. Note that this method is + limited to D-Bus users with the effective UID set to the user of the session or root.</para> + + <para><function>ReleaseControl()</function> drops control of a given session. Closing the D-Bus + connection implicitly releases control as well. See <function>TakeControl()</function> for more + information. This method also releases all devices for which the controller requested ownership via + <function>TakeDevice()</function>.</para> + + <para><function>SetType()</function> allows the type of the session to be changed dynamically. It can + only be called by session's current controller. If <function>TakeControl()</function> has not been + called, this method will fail. In addition, the session type will be reset to its original value once + control is released, either by calling <function>ReleaseControl()</function> or closing the D-Bus + connection. This should help prevent a session from entering an inconsistent state, for example if the + controller crashes. The only argument <varname>type</varname> is the new session type.</para> + + <para><function>SetDisplay()</function> allows the display name of the graphical session to be changed. This is + useful if the display server is started as part of the session. It can only be called by session's current + controller. If <function>TakeControl()</function> has not been called, this method will fail. The only argument + <varname>display</varname> is the new display name.</para> + + <para><function>TakeDevice()</function> allows a session controller to get a file descriptor for a + specific device. Pass in the major and minor numbers of the character device and + <filename>systemd-logind</filename> will return a file descriptor for the device. Only a limited set of + device-types is currently supported (but may be extended). <filename>systemd-logind</filename> + automatically mutes the file descriptor if the session is inactive and resumes it once the session is + activated again. This guarantees that a session can only access session devices if the session is + active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This + only works on devices that are attached to the seat of the given session. A process is not required to + have direct access to the device node. <filename>systemd-logind</filename> only requires you to be the + active session controller (see <function>TakeControl()</function>). Also note that any device can only + be requested once. As long as you don't release it, further <function>TakeDevice()</function> calls + will fail.</para> + + <para><function>ReleaseDevice()</function> releases a device again (see + <function>TakeDevice()</function>). This is also implicitly done by + <function>ReleaseControl()</function> or when closing the D-Bus connection.</para> + + <para><function>PauseDeviceComplete()</function> allows a session controller to synchronously pause a + device after receiving a <function>PauseDevice(<literal>pause</literal>)</function> signal. Forced + signals (or after an internal timeout) are automatically completed by + <filename>systemd-logind</filename> asynchronously.</para> + + <para><function>SetLockedHint()</function> may be used to set the "locked hint" to + <varname>locked</varname>, i.e. information whether the session is locked. This is intended to be used + by the desktop environment to tell <command>systemd-logind</command> when the session is locked and + unlocked.</para> + + <para><function>SetBrightness()</function> may be used to set the display brightness. This is intended + to be used by the desktop environment and allows unprivileged programs to access hardware settings in + a controlled way. The <varname>subsystem</varname> parameter specifies a kernel subsystem, either + <literal>backlight</literal> or <literal>leds</literal>. The <varname>name</varname> parameter + specifies a device name under the specified subsystem. The <varname>brightness</varname> parameter + specifies the brightness. The range is defined by individual drivers, see + <filename>/sys/class/<varname>subsystem</varname>/<varname>name</varname>/max_brightness</filename>. + </para> + </refsect2> + + <refsect2> + <title>Signals</title> + + <para>The active session controller exclusively gets <function>PauseDevice</function> and + <function>ResumeDevice</function> events for any device it requested via + <function>TakeDevice()</function>. They notify the controller whenever a device is paused or resumed. A + device is never resumed if its session is inactive. Also note that <function>PauseDevice</function> + signals are sent before the <function>PropertyChanged</function> signal for the + <function>Active</function> state. The inverse is true for <function>ResumeDevice</function>. A device + may remain paused for unknown reasons even though the <interfacename>Session</interfacename> is active. + </para> + + <para>A <function>PauseDevice</function> signal carries the major and minor numbers and a string describing the + type as arguments. <function>force</function> means the device was already paused by + <filename>systemd-logind</filename> and the signal is only an asynchronous + 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 + <function>PauseDeviceComplete()</function>. This synchronous pausing mechanism is used for + backwards-compatibility to VTs and <filename>systemd-logind</filename> is free to not make use of + it. It is also free to send a forced <function>PauseDevice</function> if you don't respond in a timely + manner (or for any other reason). <function>gone</function> means the device was unplugged from the + system and you will no longer get any notifications about it. There is no need to call + <function>ReleaseDevice()</function>. You may call <function>TakeDevice()</function> again if a new + device is assigned the major+minor combination.</para> + + <para><function>ResumeDevice</function> is sent whenever a session is active and a device is + resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should + switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying + open file descriptor in the kernel (except for a limited set of device types).</para> + + <para>Whenever <function>Active</function> or the idle state changes, + <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para> + + <para><function>Lock</function>/<function>Unlock</function> is sent when the session is asked to be + screen-locked/unlocked. A session manager of the session should listen to this signal and act + accordingly. This signal is sent out as a result of the <function>Lock()</function> and + <function>Unlock()</function> methods, respectively.</para> + </refsect2> + + <refsect2> + <title>Properties</title> + + <para><varname>Id</varname> encodes the session ID.</para> + + <para><varname>User</varname> encodes the user ID of the user this session belongs to. This is a + structure consisting of the Unix UID and the object path.</para> + + <para><varname>Name</varname> encodes the user name.</para> + + <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the microseconds + since the epoch when the session was created, in <constant>CLOCK_REALTIME</constant> or + <constant>CLOCK_MONOTONIC</constant>, respectively.</para> + + <para><varname>VTNr</varname> encodes the virtual terminal number of the session if there is any, 0 + otherwise.</para> + + <para><varname>Seat</varname> encodes the seat this session belongs to if there is any. This is a + structure consisting of the ID and the seat object path.</para> + + <para><varname>TTY</varname> encodes the kernel TTY path of the session if this is a text login. If not + this is an empty string.</para> + + <para><varname>Display</varname> encodes the X11 display name if this is a graphical login. If not, + this is an empty string.</para> + + <para><varname>Remote</varname> encodes whether the session is local or remote.</para> + + <para><varname>RemoteHost</varname> and <varname>RemoteUser</varname> encode the remote host and user + if this is a remote session, or an empty string otherwise.</para> + + <para><varname>Service</varname> encodes the PAM service name that registered the session.</para> + + <para><varname>Desktop</varname> describes the desktop environment running in the session (if + known).</para> + + <para><varname>Scope</varname> contains the systemd scope unit name of this session.</para> + + <para><varname>Leader</varname> encodes the PID of the process that registered the session.</para> + + <para><varname>Audit</varname> encodes the Kernel Audit session ID of the session if auditing is + available.</para> + + <para><varname>Type</varname> encodes the session type. It's one of <literal>unspecified</literal> (for + cron PAM sessions and suchlike), <literal>tty</literal> (for text logins) or + <literal>x11</literal>/<literal>mir</literal>/<literal>wayland</literal> (for graphical logins).</para> + + <para><varname>Class</varname> encodes the session class. It's one of <literal>user</literal> (for + normal user sessions), <literal>greeter</literal> (for display manager pseudo-sessions), or + <literal>lock-screen</literal> (for display lock screens).</para> + + <para><varname>Active</varname> is a boolean that is true if the session is active, i.e. currently in the + foreground. This field is semi-redundant due to <varname>State</varname>.</para> + + <para><varname>State</varname> encodes the session state and one of <literal>online</literal>, + <literal>active</literal>, or <literal>closing</literal>. See + <citerefentry><refentrytitle>sd_session_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the states.</para> + + <para><varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and + <varname>IdleSinceHintMonotonic</varname> encapsulate the idle hint state of this session, similarly to + how the respective properties on the manager object do it for the whole system.</para> + + <para><varname>LockedHint</varname> shows the locked hint state of this session, as set by the + <function>SetLockedHint()</function> method described above.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Introspect the logind manager on the bus</title> + + <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1 + </programlisting> + + <para>or</para> + + <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1 + </programlisting> + </example> + + <example> + <title>Introspect the default seat on the bus</title> + + <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1/seat/seat0 + </programlisting> + + <para>or</para> + + <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/seat/seat0 + </programlisting> + + <para>Seat <literal>seat0</literal> is the default seat, so it'll be present unless local configuration + is made to reassign all devices to a different seat. The list of seats and users can be acquired with + <command>loginctl list-sessions</command>.</para> + </example> + + <example> + <title>Introspect a single user on the bus</title> + + <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1/user/_1000 + </programlisting> + + <para>or</para> + + <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/user/_1000 + </programlisting> + </example> + + <example> + <title>Introspect <interfacename>org.freedesktop.login1.Session</interfacename> on the bus</title> + + <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1/session/45 + </programlisting> + + <para>or</para> + + <programlisting>$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/session/45 + </programlisting> + </example> + </refsect1> + + <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> +</refentry> |