1SD-LOGIN(3) sd-login SD-LOGIN(3)
2
6 sd-login - APIs for tracking logins
7
9 #include <systemd/sd-login.h>
10 pkg-config --cflags --libs libsystemd
12
14 sd-login.h is part of libsystemd(3) and provides APIs to introspect and
15 monitor seat, login session, and user status information on the local
16 system.
17 Note that these APIs only allow purely passive access and monitoring of
19 seats, sessions and users. To actively make changes to the seat
20 configuration, terminate login sessions, or switch session on a seat
21 you need to utilize the D-Bus API of systemd-logind, instead.
22 These functions synchronously access data in /proc/, /sys/fs/cgroup/
24 and /run/. All of these are virtual file systems, hence the runtime
25 cost of the accesses is relatively cheap.
26 It is possible (and often a very good choice) to mix calls to the
28 synchronous interface of sd-login.h with the asynchronous D-Bus
29 interface of systemd-logind. However, if this is done you need to think
30 a bit about possible races since the stream of events from D-Bus and
31 from sd-login.h interfaces such as the login monitor are asynchronous
32 and not ordered against each other.
33 If the functions return string arrays, these are generally NULL
35 terminated and need to be freed by the caller with the libc free(3)
36 call after use, including the strings referenced therein. Similarly,
37 individual strings returned need to be freed, as well.
38 As a special exception, instead of an empty string array NULL may be
40 returned, which should be treated equivalent to an empty string array.
41 See sd_pid_get_session(3), sd_uid_get_state(3),
43 sd_session_is_active(3), sd_seat_get_active(3), sd_get_seats(3),
44 sd_login_monitor_new(3) for more information about the functions
45 implemented.
46
48 seat
49 A seat consists of all hardware devices assigned to a specific
50 workplace. It consists of at least one graphics device, and usually
51 also includes keyboard, mouse. It can also include video cameras,
52 sound cards and more. Seats are identified by seat names, which are
53 strings (<= 255 characters), that start with the four characters
54 "seat" followed by at least one character from the range
55 [a-zA-Z0-9], "_" and "-". They are suitable for use as file names.
56 Seat names may or may not be stable and may be reused if a seat
57 becomes available again.
58 session
60 A session is defined by the time a user is logged in until they log
61 out. A session is bound to one or no seats (the latter for
62 'virtual' ssh logins). Multiple sessions can be attached to the
63 same seat, but only one of them can be active, the others are in
64 the background. A session is identified by a short string.
65 systemd(1) ensures that audit sessions are identical to systemd
67 sessions, and uses the audit session ID as session ID in systemd
68 (if auditing is enabled). In general the session identifier is a
69 short string consisting only of [a-zA-Z0-9], "_" and "-", suitable
70 for use as a file name. Session IDs are unique on the local machine
71 and are never reused as long as the machine is online. A user (the
72 way we know it on UNIX) corresponds to the person using a computer.
73 A single user can have multiple sessions open at the same time. A
74 user is identified by a numeric user id (UID) or a user name (a
75 string). A multi-session system allows multiple user sessions on
76 the same seat at the same time. A multi-seat system allows multiple
77 independent seats that can be individually and simultaneously used
78 by different users.
79 All hardware devices that are eligible to being assigned to a seat, are
81 assigned to one. A device can be assigned to only one seat at a time.
82 If a device is not assigned to any particular other seat it is
83 implicitly assigned to the special default seat called "seat0".
84 Note that hardware like printers, hard disks or network cards is
86 generally not assigned to a specific seat. They are available to all
87 seats equally. (Well, with one exception: USB sticks can be assigned to
88 a seat.)
89 "seat0" always exists.
91
93 Assignment of hardware devices to seats is managed inside the udev
94 database, via settings on the devices:
95 Tag "seat"
97 When set, a device is eligible to be assigned to a seat. This tag
98 is set for graphics devices, mice, keyboards, video cards, sound
99 cards and more. Note that some devices like sound cards consist of
100 multiple subdevices (i.e. a PCM for input and another one for
101 output). This tag will be set only for the originating device, not
102 for the individual subdevices. A UI for configuring assignment of
103 devices to seats should enumerate and subscribe to all devices with
104 this tag set and show them in the UI. Note that USB hubs can be
105 assigned to a seat as well, in which case all (current and future)
106 devices plugged into it will also be assigned to the same seat
107 (unless they are explicitly assigned to another seat).
108 Tag "master-of-seat"
110 When set, this device is enough for a seat to be considered
111 existent. This tag is usually set for the framebuffer device of
112 graphics cards. A seat hence consists of an arbitrary number of
113 devices marked with the "seat" tag, but (at least) one of these
114 devices needs to be tagged with "master-of-seat" before the seat is
115 actually considered to be around.
116 Property ID_SEAT
118 This property specifies the name of the seat a specific device is
119 assigned to. If not set the device is assigned to "seat0". Also, to
120 speed up enumeration of hardware belonging to a specific seat, the
121 seat is also set as tag on the device. I.e. if the property
122 ID_SEAT=seat-waldo is set for a device, the tag "seat-waldo" will
123 be set as well. Note that if a device is assigned to "seat0", it
124 will usually not carry such a tag and you need to enumerate all
125 devices and check the ID_SEAT property manually. Again, if a device
126 is assigned to seat0 this is visible on the device in two ways:
127 with a property ID_SEAT=seat0 and with no property ID_SEAT set for
128 it at all.
129 Property ID_AUTOSEAT
131 When set to "1", this device automatically generates a new and
132 independent seat, which is named after the path of the device. This
133 is set for specialized USB hubs like the Pluggable devices, which
134 when plugged in should create a hotplug seat without further
135 configuration.
136 Property ID_FOR_SEAT
138 When creating additional (manual) seats starting from a graphics
139 device this is a good choice to name the seat after. It is created
140 from the path of the device. This is useful in UIs for configuring
141 seats: as soon as you create a new seat from a graphics device,
142 read this property and prefix it with "seat-" and use it as name
143 for the seat.
144 A seat exists only and exclusively because a properly tagged device
146 with the right ID_SEAT property exists. Besides udev rules there is no
147 persistent data about seats stored on disk.
148 Note that systemd-logind(8) manages ACLs on a number of device classes,
150 to allow user code to access the device nodes attached to a seat as
151 long as the user has an active session on it. This is mostly
152 transparent to applications. As mentioned above, for certain user
153 software it might be a good idea to watch whether they can access
154 device nodes instead of thinking about seats.
155
157 Functions described here are available as a shared library, which can
158 be compiled against and linked to with the libsystemd pkg-config(1)
159 file.
160 The code described here uses getenv(3), which is declared to be not
162 multi-thread-safe. This means that the code calling the functions
163 described here must not call setenv(3) from a parallel thread. It is
164 recommended to only do calls to setenv() from an early phase of the
165 program when no other threads have been started.
166
168 systemd(1), sd_pid_get_session(3), sd_uid_get_state(3),
169 sd_session_is_active(3), sd_seat_get_active(3), sd_get_seats(3),
170 sd_login_monitor_new(3), sd-daemon(3), pkg-config(1)
171 Multi-Seat on Linux[1] may also be of historical interest.
173
175 1. Multi-Seat on Linux
176 https://www.freedesktop.org/wiki/Software/systemd/multiseat
177systemd 254 SD-LOGIN(3)