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   This file is part of systemd.
   9
  10   Copyright 2010 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_session_is_active" conditional='HAVE_PAM'>
  27
  28   <refentryinfo>
  29     <title>sd_session_is_active</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_session_is_active</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_session_is_active</refname>
  49     <refname>sd_session_is_remote</refname>
  50     <refname>sd_session_get_state</refname>
  51     <refname>sd_session_get_uid</refname>
  52     <refname>sd_session_get_seat</refname>
  53     <refname>sd_session_get_service</refname>
  54     <refname>sd_session_get_type</refname>
  55     <refname>sd_session_get_class</refname>
  56     <refname>sd_session_get_desktop</refname>
  57     <refname>sd_session_get_display</refname>
  58     <refname>sd_session_get_tty</refname>
  59     <refname>sd_session_get_vt</refname>
  60     <refname>sd_session_get_remote_host</refname>
  61     <refname>sd_session_get_remote_user</refname>
  62     <refpurpose>Determine state of a specific session</refpurpose>
  63   </refnamediv>
  64
  65   <refsynopsisdiv>
  66     <funcsynopsis>
  67       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  68
  69       <funcprototype>
  70         <funcdef>int <function>sd_session_is_active</function></funcdef>
  71         <paramdef>const char *<parameter>session</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int <function>sd_session_is_remote</function></funcdef>
  76         <paramdef>const char *<parameter>session</parameter></paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>int <function>sd_session_get_state</function></funcdef>
  81         <paramdef>const char *<parameter>session</parameter></paramdef>
  82         <paramdef>char **<parameter>state</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int <function>sd_session_get_uid</function></funcdef>
  87         <paramdef>const char *<parameter>session</parameter></paramdef>
  88         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  89       </funcprototype>
  90
  91       <funcprototype>
  92         <funcdef>int <function>sd_session_get_seat</function></funcdef>
  93         <paramdef>const char *<parameter>session</parameter></paramdef>
  94         <paramdef>char **<parameter>seat</parameter></paramdef>
  95       </funcprototype>
  96
  97       <funcprototype>
  98         <funcdef>int <function>sd_session_get_service</function></funcdef>
  99         <paramdef>const char *<parameter>session</parameter></paramdef>
 100         <paramdef>char **<parameter>service</parameter></paramdef>
 101       </funcprototype>
 102
 103       <funcprototype>
 104         <funcdef>int <function>sd_session_get_type</function></funcdef>
 105         <paramdef>const char *<parameter>session</parameter></paramdef>
 106         <paramdef>char **<parameter>type</parameter></paramdef>
 107       </funcprototype>
 108
 109       <funcprototype>
 110         <funcdef>int <function>sd_session_get_class</function></funcdef>
 111         <paramdef>const char *<parameter>session</parameter></paramdef>
 112         <paramdef>char **<parameter>class</parameter></paramdef>
 113       </funcprototype>
 114
 115       <funcprototype>
 116         <funcdef>int <function>sd_session_get_desktop</function></funcdef>
 117         <paramdef>const char *<parameter>session</parameter></paramdef>
 118         <paramdef>char **<parameter>desktop</parameter></paramdef>
 119       </funcprototype>
 120
 121       <funcprototype>
 122         <funcdef>int <function>sd_session_get_display</function></funcdef>
 123         <paramdef>const char *<parameter>session</parameter></paramdef>
 124         <paramdef>char **<parameter>display</parameter></paramdef>
 125       </funcprototype>
 126
 127       <funcprototype>
 128         <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
 129         <paramdef>const char *<parameter>session</parameter></paramdef>
 130         <paramdef>char **<parameter>remote_host</parameter></paramdef>
 131       </funcprototype>
 132
 133       <funcprototype>
 134         <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
 135         <paramdef>const char *<parameter>session</parameter></paramdef>
 136         <paramdef>char **<parameter>remote_user</parameter></paramdef>
 137       </funcprototype>
 138
 139       <funcprototype>
 140         <funcdef>int <function>sd_session_get_tty</function></funcdef>
 141         <paramdef>const char *<parameter>session</parameter></paramdef>
 142         <paramdef>char **<parameter>tty</parameter></paramdef>
 143       </funcprototype>
 144
 145       <funcprototype>
 146         <funcdef>int <function>sd_session_get_vt</function></funcdef>
 147         <paramdef>const char *<parameter>session</parameter></paramdef>
 148         <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
 149       </funcprototype>
 150     </funcsynopsis>
 151   </refsynopsisdiv>
 152
 153   <refsect1>
 154     <title>Description</title>
 155
 156     <para><function>sd_session_is_active()</function> may be used to
 157     determine whether the session identified by the specified session
 158     identifier is currently active (i.e. currently in the foreground
 159     and available for user input) or not.</para>
 160
 161     <para><function>sd_session_is_remote()</function> may be used to
 162     determine whether the session identified by the specified session
 163     identifier is a remote session (i.e. its remote host is known) or
 164     not.</para>
 165
 166     <para><function>sd_session_get_state()</function> may be used to
 167     determine the state of the session identified by the specified
 168     session identifier. The following states are currently known:
 169     <literal>online</literal> (session logged in, but session not
 170     active, i.e. not in the foreground), <literal>active</literal>
 171     (session logged in and active, i.e. in the foreground),
 172     <literal>closing</literal> (session nominally logged out, but some
 173     processes belonging to it are still around). In the future
 174     additional states might be defined, client code should be written
 175     to be robust in regards to additional state strings being
 176     returned. This function is a more generic version of
 177     <function>sd_session_is_active()</function>. The returned string
 178     needs to be freed with the libc
 179     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 180     call after use.</para>
 181
 182     <para><function>sd_session_get_uid()</function> may be used to
 183     determine the user identifier of the Unix user the session
 184     identified by the specified session identifier belongs to.</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_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>Errors</title>
 297
 298     <para>Returned errors may indicate the following problems:</para>
 299
 300     <variablelist>
 301
 302       <varlistentry>
 303         <term><constant>-ENXIO</constant></term>
 304
 305         <listitem><para>The specified session does not exist.</para>
 306         </listitem>
 307       </varlistentry>
 308
 309       <varlistentry>
 310         <term><constant>-ENODATA</constant></term>
 311
 312         <listitem><para>The given field is not specified for the described
 313         session.</para>
 314         </listitem>
 315       </varlistentry>
 316
 317       <varlistentry>
 318         <term><constant>-EINVAL</constant></term>
 319
 320         <listitem><para>An input parameter was invalid (out of range,
 321         or NULL, where that is not accepted).</para></listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term><constant>-ENOMEM</constant></term>
 326
 327         <listitem><para>Memory allocation failed.</para></listitem>
 328       </varlistentry>
 329     </variablelist>
 330   </refsect1>
 331
 332   <refsect1>
 333     <title>Notes</title>
 334
 335     <para>The <function>sd_session_is_active()</function>,
 336     <function>sd_session_get_state()</function>,
 337     <function>sd_session_get_uid()</function>,
 338     <function>sd_session_get_seat()</function>,
 339     <function>sd_session_get_service()</function>,
 340     <function>sd_session_get_type()</function>,
 341     <function>sd_session_get_class()</function>,
 342     <function>sd_session_get_display()</function>,
 343     <function>sd_session_get_remote_host()</function>,
 344     <function>sd_session_get_remote_user()</function> and
 345     <function>sd_session_get_tty()</function>
 346     interfaces are available as a shared library, which can
 347     be compiled and linked to with the
 348     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 349     file.</para>
 350   </refsect1>
 351
 352   <refsect1>
 353     <title>See Also</title>
 354
 355     <para>
 356       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 357       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 358       <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 359     </para>
 360   </refsect1>
 361
 362 </refentry>