man: suffix C functions with ()

[elogind.git] / man / sd_uid_get_state.xml

diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml
index d4d23f4f1d703d813a3cc99178252070ca18f3a1..e1b345c2779a1774bb94d72445ba43e2207a8c9f 100644 (file)
--- a/man/sd_uid_get_state.xml
+++ b/man/sd_uid_get_state.xml
@@ -47,6 +47,7 @@
                 <refname>sd_uid_is_on_seat</refname>
                 <refname>sd_uid_get_sessions</refname>
                 <refname>sd_uid_get_seats</refname>
+                <refname>sd_uid_get_display</refname>
                 <refpurpose>Determine login state of a specific Unix user ID</refpurpose>
         </refnamediv>
 
@@ -57,28 +58,34 @@
                         <funcprototype>
                                 <funcdef>int <function>sd_uid_get_state</function></funcdef>
                                 <paramdef>uid_t <parameter>uid</parameter></paramdef>
-                                <paramdef>char** <parameter>state</parameter></paramdef>
+                                <paramdef>char **<parameter>state</parameter></paramdef>
                         </funcprototype>
 
                         <funcprototype>
                                 <funcdef>int <function>sd_uid_is_on_seat</function></funcdef>
                                 <paramdef>uid_t <parameter>uid</parameter></paramdef>
                                 <paramdef>int <parameter>require_active</parameter></paramdef>
-                                <paramdef>const char* <parameter>seat</parameter></paramdef>
+                                <paramdef>const char *<parameter>seat</parameter></paramdef>
                         </funcprototype>
 
                         <funcprototype>
                                 <funcdef>int <function>sd_uid_get_sessions</function></funcdef>
                                 <paramdef>uid_t <parameter>uid</parameter></paramdef>
                                 <paramdef>int <parameter>require_active</parameter></paramdef>
-                                <paramdef>char*** <parameter>sessions</parameter></paramdef>
+                                <paramdef>char ***<parameter>sessions</parameter></paramdef>
                         </funcprototype>
 
                         <funcprototype>
                                 <funcdef>int <function>sd_uid_get_seats</function></funcdef>
                                 <paramdef>uid_t <parameter>uid</parameter></paramdef>
                                 <paramdef>int <parameter>require_active</parameter></paramdef>
-                                <paramdef>char*** <parameter>seats</parameter></paramdef>
+                                <paramdef>char ***<parameter>seats</parameter></paramdef>
+                        </funcprototype>
+
+                        <funcprototype>
+                                <funcdef>int <function>sd_uid_get_display</function></funcdef>
+                                <paramdef>uid_t <parameter>uid</parameter></paramdef>
+                                <paramdef>char **<parameter>session</parameter></paramdef>
                         </funcprototype>
                 </funcsynopsis>
         </refsynopsisdiv>
@@ -103,7 +110,7 @@
                 in regards to additional state strings being
                 returned. The returned string needs to be freed with
                 the libc
-                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 call after use.</para>
 
                 <para><function>sd_uid_is_on_seat()</function> may be
@@ -130,7 +137,7 @@
                 <constant>NULL</constant> terminated string array of session identifiers in
                 <parameter>sessions</parameter> which needs to be
                 freed by the caller with the libc
-                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 call after use, including all the strings
                 referenced. If the string array parameter is passed as
                 <constant>NULL</constant>, the array will not be filled in, but the return
@@ -139,7 +146,7 @@
                 be returned and should be considered equivalent to an
                 empty array.</para>
 
-                <para>Similar, <function>sd_uid_get_seats()</function>
+                <para>Similarly, <function>sd_uid_get_seats()</function>
                 may be used to determine the list of seats on which
                 the user currently has sessions. Similar semantics
                 apply, however note that the user may have
@@ -147,19 +154,27 @@
                 with no attached seat and hence the number of entries
                 in the returned array may differ from the one returned
                 by <function>sd_uid_get_sessions()</function>.</para>
+
+                <para><function>sd_uid_get_display()</function>
+                returns the name of the "primary" session of a user.
+                If the user has graphical sessions, it will be the
+                oldest graphical session. Otherwise, it will be the
+                oldest open session.</para>
         </refsect1>
 
         <refsect1>
                 <title>Return Value</title>
 
-                <para>On success
+                <para>On success,
                 <function>sd_uid_get_state()</function> returns 0 or a
                 positive integer. If the test succeeds,
                 <function>sd_uid_is_on_seat()</function> returns a
-                positive integer, if it fails
+                positive integer; if it fails,
                 0. <function>sd_uid_get_sessions()</function> and
                 <function>sd_uid_get_seats()</function> return the
-                number of entries in the returned arrays. On failure,
+                number of entries in the returned arrays.
+                <function>sd_uid_get_display()</function> returns
+                a non-negative code on success. On failure,
                 these calls return a negative errno-style error
                 code.</para>
         </refsect1>
@@ -167,13 +182,24 @@
         <refsect1>
                 <title>Notes</title>
 
-                <para>The <function>sd_uid_get_state()</function>,
+                <para>Functions described here are available as a
+                shared library, and can be compiled and linked to
+                using the
+                <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                entry.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>History</title>
+
+                <function>sd_uid_get_state()</function>,
                 <function>sd_uid_is_on_seat()</function>,
-                <function>sd_uid_get_sessions()</function>, and
-                <function>sd_uid_get_seats()</function> interfaces are
-                available as shared library, which can be compiled and
-                linked to with the <constant>libsystemd-login</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                file.</para>
+                <function>sd_uid_get_sessions()</function>,
+                and <function>sd_uid_get_seats()</function> functions
+                were added in systemd-31.
+
+                <para><function>sd_uid_get_display()</function> was
+                added in systemd-213.</para>
         </refsect1>
 
         <refsect1>