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_login_monitor_new" conditional='HAVE_PAM'
10 xmlns:xi="http://www.w3.org/2001/XInclude">
13 <title>sd_login_monitor_new</title>
14 <productname>systemd</productname>
18 <contrib>Developer</contrib>
19 <firstname>Lennart</firstname>
20 <surname>Poettering</surname>
21 <email>lennart@poettering.net</email>
27 <refentrytitle>sd_login_monitor_new</refentrytitle>
28 <manvolnum>3</manvolnum>
32 <refname>sd_login_monitor_new</refname>
33 <refname>sd_login_monitor_unref</refname>
34 <refname>sd_login_monitor_unrefp</refname>
35 <refname>sd_login_monitor_flush</refname>
36 <refname>sd_login_monitor_get_fd</refname>
37 <refname>sd_login_monitor_get_events</refname>
38 <refname>sd_login_monitor_get_timeout</refname>
39 <refname>sd_login_monitor</refname>
40 <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose>
45 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
48 <funcdef>int <function>sd_login_monitor_new</function></funcdef>
49 <paramdef>const char *<parameter>category</parameter></paramdef>
50 <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef>
54 <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef>
55 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
59 <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef>
60 <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef>
64 <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
65 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
69 <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
70 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
74 <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
75 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
79 <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef>
80 <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
81 <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
88 <title>Description</title>
90 <para><function>sd_login_monitor_new()</function> may be used to
91 monitor login sessions, users, seats, and virtual
92 machines/containers. Via a monitor object a file descriptor can be
93 integrated into an application defined event loop which is woken
94 up each time a user logs in, logs out or a seat is added or
95 removed, or a session, user, seat or virtual machine/container
96 changes state otherwise. The first parameter takes a string which
97 can be <literal>seat</literal> (to get only notifications about
98 seats being added, removed or changed), <literal>session</literal>
99 (to get only notifications about sessions being created or removed
100 or changed), <literal>uid</literal> (to get only notifications
101 when a user changes state in respect to logins) or
102 <literal>machine</literal> (to get only notifications when a
103 virtual machine or container is started or stopped). If
104 notifications shall be generated in all these conditions,
105 <constant>NULL</constant> may be passed. Note that in the future
106 additional categories may be defined. The second parameter returns
107 a monitor object and needs to be freed with the
108 <function>sd_login_monitor_unref()</function> call after
111 <para><function>sd_login_monitor_unref()</function> may be used to
112 destroy a monitor object. Note that this will invalidate any file
113 descriptor returned by
114 <function>sd_login_monitor_get_fd()</function>.</para>
116 <para><function>sd_login_monitor_unrefp()</function> is similar to
117 <function>sd_login_monitor_unref()</function> but takes a pointer
118 to a pointer to an <type>sd_login_monitor</type> object. This call
119 is useful in conjunction with GCC's and LLVM's <ulink
120 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
121 Variable Attribute</ulink>. Note that this function is defined as
122 inline function. Use a declaration like the following, in order to
123 allocate a login monitor object that is freed automatically as the
124 code block is left:</para>
127 __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
130 r = sd_login_monitor_default(&m);
132 fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
136 <para><function>sd_login_monitor_flush()</function> may be used to
137 reset the wakeup state of the monitor object. Whenever an event
138 causes the monitor to wake up the event loop via the file
139 descriptor this function needs to be called to reset the wake-up
140 state. If this call is not invoked, the file descriptor will
141 immediately wake up the event loop again.</para>
143 <para><function>sd_login_monitor_unref()</function> and
144 <function>sd_login_monitor_unrefp()</function> execute no
145 operation if the passed in monitor object is
146 <constant>NULL</constant>.</para>
148 <para><function>sd_login_monitor_get_fd()</function> may be used
149 to retrieve the file descriptor of the monitor object that may be
150 integrated in an application defined event loop, based around
151 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
152 or a similar interface. The application should include the
153 returned file descriptor as wake-up source for the events mask
154 returned by <function>sd_login_monitor_get_events()</function>. It
155 should pass a timeout value as returned by
156 <function>sd_login_monitor_get_timeout()</function>. Whenever a
157 wake-up is triggered the file descriptor needs to be reset via
158 <function>sd_login_monitor_flush()</function>. An application
159 needs to reread the login state with a function like
160 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
161 or similar to determine what changed.</para>
163 <para><function>sd_login_monitor_get_events()</function> will
164 return the <function>poll()</function> mask to wait for. This
165 function will return a combination of <constant>POLLIN</constant>,
166 <constant>POLLOUT</constant> and similar to fill into the
167 <literal>.events</literal> field of <varname>struct
168 pollfd</varname>.</para>
170 <para><function>sd_login_monitor_get_timeout()</function> will
171 return a timeout value for usage in <function>poll()</function>.
172 This returns a value in microseconds since the epoch of
173 <constant>CLOCK_MONOTONIC</constant> for timing out
174 <function>poll()</function> in <varname>timeout_usec</varname>.
176 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
177 for details about <constant>CLOCK_MONOTONIC</constant>. If there
178 is no timeout to wait for this will fill in <constant>(uint64_t)
179 -1</constant> instead. Note that <function>poll()</function> takes
180 a relative timeout in milliseconds rather than an absolute timeout
181 in microseconds. To convert the absolute 'µs' timeout into
182 relative 'ms', use code like the following:</para>
184 <programlisting>uint64_t t;
186 sd_login_monitor_get_timeout(m, &t);
187 if (t == (uint64_t) -1)
192 clock_gettime(CLOCK_MONOTONIC, &ts);
193 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
194 msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
197 <para>The code above does not do any error checking for brevity's
198 sake. The calculated <varname>msec</varname> integer can be passed
199 directly as <function>poll()</function>'s timeout
204 <title>Return Value</title>
207 <function>sd_login_monitor_new()</function>,
208 <function>sd_login_monitor_flush()</function> and
209 <function>sd_login_monitor_get_timeout()</function>
210 return 0 or a positive integer. On success,
211 <function>sd_login_monitor_get_fd()</function> returns
212 a Unix file descriptor. On success,
213 <function>sd_login_monitor_get_events()</function>
214 returns a combination of <constant>POLLIN</constant>,
215 <constant>POLLOUT</constant> and suchlike. On failure,
216 these calls return a negative errno-style error
219 <para><function>sd_login_monitor_unref()</function>
220 always returns <constant>NULL</constant>.</para>
224 <title>Errors</title>
226 <para>Returned errors may indicate the following problems:</para>
231 <term><constant>-EINVAL</constant></term>
233 <listitem><para>An input parameter was invalid (out of range,
234 or NULL, where that is not accepted). The specified category to
235 watch is not known.</para></listitem>
239 <term><constant>-ENOMEM</constant></term>
241 <listitem><para>Memory allocation failed.</para></listitem>
246 <xi:include href="libelogind-pkgconfig.xml" />
249 <title>See Also</title>
252 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
253 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
254 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
255 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
256 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>