test-login: make the test non-manual

[elogind.git] / man / sd_login_monitor_new.xml

diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml
index f24d8b3ce4237d57dc03baeb1e1f5fe51db67092..c6c58390a2b863705bd9973fc9e1ce794b2dfb19 100644 (file)
--- a/man/sd_login_monitor_new.xml
+++ b/man/sd_login_monitor_new.xml
@@ -1,9 +1,6 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % entities SYSTEM "custom-entities.ent" >
-%entities;
-]>
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -48,6 +45,7 @@
   <refnamediv>
     <refname>sd_login_monitor_new</refname>
     <refname>sd_login_monitor_unref</refname>
+    <refname>sd_login_monitor_unrefp</refname>
     <refname>sd_login_monitor_flush</refname>
     <refname>sd_login_monitor_get_fd</refname>
     <refname>sd_login_monitor_get_events</refname>
@@ -71,6 +69,11 @@
         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef>
+        <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
@@ -124,6 +127,26 @@
     descriptor returned by
     <function>sd_login_monitor_get_fd()</function>.</para>
 
+    <para><function>sd_login_monitor_unrefp()</function> is similar to
+    <function>sd_login_monitor_unref()</function> but takes a pointer
+    to a pointer to an <type>sd_login_monitor</type> object. This call
+    is useful in conjunction with GCC's and LLVM's <ulink
+    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
+    Variable Attribute</ulink>. Note that this function is defined as
+    inline function. Use a declaration like the following, in order to
+    allocate a login monitor object that is freed automatically as the
+    code block is left:</para>
+
+    <programlisting>{
+        __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
+        int r;
+        …
+        r = sd_login_monitor_default(&amp;m);
+        if (r &lt; 0)
+                fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
+        …
+}</programlisting>
+
     <para><function>sd_login_monitor_flush()</function> may be used to
     reset the wakeup state of the monitor object. Whenever an event
     causes the monitor to wake up the event loop via the file
@@ -131,6 +154,11 @@
     state. If this call is not invoked, the file descriptor will
     immediately wake up the event loop again.</para>
 
+    <para><function>sd_login_monitor_unref()</function> and
+    <function>sd_login_monitor_unrefp()</function> execute no
+    operation if the passed in monitor object is
+    <constant>NULL</constant>.</para>
+
     <para><function>sd_login_monitor_get_fd()</function> may be used
     to retrieve the file descriptor of the monitor object that may be
     integrated in an application defined event loop, based around
@@ -164,20 +192,20 @@
     is no timeout to wait for this will fill in <constant>(uint64_t)
     -1</constant> 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
+    in microseconds. To convert the absolute 'µs' timeout into
     relative 'ms', use code like the following:</para>
 
     <programlisting>uint64_t t;
 int msec;
 sd_login_monitor_get_timeout(m, &amp;t);
 if (t == (uint64_t) -1)
-  msec = -1;
+         msec = -1;
 else {
-  struct timespec ts;
-  uint64_t n;
-  clock_getttime(CLOCK_MONOTONIC, &amp;ts);
-  n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
-  msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
+         struct timespec ts;
+         uint64_t n;
+         clock_gettime(CLOCK_MONOTONIC, &amp;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
@@ -206,6 +234,29 @@ else {
     always returns <constant>NULL</constant>.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>An input parameter was invalid (out of range,
+        or NULL, where that is not accepted). The specified category to
+        watch is not known.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Memory allocation failed.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
   <refsect1>
     <title>Notes</title>