<refsect1>
<title>Relation to OSF UUIDs</title>
- <para>Note that the machine ID historically is not an OSF UUID as
- defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
- 4122</ulink>, nor a Microsoft GUID; however, starting with systemd
- v30, newly generated machine IDs do qualify as v4 UUIDs.</para>
-
- <para>In order to maintain compatibility with existing
- installations, an application requiring a UUID should decode the
- machine ID, and then apply the following operations to turn it
- into a valid OSF v4 UUID. With <literal>id</literal> being an
+ <para>Note that the machine ID historically is not an OSF UUID as defined by <ulink
+ url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink>, nor a Microsoft GUID; however, starting with
+ systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
+
+ <para>In order to maintain compatibility with existing installations, an application requiring a strictly
+ RFC 4122 compliant UUID should decode the machine ID, and then (non-reversibly) apply the following
+ operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID. With <literal>id</literal> being an
unsigned character array:</para>
<programlisting>/* Set UUID version to 4 --- truly random generation */
<refsect1>
<title>Description</title>
- <para><filename>sd-id128.h</filename> provides APIs to process and
- generate 128-bit ID values. The 128-bit ID values processed and
- generated by these APIs are a generalization of OSF UUIDs as
- defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
- 4122</ulink> but use a simpler string format. These functions
- impose no structure on the used IDs, much unlike OSF UUIDs or
- Microsoft GUIDs, but are fully compatible with those types of IDs.
+ <para><filename>sd-id128.h</filename> provides APIs to process and generate 128-bit ID values. The
+ 128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by
+ <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> but use a simpler string format. These
+ functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
+ compatible with those types of IDs.
</para>
<para>See
int main(int argc, char **argv) {
puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
-}
- </programlisting>
+}</programlisting>
<para><function>SD_ID128_CONST_STR()</function> may be used to
convert constant 128-bit IDs into constant strings for output. The
}</programlisting>
<para><constant>SD_ID128_UUID_FORMAT_STR</constant> is similar to
- <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the
- "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
- </para>
+ <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the "<ulink
+ url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical
+ representation</ulink>". This formats the string based on <ulink
+ url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
+ Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
+ best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All 128-bit IDs
+ generated by the sd-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
<para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</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
+ <function>sd_id128_get_invocation()</function> always return UUID Variant 1 Version 4 compatible IDs.
+ <function>sd_id128_get_machine()</function> will also return a UUID Variant 1 Version 4 compatible ID on
+ new installations but might not on older. It is possible to convert the machine ID non-reversibly into a
+ UUID Variant 1 Version 4 compatible one. For more information, see
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It is
hence guaranteed that these 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
<filename>/dev/urandom</filename> kernel random number
generator.</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>Note that <function>sd_id128_randomize()</function> always returns a UUID Variant 1 Version 4
+ 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
<constant>NULL</constant> the function will validate the passed ID string, but not actually return it in parsed
form.</para>
+ <para>Note that when parsing 37 character UUIDs this is done strictly in Big Endian byte order,
+ i.e. according to <ulink url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1
+ rules, even if the UUID encodes a different variant. This matches behaviour in various other Linux
+ userspace tools. It's probably wise to avoid UUIDs of other variant types.</para>
+
<para>For more information about the <literal>sd_id128_t</literal>
type see
<citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
#define SD_ID128_FORMAT_STR "%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x"
#define SD_ID128_FORMAT_VAL(x) (x).bytes[0], (x).bytes[1], (x).bytes[2], (x).bytes[3], (x).bytes[4], (x).bytes[5], (x).bytes[6], (x).bytes[7], (x).bytes[8], (x).bytes[9], (x).bytes[10], (x).bytes[11], (x).bytes[12], (x).bytes[13], (x).bytes[14], (x).bytes[15]
-/* Like SD_ID128_FORMAT_STR, but formats as UUID, not in plain format */
+/* Like SD_ID128_FORMAT_STR, but formats as UUID, not in plain format (Strictly Big Endian byte order,
+ * i.e. treats everything as RFC4122 Variant 1 UUIDs, even if variant says otherwise, but matching other
+ * Linux userspace behaviour.) */
#define SD_ID128_UUID_FORMAT_STR "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x"
#define SD_ID128_CONST_STR(x) \
projects / thirdparty / systemd.git / commitdiff
