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