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.5/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_string_equal
</refname>
32 <refname>sd_id128_in_set
</refname>
33 <refname>sd_id128_in_set_sentinel
</refname>
34 <refname>sd_id128_in_setv
</refname>
35 <refname>sd_id128_is_allf
</refname>
36 <refname>sd_id128_is_null
</refname>
37 <refname>sd_id128_t
</refname>
38 <refpurpose>APIs for processing
128-bit IDs
</refpurpose>
43 <funcsynopsisinfo>#include
<systemd/sd-id128.h
></funcsynopsisinfo>
47 <constant>SD_ID128_ALLF
</constant>
50 <constant>SD_ID128_NULL
</constant>
53 <constant>SD_ID128_CONST_STR(
<replaceable>id
</replaceable>)
</constant>
56 <constant>SD_ID128_FORMAT_STR
</constant>
59 <constant>SD_ID128_FORMAT_VAL(
<replaceable>id
</replaceable>)
</constant>
62 <constant>SD_ID128_MAKE(
<replaceable>v0
</replaceable>,
<replaceable>v1
</replaceable>,
<replaceable>v2
</replaceable>,
<replaceable>v3
</replaceable>,
<replaceable>v4
</replaceable>,
<replaceable>v5
</replaceable>,
<replaceable>v6
</replaceable>,
<replaceable>v7
</replaceable>,
<replaceable>v8
</replaceable>,
<replaceable>v9
</replaceable>,
<replaceable>vA
</replaceable>,
<replaceable>vB
</replaceable>,
<replaceable>vC
</replaceable>,
<replaceable>vD
</replaceable>,
<replaceable>vE
</replaceable>,
<replaceable>vF
</replaceable>)
</constant>
65 <constant>SD_ID128_MAKE_STR(
<replaceable>v0
</replaceable>,
<replaceable>v1
</replaceable>,
<replaceable>v2
</replaceable>,
<replaceable>v3
</replaceable>,
<replaceable>v4
</replaceable>,
<replaceable>v5
</replaceable>,
<replaceable>v6
</replaceable>,
<replaceable>v7
</replaceable>,
<replaceable>v8
</replaceable>,
<replaceable>v9
</replaceable>,
<replaceable>vA
</replaceable>,
<replaceable>vB
</replaceable>,
<replaceable>vC
</replaceable>,
<replaceable>vD
</replaceable>,
<replaceable>vE
</replaceable>,
<replaceable>vF
</replaceable>)
</constant>
68 <constant>SD_ID128_MAKE_UUID_STR(
<replaceable>v0
</replaceable>,
<replaceable>v1
</replaceable>,
<replaceable>v2
</replaceable>,
<replaceable>v3
</replaceable>,
<replaceable>v4
</replaceable>,
<replaceable>v5
</replaceable>,
<replaceable>v6
</replaceable>,
<replaceable>v7
</replaceable>,
<replaceable>v8
</replaceable>,
<replaceable>v9
</replaceable>,
<replaceable>vA
</replaceable>,
<replaceable>vB
</replaceable>,
<replaceable>vC
</replaceable>,
<replaceable>vD
</replaceable>,
<replaceable>vE
</replaceable>,
<replaceable>vF
</replaceable>)
</constant>
71 <constant>SD_ID128_UUID_FORMAT_STR
</constant>
76 <funcdef>int
<function>sd_id128_equal
</function></funcdef>
77 <paramdef>sd_id128_t
<parameter>a
</parameter></paramdef>
78 <paramdef>sd_id128_t
<parameter>b
</parameter></paramdef>
82 <funcdef>int
<function>sd_id128_string_equal
</function></funcdef>
83 <paramdef>const char *
<parameter>a
</parameter></paramdef>
84 <paramdef>sd_id128_t
<parameter>b
</parameter></paramdef>
88 <funcdef>int
<function>sd_id128_is_null
</function></funcdef>
89 <paramdef>sd_id128_t
<parameter>id
</parameter></paramdef>
93 <funcdef>int
<function>sd_id128_is_allf
</function></funcdef>
94 <paramdef>sd_id128_t
<parameter>id
</parameter></paramdef>
98 <funcdef>int
<function>sd_id128_in_setv
</function></funcdef>
99 <paramdef>sd_id128_t
<parameter>id
</parameter></paramdef>
100 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
104 <funcdef>int
<function>sd_id128_in_set_sentinel
</function></funcdef>
105 <paramdef>sd_id128_t
<parameter>id
</parameter></paramdef>
106 <paramdef>…
</paramdef>
107 <paramdef><parameter><constant>SD_ID128_NULL
</constant></parameter></paramdef>
111 <funcdef>int
<function>sd_id128_in_set
</function></funcdef>
112 <paramdef>sd_id128_t
<parameter>id
</parameter></paramdef>
113 <paramdef>…
</paramdef>
118 <command>pkg-config --cflags --libs libsystemd
</command>
124 <title>Description
</title>
126 <para><filename>sd-id128.h
</filename> is part of
127 <citerefentry><refentrytitle>libsystemd
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
128 provides APIs to generate, convert, and compare
128-bit ID values. The
128-bit ID values processed and
129 generated by these APIs are a generalization of OSF UUIDs as defined by
<ulink
130 url=
"https://tools.ietf.org/html/rfc4122">RFC
4122</ulink> but use a simpler string format. These
131 functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
132 compatible with those types of IDs.
135 <para>A
128-bit ID is implemented as the following
138 <programlisting>typedef union sd_id128 {
141 } sd_id128_t;
</programlisting>
143 <para>This union type allows accessing the
128-bit ID as
16 separate bytes or two
64-bit words. It is
144 generally safer to access the ID components by their
8-bit array to avoid endianness issues. This union
145 is intended to be passed by value (as opposed to pass-by-reference) and may be directly manipulated by
148 <para>A couple of macros are defined to denote and decode
128-bit
151 <para><function>SD_ID128_MAKE()
</function> is used to write a constant ID in source code. A commonly used
152 idiom is to assign a name to an ID using this macro:
</para>
154 <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>
156 <para><constant>SD_ID128_NULL
</constant> defines an ID consisting of only
<constant>NUL
</constant> bytes
157 (i.e. all bits off).
</para>
159 <para><constant>SD_ID128_ALLF
</constant> defines an ID consisting of only
<constant>0xFF</constant> bytes
160 (i.e. all bits on).
</para>
162 <para><function>SD_ID128_MAKE_STR()
</function> is similar to
<function>SD_ID128_MAKE()
</function>, but
163 creates a
<type>const char*
</type> expression that can be conveniently used in message formats and
166 <programlisting>#include
<stdio.h
>
167 #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)
169 int main(int argc, char **argv) {
170 puts(
"Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
173 <para><function>SD_ID128_CONST_STR()
</function> converts constant IDs into constant strings for
174 output. The following example code will output the string
"fc2e22bc6ee647b6b90729ab34a250b1":
</para>
175 <programlisting>int main(int argc, char *argv[]) {
176 puts(
"Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
179 <para><constant>SD_ID128_FORMAT_STR
</constant> and
<function>SD_ID128_FORMAT_VAL()
</function> is used to
180 format an ID in a
<citerefentry
181 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry> format
182 string, as shown in the following example:
</para>
184 <programlisting>int main(int argc, char *argv[]) {
186 id = SD_ID128_MAKE(ee,
89,be,
71,bd,
6e,
43,d6,
91,e6,c5,
5d,eb,
03,
02,
07);
187 printf(
"The ID encoded in this C file is " SD_ID128_FORMAT_STR
".\n", SD_ID128_FORMAT_VAL(id));
191 <para><constant>SD_ID128_UUID_FORMAT_STR
</constant> and
<function>SD_ID128_MAKE_UUID_STR()
</function>
193 <constant>SD_ID128_FORMAT_STR
</constant> and
<function>SD_ID128_MAKE_STR()
</function>,
194 but include separating hyphens to conform to the
195 "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format
">UUID canonical representation</ulink>".
196 They format the string based on
<ulink
197 url=
"https://tools.ietf.org/html/rfc4122">RFC4122
</ulink> Variant
1 rules, i.e. converting from Big
198 Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
199 best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All
128-bit IDs
200 generated by the sd-id128 APIs strictly conform to Variant
1 Version
4 UUIDs, as per RFC
4122.
</para>
202 <para><function>sd_id128_equal()
</function> compares two
128-bit IDs:
</para>
204 <programlisting>int main(int argc, char *argv[]) {
206 a = SD_ID128_MAKE(ee,
89,be,
71,bd,
6e,
43,d6,
91,e6,c5,
5d,eb,
03,
02,
07);
207 b = SD_ID128_MAKE(f2,
28,
88,
9c,
5f,
09,
44,
15,
9d,d7,
04,
77,
58,cb,e7,
3e);
209 assert(sd_id128_equal(a, c));
210 assert(!sd_id128_equal(a, b));
214 <para><function>sd_id128_string_equal()
</function> is similar to
<function>sd_id128_equal()
</function>,
215 but the first ID is formatted as
<type>const char*
</type>. The same restrictions apply as to the first
216 argument of
<function>sd_id128_from_string()
</function>.
</para>
218 <para><function>sd_id128_is_null()
</function> checks if an ID consists of only
<constant>NUL
</constant>
221 <programlisting>assert(sd_id128_is_null(SD_ID128_NULL));
</programlisting>
223 <para>Similarly,
<function>sd_id128_is_allf()
</function> checks if an ID consists of only
224 <constant>0xFF</constant> bytes (all bits on):
</para>
226 <programlisting>assert(sd_id128_is_allf(SD_ID128_ALLF));
</programlisting>
228 <para><function>sd_id128_in_set_sentinel()
</function> takes a list of IDs and returns true if the first
229 argument is equal to any of the subsequent arguments. The argument list is terminated by an
230 <constant>SD_ID128_NULL
</constant> sentinel, which must be present.
</para>
232 <para><function>sd_id128_in_set()
</function> is a convenience function that takes a list of IDs and
233 returns true if the first argument is equal to any of the subsequent arguments:
</para>
235 <programlisting>int main(int argc, char *argv[]) {
236 sd_id12_t a = SD_ID128_MAKE(ee,
89,be,
71,bd,
6e,
43,d6,
91,e6,c5,
5d,eb,
03,
02,
07);
237 assert(sd_id128_in_set(a, a));
238 assert(sd_id128_in_set(a, a, a));
239 assert(!sd_id128_in_set(a));
240 assert(!sd_id128_in_set(a,
241 SD_ID128_MAKE(f2,
28,
88,
9c,
5f,
09,
44,
15,
9d,d7,
04,
77,
58,cb,e7,
3e)
242 SD_ID128_MAKE(
2f,
88,
28,
5f,
9c,
44,
09,
9d,d7,
15,
77,
04,bc,
85,
7e,e3)
248 <para><function>sd_id128_in_set()
</function> is defined as a macro over
249 <function>sd_id128_in_set_sentinel()
</function>, adding the
<constant>SD_ID128_NULL
</constant> sentinel
250 automatically. Since
<function>sd_id128_in_set_sentinel()
</function> uses
251 <constant>SD_ID128_NULL
</constant> as the sentinel,
<constant>SD_ID128_NULL
</constant> cannot be
252 otherwise placed in the argument list.
</para>
254 <para><function>sd_id128_in_setv()
</function> is similar to
255 <function>sd_id128_in_set_sentinel()
</function>, but takes a
<structname>struct varargs
</structname>
258 <para>New randomized IDs may be generated with
259 <citerefentry><refentrytitle>systemd-id128
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
260 <command>new
</command> command.
</para>
263 <citerefentry><refentrytitle>sd_id128_to_string
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>sd_id128_randomize
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
266 <citerefentry><refentrytitle>sd_id128_get_machine
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
267 for information about other implemented functions.
</para>
270 <xi:include href=
"libsystemd-pkgconfig.xml" />
273 <title>History
</title>
274 <para><function>sd_id128_equal()
</function>,
275 <function>sd_id128_string_equal()
</function>,
276 <function>sd_id128_is_null()
</function>,
277 <function>sd_id128_is_allf()
</function>,
278 <function>sd_id128_in_setv()
</function>,
279 <function>sd_id128_in_set_sentinel()
</function>, and
280 <function>sd_id128_in_set()
</function> were added in version
252.
</para>
284 <title>See Also
</title>
285 <para><simplelist type=
"inline">
286 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
287 <member><citerefentry><refentrytitle>sd_id128_to_string
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
288 <member><citerefentry><refentrytitle>sd_id128_randomize
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
289 <member><citerefentry><refentrytitle>sd_id128_get_machine
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
290 <member><citerefentry project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
291 <member><citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
292 <member><citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
293 <member><citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
294 <member><citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>