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 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_session_is_active" conditional='HAVE_PAM'
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>sd_session_is_active
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>sd_session_is_active
</refentrytitle>
19 <manvolnum>3</manvolnum>
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>
42 <funcsynopsisinfo>#include
<systemd/sd-login.h
></funcsynopsisinfo>
45 <funcdef>int
<function>sd_session_is_active
</function></funcdef>
46 <paramdef>const char *
<parameter>session
</parameter></paramdef>
50 <funcdef>int
<function>sd_session_is_remote
</function></funcdef>
51 <paramdef>const char *
<parameter>session
</parameter></paramdef>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
129 <title>Description
</title>
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>
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
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>
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>
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
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
167 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
168 call after use.
</para>
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
175 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
176 call after use.
</para>
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>
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>
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
206 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
207 call after use.
</para>
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
213 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
214 call after use.
</para>
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
220 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
221 call after use.
</para>
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
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>
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
235 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
236 call after use.
</para>
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>
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
250 <title>Return Value
</title>
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>
271 <title>Errors
</title>
273 <para>Returned errors may indicate the following problems:
</para>
278 <term><constant>-ENXIO
</constant></term>
280 <listitem><para>The specified session does not exist.
</para>
285 <term><constant>-ENODATA
</constant></term>
287 <listitem><para>The given field is not specified for the described
293 <term><constant>-EINVAL
</constant></term>
295 <listitem><para>An input parameter was invalid (out of range,
296 or NULL, where that is not accepted).
</para></listitem>
300 <term><constant>-ENOMEM
</constant></term>
302 <listitem><para>Memory allocation failed.
</para></listitem>
307 <xi:include href=
"libsystemd-pkgconfig.xml" />
310 <title>See Also
</title>
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>