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