From 6d99c5d1d9832a2a85c77f8d90767028651f3f35 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 21 Mar 2019 14:08:34 +0100
Subject: [PATCH] man: document error values for sd_id128_get_*()

---
 man/sd_id128_get_machine.xml | 53 ++++++++++++++++++++++++++++++++----
 1 file changed, 47 insertions(+), 6 deletions(-)

diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml
index 59620ab77b..e665f7343f 100644
--- a/man/sd_id128_get_machine.xml
+++ b/man/sd_id128_get_machine.xml
@@ -115,12 +115,53 @@
     <title>Return Value</title>
 
     <para>Those calls return 0 on success (in which case <parameter>ret</parameter> is filled in),
-    or a negative errno-style error code. In particular,
-    <function>sd_id128_get_machine()</function>,
-    <function>sd_id128_get_machine_app_specific()</function>, and
-    <function>sd_id128_get_boot_app_specific()</function> return <constant>-ENOENT</constant> if
-    <filename>/etc/machine-id</filename> is missing, and <constant>-ENOMEDIUM</constant> if
-    <filename>/etc/machine-id</filename> is empty or all zeros.</para>
+    or a negative errno-style error code.</para>
+
+    <refsect2>
+      <title>Errors</title>
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-ENOENT</constant></term>
+
+          <listitem><para>Returned by <function>sd_id128_get_machine()</function>,
+          <function>sd_id128_get_machine_app_specific()</function>, and
+          <function>sd_id128_get_boot_app_specific()</function> when <filename>/etc/machine-id</filename> is
+          missing.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOMEDIUM</constant></term>
+
+          <listitem><para>Returned by <function>sd_id128_get_machine()</function>,
+          <function>sd_id128_get_machine_app_specific()</function>, and
+          <function>sd_id128_get_boot_app_specific()</function> when <filename>/etc/machine-id</filename> is
+          empty or all zeros.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENXIO</constant></term>
+
+          <listitem><para>Returned by <function>sd_id128_get_invocation()</function> if no invocation ID is
+          set.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EIO</constant></term>
+
+          <listitem><para>Returned by any of the functions described here when the configured value has
+          invalid format.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EPERM</constant></term>
+
+          <listitem><para>Requested information could not be retrieved because of insufficient permissions.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />