From dace83cbd0c2212fc0e25d36d50711b19f14b1b6 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 4 Apr 2013 17:38:08 +0200
Subject: login: add new public API call sd_login_monitor_get_events() to get
 poll() flags to wait for

We should keep our options open, so that we can watch for POLLOUT later
on if we wish to. CUrrently this call will always return POLLIN however.
---
 man/sd_login_monitor_new.xml | 43 +++++++++++++++++++++++++++++++++----------
 1 file changed, 33 insertions(+), 10 deletions(-)

(limited to 'man/sd_login_monitor_new.xml')

diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml
index 2c4d05dcb9..94428771a8 100644
--- a/man/sd_login_monitor_new.xml
+++ b/man/sd_login_monitor_new.xml
@@ -47,6 +47,7 @@
                 <refname>sd_login_monitor_unref</refname>
                 <refname>sd_login_monitor_flush</refname>
                 <refname>sd_login_monitor_get_fd</refname>
+                <refname>sd_login_monitor_get_events</refname>
                 <refname>sd_login_monitor</refname>
                 <refpurpose>Monitor login sessions, seats and users</refpurpose>
         </refnamediv>
@@ -76,6 +77,11 @@
                                 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
                         </funcprototype>
 
+                        <funcprototype>
+                                <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
+                                <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
+                        </funcprototype>
+
                 </funcsynopsis>
         </refsynopsisdiv>
 
@@ -122,14 +128,24 @@
                 application defined event loop, based around
                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                 or a similar interface. The application should include
-                the returned file descriptor as wake up source for
-                POLLIN events. Whenever a wake-up is triggered the
-                file descriptor needs to be reset via
+                the returned file descriptor as wake-up source for the
+                events mask returned by
+                <function>sd_login_monitor_get_events()</function>. Whenever
+                a wake-up is triggered the file descriptor needs to be
+                reset via
                 <function>sd_login_monitor_flush()</function>. An
                 application needs to reread the login state with a
                 function like
                 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 or similar to determine what changed.</para>
+
+                <para><function>sd_login_monitor_get_events()</function>
+                will return the <function>poll()</function> mask to
+                wait for. This function will return a combination of
+                <literal>POLLIN</literal>, <literal>POLLOUT</literal>
+                and similar to fill into the
+                <literal>.events</literal> field of <literal>struct
+                pollfd</literal>.</para>
         </refsect1>
 
         <refsect1>
@@ -140,8 +156,12 @@
                 <function>sd_login_monitor_flush()</function> return 0
                 or a positive integer. On success
                 <function>sd_login_monitor_get_fd()</function> returns
-                a Unix file descriptor. On failure, these calls return
-                a negative errno-style error code.</para>
+                a Unix file descriptor. On success
+                <function>sd_login_monitor_get_events()</function>
+                returns a combination of <literal>POLLIN</literal>,
+                <literal>POLLOUT</literal> and suchlike. On failure,
+                these calls return a negative errno-style error
+                code.</para>
 
                 <para><function>sd_login_monitor_unref()</function>
                 always returns NULL.</para>
@@ -151,10 +171,12 @@
                 <title>Notes</title>
 
                 <para>The <function>sd_login_monitor_new()</function>,
-                <function>sd_login_monitor_unref()</function>, <function>sd_login_monitor_flush()</function> and
-                <function>sd_login_monitor_get_fd()</function> interfaces
-                are available as shared library, which can be compiled
-                and linked to with the
+                <function>sd_login_monitor_unref()</function>,
+                <function>sd_login_monitor_flush()</function>,
+                <function>sd_login_monitor_get_fd()</function> and
+                <function>sd_login_monitor_get_events()</function>
+                interfaces are available as shared library, which can
+                be compiled and linked to with the
                 <literal>libsystemd-login</literal>
                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 file.</para>
@@ -166,7 +188,8 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                 </para>
         </refsect1>
 
-- 
cgit v1.2.3-54-g00ecf