Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 368 insertions, 0 deletions

diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml
new file mode 100644
index 0000000..79cf8af
--- /dev/null
+++ b/man/sd_session_is_active.xml
@@ -0,0 +1,368 @@
+<?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_session_is_active" conditional='HAVE_PAM'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_session_is_active</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_session_is_active</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_session_is_active</refname>
+    <refname>sd_session_is_remote</refname>
+    <refname>sd_session_get_state</refname>
+    <refname>sd_session_get_uid</refname>
+    <refname>sd_session_get_username</refname>
+    <refname>sd_session_get_seat</refname>
+    <refname>sd_session_get_start_time</refname>
+    <refname>sd_session_get_service</refname>
+    <refname>sd_session_get_type</refname>
+    <refname>sd_session_get_class</refname>
+    <refname>sd_session_get_desktop</refname>
+    <refname>sd_session_get_display</refname>
+    <refname>sd_session_get_tty</refname>
+    <refname>sd_session_get_vt</refname>
+    <refname>sd_session_get_remote_host</refname>
+    <refname>sd_session_get_remote_user</refname>
+    <refname>sd_session_get_leader</refname>
+    <refpurpose>Determine state of a specific session</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_is_active</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_is_remote</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_state</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>state</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_uid</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>uid_t *<parameter>uid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_username</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>username</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_seat</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>seat</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_start_time</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_service</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>service</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_type</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>type</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_class</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>class</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_desktop</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>desktop</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_display</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>display</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_leader</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>pid_t *<parameter>leader</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>remote_host</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>remote_user</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_tty</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>tty</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_session_get_vt</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_session_is_active()</function> may be used to
+    determine whether the session identified by the specified session
+    identifier is currently active (i.e. currently in the foreground
+    and available for user input) or not.</para>
+
+    <para><function>sd_session_is_remote()</function> may be used to
+    determine whether the session identified by the specified session
+    identifier is a remote session (i.e. its remote host is known) or
+    not.</para>
+
+    <para><function>sd_session_get_state()</function> may be used to
+    determine the state of the session identified by the specified
+    session identifier. The following states are currently known:
+    <literal>online</literal> (session logged in, but session not
+    active, i.e. not in the foreground), <literal>active</literal>
+    (session logged in and active, i.e. in the foreground),
+    <literal>closing</literal> (session nominally logged out, but some
+    processes belonging to it are still around). In the future
+    additional states might be defined, client code should be written
+    to be robust in regards to additional state strings being
+    returned. This function is a more generic version of
+    <function>sd_session_is_active()</function>. 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_session_get_uid()</function> may be used to
+    determine the user identifier of the Unix user the session
+    identified by the specified session identifier belongs to.</para>
+
+    <para><function>sd_session_get_username()</function> may be used to
+    determine the name of the Unix user the session identified by
+    the specified session identifier belongs to. 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_session_get_seat()</function> may be used to
+    determine the seat identifier of the seat the session identified
+    by the specified session identifier belongs to. Note that not all
+    sessions are attached to a seat, this call will fail (returning
+    <constant>-ENODATA</constant>) for them. 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_session_get_start_time()</function> may be used to
+    determine the start time of the session identified by the specified
+    session identifier belongs to. The <parameter>usec</parameter>
+    is in microseconds since the epoch (<constant>CLOCK_REALTIME</constant>).</para>
+
+    <para><function>sd_session_get_service()</function> may be used to
+    determine the name of the service (as passed during PAM session
+    setup) that registered the session identified by the specified
+    session identifier. 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_session_get_type()</function> may be used to
+    determine the type of the session identified by the specified
+    session identifier. The returned string is one of
+    <literal>x11</literal>, <literal>wayland</literal>,
+    <literal>tty</literal>, <literal>mir</literal> or
+    <literal>unspecified</literal> and 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_session_get_class()</function> may be used to
+    determine the class of the session identified by the specified
+    session identifier. The returned string is one of
+    <literal>user</literal>, <literal>greeter</literal>,
+    <literal>lock-screen</literal>, or <literal>background</literal>
+    and 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_session_get_desktop()</function> may be used to
+    determine the brand of the desktop running on the session
+    identified by the specified session identifier. This field can be
+    set freely by desktop environments and does not follow any special
+    formatting. However, desktops are strongly recommended to use the
+    same identifiers and capitalization as for
+    <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
+    url="https://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
+    Entry Specification</ulink>. 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_session_get_display()</function> may be used to
+    determine the X11 display of the session identified by the
+    specified session identifier. 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_session_get_leader()</function> may be used to
+    determine the PID of the leader of the session identified by the
+    specified session identifier.</para>
+
+    <para><function>sd_session_get_remote_host()</function> may be
+    used to determine the remote hostname of the session identified by
+    the specified session identifier. 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_session_get_remote_user()</function> may be
+    used to determine the remote username of the session identified by
+    the specified session identifier. The returned string needs to be
+    freed with the libc
+    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    call after use. Note that this value is rarely known to the
+    system, and even then should not be relied on.</para>
+
+    <para><function>sd_session_get_tty()</function> may be used to
+    determine the TTY device of the session identified by the
+    specified session identifier. 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_session_get_vt()</function> may be used to
+    determine the VT number of the session identified by the specified
+    session identifier. This function will return an error if the seat
+    does not support VTs.</para>
+
+    <para>If the <varname>session</varname> parameter of any of these
+    functions is passed as <constant>NULL</constant>, the operation is
+    executed for the session the calling process is a member of, if
+    there is any.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>If the test succeeds,
+    <function>sd_session_is_active()</function> and
+    <function>sd_session_is_remote()</function> return a
+    positive integer; if it fails, 0.  On success,
+    <function>sd_session_get_state()</function>,
+    <function>sd_session_get_uid()</function>,
+    <function>sd_session_get_username()</function>,
+    <function>sd_session_get_seat()</function>,
+    <function>sd_session_get_service()</function>,
+    <function>sd_session_get_type()</function>,
+    <function>sd_session_get_class()</function>,
+    <function>sd_session_get_display()</function>,
+    <function>sd_session_get_leader()</function>,
+    <function>sd_session_get_remote_user()</function>,
+    <function>sd_session_get_remote_host()</function> and
+    <function>sd_session_get_tty()</function> return 0 or
+    a positive integer. 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>-ENXIO</constant></term>
+
+          <listitem><para>The specified session does not exist.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENODATA</constant></term>
+
+          <listitem><para>The given field is not specified for the described session.</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><function>sd_session_get_state()</function> was added in version 186.</para>
+    <para><function>sd_session_get_tty()</function> was added in version 198.</para>
+    <para><function>sd_session_get_vt()</function> was added in version 207.</para>
+    <para><function>sd_session_is_remote()</function>,
+    <function>sd_session_get_remote_host()</function>, and
+    <function>sd_session_get_remote_user()</function> were added in version 209.</para>
+    <para><function>sd_session_get_desktop()</function> was added in version 217.</para>
+    <para><function>sd_session_get_username()</function>,
+    <function>sd_session_get_start_time()</function>, and
+    <function>sd_session_get_leader()</function> were added in version 254.</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_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>