man/sd_session_is_active.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
   9 <refentry id="sd_session_is_active" conditional='HAVE_PAM'
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>sd_session_is_active</title>
  14     <productname>elogind</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>sd_session_is_active</refentrytitle>
  19     <manvolnum>3</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>sd_session_is_active</refname>
  24     <refname>sd_session_is_remote</refname>
  25     <refname>sd_session_get_state</refname>
  26     <refname>sd_session_get_uid</refname>
  27     <refname>sd_session_get_seat</refname>
  28     <refname>sd_session_get_service</refname>
  29     <refname>sd_session_get_type</refname>
  30     <refname>sd_session_get_class</refname>
  31     <refname>sd_session_get_desktop</refname>
  32     <refname>sd_session_get_display</refname>
  33     <refname>sd_session_get_tty</refname>
  34     <refname>sd_session_get_vt</refname>
  35     <refname>sd_session_get_remote_host</refname>
  36     <refname>sd_session_get_remote_user</refname>
  37     <refpurpose>Determine state of a specific session</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;elogind/sd-login.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_session_is_active</function></funcdef>
  46         <paramdef>const char *<parameter>session</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_session_is_remote</function></funcdef>
  51         <paramdef>const char *<parameter>session</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>int <function>sd_session_get_state</function></funcdef>
  56         <paramdef>const char *<parameter>session</parameter></paramdef>
  57         <paramdef>char **<parameter>state</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_session_get_uid</function></funcdef>
  62         <paramdef>const char *<parameter>session</parameter></paramdef>
  63         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_session_get_seat</function></funcdef>
  68         <paramdef>const char *<parameter>session</parameter></paramdef>
  69         <paramdef>char **<parameter>seat</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_session_get_service</function></funcdef>
  74         <paramdef>const char *<parameter>session</parameter></paramdef>
  75         <paramdef>char **<parameter>service</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_session_get_type</function></funcdef>
  80         <paramdef>const char *<parameter>session</parameter></paramdef>
  81         <paramdef>char **<parameter>type</parameter></paramdef>
  82       </funcprototype>
  83
  84       <funcprototype>
  85         <funcdef>int <function>sd_session_get_class</function></funcdef>
  86         <paramdef>const char *<parameter>session</parameter></paramdef>
  87         <paramdef>char **<parameter>class</parameter></paramdef>
  88       </funcprototype>
  89
  90       <funcprototype>
  91         <funcdef>int <function>sd_session_get_desktop</function></funcdef>
  92         <paramdef>const char *<parameter>session</parameter></paramdef>
  93         <paramdef>char **<parameter>desktop</parameter></paramdef>
  94       </funcprototype>
  95
  96       <funcprototype>
  97         <funcdef>int <function>sd_session_get_display</function></funcdef>
  98         <paramdef>const char *<parameter>session</parameter></paramdef>
  99         <paramdef>char **<parameter>display</parameter></paramdef>
 100       </funcprototype>
 101
 102       <funcprototype>
 103         <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
 104         <paramdef>const char *<parameter>session</parameter></paramdef>
 105         <paramdef>char **<parameter>remote_host</parameter></paramdef>
 106       </funcprototype>
 107
 108       <funcprototype>
 109         <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
 110         <paramdef>const char *<parameter>session</parameter></paramdef>
 111         <paramdef>char **<parameter>remote_user</parameter></paramdef>
 112       </funcprototype>
 113
 114       <funcprototype>
 115         <funcdef>int <function>sd_session_get_tty</function></funcdef>
 116         <paramdef>const char *<parameter>session</parameter></paramdef>
 117         <paramdef>char **<parameter>tty</parameter></paramdef>
 118       </funcprototype>
 119
 120       <funcprototype>
 121         <funcdef>int <function>sd_session_get_vt</function></funcdef>
 122         <paramdef>const char *<parameter>session</parameter></paramdef>
 123         <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
 124       </funcprototype>
 125     </funcsynopsis>
 126   </refsynopsisdiv>
 127
 128   <refsect1>
 129     <title>Description</title>
 130
 131     <para><function>sd_session_is_active()</function> may be used to
 132     determine whether the session identified by the specified session
 133     identifier is currently active (i.e. currently in the foreground
 134     and available for user input) or not.</para>
 135
 136     <para><function>sd_session_is_remote()</function> may be used to
 137     determine whether the session identified by the specified session
 138     identifier is a remote session (i.e. its remote host is known) or
 139     not.</para>
 140
 141     <para><function>sd_session_get_state()</function> may be used to
 142     determine the state of the session identified by the specified
 143     session identifier. The following states are currently known:
 144     <literal>online</literal> (session logged in, but session not
 145     active, i.e. not in the foreground), <literal>active</literal>
 146     (session logged in and active, i.e. in the foreground),
 147     <literal>closing</literal> (session nominally logged out, but some
 148     processes belonging to it are still around). In the future
 149     additional states might be defined, client code should be written
 150     to be robust in regards to additional state strings being
 151     returned. This function is a more generic version of
 152     <function>sd_session_is_active()</function>. The returned string
 153     needs to be freed with the libc
 154     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 155     call after use.</para>
 156
 157     <para><function>sd_session_get_uid()</function> may be used to
 158     determine the user identifier of the Unix user the session
 159     identified by the specified session identifier belongs to.</para>
 160
 161     <para><function>sd_session_get_seat()</function> may be used to
 162     determine the seat identifier of the seat the session identified
 163     by the specified session identifier belongs to. Note that not all
 164     sessions are attached to a seat, this call will fail (returning
 165     <constant>-ENODATA</constant>) for them. The returned string needs
 166     to be freed with the libc
 167     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 168     call after use.</para>
 169
 170     <para><function>sd_session_get_service()</function> may be used to
 171     determine the name of the service (as passed during PAM session
 172     setup) that registered the session identified by the specified
 173     session identifier. The returned string needs to be freed with the
 174     libc
 175     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 176     call after use.</para>
 177
 178     <para><function>sd_session_get_type()</function> may be used to
 179     determine the type of the session identified by the specified
 180     session identifier. The returned string is one of
 181     <literal>x11</literal>, <literal>wayland</literal>,
 182     <literal>tty</literal>, <literal>mir</literal> or
 183     <literal>unspecified</literal> and needs to be freed with the libc
 184     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 185     call after use.</para>
 186
 187     <para><function>sd_session_get_class()</function> may be used to
 188     determine the class of the session identified by the specified
 189     session identifier. The returned string is one of
 190     <literal>user</literal>, <literal>greeter</literal>,
 191     <literal>lock-screen</literal>, or <literal>background</literal>
 192     and needs to be freed with the libc
 193     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 194     call after use.</para>
 195
 196     <para><function>sd_session_get_desktop()</function> may be used to
 197     determine the brand of the desktop running on the session
 198     identified by the specified session identifier. This field can be
 199     set freely by desktop environments and does not follow any special
 200     formatting. However, desktops are strongly recommended to use the
 201     same identifiers and capitalization as for
 202     <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
 203     url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
 204     Entry Specification</ulink>. The returned string needs to be freed
 205     with the libc
 206     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 207     call after use.</para>
 208
 209     <para><function>sd_session_get_display()</function> may be used to
 210     determine the X11 display of the session identified by the
 211     specified session identifier. The returned string needs to be
 212     freed with the libc
 213     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 214     call after use.</para>
 215
 216     <para><function>sd_session_get_remote_host()</function> may be
 217     used to determine the remote hostname of the session identified by
 218     the specified session identifier. The returned string needs to be
 219     freed with the libc
 220     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 221     call after use.</para>
 222
 223     <para><function>sd_session_get_remote_user()</function> may be
 224     used to determine the remote username of the session identified by
 225     the specified session identifier. The returned string needs to be
 226     freed with the libc
 227     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 228     call after use. Note that this value is rarely known to the
 229     system, and even then should not be relied on.</para>
 230
 231     <para><function>sd_session_get_tty()</function> may be used to
 232     determine the TTY device of the session identified by the
 233     specified session identifier. The returned string needs to be
 234     freed with the libc
 235     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 236     call after use.</para>
 237
 238     <para><function>sd_session_get_vt()</function> may be used to
 239     determine the VT number of the session identified by the specified
 240     session identifier. This function will return an error if the seat
 241     does not support VTs.</para>
 242
 243     <para>If the <varname>session</varname> parameter of any of these
 244     functions is passed as <constant>NULL</constant>, the operation is
 245     executed for the session the calling process is a member of, if
 246     there is any.</para>
 247   </refsect1>
 248
 249   <refsect1>
 250     <title>Return Value</title>
 251
 252     <para>If the test succeeds,
 253     <function>sd_session_is_active()</function> and
 254     <function>sd_session_is_remote()</function> return a
 255     positive integer; if it fails, 0.  On success,
 256     <function>sd_session_get_state()</function>,
 257     <function>sd_session_get_uid()</function>,
 258     <function>sd_session_get_seat()</function>,
 259     <function>sd_session_get_service()</function>,
 260     <function>sd_session_get_type()</function>,
 261     <function>sd_session_get_class()</function>,
 262     <function>sd_session_get_display()</function>,
 263     <function>sd_session_get_remote_user()</function>,
 264     <function>sd_session_get_remote_host()</function> and
 265     <function>sd_session_get_tty()</function> return 0 or
 266     a positive integer. On failure, these calls return a
 267     negative errno-style error code.</para>
 268   </refsect1>
 269
 270   <refsect1>
 271     <title>Errors</title>
 272
 273     <para>Returned errors may indicate the following problems:</para>
 274
 275     <variablelist>
 276
 277       <varlistentry>
 278         <term><constant>-ENXIO</constant></term>
 279
 280         <listitem><para>The specified session does not exist.</para>
 281         </listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><constant>-ENODATA</constant></term>
 286
 287         <listitem><para>The given field is not specified for the described
 288         session.</para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><constant>-EINVAL</constant></term>
 294
 295         <listitem><para>An input parameter was invalid (out of range,
 296         or NULL, where that is not accepted).</para></listitem>
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term><constant>-ENOMEM</constant></term>
 301
 302         <listitem><para>Memory allocation failed.</para></listitem>
 303       </varlistentry>
 304     </variablelist>
 305   </refsect1>
 306
 307   <xi:include href="libelogind-pkgconfig.xml" />
 308
 309   <refsect1>
 310     <title>See Also</title>
 311
 312     <para>
 313       <!-- 0 /// elogind is in section 8
 314       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 315       --><!-- else -->
 316       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 317       <!-- // 0 -->
 318       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 319       <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 320     </para>
 321   </refsect1>
 322
 323 </refentry>