SD_ID128_FORMAT_STR(3)

1SD-ID128(3)                        sd-id128                        SD-ID128(3)
2
3
4

NAME

6       sd-id128, SD_ID128_ALLF, SD_ID128_CONST_STR, SD_ID128_FORMAT_STR,
7       SD_ID128_FORMAT_VAL, SD_ID128_MAKE, SD_ID128_MAKE_STR,
8       SD_ID128_MAKE_UUID_STR, SD_ID128_NULL, SD_ID128_UUID_FORMAT_STR,
9       sd_id128_equal, sd_id128_string_equal, sd_id128_in_set,
10       sd_id128_in_set_sentinel, sd_id128_in_setv, sd_id128_is_allf,
11       sd_id128_is_null, sd_id128_t - APIs for processing 128-bit IDs
12

SYNOPSIS

14       #include <systemd/sd-id128.h>
15
16       SD_ID128_ALLF
17
18       SD_ID128_NULL
19
20       SD_ID128_CONST_STR(id)
21
22       SD_ID128_FORMAT_STR
23
24       SD_ID128_FORMAT_VAL(id)
25
26       SD_ID128_MAKE(v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, vA, vB, vC, vD,
27       vE, vF)
28
29       SD_ID128_MAKE_STR(v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, vA, vB, vC,
30       vD, vE, vF)
31
32       SD_ID128_MAKE_UUID_STR(v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, vA, vB,
33       vC, vD, vE, vF)
34
35       SD_ID128_UUID_FORMAT_STR
36
37       int sd_id128_equal(sd_id128_t a, sd_id128_t b);
38
39       int sd_id128_string_equal(const char *a, sd_id128_t b);
40
41       int sd_id128_is_null(sd_id128_t id);
42
43       int sd_id128_is_allf(sd_id128_t id);
44
45       int sd_id128_in_setv(sd_id128_t id, va_list ap);
46
47       int sd_id128_in_set_sentinel(sd_id128_t id, ..., SD_ID128_NULL);
48
49       int sd_id128_in_set(sd_id128_t id, ...);
50
51       pkg-config --cflags --libs libsystemd
52

DESCRIPTION

