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