'\" t .TH "SD\-LOGIN" "3" "" "systemd 256.7" "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 .fi .ft .HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u \fBpkg\-config \-\-cflags \-\-libs libsystemd\fR .SH "DESCRIPTION" .PP sd\-login\&.h is part of \fBlibsystemd\fR(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 \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\&. .sp Added in version 235\&. .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\&. .sp 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" .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)\&. .sp Added in version 235\&. .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\&. .sp Added in version 235\&. .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\&. .sp Added in version 235\&. .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 Pluggable devices, which when plugged in should create a hotplug seat without further configuration\&. .sp Added in version 235\&. .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\&. .sp Added in version 235\&. .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 Functions described here are available as a shared library, which can be compiled against and linked to with the \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) file\&. .PP The code described here uses \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call \fBsetenv\fR(3) from a parallel thread\&. It is recommended to only do calls to \fBsetenv()\fR from an early phase of the program when no other threads have been started\&. .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 may also be of historical interest\&. .SH "NOTES" .IP " 1." 4 Multi-Seat on Linux .RS 4 \%https://www.freedesktop.org/wiki/Software/systemd/multiseat .RE