man/sd-id128.xml

   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 -->
   5
   6 <refentry id="sd-id128"
   7   xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd-id128</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd-id128</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  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>
  39   </refnamediv>
  40
  41   <refsynopsisdiv>
  42     <funcsynopsis>
  43       <funcsynopsisinfo>#include &lt;systemd/sd-id128.h&gt;</funcsynopsisinfo>
  44
  45       <para>
  46         <constant>SD_ID128_ALLF</constant>
  47       </para>
  48       <para>
  49         <constant>SD_ID128_NULL</constant>
  50       </para>
  51       <para>
  52         <constant>SD_ID128_CONST_STR(<replaceable>id</replaceable>)</constant>
  53       </para>
  54       <para>
  55         <constant>SD_ID128_FORMAT_STR</constant>
  56       </para>
  57       <para>
  58         <constant>SD_ID128_FORMAT_VAL(<replaceable>id</replaceable>)</constant>
  59       </para>
  60       <para>
  61         <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>
  62       </para>
  63       <para>
  64         <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>
  65       </para>
  66       <para>
  67         <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>
  68       </para>
  69       <para>
  70         <constant>SD_ID128_UUID_FORMAT_STR</constant>
  71       </para>
  72
  73       <funcprototype>
  74         <funcdef>int <function>sd_id128_equal</function></funcdef>
  75         <paramdef>sd_id128_t <parameter>a</parameter></paramdef>
  76         <paramdef>sd_id128_t <parameter>b</parameter></paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>int <function>sd_id128_string_equal</function></funcdef>
  81         <paramdef>const char *<parameter>a</parameter></paramdef>
  82         <paramdef>sd_id128_t <parameter>b</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int <function>sd_id128_is_null</function></funcdef>
  87         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  88       </funcprototype>
  89
  90       <funcprototype>
  91         <funcdef>int <function>sd_id128_is_allf</function></funcdef>
  92         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  93       </funcprototype>
  94
  95       <funcprototype>
  96         <funcdef>int <function>sd_id128_in_setv</function></funcdef>
  97         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  98         <paramdef>va_list <parameter>ap</parameter></paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>int <function>sd_id128_in_set_sentinel</function></funcdef>
 103         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
 104         <paramdef>…</paramdef>
 105         <paramdef><parameter><constant>SD_ID128_NULL</constant></parameter></paramdef>
 106       </funcprototype>
 107
 108       <funcprototype>
 109         <funcdef>int <function>sd_id128_in_set</function></funcdef>
 110         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
 111         <paramdef>…</paramdef>
 112       </funcprototype>
 113     </funcsynopsis>
 114
 115     <cmdsynopsis>
 116       <command>pkg-config --cflags --libs libsystemd</command>
 117     </cmdsynopsis>
 118
 119   </refsynopsisdiv>
 120
 121   <refsect1>
 122     <title>Description</title>
 123
 124     <para><filename>sd-id128.h</filename> is part of
 125     <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
 126     provides APIs to generate, convert, and compare 128-bit ID values. The 128-bit ID values processed and
 127     generated by these APIs are a generalization of OSF UUIDs as defined by <ulink
 128     url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> but use a simpler string format. These
 129     functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
 130     compatible with those types of IDs.
 131     </para>
 132
 133     <para>A 128-bit ID is implemented as the following
 134     union type:</para>
 135
 136     <programlisting>typedef union sd_id128 {
 137   uint8_t bytes[16];
 138   uint64_t qwords[2];
 139 } sd_id128_t;</programlisting>
 140
 141     <para>This union type allows accessing the 128-bit ID as 16 separate bytes or two 64-bit words. It is
 142     generally safer to access the ID components by their 8-bit array to avoid endianness issues. This union
 143     is intended to be passed by value (as opposed to pass-by-reference) and may be directly manipulated by
 144     clients.</para>
 145
 146     <para>A couple of macros are defined to denote and decode 128-bit
 147     IDs:</para>
 148
 149     <para><function>SD_ID128_MAKE()</function> is used to write a constant ID in source code. A commonly used
 150     idiom is to assign a name to an ID using this macro:</para>
 151
 152     <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>
 153
 154     <para><constant>SD_ID128_NULL</constant> defines an ID consisting of only <constant>NUL</constant> bytes
 155     (i.e. all bits off).</para>
 156
 157     <para><constant>SD_ID128_ALLF</constant> defines an ID consisting of only <constant>0xFF</constant> bytes
 158     (i.e. all bits on).</para>
 159
 160     <para><function>SD_ID128_MAKE_STR()</function> is similar to <function>SD_ID128_MAKE()</function>, but
 161     creates a <type>const char*</type> expression that can be conveniently used in message formats and
 162     such:</para>
 163
 164     <programlisting>#include &lt;stdio.h&gt;
 165 #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)
 166
 167 int main(int argc, char **argv) {
 168   puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
 169 }</programlisting>
 170
 171     <para><function>SD_ID128_CONST_STR()</function> converts constant IDs into constant strings for
 172     output. The following example code will output the string "fc2e22bc6ee647b6b90729ab34a250b1":</para>
 173     <programlisting>int main(int argc, char *argv[]) {
 174   puts("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
 175 }</programlisting>
 176
 177     <para><constant>SD_ID128_FORMAT_STR</constant> and <function>SD_ID128_FORMAT_VAL()</function> is used to
 178     format an ID in a <citerefentry
 179     project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> format
 180     string, as shown in the following example:</para>
 181
 182     <programlisting>int main(int argc, char *argv[]) {
 183   sd_id128_t id;
 184   id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
 185   printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id));
 186   return 0;
 187 }</programlisting>
 188
 189     <para><constant>SD_ID128_UUID_FORMAT_STR</constant> and <function>SD_ID128_MAKE_UUID_STR()</function>
 190     are similar to
 191     <constant>SD_ID128_FORMAT_STR</constant> and <function>SD_ID128_MAKE_STR()</function>,
 192     but include separating hyphens to conform to the
 193     "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">UUID canonical representation</ulink>".
 194     They format the string based on <ulink
 195     url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
 196     Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
 197     best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All 128-bit IDs
 198     generated by the sd-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
 199
 200     <para><function>sd_id128_equal()</function> compares two 128-bit IDs:</para>
 201
 202     <programlisting>int main(int argc, char *argv[]) {
 203   sd_id128_t a, b, c;
 204   a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
 205   b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e);
 206   c = a;
 207   assert(sd_id128_equal(a, c));
 208   assert(!sd_id128_equal(a, b));
 209   return 0;
 210 }</programlisting>
 211
 212     <para><function>sd_id128_string_equal()</function> is similar to <function>sd_id128_equal()</function>,
 213     but the first ID is formatted as <type>const char*</type>. The same restrictions apply as to the first
 214     argument of <function>sd_id128_from_string()</function>.</para>
 215
 216     <para><function>sd_id128_is_null()</function> checks if an ID consists of only <constant>NUL</constant>
 217     bytes:</para>
 218
 219     <programlisting>assert(sd_id128_is_null(SD_ID128_NULL));</programlisting>
 220
 221     <para>Similarly, <function>sd_id128_is_allf()</function> checks if an ID consists of only
 222     <constant>0xFF</constant> bytes (all bits on):</para>
 223
 224     <programlisting>assert(sd_id128_is_allf(SD_ID128_ALLF));</programlisting>
 225
 226     <para><function>sd_id128_in_set_sentinel()</function> takes a list of IDs and returns true if the first
 227     argument is equal to any of the subsequent arguments. The argument list is terminated by an
 228     <constant>SD_ID128_NULL</constant> sentinel, which must be present.</para>
 229
 230     <para><function>sd_id128_in_set()</function> is a convenience function that takes a list of IDs and
 231     returns true if the first argument is equal to any of the subsequent arguments:</para>
 232
 233     <programlisting>int main(int argc, char *argv[]) {
 234   sd_id12_t a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
 235   assert(sd_id128_in_set(a, a));
 236   assert(sd_id128_in_set(a, a, a));
 237   assert(!sd_id128_in_set(a));
 238   assert(!sd_id128_in_set(a,
 239                           SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e)
 240                           SD_ID128_MAKE(2f,88,28,5f,9c,44,09,9d,d7,15,77,04,bc,85,7e,e3)
 241                           SD_ID128_ALLF));
 242   return 0;
 243 }
 244 </programlisting>
 245
 246     <para><function>sd_id128_in_set()</function> is defined as a macro over
 247     <function>sd_id128_in_set_sentinel()</function>, adding the <constant>SD_ID128_NULL</constant> sentinel
 248     automatically. Since <function>sd_id128_in_set_sentinel()</function> uses
 249     <constant>SD_ID128_NULL</constant> as the sentinel, <constant>SD_ID128_NULL</constant> cannot be
 250     otherwise placed in the argument list.</para>
 251
 252     <para><function>sd_id128_in_setv()</function> is similar to
 253     <function>sd_id128_in_set_sentinel()</function>, but takes a <structname>struct varargs</structname>
 254     argument.</para>
 255
 256     <para>New randomized IDs may be generated with
 257     <citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 258     <command>new</command> command.</para>
 259
 260     <para>See
 261     <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 262     <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 263     and
 264     <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 265     for information about other implemented functions.</para>
 266   </refsect1>
 267
 268   <xi:include href="libsystemd-pkgconfig.xml" />
 269
 270   <refsect1>
 271     <title>History</title>
 272     <para><function>sd_id128_equal()</function>,
 273     <function>sd_id128_string_equal()</function>,
 274     <function>sd_id128_is_null()</function>,
 275     <function>sd_id128_is_allf()</function>,
 276     <function>sd_id128_in_setv()</function>,
 277     <function>sd_id128_in_set_sentinel()</function>, and
 278     <function>sd_id128_in_set()</function> were added in version 252.</para>
 279   </refsect1>
 280
 281   <refsect1>
 282     <title>See Also</title>
 283     <para><simplelist type="inline">
 284       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 285       <member><citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 286       <member><citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 287       <member><citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 288       <member><citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 289       <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 290       <member><citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 291       <member><citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 292       <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 293     </simplelist></para>
 294   </refsect1>
 295
 296 </refentry>