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_display</refname>
  55                 <refname>sd_session_get_tty</refname>
  56                 <refname>sd_session_get_vt</refname>
  57                 <refname>sd_session_get_remote_host</refname>
  58                 <refname>sd_session_get_remote_user</refname>
  59                 <refpurpose>Determine state of a specific session</refpurpose>
  60         </refnamediv>
  61
  62         <refsynopsisdiv>
  63                 <funcsynopsis>
  64                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  65
  66                         <funcprototype>
  67                                 <funcdef>int <function>sd_session_is_active</function></funcdef>
  68                                 <paramdef>const char *<parameter>session</parameter></paramdef>
  69                         </funcprototype>
  70
  71                         <funcprototype>
  72                                 <funcdef>int <function>sd_session_is_remote</function></funcdef>
  73                                 <paramdef>const char *<parameter>session</parameter></paramdef>
  74                         </funcprototype>
  75
  76                         <funcprototype>
  77                                 <funcdef>int <function>sd_session_get_state</function></funcdef>
  78                                 <paramdef>const char *<parameter>session</parameter></paramdef>
  79                                 <paramdef>char **<parameter>state</parameter></paramdef>
  80                         </funcprototype>
  81
  82                         <funcprototype>
  83                                 <funcdef>int <function>sd_session_get_uid</function></funcdef>
  84                                 <paramdef>const char *<parameter>session</parameter></paramdef>
  85                                 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  86                         </funcprototype>
  87
  88                         <funcprototype>
  89                                 <funcdef>int <function>sd_session_get_seat</function></funcdef>
  90                                 <paramdef>const char *<parameter>session</parameter></paramdef>
  91                                 <paramdef>char **<parameter>seat</parameter></paramdef>
  92                         </funcprototype>
  93
  94                         <funcprototype>
  95                                 <funcdef>int <function>sd_session_get_service</function></funcdef>
  96                                 <paramdef>const char *<parameter>session</parameter></paramdef>
  97                                 <paramdef>char **<parameter>service</parameter></paramdef>
  98                         </funcprototype>
  99
 100                         <funcprototype>
 101                                 <funcdef>int <function>sd_session_get_type</function></funcdef>
 102                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 103                                 <paramdef>char **<parameter>type</parameter></paramdef>
 104                         </funcprototype>
 105
 106                         <funcprototype>
 107                                 <funcdef>int <function>sd_session_get_class</function></funcdef>
 108                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 109                                 <paramdef>char **<parameter>class</parameter></paramdef>
 110                         </funcprototype>
 111
 112                         <funcprototype>
 113                                 <funcdef>int <function>sd_session_get_display</function></funcdef>
 114                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 115                                 <paramdef>char **<parameter>display</parameter></paramdef>
 116                         </funcprototype>
 117
 118                         <funcprototype>
 119                                 <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
 120                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 121                                 <paramdef>char **<parameter>remote_host</parameter></paramdef>
 122                         </funcprototype>
 123
 124                         <funcprototype>
 125                                 <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
 126                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 127                                 <paramdef>char **<parameter>remote_user</parameter></paramdef>
 128                         </funcprototype>
 129
 130                         <funcprototype>
 131                                 <funcdef>int <function>sd_session_get_tty</function></funcdef>
 132                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 133                                 <paramdef>char **<parameter>tty</parameter></paramdef>
 134                         </funcprototype>
 135
 136                         <funcprototype>
 137                                 <funcdef>int <function>sd_session_get_vt</function></funcdef>
 138                                 <paramdef>const char *<parameter>session</parameter></paramdef>
 139                                 <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
 140                         </funcprototype>
 141                 </funcsynopsis>
 142         </refsynopsisdiv>
 143
 144         <refsect1>
 145                 <title>Description</title>
 146
 147                 <para><function>sd_session_is_active()</function> may
 148                 be used to determine whether the session identified by
 149                 the specified session identifier is currently active
 150                 (i.e. currently in the foreground and available for
 151                 user input) or not.</para>
 152
 153                 <para><function>sd_session_is_remote()</function> may
 154                 be used to determine whether the session identified by
 155                 the specified session identifier is a remote session
 156                 (i.e. its remote host is known) or not.</para>
 157
 158                 <para><function>sd_session_get_state()</function> may
 159                 be used to determine the state of the session
 160                 identified by the specified session identifier. The
 161                 following states are currently known:
 162                 <literal>online</literal> (session logged in, but
 163                 session not active, i.e. not in the foreground),
 164                 <literal>active</literal> (session logged in and
 165                 active, i.e. in the foreground),
 166                 <literal>closing</literal> (session nominally logged
 167                 out, but some processes belonging to it are still
 168                 around). In the future additional states might be
 169                 defined, client code should be written to be robust in
 170                 regards to additional state strings being
 171                 returned. This function is a more generic version of
 172                 <function>sd_session_is_active()</function>. The returned
 173                 string needs to be freed with the libc
 174                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 175                 call after use.</para>
 176
 177                 <para><function>sd_session_get_uid()</function> may be
 178                 used to determine the user identifier of the Unix user the session
 179                 identified by the specified session identifier belongs
 180                 to.</para>
 181
 182                 <para><function>sd_session_get_seat()</function> may
 183                 be used to determine the seat identifier of the seat
 184                 the session identified by the specified session
 185                 identifier belongs to. Note that not all sessions are
 186                 attached to a seat, this call will fail for them. The
 187                 returned string needs to be freed with the libc
 188                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189                 call after use.</para>
 190
 191                 <para><function>sd_session_get_service()</function>
 192                 may be used to determine the name of the service (as
 193                 passed during PAM session setup) that registered the
 194                 session identified by the specified session
 195                 identifier. The returned string needs to be freed with
 196                 the libc
 197                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 198                 call after use.</para>
 199
 200                 <para><function>sd_session_get_type()</function> may
 201                 be used to determine the type of the session
 202                 identified by the specified session identifier. The
 203                 returned string is one of <literal>x11</literal>,
 204                 <literal>wayland</literal>, <literal>tty</literal>,
 205                 <literal>mir</literal> or <literal>unspecified</literal> and
 206                 needs to be freed with the libc
 207                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 208                 call after use.</para>
 209
 210                 <para><function>sd_session_get_class()</function> may
 211                 be used to determine the class of the session
 212                 identified by the specified session identifier. The
 213                 returned string is one of <literal>user</literal>,
 214                 <literal>greeter</literal>,
 215                 <literal>lock-screen</literal>, or
 216                 <literal>background</literal> and needs to be freed
 217                 with the libc
 218                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 219                 call after use.</para>
 220
 221                 <para><function>sd_session_get_display()</function>
 222                 may be used to determine the X11 display of the
 223                 session identified by the specified session
 224                 identifier. The returned string needs to be
 225                 freed with the libc
 226                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 227                 call after use.</para>
 228
 229                 <para><function>sd_session_get_remote_host()</function>
 230                 may be used to determine the remote hostname of the
 231                 session identified by the specified session
 232                 identifier. The returned string needs to be
 233                 freed with the libc
 234                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 235                 call after use.</para>
 236
 237                 <para><function>sd_session_get_remote_user()</function>
 238                 may be used to determine the remote username of the
 239                 session identified by the specified session
 240                 identifier. The returned string needs to be
 241                 freed with the libc
 242                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 243                 call after use. Note that this value is rarely known
 244                 to the system, and even then should not be relied on.</para>
 245
 246                 <para><function>sd_session_get_tty()</function>
 247                 may be used to determine the TTY device of the
 248                 session identified by the specified session
 249                 identifier. The returned string needs to be
 250                 freed with the libc
 251                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 252                 call after use.</para>
 253
 254                 <para><function>sd_session_get_vt()</function>
 255                 may be used to determine the VT number of the
 256                 session identified by the specified session
 257                 identifier. This function will return an error if
 258                 the seat does not support VTs.</para>
 259
 260                 <para>If the <varname>session</varname> parameter of
 261                 any of these functions is passed as
 262                 <constant>NULL</constant>, the operation is executed
 263                 for the session the calling process is a member of, if
 264                 there is any.</para>
 265         </refsect1>
 266
 267         <refsect1>
 268                 <title>Return Value</title>
 269
 270                 <para>If the test succeeds,
 271                 <function>sd_session_is_active()</function> and
 272                 <function>sd_session_is_remote()</function> return a
 273                 positive integer; if it fails, 0.  On success,
 274                 <function>sd_session_get_state()</function>,
 275                 <function>sd_session_get_uid()</function>,
 276                 <function>sd_session_get_seat()</function>,
 277                 <function>sd_session_get_service()</function>,
 278                 <function>sd_session_get_type()</function>,
 279                 <function>sd_session_get_class()</function>,
 280                 <function>sd_session_get_display()</function>,
 281                 <function>sd_session_get_remote_user()</function>,
 282                 <function>sd_session_get_remote_host()</function> and
 283                 <function>sd_session_get_tty()</function> return 0 or
 284                 a positive integer. On failure, these calls return a
 285                 negative errno-style error code.</para>
 286         </refsect1>
 287
 288         <refsect1>
 289                 <title>Notes</title>
 290
 291                 <para>The <function>sd_session_is_active()</function>,
 292                 <function>sd_session_get_state()</function>,
 293                 <function>sd_session_get_uid()</function>,
 294                 <function>sd_session_get_seat()</function>,
 295                 <function>sd_session_get_service()</function>,
 296                 <function>sd_session_get_type()</function>,
 297                 <function>sd_session_get_class()</function>,
 298                 <function>sd_session_get_display()</function>,
 299                 <function>sd_session_get_remote_host()</function>,
 300                 <function>sd_session_get_remote_user()</function> and
 301                 <function>sd_session_get_tty()</function>
 302                 interfaces are available as a shared library, which can
 303                 be compiled and linked to with the
 304                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 305                 file.</para>
 306         </refsect1>
 307
 308         <refsect1>
 309                 <title>See Also</title>
 310
 311                 <para>
 312                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 313                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 314                         <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 315                 </para>
 316         </refsect1>
 317
 318 </refentry>