From 623538c3125fd0174513e4ef5b0e6163f4ea41ef Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Sat, 24 May 2014 18:49:45 -0400
Subject: [PATCH 1/1] man: describe sd_uid_get_display

---
 Makefile-man.am          |  5 +++++
 man/sd_uid_get_state.xml | 40 +++++++++++++++++++++++++++++++++-------
 2 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/Makefile-man.am b/Makefile-man.am
index 6d57b7513..03adc7ca2 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -1288,6 +1288,7 @@ MANPAGES_ALIAS += \
 	man/sd_session_get_uid.3 \
 	man/sd_session_get_vt.3 \
 	man/sd_session_is_remote.3 \
+	man/sd_uid_get_display.3 \
 	man/sd_uid_get_seats.3 \
 	man/sd_uid_get_sessions.3 \
 	man/sd_uid_is_on_seat.3 \
@@ -1328,6 +1329,7 @@ man/sd_session_get_type.3: man/sd_session_is_active.3
 man/sd_session_get_uid.3: man/sd_session_is_active.3
 man/sd_session_get_vt.3: man/sd_session_is_active.3
 man/sd_session_is_remote.3: man/sd_session_is_active.3
+man/sd_uid_get_display.3: man/sd_uid_get_state.3
 man/sd_uid_get_seats.3: man/sd_uid_get_state.3
 man/sd_uid_get_sessions.3: man/sd_uid_get_state.3
 man/sd_uid_is_on_seat.3: man/sd_uid_get_state.3
@@ -1440,6 +1442,9 @@ man/sd_session_get_vt.html: man/sd_session_is_active.html
 man/sd_session_is_remote.html: man/sd_session_is_active.html
 	$(html-alias)
 
+man/sd_uid_get_display.html: man/sd_uid_get_state.html
+	$(html-alias)
+
 man/sd_uid_get_seats.html: man/sd_uid_get_state.html
 	$(html-alias)
 
diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml
index 01ad0abfc..1007a7917 100644
--- 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>
 
@@ -80,6 +81,12 @@
                                 <paramdef>int <parameter>require_active</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>
 
@@ -147,6 +154,12 @@
                 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>
@@ -159,7 +172,9 @@
                 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><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 a shared library, which can be compiled and
-                linked to with the <constant>libsystemd</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>
-- 
2.30.2