]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/sd_session_is_active.xml
Merge pull request #8822 from fbuihuu/rfc-tmpfiles-safe-upstream
[thirdparty/systemd.git] / man / sd_session_is_active.xml
CommitLineData
0b3b020a
LP
1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
0b3b020a
LP
4
5<!--
572eb058 6 SPDX-License-Identifier: LGPL-2.1+
0b3b020a
LP
7-->
8
7d6b2723
ZJS
9<refentry id="sd_session_is_active" conditional='HAVE_PAM'
10 xmlns:xi="http://www.w3.org/2001/XInclude">
0b3b020a 11
798d3a52
ZJS
12 <refentryinfo>
13 <title>sd_session_is_active</title>
14 <productname>systemd</productname>
798d3a52
ZJS
15 </refentryinfo>
16
17 <refmeta>
18 <refentrytitle>sd_session_is_active</refentrytitle>
19 <manvolnum>3</manvolnum>
20 </refmeta>
21
22 <refnamediv>
23 <refname>sd_session_is_active</refname>
24 <refname>sd_session_is_remote</refname>
25 <refname>sd_session_get_state</refname>
26 <refname>sd_session_get_uid</refname>
27 <refname>sd_session_get_seat</refname>
28 <refname>sd_session_get_service</refname>
29 <refname>sd_session_get_type</refname>
30 <refname>sd_session_get_class</refname>
31 <refname>sd_session_get_desktop</refname>
32 <refname>sd_session_get_display</refname>
33 <refname>sd_session_get_tty</refname>
34 <refname>sd_session_get_vt</refname>
35 <refname>sd_session_get_remote_host</refname>
36 <refname>sd_session_get_remote_user</refname>
37 <refpurpose>Determine state of a specific session</refpurpose>
38 </refnamediv>
39
40 <refsynopsisdiv>
41 <funcsynopsis>
42 <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
43
44 <funcprototype>
45 <funcdef>int <function>sd_session_is_active</function></funcdef>
46 <paramdef>const char *<parameter>session</parameter></paramdef>
47 </funcprototype>
48
49 <funcprototype>
50 <funcdef>int <function>sd_session_is_remote</function></funcdef>
51 <paramdef>const char *<parameter>session</parameter></paramdef>
52 </funcprototype>
53
54 <funcprototype>
55 <funcdef>int <function>sd_session_get_state</function></funcdef>
56 <paramdef>const char *<parameter>session</parameter></paramdef>
57 <paramdef>char **<parameter>state</parameter></paramdef>
58 </funcprototype>
59
60 <funcprototype>
61 <funcdef>int <function>sd_session_get_uid</function></funcdef>
62 <paramdef>const char *<parameter>session</parameter></paramdef>
63 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
64 </funcprototype>
65
66 <funcprototype>
67 <funcdef>int <function>sd_session_get_seat</function></funcdef>
68 <paramdef>const char *<parameter>session</parameter></paramdef>
69 <paramdef>char **<parameter>seat</parameter></paramdef>
70 </funcprototype>
71
72 <funcprototype>
73 <funcdef>int <function>sd_session_get_service</function></funcdef>
74 <paramdef>const char *<parameter>session</parameter></paramdef>
75 <paramdef>char **<parameter>service</parameter></paramdef>
76 </funcprototype>
77
78 <funcprototype>
79 <funcdef>int <function>sd_session_get_type</function></funcdef>
80 <paramdef>const char *<parameter>session</parameter></paramdef>
81 <paramdef>char **<parameter>type</parameter></paramdef>
82 </funcprototype>
83
84 <funcprototype>
85 <funcdef>int <function>sd_session_get_class</function></funcdef>
86 <paramdef>const char *<parameter>session</parameter></paramdef>
87 <paramdef>char **<parameter>class</parameter></paramdef>
88 </funcprototype>
89
90 <funcprototype>
91 <funcdef>int <function>sd_session_get_desktop</function></funcdef>
92 <paramdef>const char *<parameter>session</parameter></paramdef>
93 <paramdef>char **<parameter>desktop</parameter></paramdef>
94 </funcprototype>
95
96 <funcprototype>
97 <funcdef>int <function>sd_session_get_display</function></funcdef>
98 <paramdef>const char *<parameter>session</parameter></paramdef>
99 <paramdef>char **<parameter>display</parameter></paramdef>
100 </funcprototype>
101
102 <funcprototype>
103 <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
104 <paramdef>const char *<parameter>session</parameter></paramdef>
105 <paramdef>char **<parameter>remote_host</parameter></paramdef>
106 </funcprototype>
107
108 <funcprototype>
109 <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
110 <paramdef>const char *<parameter>session</parameter></paramdef>
111 <paramdef>char **<parameter>remote_user</parameter></paramdef>
112 </funcprototype>
113
114 <funcprototype>
115 <funcdef>int <function>sd_session_get_tty</function></funcdef>
116 <paramdef>const char *<parameter>session</parameter></paramdef>
117 <paramdef>char **<parameter>tty</parameter></paramdef>
118 </funcprototype>
119
120 <funcprototype>
121 <funcdef>int <function>sd_session_get_vt</function></funcdef>
122 <paramdef>const char *<parameter>session</parameter></paramdef>
123 <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
124 </funcprototype>
125 </funcsynopsis>
126 </refsynopsisdiv>
127
128 <refsect1>
129 <title>Description</title>
130
131 <para><function>sd_session_is_active()</function> may be used to
132 determine whether the session identified by the specified session
133 identifier is currently active (i.e. currently in the foreground
134 and available for user input) or not.</para>
135
136 <para><function>sd_session_is_remote()</function> may be used to
137 determine whether the session identified by the specified session
138 identifier is a remote session (i.e. its remote host is known) or
139 not.</para>
140
141 <para><function>sd_session_get_state()</function> may be used to
142 determine the state of the session identified by the specified
143 session identifier. The following states are currently known:
144 <literal>online</literal> (session logged in, but session not
145 active, i.e. not in the foreground), <literal>active</literal>
146 (session logged in and active, i.e. in the foreground),
147 <literal>closing</literal> (session nominally logged out, but some
148 processes belonging to it are still around). In the future
149 additional states might be defined, client code should be written
150 to be robust in regards to additional state strings being
151 returned. This function is a more generic version of
152 <function>sd_session_is_active()</function>. The returned string
153 needs to be freed with the libc
154 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
155 call after use.</para>
156
157 <para><function>sd_session_get_uid()</function> may be used to
158 determine the user identifier of the Unix user the session
159 identified by the specified session identifier belongs to.</para>
160
161 <para><function>sd_session_get_seat()</function> may be used to
162 determine the seat identifier of the seat the session identified
163 by the specified session identifier belongs to. Note that not all
ce737f46
ZJS
164 sessions are attached to a seat, this call will fail (returning
165 <constant>-ENODATA</constant>) for them. The returned string needs
166 to be freed with the libc
798d3a52
ZJS
167 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
168 call after use.</para>
169
170 <para><function>sd_session_get_service()</function> may be used to
171 determine the name of the service (as passed during PAM session
172 setup) that registered the session identified by the specified
173 session identifier. The returned string needs to be freed with the
174 libc
175 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
176 call after use.</para>
177
178 <para><function>sd_session_get_type()</function> may be used to
179 determine the type of the session identified by the specified
180 session identifier. The returned string is one of
181 <literal>x11</literal>, <literal>wayland</literal>,
182 <literal>tty</literal>, <literal>mir</literal> or
183 <literal>unspecified</literal> and needs to be freed with the libc
184 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
185 call after use.</para>
186
187 <para><function>sd_session_get_class()</function> may be used to
188 determine the class of the session identified by the specified
189 session identifier. The returned string is one of
190 <literal>user</literal>, <literal>greeter</literal>,
191 <literal>lock-screen</literal>, or <literal>background</literal>
192 and needs to be freed with the libc
193 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
194 call after use.</para>
195
196 <para><function>sd_session_get_desktop()</function> may be used to
197 determine the brand of the desktop running on the session
198 identified by the specified session identifier. This field can be
199 set freely by desktop environments and does not follow any special
200 formatting. However, desktops are strongly recommended to use the
201 same identifiers and capitalization as for
202 <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
203 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
204 Entry Specification</ulink>. The returned string needs to be freed
205 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_display()</function> may be used to
210 determine the X11 display of the session identified by the
211 specified session identifier. The returned string needs to be
212 freed with the libc
213 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
214 call after use.</para>
215
216 <para><function>sd_session_get_remote_host()</function> may be
217 used to determine the remote hostname of the session identified by
218 the specified session identifier. The returned string needs to be
219 freed with the libc
220 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
221 call after use.</para>
222
223 <para><function>sd_session_get_remote_user()</function> may be
224 used to determine the remote username of the session identified by
225 the specified session identifier. The returned string needs to be
226 freed with the libc
227 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
228 call after use. Note that this value is rarely known to the
229 system, and even then should not be relied on.</para>
230
231 <para><function>sd_session_get_tty()</function> may be used to
232 determine the TTY device 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_vt()</function> may be used to
239 determine the VT number of the session identified by the specified
240 session identifier. This function will return an error if the seat
241 does not support VTs.</para>
242
243 <para>If the <varname>session</varname> parameter of any of these
244 functions is passed as <constant>NULL</constant>, the operation is
245 executed for the session the calling process is a member of, if
246 there is any.</para>
247 </refsect1>
248
249 <refsect1>
250 <title>Return Value</title>
251
252 <para>If the test succeeds,
253 <function>sd_session_is_active()</function> and
254 <function>sd_session_is_remote()</function> return a
255 positive integer; if it fails, 0. On success,
256 <function>sd_session_get_state()</function>,
257 <function>sd_session_get_uid()</function>,
258 <function>sd_session_get_seat()</function>,
259 <function>sd_session_get_service()</function>,
260 <function>sd_session_get_type()</function>,
261 <function>sd_session_get_class()</function>,
262 <function>sd_session_get_display()</function>,
263 <function>sd_session_get_remote_user()</function>,
264 <function>sd_session_get_remote_host()</function> and
265 <function>sd_session_get_tty()</function> return 0 or
266 a positive integer. On failure, these calls return a
267 negative errno-style error code.</para>
268 </refsect1>
269
707b66c6
LP
270 <refsect1>
271 <title>Errors</title>
272
273 <para>Returned errors may indicate the following problems:</para>
274
275 <variablelist>
276
277 <varlistentry>
278 <term><constant>-ENXIO</constant></term>
279
280 <listitem><para>The specified session does not exist.</para>
281 </listitem>
282 </varlistentry>
283
284 <varlistentry>
285 <term><constant>-ENODATA</constant></term>
286
a8eaaee7 287 <listitem><para>The given field is not specified for the described
707b66c6
LP
288 session.</para>
289 </listitem>
290 </varlistentry>
291
292 <varlistentry>
293 <term><constant>-EINVAL</constant></term>
294
295 <listitem><para>An input parameter was invalid (out of range,
7ca41557 296 or NULL, where that is not accepted).</para></listitem>
707b66c6
LP
297 </varlistentry>
298
299 <varlistentry>
300 <term><constant>-ENOMEM</constant></term>
301
302 <listitem><para>Memory allocation failed.</para></listitem>
303 </varlistentry>
304 </variablelist>
305 </refsect1>
306
7d6b2723 307 <xi:include href="libsystemd-pkgconfig.xml" />
798d3a52
ZJS
308
309 <refsect1>
310 <title>See Also</title>
311
312 <para>
313 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
315 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
316 </para>
317 </refsect1>
0b3b020a
LP
318
319</refentry>