man/sd_uid_get_state.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_uid_get_state" conditional='HAVE_PAM'
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>sd_uid_get_state</title>
  14     <productname>systemd</productname>
  15
  16     <authorgroup>
  17       <author>
  18         <contrib>Developer</contrib>
  19         <firstname>Lennart</firstname>
  20         <surname>Poettering</surname>
  21         <email>lennart@poettering.net</email>
  22       </author>
  23     </authorgroup>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle>sd_uid_get_state</refentrytitle>
  28     <manvolnum>3</manvolnum>
  29   </refmeta>
  30
  31   <refnamediv>
  32     <refname>sd_uid_get_state</refname>
  33     <refname>sd_uid_is_on_seat</refname>
  34     <refname>sd_uid_get_sessions</refname>
  35     <refname>sd_uid_get_seats</refname>
  36     <refname>sd_uid_get_display</refname>
  37     <refpurpose>Determine login state of a specific Unix user ID</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_uid_get_state</function></funcdef>
  46         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  47         <paramdef>char **<parameter>state</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_uid_is_on_seat</function></funcdef>
  52         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  53         <paramdef>int <parameter>require_active</parameter></paramdef>
  54         <paramdef>const char *<parameter>seat</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_uid_get_sessions</function></funcdef>
  59         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  60         <paramdef>int <parameter>require_active</parameter></paramdef>
  61         <paramdef>char ***<parameter>sessions</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_uid_get_seats</function></funcdef>
  66         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  67         <paramdef>int <parameter>require_active</parameter></paramdef>
  68         <paramdef>char ***<parameter>seats</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_uid_get_display</function></funcdef>
  73         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  74         <paramdef>char **<parameter>session</parameter></paramdef>
  75       </funcprototype>
  76     </funcsynopsis>
  77   </refsynopsisdiv>
  78
  79   <refsect1>
  80     <title>Description</title>
  81
  82     <para><function>sd_uid_get_state()</function> may be used to
  83     determine the login state of a specific Unix user identifier. The
  84     following states are currently known: <literal>offline</literal>
  85     (user not logged in at all), <literal>lingering</literal> (user
  86     not logged in, but some user services running),
  87     <literal>online</literal> (user logged in, but not active, i.e.
  88     has no session in the foreground), <literal>active</literal> (user
  89     logged in, and has at least one active session, i.e. one session
  90     in the foreground), <literal>closing</literal> (user not logged
  91     in, and not lingering, but some processes are still around). In
  92     the future additional states might be defined, client code should
  93     be written to be robust in regards to additional state strings
  94     being returned. The returned string needs to be freed with the
  95     libc
  96     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  97     call after use.</para>
  98
  99     <para><function>sd_uid_is_on_seat()</function> may be used to
 100     determine whether a specific user is logged in or active on a
 101     specific seat. Accepts a Unix user identifier and a seat
 102     identifier string as parameters. The
 103     <parameter>require_active</parameter> parameter is a boolean
 104     value. If non-zero (true), this function will test if the user is
 105     active (i.e. has a session that is in the foreground and accepting
 106     user input) on the specified seat, otherwise (false) only if the
 107     user is logged in (and possibly inactive) on the specified
 108     seat.</para>
 109
 110     <para><function>sd_uid_get_sessions()</function> may be used to
 111     determine the current sessions of the specified user. Accepts a
 112     Unix user identifier as parameter. The
 113     <parameter>require_active</parameter> parameter controls whether
 114     the returned list shall consist of only those sessions where the
 115     user is currently active (&gt; 0), where the user is currently
 116     online but possibly inactive (= 0), or logged in at all but
 117     possibly closing the session (&lt; 0). The call returns a
 118     <constant>NULL</constant> terminated string array of session
 119     identifiers in <parameter>sessions</parameter> which needs to be
 120     freed by the caller with the libc
 121     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 122     call after use, including all the strings referenced. If the
 123     string array parameter is passed as <constant>NULL</constant>, the
 124     array will not be filled in, but the return code still indicates
 125     the number of current sessions. Note that instead of an empty
 126     array <constant>NULL</constant> may be returned and should be
 127     considered equivalent to an empty array.</para>
 128
 129     <para>Similarly, <function>sd_uid_get_seats()</function> may be
 130     used to determine the list of seats on which the user currently
 131     has sessions. Similar semantics apply, however note that the user
 132     may have multiple sessions on the same seat as well as sessions
 133     with no attached seat and hence the number of entries in the
 134     returned array may differ from the one returned by
 135     <function>sd_uid_get_sessions()</function>.</para>
 136
 137     <para><function>sd_uid_get_display()</function> returns the name
 138     of the "primary" session of a user. If the user has graphical
 139     sessions, it will be the oldest graphical session. Otherwise, it
 140     will be the oldest open session.</para>
 141   </refsect1>
 142
 143   <refsect1>
 144     <title>Return Value</title>
 145
 146     <para>On success, <function>sd_uid_get_state()</function> returns
 147     0 or a positive integer. If the test succeeds,
 148     <function>sd_uid_is_on_seat()</function> returns a positive
 149     integer; if it fails, 0.
 150     <function>sd_uid_get_sessions()</function> and
 151     <function>sd_uid_get_seats()</function> return the number of
 152     entries in the returned arrays.
 153     <function>sd_uid_get_display()</function> returns a non-negative
 154     code on success. On failure, these calls return a negative
 155     errno-style error code.</para>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>Errors</title>
 160
 161     <para>Returned errors may indicate the following problems:</para>
 162
 163     <variablelist>
 164
 165       <varlistentry>
 166         <term><constant>-ENODATA</constant></term>
 167
 168         <listitem><para>The given field is not specified for the described
 169         user.</para>
 170         </listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><constant>-ENXIO</constant></term>
 175
 176         <listitem><para>The specified seat is unknown.</para>
 177         </listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><constant>-EINVAL</constant></term>
 182
 183         <listitem><para>An input parameter was invalid (out of range,
 184         or NULL, where that is not accepted). This is also returned if
 185         the passed user ID is 0xFFFF or 0xFFFFFFFF, which are
 186         undefined on Linux.</para></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><constant>-ENOMEM</constant></term>
 191
 192         <listitem><para>Memory allocation failed.</para></listitem>
 193       </varlistentry>
 194     </variablelist>
 195   </refsect1>
 196
 197   <xi:include href="libelogind-pkgconfig.xml" />
 198
 199   <refsect1>
 200     <title>See Also</title>
 201
 202     <para>
 203       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 204       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 205       <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 206     </para>
 207   </refsect1>
 208
 209 </refentry>