X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_session_is_active.xml;h=70d201e29b7f5d580f4b1c078c6d1394780a0d81;hb=124457a19a42925520f22543b971ff3e98cb2f7c;hp=76f6f9544ce3c8daa9f232f4739ec28986daae53;hpb=56ba3c78ae35065064c4289a0c8e22a81256af20;p=elogind.git

diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml
index 76f6f9544..70d201e29 100644
--- a/man/sd_session_is_active.xml
+++ b/man/sd_session_is_active.xml
@@ -1,6 +1,9 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "custom-entities.ent" >
+%entities;
+]>
 
 <!--
   This file is part of systemd.
@@ -23,235 +26,300 @@
 
 <refentry id="sd_session_is_active" conditional='HAVE_PAM'>
 
-        <refentryinfo>
-                <title>sd_session_is_active</title>
-                <productname>systemd</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>Developer</contrib>
-                                <firstname>Lennart</firstname>
-                                <surname>Poettering</surname>
-                                <email>lennart@poettering.net</email>
-                        </author>
-                </authorgroup>
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>sd_session_is_active</refentrytitle>
-                <manvolnum>3</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>sd_session_is_active</refname>
-                <refname>sd_session_get_state</refname>
-                <refname>sd_session_get_uid</refname>
-                <refname>sd_session_get_seat</refname>
-                <refname>sd_session_get_service</refname>
-                <refname>sd_session_get_type</refname>
-                <refname>sd_session_get_class</refname>
-                <refname>sd_session_get_display</refname>
-                <refname>sd_session_get_tty</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_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_seat</function></funcdef>
-                                <paramdef>const char* <parameter>session</parameter></paramdef>
-                                <paramdef>char** <parameter>seat</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_display</function></funcdef>
-                                <paramdef>const char* <parameter>session</parameter></paramdef>
-                                <paramdef>char** <parameter>display</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>
-                </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_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><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_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 for them. The
-                returned string needs to be freed with the libc
-                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call after use.</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><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>tty</literal> or
-                <literal>unspecified</literal> and needs to be freed
-                with the libc
-                <citerefentry><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> or
-                <literal>lock-screen</literal> and needs to be freed
-                with the libc
-                <citerefentry><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><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call after use.</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><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call after use.</para>
-
-                <para>If the <literal>session</literal> parameter of
-                any of these functions is passed as NULL 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> returns 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_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> 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>
-        </refsect1>
-
-        <refsect1>
-                <title>Notes</title>
-
-                <para>The <function>sd_session_is_active()</function>,
-                <function>sd_session_get_state()</function>,
-                <function>sd_session_get_uid()</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> and
-                <function>sd_session_get_tty()</function>
-                interfaces are available as shared library, which can
-                be compiled and linked to with the
-                <literal>libsystemd-login</literal>
-                <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                file.</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>
+  <refentryinfo>
+    <title>sd_session_is_active</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </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_seat</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>
+    <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_seat</function></funcdef>
+        <paramdef>const char *<parameter>session</parameter></paramdef>
+        <paramdef>char **<parameter>seat</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_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_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 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_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="http://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_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_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_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>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para>The <function>sd_session_is_active()</function>,
+    <function>sd_session_get_state()</function>,
+    <function>sd_session_get_uid()</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_remote_host()</function>,
+    <function>sd_session_get_remote_user()</function> and
+    <function>sd_session_get_tty()</function>
+    interfaces are available as a shared library, which can
+    be compiled and linked to with the
+    <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    file.</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>