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