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