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" [
4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2010 Lennart Poettering
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id="sd_login_monitor_new" conditional='HAVE_PAM'>
30 <title>sd_login_monitor_new</title>
31 <productname>systemd</productname>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
44 <refentrytitle>sd_login_monitor_new</refentrytitle>
45 <manvolnum>3</manvolnum>
49 <refname>sd_login_monitor_new</refname>
50 <refname>sd_login_monitor_unref</refname>
51 <refname>sd_login_monitor_flush</refname>
52 <refname>sd_login_monitor_get_fd</refname>
53 <refname>sd_login_monitor_get_events</refname>
54 <refname>sd_login_monitor_get_timeout</refname>
55 <refname>sd_login_monitor</refname>
56 <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose>
61 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
64 <funcdef>int <function>sd_login_monitor_new</function></funcdef>
65 <paramdef>const char *<parameter>category</parameter></paramdef>
66 <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef>
70 <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef>
71 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
75 <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
76 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
80 <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
81 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
85 <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
86 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
90 <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef>
91 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
92 <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
99 <title>Description</title>
101 <para><function>sd_login_monitor_new()</function> may be used to
102 monitor login sessions, users, seats, and virtual
103 machines/containers. Via a monitor object a file descriptor can be
104 integrated into an application defined event loop which is woken
105 up each time a user logs in, logs out or a seat is added or
106 removed, or a session, user, seat or virtual machine/container
107 changes state otherwise. The first parameter takes a string which
108 can be <literal>seat</literal> (to get only notifications about
109 seats being added, removed or changed), <literal>session</literal>
110 (to get only notifications about sessions being created or removed
111 or changed), <literal>uid</literal> (to get only notifications
112 when a user changes state in respect to logins) or
113 <literal>machine</literal> (to get only notifications when a
114 virtual machine or container is started or stopped). If
115 notifications shall be generated in all these conditions,
116 <constant>NULL</constant> may be passed. Note that in the future
117 additional categories may be defined. The second parameter returns
118 a monitor object and needs to be freed with the
119 <function>sd_login_monitor_unref()</function> call after
122 <para><function>sd_login_monitor_unref()</function> may be used to
123 destroy a monitor object. Note that this will invalidate any file
124 descriptor returned by
125 <function>sd_login_monitor_get_fd()</function>.</para>
127 <para><function>sd_login_monitor_flush()</function> may be used to
128 reset the wakeup state of the monitor object. Whenever an event
129 causes the monitor to wake up the event loop via the file
130 descriptor this function needs to be called to reset the wake-up
131 state. If this call is not invoked, the file descriptor will
132 immediately wake up the event loop again.</para>
134 <para><function>sd_login_monitor_get_fd()</function> may be used
135 to retrieve the file descriptor of the monitor object that may be
136 integrated in an application defined event loop, based around
137 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
138 or a similar interface. The application should include the
139 returned file descriptor as wake-up source for the events mask
140 returned by <function>sd_login_monitor_get_events()</function>. It
141 should pass a timeout value as returned by
142 <function>sd_login_monitor_get_timeout()</function>. Whenever a
143 wake-up is triggered the file descriptor needs to be reset via
144 <function>sd_login_monitor_flush()</function>. An application
145 needs to reread the login state with a function like
146 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
147 or similar to determine what changed.</para>
149 <para><function>sd_login_monitor_get_events()</function> will
150 return the <function>poll()</function> mask to wait for. This
151 function will return a combination of <constant>POLLIN</constant>,
152 <constant>POLLOUT</constant> and similar to fill into the
153 <literal>.events</literal> field of <varname>struct
154 pollfd</varname>.</para>
156 <para><function>sd_login_monitor_get_timeout()</function> will
157 return a timeout value for usage in <function>poll()</function>.
158 This returns a value in microseconds since the epoch of
159 <constant>CLOCK_MONOTONIC</constant> for timing out
160 <function>poll()</function> in <varname>timeout_usec</varname>.
162 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
163 for details about <constant>CLOCK_MONOTONIC</constant>. If there
164 is no timeout to wait for this will fill in <constant>(uint64_t)
165 -1</constant> instead. Note that <function>poll()</function> takes
166 a relative timeout in milliseconds rather than an absolute timeout
167 in microseconds. To convert the absolute 'us' timeout into
168 relative 'ms', use code like the following:</para>
170 <programlisting>uint64_t t;
172 sd_login_monitor_get_timeout(m, &t);
173 if (t == (uint64_t) -1)
178 clock_getttime(CLOCK_MONOTONIC, &ts);
179 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
180 msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
183 <para>The code above does not do any error checking for brevity's
184 sake. The calculated <varname>msec</varname> integer can be passed
185 directly as <function>poll()</function>'s timeout
190 <title>Return Value</title>
193 <function>sd_login_monitor_new()</function>,
194 <function>sd_login_monitor_flush()</function> and
195 <function>sd_login_monitor_get_timeout()</function>
196 return 0 or a positive integer. On success,
197 <function>sd_login_monitor_get_fd()</function> returns
198 a Unix file descriptor. On success,
199 <function>sd_login_monitor_get_events()</function>
200 returns a combination of <constant>POLLIN</constant>,
201 <constant>POLLOUT</constant> and suchlike. On failure,
202 these calls return a negative errno-style error
205 <para><function>sd_login_monitor_unref()</function>
206 always returns <constant>NULL</constant>.</para>
212 <para>The <function>sd_login_monitor_new()</function>,
213 <function>sd_login_monitor_unref()</function>,
214 <function>sd_login_monitor_flush()</function>,
215 <function>sd_login_monitor_get_fd()</function>,
216 <function>sd_login_monitor_get_events()</function> and
217 <function>sd_login_monitor_get_timeout()</function>
218 interfaces are available as a shared library, which can be
219 compiled and linked to with the
220 <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
225 <title>See Also</title>
228 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
229 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
230 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
231 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
232 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>