'\" t
.TH "SD\-LOGIN" "3" "" "systemd 241" "sd-login"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd-login \- APIs for tracking logins
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-login\&.h>
.fi
.ft
.HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u
\fBpkg\-config \-\-cflags \-\-libs libsystemd\fR
.SH "DESCRIPTION"
.PP
sd\-login\&.h
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
\fBNULL\fR
terminated and need to be freed by the caller with the libc
\fBfree\fR(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
\fBNULL\fR
may be returned, which should be treated equivalent to an empty string array\&.
.PP
See
\fBsd_pid_get_session\fR(3),
\fBsd_uid_get_state\fR(3),
\fBsd_session_is_active\fR(3),
\fBsd_seat_get_active\fR(3),
\fBsd_get_seats\fR(3),
\fBsd_login_monitor_new\fR(3)
for more information about the functions implemented\&.
.SH "DEFINITION OF TERMS"
.PP
seat
.RS 4
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\&.
.RE
.PP
session
.RS 4
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 \*(Aqvirtual\*(Aq 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\&.
.sp
\fBsystemd\fR(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\&.
.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"
.RS 4
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)\&.
.RE
.PP
Tag "master\-of\-seat"
.RS 4
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\&.
.RE
.PP
Property \fIID_SEAT\fR
.RS 4
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
\fIID_SEAT=seat\-waldo\fR
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
\fIID_SEAT\fR
property manually\&. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property
\fIID_SEAT=seat0\fR
and with no property
\fIID_SEAT\fR
set for it at all\&.
.RE
.PP
Property \fIID_AUTOSEAT\fR
.RS 4
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 Plugable devices, which when plugged in should create a hotplug seat without further configuration\&.
.RE
.PP
Property \fIID_FOR_SEAT\fR
.RS 4
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\&.
.RE
.PP
A seat exists only and exclusively because a properly tagged device with the right
\fIID_SEAT\fR
property exists\&. Besides udev rules there is no persistent data about seats stored on disk\&.
.PP
Note that
\fBsystemd-logind\fR(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
These APIs are implemented as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd_pid_get_session\fR(3),
\fBsd_uid_get_state\fR(3),
\fBsd_session_is_active\fR(3),
\fBsd_seat_get_active\fR(3),
\fBsd_get_seats\fR(3),
\fBsd_login_monitor_new\fR(3),
\fBsd-daemon\fR(3),
\fBpkg-config\fR(1)
.PP
\m[blue]\fBMulti\-Seat on Linux\fR\m[]\&\s-2\u[1]\d\s+2
for an introduction to multi\-seat support on Linux and the background for this set of APIs\&.
.SH "NOTES"
.IP " 1." 4
Multi-Seat on Linux
.RS 4
\%https://www.freedesktop.org/wiki/Software/systemd/multiseat
.RE