54       sd-id128.h provides APIs to generate, convert, and compare 128-bit ID
55       values. The 128-bit ID values processed and generated by these APIs are
56       a generalization of OSF UUIDs as defined by RFC 4122[1] but use a
57       simpler string format. These functions impose no structure on the used
58       IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
59       compatible with those types of IDs.
60
61       A 128-bit ID is implemented as the following union type:
62
63           typedef union sd_id128 {
64             uint8_t bytes[16];
65             uint64_t qwords[2];
66           } sd_id128_t;
67
68       This union type allows accessing the 128-bit ID as 16 separate bytes or
69       two 64-bit words. It is generally safer to access the ID components by
70       their 8-bit array to avoid endianness issues. This union is intended to
71       be passed by value (as opposed to pass-by-reference) and may be
72       directly manipulated by clients.
73
74       A couple of macros are defined to denote and decode 128-bit IDs:
75
76       SD_ID128_MAKE() is used to write a constant ID in source code. A
77       commonly used idiom is to assign a name to an ID using this macro:
78
79           #define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)
80
81       SD_ID128_NULL defines an ID consisting of only NUL bytes (i.e. all bits
82       off).
83
84       SD_ID128_ALLF defines an ID consisting of only 0xFF bytes (i.e. all
85       bits on).
86
87       SD_ID128_MAKE_STR() is similar to SD_ID128_MAKE(), but creates a const
88       char* expression that can be conveniently used in message formats and
89       such:
90
91           #include <stdio.h>
92           #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)
93
94           int main(int argc, char **argv) {
95             puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
96           }
97
98       SD_ID128_CONST_STR() converts constant IDs into constant strings for
99       output. The following example code will output the string
100       "fc2e22bc6ee647b6b90729ab34a250b1":
101
102           int main(int argc, char *argv[]) {
103             puts("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
104           }
105
106       SD_ID128_FORMAT_STR and SD_ID128_FORMAT_VAL() is used to format an ID
107       in a printf(3) format string, as shown in the following example:
108
109           int main(int argc, char *argv[]) {
110             sd_id128_t id;
111             id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
112             printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id));
113             return 0;
114           }
115
116       SD_ID128_UUID_FORMAT_STR and SD_ID128_MAKE_UUID_STR() are similar to
117       SD_ID128_FORMAT_STR and SD_ID128_MAKE_STR(), but include separating
118       hyphens to conform to the "canonical representation[2]". They format
119       the string based on RFC4122[1] Variant 1 rules, i.e. converting from
120       Big Endian byte order. This matches behaviour of most other Linux
121       userspace infrastructure. It's probably best to avoid UUIDs of other
122       variants, in order to avoid unnecessary ambiguities. All 128-bit IDs
123       generated by the sd-id128 APIs strictly conform to Variant 1 Version 4
124       UUIDs, as per RFC 4122.
125
126       sd_id128_equal() compares two 128-bit IDs:
127
128           int main(int argc, char *argv[]) {
129             sd_id128_t a, b, c;
130             a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
131             b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e);
132             c = a;
133             assert(sd_id128_equal(a, c));
134             assert(!sd_id128_equal(a, b));
135             return 0;
136           }
137
138       sd_id128_string_equal() is similar to sd_id128_equal(), but the first
139       ID is formatted as const char*. The same restrictions apply as to the
140       first argument of sd_id128_from_string().
141
142       sd_id128_is_null() checks if an ID consists of only NUL bytes:
143
144           assert(sd_id128_is_null(SD_ID128_NULL));
145
146       Similarly, sd_id128_is_allf() checks if an ID consists of only 0xFF
147       bytes (all bits on):
148
149           assert(sd_id128_is_allf(SD_ID128_ALLF));
150
151       sd_id128_in_set_sentinel() takes a list of IDs and returns true if the
152       first argument is equal to any of the subsequent arguments. The
153       argument list is terminated by an SD_ID128_NULL sentinel, which must be
154       present.
155
156       sd_id128_in_set() is a convenience function that takes a list of IDs
157       and returns true if the first argument is equal to any of the
158       subsequent arguments:
159
160           int main(int argc, char *argv[]) {
161             sd_id12_t a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
162             assert(sd_id128_in_set(a, a));
163             assert(sd_id128_in_set(a, a, a));
164             assert(!sd_id128_in_set(a));
165             assert(!sd_id128_in_set(a,
166                                     SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e)
167                                     SD_ID128_MAKE(2f,88,28,5f,9c,44,09,9d,d7,15,77,04,bc,85,7e,e3)
168                                     SD_ID128_ALLF));
169             return 0;
170           }
171
172       sd_id128_in_set() is defined as a macro over
173       sd_id128_in_set_sentinel(), adding the SD_ID128_NULL sentinel
174       automatically. Since sd_id128_in_set_sentinel() uses SD_ID128_NULL as
175       the sentinel, SD_ID128_NULL cannot be otherwise placed in the argument
176       list.
177
178       sd_id128_in_setv() is similar to sd_id128_in_set_sentinel(), but takes
179       a struct varargs argument.
180
181       New randomized IDs may be generated with systemd-id128(1)'s new
182       command.
183
184       See sd_id128_to_string(3), sd_id128_randomize(3) and
185       sd_id128_get_machine(3) for information about other implemented
186       functions.
187

NOTES

189       These APIs are implemented as a shared library, which can be compiled
190       and linked to with the libsystemd pkg-config(1) file.
191

NOTES

198        1. RFC 4122
199           https://tools.ietf.org/html/rfc4122
200
201        2. canonical representation
202           https://en.wikipedia.org/wiki/Universally_unique_identifier#Format
203
204
205
206systemd 253                                                        SD-ID128(3)

NAME

SYNOPSIS

DESCRIPTION

NOTES

SEE ALSO

NOTES