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