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

       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.

       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"
           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).

       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.

       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.

       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.

       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.

       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
           https://www.freedesktop.org/wiki/Software/systemd/multiseat