From caaed693b9e8b16102c794fa52850bbcb7cc6fd9 Mon Sep 17 00:00:00 2001

From: Lennart Poettering <lennart@poettering.net>

Date: Mon, 19 Dec 2011 03:02:17 +0100

Subject: [PATCH] man: document the sd-login interfaces (cherry picked from

 commit 0b3b020a178cf3b957fed627de13c895773995ec)

---

 man/sd_get_seats.xml         |  125 +++++++++++++++++++++++++++++

 man/sd_login_monitor_new.xml |  172 +++++++++++++++++++++++++++++++++++++++

 man/sd_pid_get_session.xml   |  136 +++++++++++++++++++++++++++++++

 man/sd_seat_get_active.xml   |  150 ++++++++++++++++++++++++++++++++++

 man/sd_session_is_active.xml |  134 +++++++++++++++++++++++++++++++

 man/sd_uid_get_state.xml     |  182 ++++++++++++++++++++++++++++++++++++++++++

 6 files changed, 899 insertions(+), 0 deletions(-)

 create mode 100644 man/sd_get_seats.xml

 create mode 100644 man/sd_login_monitor_new.xml

 create mode 100644 man/sd_pid_get_session.xml

 create mode 100644 man/sd_seat_get_active.xml

 create mode 100644 man/sd_session_is_active.xml

 create mode 100644 man/sd_uid_get_state.xml

diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml

new file mode 100644

index 0000000..bbc396a

--- /dev/null

+++ b/man/sd_get_seats.xml

@@ -0,0 +1,125 @@

+ 

+

+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

+

+

+  This file is part of systemd.

+

+  Copyright 2010 Lennart Poettering

+

+  systemd is free software; you can redistribute it and/or modify it

+  under the terms of the GNU General Public License as published by

+  the Free Software Foundation; either version 2 of the License, or

+  (at your option) any later version.

+

+  systemd is distributed in the hope that it will be useful, but

+  WITHOUT ANY WARRANTY; without even the implied warranty of

+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

+  General Public License for more details.

+

+  You should have received a copy of the GNU General Public License

+  along with systemd; If not, see <http://www.gnu.org/licenses/>.

+-->

+

+<refentry id="sd_get_seats">

+

+        <refentryinfo>

+                <title>sd_get_seats</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_get_seats</refentrytitle>

+                <manvolnum>3</manvolnum>

+        </refmeta>

+

+        <refnamediv>

+                <refname>sd_get_seats</refname>

+                <refname>sd_get_sessions</refname>

+                <refname>sd_get_uids</refname>

+                <refpurpose>Determine available seats, sessions and logged in users</refpurpose>

+        </refnamediv>

+

+        <refsynopsisdiv>

+                <funcsynopsis>

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

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_get_seats</function></funcdef>

+                                <paramdef>char*** <parameter>seats</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_get_sessions</function></funcdef>

+                                <paramdef>char*** <parameter>sessions</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_get_uids</function></funcdef>

+                                <paramdef>char*** <parameter>sessions</parameter></paramdef>

+                        </funcprototype>

+

+                </funcsynopsis>

+        </refsynopsisdiv>

+

+        <refsect1>

+                <title>Description</title>

+

+                <para><function>sd_get_seats()</function> may be used

+                to determine all currently available local

+                seats. Returns an array of seat identifiers. The

+                returned array and all strings it references need to

+                be freed with the libc

+                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

+                call after use.</para>

+

+                <para>Similar, <function>sd_get_sessions()</function> may

+                be used to determine all current login sessions.</para>

+

+                <para>Similar, <function>sd_get_uids()</function> may

+                be used to determine all Unix users who currently have login sessions.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Return Value</title>

+

+                <para>On success <function>sd_get_seats()</function>,

+                <function>sd_get_sessions()</function> and

+                <function>sd_get_uids()</function> return the number

+                of entries in the arrays. On failure, these calls

+                return a negative errno-style error code.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Notes</title>

+

+                <para>The <function>sd_get_seats()</function>,

+                <function>sd_get_sessions()</function> and

+                <function>sd_get_uids()</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>7</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

+                </para>

+        </refsect1>

+

+</refentry>

diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml

new file mode 100644

index 0000000..2b37f00

--- /dev/null

+++ b/man/sd_login_monitor_new.xml

@@ -0,0 +1,172 @@

+ 

+

+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

+

+

+  This file is part of systemd.

+

+  Copyright 2010 Lennart Poettering

+

+  systemd is free software; you can redistribute it and/or modify it

+  under the terms of the GNU General Public License as published by

+  the Free Software Foundation; either version 2 of the License, or

+  (at your option) any later version.

+

+  systemd is distributed in the hope that it will be useful, but

