man: various updates

diff --git a/man/sd-login.xml b/man/sd-login.xml
index 62ec6ffefd07e3dc6e8bfef5547233b03c6cc479..9926d2b85cfd85df91bebb2384d233754fc6c8da 100644 (file)
--- a/man/sd-login.xml
+++ b/man/sd-login.xml
@@ -75,7 +75,26 @@
                 actively make changes to the seat configuration,
                 terminate login sessions, or switch session on a seat
                 you need to utilize the D-Bus API of
-                systemd-logind.</para>
+                systemd-logind, instead.</para>
+
+                <para>These functions access data in
+                <filename>/proc</filename>,
+                <filename>/sys/fs/cgroup</filename> and
+                <filename>/run</filename>. All of these are virtual
+                file systems, hence the runtime cost of the accesses
+                is relatively cheap.</para>
+
+                <para>If the functions return string arrays, these are
+                generally NULL terminated and need to be freed by the
+                caller with the libc
+                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                call after use, including the strings referenced
+                therein. Similar, individual strings returned need to
+                be freed, as well.</para>
+
+                <para>As a special exception, instead of an empty
+                string array NULL may be returned, which should be
+                treated equivalent to an empty string array.</para>
 
                 <para>See
                 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml
index bbc396a09b3601d7ae0aa636149cd81d5d2cec9c..2ac76500ec8dc409fb22a996a212e849d5b74f60 100644 (file)
--- a/man/sd_get_seats.xml
+++ b/man/sd_get_seats.xml
@@ -76,11 +76,13 @@
 
                 <para><function>sd_get_seats()</function> may be used
                 to determine all currently available local
-                seats. Returns an array of seat identifiers. The
-                returned array and all strings it references need to
-                be freed with the libc
+                seats. Returns a NULL terminated array of seat
+                identifiers. The returned array and all strings it
+                references need to be freed with the libc
                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call after use.</para>
+                call after use. Note that instead of an empty array
+                NULL may be returned and should be considered
+                equivalent to an empty array.</para>
 
                 <para>Similar, <function>sd_get_sessions()</function> may
                 be used to determine all current login sessions.</para>
@@ -118,7 +120,7 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 </para>
         </refsect1>
 

diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml
index 2b37f00d309ddc0f61d1241e80be639332884f62..de484329a9900c794489d891804c3d08787452f9 100644 (file)
--- a/man/sd_login_monitor_new.xml
+++ b/man/sd_login_monitor_new.xml
@@ -165,7 +165,7 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 </para>
         </refsect1>
 

diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml
index e729a653b7dbb8374f19f9d83badd40d1c0fbc29..14cda60a56032b67b9729be1a6b471e3b0f6cfd7 100644 (file)
--- a/man/sd_seat_get_active.xml
+++ b/man/sd_seat_get_active.xml
@@ -101,7 +101,9 @@
                 determined. The arrays and the strings referenced by
                 them need to be freed with the libc
                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call after use.</para>
+                call after use. Note that instead of an empty array
+                NULL may be returned and should be considered
+                equivalent to an empty array.</para>
 
                 <para><function>sd_seat_can_multi_session()</function>
                 may be used to determine whether a specific seat is
@@ -143,7 +145,7 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 </para>
         </refsect1>
 

diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml
index 82919f84fbb23abae6db876e5775a77aff546305..88b22fd9f8366cabe5b791d26c209f98f84610f2 100644 (file)
--- a/man/sd_session_is_active.xml
+++ b/man/sd_session_is_active.xml
@@ -127,7 +127,7 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 </para>
         </refsect1>
 

diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml
index a4e9e73087091f0ee179bd0876d630d1e1b57509..67776257db26ed35e7457533677dc59e565dabc5 100644 (file)
--- a/man/sd_uid_get_state.xml
+++ b/man/sd_uid_get_state.xml
@@ -126,10 +126,13 @@
                 identifiers in <parameter>sessions</parameter> which
                 needs to be freed by the caller with the libc
                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call after use, including all the strings referenced. If
-                the string array parameter is passed as NULL the array
-                will not be filled in, but the return code still
-                indicates the number of current sessions.</para>
+                call after use, including all the strings
+                referenced. If the string array parameter is passed as
+                NULL the array will not be filled in, but the return
+                code still indicates the number of current
+                sessions. Note that instead of an empty array NULL may
+                be returned and should be considered equivalent to an
+                empty array.</para>
 
                 <para>Similar, <function>sd_uid_get_seats()</function>
                 may be used to determine the list of seats on which
@@ -175,7 +178,7 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 </para>
         </refsect1>