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