sd-login - Man Page

#include <systemd/sd-login​.h>

pkg-config --cflags --libs libsystemd

sd-login​.h is part of libsystemd(3) and 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​.

seat

A seat consists of all hardware devices assigned to a specific workplace​. It consists of at least one graphics device, and usually also includes keyboard, mouse​. It can also include video cameras, sound cards and more​. Seats are identified by seat names, which are strings (<= 255 characters), that start with the four characters "seat" followed by at least one character from the range [a-zA-Z0-9], "_" and "-"​. They are suitable for use as file names​. Seat names may or may not be stable and may be reused if a seat becomes available again​.

Added in version 235​.

session

A session is defined by the time a user is logged in until they log out​. A session is bound to one or no seats (the latter for 'virtual' ssh logins)​. Multiple sessions can be attached to the same seat, but only one of them can be active, the others are in the background​. A session is identified by a short string​.

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​.

Added in version 235​.

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​.

Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices:

Tag "seat"

When set, a device is eligible to be assigned to a seat​. This tag is set for graphics devices, mice, keyboards, video cards, sound cards and more​. Note that some devices like sound cards consist of multiple subdevices (i​.e​. a PCM for input and another one for output)​. This tag will be set only for the originating device, not for the individual subdevices​. A UI for configuring assignment of devices to seats should enumerate and subscribe to all devices with this tag set and show them in the UI​. Note that USB hubs can be assigned to a seat as well, in which case all (current and future) devices plugged into it will also be assigned to the same seat (unless they are explicitly assigned to another seat)​.

Added in version 235​.

Tag "master-of-seat"

When set, this device is enough for a seat to be considered existent​. This tag is usually set for the framebuffer device of graphics cards​. A seat hence consists of an arbitrary number of devices marked with the "seat" tag, but (at least) one of these devices needs to be tagged with "master-of-seat" before the seat is actually considered to be around​.

Added in version 235​.

Tag "uaccess"

When set, access to this device is tied to an active seat​. As the session on the seat becomes active or inactive, access to the device is updated accordingly​.

Tag "xaccess-*"

When "xaccess-ID" is set, access to this device is granted to sessions created with "ID" listed in "ExtraDeviceAccess"​. As the sessions with some "ExtraDeviceAccess" open and close, access to the device is updated accordingly​.

Added in version 260​.

Property ID_SEAT

This property specifies the name of the seat a specific device is assigned to​. If not set the device is assigned to "seat0"​. Also, to speed up enumeration of hardware belonging to a specific seat, the seat is also set as tag on the device​. I​.e​. if the property ID_SEAT=seat-waldo is set for a device, the tag "seat-waldo" will be set as well​. Note that if a device is assigned to "seat0", it will usually not carry such a tag and you need to enumerate all devices and check the ID_SEAT property manually​. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property ID_SEAT=seat0 and with no property ID_SEAT set for it at all​.

Added in version 235​.

Property ID_AUTOSEAT

When set to "1", this device automatically generates a new and independent seat, which is named after the path of the device​. This is set for specialized USB hubs like the Pluggable devices, which when plugged in should create a hotplug seat without further configuration​.

Added in version 235​.

Property ID_FOR_SEAT

When creating additional (manual) seats starting from a graphics device this is a good choice to name the seat after​. It is created from the path of the device​. This is useful in UIs for configuring seats: as soon as you create a new seat from a graphics device, read this property and prefix it with "seat-" and use it as name for the seat​.

Added in version 235​.

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​.

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd ​pkg-config(1) file​.

The code described here uses getenv(3), which is declared to be not multi-thread-safe​. This means that the code calling the functions described here must not call setenv(3) from a parallel thread​. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started​.

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​.

1.

Multi-Seat on Linux
https://www.freedesktop.org/wiki/Software/systemd/multiseat

libsystemd(3), org.freedesktop.login1(5), sd_get_seats(3), sd_login_monitor_new(3), sd_machine_get_class(3), sd_pid_get_owner_uid(3), sd_seat_get_active(3), sd_session_is_active(3), sd_uid_get_state(3), systemd.directives(7), systemd.index(7), systemd-logind.service(8), systemd-machined.service(8).