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">
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 <refpurpose>Determine state of a specific session</refpurpose>
59 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
62 <funcdef>int <function>sd_session_is_active</function></funcdef>
63 <paramdef>const char* <parameter>session</parameter></paramdef>
67 <funcdef>int <function>sd_session_get_state</function></funcdef>
68 <paramdef>const char* <parameter>session</parameter></paramdef>
69 <paramdef>char** <parameter>state</parameter></paramdef>
73 <funcdef>int <function>sd_session_get_uid</function></funcdef>
74 <paramdef>const char* <parameter>session</parameter></paramdef>
75 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
79 <funcdef>int <function>sd_session_get_seat</function></funcdef>
80 <paramdef>const char* <parameter>session</parameter></paramdef>
81 <paramdef>char** <parameter>seat</parameter></paramdef>
85 <funcdef>int <function>sd_session_get_service</function></funcdef>
86 <paramdef>const char* <parameter>session</parameter></paramdef>
87 <paramdef>char** <parameter>service</parameter></paramdef>
91 <funcdef>int <function>sd_session_get_type</function></funcdef>
92 <paramdef>const char* <parameter>session</parameter></paramdef>
93 <paramdef>char** <parameter>type</parameter></paramdef>
97 <funcdef>int <function>sd_session_get_class</function></funcdef>
98 <paramdef>const char* <parameter>session</parameter></paramdef>
99 <paramdef>char** <parameter>class</parameter></paramdef>
103 <funcdef>int <function>sd_session_get_display</function></funcdef>
104 <paramdef>const char* <parameter>session</parameter></paramdef>
105 <paramdef>char** <parameter>display</parameter></paramdef>
111 <title>Description</title>
113 <para><function>sd_session_is_active()</function> may
114 be used to determine whether the session identified by
115 the specified session identifier is currently active
116 (i.e. currently in the foreground and available for
117 user input) or not.</para>
119 <para><function>sd_session_get_state()</function> may
120 be used to determine the state of the session
121 identified by the specified session identifier. The
122 following states are currently known:
123 <literal>online</literal> (session logged in, but
124 session not active, i.e. not in the foreground),
125 <literal>active</literal> (session logged in and
126 active, i.e. in the foreground),
127 <literal>closing</literal> (session nominally logged
128 out, but some processes belonging to it are still
129 around). In the future additional states might be
130 defined, client code should be written to be robust in
131 regards to additional state strings being
132 returned. This function is a more generic version of
133 <function>sd_session_is_active()</function>. The returned
134 string needs to be freed with the libc
135 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
136 call after use.</para>
138 <para><function>sd_session_get_uid()</function> may be
139 used to determine the user identifier of the Unix user the session
140 identified by the specified session identifier belongs
143 <para><function>sd_session_get_seat()</function> may
144 be used to determine the seat identifier of the seat
145 the session identified by the specified session
146 identifier belongs to. Note that not all sessions are
147 attached to a seat, this call will fail for them. The
148 returned 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_service()</function>
153 may be used to determine the name of the service (as
154 passed during PAM session setup) that registered the
155 session identified by the specified session
156 identifier. The returned string needs to be freed with
158 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
159 call after use.</para>
161 <para><function>sd_session_get_type()</function> may
162 be used to determine the type of the session
163 identified by the specified session identifier. The
164 returned string is one of <literal>x11</literal>,
165 <literal>tty</literal> or
166 <literal>unspecified</literal> and needs to be freed
168 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
169 call after use.</para>
171 <para><function>sd_session_get_class()</function> may
172 be used to determine the class of the session
173 identified by the specified session identifier. The
174 returned string is one of <literal>user</literal>,
175 <literal>greeter</literal> or
176 <literal>lock-screen</literal> and needs to be freed
178 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
179 call after use.</para>
181 <para><function>sd_session_get_display()</function>
182 may be used to determine the X11 display of the
183 session identified by the specified session
184 identifier. The returned string is one of needs to be
186 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
187 call after use.</para>
189 <para>If the <literal>session</literal> parameter of
190 any of these functions is passed as NULL the operation
191 is executed for the session the calling process is a
192 member of, if there is any.</para>
196 <title>Return Value</title>
198 <para>If the test succeeds
199 <function>sd_session_is_active()</function> returns a
200 positive integer, if it fails 0. On success
201 <function>sd_session_get_state()</function>,
202 <function>sd_session_get_uid()</function>,
203 <function>sd_session_get_seat()</function>,
204 <function>sd_session_get_service()</function>,
205 <function>sd_session_get_type()</function>,
206 <function>sd_session_get_class()</function> and
207 <function>sd_session_get_display()</function> return 0 or
208 a positive integer. On failure, these calls return a
209 negative errno-style error code.</para>
215 <para>The <function>sd_session_is_active()</function>,
216 <function>sd_session_get_state()</function>,
217 <function>sd_session_get_uid()</function>,
218 <function>sd_session_get_seat()</function>,
219 <function>sd_session_get_service()</function>,
220 <function>sd_session_get_type()</function>,
221 <function>sd_session_get_class()</function> and
222 <function>sd_session_get_display()</function> interfaces
223 are available as shared library, which can be compiled
224 and linked to with the
225 <literal>libsystemd-login</literal>
226 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
231 <title>See Also</title>
234 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
235 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
236 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>