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