chiark / gitweb /
man: ipv4 link-local
[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_is_remote</refname>
48                 <refname>sd_session_get_state</refname>
49                 <refname>sd_session_get_uid</refname>
50                 <refname>sd_session_get_seat</refname>
51                 <refname>sd_session_get_service</refname>
52                 <refname>sd_session_get_type</refname>
53                 <refname>sd_session_get_class</refname>
54                 <refname>sd_session_get_display</refname>
55                 <refname>sd_session_get_tty</refname>
56                 <refname>sd_session_get_vt</refname>
57                 <refname>sd_session_get_remote_host</refname>
58                 <refname>sd_session_get_remote_user</refname>
59                 <refpurpose>Determine state of a specific session</refpurpose>
60         </refnamediv>
61
62         <refsynopsisdiv>
63                 <funcsynopsis>
64                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
65
66                         <funcprototype>
67                                 <funcdef>int <function>sd_session_is_active</function></funcdef>
68                                 <paramdef>const char* <parameter>session</parameter></paramdef>
69                         </funcprototype>
70
71                         <funcprototype>
72                                 <funcdef>int <function>sd_session_is_remote</function></funcdef>
73                                 <paramdef>const char* <parameter>session</parameter></paramdef>
74                         </funcprototype>
75
76                         <funcprototype>
77                                 <funcdef>int <function>sd_session_get_state</function></funcdef>
78                                 <paramdef>const char* <parameter>session</parameter></paramdef>
79                                 <paramdef>char** <parameter>state</parameter></paramdef>
80                         </funcprototype>
81
82                         <funcprototype>
83                                 <funcdef>int <function>sd_session_get_uid</function></funcdef>
84                                 <paramdef>const char* <parameter>session</parameter></paramdef>
85                                 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
86                         </funcprototype>
87
88                         <funcprototype>
89                                 <funcdef>int <function>sd_session_get_seat</function></funcdef>
90                                 <paramdef>const char* <parameter>session</parameter></paramdef>
91                                 <paramdef>char** <parameter>seat</parameter></paramdef>
92                         </funcprototype>
93
94                         <funcprototype>
95                                 <funcdef>int <function>sd_session_get_service</function></funcdef>
96                                 <paramdef>const char* <parameter>session</parameter></paramdef>
97                                 <paramdef>char** <parameter>service</parameter></paramdef>
98                         </funcprototype>
99
100                         <funcprototype>
101                                 <funcdef>int <function>sd_session_get_type</function></funcdef>
102                                 <paramdef>const char* <parameter>session</parameter></paramdef>
103                                 <paramdef>char** <parameter>type</parameter></paramdef>
104                         </funcprototype>
105
106                         <funcprototype>
107                                 <funcdef>int <function>sd_session_get_class</function></funcdef>
108                                 <paramdef>const char* <parameter>session</parameter></paramdef>
109                                 <paramdef>char** <parameter>class</parameter></paramdef>
110                         </funcprototype>
111
112                         <funcprototype>
113                                 <funcdef>int <function>sd_session_get_display</function></funcdef>
114                                 <paramdef>const char* <parameter>session</parameter></paramdef>
115                                 <paramdef>char** <parameter>display</parameter></paramdef>
116                         </funcprototype>
117
118                         <funcprototype>
119                                 <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
120                                 <paramdef>const char* <parameter>session</parameter></paramdef>
121                                 <paramdef>char** <parameter>remote_host</parameter></paramdef>
122                         </funcprototype>
123
124                         <funcprototype>
125                                 <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
126                                 <paramdef>const char* <parameter>session</parameter></paramdef>
127                                 <paramdef>char** <parameter>remote_user</parameter></paramdef>
128                         </funcprototype>
129
130                         <funcprototype>
131                                 <funcdef>int <function>sd_session_get_tty</function></funcdef>
132                                 <paramdef>const char* <parameter>session</parameter></paramdef>
133                                 <paramdef>char** <parameter>tty</parameter></paramdef>
134                         </funcprototype>
135
136                         <funcprototype>
137                                 <funcdef>int <function>sd_session_get_vt</function></funcdef>
138                                 <paramdef>const char* <parameter>session</parameter></paramdef>
139                                 <paramdef>unsigned int* <parameter>vt</parameter></paramdef>
140                         </funcprototype>
141                 </funcsynopsis>
142         </refsynopsisdiv>
143
144         <refsect1>
145                 <title>Description</title>
146
147                 <para><function>sd_session_is_active()</function> may
148                 be used to determine whether the session identified by
149                 the specified session identifier is currently active
150                 (i.e. currently in the foreground and available for
151                 user input) or not.</para>
152
153                 <para><function>sd_session_is_remote()</function> may
154                 be used to determine whether the session identified by
155                 the specified session identifier is a remote session
156                 (i.e. its remote host is known) or not.</para>
157
158                 <para><function>sd_session_get_state()</function> may
159                 be used to determine the state of the session
160                 identified by the specified session identifier. The
161                 following states are currently known:
162                 <literal>online</literal> (session logged in, but
163                 session not active, i.e. not in the foreground),
164                 <literal>active</literal> (session logged in and
165                 active, i.e. in the foreground),
166                 <literal>closing</literal> (session nominally logged
167                 out, but some processes belonging to it are still
168                 around). In the future additional states might be
169                 defined, client code should be written to be robust in
170                 regards to additional state strings being
171                 returned. This function is a more generic version of
172                 <function>sd_session_is_active()</function>. The returned
173                 string needs to be freed with the libc
174                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
175                 call after use.</para>
176
177                 <para><function>sd_session_get_uid()</function> may be
178                 used to determine the user identifier of the Unix user the session
179                 identified by the specified session identifier belongs
180                 to.</para>
181
182                 <para><function>sd_session_get_seat()</function> may
183                 be used to determine the seat identifier of the seat
184                 the session identified by the specified session
185                 identifier belongs to. Note that not all sessions are
186                 attached to a seat, this call will fail for them. The
187                 returned string needs to be freed with the libc
188                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
189                 call after use.</para>
190
191                 <para><function>sd_session_get_service()</function>
192                 may be used to determine the name of the service (as
193                 passed during PAM session setup) that registered the
194                 session identified by the specified session
195                 identifier. The returned string needs to be freed with
196                 the libc
197                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
198                 call after use.</para>
199
200                 <para><function>sd_session_get_type()</function> may
201                 be used to determine the type of the session
202                 identified by the specified session identifier. The
203                 returned string is one of <literal>x11</literal>,
204                 <literal>wayland</literal>, <literal>tty</literal> or
205                 <literal>unspecified</literal> and needs to be freed
206                 with the libc
207                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
208                 call after use.</para>
209
210                 <para><function>sd_session_get_class()</function> may
211                 be used to determine the class of the session
212                 identified by the specified session identifier. The
213                 returned string is one of <literal>user</literal>,
214                 <literal>greeter</literal>,
215                 <literal>lock-screen</literal>, or
216                 <literal>background</literal> and needs to be freed
217                 with the libc
218                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
219                 call after use.</para>
220
221                 <para><function>sd_session_get_display()</function>
222                 may be used to determine the X11 display of the
223                 session identified by the specified session
224                 identifier. The returned string needs to be
225                 freed with the libc
226                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
227                 call after use.</para>
228
229                 <para><function>sd_session_get_remote_host()</function>
230                 may be used to determine the remote hostname of the
231                 session identified by the specified session
232                 identifier. The returned string needs to be
233                 freed with the libc
234                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
235                 call after use.</para>
236
237                 <para><function>sd_session_get_remote_user()</function>
238                 may be used to determine the remote username of the
239                 session identified by the specified session
240                 identifier. The returned string needs to be
241                 freed with the libc
242                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
243                 call after use. Note that this value is rarely known
244                 to the system, and even then should not be relied on.</para>
245
246                 <para><function>sd_session_get_tty()</function>
247                 may be used to determine the TTY device of the
248                 session identified by the specified session
249                 identifier. The returned string needs to be
250                 freed with the libc
251                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
252                 call after use.</para>
253
254                 <para><function>sd_session_get_vt()</function>
255                 may be used to determine the VT number of the
256                 session identified by the specified session
257                 identifier. This function will return an error if
258                 the seat does not support VTs.</para>
259
260                 <para>If the <varname>session</varname> parameter of
261                 any of these functions is passed as
262                 <constant>NULL</constant>, the operation is executed
263                 for the session the calling process is a member of, if
264                 there is any.</para>
265         </refsect1>
266
267         <refsect1>
268                 <title>Return Value</title>
269
270                 <para>If the test succeeds,
271                 <function>sd_session_is_active()</function> and
272                 <function>sd_session_is_remote()</function> return a
273                 positive integer; if it fails, 0.  On success,
274                 <function>sd_session_get_state()</function>,
275                 <function>sd_session_get_uid()</function>,
276                 <function>sd_session_get_seat()</function>,
277                 <function>sd_session_get_service()</function>,
278                 <function>sd_session_get_type()</function>,
279                 <function>sd_session_get_class()</function>,
280                 <function>sd_session_get_display()</function>,
281                 <function>sd_session_get_remote_user()</function>,
282                 <function>sd_session_get_remote_host()</function> and
283                 <function>sd_session_get_tty()</function> return 0 or
284                 a positive integer. On failure, these calls return a
285                 negative errno-style error code.</para>
286         </refsect1>
287
288         <refsect1>
289                 <title>Notes</title>
290
291                 <para>The <function>sd_session_is_active()</function>,
292                 <function>sd_session_get_state()</function>,
293                 <function>sd_session_get_uid()</function>,
294                 <function>sd_session_get_seat()</function>,
295                 <function>sd_session_get_service()</function>,
296                 <function>sd_session_get_type()</function>,
297                 <function>sd_session_get_class()</function>,
298                 <function>sd_session_get_display()</function>,
299                 <function>sd_session_get_remote_host()</function>,
300                 <function>sd_session_get_remote_user()</function> and
301                 <function>sd_session_get_tty()</function>
302                 interfaces are available as a shared library, which can
303                 be compiled and linked to with the
304                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
305                 file.</para>
306         </refsect1>
307
308         <refsect1>
309                 <title>See Also</title>
310
311                 <para>
312                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
313                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
314                         <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
315                 </para>
316         </refsect1>
317
318 </refentry>