+  WITHOUT ANY WARRANTY; without even the implied warranty of

+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

+  General Public License for more details.

+

+  You should have received a copy of the GNU General Public License

+  along with systemd; If not, see <http://www.gnu.org/licenses/>.

+-->

+

+<refentry id="sd_login_monitor_new">

+

+        <refentryinfo>

+                <title>sd_login_monitor_new</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_login_monitor_new</refentrytitle>

+                <manvolnum>3</manvolnum>

+        </refmeta>

+

+        <refnamediv>

+                <refname>sd_login_monitor_new</refname>

+                <refname>sd_login_monitor_unref</refname>

+                <refname>sd_login_monitor_flush</refname>

+                <refname>sd_login_monitor_get_fd</refname>

+                <refpurpose>Monitor login sessions, seats and users</refpurpose>

+        </refnamediv>

+

+        <refsynopsisdiv>

+                <funcsynopsis>

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

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_login_monitor_new</function></funcdef>

+                                <paramdef>const char* <parameter>category</parameter></paramdef>

+                                <paramdef>sd_login_monitor** <parameter>ret</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>sd_login_monitor* <function>sd_login_monitor_unref</function></funcdef>

+                                <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_login_monitor_flush</function></funcdef>

+                                <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>

+                                <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>

+                        </funcprototype>

+

+                </funcsynopsis>

+        </refsynopsisdiv>

+

+        <refsect1>

+                <title>Description</title>

+

+                <para><function>sd_login_monitor_new()</function> may

+                be used to monitor login session, users and seats. Via

+                a monitor object a file descriptor can be integrated

+                into an application defined event loop which is woken

+                up each time a user logs in, logs out or a seat is

+                added or removed, or a session, user, or seat changes

+                state otherwise. The first parameter takes a string

+                which can be either <literal>seat</literal> (to get

+                only notifications about seats being added, removed or

+                changed), <literal>session</literal> (to get only

+                notifications about sessions being created or removed

+                or changed) or <literal>uid</literal> (to get only

+                notifications when a user changes state in respect to

+                logins). If notifications shall be generated in all

+                these conditions, NULL may be passed. Note that in

+                future additional categories may be defined. The

+                second parameter returns a monitor object and needs to

+                be freed with the

+                <function>sd_login_monitor_unref()</function> call

+                after use.</para>

+

+                <para><function>sd_login_monitor_unref()</function>

+                may be used to destroy a monitor object. Note that

+                this will invalidate any file descriptor returned by

+                <function>sd_login_monitor_get_fd()</function>.</para>

+

+                <para><function>sd_login_monitor_flush()</function>

+                may be used to reset the wakeup state of the monitor

+                object. Whenever an event causes the monitor to wake

+                up the event loop via the file descriptor this

+                function needs to be called to reset the wake-up

+                state. If this call is not invoked the file descriptor

+                will immediately wake up the event loop again.</para>

+

+                <para><function>sd_login_monitor_get_fd()</function>

+                may be used to retrieve the file descriptor of the

+                monitor object that may be integrated in an

+                application defined event loop, based around

+                <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>

+                or a similar interface. The application should include

+                the returned file descriptor as wake up source for

+                POLLIN events. Whenever a wake-up is triggered the

+                file descriptor needs to be reset via

+                <function>sd_login_monitor_flush()</function>. An

+                application needs to reread the login state with a

+                function like

+                <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>

+                or similar to determine what changed.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Return Value</title>

+

+                <para>On success

+                <function>sd_login_monitor_new()</function> and

+                <function>sd_login_monitor_flush()</function> return 0

+                or a positive integer. On success

+                <function>sd_login_monitor_get_fd()</function> returns

+                a Unix file descriptor. On failure, these calls return

+                a negative errno-style error code.</para>

+

+                <para><function>sd_login_monitor_unref()</function>

+                always returns NULL.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Notes</title>

+

+                <para>The <function>sd_login_monitor_new()</function>,

+                <function>sd_login_monitor_unref()</function>, <function>sd_login_monitor_flush()</function> and

+                <function>sd_login_monitor_get_fd()</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>7</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

+                </para>

+        </refsect1>

+

+</refentry>

diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml

new file mode 100644

index 0000000..9176433

--- /dev/null

+++ b/man/sd_pid_get_session.xml

@@ -0,0 +1,136 @@

+ 

+

+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

+

+

+  This file is part of systemd.

+

+  Copyright 2010 Lennart Poettering

+

+  systemd is free software; you can redistribute it and/or modify it

+  under the terms of the GNU General Public License as published by

+  the Free Software Foundation; either version 2 of the License, or

+  (at your option) any later version.

+

+  systemd is distributed in the hope that it will be useful, but

