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