Debian Codegraph @

upstream/debian-unstable/man3/sd-login.3

raw
1 '\" t
2 .TH "SD\-LOGIN" "3" "" "systemd 261~rc3" "sd-login"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd-login \- APIs for tracking logins
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-login\&.h>
29 .fi
30 .ft
31 .HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u
32 \fBpkg\-config \-\-cflags \-\-libs libsystemd\fR
33 .SH "DESCRIPTION"
34 .PP
35 sd\-login\&.h
36 is part of
37 \fBlibsystemd\fR(3)
38 and provides APIs to introspect and monitor seat, login session, and user status information on the local system\&.
39 .PP
40 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\&.
41 .PP
42 These functions synchronously access data in
43 /proc/,
44 /sys/fs/cgroup/
45 and
46 /run/\&. All of these are virtual file systems, hence the runtime cost of the accesses is relatively cheap\&.
47 .PP
48 It is possible (and often a very good choice) to mix calls to the synchronous interface of
49 sd\-login\&.h
50 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
51 sd\-login\&.h
52 interfaces such as the login monitor are asynchronous and not ordered against each other\&.
53 .PP
54 If the functions return string arrays, these are generally
55 \fBNULL\fR\-terminated and need to be freed by the caller with the libc
56 \fBfree\fR(3)
57 call after use, including the strings referenced therein\&. Similarly, individual strings returned need to be freed, as well\&.
58 .PP
59 As a special exception, instead of an empty string array
60 \fBNULL\fR
61 may be returned, which should be treated equivalent to an empty string array\&.
62 .PP
63 See
64 \fBsd_pid_get_session\fR(3),
65 \fBsd_uid_get_state\fR(3),
66 \fBsd_session_is_active\fR(3),
67 \fBsd_seat_get_active\fR(3),
68 \fBsd_get_seats\fR(3),
69 \fBsd_login_monitor_new\fR(3)
70 for more information about the functions implemented\&.
71 .SH "DEFINITION OF TERMS"
72 .PP
73 seat
74 .RS 4
75 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
76 "seat"
77 followed by at least one character from the range [a\-zA\-Z0\-9],
78 "_"
79 and
80 "\-"\&. 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\&.
81 .sp
82 Added in version 235\&.
83 .RE
84 .PP
85 session
86 .RS 4
87 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\&.
88 .sp
89 \fBsystemd\fR(1)
90 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],
91 "_"
92 and
93 "\-", 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\&.
94 .sp
95 Added in version 235\&.
96 .RE
97 .PP
98 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
99 "seat0"\&.
100 .PP
101 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\&.)
102 .PP
103 "seat0"
104 always exists\&.
105 .SH "UDEV RULES"
106 .PP
107 Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices:
108 .PP
109 Tag "seat"
110 .RS 4
111 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)\&.
112 .sp
113 Added in version 235\&.
114 .RE
115 .PP
116 Tag "master\-of\-seat"
117 .RS 4
118 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
119 "seat"
120 tag, but (at least) one of these devices needs to be tagged with
121 "master\-of\-seat"
122 before the seat is actually considered to be around\&.
123 .sp
124 Added in version 235\&.
125 .RE
126 .PP
127 Tag "uaccess"
128 .RS 4
129 When set, access to this device is tied to an active seat\&. As the session on the seat becomes active or inactive, access to the device is updated accordingly\&.
130 .RE
131 .PP
132 Tag "xaccess\-*"
133 .RS 4
134 When
135 "xaccess\-\fIID\fR"
136 is set, access to this device is granted to sessions created with
137 "\fIID\fR"
138 listed in
139 "ExtraDeviceAccess"\&. As the sessions with some
140 "ExtraDeviceAccess"
141 open and close, access to the device is updated accordingly\&.
142 .sp
143 Added in version 260\&.
144 .RE
145 .PP
146 Property \fIID_SEAT\fR
147 .RS 4
148 This property specifies the name of the seat a specific device is assigned to\&. If not set the device is assigned to
149 "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
150 \fIID_SEAT=seat\-waldo\fR
151 is set for a device, the tag
152 "seat\-waldo"
153 will be set as well\&. Note that if a device is assigned to
154 "seat0", it will usually not carry such a tag and you need to enumerate all devices and check the
155 \fIID_SEAT\fR
156 property manually\&. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property
157 \fIID_SEAT=seat0\fR
158 and with no property
159 \fIID_SEAT\fR
160 set for it at all\&.
161 .sp
162 Added in version 235\&.
163 .RE
164 .PP
165 Property \fIID_AUTOSEAT\fR
166 .RS 4
167 When set to
168 "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\&.
169 .sp
170 Added in version 235\&.
171 .RE
172 .PP
173 Property \fIID_FOR_SEAT\fR
174 .RS 4
175 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
176 "seat\-"
177 and use it as name for the seat\&.
178 .sp
179 Added in version 235\&.
180 .RE
181 .PP
182 A seat exists only and exclusively because a properly tagged device with the right
183 \fIID_SEAT\fR
184 property exists\&. Besides udev rules there is no persistent data about seats stored on disk\&.
185 .PP
186 Note that
187 \fBsystemd-logind\fR(8)
188 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\&.
189 .SH "NOTES"
190 .PP
191 Functions described here are available as a shared library, which can be compiled against and linked to with the
192 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
193 file\&.
194 .PP
195 The code described here uses
196 \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
197 \fBsetenv\fR(3)
198 from a parallel thread\&. It is recommended to only do calls to
199 \fBsetenv()\fR
200 from an early phase of the program when no other threads have been started\&.
201 .SH "SEE ALSO"
202 .PP
203 \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)
204 .PP
205 \m[blue]\fBMulti\-Seat on Linux\fR\m[]\&\s-2\u[1]\d\s+2
206 may also be of historical interest\&.
207 .SH "NOTES"
208 .IP " 1." 4
209 Multi-Seat on Linux
210 .RS 4
211 \%https://www.freedesktop.org/wiki/Software/systemd/multiseat
212 .RE