sd_login_monitor.html 12.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<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>·
22
  <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 &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="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
23
                be used to monitor login sessions, users, seats, and
24 25 26 27 28 29
                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
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 38
                notifications when a virtual machine or container is
                started or stopped). If notifications shall be
39
                generated in all these conditions, <code class="constant">NULL</code> may be
40 41 42 43 44 45 46 47 48 49 50 51
                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
52
                state. If this call is not invoked, the file descriptor
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
                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
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 77 78
                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
79 80 81
                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
82 83
                <a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>
                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 88 89 90 91 92 93 94 95 96 97 98 99 100 101
                <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, &amp;t);
if (t == (uint64_t) -1)
        msec = -1;
else {
        struct timespec ts;
        uint64_t n;
        clock_getttime(CLOCK_MONOTONIC, &amp;ts);
        n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
        msec = t &gt; n ? (int) ((t - n + 999) / 1000) : 0;
}</pre><p>The code above does not do any error checking
102
                for brevity's sake. The calculated <code class="varname">msec</code>
103 104
                integer can be passed directly as
                <code class="function">poll()</code>'s timeout
105
                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,
106 107 108
                <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>
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 114
                returns a combination of <code class="constant">POLLIN</code>,
                <code class="constant">POLLOUT</code> and suchlike. On failure,
115 116
                these calls return a negative errno-style error
                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="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>,
118 119 120 121 122
                <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>
123
                interfaces are available as a shared library, which can
124
                be compiled and linked to with the
125
                <code class="constant">libsystemd</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="idm214192935712"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
127 128 129 130 131 132
                        <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>