From fc53809803cd2bc2434e312b19a18fa36776da12 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 05:50:40 +0200 Subject: Adding upstream version 256. Signed-off-by: Daniel Baumann --- man/org.freedesktop.login1.xml | 167 +++++++++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 65 deletions(-) (limited to 'man/org.freedesktop.login1.xml') 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 @@ + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" > + + @@ -309,6 +315,8 @@ node /org/freedesktop/login1 { + + @@ -377,6 +385,8 @@ node /org/freedesktop/login1 { + + @@ -391,6 +401,8 @@ node /org/freedesktop/login1 { + + @@ -415,23 +427,23 @@ node /org/freedesktop/login1 { - + - + - + - + - + - + - + - + - + @@ -469,6 +481,8 @@ node /org/freedesktop/login1 { + + @@ -537,8 +551,17 @@ node /org/freedesktop/login1 { is any. ListSessions() 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. + the array consist of the following fields: session id, user id, + user name, seat id, and session object path. + If a session does not have a seat attached, the seat id field will be an empty string. + + ListSessionsEx() returns an array of all current sessions with more metadata + than ListSessions(). The structures in the array consist of the following fields: + session id, user id, user name, + seat id, leader pid, session class, + tty name, idle hint, idle hint monotonic timestamp, + and session object path. tty and seat id fields + could be empty, if the session has no associated tty or session has no seat attached, respectively. ListUsers() 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. @@ -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). HybridSleep() results in the system entering a hybrid-sleep mode, - i.e. the system is both hibernated and suspended. SuspendThenHibernate() results + i.e. the system is both hibernated and suspended. SuspendThenHibernate() results in the system being suspended, then later woken using an RTC timer and hibernated. The only argument is the polkit interactivity boolean interactive (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. + Sleep() automatically selects the most suitable sleep operation supported by the + machine. The candidate sleep operations to check for support can be configured through SleepOperation= + setting in logind.conf5. + UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. Methods PowerOffWithFlags(), RebootWithFlags(), HaltWithFlags(), SuspendWithFlags(), - HibernateWithFlags(), HybridSleepWithFlags() and - SuspendThenHibernateWithFlags() add flags to allow for - extendability, defined as follows: + HibernateWithFlags(), HybridSleepWithFlags(), + SuspendThenHibernateWithFlags(), and Sleep() take + flags to allow for extendability, defined as follows: #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 { systemctl1 for the corresponding command line interface. - CanPowerOff(), CanReboot(), - CanHalt(), CanSuspend(), CanHibernate(), - CanHybridSleep(), CanSuspendThenHibernate(), + CanPowerOff(), CanReboot(), CanHalt(), + CanSuspend(), CanHibernate(), CanHybridSleep(), + CanSuspendThenHibernate(), CanSleep(), CanRebootParameter(), CanRebootToFirmwareSetup(), - CanRebootToBootLoaderMenu(), and - CanRebootToBootLoaderEntry() test whether the system supports the respective - operation and whether the calling user is allowed to execute it. Returns one of na, - yes, no, and challenge. If - na is returned, the operation is not available because hardware, kernel, or drivers - do not support it. If yes is returned, the operation is supported and the user may - execute the operation without further authentication. If no is returned, the - operation is available but the user is not allowed to execute the operation. If - challenge is returned, the operation is available but only after - authorization. + CanRebootToBootLoaderMenu(), and CanRebootToBootLoaderEntry() + test whether the system supports the respective operation and whether the calling user is allowed to + execute it. Returns one of na, yes, no, and + challenge. If na is returned, the operation is not available because + hardware, kernel, or drivers do not support it. If yes is returned, the operation is + supported and the user may execute the operation without further authentication. If no + is returned, the operation is available but the user is not allowed to execute the operation. If + challenge is returned, the operation is available but only after authorization. ScheduleShutdown() schedules a shutdown operation type at time usec in microseconds since the UNIX epoch. type 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 - Inhibitor Locks. + Inhibitor Locks. @@ -701,26 +725,26 @@ node /org/freedesktop/login1 { Whenever the inhibition state or idle hint changes, PropertyChanged signals are sent out to which clients can subscribe. - The SessionNew, SessionRemoved, - UserNew, UserRemoved, SeatNew, and - SeatRemoved signals are sent each time a session is created or removed, a user + The SessionNew(), SessionRemoved(), + UserNew(), UserRemoved(), SeatNew(), and + SeatRemoved() 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. - The PrepareForShutdown, - PrepareForShutdownWithMetadata, and PrepareForSleep + The PrepareForShutdown(), + PrepareForShutdownWithMetadata(), and PrepareForSleep() signals are sent right before (with the argument true) or after (with the argument false) 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 - Inhibitor Locks. The + Inhibitor Locks. The PrepareForShutdownWithMetadata() signal additionally sends a list of key/value pair metadata fields. Currently it sends a type string which defines the type of shutdown. The type can be one of power-off, reboot, halt, kexec or soft-reboot. This signal is - sent first, followed by PrepareForShutdown (for backward compatibility). + sent first, followed by PrepareForShutdown() (for backward compatibility). @@ -763,8 +787,8 @@ node /org/freedesktop/login1 { for more information. The PreparingForShutdown and PreparingForSleep boolean - properties are true during the interval between the two PrepareForShutdown and - PrepareForSleep signals respectively. Note that these properties do not + properties are true during the interval between the two PrepareForShutdown() and + PrepareForSleep() signals respectively. Note that these properties do not send out PropertyChanged signals. The RebootParameter property shows the value set with the @@ -775,9 +799,9 @@ node /org/freedesktop/login1 { RebootToFirmwareSetup, RebootToBootLoaderMenu, and RebootToBootLoaderEntry are true when the resprective post-reboot operation was - selected with SetRebootToFirmwareSetup, - SetRebootToBootLoaderMenu, or - SetRebootToBootLoaderEntry. + selected with SetRebootToFirmwareSetup(), + SetRebootToBootLoaderMenu(), or + SetRebootToBootLoaderEntry(). The WallMessage and EnableWallMessages properties reflect the shutdown reason and wall message enablement switch which can be set with the @@ -818,19 +842,19 @@ node /org/freedesktop/login1 { org.freedesktop.login1.hibernate-ignore-inhibit, respectively depending on whether there are other sessions around or active inhibits are present. HybridSleep() and SuspendThenHibernate() - use the same privileges as Hibernate(). - SetRebootParameter() requires + use the same privileges as Hibernate(). Sleep() uses + the inhibits of the auto-selected sleep operation. SetRebootParameter() requires org.freedesktop.login1.set-reboot-parameter. - SetRebootToFirmwareSetup requires + SetRebootToFirmwareSetup() requires org.freedesktop.login1.set-reboot-to-firmware-setup. - SetRebootToBootLoaderMenu requires + SetRebootToBootLoaderMenu() requires org.freedesktop.login1.set-reboot-to-boot-loader-menu. - SetRebootToBootLoaderEntry requires + SetRebootToBootLoaderEntry() requires org.freedesktop.login1.set-reboot-to-boot-loader-entry. - ScheduleShutdown and CancelScheduledShutdown require + ScheduleShutdown() and CancelScheduledShutdown() require the same privileges (listed above) as the immediate poweroff/reboot/halt operations. Inhibit() 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 { + + @@ -1230,13 +1256,13 @@ node /org/freedesktop/login1/session/1 { - + - + - + - + @@ -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 type is the new session type. + SetClass() 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 user-incomplete to user. The call is synchronous, + and will return only once the user's service manager has successfully been started, if necessary. The + only argument type is the new session type. + SetDisplay() 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 TakeControl() has not been called, this method will fail. The only argument @@ -1368,28 +1400,28 @@ node /org/freedesktop/login1/session/1 { Signals - The active session controller exclusively gets PauseDevice and - ResumeDevice events for any device it requested via + The active session controller exclusively gets PauseDevice() and + ResumeDevice() events for any device it requested via TakeDevice(). They notify the controller whenever a device is paused or resumed. A - device is never resumed if its session is inactive. Also note that PauseDevice + device is never resumed if its session is inactive. Also note that PauseDevice() signals are sent before the PropertyChanged signal for the - Active state. The inverse is true for ResumeDevice. A device + Active state. The inverse is true for ResumeDevice(). A device may remain paused for unknown reasons even though the Session is active. - A PauseDevice signal carries the major and minor numbers and a string describing the + A PauseDevice() signal carries the major and minor numbers and a string describing the type as arguments. force means the device was already paused by systemd-logind and the signal is only an asynchronous notification. pause means systemd-logind grants you a limited amount of time to pause the device. You must respond to this via PauseDeviceComplete(). This synchronous pausing mechanism is used for backwards-compatibility to VTs and systemd-logind is free to not make use of - it. It is also free to send a forced PauseDevice if you don't respond in a timely + it. It is also free to send a forced PauseDevice() if you don't respond in a timely manner (or for any other reason). gone means the device was unplugged from the system and you will no longer get any notifications about it. There is no need to call ReleaseDevice(). You may call TakeDevice() again if a new device is assigned the major+minor combination. - ResumeDevice is sent whenever a session is active and a device is + ResumeDevice() 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). @@ -1397,7 +1429,7 @@ node /org/freedesktop/login1/session/1 { Whenever Active or the idle state changes, PropertyChanged signals are sent out to which clients can subscribe. - Lock/Unlock is sent when the session is asked to be + Lock()/Unlock() 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 Lock() and Unlock() methods, respectively. @@ -1543,13 +1575,18 @@ node /org/freedesktop/login1/session/1 { HandleSuspendKeyLongPress, and HandleHibernateKeyLongPress were added in version 251. StopIdleSessionUSec was added in version 252. - PrepareForShutdownWithMetadata and + PrepareForShutdownWithMetadata() and CreateSessionWithPIDFD() were added in version 255. + Sleep(), + CanSleep(), + SleepOperation, and + ListSessionsEx() were added in version 256. Session Objects SetDisplay() was added in version 252. SetTTY() was added in version 254. + SetClass() was added in version 256. -- cgit v1.2.3