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 systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd 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   systemd 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 systemd; 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>systemd</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;systemd/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 (returning
 188     <constant>-ENODATA</constant>) for them. The returned string needs
 189     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_service()</function> may be used to
 194     determine the name of the service (as passed during PAM session
 195     setup) that registered the session identified by the specified
 196     session identifier. The returned string needs to be freed with the
 197     libc
 198     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 199     call after use.</para>
 200
 201     <para><function>sd_session_get_type()</function> may be used to
 202     determine the type of the session identified by the specified
 203     session identifier. The returned string is one of
 204     <literal>x11</literal>, <literal>wayland</literal>,
 205     <literal>tty</literal>, <literal>mir</literal> or
 206     <literal>unspecified</literal> and needs to be freed with the libc
 207     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 208     call after use.</para>
 209
 210     <para><function>sd_session_get_class()</function> may be used to
 211     determine the class of the session identified by the specified
 212     session identifier. The returned string is one of
 213     <literal>user</literal>, <literal>greeter</literal>,
 214     <literal>lock-screen</literal>, or <literal>background</literal>
 215     and needs to be freed with the libc
 216     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 217     call after use.</para>
 218
 219     <para><function>sd_session_get_desktop()</function> may be used to
 220     determine the brand of the desktop running on the session
 221     identified by the specified session identifier. This field can be
 222     set freely by desktop environments and does not follow any special
 223     formatting. However, desktops are strongly recommended to use the
 224     same identifiers and capitalization as for
 225     <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
 226     url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
 227     Entry Specification</ulink>. The returned string needs to be freed
 228     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_display()</function> may be used to
 233     determine the X11 display of the session identified by the
 234     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.</para>
 238
 239     <para><function>sd_session_get_remote_host()</function> may be
 240     used to determine the remote hostname of the session identified by
 241     the 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_remote_user()</function> may be
 247     used to determine the remote username of the session identified by
 248     the specified session identifier. The returned string needs to be
 249     freed with the libc
 250     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 251     call after use. Note that this value is rarely known to the
 252     system, and even then should not be relied on.</para>
 253
 254     <para><function>sd_session_get_tty()</function> may be used to
 255     determine the TTY device of the session identified by the
 256     specified session identifier. The returned string needs to be
 257     freed with the libc
 258     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 259     call after use.</para>
 260
 261     <para><function>sd_session_get_vt()</function> may be used to
 262     determine the VT number of the session identified by the specified
 263     session identifier. This function will return an error if the seat
 264     does not support VTs.</para>
 265
 266     <para>If the <varname>session</varname> parameter of any of these
 267     functions is passed as <constant>NULL</constant>, the operation is
 268     executed for the session the calling process is a member of, if
 269     there is any.</para>
 270   </refsect1>
 271
 272   <refsect1>
 273     <title>Return Value</title>
 274
 275     <para>If the test succeeds,
 276     <function>sd_session_is_active()</function> and
 277     <function>sd_session_is_remote()</function> return a
 278     positive integer; if it fails, 0.  On success,
 279     <function>sd_session_get_state()</function>,
 280     <function>sd_session_get_uid()</function>,
 281     <function>sd_session_get_seat()</function>,
 282     <function>sd_session_get_service()</function>,
 283     <function>sd_session_get_type()</function>,
 284     <function>sd_session_get_class()</function>,
 285     <function>sd_session_get_display()</function>,
 286     <function>sd_session_get_remote_user()</function>,
 287     <function>sd_session_get_remote_host()</function> and
 288     <function>sd_session_get_tty()</function> return 0 or
 289     a positive integer. On failure, these calls return a
 290     negative errno-style error code.</para>
 291   </refsect1>
 292
 293   <refsect1>
 294     <title>Errors</title>
 295
 296     <para>Returned errors may indicate the following problems:</para>
 297
 298     <variablelist>
 299
 300       <varlistentry>
 301         <term><constant>-ENXIO</constant></term>
 302
 303         <listitem><para>The specified session does not exist.</para>
 304         </listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term><constant>-ENODATA</constant></term>
 309
 310         <listitem><para>The given field is not specified for the described
 311         session.</para>
 312         </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term><constant>-EINVAL</constant></term>
 317
 318         <listitem><para>An input parameter was invalid (out of range,
 319         or NULL, where that is not accepted).</para></listitem>
 320       </varlistentry>
 321
 322       <varlistentry>
 323         <term><constant>-ENOMEM</constant></term>
 324
 325         <listitem><para>Memory allocation failed.</para></listitem>
 326       </varlistentry>
 327     </variablelist>
 328   </refsect1>
 329
 330   <refsect1>
 331     <title>Notes</title>
 332
 333     <para>The <function>sd_session_is_active()</function>,
 334     <function>sd_session_get_state()</function>,
 335     <function>sd_session_get_uid()</function>,
 336     <function>sd_session_get_seat()</function>,
 337     <function>sd_session_get_service()</function>,
 338     <function>sd_session_get_type()</function>,
 339     <function>sd_session_get_class()</function>,
 340     <function>sd_session_get_display()</function>,
 341     <function>sd_session_get_remote_host()</function>,
 342     <function>sd_session_get_remote_user()</function> and
 343     <function>sd_session_get_tty()</function>
 344     interfaces are available as a shared library, which can
 345     be compiled and linked to with the
 346     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 347     file.</para>
 348   </refsect1>
 349
 350   <refsect1>
 351     <title>See Also</title>
 352
 353     <para>
 354       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 355       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 356       <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 357     </para>
 358   </refsect1>
 359
 360 </refentry>