diff options
Diffstat (limited to 'man/sd_uid_get_state.xml')
| -rw-r--r-- | man/sd_uid_get_state.xml | 367 |
1 files changed, 178 insertions, 189 deletions
diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index e1b345c277..b158f3528c 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -1,6 +1,6 @@ <?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"> <!-- This file is part of systemd. @@ -23,193 +23,182 @@ <refentry id="sd_uid_get_state" conditional='HAVE_PAM'> - <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> - <refname>sd_uid_get_display</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>uid</parameter></paramdef> - <paramdef>char **<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> - <paramdef>uid_t <parameter>uid</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>uid</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>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>char ***<parameter>seats</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_display</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>char **<parameter>session</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, i.e. has no session in the foreground), - <literal>active</literal> (user logged in, and has at - least one active session, i.e. one session in the - foreground), <literal>closing</literal> (user not - logged in, and not lingering, but some processes 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. 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_uid_is_on_seat()</function> may be - used to determine whether a specific user is logged in - or active on a specific seat. Accepts a Unix user - identifier and a seat identifier string as - parameters. The <parameter>require_active</parameter> - parameter is a boolean value. If non-zero (true), this - function will test if the user is active (i.e. has a - session that is in the foreground and accepting user - input) on the specified seat, otherwise (false) only - if the user is logged in (and possibly inactive) on - the specified seat.</para> - - <para><function>sd_uid_get_sessions()</function> may - be used to determine the current sessions of the - specified user. Accepts a Unix user identifier as - parameter. The <parameter>require_active</parameter> - parameter controls whether the returned list shall - consist of only those sessions where the user is - currently active (> 0), where the user is currently - online but possibly inactive (= 0), or - logged in at all but possibly closing the session (< 0). The call returns a - <constant>NULL</constant> terminated string array of session identifiers in - <parameter>sessions</parameter> which needs to be - freed by the caller with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use, including all the strings - referenced. If the string array parameter is passed as - <constant>NULL</constant>, the array will not be filled in, but the return - code still indicates the number of current - sessions. Note that instead of an empty array <constant>NULL</constant> may - be returned and should be considered equivalent to an - empty array.</para> - - <para>Similarly, <function>sd_uid_get_seats()</function> - may be used to determine the list of seats on which - the user currently has sessions. Similar semantics - apply, however note that the user may have - multiple sessions on the same seat as well as sessions - with no attached seat and hence the number of entries - in the returned array may differ from the one returned - by <function>sd_uid_get_sessions()</function>.</para> - - <para><function>sd_uid_get_display()</function> - returns the name of the "primary" session of a user. - If the user has graphical sessions, it will be the - oldest graphical session. Otherwise, it will be the - oldest open session.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_uid_get_state()</function> returns 0 or a - positive integer. If the test succeeds, - <function>sd_uid_is_on_seat()</function> returns a - positive integer; if it fails, - 0. <function>sd_uid_get_sessions()</function> and - <function>sd_uid_get_seats()</function> return the - number of entries in the returned arrays. - <function>sd_uid_get_display()</function> returns - a non-negative code on success. On failure, - these calls return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>Functions described here are available as a - shared library, and can be compiled and linked to - using the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - entry.</para> - </refsect1> - - <refsect1> - <title>History</title> - - <function>sd_uid_get_state()</function>, - <function>sd_uid_is_on_seat()</function>, - <function>sd_uid_get_sessions()</function>, - and <function>sd_uid_get_seats()</function> functions - were added in systemd-31. - - <para><function>sd_uid_get_display()</function> was - added in systemd-213.</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_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <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> + <refname>sd_uid_get_display</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>uid</parameter></paramdef> + <paramdef>char **<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> + <paramdef>uid_t <parameter>uid</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>uid</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>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char ***<parameter>seats</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_display</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>session</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, i.e. + has no session in the foreground), <literal>active</literal> (user + logged in, and has at least one active session, i.e. one session + in the foreground), <literal>closing</literal> (user not logged + in, and not lingering, but some processes 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. 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_uid_is_on_seat()</function> may be used to + determine whether a specific user is logged in or active on a + specific seat. Accepts a Unix user identifier and a seat + identifier string as parameters. The + <parameter>require_active</parameter> parameter is a boolean + value. If non-zero (true), this function will test if the user is + active (i.e. has a session that is in the foreground and accepting + user input) on the specified seat, otherwise (false) only if the + user is logged in (and possibly inactive) on the specified + seat.</para> + + <para><function>sd_uid_get_sessions()</function> may be used to + determine the current sessions of the specified user. Accepts a + Unix user identifier as parameter. The + <parameter>require_active</parameter> parameter controls whether + the returned list shall consist of only those sessions where the + user is currently active (> 0), where the user is currently + online but possibly inactive (= 0), or logged in at all but + possibly closing the session (< 0). The call returns a + <constant>NULL</constant> terminated string array of session + identifiers in <parameter>sessions</parameter> which needs to be + freed by the caller with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including all the strings referenced. If the + string array parameter is passed as <constant>NULL</constant>, the + array will not be filled in, but the return code still indicates + the number of current sessions. Note that instead of an empty + array <constant>NULL</constant> may be returned and should be + considered equivalent to an empty array.</para> + + <para>Similarly, <function>sd_uid_get_seats()</function> may be + used to determine the list of seats on which the user currently + has sessions. Similar semantics apply, however note that the user + may have multiple sessions on the same seat as well as sessions + with no attached seat and hence the number of entries in the + returned array may differ from the one returned by + <function>sd_uid_get_sessions()</function>.</para> + + <para><function>sd_uid_get_display()</function> returns the name + of the "primary" session of a user. If the user has graphical + sessions, it will be the oldest graphical session. Otherwise, it + will be the oldest open session.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_uid_get_state()</function> returns + 0 or a positive integer. If the test succeeds, + <function>sd_uid_is_on_seat()</function> returns a positive + integer; if it fails, 0. + <function>sd_uid_get_sessions()</function> and + <function>sd_uid_get_seats()</function> return the number of + entries in the returned arrays. + <function>sd_uid_get_display()</function> returns a non-negative + code on success. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>Functions described here are available as a shared library, + and can be compiled and linked to using the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + entry.</para> + </refsect1> + + <refsect1> + <title>History</title> + + <para><function>sd_uid_get_state()</function>, + <function>sd_uid_is_on_seat()</function>, + <function>sd_uid_get_sessions()</function>, and + <function>sd_uid_get_seats()</function> functions were added in + systemd-31.</para> + + <para><function>sd_uid_get_display()</function> was added in + systemd-213.</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_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> |