diff options
Diffstat (limited to 'man/org.freedesktop.login1.xml')
| -rw-r--r-- | man/org.freedesktop.login1.xml | 167 |
1 files changed, 102 insertions, 65 deletions
diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 519a686..aacaa1b 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -1,6 +1,6 @@ <?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" > + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" > <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> <refentry id="org.freedesktop.login1" conditional='ENABLE_LOGIND' @@ -53,6 +53,7 @@ node /org/freedesktop/login1 { GetSeat(in s seat_id, out o object_path); ListSessions(out a(susso) sessions); + ListSessionsEx(out a(sussussbto) sessions); ListUsers(out a(uso) users); ListSeats(out a(so) seats); ListInhibitors(out a(ssssuu) inhibitors); @@ -103,7 +104,6 @@ node /org/freedesktop/login1 { 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, @@ -141,6 +141,7 @@ node /org/freedesktop/login1 { HybridSleepWithFlags(in t flags); SuspendThenHibernate(in b interactive); SuspendThenHibernateWithFlags(in t flags); + Sleep(in t flags); CanPowerOff(out s result); CanReboot(out s result); CanHalt(out s result); @@ -148,6 +149,7 @@ node /org/freedesktop/login1 { CanHibernate(out s result); CanHybridSleep(out s result); CanSuspendThenHibernate(out s result); + CanSleep(out s result); ScheduleShutdown(in s type, in t usec); CancelScheduledShutdown(out b cancelled); @@ -218,6 +220,8 @@ node /org/freedesktop/login1 { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UserStopDelayUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as SleepOperation = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandlePowerKey = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandlePowerKeyLongPress = '...'; @@ -279,6 +283,8 @@ node /org/freedesktop/login1 { }; </programlisting> + <!--property SleepOperation is not documented!--> + <!--property HandlePowerKeyLongPress is not documented!--> <!--property HandleRebootKey is not documented!--> @@ -309,6 +315,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-method" generated="True" extra-ref="ListSessions()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ListSessionsEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ListUsers()"/> <variablelist class="dbus-method" generated="True" extra-ref="ListSeats()"/> @@ -377,6 +385,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-method" generated="True" extra-ref="SuspendThenHibernateWithFlags()"/> + <variablelist class="dbus-method" generated="True" extra-ref="Sleep()"/> + <variablelist class="dbus-method" generated="True" extra-ref="CanPowerOff()"/> <variablelist class="dbus-method" generated="True" extra-ref="CanReboot()"/> @@ -391,6 +401,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-method" generated="True" extra-ref="CanSuspendThenHibernate()"/> + <variablelist class="dbus-method" generated="True" extra-ref="CanSleep()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ScheduleShutdown()"/> <variablelist class="dbus-method" generated="True" extra-ref="CancelScheduledShutdown()"/> @@ -415,23 +427,23 @@ node /org/freedesktop/login1 { <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="SessionNew()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="SessionRemoved"/> + <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="UserNew()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="UserRemoved"/> + <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="SeatNew()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="SeatRemoved"/> + <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="PrepareForShutdown()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForShutdownWithMetadata"/> + <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForShutdownWithMetadata()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForSleep"/> + <variablelist class="dbus-signal" generated="True" extra-ref="PrepareForSleep()"/> <variablelist class="dbus-property" generated="True" extra-ref="EnableWallMessages"/> @@ -469,6 +481,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-property" generated="True" extra-ref="UserStopDelayUSec"/> + <variablelist class="dbus-property" generated="True" extra-ref="SleepOperation"/> + <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKey"/> <variablelist class="dbus-property" generated="True" extra-ref="HandlePowerKeyLongPress"/> @@ -537,8 +551,17 @@ node /org/freedesktop/login1 { 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> + the array consist of the following fields: <varname>session id</varname>, <varname>user id</varname>, + <varname>user name</varname>, <varname>seat id</varname>, and <varname>session object path</varname>. + If a session does not have a seat attached, the seat id field will be an empty string.</para> + + <para><function>ListSessionsEx()</function> returns an array of all current sessions with more metadata + than <function>ListSessions()</function>. The structures in the array consist of the following fields: + <varname>session id</varname>, <varname>user id</varname>, <varname>user name</varname>, + <varname>seat id</varname>, <varname>leader pid</varname>, <varname>session class</varname>, + <varname>tty name</varname>, <varname>idle hint</varname>, <varname>idle hint monotonic timestamp</varname>, + and <varname>session object path</varname>. <varname>tty</varname> and <varname>seat id</varname> fields + could be empty, if the session has no associated tty or session has no seat attached, respectively.</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> @@ -608,17 +631,20 @@ node /org/freedesktop/login1 { 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 + 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 + even by unprivileged users. They also enforce inhibition locks for non-privileged users. + <function>Sleep()</function> automatically selects the most suitable sleep operation supported by the + machine. The candidate sleep operations to check for support can be configured through <varname>SleepOperation=</varname> + setting in <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + 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> + <function>HibernateWithFlags()</function>, <function>HybridSleepWithFlags()</function>, + <function>SuspendThenHibernateWithFlags()</function>, and <function>Sleep()</function> take + <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) @@ -648,20 +674,18 @@ node /org/freedesktop/login1 { <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>, + <para><function>CanPowerOff()</function>, <function>CanReboot()</function>, <function>CanHalt()</function>, + <function>CanSuspend()</function>, <function>CanHibernate()</function>, <function>CanHybridSleep()</function>, + <function>CanSuspendThenHibernate()</function>, <function>CanSleep()</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> + <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 @@ -691,7 +715,7 @@ node /org/freedesktop/login1 { 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>. + <ulink url="https://systemd.io/INHIBITOR_LOCKS">Inhibitor Locks</ulink>. </para> </refsect2> @@ -701,26 +725,26 @@ node /org/freedesktop/login1 { <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 + <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>, - <function>PrepareForShutdownWithMetadata</function>, and <function>PrepareForSleep</function> + <para>The <function>PrepareForShutdown()</function>, + <function>PrepareForShutdownWithMetadata()</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>. The + <ulink url="https://systemd.io/INHIBITOR_LOCKS">Inhibitor Locks</ulink>. The <function>PrepareForShutdownWithMetadata()</function> signal additionally sends a list of key/value pair metadata fields. Currently it sends a <varname>type</varname> string which defines the type of shutdown. The type can be one of <literal>power-off</literal>, <literal>reboot</literal>, <literal>halt</literal>, <literal>kexec</literal> or <literal>soft-reboot</literal>. This signal is - sent first, followed by <function>PrepareForShutdown</function> (for backward compatibility).</para> + sent first, followed by <function>PrepareForShutdown()</function> (for backward compatibility).</para> </refsect2> <refsect2> @@ -763,8 +787,8 @@ node /org/freedesktop/login1 { 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 + 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 @@ -775,9 +799,9 @@ node /org/freedesktop/login1 { <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> + 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 @@ -818,19 +842,19 @@ node /org/freedesktop/login1 { <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 + use the same privileges as <function>Hibernate()</function>. <function>Sleep()</function> uses + the inhibits of the auto-selected sleep operation. <function>SetRebootParameter()</function> requires <interfacename>org.freedesktop.login1.set-reboot-parameter</interfacename>.</para> - <para><function>SetRebootToFirmwareSetup</function> requires + <para><function>SetRebootToFirmwareSetup()</function> requires <interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup</interfacename>. - <function>SetRebootToBootLoaderMenu</function> requires + <function>SetRebootToBootLoaderMenu()</function> requires <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu</interfacename>. - <function>SetRebootToBootLoaderEntry</function> requires + <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 + <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 @@ -1121,6 +1145,7 @@ node /org/freedesktop/login1/session/1 { TakeControl(in b force); ReleaseControl(); SetType(in s type); + SetClass(in s class); SetDisplay(in s display); SetTTY(in h tty_fd); TakeDevice(in u major, @@ -1177,7 +1202,6 @@ node /org/freedesktop/login1/session/1 { @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 = '...'; @@ -1218,6 +1242,8 @@ node /org/freedesktop/login1/session/1 { <variablelist class="dbus-method" generated="True" extra-ref="SetType()"/> + <variablelist class="dbus-method" generated="True" extra-ref="SetClass()"/> + <variablelist class="dbus-method" generated="True" extra-ref="SetDisplay()"/> <variablelist class="dbus-method" generated="True" extra-ref="SetTTY()"/> @@ -1230,13 +1256,13 @@ node /org/freedesktop/login1/session/1 { <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="PauseDevice()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="ResumeDevice"/> + <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="Lock()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="Unlock"/> + <variablelist class="dbus-signal" generated="True" extra-ref="Unlock()"/> <variablelist class="dbus-property" generated="True" extra-ref="Id"/> @@ -1318,6 +1344,12 @@ node /org/freedesktop/login1/session/1 { 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>SetClass()</function> allows the caller to change the class of the session dynamically. + It may only be called by session's owening user. Currently, this call may be exclusively used to change + the class from <literal>user-incomplete</literal> to <literal>user</literal>. The call is synchronous, + and will return only once the user's service manager has successfully been started, if necessary. 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 @@ -1368,28 +1400,28 @@ node /org/freedesktop/login1/session/1 { <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 + <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> + 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 + <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 + <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 + 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 + <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> @@ -1397,7 +1429,7 @@ node /org/freedesktop/login1/session/1 { <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 + <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> @@ -1543,13 +1575,18 @@ node /org/freedesktop/login1/session/1 { <varname>HandleSuspendKeyLongPress</varname>, and <varname>HandleHibernateKeyLongPress</varname> were added in version 251.</para> <para><varname>StopIdleSessionUSec</varname> was added in version 252.</para> - <para><function>PrepareForShutdownWithMetadata</function> and + <para><function>PrepareForShutdownWithMetadata()</function> and <function>CreateSessionWithPIDFD()</function> were added in version 255.</para> + <para><function>Sleep()</function>, + <function>CanSleep()</function>, + <varname>SleepOperation</varname>, and + <function>ListSessionsEx()</function> were added in version 256.</para> </refsect2> <refsect2> <title>Session Objects</title> <para><function>SetDisplay()</function> was added in version 252.</para> <para><function>SetTTY()</function> was added in version 254.</para> + <para><function>SetClass()</function> was added in version 256.</para> </refsect2> </refsect1> </refentry> |