diff options
Diffstat (limited to 'man/sd_login_monitor_new.xml')
| -rw-r--r-- | man/sd_login_monitor_new.xml | 61 |
1 files changed, 54 insertions, 7 deletions
diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index 94428771a8..b187ad0dbe 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -48,6 +48,7 @@ <refname>sd_login_monitor_flush</refname> <refname>sd_login_monitor_get_fd</refname> <refname>sd_login_monitor_get_events</refname> + <refname>sd_login_monitor_get_timeout</refname> <refname>sd_login_monitor</refname> <refpurpose>Monitor login sessions, seats and users</refpurpose> </refnamediv> @@ -82,6 +83,12 @@ <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef> </funcprototype> + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> + <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef> + <paramdef>uint64_t* <parameter>timeout_usec</parameter></paramdef> + </funcprototype> + </funcsynopsis> </refsynopsisdiv> @@ -130,7 +137,9 @@ or a similar interface. The application should include the returned file descriptor as wake-up source for the events mask returned by - <function>sd_login_monitor_get_events()</function>. Whenever + <function>sd_login_monitor_get_events()</function>. It + should pass a timeout value as returned by + <function>sd_login_monitor_get_timeout()</function>. Whenever a wake-up is triggered the file descriptor needs to be reset via <function>sd_login_monitor_flush()</function>. An @@ -146,15 +155,51 @@ and similar to fill into the <literal>.events</literal> field of <literal>struct pollfd</literal>.</para> + + <para><function>sd_login_monitor_get_timeout()</function> + will return a timeout value for usage in + <function>poll()</function>. This returns a value in + microseconds since the epoch of CLOCK_MONOTONIC for + timing out <function>poll()</function> in + <literal>timeout_usec</literal>. See + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about + <literal>CLOCK_MONOTONIC</literal>. If there's no + timeout to wait for this will fill in + <literal>(uint64_t) -1</literal> instead. Note that + <function>poll()</function> takes a relative timeout + in milliseconds rather than an absolute timeout in + microseconds. To convert the absolute 'us' timeout into + relative 'ms', use code like the following:</para> + + <programlisting>uint64_t t; +int msec; +sd_login_monitor_get_timeout(m, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; +}</programlisting> + + <para>The code above does not do any error checking + for brevity's sake. The calculated <literal>msec</literal> + integer can be passed directly as + <function>poll()</function>'s timeout + parameter.</para> </refsect1> <refsect1> <title>Return Value</title> <para>On success - <function>sd_login_monitor_new()</function> and - <function>sd_login_monitor_flush()</function> return 0 - or a positive integer. On success + <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_flush()</function> and + <function>sd_login_monitor_get_timeout()</function> + return 0 or a positive integer. On success <function>sd_login_monitor_get_fd()</function> returns a Unix file descriptor. On success <function>sd_login_monitor_get_events()</function> @@ -173,8 +218,9 @@ <para>The <function>sd_login_monitor_new()</function>, <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> + <function>sd_login_monitor_get_fd()</function>, + <function>sd_login_monitor_get_events()</function> and + <function>sd_login_monitor_get_timeout()</function> interfaces are available as shared library, which can be compiled and linked to with the <literal>libsystemd-login</literal> @@ -189,7 +235,8 @@ <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>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> </refsect1> |