man/sd_login_monitor_get_events.html

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