1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_login_monitor_new</title><meta name="generator" content="DocBook XSL Stylesheets V1.77.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><a href="index.html">Index </a>·
2
<a href="systemd.directives.html">Directives </a>·
3
<a href="../python-systemd/index.html">Python </a>·
4
<a href="../libudev/index.html">libudev </a>·
5
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 202</span><hr><div class="refentry"><a name="sd_login_monitor_new"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_login_monitor_new, sd_login_monitor_unref, sd_login_monitor_flush, sd_login_monitor_get_fd, sd_login_monitor_get_events, sd_login_monitor_get_timeout, sd_login_monitor — Monitor login sessions, seats and users</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <systemd/sd-login.h></pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_login_monitor_new</b>(</code></td><td>const char* <var class="pdparam">category</var>, </td></tr><tr><td> </td><td>sd_login_monitor** <var class="pdparam">ret</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">sd_login_monitor* <b class="fsfunc">sd_login_monitor_unref</b>(</code></td><td>sd_login_monitor* <var class="pdparam">m</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_login_monitor_flush</b>(</code></td><td>sd_login_monitor* <var class="pdparam">m</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_login_monitor_get_fd</b>(</code></td><td>sd_login_monitor* <var class="pdparam">m</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_login_monitor_get_events</b>(</code></td><td>sd_login_monitor* <var class="pdparam">m</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_login_monitor_get_timeout</b>(</code></td><td>sd_login_monitor* <var class="pdparam">m</var>, </td></tr><tr><td> </td><td>uint64_t* <var class="pdparam">timeout_usec</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp193168"></a><h2>Description</h2><p><code class="function">sd_login_monitor_new()</code> may
6
be used to monitor login sessions, users and seats. Via
7
a monitor object a file descriptor can be integrated
8
into an application defined event loop which is woken
9
up each time a user logs in, logs out or a seat is
10
added or removed, or a session, user, or seat changes
11
state otherwise. The first parameter takes a string
12
which can be <code class="literal">seat</code> (to get
13
only notifications about seats being added, removed or
14
changed), <code class="literal">session</code> (to get only
15
notifications about sessions being created or removed
16
or changed) or <code class="literal">uid</code> (to get only
17
notifications when a user changes state in respect to
18
logins). If notifications shall be generated in all
19
these conditions, NULL may be passed. Note that in the
20
future additional categories may be defined. The
21
second parameter returns a monitor object and needs to
23
<code class="function">sd_login_monitor_unref()</code> call
24
after use.</p><p><code class="function">sd_login_monitor_unref()</code>
25
may be used to destroy a monitor object. Note that
26
this will invalidate any file descriptor returned by
27
<code class="function">sd_login_monitor_get_fd()</code>.</p><p><code class="function">sd_login_monitor_flush()</code>
28
may be used to reset the wakeup state of the monitor
29
object. Whenever an event causes the monitor to wake
30
up the event loop via the file descriptor this
31
function needs to be called to reset the wake-up
32
state. If this call is not invoked the file descriptor
33
will immediately wake up the event loop again.</p><p><code class="function">sd_login_monitor_get_fd()</code>
34
may be used to retrieve the file descriptor of the
35
monitor object that may be integrated in an
36
application defined event loop, based around
37
<a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>
38
or a similar interface. The application should include
39
the returned file descriptor as wake-up source for the
40
events mask returned by
41
<code class="function">sd_login_monitor_get_events()</code>. It
42
should pass a timeout value as returned by
43
<code class="function">sd_login_monitor_get_timeout()</code>. Whenever
44
a wake-up is triggered the file descriptor needs to be
46
<code class="function">sd_login_monitor_flush()</code>. An
47
application needs to reread the login state with a
49
<a href="sd_get_seats.html"><span class="citerefentry"><span class="refentrytitle">sd_get_seats</span>(3)</span></a>
50
or similar to determine what changed.</p><p><code class="function">sd_login_monitor_get_events()</code>
51
will return the <code class="function">poll()</code> mask to
52
wait for. This function will return a combination of
53
<code class="literal">POLLIN</code>, <code class="literal">POLLOUT</code>
54
and similar to fill into the
55
<code class="literal">.events</code> field of <code class="literal">struct
56
pollfd</code>.</p><p><code class="function">sd_login_monitor_get_timeout()</code>
57
will return a timeout value for usage in
58
<code class="function">poll()</code>. This returns a value in
59
microseconds since the epoch of CLOCK_MONOTONIC for
60
timing out <code class="function">poll()</code> in
61
<code class="literal">timeout_usec</code>. See
62
<a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
64
<code class="literal">CLOCK_MONOTONIC</code>. If there's no
65
timeout to wait for this will fill in
66
<code class="literal">(uint64_t) -1</code> instead. Note that
67
<code class="function">poll()</code> takes a relative timeout
68
in milliseconds rather than an absolute timeout in
69
microseconds. To convert the absolute 'us' timeout into
70
relative 'ms', use code like the following:</p><pre class="programlisting">uint64_t t;
72
sd_login_monitor_get_timeout(m, &t);
73
if (t == (uint64_t) -1)
78
clock_getttime(CLOCK_MONOTONIC, &ts);
79
n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
80
msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
81
}</pre><p>The code above does not do any error checking
82
for brevity's sake. The calculated <code class="literal">msec</code>
83
integer can be passed directly as
84
<code class="function">poll()</code>'s timeout
85
parameter.</p></div><div class="refsect1"><a name="idp54976"></a><h2>Return Value</h2><p>On success
86
<code class="function">sd_login_monitor_new()</code>,
87
<code class="function">sd_login_monitor_flush()</code> and
88
<code class="function">sd_login_monitor_get_timeout()</code>
89
return 0 or a positive integer. On success
90
<code class="function">sd_login_monitor_get_fd()</code> returns
91
a Unix file descriptor. On success
92
<code class="function">sd_login_monitor_get_events()</code>
93
returns a combination of <code class="literal">POLLIN</code>,
94
<code class="literal">POLLOUT</code> and suchlike. On failure,
95
these calls return a negative errno-style error
96
code.</p><p><code class="function">sd_login_monitor_unref()</code>
97
always returns NULL.</p></div><div class="refsect1"><a name="idp62416"></a><h2>Notes</h2><p>The <code class="function">sd_login_monitor_new()</code>,
98
<code class="function">sd_login_monitor_unref()</code>,
99
<code class="function">sd_login_monitor_flush()</code>,
100
<code class="function">sd_login_monitor_get_fd()</code>,
101
<code class="function">sd_login_monitor_get_events()</code> and
102
<code class="function">sd_login_monitor_get_timeout()</code>
103
interfaces are available as shared library, which can
104
be compiled and linked to with the
105
<code class="literal">libsystemd-login</code>
106
<a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
107
file.</p></div><div class="refsect1"><a name="idp69728"></a><h2>See Also</h2><p>
108
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
109
<a href="sd-login.html"><span class="citerefentry"><span class="refentrytitle">sd-login</span>(3)</span></a>,
110
<a href="sd_get_seats.html"><span class="citerefentry"><span class="refentrytitle">sd_get_seats</span>(3)</span></a>,
111
<a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,
112
<a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
113
</p></div></div></body></html>