+  WITHOUT ANY WARRANTY; without even the implied warranty of

+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

+  General Public License for more details.

+

+  You should have received a copy of the GNU General Public License

+  along with systemd; If not, see <http://www.gnu.org/licenses/>.

+-->

+

+<refentry id="sd_pid_get_session">

+

+        <refentryinfo>

+                <title>sd_pid_get_session</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_pid_get_session</refentrytitle>

+                <manvolnum>3</manvolnum>

+        </refmeta>

+

+        <refnamediv>

+                <refname>sd_pid_get_session</refname>

+                <refname>sd_pid_get_owner_uid</refname>

+                <refpurpose>Determine session or owner of a session of a specific PID</refpurpose>

+        </refnamediv>

+

+        <refsynopsisdiv>

+                <funcsynopsis>

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

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_pid_get_session</function></funcdef>

+                                <paramdef>pid_t <parameter>pid</parameter></paramdef>

+                                <paramdef>char** <parameter>session</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>

+                                <paramdef>pid_t <parameter>pid</parameter></paramdef>

+                                <paramdef>uid_t* <parameter>uid</parameter></paramdef>

+                        </funcprototype>

+                </funcsynopsis>

+        </refsynopsisdiv>

+

+        <refsect1>

+                <title>Description</title>

+

+                <para><function>sd_pid_get_session()</function> may be

+                used to determine the login session identifier of a

+                process identified by the specified process identifier. The session

+                identifier is a short string (up to 64 characters),

+                consisting only of the characters a-zA-Z0-9 as well as

+                '-' and '_'. It is suitable for usage in file system

+                paths. Note that not all processes are part of a login

+                session (e.g. system service processes and user

+                processes that are shared between multiple sessions of

+                the same user). For processes not being part of a

+                login session this function will fail. 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_pid_get_owner_uid()</function> may

+                be used to determine the Unix user identifier of the

+                owner of the session of a process identified the

+                specified PID. Note that this function will succeed

+                for user processes which are shared between multiple

+                login sessions of the same user, where

+                <function>sd_pid_get_session()</function> will

+                fail. For processes not being part of a login session

+                and not being a shared process of a user this function

+                will fail.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Return Value</title>

+

+                <para>On success these calls 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_pid_get_session()</function>

+                and <function>sd_pid_get_owner_uid()</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>

+

+                <para>Note that the login session identifier as

+                returned by <function>sd_pid_get_session()</function>

+                is completely unrelated to the process session

+                identifier as returned by

+                <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>See Also</title>

+

+                <para>

+                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>

+                </para>

+        </refsect1>

+

+</refentry>

diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml

new file mode 100644

index 0000000..e729a65

--- /dev/null

+++ b/man/sd_seat_get_active.xml

@@ -0,0 +1,150 @@

+ 

+

+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

+

+

+  This file is part of systemd.

+

+  Copyright 2010 Lennart Poettering

+

+  systemd is free software; you can redistribute it and/or modify it

+  under the terms of the GNU General Public License as published by

+  the Free Software Foundation; either version 2 of the License, or

+  (at your option) any later version.

+

+  systemd is distributed in the hope that it will be useful, but

+  WITHOUT ANY WARRANTY; without even the implied warranty of

+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

+  General Public License for more details.

+

+  You should have received a copy of the GNU General Public License

+  along with systemd; If not, see <http://www.gnu.org/licenses/>.

+-->

+

+<refentry id="sd_seat_get_active">

+

+        <refentryinfo>

+                <title>sd_seat_get_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_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>

+                <refpurpose>Determine state of a specific seat</refpurpose>

+        </refnamediv>

+

+        <refsynopsisdiv>

+                <funcsynopsis>

+                        <funcsynopsisinfo>#include <systemd/sd-login.h></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* <parameter>n_uids</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_seat_can_multi_session</function></funcdef>

+                                <paramdef>const char* <parameter>session</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 be passed NULL, in

+                case only one of the parameters shall be queried. 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_seat_get_sessions()</function> may

+                be used to determine all sessions on the specified

