# sd-login

## NAME



           sd-login - APIs for tracking logins
    


## SYNOPSIS



           **#include <systemd/sd-login.h>**
    
           **pkg-config --cflags --libs libsystemd**
    


## DESCRIPTION



           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.
    


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


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


## NOTES



           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.
    


## NOTES



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


* * *