tree-wide: drop license boilerplate

[thirdparty/systemd.git] / man / sd_login_monitor_new.xml

diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml
index a8854dd5902f0df65f13ac7ae020d5ac5e57ef97..f27c4f8bff5f00ab082e5af8f35fd843c3fce438 100644 (file)
--- a/man/sd_login_monitor_new.xml
+++ b/man/sd_login_monitor_new.xml
@@ -3,22 +3,11 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2010 Lennart Poettering
-
-  systemd is free software; you can redistribute it and/or modify it
-  under the terms of the GNU Lesser General Public License as published by
-  the Free Software Foundation; either version 2.1 of the License, or
-  (at your option) any later version.
-
-  systemd is distributed in the hope that it will be useful, but
-  WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-  Lesser General Public License for more details.
-
-  You should have received a copy of the GNU Lesser General Public License
-  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
 <refentry id="sd_login_monitor_new" conditional='HAVE_PAM'>
@@ -45,6 +34,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>
@@ -68,6 +58,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>
@@ -121,6 +116,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
@@ -128,6 +143,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
@@ -172,7 +192,7 @@ if (t == (uint64_t) -1)
 else {
          struct timespec ts;
          uint64_t n;
-         clock_getttime(CLOCK_MONOTONIC, &amp;ts);
+         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>
@@ -214,7 +234,7 @@ else {
         <term><constant>-EINVAL</constant></term>
 
         <listitem><para>An input parameter was invalid (out of range,
-        or NULL, where that's not accepted). The specified category to
+        or NULL, where that is not accepted). The specified category to
         watch is not known.</para></listitem>
       </varlistentry>