~ubuntu-branches/ubuntu/trusty/systemd/trusty

<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>·

<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 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

be used to monitor login sessions, users and seats. 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, or seat 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) or <code class="literal">uid</code> (to get only

notifications when a user changes state in respect to

logins). If notifications shall be generated in all

these conditions, NULL 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

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="literal">POLLIN</code>, <code class="literal">POLLOUT</code>

and similar to fill into the

<code class="literal">.events</code> field of <code class="literal">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 CLOCK_MONOTONIC for

timing out <code class="function">poll()</code> in

<code class="literal">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="literal">CLOCK_MONOTONIC</code>. If there's no

timeout to wait for this will fill in

<code class="literal">(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="literal">msec</code>

integer can be passed directly as

<code class="function">poll()</code>'s timeout

parameter.</p></div><div class="refsect1"><a name="idp54976"></a><h2>Return Value</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="literal">POLLIN</code>,

<code class="literal">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 NULL.</p></div><div class="refsect1"><a name="idp62416"></a><h2>Notes</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>,

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>

Older »