man/sd-login.xml - systemd - Git at Google

 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

 <refentry id="sd-login" conditional='HAVE_PAM'
   xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>
     <title>sd-login</title>
     <productname>systemd</productname>
   </refentryinfo>

   <refmeta>
     <refentrytitle>sd-login</refentrytitle>
     <manvolnum>3</manvolnum>
   </refmeta>

   <refnamediv>
     <refname>sd-login</refname>
     <refpurpose>APIs for
     tracking logins</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
     <funcsynopsis>
       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
     </funcsynopsis>

     <cmdsynopsis>
       <command>pkg-config --cflags --libs libsystemd</command>
     </cmdsynopsis>
   </refsynopsisdiv>

   <refsect1>
     <title>Description</title>

     <para><filename>sd-login.h</filename> provides APIs to introspect
     and monitor seat, login session and user status information on the
     local system. </para>

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

     <para>These functions synchronously access data in
     <filename>/proc/</filename>, <filename>/sys/fs/cgroup/</filename>
     and <filename>/run/</filename>. All of these are virtual file
     systems, hence the runtime cost of the accesses is relatively
     cheap.</para>

     <para>It is possible (and often a very good choice) to mix calls
     to the synchronous interface of <filename>sd-login.h</filename>
     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
     <filename>sd-login.h</filename> interfaces such as the login
     monitor are asynchronous and not ordered against each
     other.</para>

     <para>If the functions return string arrays, these are generally
     <constant>NULL</constant> terminated and need to be freed by the
     caller with the libc
     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     call after use, including the strings referenced therein.
     Similarly, individual strings returned need to be freed, as
     well.</para>

     <para>As a special exception, instead of an empty string array
     <constant>NULL</constant> may be returned, which should be treated
     equivalent to an empty string array.</para>

     <para>See
     <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     for more information about the functions
     implemented.</para>
   </refsect1>

   <refsect1>
     <title>Definition of Terms</title>

     <variablelist>
       <varlistentry>
         <term>seat</term>

         <listitem><para>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 (&lt;= 255 characters), that start
         with the four characters <literal>seat</literal> followed by at least one
         character from the range [a-zA-Z0-9], <literal>_</literal> and
         <literal>-</literal>. 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.
         </para></listitem>
       </varlistentry>

       <varlistentry>
         <term>session</term>

         <listitem><para>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.</para>

         <para>
         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         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],
         <literal>_</literal> and <literal>-</literal>, 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.</para>
         </listitem>
       </varlistentry>
     </variablelist>

     <para>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 <literal>seat0</literal>.</para>

     <para>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.)</para>

     <para><literal>seat0</literal> always exists.</para>
   </refsect1>

   <refsect1>
     <title>udev Rules</title>

     <para>Assignment of hardware devices to seats is managed inside the udev database, via
     settings on the devices:</para>

     <variablelist class='udev-directives'>
       <varlistentry>
         <term>Tag <literal>seat</literal></term>

         <listitem><para>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).
         </para></listitem>
       </varlistentry>

       <varlistentry>
         <term>Tag <literal>master-of-seat</literal></term>

         <listitem><para>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
         <literal>seat</literal> tag, but (at least) one of these devices needs to be
         tagged with <literal>master-of-seat</literal> before the seat is actually
         considered to be around.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term>Property <varname>ID_SEAT</varname></term>

         <listitem><para>This property specifies the name of the seat a specific device is
         assigned to. If not set the device is assigned to <literal>seat0</literal>. 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
         <varname>ID_SEAT=seat-waldo</varname> is set for a device, the tag
         <literal>seat-waldo</literal> will be set as well. Note that if a device is
         assigned to <literal>seat0</literal>, it will usually not carry such a tag and you
         need to enumerate all devices and check the <varname>ID_SEAT</varname> property
         manually. Again, if a device is assigned to seat0 this is visible on the device in
         two ways: with a property <varname>ID_SEAT=seat0</varname> and with no property
         <varname>ID_SEAT</varname> set for it at all.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term>Property <varname>ID_AUTOSEAT</varname></term>

         <listitem><para>When set to <literal>1</literal>, 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.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>Property <varname>ID_FOR_SEAT</varname></term>

         <listitem><para>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
         <literal>seat-</literal> and use it as name for the seat.</para></listitem>
       </varlistentry>
     </variablelist>

     <para>A seat exists only and exclusively because a properly tagged device with the
     right <varname>ID_SEAT</varname> property exists. Besides udev rules there is no
     persistent data about seats stored on disk.</para>

     <para>Note that
     <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     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.</para>
   </refsect1>

   <xi:include href="libsystemd-pkgconfig.xml" />

   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>

     <para>
       <ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat on Linux</ulink>
       may also be of historical interest.
     </para>
   </refsect1>
 </refentry>
	<?xml version='1.0'?> <!---nxml--->
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

	<refentry id="sd-login" conditional='HAVE_PAM'
	xmlns:xi="http://www.w3.org/2001/XInclude">

	<refentryinfo>
	<title>sd-login</title>
	<productname>systemd</productname>
	</refentryinfo>

	<refmeta>
	<refentrytitle>sd-login</refentrytitle>
	<manvolnum>3</manvolnum>
	</refmeta>

	<refnamediv>
	<refname>sd-login</refname>
	<refpurpose>APIs for
	tracking logins</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<funcsynopsis>
	<funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
	</funcsynopsis>

	<cmdsynopsis>
	<command>pkg-config --cflags --libs libsystemd</command>
	</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
	<title>Description</title>

	<para><filename>sd-login.h</filename> provides APIs to introspect
	and monitor seat, login session and user status information on the
	local system. </para>

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

	<para>These functions synchronously access data in
	<filename>/proc/</filename>, <filename>/sys/fs/cgroup/</filename>
	and <filename>/run/</filename>. All of these are virtual file
	systems, hence the runtime cost of the accesses is relatively
	cheap.</para>

	<para>It is possible (and often a very good choice) to mix calls
	to the synchronous interface of <filename>sd-login.h</filename>
	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
	<filename>sd-login.h</filename> interfaces such as the login
	monitor are asynchronous and not ordered against each
	other.</para>

	<para>If the functions return string arrays, these are generally
	<constant>NULL</constant> terminated and need to be freed by the
	caller with the libc
	<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
	call after use, including the strings referenced therein.
	Similarly, individual strings returned need to be freed, as
	well.</para>

	<para>As a special exception, instead of an empty string array
	<constant>NULL</constant> may be returned, which should be treated
	equivalent to an empty string array.</para>

	<para>See
	<citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
	for more information about the functions
	implemented.</para>
	</refsect1>

	<refsect1>
	<title>Definition of Terms</title>

	<variablelist>
	<varlistentry>
	<term>seat</term>

	<listitem><para>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 <literal>seat</literal> followed by at least one
	character from the range [a-zA-Z0-9], <literal>_</literal> and
	<literal>-</literal>. 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.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term>session</term>

	<listitem><para>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.</para>

	<para>
	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	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],
	<literal>_</literal> and <literal>-</literal>, 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.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>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 <literal>seat0</literal>.</para>

	<para>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.)</para>

	<para><literal>seat0</literal> always exists.</para>
	</refsect1>

	<refsect1>
	<title>udev Rules</title>

	<para>Assignment of hardware devices to seats is managed inside the udev database, via
	settings on the devices:</para>

	<variablelist class='udev-directives'>
	<varlistentry>
	<term>Tag <literal>seat</literal></term>

	<listitem><para>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).
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term>Tag <literal>master-of-seat</literal></term>

	<listitem><para>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
	<literal>seat</literal> tag, but (at least) one of these devices needs to be
	tagged with <literal>master-of-seat</literal> before the seat is actually
	considered to be around.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term>Property <varname>ID_SEAT</varname></term>

	<listitem><para>This property specifies the name of the seat a specific device is
	assigned to. If not set the device is assigned to <literal>seat0</literal>. 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
	<varname>ID_SEAT=seat-waldo</varname> is set for a device, the tag
	<literal>seat-waldo</literal> will be set as well. Note that if a device is
	assigned to <literal>seat0</literal>, it will usually not carry such a tag and you
	need to enumerate all devices and check the <varname>ID_SEAT</varname> property
	manually. Again, if a device is assigned to seat0 this is visible on the device in
	two ways: with a property <varname>ID_SEAT=seat0</varname> and with no property
	<varname>ID_SEAT</varname> set for it at all.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term>Property <varname>ID_AUTOSEAT</varname></term>

	<listitem><para>When set to <literal>1</literal>, 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.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Property <varname>ID_FOR_SEAT</varname></term>

	<listitem><para>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
	<literal>seat-</literal> and use it as name for the seat.</para></listitem>
	</varlistentry>
	</variablelist>

	<para>A seat exists only and exclusively because a properly tagged device with the
	right <varname>ID_SEAT</varname> property exists. Besides udev rules there is no
	persistent data about seats stored on disk.</para>

	<para>Note that
	<citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	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.</para>
	</refsect1>

	<xi:include href="libsystemd-pkgconfig.xml" />

	<refsect1>
	<title>See Also</title>
	<para>
	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	<citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	</para>

	<para>
	<ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat on Linux</ulink>
	may also be of historical interest.
	</para>
	</refsect1>
	</refentry>