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