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 and users</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 and seats. Via
 100                 a monitor object a file descriptor can be integrated
 101                 into an application defined event loop which is woken
 102                 up each time a user logs in, logs out or a seat is
 103                 added or removed, or a session, user, or seat changes
 104                 state otherwise. The first parameter takes a string
 105                 which can be <literal>seat</literal> (to get
 106                 only notifications about seats being added, removed or
 107                 changed), <literal>session</literal> (to get only
 108                 notifications about sessions being created or removed
 109                 or changed) or <literal>uid</literal> (to get only
 110                 notifications when a user changes state in respect to
 111                 logins). If notifications shall be generated in all
 112                 these conditions, NULL may be passed. Note that in the
 113                 future additional categories may be defined. The
 114                 second parameter returns a monitor object and needs to
 115                 be freed with the
 116                 <function>sd_login_monitor_unref()</function> call
 117                 after use.</para>
 118
 119                 <para><function>sd_login_monitor_unref()</function>
 120                 may be used to destroy a monitor object. Note that
 121                 this will invalidate any file descriptor returned by
 122                 <function>sd_login_monitor_get_fd()</function>.</para>
 123
 124                 <para><function>sd_login_monitor_flush()</function>
 125                 may be used to reset the wakeup state of the monitor
 126                 object. Whenever an event causes the monitor to wake
 127                 up the event loop via the file descriptor this
 128                 function needs to be called to reset the wake-up
 129                 state. If this call is not invoked the file descriptor
 130                 will immediately wake up the event loop again.</para>
 131
 132                 <para><function>sd_login_monitor_get_fd()</function>
 133                 may be used to retrieve the file descriptor of the
 134                 monitor object that may be integrated in an
 135                 application defined event loop, based around
 136                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 137                 or a similar interface. The application should include
 138                 the returned file descriptor as wake-up source for the
 139                 events mask returned by
 140                 <function>sd_login_monitor_get_events()</function>. It
 141                 should pass a timeout value as returned by
 142                 <function>sd_login_monitor_get_timeout()</function>. Whenever
 143                 a wake-up is triggered the file descriptor needs to be
 144                 reset via
 145                 <function>sd_login_monitor_flush()</function>. An
 146                 application needs to reread the login state with a
 147                 function like
 148                 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 149                 or similar to determine what changed.</para>
 150
 151                 <para><function>sd_login_monitor_get_events()</function>
 152                 will return the <function>poll()</function> mask to
 153                 wait for. This function will return a combination of
 154                 <literal>POLLIN</literal>, <literal>POLLOUT</literal>
 155                 and similar to fill into the
 156                 <literal>.events</literal> field of <literal>struct
 157                 pollfd</literal>.</para>
 158
 159                 <para><function>sd_login_monitor_get_timeout()</function>
 160                 will return a timeout value for usage in
 161                 <function>poll()</function>. This returns a value in
 162                 microseconds since the epoch of CLOCK_MONOTONIC for
 163                 timing out <function>poll()</function> in
 164                 <literal>timeout_usec</literal>. See
 165                 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 166                 for details about
 167                 <literal>CLOCK_MONOTONIC</literal>. If there's no
 168                 timeout to wait for this will fill in
 169                 <literal>(uint64_t) -1</literal> instead. Note that
 170                 <function>poll()</function> takes a relative timeout
 171                 in milliseconds rather than an absolute timeout in
 172                 microseconds. To convert the absolute 'us' timeout into
 173                 relative 'ms', use code like the following:</para>
 174
 175                 <programlisting>uint64_t t;
 176 int msec;
 177 sd_login_monitor_get_timeout(m, &amp;t);
 178 if (t == (uint64_t) -1)
 179         msec = -1;
 180 else {
 181         struct timespec ts;
 182         uint64_t n;
 183         clock_getttime(CLOCK_MONOTONIC, &amp;ts);
 184         n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
 185         msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
 186 }</programlisting>
 187
 188                 <para>The code above does not do any error checking
 189                 for brevity's sake. The calculated <literal>msec</literal>
 190                 integer can be passed directly as
 191                 <function>poll()</function>'s timeout
 192                 parameter.</para>
 193         </refsect1>
 194
 195         <refsect1>
 196                 <title>Return Value</title>
 197
 198                 <para>On success
 199                 <function>sd_login_monitor_new()</function>,
 200                 <function>sd_login_monitor_flush()</function> and
 201                 <function>sd_login_monitor_get_timeout()</function>
 202                 return 0 or a positive integer. On success
 203                 <function>sd_login_monitor_get_fd()</function> returns
 204                 a Unix file descriptor. On success
 205                 <function>sd_login_monitor_get_events()</function>
 206                 returns a combination of <literal>POLLIN</literal>,
 207                 <literal>POLLOUT</literal> and suchlike. On failure,
 208                 these calls return a negative errno-style error
 209                 code.</para>
 210
 211                 <para><function>sd_login_monitor_unref()</function>
 212                 always returns NULL.</para>
 213         </refsect1>
 214
 215         <refsect1>
 216                 <title>Notes</title>
 217
 218                 <para>The <function>sd_login_monitor_new()</function>,
 219                 <function>sd_login_monitor_unref()</function>,
 220                 <function>sd_login_monitor_flush()</function>,
 221                 <function>sd_login_monitor_get_fd()</function>,
 222                 <function>sd_login_monitor_get_events()</function> and
 223                 <function>sd_login_monitor_get_timeout()</function>
 224                 interfaces are available as shared library, which can
 225                 be compiled and linked to with the
 226                 <literal>libsystemd-login</literal>
 227                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 228                 file.</para>
 229         </refsect1>
 230
 231         <refsect1>
 232                 <title>See Also</title>
 233
 234                 <para>
 235                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 236                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 237                         <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 238                         <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 239                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 240                 </para>
 241         </refsect1>
 242
 243 </refentry>