1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-23 17:34:00 +03:00
systemd-stable/man/sd_seat_get_active.xml
Zbigniew Jędrzejewski-Szmek 8f8cc84ba4 sd-login: get rid of seat_can_multi_session()
Follow-up for fa2cf64a91.
Backwards-compat is retained. A short note is added in docs, in case
people see sd_seat_can_multi_session() mentioned somewhere and wonder what
happened to it.

Also see https://github.com/systemd/systemd/pull/15337#issuecomment-610369404.
2020-04-17 16:15:30 +02:00

168 lines
6.4 KiB
XML

<?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+ -->
<refentry id="sd_seat_get_active" conditional='HAVE_PAM'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_seat_get_active</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_seat_get_active</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_seat_get_active</refname>
<refname>sd_seat_get_sessions</refname>
<refname>sd_seat_can_tty</refname>
<refname>sd_seat_can_graphical</refname>
<refpurpose>Determine state of a specific seat</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_seat_get_active</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
<paramdef>char **<parameter>session</parameter></paramdef>
<paramdef>uid_t *<parameter>uid</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_get_sessions</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
<paramdef>char ***<parameter>sessions</parameter></paramdef>
<paramdef>uid_t **<parameter>uid</parameter></paramdef>
<paramdef>unsigned int *<parameter>n_uids</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_can_tty</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_can_graphical</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_seat_get_active()</function> may be used to
determine which session is currently active on a seat, if there is
any. Returns the session identifier and the user identifier of the
Unix user the session is belonging to. Either the session or the
user identifier parameter can be passed <constant>NULL</constant>,
in case only one of the parameters shall be queried. The returned
string needs to be freed with the libc
<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call after use.</para>
<para><function>sd_seat_get_sessions()</function> may be used to
determine all sessions on the specified seat. Returns two arrays,
one (<constant>NULL</constant> terminated) with the session
identifiers of the sessions and one with the user identifiers of
the Unix users the sessions belong to. An additional parameter may
be used to return the number of entries in the latter array. This
value is the same the return value, if the latter is nonnegative.
The two arrays and the last parameter may be passed as
<constant>NULL</constant> in case these values need not to be
determined. The arrays and the strings referenced by them need to
be freed with the libc
<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call after use. Note that instead of an empty array
<constant>NULL</constant> may be returned and should be considered
equivalent to an empty array.</para>
<para><function>sd_seat_can_tty()</function> may be used to
determine whether a specific seat provides TTY functionality, i.e.
is useful as a text console.</para>
<para><function>sd_seat_can_graphical()</function> may be used to
determine whether a specific seat provides graphics functionality,
i.e. is useful as a graphics display.</para>
<para>If the <varname>seat</varname> parameter of any of these
functions is passed as <constant>NULL</constant>, the operation is
executed for the seat of the session of the calling process, if
there is any.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para> On success, <function>sd_seat_get_active()</function> returns 0 or a positive integer. On success,
<function>sd_seat_get_sessions()</function> returns the number of entries in the session identifier
array. If the test succeeds,
<function>sd_seat_can_tty</function> and <function>sd_seat_can_graphical</function> return a positive
integer, if it fails 0. On failure, these calls return a negative errno-style error code.</para>
<refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ENODATA</constant></term>
<listitem><para>The given field is not specified for the described seat.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENXIO</constant></term>
<listitem><para>The specified seat is unknown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, where
that is not accepted).</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>History</title>
<para>In the past, <function>sd_seat_can_multi_session()</function> was used to check whether the seat
supports multiple sessions. All seats support that now, so that function has been deprecated and always
returns true.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>