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