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