+                seat. Returns two arrays, one (NULL 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. The

+                two arrays and the latter parameter may be passed as

+                NULL 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><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

+                call after use.</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 (whith only one being active at a

+                time).</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Return Value</title>

+

+                <para> On success

+                <function>sd_seat_get_active()</function> return

+                return 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> returns

+                a positive integer, if it fails 0. On failure, these

+                calls return a negative errno-style error code.</para>

+        </refsect1>

+

+        <refsect1>

+                <title>Notes</title>

+

+                <para>The <function>sd_seat_get_active()</function>,

+                <function>sd_seat_get_sessions()</function>, and

+                <function>sd_seat_can_multi_session()</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>7</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

+                </para>

+        </refsect1>

+

+</refentry>

diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml

new file mode 100644

index 0000000..82919f8

--- /dev/null

+++ b/man/sd_session_is_active.xml

@@ -0,0 +1,134 @@

+ 

+

+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

+

+

+  This file is part of systemd.

+

+  Copyright 2010 Lennart Poettering

+

+  systemd is free software; you can redistribute it and/or modify it

+  under the terms of the GNU General Public License as published by

+  the Free Software Foundation; either version 2 of the License, or

+  (at your option) any later version.

+

+  systemd is distributed in the hope that it will be useful, but

+  WITHOUT ANY WARRANTY; without even the implied warranty of

+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

+  General Public License for more details.

+

+  You should have received a copy of the GNU General Public License

+  along with systemd; If not, see <http://www.gnu.org/licenses/>.

+-->

+

+<refentry id="sd_session_is_active">

+

+        <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_uid</refname>

+                <refname>sd_session_get_seat</refname>

+                <refpurpose>Determine state of a specific session</refpurpose>

+        </refnamediv>

+

+        <refsynopsisdiv>

+                <funcsynopsis>

+                        <funcsynopsisinfo>#include <systemd/sd-login.h></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_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>

+                </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_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>

+        </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_uid()</function> and

+                <function>sd_session_get_seat()</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_uid()</function>, and

+                <function>sd_session_get_seat()</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>7</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

+                </para>

+        </refsect1>

+

+</refentry>

diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml

new file mode 100644

index 0000000..a4e9e73

--- /dev/null

+++ b/man/sd_uid_get_state.xml

@@ -0,0 +1,182 @@

+ 

+

+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

+

+

+  This file is part of systemd.

+

+  Copyright 2010 Lennart Poettering

+

+  systemd is free software; you can redistribute it and/or modify it

+  under the terms of the GNU General Public License as published by

+  the Free Software Foundation; either version 2 of the License, or

+  (at your option) any later version.

+

+  systemd is distributed in the hope that it will be useful, but

+  WITHOUT ANY WARRANTY; without even the implied warranty of

+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

+  General Public License for more details.

+

+  You should have received a copy of the GNU General Public License

+  along with systemd; If not, see <http://www.gnu.org/licenses/>.

+-->

+

+<refentry id="sd_uid_get_state">

+

+        <refentryinfo>

+                <title>sd_uid_get_state</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_uid_get_state</refentrytitle>

+                <manvolnum>3</manvolnum>

+        </refmeta>

+

+        <refnamediv>

+                <refname>sd_uid_get_state</refname>

+                <refname>sd_uid_is_on_seat</refname>

+                <refname>sd_uid_get_sessions</refname>

+                <refname>sd_uid_get_seats</refname>

+                <refpurpose>Determine login state of a specific Unix user ID</refpurpose>

+        </refnamediv>

+

+        <refsynopsisdiv>

+                <funcsynopsis>

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

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_uid_get_state</function></funcdef>

+                                <paramdef>uid_t <parameter>pid</parameter></paramdef>

+                                <paramdef>char** <parameter>state</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_uid_is_on_seat</function></funcdef>

+                                <paramdef>uid_t <parameter>pid</parameter></paramdef>

+                                <paramdef>int <parameter>require_active</parameter></paramdef>

+                                <paramdef>const char* <parameter>seat</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_uid_get_sessions</function></funcdef>

+                                <paramdef>uid_t <parameter>pid</parameter></paramdef>

+                                <paramdef>int <parameter>require_active</parameter></paramdef>

+                                <paramdef>char*** <parameter>sessions</parameter></paramdef>

+                        </funcprototype>

+

+                        <funcprototype>

+                                <funcdef>int <function>sd_uid_get_seats</function></funcdef>

+                                <paramdef>uid_t <parameter>pid</parameter></paramdef>

+                                <paramdef>int <parameter>require_active</parameter></paramdef>

+                                <paramdef>char*** <parameter>seats</parameter></paramdef>

+                        </funcprototype>

+                </funcsynopsis>

+        </refsynopsisdiv>

+

+        <refsect1>

+                <title>Description</title>

+

+                <para><function>sd_uid_get_state()</function> may be

+                used to determine the login state of a specific Unix

+                user identifier. The following states are currently

+                known: <literal>offline</literal> (user not logged in

+                at all), <literal>lingering</literal> (user not logged

+                in, but some user services running),

+                <literal>online</literal> (user logged in, but not

+                active), <literal>active</literal> (user logged in on

+                an active seat). In the future additional states might

+                be defined, client code should be written to be robust

+                in regards to additional state strings being

+                returned. The returned string needs to be freed with

+                the libc

+                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

+                call after use.</para>