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