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
 155                 be used to determine whether the session identified by
 156                 the specified session identifier is currently active
 157                 (i.e. currently in the foreground and available for
 158                 user input) or not.</para>
 159
 160                 <para><function>sd_session_is_remote()</function> may
 161                 be used to determine whether the session identified by
 162                 the specified session identifier is a remote session
 163                 (i.e. its remote host is known) or not.</para>
 164
 165                 <para><function>sd_session_get_state()</function> may
 166                 be used to determine the state of the session
 167                 identified by the specified session identifier. The
 168                 following states are currently known:
 169                 <literal>online</literal> (session logged in, but
 170                 session not active, i.e. not in the foreground),
 171                 <literal>active</literal> (session logged in and
 172                 active, i.e. in the foreground),
 173                 <literal>closing</literal> (session nominally logged
 174                 out, but some processes belonging to it are still
 175                 around). In the future additional states might be
 176                 defined, client code should be written to be robust in
 177                 regards to additional state strings being
 178                 returned. This function is a more generic version of
 179                 <function>sd_session_is_active()</function>. The returned
 180                 string needs to be freed with the libc
 181                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 182                 call after use.</para>
 183
 184                 <para><function>sd_session_get_uid()</function> may be
 185                 used to determine the user identifier of the Unix user the session
 186                 identified by the specified session identifier belongs
 187                 to.</para>
 188
 189                 <para><function>sd_session_get_seat()</function> may
 190                 be used to determine the seat identifier of the seat
 191                 the session identified by the specified session
 192                 identifier belongs to. Note that not all sessions are
 193                 attached to a seat, this call will fail for them. The
 194                 returned string needs to be freed with the libc
 195                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 196                 call after use.</para>
 197
 198                 <para><function>sd_session_get_service()</function>
 199                 may be used to determine the name of the service (as
 200                 passed during PAM session setup) that registered the
 201                 session identified by the specified session
 202                 identifier. The returned string needs to be freed with
 203                 the libc
 204                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 205                 call after use.</para>
 206
 207                 <para><function>sd_session_get_type()</function> may
 208                 be used to determine the type of the session
 209                 identified by the specified session identifier. The
 210                 returned string is one of <literal>x11</literal>,
 211                 <literal>wayland</literal>, <literal>tty</literal>,
 212                 <literal>mir</literal> or <literal>unspecified</literal> and
 213                 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
 218                 be used to determine the class of the session
 219                 identified by the specified session identifier. The
 220                 returned string is one of <literal>user</literal>,
 221                 <literal>greeter</literal>,
 222                 <literal>lock-screen</literal>, or
 223                 <literal>background</literal> and needs to be freed
 224                 with the libc
 225                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 226                 call after use.</para>
 227
 228                 <para><function>sd_session_get_desktop()</function> may
 229                 be used to determine the brand of the desktop running on
 230                 the session identified by the specified session identifier.
 231                 This field can be set freely by desktop environments and
 232                 does not follow any special formatting. However, desktops
 233                 are strongly recommended to use the same identifiers and
 234                 capitalization as for
 235                 <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by
 236                 the <ulink
 237                 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
 238                 Entry
 239                 Specification</ulink>. The returned string needs to be
 240                 freed with the libc
 241                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 242                 call after use.</para>
 243
 244                 <para><function>sd_session_get_display()</function>
 245                 may be used to determine the X11 display of the
 246                 session identified by the specified session
 247                 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.</para>
 251
 252                 <para><function>sd_session_get_remote_host()</function>
 253                 may be used to determine the remote hostname of the
 254                 session identified by the specified session
 255                 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_remote_user()</function>
 261                 may be used to determine the remote username of the
 262                 session identified by the specified session
 263                 identifier. The returned string needs to be
 264                 freed with the libc
 265                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 266                 call after use. Note that this value is rarely known
 267                 to the system, and even then should not be relied on.</para>
 268
 269                 <para><function>sd_session_get_tty()</function>
 270                 may be used to determine the TTY device of the
 271                 session identified by the specified session
 272                 identifier. The returned string needs to be
 273                 freed with the libc
 274                 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 275                 call after use.</para>
 276
 277                 <para><function>sd_session_get_vt()</function>
 278                 may be used to determine the VT number of the
 279                 session identified by the specified session
 280                 identifier. This function will return an error if
 281                 the seat does not support VTs.</para>
 282
 283                 <para>If the <varname>session</varname> parameter of
 284                 any of these functions is passed as
 285                 <constant>NULL</constant>, the operation is executed
 286                 for the session the calling process is a member of, if
 287                 there is any.</para>
 288         </refsect1>
 289
 290         <refsect1>
 291                 <title>Return Value</title>
 292
 293                 <para>If the test succeeds,
 294                 <function>sd_session_is_active()</function> and
 295                 <function>sd_session_is_remote()</function> return a
 296                 positive integer; if it fails, 0.  On success,
 297                 <function>sd_session_get_state()</function>,
 298                 <function>sd_session_get_uid()</function>,
 299                 <function>sd_session_get_seat()</function>,
 300                 <function>sd_session_get_service()</function>,
 301                 <function>sd_session_get_type()</function>,
 302                 <function>sd_session_get_class()</function>,
 303                 <function>sd_session_get_display()</function>,
 304                 <function>sd_session_get_remote_user()</function>,
 305                 <function>sd_session_get_remote_host()</function> and
 306                 <function>sd_session_get_tty()</function> return 0 or
 307                 a positive integer. On failure, these calls return a
 308                 negative errno-style error code.</para>
 309         </refsect1>
 310
 311         <refsect1>
 312                 <title>Notes</title>
 313
 314                 <para>The <function>sd_session_is_active()</function>,
 315                 <function>sd_session_get_state()</function>,
 316                 <function>sd_session_get_uid()</function>,
 317                 <function>sd_session_get_seat()</function>,
 318                 <function>sd_session_get_service()</function>,
 319                 <function>sd_session_get_type()</function>,
 320                 <function>sd_session_get_class()</function>,
 321                 <function>sd_session_get_display()</function>,
 322                 <function>sd_session_get_remote_host()</function>,
 323                 <function>sd_session_get_remote_user()</function> and
 324                 <function>sd_session_get_tty()</function>
 325                 interfaces are available as a shared library, which can
 326                 be compiled and linked to with the
 327                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 328                 file.</para>
 329         </refsect1>
 330
 331         <refsect1>
 332                 <title>See Also</title>
 333
 334                 <para>
 335                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 336                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 337                         <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 338                 </para>
 339         </refsect1>
 340
 341 </refentry>