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_get_state</refname>
48 <refname>sd_session_get_uid</refname>
49 <refname>sd_session_get_seat</refname>
50 <refname>sd_session_get_service</refname>
51 <refname>sd_session_get_type</refname>
52 <refname>sd_session_get_class</refname>
53 <refname>sd_session_get_display</refname>
54 <refname>sd_session_get_tty</refname>
55 <refname>sd_session_get_vt</refname>
56 <refpurpose>Determine state of a specific session</refpurpose>
61 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
64 <funcdef>int <function>sd_session_is_active</function></funcdef>
65 <paramdef>const char* <parameter>session</parameter></paramdef>
69 <funcdef>int <function>sd_session_get_state</function></funcdef>
70 <paramdef>const char* <parameter>session</parameter></paramdef>
71 <paramdef>char** <parameter>state</parameter></paramdef>
75 <funcdef>int <function>sd_session_get_uid</function></funcdef>
76 <paramdef>const char* <parameter>session</parameter></paramdef>
77 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
81 <funcdef>int <function>sd_session_get_seat</function></funcdef>
82 <paramdef>const char* <parameter>session</parameter></paramdef>
83 <paramdef>char** <parameter>seat</parameter></paramdef>
87 <funcdef>int <function>sd_session_get_service</function></funcdef>
88 <paramdef>const char* <parameter>session</parameter></paramdef>
89 <paramdef>char** <parameter>service</parameter></paramdef>
93 <funcdef>int <function>sd_session_get_type</function></funcdef>
94 <paramdef>const char* <parameter>session</parameter></paramdef>
95 <paramdef>char** <parameter>type</parameter></paramdef>
99 <funcdef>int <function>sd_session_get_class</function></funcdef>
100 <paramdef>const char* <parameter>session</parameter></paramdef>
101 <paramdef>char** <parameter>class</parameter></paramdef>
105 <funcdef>int <function>sd_session_get_display</function></funcdef>
106 <paramdef>const char* <parameter>session</parameter></paramdef>
107 <paramdef>char** <parameter>display</parameter></paramdef>
111 <funcdef>int <function>sd_session_get_tty</function></funcdef>
112 <paramdef>const char* <parameter>session</parameter></paramdef>
113 <paramdef>char** <parameter>tty</parameter></paramdef>
117 <funcdef>int <function>sd_session_get_vt</function></funcdef>
118 <paramdef>const char* <parameter>session</parameter></paramdef>
119 <paramdef>unsigned int* <parameter>vt</parameter></paramdef>
125 <title>Description</title>
127 <para><function>sd_session_is_active()</function> may
128 be used to determine whether the session identified by
129 the specified session identifier is currently active
130 (i.e. currently in the foreground and available for
131 user input) or not.</para>
133 <para><function>sd_session_get_state()</function> may
134 be used to determine the state of the session
135 identified by the specified session identifier. The
136 following states are currently known:
137 <literal>online</literal> (session logged in, but
138 session not active, i.e. not in the foreground),
139 <literal>active</literal> (session logged in and
140 active, i.e. in the foreground),
141 <literal>closing</literal> (session nominally logged
142 out, but some processes belonging to it are still
143 around). In the future additional states might be
144 defined, client code should be written to be robust in
145 regards to additional state strings being
146 returned. This function is a more generic version of
147 <function>sd_session_is_active()</function>. The returned
148 string needs to be freed with the libc
149 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
150 call after use.</para>
152 <para><function>sd_session_get_uid()</function> may be
153 used to determine the user identifier of the Unix user the session
154 identified by the specified session identifier belongs
157 <para><function>sd_session_get_seat()</function> may
158 be used to determine the seat identifier of the seat
159 the session identified by the specified session
160 identifier belongs to. Note that not all sessions are
161 attached to a seat, this call will fail for them. The
162 returned string needs to be freed with the libc
163 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
164 call after use.</para>
166 <para><function>sd_session_get_service()</function>
167 may be used to determine the name of the service (as
168 passed during PAM session setup) that registered the
169 session identified by the specified session
170 identifier. The returned string needs to be freed with
172 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
173 call after use.</para>
175 <para><function>sd_session_get_type()</function> may
176 be used to determine the type of the session
177 identified by the specified session identifier. The
178 returned string is one of <literal>x11</literal>,
179 <literal>tty</literal> or
180 <literal>unspecified</literal> and needs to be freed
182 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
183 call after use.</para>
185 <para><function>sd_session_get_class()</function> may
186 be used to determine the class of the session
187 identified by the specified session identifier. The
188 returned string is one of <literal>user</literal>,
189 <literal>greeter</literal>,
190 <literal>lock-screen</literal>, or
191 <literal>background</literal> and needs to be freed
193 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
194 call after use.</para>
196 <para><function>sd_session_get_display()</function>
197 may be used to determine the X11 display of the
198 session identified by the specified session
199 identifier. The returned string needs to be
201 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
202 call after use.</para>
204 <para><function>sd_session_get_tty()</function>
205 may be used to determine the TTY device of the
206 session identified by the specified session
207 identifier. The returned string needs to be
209 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
210 call after use.</para>
212 <para><function>sd_session_get_vt()</function>
213 may be used to determine the VT number of the
214 session identified by the specified session
215 identifier. This function will return an error if
216 the seat does not support VTs.</para>
218 <para>If the <varname>session</varname> parameter of
219 any of these functions is passed as
220 <constant>NULL</constant>, the operation is executed
221 for the session the calling process is a member of, if
226 <title>Return Value</title>
228 <para>If the test succeeds,
229 <function>sd_session_is_active()</function> returns a
230 positive integer, if it fails 0. On success
231 <function>sd_session_get_state()</function>,
232 <function>sd_session_get_uid()</function>,
233 <function>sd_session_get_seat()</function>,
234 <function>sd_session_get_service()</function>,
235 <function>sd_session_get_type()</function>,
236 <function>sd_session_get_class()</function>,
237 <function>sd_session_get_display()</function> and
238 <function>sd_session_get_tty()</function> return 0 or
239 a positive integer. On failure, these calls return a
240 negative errno-style error code.</para>
246 <para>The <function>sd_session_is_active()</function>,
247 <function>sd_session_get_state()</function>,
248 <function>sd_session_get_uid()</function>,
249 <function>sd_session_get_seat()</function>,
250 <function>sd_session_get_service()</function>,
251 <function>sd_session_get_type()</function>,
252 <function>sd_session_get_class()</function>,
253 <function>sd_session_get_display()</function> and
254 <function>sd_session_get_tty()</function>
255 interfaces are available as shared library, which can
256 be compiled and linked to with the
257 <constant>libsystemd-login</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
262 <title>See Also</title>
265 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
266 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
267 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>