man/sd_uid_get_state.xml

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