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