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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2010 Lennart Poettering
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id="sd_session_is_active" conditional='HAVE_PAM'>
30 <title>sd_session_is_active</title>
31 <productname>systemd</productname>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
44 <refentrytitle>sd_session_is_active</refentrytitle>
45 <manvolnum>3</manvolnum>
49 <refname>sd_session_is_active</refname>
50 <refname>sd_session_is_remote</refname>
51 <refname>sd_session_get_state</refname>
52 <refname>sd_session_get_uid</refname>
53 <refname>sd_session_get_seat</refname>
54 <refname>sd_session_get_service</refname>
55 <refname>sd_session_get_type</refname>
56 <refname>sd_session_get_class</refname>
57 <refname>sd_session_get_desktop</refname>
58 <refname>sd_session_get_display</refname>
59 <refname>sd_session_get_tty</refname>
60 <refname>sd_session_get_vt</refname>
61 <refname>sd_session_get_remote_host</refname>
62 <refname>sd_session_get_remote_user</refname>
63 <refpurpose>Determine state of a specific session</refpurpose>
68 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
71 <funcdef>int <function>sd_session_is_active</function></funcdef>
72 <paramdef>const char *<parameter>session</parameter></paramdef>
76 <funcdef>int <function>sd_session_is_remote</function></funcdef>
77 <paramdef>const char *<parameter>session</parameter></paramdef>
81 <funcdef>int <function>sd_session_get_state</function></funcdef>
82 <paramdef>const char *<parameter>session</parameter></paramdef>
83 <paramdef>char **<parameter>state</parameter></paramdef>
87 <funcdef>int <function>sd_session_get_uid</function></funcdef>
88 <paramdef>const char *<parameter>session</parameter></paramdef>
89 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
93 <funcdef>int <function>sd_session_get_seat</function></funcdef>
94 <paramdef>const char *<parameter>session</parameter></paramdef>
95 <paramdef>char **<parameter>seat</parameter></paramdef>
99 <funcdef>int <function>sd_session_get_service</function></funcdef>
100 <paramdef>const char *<parameter>session</parameter></paramdef>
101 <paramdef>char **<parameter>service</parameter></paramdef>
105 <funcdef>int <function>sd_session_get_type</function></funcdef>
106 <paramdef>const char *<parameter>session</parameter></paramdef>
107 <paramdef>char **<parameter>type</parameter></paramdef>
111 <funcdef>int <function>sd_session_get_class</function></funcdef>
112 <paramdef>const char *<parameter>session</parameter></paramdef>
113 <paramdef>char **<parameter>class</parameter></paramdef>
117 <funcdef>int <function>sd_session_get_desktop</function></funcdef>
118 <paramdef>const char *<parameter>session</parameter></paramdef>
119 <paramdef>char **<parameter>desktop</parameter></paramdef>
123 <funcdef>int <function>sd_session_get_display</function></funcdef>
124 <paramdef>const char *<parameter>session</parameter></paramdef>
125 <paramdef>char **<parameter>display</parameter></paramdef>
129 <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
130 <paramdef>const char *<parameter>session</parameter></paramdef>
131 <paramdef>char **<parameter>remote_host</parameter></paramdef>
135 <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
136 <paramdef>const char *<parameter>session</parameter></paramdef>
137 <paramdef>char **<parameter>remote_user</parameter></paramdef>
141 <funcdef>int <function>sd_session_get_tty</function></funcdef>
142 <paramdef>const char *<parameter>session</parameter></paramdef>
143 <paramdef>char **<parameter>tty</parameter></paramdef>
147 <funcdef>int <function>sd_session_get_vt</function></funcdef>
148 <paramdef>const char *<parameter>session</parameter></paramdef>
149 <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
155 <title>Description</title>
157 <para><function>sd_session_is_active()</function> may be used to
158 determine whether the session identified by the specified session
159 identifier is currently active (i.e. currently in the foreground
160 and available for user input) or not.</para>
162 <para><function>sd_session_is_remote()</function> may be used to
163 determine whether the session identified by the specified session
164 identifier is a remote session (i.e. its remote host is known) or
167 <para><function>sd_session_get_state()</function> may be used to
168 determine the state of the session identified by the specified
169 session identifier. The following states are currently known:
170 <literal>online</literal> (session logged in, but session not
171 active, i.e. not in the foreground), <literal>active</literal>
172 (session logged in and active, i.e. in the foreground),
173 <literal>closing</literal> (session nominally logged out, but some
174 processes belonging to it are still around). In the future
175 additional states might be defined, client code should be written
176 to be robust in regards to additional state strings being
177 returned. This function is a more generic version of
178 <function>sd_session_is_active()</function>. The returned string
179 needs to be freed with the libc
180 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
181 call after use.</para>
183 <para><function>sd_session_get_uid()</function> may be used to
184 determine the user identifier of the Unix user the session
185 identified by the specified session identifier belongs to.</para>
187 <para><function>sd_session_get_seat()</function> may be used to
188 determine the seat identifier of the seat the session identified
189 by the specified session identifier belongs to. Note that not all
190 sessions are attached to a seat, this call will fail for them. The
191 returned string needs to be freed with the libc
192 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
193 call after use.</para>
195 <para><function>sd_session_get_service()</function> may be used to
196 determine the name of the service (as passed during PAM session
197 setup) that registered the session identified by the specified
198 session identifier. The returned string needs to be freed with the
200 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
201 call after use.</para>
203 <para><function>sd_session_get_type()</function> may be used to
204 determine the type of the session identified by the specified
205 session identifier. The returned string is one of
206 <literal>x11</literal>, <literal>wayland</literal>,
207 <literal>tty</literal>, <literal>mir</literal> or
208 <literal>unspecified</literal> and needs to be freed with the libc
209 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
210 call after use.</para>
212 <para><function>sd_session_get_class()</function> may be used to
213 determine the class of the session identified by the specified
214 session identifier. The returned string is one of
215 <literal>user</literal>, <literal>greeter</literal>,
216 <literal>lock-screen</literal>, or <literal>background</literal>
217 and needs to be freed with the libc
218 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
219 call after use.</para>
221 <para><function>sd_session_get_desktop()</function> may be used to
222 determine the brand of the desktop running on the session
223 identified by the specified session identifier. This field can be
224 set freely by desktop environments and does not follow any special
225 formatting. However, desktops are strongly recommended to use the
226 same identifiers and capitalization as for
227 <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
228 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
229 Entry Specification</ulink>. The returned string needs to be freed
231 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
232 call after use.</para>
234 <para><function>sd_session_get_display()</function> may be used to
235 determine the X11 display of the session identified by the
236 specified session identifier. The returned string needs to be
238 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
239 call after use.</para>
241 <para><function>sd_session_get_remote_host()</function> may be
242 used to determine the remote hostname of the session identified by
243 the specified session identifier. The returned string needs to be
245 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
246 call after use.</para>
248 <para><function>sd_session_get_remote_user()</function> may be
249 used to determine the remote username of the session identified by
250 the specified session identifier. The returned string needs to be
252 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
253 call after use. Note that this value is rarely known to the
254 system, and even then should not be relied on.</para>
256 <para><function>sd_session_get_tty()</function> may be used to
257 determine the TTY device of the session identified by the
258 specified session identifier. The returned string needs to be
260 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
261 call after use.</para>
263 <para><function>sd_session_get_vt()</function> may be used to
264 determine the VT number of the session identified by the specified
265 session identifier. This function will return an error if the seat
266 does not support VTs.</para>
268 <para>If the <varname>session</varname> parameter of any of these
269 functions is passed as <constant>NULL</constant>, the operation is
270 executed for the session the calling process is a member of, if
275 <title>Return Value</title>
277 <para>If the test succeeds,
278 <function>sd_session_is_active()</function> and
279 <function>sd_session_is_remote()</function> return a
280 positive integer; if it fails, 0. On success,
281 <function>sd_session_get_state()</function>,
282 <function>sd_session_get_uid()</function>,
283 <function>sd_session_get_seat()</function>,
284 <function>sd_session_get_service()</function>,
285 <function>sd_session_get_type()</function>,
286 <function>sd_session_get_class()</function>,
287 <function>sd_session_get_display()</function>,
288 <function>sd_session_get_remote_user()</function>,
289 <function>sd_session_get_remote_host()</function> and
290 <function>sd_session_get_tty()</function> return 0 or
291 a positive integer. On failure, these calls return a
292 negative errno-style error code.</para>
298 <para>The <function>sd_session_is_active()</function>,
299 <function>sd_session_get_state()</function>,
300 <function>sd_session_get_uid()</function>,
301 <function>sd_session_get_seat()</function>,
302 <function>sd_session_get_service()</function>,
303 <function>sd_session_get_type()</function>,
304 <function>sd_session_get_class()</function>,
305 <function>sd_session_get_display()</function>,
306 <function>sd_session_get_remote_host()</function>,
307 <function>sd_session_get_remote_user()</function> and
308 <function>sd_session_get_tty()</function>
309 interfaces are available as a shared library, which can
310 be compiled and linked to with the
311 <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
316 <title>See Also</title>
319 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
320 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
321 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>