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