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