| SD-LOGIN(3) | sd-login | SD-LOGIN(3) |
.SH "NAME" sd-login - APIs for tracking logins
.SH "SYNOPSIS"
#include <systemd/sd-login.h>
.HP 912u
pkg-config --cflags --libs libsystemd
.SH "DESCRIPTION"
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP As a special exception, instead of an empty string array NULL may
be returned, which should be treated equivalent to an empty string
array.
.PP 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.
.SH "DEFINITION OF TERMS"
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.PP 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.)
.PP seat0 always exists.
.SH "UDEV RULES"
.PP Assignment of hardware devices to seats is managed inside the udev
database, via settings on the devices:
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.RE
.PP 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.
.PP 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.
.SH "NOTES"
.PP Functions described here are available as a shared library, which can be
compiled against and linked to with the
libsystemd pkg-config(1) file.
.PP 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.
.SH "SEE ALSO"
.PP 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)
.PP Multi-Seat on Linux[1] may also be of historical interest.
NOTES
- 1.
- Multi-Seat on Linux
| systemd 262.2 |