man/sd_session_is_active.xml

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