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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_session_is_active" conditional='HAVE_PAM'>
27 <title>sd_session_is_active</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_session_is_active</refentrytitle>
42 <manvolnum>3</manvolnum>
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>
65 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
68 <funcdef>int <function>sd_session_is_active</function></funcdef>
69 <paramdef>const char *<parameter>session</parameter></paramdef>
73 <funcdef>int <function>sd_session_is_remote</function></funcdef>
74 <paramdef>const char *<parameter>session</parameter></paramdef>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
152 <title>Description</title>
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>
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>
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>
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
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>
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
204 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
205 call after use.</para>
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>
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
225 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
226 call after use.</para>
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
237 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
239 Specification</ulink>. The returned string needs to be
241 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
242 call after use.</para>
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
249 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
250 call after use.</para>
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
257 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
258 call after use.</para>
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
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>
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
274 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
275 call after use.</para>
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>
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
291 <title>Return Value</title>
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>
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>
332 <title>See Also</title>
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>