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