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