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