1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd-id128"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd-id128
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd-id128
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd-id128
</refname>
21 <refname>SD_ID128_ALLF
</refname>
22 <refname>SD_ID128_CONST_STR
</refname>
23 <refname>SD_ID128_FORMAT_STR
</refname>
24 <refname>SD_ID128_FORMAT_VAL
</refname>
25 <refname>SD_ID128_MAKE
</refname>
26 <refname>SD_ID128_MAKE_STR
</refname>
27 <refname>SD_ID128_MAKE_UUID_STR
</refname>
28 <refname>SD_ID128_NULL
</refname>
29 <refname>SD_ID128_UUID_FORMAT_STR
</refname>
30 <refname>sd_id128_equal
</refname>
31 <refname>sd_id128_in_set
</refname>
32 <refname>sd_id128_in_set_sentinel
</refname>
33 <refname>sd_id128_in_setv
</refname>
34 <refname>sd_id128_is_allf
</refname>
35 <refname>sd_id128_is_null
</refname>
36 <refname>sd_id128_t
</refname>
37 <refpurpose>APIs for processing
128-bit IDs
</refpurpose>
42 <funcsynopsisinfo>#include
<systemd/sd-id128.h
></funcsynopsisinfo>
46 <command>pkg-config --cflags --libs libsystemd
</command>
52 <title>Description
</title>
54 <para><filename>sd-id128.h
</filename> provides APIs to process and generate
128-bit ID values. The
55 128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by
56 <ulink url=
"https://tools.ietf.org/html/rfc4122">RFC
4122</ulink> but use a simpler string format. These
57 functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
58 compatible with those types of IDs.
62 <citerefentry><refentrytitle>sd_id128_to_string
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
63 <citerefentry><refentrytitle>sd_id128_randomize
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
65 <citerefentry><refentrytitle>sd_id128_get_machine
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
66 for more information about the implemented functions.
</para>
68 <para>A
128-bit ID is implemented as the following
71 <programlisting>typedef union sd_id128 {
74 } sd_id128_t;
</programlisting>
76 <para>This union type allows accessing the
128-bit ID as
16
77 separate bytes or two
64-bit words. It is generally safer to
78 access the ID components by their
8-bit array to avoid endianness
79 issues. This union is intended to be passed call-by-value (as
80 opposed to call-by-reference) and may be directly manipulated by
83 <para>A couple of macros are defined to denote and decode
128-bit
86 <para><function>SD_ID128_MAKE()
</function> may be used to denote a
87 constant
128-bit ID in source code. A commonly used idiom is to
88 assign a name to a
128-bit ID using this macro:
</para>
90 <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,
2e,
22,bc,
6e,e6,
47,b6,b9,
07,
29,ab,
34,a2,
50,b1)
</programlisting>
92 <para><constant>SD_ID128_NULL
</constant> may be used to refer to the
128-bit ID consisting of only
93 <constant>NUL
</constant> bytes (i.e. all bits off).
</para>
95 <para><constant>SD_ID128_ALLF
</constant> may be used to refer to the
128-bit ID consisting of only
96 <constant>0xFF</constant> bytes (i.e. all bits on).
</para>
98 <para><function>SD_ID128_MAKE_STR()
</function> is similar to
<function>SD_ID128_MAKE()
</function>, but creates a
99 <type>const char*
</type> expression that can be conveniently used in message formats and such:
</para>
101 <programlisting>#include
<stdio.h
>
102 #define SD_MESSAGE_COREDUMP_STR SD_ID128_MAKE_STR(fc,
2e,
22,bc,
6e,e6,
47,b6,b9,
07,
29,ab,
34,a2,
50,b1)
104 int main(int argc, char **argv) {
105 puts(
"Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
108 <para><function>SD_ID128_CONST_STR()
</function> may be used to
109 convert constant
128-bit IDs into constant strings for output. The
110 following example code will output the string
111 "fc2e22bc6ee647b6b90729ab34a250b1":
</para>
112 <programlisting>int main(int argc, char *argv[]) {
113 puts(
"Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
116 <para><constant>SD_ID128_FORMAT_STR
</constant> and
<function>SD_ID128_FORMAT_VAL()
</function> may
117 be used to format a
128-bit ID in a
118 <citerefentry project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
119 format string, as shown in the following example:
</para>
121 <programlisting>int main(int argc, char *argv[]) {
123 id = SD_ID128_MAKE(ee,
89,be,
71,bd,
6e,
43,d6,
91,e6,c5,
5d,eb,
03,
02,
07);
124 printf(
"The ID encoded in this C file is " SD_ID128_FORMAT_STR
".\n", SD_ID128_FORMAT_VAL(id));
128 <para><constant>SD_ID128_UUID_FORMAT_STR
</constant> and
<function>SD_ID128_MAKE_UUID_STR()
</function>
130 <constant>SD_ID128_FORMAT_STR
</constant> and
<function>SD_ID128_MAKE_STR()
</function>,
131 but include separating hyphens to conform to the
132 "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format
">canonical representation</ulink>".
133 They format the string based on
<ulink
134 url=
"https://tools.ietf.org/html/rfc4122">RFC4122
</ulink> Variant
1 rules, i.e. converting from Big
135 Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
136 best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All
128-bit IDs
137 generated by the sd-id128 APIs strictly conform to Variant
1 Version
4 UUIDs, as per RFC
4122.
</para>
139 <para>Use
<function>sd_id128_equal()
</function> to compare two
128-bit IDs:
</para>
141 <programlisting>int main(int argc, char *argv[]) {
143 a = SD_ID128_MAKE(ee,
89,be,
71,bd,
6e,
43,d6,
91,e6,c5,
5d,eb,
03,
02,
07);
144 b = SD_ID128_MAKE(f2,
28,
88,
9c,
5f,
09,
44,
15,
9d,d7,
04,
77,
58,cb,e7,
3e);
146 assert(sd_id128_equal(a, c));
147 assert(!sd_id128_equal(a, b));
151 <para>Use
<function>sd_id128_is_null()
</function> to check if an
128-bit ID consists of only
152 <constant>NUL
</constant> bytes:
</para>
154 <programlisting>assert(sd_id128_is_null(SD_ID128_NULL));
</programlisting>
156 <para>Similarly, use
<function>sd_id128_is_allf()
</function> to check if an
128-bit ID consists of only
157 <constant>0xFF</constant> bytes (all bits on):
</para>
159 <programlisting>assert(sd_id128_is_allf(SD_ID128_ALLF));
</programlisting>
161 <para>For convenience,
<function>sd_id128_in_set()
</function> takes a list of IDs and
162 returns true if any are equal to the first argument:
</para>
164 <programlisting>int main(int argc, char *argv[]) {
165 sd_id12_t a = SD_ID128_MAKE(ee,
89,be,
71,bd,
6e,
43,d6,
91,e6,c5,
5d,eb,
03,
02,
07);
166 assert(sd_id128_in_set(a, a));
167 assert(sd_id128_in_set(a, a, a));
168 assert(!sd_id128_in_set(a));
169 assert(!sd_id128_in_set(a,
170 SD_ID128_MAKE(f2,
28,
88,
9c,
5f,
09,
44,
15,
9d,d7,
04,
77,
58,cb,e7,
3e)
171 SD_ID128_MAKE(
2f,
88,
28,
5f,
9c,
44,
09,
9d,d7,
15,
77,
04,bc,
85,
7e,e3)
177 <para><function>sd_id128_in_set()
</function> is defined as a macro over
178 <function>sd_id128_in_set_sentinel()
</function>, adding the
<constant>SD_ID128_NULL
</constant>
179 sentinel. Since
<function>sd_id128_in_set_sentinel()
</function> uses
<constant>SD_ID128_NULL
</constant>
180 as the sentinel,
<constant>SD_ID128_NULL
</constant> cannot be otherwise placed in the argument list.
183 <para><function>sd_id128_in_setv()
</function> is similar to
184 <function>sd_id128_in_set_sentinel()
</function>, but takes a
<structname>struct varargs
</structname>
187 <para>Note that new, randomized IDs may be generated with
188 <citerefentry><refentrytitle>systemd-id128
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
189 <command>new
</command> command.
</para>
192 <xi:include href=
"libsystemd-pkgconfig.xml" />
195 <title>See Also
</title>
197 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>sd_id128_to_string
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
199 <citerefentry><refentrytitle>sd_id128_randomize
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>sd_id128_get_machine
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
201 <citerefentry project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
202 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
203 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
204 <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
205 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>