chiark / gitweb /
76f6f9544ce3c8daa9f232f4739ec28986daae53
[elogind.git] / 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> or
183                 <literal>lock-screen</literal> and needs to be freed
184                 with the libc
185                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
186                 call after use.</para>
187
188                 <para><function>sd_session_get_display()</function>
189                 may be used to determine the X11 display of the
190                 session identified by the specified session
191                 identifier. The returned string needs to be
192                 freed with the libc
193                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
194                 call after use.</para>
195
196                 <para><function>sd_session_get_tty()</function>
197                 may be used to determine the TTY device 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>If the <literal>session</literal> parameter of
205                 any of these functions is passed as NULL the operation
206                 is executed for the session the calling process is a
207                 member of, if there is any.</para>
208         </refsect1>
209
210         <refsect1>
211                 <title>Return Value</title>
212
213                 <para>If the test succeeds
214                 <function>sd_session_is_active()</function> returns a
215                 positive integer, if it fails 0.  On success
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>,
222                 <function>sd_session_get_display()</function> and
223                 <function>sd_session_get_tty()</function> return 0 or
224                 a positive integer. On failure, these calls return a
225                 negative errno-style error code.</para>
226         </refsect1>
227
228         <refsect1>
229                 <title>Notes</title>
230
231                 <para>The <function>sd_session_is_active()</function>,
232                 <function>sd_session_get_state()</function>,
233                 <function>sd_session_get_uid()</function>,
234                 <function>sd_session_get_seat()</function>,
235                 <function>sd_session_get_service()</function>,
236                 <function>sd_session_get_type()</function>,
237                 <function>sd_session_get_class()</function>,
238                 <function>sd_session_get_display()</function> and
239                 <function>sd_session_get_tty()</function>
240                 interfaces are available as shared library, which can
241                 be compiled and linked to with the
242                 <literal>libsystemd-login</literal>
243                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
244                 file.</para>
245         </refsect1>
246
247         <refsect1>
248                 <title>See Also</title>
249
250                 <para>
251                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
252                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
253                         <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
254                 </para>
255         </refsect1>
256
257 </refentry>