system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-10-06 16:21:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

man: document that it is guaranteed that generated ID128 are never all-zero or all-one

Browse source 
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.
This commit is contained in:
Lennart Poettering 2021-05-26 16:07:55 +02:00
parent 997c2d5625
commit 6f75309295
2 changed files with 13 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
man/sd_id128_get_machine.xml
View file

@ -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

5
man/sd_id128_randomize.xml
View file

@ -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