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