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