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</refname>
  52                 <refpurpose>Monitor login sessions, seats and users</refpurpose>
  53         </refnamediv>
  54
  55         <refsynopsisdiv>
  56                 <funcsynopsis>
  57                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  58
  59                         <funcprototype>
  60                                 <funcdef>int <function>sd_login_monitor_new</function></funcdef>
  61                                 <paramdef>const char* <parameter>category</parameter></paramdef>
  62                                 <paramdef>sd_login_monitor** <parameter>ret</parameter></paramdef>
  63                         </funcprototype>
  64
  65                         <funcprototype>
  66                                 <funcdef>sd_login_monitor* <function>sd_login_monitor_unref</function></funcdef>
  67                                 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
  68                         </funcprototype>
  69
  70                         <funcprototype>
  71                                 <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
  72                                 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
  73                         </funcprototype>
  74
  75                         <funcprototype>
  76                                 <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
  77                                 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
  78                         </funcprototype>
  79
  80                         <funcprototype>
  81                                 <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
  82                                 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
  83                         </funcprototype>
  84
  85                 </funcsynopsis>
  86         </refsynopsisdiv>
  87
  88         <refsect1>
  89                 <title>Description</title>
  90
  91                 <para><function>sd_login_monitor_new()</function> may
  92                 be used to monitor login sessions, users and seats. Via
  93                 a monitor object a file descriptor can be integrated
  94                 into an application defined event loop which is woken
  95                 up each time a user logs in, logs out or a seat is
  96                 added or removed, or a session, user, or seat changes
  97                 state otherwise. The first parameter takes a string
  98                 which can be <literal>seat</literal> (to get
  99                 only notifications about seats being added, removed or
 100                 changed), <literal>session</literal> (to get only
 101                 notifications about sessions being created or removed
 102                 or changed) or <literal>uid</literal> (to get only
 103                 notifications when a user changes state in respect to
 104                 logins). If notifications shall be generated in all
 105                 these conditions, NULL may be passed. Note that in the
 106                 future additional categories may be defined. The
 107                 second parameter returns a monitor object and needs to
 108                 be freed with the
 109                 <function>sd_login_monitor_unref()</function> call
 110                 after use.</para>
 111
 112                 <para><function>sd_login_monitor_unref()</function>
 113                 may be used to destroy a monitor object. Note that
 114                 this will invalidate any file descriptor returned by
 115                 <function>sd_login_monitor_get_fd()</function>.</para>
 116
 117                 <para><function>sd_login_monitor_flush()</function>
 118                 may be used to reset the wakeup state of the monitor
 119                 object. Whenever an event causes the monitor to wake
 120                 up the event loop via the file descriptor this
 121                 function needs to be called to reset the wake-up
 122                 state. If this call is not invoked the file descriptor
 123                 will immediately wake up the event loop again.</para>
 124
 125                 <para><function>sd_login_monitor_get_fd()</function>
 126                 may be used to retrieve the file descriptor of the
 127                 monitor object that may be integrated in an
 128                 application defined event loop, based around
 129                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 130                 or a similar interface. The application should include
 131                 the returned file descriptor as wake-up source for the
 132                 events mask returned by
 133                 <function>sd_login_monitor_get_events()</function>. Whenever
 134                 a wake-up is triggered the file descriptor needs to be
 135                 reset via
 136                 <function>sd_login_monitor_flush()</function>. An
 137                 application needs to reread the login state with a
 138                 function like
 139                 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 140                 or similar to determine what changed.</para>
 141
 142                 <para><function>sd_login_monitor_get_events()</function>
 143                 will return the <function>poll()</function> mask to
 144                 wait for. This function will return a combination of
 145                 <literal>POLLIN</literal>, <literal>POLLOUT</literal>
 146                 and similar to fill into the
 147                 <literal>.events</literal> field of <literal>struct
 148                 pollfd</literal>.</para>
 149         </refsect1>
 150
 151         <refsect1>
 152                 <title>Return Value</title>
 153
 154                 <para>On success
 155                 <function>sd_login_monitor_new()</function> and
 156                 <function>sd_login_monitor_flush()</function> return 0
 157                 or a positive integer. On success
 158                 <function>sd_login_monitor_get_fd()</function> returns
 159                 a Unix file descriptor. On success
 160                 <function>sd_login_monitor_get_events()</function>
 161                 returns a combination of <literal>POLLIN</literal>,
 162                 <literal>POLLOUT</literal> and suchlike. On failure,
 163                 these calls return a negative errno-style error
 164                 code.</para>
 165
 166                 <para><function>sd_login_monitor_unref()</function>
 167                 always returns NULL.</para>
 168         </refsect1>
 169
 170         <refsect1>
 171                 <title>Notes</title>
 172
 173                 <para>The <function>sd_login_monitor_new()</function>,
 174                 <function>sd_login_monitor_unref()</function>,
 175                 <function>sd_login_monitor_flush()</function>,
 176                 <function>sd_login_monitor_get_fd()</function> and
 177                 <function>sd_login_monitor_get_events()</function>
 178                 interfaces are available as shared library, which can
 179                 be compiled and linked to with the
 180                 <literal>libsystemd-login</literal>
 181                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 182                 file.</para>
 183         </refsect1>
 184
 185         <refsect1>
 186                 <title>See Also</title>
 187
 188                 <para>
 189                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 190                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 191                         <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192                         <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 193                 </para>
 194         </refsect1>
 195
 196 </refentry>