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 General Public License as published by
  12   the Free Software Foundation; either version 2 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   General Public License for more details.
  19
  20   You should have received a copy of the GNU 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                 <refpurpose>Determine state of a specific session</refpurpose>
  51         </refnamediv>
  52
  53         <refsynopsisdiv>
  54                 <funcsynopsis>
  55                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  56
  57                         <funcprototype>
  58                                 <funcdef>int <function>sd_session_is_active</function></funcdef>
  59                                 <paramdef>const char* <parameter>session</parameter></paramdef>
  60                         </funcprototype>
  61
  62                         <funcprototype>
  63                                 <funcdef>int <function>sd_session_get_uid</function></funcdef>
  64                                 <paramdef>const char* <parameter>session</parameter></paramdef>
  65                                 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
  66                         </funcprototype>
  67
  68                         <funcprototype>
  69                                 <funcdef>int <function>sd_session_get_seat</function></funcdef>
  70                                 <paramdef>const char* <parameter>session</parameter></paramdef>
  71                                 <paramdef>char** <parameter>seat</parameter></paramdef>
  72                         </funcprototype>
  73
  74                         <funcprototype>
  75                                 <funcdef>int <function>sd_session_get_service</function></funcdef>
  76                                 <paramdef>const char* <parameter>session</parameter></paramdef>
  77                                 <paramdef>char** <parameter>service</parameter></paramdef>
  78                         </funcprototype>
  79                 </funcsynopsis>
  80         </refsynopsisdiv>
  81
  82         <refsect1>
  83                 <title>Description</title>
  84
  85                 <para><function>sd_session_is_active()</function> may
  86                 be used to determine whether the session identified by
  87                 the specified session identifier is currently active
  88                 (i.e. currently in the foreground and available for
  89                 user input) or not.</para>
  90
  91                 <para><function>sd_session_get_uid()</function> may be
  92                 used to determine the user identifier of the Unix user the session
  93                 identified by the specified session identifier belongs
  94                 to.</para>
  95
  96                 <para><function>sd_session_get_seat()</function> may
  97                 be used to determine the seat identifier of the seat
  98                 the session identified by the specified session
  99                 identifier belongs to. Note that not all sessions are
 100                 attached to a seat, this call will fail for them. The
 101                 returned string needs to be freed with the libc
 102                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 103                 call after use.</para>
 104
 105                 <para><function>sd_session_get_service()</function>
 106                 may be used to determine the name of the service (as
 107                 passed during PAM session setup) that registered the
 108                 session identified by the specified session
 109                 identifier. The returned string needs to be freed with
 110                 the libc
 111                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 112                 call after use.</para>
 113         </refsect1>
 114
 115         <refsect1>
 116                 <title>Return Value</title>
 117
 118                 <para>If the test succeeds
 119                 <function>sd_session_is_active()</function> returns a
 120                 positive integer, if it fails 0.  On success
 121                 <function>sd_session_get_uid()</function>,
 122                 <function>sd_session_get_service()</function> and
 123                 <function>sd_session_get_seat()</function> return 0 or
 124                 a positive integer. On failure, these calls return a
 125                 negative errno-style error code.</para>
 126         </refsect1>
 127
 128         <refsect1>
 129                 <title>Notes</title>
 130
 131                 <para>The <function>sd_session_is_active()</function>,
 132                 <function>sd_session_get_uid()</function>,
 133                 <function>sd_session_get_service()</function> and
 134                 <function>sd_session_get_seat()</function> interfaces
 135                 are available as shared library, which can be compiled
 136                 and linked to with the
 137                 <literal>libsystemd-login</literal>
 138                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 139                 file.</para>
 140         </refsect1>
 141
 142         <refsect1>
 143                 <title>See Also</title>
 144
 145                 <para>
 146                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 147                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 148                         <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 149                 </para>
 150         </refsect1>
 151
 152 </refentry>