man/sd_login_monitor_new.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2010 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_login_monitor_new" conditional='HAVE_PAM'>
  28
  29   <refentryinfo>
  30     <title>sd_login_monitor_new</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_login_monitor_new</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_login_monitor_new</refname>
  50     <refname>sd_login_monitor_unref</refname>
  51     <refname>sd_login_monitor_flush</refname>
  52     <refname>sd_login_monitor_get_fd</refname>
  53     <refname>sd_login_monitor_get_events</refname>
  54     <refname>sd_login_monitor_get_timeout</refname>
  55     <refname>sd_login_monitor</refname>
  56     <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose>
  57   </refnamediv>
  58
  59   <refsynopsisdiv>
  60     <funcsynopsis>
  61       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_login_monitor_new</function></funcdef>
  65         <paramdef>const char *<parameter>category</parameter></paramdef>
  66         <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef>
  67       </funcprototype>
  68
  69       <funcprototype>
  70         <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef>
  71         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
  76         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
  81         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  82       </funcprototype>
  83
  84       <funcprototype>
  85         <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
  86         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef>
  91         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  92         <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
  93       </funcprototype>
  94
  95     </funcsynopsis>
  96   </refsynopsisdiv>
  97
  98   <refsect1>
  99     <title>Description</title>
 100
 101     <para><function>sd_login_monitor_new()</function> may be used to
 102     monitor login sessions, users, seats, and virtual
 103     machines/containers. Via a monitor object a file descriptor can be
 104     integrated into an application defined event loop which is woken
 105     up each time a user logs in, logs out or a seat is added or
 106     removed, or a session, user, seat or virtual machine/container
 107     changes state otherwise. The first parameter takes a string which
 108     can be <literal>seat</literal> (to get only notifications about
 109     seats being added, removed or changed), <literal>session</literal>
 110     (to get only notifications about sessions being created or removed
 111     or changed), <literal>uid</literal> (to get only notifications
 112     when a user changes state in respect to logins) or
 113     <literal>machine</literal> (to get only notifications when a
 114     virtual machine or container is started or stopped). If
 115     notifications shall be generated in all these conditions,
 116     <constant>NULL</constant> may be passed. Note that in the future
 117     additional categories may be defined. The second parameter returns
 118     a monitor object and needs to be freed with the
 119     <function>sd_login_monitor_unref()</function> call after
 120     use.</para>
 121
 122     <para><function>sd_login_monitor_unref()</function> may be used to
 123     destroy a monitor object. Note that this will invalidate any file
 124     descriptor returned by
 125     <function>sd_login_monitor_get_fd()</function>.</para>
 126
 127     <para><function>sd_login_monitor_flush()</function> may be used to
 128     reset the wakeup state of the monitor object. Whenever an event
 129     causes the monitor to wake up the event loop via the file
 130     descriptor this function needs to be called to reset the wake-up
 131     state. If this call is not invoked, the file descriptor will
 132     immediately wake up the event loop again.</para>
 133
 134     <para><function>sd_login_monitor_get_fd()</function> may be used
 135     to retrieve the file descriptor of the monitor object that may be
 136     integrated in an application defined event loop, based around
 137     <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 138     or a similar interface. The application should include the
 139     returned file descriptor as wake-up source for the events mask
 140     returned by <function>sd_login_monitor_get_events()</function>. It
 141     should pass a timeout value as returned by
 142     <function>sd_login_monitor_get_timeout()</function>. Whenever a
 143     wake-up is triggered the file descriptor needs to be reset via
 144     <function>sd_login_monitor_flush()</function>. An application
 145     needs to reread the login state with a function like
 146     <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 147     or similar to determine what changed.</para>
 148
 149     <para><function>sd_login_monitor_get_events()</function> will
 150     return the <function>poll()</function> mask to wait for. This
 151     function will return a combination of <constant>POLLIN</constant>,
 152     <constant>POLLOUT</constant> and similar to fill into the
 153     <literal>.events</literal> field of <varname>struct
 154     pollfd</varname>.</para>
 155
 156     <para><function>sd_login_monitor_get_timeout()</function> will
 157     return a timeout value for usage in <function>poll()</function>.
 158     This returns a value in microseconds since the epoch of
 159     <constant>CLOCK_MONOTONIC</constant> for timing out
 160     <function>poll()</function> in <varname>timeout_usec</varname>.
 161     See
 162     <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 163     for details about <constant>CLOCK_MONOTONIC</constant>. If there
 164     is no timeout to wait for this will fill in <constant>(uint64_t)
 165     -1</constant> instead. Note that <function>poll()</function> takes
 166     a relative timeout in milliseconds rather than an absolute timeout
 167     in microseconds. To convert the absolute 'us' timeout into
 168     relative 'ms', use code like the following:</para>
 169
 170     <programlisting>uint64_t t;
 171 int msec;
 172 sd_login_monitor_get_timeout(m, &amp;t);
 173 if (t == (uint64_t) -1)
 174   msec = -1;
 175 else {
 176   struct timespec ts;
 177   uint64_t n;
 178   clock_getttime(CLOCK_MONOTONIC, &amp;ts);
 179   n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
 180   msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 181 }</programlisting>
 182
 183     <para>The code above does not do any error checking for brevity's
 184     sake. The calculated <varname>msec</varname> integer can be passed
 185     directly as <function>poll()</function>'s timeout
 186     parameter.</para>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>Return Value</title>
 191
 192     <para>On success,
 193     <function>sd_login_monitor_new()</function>,
 194     <function>sd_login_monitor_flush()</function> and
 195     <function>sd_login_monitor_get_timeout()</function>
 196     return 0 or a positive integer. On success,
 197     <function>sd_login_monitor_get_fd()</function> returns
 198     a Unix file descriptor. On success,
 199     <function>sd_login_monitor_get_events()</function>
 200     returns a combination of <constant>POLLIN</constant>,
 201     <constant>POLLOUT</constant> and suchlike. On failure,
 202     these calls return a negative errno-style error
 203     code.</para>
 204
 205     <para><function>sd_login_monitor_unref()</function>
 206     always returns <constant>NULL</constant>.</para>
 207   </refsect1>
 208
 209   <refsect1>
 210     <title>Notes</title>
 211
 212     <para>The <function>sd_login_monitor_new()</function>,
 213     <function>sd_login_monitor_unref()</function>,
 214     <function>sd_login_monitor_flush()</function>,
 215     <function>sd_login_monitor_get_fd()</function>,
 216     <function>sd_login_monitor_get_events()</function> and
 217     <function>sd_login_monitor_get_timeout()</function>
 218     interfaces are available as a shared library, which can be
 219     compiled and linked to with the
 220     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 221     file.</para>
 222   </refsect1>
 223
 224   <refsect1>
 225     <title>See Also</title>
 226
 227     <para>
 228       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 229       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 230       <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 231       <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 232       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 233     </para>
 234   </refsect1>
 235
 236 </refentry>