From 6f7530929538b28cb41c289ad9cbced51848fc02 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 26 May 2021 16:07:55 +0200
Subject: [PATCH] man: document that it is guaranteed that generated ID128 are
 never all-zero or all-one

This is the case because the ID128 we generate are all marked as v4 UUID
which requires that some bits are zero and others are one. Let's
document this so that people can rely on SD_ID128_NULL being a special
value for "uninitialized" that is always distinguishable from generated
UUIDs.
---
 man/sd_id128_get_machine.xml | 16 ++++++++++------
 man/sd_id128_randomize.xml   |  5 +++--
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml
index 2df4496f192..7fa98608987 100644
--- a/man/sd_id128_get_machine.xml
+++ b/man/sd_id128_get_machine.xml
@@ -99,12 +99,16 @@
     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
     ID is cached internally. In future a different mechanism to determine the invocation ID may be added.</para>
 
-    <para>Note that <function>sd_id128_get_machine_app_specific()</function>, <function>sd_id128_get_boot()</function>,
-    <function>sd_id128_get_boot_app_specific()</function>, and <function>sd_id128_get_invocation()</function> always
-    return UUID v4 compatible IDs.  <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible
-    ID on new installations but might not on older. It is possible to convert the machine ID into a UUID v4-compatible
-    one. For more information, see
-    <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+    <para>Note that <function>sd_id128_get_machine_app_specific()</function>,
+    <function>sd_id128_get_boot()</function>, <function>sd_id128_get_boot_app_specific()</function>, and
+    <function>sd_id128_get_invocation()</function> always return UUID v4 compatible IDs.
+    <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible ID on new installations
+    but might not on older. It is possible to convert the machine ID into a UUID v4-compatible one. For more
+    information, see
+    <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It is
+    hence guaranteed that thes functions will never return the ID consisting of all zero or all one bits
+    (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>) — with the possible exception of
+    <function>sd_id128_get_machine()</function>, as mentioned.</para>
 
     <para>For more information about the <literal>sd_id128_t</literal>
     type see
diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml
index cf6ca7726f1..0bc1d0abd8f 100644
--- a/man/sd_id128_randomize.xml
+++ b/man/sd_id128_randomize.xml
@@ -42,8 +42,9 @@
     <filename>/dev/urandom</filename> kernel random number
     generator.</para>
 
-    <para>Note that <function>sd_id128_randomize()</function> always
-    returns a UUID v4-compatible ID.</para>
+    <para>Note that <function>sd_id128_randomize()</function> always returns a UUID v4-compatible ID. It is
+    hence guaranteed that this function will never return the ID consisting of all zero or all one bits
+    (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>).</para>
 
     <para>For more information about the <literal>sd_id128_t</literal>
     type, see