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