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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   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_username</refname>
  25     <refname>sd_session_get_seat</refname>
  26     <refname>sd_session_get_start_time</refname>
  27     <refname>sd_session_get_service</refname>
  28     <refname>sd_session_get_type</refname>
  29     <refname>sd_session_get_class</refname>
  30     <refname>sd_session_get_desktop</refname>
  31     <refname>sd_session_get_display</refname>
  32     <refname>sd_session_get_tty</refname>
  33     <refname>sd_session_get_vt</refname>
  34     <refname>sd_session_get_remote_host</refname>
  35     <refname>sd_session_get_remote_user</refname>
  36     <refname>sd_session_get_leader</refname>
  37     <refpurpose>Determine state of a specific session</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_session_is_active</function></funcdef>
  46         <paramdef>const char *<parameter>session</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_session_is_remote</function></funcdef>
  51         <paramdef>const char *<parameter>session</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>int <function>sd_session_get_state</function></funcdef>
  56         <paramdef>const char *<parameter>session</parameter></paramdef>
  57         <paramdef>char **<parameter>state</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_session_get_uid</function></funcdef>
  62         <paramdef>const char *<parameter>session</parameter></paramdef>
  63         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_session_get_username</function></funcdef>
  68         <paramdef>const char *<parameter>session</parameter></paramdef>
  69         <paramdef>char **<parameter>username</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_session_get_seat</function></funcdef>
  74         <paramdef>const char *<parameter>session</parameter></paramdef>
  75         <paramdef>char **<parameter>seat</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_session_get_start_time</function></funcdef>
  80         <paramdef>const char *<parameter>session</parameter></paramdef>
  81         <paramdef>uint64_t *<parameter>usec</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_leader</function></funcdef>
 116         <paramdef>const char *<parameter>session</parameter></paramdef>
 117         <paramdef>pid_t *<parameter>leader</parameter></paramdef>
 118       </funcprototype>
 119
 120       <funcprototype>
 121         <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
 122         <paramdef>const char *<parameter>session</parameter></paramdef>
 123         <paramdef>char **<parameter>remote_host</parameter></paramdef>
 124       </funcprototype>
 125
 126       <funcprototype>
 127         <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
 128         <paramdef>const char *<parameter>session</parameter></paramdef>
 129         <paramdef>char **<parameter>remote_user</parameter></paramdef>
 130       </funcprototype>
 131
 132       <funcprototype>
 133         <funcdef>int <function>sd_session_get_tty</function></funcdef>
 134         <paramdef>const char *<parameter>session</parameter></paramdef>
 135         <paramdef>char **<parameter>tty</parameter></paramdef>
 136       </funcprototype>
 137
 138       <funcprototype>
 139         <funcdef>int <function>sd_session_get_vt</function></funcdef>
 140         <paramdef>const char *<parameter>session</parameter></paramdef>
 141         <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
 142       </funcprototype>
 143     </funcsynopsis>
 144   </refsynopsisdiv>
 145
 146   <refsect1>
 147     <title>Description</title>
 148
 149     <para><function>sd_session_is_active()</function> may be used to
 150     determine whether the session identified by the specified session
 151     identifier is currently active (i.e. currently in the foreground
 152     and available for user input) or not.</para>
 153
 154     <para><function>sd_session_is_remote()</function> may be used to
 155     determine whether the session identified by the specified session
 156     identifier is a remote session (i.e. its remote host is known) or
 157     not.</para>
 158
 159     <para><function>sd_session_get_state()</function> may be used to
 160     determine the state of the session identified by the specified
 161     session identifier. The following states are currently known:
 162     <literal>online</literal> (session logged in, but session not
 163     active, i.e. not in the foreground), <literal>active</literal>
 164     (session logged in and active, i.e. in the foreground),
 165     <literal>closing</literal> (session nominally logged out, but some
 166     processes belonging to it are still around). In the future
 167     additional states might be defined, client code should be written
 168     to be robust in regards to additional state strings being
 169     returned. This function is a more generic version of
 170     <function>sd_session_is_active()</function>. The returned string
 171     needs to be freed with the 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_uid()</function> may be used to
 176     determine the user identifier of the Unix user the session
 177     identified by the specified session identifier belongs to.</para>
 178
 179     <para><function>sd_session_get_username()</function> may be used to
 180     determine the name of the Unix user the session identified by
 181     the specified session identifier belongs to. The returned string
 182     needs to be freed with the libc
 183     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 184     call after use.</para>
 185
 186     <para><function>sd_session_get_seat()</function> may be used to
 187     determine the seat identifier of the seat the session identified
 188     by the specified session identifier belongs to. Note that not all
 189     sessions are attached to a seat, this call will fail (returning
 190     <constant>-ENODATA</constant>) for them. The returned string needs
 191     to be freed with the libc
 192     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 193     call after use.</para>
 194
 195     <para><function>sd_session_get_start_time()</function> may be used to
 196     determine the start time of the session identified by the specified
 197     session identifier belongs to. The <parameter>usec</parameter>
 198     is in microseconds since the epoch (<constant>CLOCK_REALTIME</constant>).</para>
 199
 200     <para><function>sd_session_get_service()</function> may be used to
 201     determine the name of the service (as passed during PAM session
 202     setup) that registered the session identified by the specified
 203     session identifier. The returned string needs to be freed with the
 204     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_type()</function> may be used to
 209     determine the type of the session identified by the specified
 210     session identifier. The returned string is one of
 211     <literal>x11</literal>, <literal>wayland</literal>,
 212     <literal>tty</literal>, <literal>mir</literal> or
 213     <literal>unspecified</literal> and needs to be freed with the libc
 214     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 215     call after use.</para>
 216
 217     <para><function>sd_session_get_class()</function> may be used to determine the class of the session
 218     identified by the specified session identifier. The returned string is one of <literal>user</literal>,
 219     <literal>user-early</literal>, <literal>user-incomplete</literal>, <literal>greeter</literal>,
 220     <literal>lock-screen</literal>, <literal>background</literal>, <literal>background-light</literal>,
 221     <literal>manager</literal> or <literal>manager-early</literal> and needs to be freed with the libc
 222     <citerefentry
 223     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after
 224     use.</para>
 225
 226     <para><function>sd_session_get_desktop()</function> may be used to
 227     determine the brand of the desktop running on the session
 228     identified by the specified session identifier. This field can be
 229     set freely by desktop environments and does not follow any special
 230     formatting. However, desktops are strongly recommended to use the
 231     same identifiers and capitalization as for
 232     <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
 233     url="https://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
 234     Entry Specification</ulink>. The returned string needs to be freed
 235     with the libc
 236     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 237     call after use.</para>
 238
 239     <para><function>sd_session_get_display()</function> may be used to
 240     determine the X11 display of the session identified by the
 241     specified session identifier. The returned string needs to be
 242     freed with the libc
 243     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 244     call after use.</para>
 245
 246     <para><function>sd_session_get_leader()</function> may be used to
 247     determine the PID of the leader of the session identified by the
 248     specified session identifier.</para>
 249
 250     <para><function>sd_session_get_remote_host()</function> may be
 251     used to determine the remote hostname of the session identified by
 252     the specified session identifier. The returned string needs to be
 253     freed with the libc
 254     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 255     call after use.</para>
 256
 257     <para><function>sd_session_get_remote_user()</function> may be
 258     used to determine the remote username of the session identified by
 259     the specified session identifier. The returned string needs to be
 260     freed with the libc
 261     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 262     call after use. Note that this value is rarely known to the
 263     system, and even then should not be relied on.</para>
 264
 265     <para><function>sd_session_get_tty()</function> may be used to
 266     determine the TTY device of the session identified by the
 267     specified session identifier. The returned string needs to be
 268     freed with the libc
 269     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 270     call after use.</para>
 271
 272     <para><function>sd_session_get_vt()</function> may be used to
 273     determine the VT number of the session identified by the specified
 274     session identifier. This function will return an error if the seat
 275     does not support VTs.</para>
 276
 277     <para>If the <varname>session</varname> parameter of any of these
 278     functions is passed as <constant>NULL</constant>, the operation is
 279     executed for the session the calling process is a member of, if
 280     there is any.</para>
 281   </refsect1>
 282
 283   <refsect1>
 284     <title>Return Value</title>
 285
 286     <para>If the test succeeds,
 287     <function>sd_session_is_active()</function> and
 288     <function>sd_session_is_remote()</function> return a
 289     positive integer; if it fails, 0.  On success,
 290     <function>sd_session_get_state()</function>,
 291     <function>sd_session_get_uid()</function>,
 292     <function>sd_session_get_username()</function>,
 293     <function>sd_session_get_seat()</function>,
 294     <function>sd_session_get_service()</function>,
 295     <function>sd_session_get_type()</function>,
 296     <function>sd_session_get_class()</function>,
 297     <function>sd_session_get_display()</function>,
 298     <function>sd_session_get_leader()</function>,
 299     <function>sd_session_get_remote_user()</function>,
 300     <function>sd_session_get_remote_host()</function> and
 301     <function>sd_session_get_tty()</function> return 0 or
 302     a positive integer. On failure, these calls return a
 303     negative errno-style error code.</para>
 304
 305     <refsect2>
 306       <title>Errors</title>
 307
 308       <para>Returned errors may indicate the following problems:</para>
 309
 310       <variablelist>
 311
 312         <varlistentry>
 313           <term><constant>-ENXIO</constant></term>
 314
 315           <listitem><para>The specified session does not exist.</para>
 316           </listitem>
 317         </varlistentry>
 318
 319         <varlistentry>
 320           <term><constant>-ENODATA</constant></term>
 321
 322           <listitem><para>The given field is not specified for the described session.</para>
 323           </listitem>
 324         </varlistentry>
 325
 326         <varlistentry>
 327           <term><constant>-EINVAL</constant></term>
 328
 329           <listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, where
 330           that is not accepted).</para></listitem>
 331         </varlistentry>
 332
 333         <varlistentry>
 334           <term><constant>-ENOMEM</constant></term>
 335
 336           <listitem><para>Memory allocation failed.</para></listitem>
 337         </varlistentry>
 338       </variablelist>
 339     </refsect2>
 340   </refsect1>
 341
 342   <xi:include href="libsystemd-pkgconfig.xml" />
 343
 344   <refsect1>
 345     <title>History</title>
 346     <para><function>sd_session_get_state()</function> was added in version 186.</para>
 347     <para><function>sd_session_get_tty()</function> was added in version 198.</para>
 348     <para><function>sd_session_get_vt()</function> was added in version 207.</para>
 349     <para><function>sd_session_is_remote()</function>,
 350     <function>sd_session_get_remote_host()</function>, and
 351     <function>sd_session_get_remote_user()</function> were added in version 209.</para>
 352     <para><function>sd_session_get_desktop()</function> was added in version 217.</para>
 353     <para><function>sd_session_get_username()</function>,
 354     <function>sd_session_get_start_time()</function>, and
 355     <function>sd_session_get_leader()</function> were added in version 254.</para>
 356   </refsect1>
 357
 358   <refsect1>
 359     <title>See Also</title>
 360
 361     <para><simplelist type="inline">
 362       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 363       <member><citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 364       <member><citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 365     </simplelist></para>
 366   </refsect1>
 367
 368 </refentry>