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-or-later -->
   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     <refname>sd_uid_get_login_time</refname>
  26     <refpurpose>Determine login state of a specific Unix user ID</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  34         <funcdef>int <function>sd_uid_get_state</function></funcdef>
  35         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  36         <paramdef>char **<parameter>state</parameter></paramdef>
  37       </funcprototype>
  38
  39       <funcprototype>
  40         <funcdef>int <function>sd_uid_is_on_seat</function></funcdef>
  41         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  42         <paramdef>int <parameter>require_active</parameter></paramdef>
  43         <paramdef>const char *<parameter>seat</parameter></paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>int <function>sd_uid_get_sessions</function></funcdef>
  48         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  49         <paramdef>int <parameter>require_active</parameter></paramdef>
  50         <paramdef>char ***<parameter>sessions</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>int <function>sd_uid_get_seats</function></funcdef>
  55         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  56         <paramdef>int <parameter>require_active</parameter></paramdef>
  57         <paramdef>char ***<parameter>seats</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_uid_get_display</function></funcdef>
  62         <paramdef>uid_t <parameter>uid</parameter></paramdef>
  63         <paramdef>char **<parameter>session</parameter></paramdef>
  64       </funcprototype>
  65     </funcsynopsis>
  66
  67     <funcprototype>
  68        <funcdef>int <function>sd_uid_get_login_time</function></funcdef>
  69        <paramdef>uid_t <parameter>uid</parameter></paramdef>
  70        <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  71     </funcprototype>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>Description</title>
  76
  77     <para><function>sd_uid_get_state()</function> may be used to
  78     determine the login state of a specific Unix user identifier. The
  79     following states are currently known: <literal>offline</literal>
  80     (user not logged in at all), <literal>lingering</literal> (user
  81     not logged in, but some user services running),
  82     <literal>online</literal> (user logged in, but not active, i.e.
  83     has no session in the foreground), <literal>active</literal> (user
  84     logged in, and has at least one active session, i.e. one session
  85     in the foreground), <literal>closing</literal> (user not logged
  86     in, and not lingering, but some processes are still around). In
  87     the future additional states might be defined, client code should
  88     be written to be robust in regards to additional state strings
  89     being returned. The returned string needs to be freed with the
  90     libc
  91     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  92     call after use.</para>
  93
  94     <para><function>sd_uid_is_on_seat()</function> may be used to
  95     determine whether a specific user is logged in or active on a
  96     specific seat. Accepts a Unix user identifier and a seat
  97     identifier string as parameters. The
  98     <parameter>require_active</parameter> parameter is a boolean
  99     value. If non-zero (true), this function will test if the user is
 100     active (i.e. has a session that is in the foreground and accepting
 101     user input) on the specified seat, otherwise (false) only if the
 102     user is logged in (and possibly inactive) on the specified
 103     seat.</para>
 104
 105     <para><function>sd_uid_get_sessions()</function> may be used to
 106     determine the current sessions of the specified user. Accepts a
 107     Unix user identifier as parameter. The
 108     <parameter>require_active</parameter> parameter controls whether
 109     the returned list shall consist of only those sessions where the
 110     user is currently active (&gt; 0), where the user is currently
 111     online but possibly inactive (= 0), or logged in but
 112     possibly closing the session (&lt; 0). The call returns a
 113     <constant>NULL</constant> terminated string array of session
 114     identifiers in <parameter>sessions</parameter> which needs to be
 115     freed by the caller with the libc
 116     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 117     call after use, including all the strings referenced. If the
 118     string array parameter is passed as <constant>NULL</constant>, the
 119     array will not be filled in, but the return code still indicates
 120     the number of current sessions. Note that instead of an empty
 121     array <constant>NULL</constant> may be returned and should be
 122     considered equivalent to an empty array.</para>
 123
 124     <para>Similarly, <function>sd_uid_get_seats()</function> may be
 125     used to determine the list of seats on which the user currently
 126     has sessions. Similar semantics apply, however note that the user
 127     may have multiple sessions on the same seat as well as sessions
 128     with no attached seat and hence the number of entries in the
 129     returned array may differ from the one returned by
 130     <function>sd_uid_get_sessions()</function>.</para>
 131
 132     <para><function>sd_uid_get_display()</function> returns the name
 133     of the "primary" session of a user. If the user has graphical
 134     sessions, it will be the oldest graphical session. Otherwise, it
 135     will be the oldest open session.</para>
 136
 137     <para><function>sd_uid_get_login_time()</function> may be used to
 138     determine the time the user's service manager has been invoked,
 139     which is the time when the user's first active session, since which
 140     they stayed logged in continuously, began. The <parameter>usec</parameter>
 141     is in microseconds since the epoch (<constant>CLOCK_REALTIME</constant>).
 142     This call will fail with <constant>-ENXIO</constant> if the user is not
 143     currently logged in.</para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Return Value</title>
 148
 149     <para>On success, <function>sd_uid_get_state()</function> and
 150     <function>sd_uid_get_login_time()</function> returns 0 or a positive
 151     integer. If the test succeeds, <function>sd_uid_is_on_seat()</function>
 152     returns a positive integer; if it fails, 0. <function>sd_uid_get_sessions()</function>
 153     and <function>sd_uid_get_seats()</function> return the number of entries
 154     in the returned arrays. <function>sd_uid_get_display()</function>
 155     returns a non-negative code on success. On failure, these calls return
 156     a negative errno-style error code.</para>
 157
 158     <refsect2>
 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 user.</para>
 169           </listitem>
 170         </varlistentry>
 171
 172         <varlistentry>
 173           <term><constant>-ENXIO</constant></term>
 174
 175           <listitem><para>The specified seat is unknown.</para>
 176           </listitem>
 177         </varlistentry>
 178
 179         <varlistentry>
 180           <term><constant>-EINVAL</constant></term>
 181
 182           <listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>,
 183           where that is not accepted). This is also returned if the passed user ID is
 184           <constant>0xFFFF</constant> or <constant>0xFFFFFFFF</constant>, which are undefined on Linux.
 185           </para></listitem>
 186         </varlistentry>
 187
 188         <varlistentry>
 189           <term><constant>-ENOMEM</constant></term>
 190
 191           <listitem><para>Memory allocation failed.</para></listitem>
 192         </varlistentry>
 193       </variablelist>
 194     </refsect2>
 195   </refsect1>
 196
 197   <xi:include href="libsystemd-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>