From 550fab31953acced44a6e7b2acc050b8270dd558 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 19 Dec 2011 14:42:59 +0100
Subject: [PATCH] man: various updates (cherry picked from commit
595aae376fae21f885ec9af2cac1aaf3ff3e9bee)
---
man/sd-login.xml | 21 ++++++++++++++++++++-
man/sd_get_seats.xml | 12 +++++++-----
man/sd_login_monitor_new.xml | 2 +-
man/sd_seat_get_active.xml | 6 ++++--
man/sd_session_is_active.xml | 2 +-
man/sd_uid_get_state.xml | 13 ++++++++-----
6 files changed, 41 insertions(+), 15 deletions(-)
diff --git a/man/sd-login.xml b/man/sd-login.xml
index 62ec6ff..9926d2b 100644
--- 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 bbc396a..2ac7650 100644
--- 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 2b37f00..de48432 100644
--- 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 e729a65..14cda60 100644
--- 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 82919f8..88b22fd 100644
--- 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 a4e9e73..6777625 100644
--- 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>
--
1.7.7.5