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