1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<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.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
visibility: hidden;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
visibility: visible;
}
</style><a href="index.html">Index </a>·
<a href="systemd.directives.html">Directives </a>·
<a href="../python-systemd/index.html">Python </a>·
<a href="../libudev/index.html">libudev </a>·
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</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, users and virtual machines/containers</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="idm214197895280"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_login_monitor_new()</code> may
be used to monitor login sessions, users, seats, and
virtual machines/containers. Via a monitor object a
file descriptor can be integrated into an application
defined event loop which is woken up each time a user
logs in, logs out or a seat is added or removed, or a
session, user, seat or virtual machine/container
changes state otherwise. The first parameter takes a
string which can be "<code class="literal">seat</code>" (to get
only notifications about seats being added, removed or
changed), "<code class="literal">session</code>" (to get only
notifications about sessions being created or removed
or changed), "<code class="literal">uid</code>" (to get only
notifications when a user changes state in respect to
logins) or "<code class="literal">machine</code>" (to get only
notifications when a virtual machine or container is
started or stopped). If notifications shall be
generated in all these conditions, <code class="constant">NULL</code> may be
passed. Note that in the future additional categories
may be defined. The second parameter returns a monitor
object and needs to be freed with the
<code class="function">sd_login_monitor_unref()</code> call
after use.</p><p><code class="function">sd_login_monitor_unref()</code>
may be used to destroy a monitor object. Note that
this will invalidate any file descriptor returned by
<code class="function">sd_login_monitor_get_fd()</code>.</p><p><code class="function">sd_login_monitor_flush()</code>
may be used to reset the wakeup state of the monitor
object. Whenever an event causes the monitor to wake
up the event loop via the file descriptor this
function needs to be called to reset the wake-up
state. If this call is not invoked, the file descriptor
will immediately wake up the event loop again.</p><p><code class="function">sd_login_monitor_get_fd()</code>
may be used to retrieve the file descriptor of the
monitor object that may be integrated in an
application defined event loop, based around
<a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>
or a similar interface. The application should include
the returned file descriptor as wake-up source for the
events mask returned by
<code class="function">sd_login_monitor_get_events()</code>. It
should pass a timeout value as returned by
<code class="function">sd_login_monitor_get_timeout()</code>. Whenever
a wake-up is triggered the file descriptor needs to be
reset via
<code class="function">sd_login_monitor_flush()</code>. An
application needs to reread the login state with a
function like
<a href="sd_get_seats.html"><span class="citerefentry"><span class="refentrytitle">sd_get_seats</span>(3)</span></a>
or similar to determine what changed.</p><p><code class="function">sd_login_monitor_get_events()</code>
will return the <code class="function">poll()</code> mask to
wait for. This function will return a combination of
<code class="constant">POLLIN</code>, <code class="constant">POLLOUT</code>
and similar to fill into the
"<code class="literal">.events</code>" field of <code class="varname">struct
pollfd</code>.</p><p><code class="function">sd_login_monitor_get_timeout()</code>
will return a timeout value for usage in
<code class="function">poll()</code>. This returns a value in
microseconds since the epoch of <code class="constant">CLOCK_MONOTONIC</code>
for timing out <code class="function">poll()</code> in
<code class="varname">timeout_usec</code>. See
<a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
for details about
<code class="constant">CLOCK_MONOTONIC</code>. If there is no
timeout to wait for this will fill in
<code class="constant">(uint64_t) -1</code> instead. Note that
<code class="function">poll()</code> takes a relative timeout
in milliseconds rather than an absolute timeout in
microseconds. To convert the absolute 'us' timeout into
relative 'ms', use code like the following:</p><pre class="programlisting">uint64_t t;
int msec;
sd_login_monitor_get_timeout(m, &t);
if (t == (uint64_t) -1)
msec = -1;
else {
struct timespec ts;
uint64_t n;
clock_getttime(CLOCK_MONOTONIC, &ts);
n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
}</pre><p>The code above does not do any error checking
for brevity's sake. The calculated <code class="varname">msec</code>
integer can be passed directly as
<code class="function">poll()</code>'s timeout
parameter.</p></div><div class="refsect1"><a name="idm214197859856"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>On success,
<code class="function">sd_login_monitor_new()</code>,
<code class="function">sd_login_monitor_flush()</code> and
<code class="function">sd_login_monitor_get_timeout()</code>
return 0 or a positive integer. On success,
<code class="function">sd_login_monitor_get_fd()</code> returns
a Unix file descriptor. On success,
<code class="function">sd_login_monitor_get_events()</code>
returns a combination of <code class="constant">POLLIN</code>,
<code class="constant">POLLOUT</code> and suchlike. On failure,
these calls return a negative errno-style error
code.</p><p><code class="function">sd_login_monitor_unref()</code>
always returns <code class="constant">NULL</code>.</p></div><div class="refsect1"><a name="idm214197852544"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>The <code class="function">sd_login_monitor_new()</code>,
<code class="function">sd_login_monitor_unref()</code>,
<code class="function">sd_login_monitor_flush()</code>,
<code class="function">sd_login_monitor_get_fd()</code>,
<code class="function">sd_login_monitor_get_events()</code> and
<code class="function">sd_login_monitor_get_timeout()</code>
interfaces are available as a shared library, which can
be compiled and linked to with the
<code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
file.</p></div><div class="refsect1"><a name="idm214192935712"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
<a href="sd-login.html"><span class="citerefentry"><span class="refentrytitle">sd-login</span>(3)</span></a>,
<a href="sd_get_seats.html"><span class="citerefentry"><span class="refentrytitle">sd_get_seats</span>(3)</span></a>,
<a href="poll.html"><span class="citerefentry"><span class="refentrytitle">poll</span>(2)</span></a>,
<a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
</p></div></div></body></html>
|
