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