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
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2010 Lennart Poettering
   9 -->
  10
  11 <refentry id="sd_login_monitor_new" conditional='HAVE_PAM'
  12           xmlns:xi="http://www.w3.org/2001/XInclude">
  13
  14   <refentryinfo>
  15     <title>sd_login_monitor_new</title>
  16     <productname>systemd</productname>
  17
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>Lennart</firstname>
  22         <surname>Poettering</surname>
  23         <email>lennart@poettering.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>sd_login_monitor_new</refentrytitle>
  30     <manvolnum>3</manvolnum>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname>sd_login_monitor_new</refname>
  35     <refname>sd_login_monitor_unref</refname>
  36     <refname>sd_login_monitor_unrefp</refname>
  37     <refname>sd_login_monitor_flush</refname>
  38     <refname>sd_login_monitor_get_fd</refname>
  39     <refname>sd_login_monitor_get_events</refname>
  40     <refname>sd_login_monitor_get_timeout</refname>
  41     <refname>sd_login_monitor</refname>
  42     <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose>
  43   </refnamediv>
  44
  45   <refsynopsisdiv>
  46     <funcsynopsis>
  47       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_login_monitor_new</function></funcdef>
  51         <paramdef>const char *<parameter>category</parameter></paramdef>
  52         <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef>
  57         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef>
  62         <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
  67         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  68       </funcprototype>
  69
  70       <funcprototype>
  71         <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
  72         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  73       </funcprototype>
  74
  75       <funcprototype>
  76         <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
  77         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  78       </funcprototype>
  79
  80       <funcprototype>
  81         <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef>
  82         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
  83         <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
  84       </funcprototype>
  85
  86     </funcsynopsis>
  87   </refsynopsisdiv>
  88
  89   <refsect1>
  90     <title>Description</title>
  91
  92     <para><function>sd_login_monitor_new()</function> may be used to
  93     monitor login sessions, users, seats, and virtual
  94     machines/containers. Via a monitor object a file descriptor can be
  95     integrated into an application defined event loop which is woken
  96     up each time a user logs in, logs out or a seat is added or
  97     removed, or a session, user, seat or virtual machine/container
  98     changes state otherwise. The first parameter takes a string which
  99     can be <literal>seat</literal> (to get only notifications about
 100     seats being added, removed or changed), <literal>session</literal>
 101     (to get only notifications about sessions being created or removed
 102     or changed), <literal>uid</literal> (to get only notifications
 103     when a user changes state in respect to logins) or
 104     <literal>machine</literal> (to get only notifications when a
 105     virtual machine or container is started or stopped). If
 106     notifications shall be generated in all these conditions,
 107     <constant>NULL</constant> may be passed. Note that in the future
 108     additional categories may be defined. The second parameter returns
 109     a monitor object and needs to be freed with the
 110     <function>sd_login_monitor_unref()</function> call after
 111     use.</para>
 112
 113     <para><function>sd_login_monitor_unref()</function> may be used to
 114     destroy a monitor object. Note that this will invalidate any file
 115     descriptor returned by
 116     <function>sd_login_monitor_get_fd()</function>.</para>
 117
 118     <para><function>sd_login_monitor_unrefp()</function> is similar to
 119     <function>sd_login_monitor_unref()</function> but takes a pointer
 120     to a pointer to an <type>sd_login_monitor</type> object. This call
 121     is useful in conjunction with GCC's and LLVM's <ulink
 122     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 123     Variable Attribute</ulink>. Note that this function is defined as
 124     inline function. Use a declaration like the following, in order to
 125     allocate a login monitor object that is freed automatically as the
 126     code block is left:</para>
 127
 128     <programlisting>{
 129         __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
 130         int r;
 131         …
 132         r = sd_login_monitor_default(&amp;m);
 133         if (r &lt; 0)
 134                 fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
 135         …
 136 }</programlisting>
 137
 138     <para><function>sd_login_monitor_flush()</function> may be used to
 139     reset the wakeup state of the monitor object. Whenever an event
 140     causes the monitor to wake up the event loop via the file
 141     descriptor this function needs to be called to reset the wake-up
 142     state. If this call is not invoked, the file descriptor will
 143     immediately wake up the event loop again.</para>
 144
 145     <para><function>sd_login_monitor_unref()</function> and
 146     <function>sd_login_monitor_unrefp()</function> execute no
 147     operation if the passed in monitor object is
 148     <constant>NULL</constant>.</para>
 149
 150     <para><function>sd_login_monitor_get_fd()</function> may be used
 151     to retrieve the file descriptor of the monitor object that may be
 152     integrated in an application defined event loop, based around
 153     <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 154     or a similar interface. The application should include the
 155     returned file descriptor as wake-up source for the events mask
 156     returned by <function>sd_login_monitor_get_events()</function>. It
 157     should pass a timeout value as returned by
 158     <function>sd_login_monitor_get_timeout()</function>. Whenever a
 159     wake-up is triggered the file descriptor needs to be reset via
 160     <function>sd_login_monitor_flush()</function>. An application
 161     needs to reread the login state with a function like
 162     <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 163     or similar to determine what changed.</para>
 164
 165     <para><function>sd_login_monitor_get_events()</function> will
 166     return the <function>poll()</function> mask to wait for. This
 167     function will return a combination of <constant>POLLIN</constant>,
 168     <constant>POLLOUT</constant> and similar to fill into the
 169     <literal>.events</literal> field of <varname>struct
 170     pollfd</varname>.</para>
 171
 172     <para><function>sd_login_monitor_get_timeout()</function> will
 173     return a timeout value for usage in <function>poll()</function>.
 174     This returns a value in microseconds since the epoch of
 175     <constant>CLOCK_MONOTONIC</constant> for timing out
 176     <function>poll()</function> in <varname>timeout_usec</varname>.
 177     See
 178     <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 179     for details about <constant>CLOCK_MONOTONIC</constant>. If there
 180     is no timeout to wait for this will fill in <constant>(uint64_t)
 181     -1</constant> instead. Note that <function>poll()</function> takes
 182     a relative timeout in milliseconds rather than an absolute timeout
 183     in microseconds. To convert the absolute 'µs' timeout into
 184     relative 'ms', use code like the following:</para>
 185
 186     <programlisting>uint64_t t;
 187 int msec;
 188 sd_login_monitor_get_timeout(m, &amp;t);
 189 if (t == (uint64_t) -1)
 190          msec = -1;
 191 else {
 192          struct timespec ts;
 193          uint64_t n;
 194          clock_gettime(CLOCK_MONOTONIC, &amp;ts);
 195          n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
 196          msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 197 }</programlisting>
 198
 199     <para>The code above does not do any error checking for brevity's
 200     sake. The calculated <varname>msec</varname> integer can be passed
 201     directly as <function>poll()</function>'s timeout
 202     parameter.</para>
 203   </refsect1>
 204
 205   <refsect1>
 206     <title>Return Value</title>
 207
 208     <para>On success,
 209     <function>sd_login_monitor_new()</function>,
 210     <function>sd_login_monitor_flush()</function> and
 211     <function>sd_login_monitor_get_timeout()</function>
 212     return 0 or a positive integer. On success,
 213     <function>sd_login_monitor_get_fd()</function> returns
 214     a Unix file descriptor. On success,
 215     <function>sd_login_monitor_get_events()</function>
 216     returns a combination of <constant>POLLIN</constant>,
 217     <constant>POLLOUT</constant> and suchlike. On failure,
 218     these calls return a negative errno-style error
 219     code.</para>
 220
 221     <para><function>sd_login_monitor_unref()</function>
 222     always returns <constant>NULL</constant>.</para>
 223   </refsect1>
 224
 225   <refsect1>
 226     <title>Errors</title>
 227
 228     <para>Returned errors may indicate the following problems:</para>
 229
 230     <variablelist>
 231
 232       <varlistentry>
 233         <term><constant>-EINVAL</constant></term>
 234
 235         <listitem><para>An input parameter was invalid (out of range,
 236         or NULL, where that is not accepted). The specified category to
 237         watch is not known.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><constant>-ENOMEM</constant></term>
 242
 243         <listitem><para>Memory allocation failed.</para></listitem>
 244       </varlistentry>
 245     </variablelist>
 246   </refsect1>
 247
 248   <xi:include href="libsystemd-pkgconfig.xml" />
 249
 250   <refsect1>
 251     <title>See Also</title>
 252
 253     <para>
 254       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 257       <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 259     </para>
 260   </refsect1>
 261
 262 </refentry>