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