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