270 lines
15 KiB
Plaintext
270 lines
15 KiB
Plaintext
<div id="readability-page-1" class="page">
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<pre><span><i>SD-LOGIN</i>(3) sd-login <i>SD-LOGIN</i>(3)</span>
|
|
</pre>
|
|
<h2><a id="NAME" href="#NAME"></a>NAME <a href="#top_of_page"><span>top</span></a></h2><pre> sd-login - APIs for tracking logins
|
|
</pre>
|
|
<h2><a id="SYNOPSIS" href="#SYNOPSIS"></a>SYNOPSIS <a href="#top_of_page"><span>top</span></a></h2><pre> <b>#include <systemd/sd-login.h></b>
|
|
|
|
<b>pkg-config --cflags --libs libsystemd</b>
|
|
</pre>
|
|
<h2><a id="DESCRIPTION" href="#DESCRIPTION"></a>DESCRIPTION <a href="#top_of_page"><span>top</span></a></h2><pre> sd-login.h is part of <a href="https://www.man7.org/linux/man-pages/man3/libsystemd.3.html">libsystemd(3)</a> 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
|
|
<b>NULL</b>-terminated and need to be freed by the caller with the libc
|
|
<a href="https://www.man7.org/linux/man-pages/man3/free.3.html">free(3)</a> 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 <b>NULL </b>may
|
|
be returned, which should be treated equivalent to an empty string
|
|
array.
|
|
|
|
See <a href="https://www.man7.org/linux/man-pages/man3/sd_pid_get_session.3.html">sd_pid_get_session(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_uid_get_state.3.html">sd_uid_get_state(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_session_is_active.3.html">sd_session_is_active(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_seat_get_active.3.html">sd_seat_get_active(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_get_seats.3.html">sd_get_seats(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_login_monitor_new.3.html">sd_login_monitor_new(3)</a> for more information about the functions
|
|
implemented.
|
|
</pre>
|
|
<h2><a id="DEFINITION_OF_TERMS" href="#DEFINITION_OF_TERMS"></a>DEFINITION OF TERMS <a href="#top_of_page"><span>top</span></a></h2><pre> 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.
|
|
|
|
<a href="https://www.man7.org/linux/man-pages/man1/systemd.1.html">systemd(1)</a> 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.
|
|
</pre>
|
|
<h2><a id="UDEV_RULES" href="#UDEV_RULES"></a>UDEV RULES <a href="#top_of_page"><span>top</span></a></h2><pre> 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 <i>ID_SEAT</i>
|
|
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 <i>ID_SEAT=seat-waldo</i> 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 <i>ID_SEAT</i>
|
|
property manually. Again, if a device is assigned to seat0
|
|
this is visible on the device in two ways: with a property
|
|
<i>ID_SEAT=seat0</i> and with no property <i>ID_SEAT</i> set for it at all.
|
|
|
|
Added in version 235.
|
|
|
|
Property <i>ID_AUTOSEAT</i>
|
|
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 <i>ID_FOR_SEAT</i>
|
|
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 <i>ID_SEAT</i> property exists. Besides udev rules
|
|
there is no persistent data about seats stored on disk.
|
|
|
|
Note that <a href="https://www.man7.org/linux/man-pages/man8/systemd-logind.8.html">systemd-logind(8)</a> 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.
|
|
</pre>
|
|
<h2><a id="NOTES" href="#NOTES"></a>NOTES <a href="#top_of_page"><span>top</span></a></h2><pre> Functions described here are available as a shared library, which
|
|
can be compiled against and linked to with the
|
|
<b>libsystemd pkg-config</b>(1) file.
|
|
|
|
The code described here uses <a href="https://www.man7.org/linux/man-pages/man3/getenv.3.html">getenv(3)</a>, which is declared to be
|
|
not multi-thread-safe. This means that the code calling the
|
|
functions described here must not call <a href="https://www.man7.org/linux/man-pages/man3/setenv.3.html">setenv(3)</a> from a parallel
|
|
thread. It is recommended to only do calls to <b>setenv() </b>from an
|
|
early phase of the program when no other threads have been
|
|
started.
|
|
</pre>
|
|
<h2><a id="SEE_ALSO" href="#SEE_ALSO"></a>SEE ALSO <a href="#top_of_page"><span>top</span></a></h2><pre> <a href="https://www.man7.org/linux/man-pages/man1/systemd.1.html">systemd(1)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_pid_get_session.3.html">sd_pid_get_session(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_uid_get_state.3.html">sd_uid_get_state(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_session_is_active.3.html">sd_session_is_active(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_seat_get_active.3.html">sd_seat_get_active(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd_get_seats.3.html">sd_get_seats(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_login_monitor_new.3.html">sd_login_monitor_new(3)</a>, <a href="https://www.man7.org/linux/man-pages/man3/sd-daemon.3.html">sd-daemon(3)</a>, <b>pkg-config</b>(1)
|
|
|
|
<b>Multi-Seat on Linux</b><b></b>[1] may also be of historical interest.
|
|
</pre>
|
|
<h2><a id="NOTES" href="#NOTES"></a>NOTES <a href="#top_of_page"><span>top</span></a></h2><pre> 1. Multi-Seat on Linux
|
|
<a href="https://www.freedesktop.org/wiki/Software/systemd/multiseat">https://www.freedesktop.org/wiki/Software/systemd/multiseat</a>
|
|
</pre>
|
|
<h2><a id="COLOPHON" href="#COLOPHON"></a>COLOPHON <a href="#top_of_page"><span>top</span></a></h2><pre> This page is part of the <i>systemd</i> (systemd system and service
|
|
manager) project. Information about the project can be found at
|
|
⟨<a href="http://www.freedesktop.org/wiki/Software/systemd">http://www.freedesktop.org/wiki/Software/systemd</a>⟩. If you have a
|
|
bug report for this manual page, see
|
|
⟨<a href="http://www.freedesktop.org/wiki/Software/systemd/#bugreports">http://www.freedesktop.org/wiki/Software/systemd/#bugreports</a>⟩.
|
|
This page was obtained from the project's upstream Git repository
|
|
⟨<a href="https://github.com/systemd/systemd.git">https://github.com/systemd/systemd.git</a>⟩ on 2026-01-16. (At that
|
|
time, the date of the most recent commit that was found in the
|
|
repository was 2026-01-16.) If you discover any rendering
|
|
problems in this HTML version of the page, or you believe there is
|
|
a better or more up-to-date source for the page, or you have
|
|
corrections or improvements to the information in this COLOPHON
|
|
(which is <i>not</i> part of the original manual page), send a mail to
|
|
man-pages@man7.org
|
|
|
|
<span>systemd 260~devel <i>SD-LOGIN</i>(3)</span>
|
|
</pre>
|
|
|
|
<hr>
|
|
<p>Pages that refer to this page:
|
|
<a href="https://www.man7.org/linux/man-pages/man3/libsystemd.3.html">libsystemd(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_get_seats.3.html">sd_get_seats(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_login_monitor_new.3.html">sd_login_monitor_new(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_machine_get_class.3.html">sd_machine_get_class(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_pid_get_owner_uid.3.html">sd_pid_get_owner_uid(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_seat_get_active.3.html">sd_seat_get_active(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_session_is_active.3.html">sd_session_is_active(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man3/sd_uid_get_state.3.html">sd_uid_get_state(3)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man5/org.freedesktop.login1.5.html">org.freedesktop.login1(5)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man7/systemd.directives.7.html">systemd.directives(7)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man7/systemd.index.7.html">systemd.index(7)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man8/systemd-logind.service.8.html">systemd-logind.service(8)</a>,
|
|
<a href="https://www.man7.org/linux/man-pages/man8/systemd-machined.service.8.html">systemd-machined.service(8)</a>
|
|
</p>
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</div> |