chiark / gitweb /
Restore shared XML files.
[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 be used to
155     determine whether the session identified by the specified session
156     identifier is currently active (i.e. currently in the foreground
157     and available for user input) or not.</para>
158
159     <para><function>sd_session_is_remote()</function> may be used to
160     determine whether the session identified by the specified session
161     identifier is a remote session (i.e. its remote host is known) or
162     not.</para>
163
164     <para><function>sd_session_get_state()</function> may be used to
165     determine the state of the session identified by the specified
166     session identifier. The following states are currently known:
167     <literal>online</literal> (session logged in, but session not
168     active, i.e. not in the foreground), <literal>active</literal>
169     (session logged in and active, i.e. in the foreground),
170     <literal>closing</literal> (session nominally logged out, but some
171     processes belonging to it are still around). In the future
172     additional states might be defined, client code should be written
173     to be robust in regards to additional state strings being
174     returned. This function is a more generic version of
175     <function>sd_session_is_active()</function>. The returned string
176     needs to be freed with the libc
177     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
178     call after use.</para>
179
180     <para><function>sd_session_get_uid()</function> may be used to
181     determine the user identifier of the Unix user the session
182     identified by the specified session identifier belongs to.</para>
183
184     <para><function>sd_session_get_seat()</function> may be used to
185     determine the seat identifier of the seat the session identified
186     by the specified session identifier belongs to. Note that not all
187     sessions are attached to a seat, this call will fail for them. The
188     returned string needs to be freed with the libc
189     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
190     call after use.</para>
191
192     <para><function>sd_session_get_service()</function> may be used to
193     determine the name of the service (as passed during PAM session
194     setup) that registered the session identified by the specified
195     session identifier. The returned string needs to be freed with the
196     libc
197     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
198     call after use.</para>
199
200     <para><function>sd_session_get_type()</function> may be used to
201     determine the type of the session identified by the specified
202     session identifier. The returned string is one of
203     <literal>x11</literal>, <literal>wayland</literal>,
204     <literal>tty</literal>, <literal>mir</literal> or
205     <literal>unspecified</literal> and needs to be freed with the libc
206     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
207     call after use.</para>
208
209     <para><function>sd_session_get_class()</function> may be used to
210     determine the class of the session identified by the specified
211     session identifier. The returned string is one of
212     <literal>user</literal>, <literal>greeter</literal>,
213     <literal>lock-screen</literal>, or <literal>background</literal>
214     and needs to be freed with the libc
215     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
216     call after use.</para>
217
218     <para><function>sd_session_get_desktop()</function> may be used to
219     determine the brand of the desktop running on the session
220     identified by the specified session identifier. This field can be
221     set freely by desktop environments and does not follow any special
222     formatting. However, desktops are strongly recommended to use the
223     same identifiers and capitalization as for
224     <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
225     url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
226     Entry Specification</ulink>. The returned string needs to be freed
227     with the libc
228     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
229     call after use.</para>
230
231     <para><function>sd_session_get_display()</function> may be used to
232     determine the X11 display of the session identified by the
233     specified session identifier. The returned string needs to be
234     freed with the libc
235     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
236     call after use.</para>
237
238     <para><function>sd_session_get_remote_host()</function> may be
239     used to determine the remote hostname of the session identified by
240     the specified session identifier. The returned string needs to be
241     freed with the libc
242     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
243     call after use.</para>
244
245     <para><function>sd_session_get_remote_user()</function> may be
246     used to determine the remote username of the session identified by
247     the specified session 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. Note that this value is rarely known to the
251     system, and even then should not be relied on.</para>
252
253     <para><function>sd_session_get_tty()</function> may be used to
254     determine the TTY device of the session identified by the
255     specified session 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_vt()</function> may be used to
261     determine the VT number of the session identified by the specified
262     session identifier. This function will return an error if the seat
263     does not support VTs.</para>
264
265     <para>If the <varname>session</varname> parameter of any of these
266     functions is passed as <constant>NULL</constant>, the operation is
267     executed for the session the calling process is a member of, if
268     there is any.</para>
269   </refsect1>
270
271   <refsect1>
272     <title>Return Value</title>
273
274     <para>If the test succeeds,
275     <function>sd_session_is_active()</function> and
276     <function>sd_session_is_remote()</function> return a
277     positive integer; if it fails, 0.  On success,
278     <function>sd_session_get_state()</function>,
279     <function>sd_session_get_uid()</function>,
280     <function>sd_session_get_seat()</function>,
281     <function>sd_session_get_service()</function>,
282     <function>sd_session_get_type()</function>,
283     <function>sd_session_get_class()</function>,
284     <function>sd_session_get_display()</function>,
285     <function>sd_session_get_remote_user()</function>,
286     <function>sd_session_get_remote_host()</function> and
287     <function>sd_session_get_tty()</function> return 0 or
288     a positive integer. On failure, these calls return a
289     negative errno-style error code.</para>
290   </refsect1>
291
292   <refsect1>
293     <title>Notes</title>
294
295     <para>The <function>sd_session_is_active()</function>,
296     <function>sd_session_get_state()</function>,
297     <function>sd_session_get_uid()</function>,
298     <function>sd_session_get_seat()</function>,
299     <function>sd_session_get_service()</function>,
300     <function>sd_session_get_type()</function>,
301     <function>sd_session_get_class()</function>,
302     <function>sd_session_get_display()</function>,
303     <function>sd_session_get_remote_host()</function>,
304     <function>sd_session_get_remote_user()</function> and
305     <function>sd_session_get_tty()</function>
306     interfaces are available as a shared library, which can
307     be compiled and linked to with the
308     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
309     file.</para>
310   </refsect1>
311
312   <refsect1>
313     <title>See Also</title>
314
315     <para>
316       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
317       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
318       <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
319     </para>
320   </refsect1>
321
322 </refentry>