systemd/man/sd_seat_get_active.xml
Zbigniew Jędrzejewski-Szmek 3a54a15760 man: use same header for all files
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.

$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n  "http^gms' man/*.xml
2019-03-14 14:42:05 +01:00

176 lines
6.6 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_multi_session</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_multi_session</function></funcdef>
<paramdef>const char *<parameter>seat</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_multi_session()</function> may be used
to determine whether a specific seat is capable of multi-session,
i.e. allows multiple login sessions in parallel (with only one
being active at a time).</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_multi_session</function>,
<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>
</refsect1>
<refsect1>
<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 NULL, where that is not accepted).</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<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>