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 elogind.
7 SPDX-License-Identifier: LGPL-2.1+
10 Copyright 2010 Lennart Poettering
13 <refentry id="sd_session_is_active" conditional='HAVE_PAM'
14 xmlns:xi="http://www.w3.org/2001/XInclude">
17 <title>sd_session_is_active</title>
18 <productname>elogind</productname>
22 <contrib>Developer</contrib>
23 <firstname>Lennart</firstname>
24 <surname>Poettering</surname>
25 <email>lennart@poettering.net</email>
31 <refentrytitle>sd_session_is_active</refentrytitle>
32 <manvolnum>3</manvolnum>
36 <refname>sd_session_is_active</refname>
37 <refname>sd_session_is_remote</refname>
38 <refname>sd_session_get_state</refname>
39 <refname>sd_session_get_uid</refname>
40 <refname>sd_session_get_seat</refname>
41 <refname>sd_session_get_service</refname>
42 <refname>sd_session_get_type</refname>
43 <refname>sd_session_get_class</refname>
44 <refname>sd_session_get_desktop</refname>
45 <refname>sd_session_get_display</refname>
46 <refname>sd_session_get_tty</refname>
47 <refname>sd_session_get_vt</refname>
48 <refname>sd_session_get_remote_host</refname>
49 <refname>sd_session_get_remote_user</refname>
50 <refpurpose>Determine state of a specific session</refpurpose>
55 <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo>
58 <funcdef>int <function>sd_session_is_active</function></funcdef>
59 <paramdef>const char *<parameter>session</parameter></paramdef>
63 <funcdef>int <function>sd_session_is_remote</function></funcdef>
64 <paramdef>const char *<parameter>session</parameter></paramdef>
68 <funcdef>int <function>sd_session_get_state</function></funcdef>
69 <paramdef>const char *<parameter>session</parameter></paramdef>
70 <paramdef>char **<parameter>state</parameter></paramdef>
74 <funcdef>int <function>sd_session_get_uid</function></funcdef>
75 <paramdef>const char *<parameter>session</parameter></paramdef>
76 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
80 <funcdef>int <function>sd_session_get_seat</function></funcdef>
81 <paramdef>const char *<parameter>session</parameter></paramdef>
82 <paramdef>char **<parameter>seat</parameter></paramdef>
86 <funcdef>int <function>sd_session_get_service</function></funcdef>
87 <paramdef>const char *<parameter>session</parameter></paramdef>
88 <paramdef>char **<parameter>service</parameter></paramdef>
92 <funcdef>int <function>sd_session_get_type</function></funcdef>
93 <paramdef>const char *<parameter>session</parameter></paramdef>
94 <paramdef>char **<parameter>type</parameter></paramdef>
98 <funcdef>int <function>sd_session_get_class</function></funcdef>
99 <paramdef>const char *<parameter>session</parameter></paramdef>
100 <paramdef>char **<parameter>class</parameter></paramdef>
104 <funcdef>int <function>sd_session_get_desktop</function></funcdef>
105 <paramdef>const char *<parameter>session</parameter></paramdef>
106 <paramdef>char **<parameter>desktop</parameter></paramdef>
110 <funcdef>int <function>sd_session_get_display</function></funcdef>
111 <paramdef>const char *<parameter>session</parameter></paramdef>
112 <paramdef>char **<parameter>display</parameter></paramdef>
116 <funcdef>int <function>sd_session_get_remote_host</function></funcdef>
117 <paramdef>const char *<parameter>session</parameter></paramdef>
118 <paramdef>char **<parameter>remote_host</parameter></paramdef>
122 <funcdef>int <function>sd_session_get_remote_user</function></funcdef>
123 <paramdef>const char *<parameter>session</parameter></paramdef>
124 <paramdef>char **<parameter>remote_user</parameter></paramdef>
128 <funcdef>int <function>sd_session_get_tty</function></funcdef>
129 <paramdef>const char *<parameter>session</parameter></paramdef>
130 <paramdef>char **<parameter>tty</parameter></paramdef>
134 <funcdef>int <function>sd_session_get_vt</function></funcdef>
135 <paramdef>const char *<parameter>session</parameter></paramdef>
136 <paramdef>unsigned int *<parameter>vt</parameter></paramdef>
142 <title>Description</title>
144 <para><function>sd_session_is_active()</function> may be used to
145 determine whether the session identified by the specified session
146 identifier is currently active (i.e. currently in the foreground
147 and available for user input) or not.</para>
149 <para><function>sd_session_is_remote()</function> may be used to
150 determine whether the session identified by the specified session
151 identifier is a remote session (i.e. its remote host is known) or
154 <para><function>sd_session_get_state()</function> may be used to
155 determine the state of the session identified by the specified
156 session identifier. The following states are currently known:
157 <literal>online</literal> (session logged in, but session not
158 active, i.e. not in the foreground), <literal>active</literal>
159 (session logged in and active, i.e. in the foreground),
160 <literal>closing</literal> (session nominally logged out, but some
161 processes belonging to it are still around). In the future
162 additional states might be defined, client code should be written
163 to be robust in regards to additional state strings being
164 returned. This function is a more generic version of
165 <function>sd_session_is_active()</function>. The returned string
166 needs to be freed with the libc
167 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
168 call after use.</para>
170 <para><function>sd_session_get_uid()</function> may be used to
171 determine the user identifier of the Unix user the session
172 identified by the specified session identifier belongs to.</para>
174 <para><function>sd_session_get_seat()</function> may be used to
175 determine the seat identifier of the seat the session identified
176 by the specified session identifier belongs to. Note that not all
177 sessions are attached to a seat, this call will fail (returning
178 <constant>-ENODATA</constant>) for them. The returned string needs
179 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_service()</function> may be used to
184 determine the name of the service (as passed during PAM session
185 setup) that registered the session identified by the specified
186 session identifier. The returned string needs to be freed with the
188 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
189 call after use.</para>
191 <para><function>sd_session_get_type()</function> may be used to
192 determine the type of the session identified by the specified
193 session identifier. The returned string is one of
194 <literal>x11</literal>, <literal>wayland</literal>,
195 <literal>tty</literal>, <literal>mir</literal> or
196 <literal>unspecified</literal> and needs to be freed with the libc
197 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
198 call after use.</para>
200 <para><function>sd_session_get_class()</function> may be used to
201 determine the class of the session identified by the specified
202 session identifier. The returned string is one of
203 <literal>user</literal>, <literal>greeter</literal>,
204 <literal>lock-screen</literal>, or <literal>background</literal>
205 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>
209 <para><function>sd_session_get_desktop()</function> may be used to
210 determine the brand of the desktop running on the session
211 identified by the specified session identifier. This field can be
212 set freely by desktop environments and does not follow any special
213 formatting. However, desktops are strongly recommended to use the
214 same identifiers and capitalization as for
215 <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
216 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
217 Entry Specification</ulink>. The returned string needs to be freed
219 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
220 call after use.</para>
222 <para><function>sd_session_get_display()</function> may be used to
223 determine the X11 display of the session identified by the
224 specified session identifier. The returned string needs to be
226 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
227 call after use.</para>
229 <para><function>sd_session_get_remote_host()</function> may be
230 used to determine the remote hostname of the session identified by
231 the specified session identifier. The returned string needs to be
233 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
234 call after use.</para>
236 <para><function>sd_session_get_remote_user()</function> may be
237 used to determine the remote username of the session identified by
238 the specified session identifier. The returned string needs to be
240 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
241 call after use. Note that this value is rarely known to the
242 system, and even then should not be relied on.</para>
244 <para><function>sd_session_get_tty()</function> may be used to
245 determine the TTY device of the session identified by the
246 specified session identifier. The returned string needs to be
248 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
249 call after use.</para>
251 <para><function>sd_session_get_vt()</function> may be used to
252 determine the VT number of the session identified by the specified
253 session identifier. This function will return an error if the seat
254 does not support VTs.</para>
256 <para>If the <varname>session</varname> parameter of any of these
257 functions is passed as <constant>NULL</constant>, the operation is
258 executed for the session the calling process is a member of, if
263 <title>Return Value</title>
265 <para>If the test succeeds,
266 <function>sd_session_is_active()</function> and
267 <function>sd_session_is_remote()</function> return a
268 positive integer; if it fails, 0. On success,
269 <function>sd_session_get_state()</function>,
270 <function>sd_session_get_uid()</function>,
271 <function>sd_session_get_seat()</function>,
272 <function>sd_session_get_service()</function>,
273 <function>sd_session_get_type()</function>,
274 <function>sd_session_get_class()</function>,
275 <function>sd_session_get_display()</function>,
276 <function>sd_session_get_remote_user()</function>,
277 <function>sd_session_get_remote_host()</function> and
278 <function>sd_session_get_tty()</function> return 0 or
279 a positive integer. On failure, these calls return a
280 negative errno-style error code.</para>
284 <title>Errors</title>
286 <para>Returned errors may indicate the following problems:</para>
291 <term><constant>-ENXIO</constant></term>
293 <listitem><para>The specified session does not exist.</para>
298 <term><constant>-ENODATA</constant></term>
300 <listitem><para>The given field is not specified for the described
306 <term><constant>-EINVAL</constant></term>
308 <listitem><para>An input parameter was invalid (out of range,
309 or NULL, where that is not accepted).</para></listitem>
313 <term><constant>-ENOMEM</constant></term>
315 <listitem><para>Memory allocation failed.</para></listitem>
320 <xi:include href="libelogind-pkgconfig.xml" />
323 <title>See Also</title>
326 <!-- 0 /// elogind is in section 8
327 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
329 <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
331 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
332 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>