table of contents
- bullseye 247.3-7+deb11u1
- bullseye-backports 252.5-2~bpo11+1
- testing 252.5-2
- unstable 252.6-1
- experimental 253-1
SD-LOGIN(3) | sd-login | SD-LOGIN(3) |
NAME¶
sd-login - APIs for tracking logins
SYNOPSIS¶
#include <systemd/sd-login.h>
pkg-config --cflags --libs libsystemd
DESCRIPTION¶
sd-login.h provides APIs to introspect and monitor seat, login session and user status information on the local system.
Note that these APIs only allow purely passive access and monitoring of seats, sessions and users. To actively make changes to the seat configuration, terminate login sessions, or switch session on a seat you need to utilize the D-Bus API of systemd-logind, instead.
These functions synchronously access data in /proc/, /sys/fs/cgroup/ and /run/. All of these are virtual file systems, hence the runtime cost of the accesses is relatively cheap.
It is possible (and often a very good choice) to mix calls to the synchronous interface of sd-login.h with the asynchronous D-Bus interface of systemd-logind. However, if this is done you need to think a bit about possible races since the stream of events from D-Bus and from sd-login.h interfaces such as the login monitor are asynchronous and not ordered against each other.
If the functions return string arrays, these are generally NULL terminated and need to be freed by the caller with the libc free(3) call after use, including the strings referenced therein. Similarly, individual strings returned need to be freed, as well.
As a special exception, instead of an empty string array NULL may be returned, which should be treated equivalent to an empty string array.
See sd_pid_get_session(3), sd_uid_get_state(3), sd_session_is_active(3), sd_seat_get_active(3), sd_get_seats(3), sd_login_monitor_new(3) for more information about the functions implemented.
DEFINITION OF TERMS¶
seat
session
systemd(1) ensures that audit sessions are identical to systemd sessions, and uses the audit session ID as session ID in systemd (if auditing is enabled). In general the session identifier is a short string consisting only of [a-zA-Z0-9], "_" and "-", suitable for use as a file name. Session IDs are unique on the local machine and are never reused as long as the machine is online. A user (the way we know it on UNIX) corresponds to the person using a computer. A single user can have multiple sessions open at the same time. A user is identified by a numeric user id (UID) or a user name (a string). A multi-session system allows multiple user sessions on the same seat at the same time. A multi-seat system allows multiple independent seats that can be individually and simultaneously used by different users.
All hardware devices that are eligible to being assigned to a seat, are assigned to one. A device can be assigned to only one seat at a time. If a device is not assigned to any particular other seat it is implicitly assigned to the special default seat called "seat0".
Note that hardware like printers, hard disks or network cards is generally not assigned to a specific seat. They are available to all seats equally. (Well, with one exception: USB sticks can be assigned to a seat.)
"seat0" always exists.
UDEV RULES¶
Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices:
Tag "seat"
Tag "master-of-seat"
Property ID_SEAT
Property ID_AUTOSEAT
Property ID_FOR_SEAT
A seat exists only and exclusively because a properly tagged device with the right ID_SEAT property exists. Besides udev rules there is no persistent data about seats stored on disk.
Note that systemd-logind(8) manages ACLs on a number of device classes, to allow user code to access the device nodes attached to a seat as long as the user has an active session on it. This is mostly transparent to applications. As mentioned above, for certain user software it might be a good idea to watch whether they can access device nodes instead of thinking about seats.
NOTES¶
These APIs are implemented as a shared library, which can be compiled and linked to with the libsystemd pkg-config(1) file.
SEE ALSO¶
systemd(1), sd_pid_get_session(3), sd_uid_get_state(3), sd_session_is_active(3), sd_seat_get_active(3), sd_get_seats(3), sd_login_monitor_new(3), sd-daemon(3), pkg-config(1)
Multi-Seat on Linux[1] may also be of historical interest.
NOTES¶
- 1.
- Multi-Seat on Linux
systemd 247 |