Merge pull request #16678 from poettering/loop-configure

[thirdparty/systemd.git] / man / sd_id128_get_machine.xml

diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml
index 0bfe1b50020ff2f7690c1c4011463e3e0d19ce28..bb85d8839f4daa6de6567347aa3aeb5e91a5598c 100644 (file)
--- a/man/sd_id128_get_machine.xml
+++ b/man/sd_id128_get_machine.xml
@@ -1,10 +1,7 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
-  SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
 <refentry id="sd_id128_get_machine" xmlns:xi="http://www.w3.org/2001/XInclude">
 
@@ -69,7 +66,7 @@
     file. This function caches the machine ID internally to make retrieving the machine ID a cheap operation. This ID
     may be used wherever a unique identifier for the local system is needed. However, it is recommended to use this ID
     as-is only in trusted environments. In untrusted environments it is recommended to derive an application specific
-    ID from this machine ID, in an irreversable (cryptographically secure) way. To make this easy
+    ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy
     <function>sd_id128_get_machine_app_specific()</function> is provided, see below.</para>
 
     <para><function>sd_id128_get_machine_app_specific()</function> is similar to
@@ -118,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" />