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 General Public License as published by
12 the Free Software Foundation; either version 2 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 General Public License for more details.
20 You should have received a copy of the GNU 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_uid</refname>
48 <refname>sd_session_get_seat</refname>
49 <refname>sd_session_get_service</refname>
50 <refname>sd_session_get_type</refname>
51 <refname>sd_session_get_class</refname>
52 <refname>sd_session_get_display</refname>
53 <refpurpose>Determine state of a specific session</refpurpose>
58 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
61 <funcdef>int <function>sd_session_is_active</function></funcdef>
62 <paramdef>const char* <parameter>session</parameter></paramdef>
66 <funcdef>int <function>sd_session_get_uid</function></funcdef>
67 <paramdef>const char* <parameter>session</parameter></paramdef>
68 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
72 <funcdef>int <function>sd_session_get_seat</function></funcdef>
73 <paramdef>const char* <parameter>session</parameter></paramdef>
74 <paramdef>char** <parameter>seat</parameter></paramdef>
78 <funcdef>int <function>sd_session_get_service</function></funcdef>
79 <paramdef>const char* <parameter>session</parameter></paramdef>
80 <paramdef>char** <parameter>service</parameter></paramdef>
84 <funcdef>int <function>sd_session_get_type</function></funcdef>
85 <paramdef>const char* <parameter>session</parameter></paramdef>
86 <paramdef>char** <parameter>type</parameter></paramdef>
90 <funcdef>int <function>sd_session_get_class</function></funcdef>
91 <paramdef>const char* <parameter>session</parameter></paramdef>
92 <paramdef>char** <parameter>class</parameter></paramdef>
96 <funcdef>int <function>sd_session_get_display</function></funcdef>
97 <paramdef>const char* <parameter>session</parameter></paramdef>
98 <paramdef>char** <parameter>display</parameter></paramdef>
104 <title>Description</title>
106 <para><function>sd_session_is_active()</function> may
107 be used to determine whether the session identified by
108 the specified session identifier is currently active
109 (i.e. currently in the foreground and available for
110 user input) or not.</para>
112 <para><function>sd_session_get_uid()</function> may be
113 used to determine the user identifier of the Unix user the session
114 identified by the specified session identifier belongs
117 <para><function>sd_session_get_seat()</function> may
118 be used to determine the seat identifier of the seat
119 the session identified by the specified session
120 identifier belongs to. Note that not all sessions are
121 attached to a seat, this call will fail for them. The
122 returned string needs to be freed with the libc
123 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
124 call after use.</para>
126 <para><function>sd_session_get_service()</function>
127 may be used to determine the name of the service (as
128 passed during PAM session setup) that registered the
129 session identified by the specified session
130 identifier. The returned string needs to be freed with
132 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
133 call after use.</para>
135 <para><function>sd_session_get_type()</function> may
136 be used to determine the type of the session
137 identified by the specified session identifier. The
138 returned string is one of <literal>x11</literal>,
139 <literal>tty</literal> or
140 <literal>unspecified</literal> and needs to be freed
142 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
143 call after use.</para>
145 <para><function>sd_session_get_class()</function> may
146 be used to determine the class of the session
147 identified by the specified session identifier. The
148 returned string is one of <literal>user</literal>,
149 <literal>greeter</literal> or
150 <literal>lock-screen</literal> and needs to be freed
152 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
153 call after use.</para>
155 <para><function>sd_session_get_display()</function>
156 may be used to determine the X11 display of the
157 session identified by the specified session
158 identifier. The returned string is one of needs to be
160 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
161 call after use.</para>
163 <para>If the <literal>session</literal> parameter of
164 any of these functions is passed as NULL the operation
165 is executed for the session the calling process is a
166 member of, if there is any.</para>
170 <title>Return Value</title>
172 <para>If the test succeeds
173 <function>sd_session_is_active()</function> returns a
174 positive integer, if it fails 0. On success
175 <function>sd_session_get_uid()</function>,
176 <function>sd_session_get_service()</function> and
177 <function>sd_session_get_seat()</function> return 0 or
178 a positive integer. On failure, these calls return a
179 negative errno-style error code.</para>
185 <para>The <function>sd_session_is_active()</function>,
186 <function>sd_session_get_uid()</function>,
187 <function>sd_session_get_service()</function> and
188 <function>sd_session_get_seat()</function> interfaces
189 are available as shared library, which can be compiled
190 and linked to with the
191 <literal>libsystemd-login</literal>
192 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
197 <title>See Also</title>
200 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
201 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
202 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>