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     </funcsynopsis>
  45
  46     <para>
  47       <constant>SD_ID128_ALLF</constant>
  48     </para>
  49     <para>
  50       <constant>SD_ID128_NULL</constant>
  51     </para>
  52     <para>
  53       <constant>SD_ID128_CONST_STR(<replaceable>id</replaceable>)</constant>
  54     </para>
  55     <para>
  56       <constant>SD_ID128_FORMAT_STR</constant>
  57     </para>
  58     <para>
  59       <constant>SD_ID128_FORMAT_VAL(<replaceable>id</replaceable>)</constant>
  60     </para>
  61     <para>
  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>
  63     </para>
  64     <para>
  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>
  66     </para>
  67     <para>
  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>
  69     </para>
  70     <para>
  71       <constant>SD_ID128_UUID_FORMAT_STR</constant>
  72     </para>
  73
  74     <funcsynopsis>
  75       <funcprototype>
  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>
  79       </funcprototype>
  80
  81       <funcprototype>
  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>
  85       </funcprototype>
  86
  87       <funcprototype>
  88         <funcdef>int <function>sd_id128_is_null</function></funcdef>
  89         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  90       </funcprototype>
  91
  92       <funcprototype>
  93         <funcdef>int <function>sd_id128_is_allf</function></funcdef>
  94         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  95       </funcprototype>
  96
  97       <funcprototype>
  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>
 101       </funcprototype>
 102
 103       <funcprototype>
 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>
 108       </funcprototype>
 109
 110       <funcprototype>
 111         <funcdef>int <function>sd_id128_in_set</function></funcdef>
 112         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
 113         <paramdef>…</paramdef>
 114       </funcprototype>
 115     </funcsynopsis>
 116
 117     <cmdsynopsis>
 118       <command>pkg-config --cflags --libs libsystemd</command>
 119     </cmdsynopsis>
 120
 121   </refsynopsisdiv>
 122
 123   <refsect1>
 124     <title>Description</title>
 125
 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.
 133     </para>
 134
 135     <para>A 128-bit ID is implemented as the following
 136     union type:</para>
 137
 138     <programlisting>typedef union sd_id128 {
 139   uint8_t bytes[16];
 140   uint64_t qwords[2];
 141 } sd_id128_t;</programlisting>
 142
 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
 146     clients.</para>
 147
 148     <para>A couple of macros are defined to denote and decode 128-bit
 149     IDs:</para>
 150
 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>
 153
 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>
 155
 156     <para><constant>SD_ID128_NULL</constant> defines an ID consisting of only <constant>NUL</constant> bytes
 157     (i.e. all bits off).</para>
 158
 159     <para><constant>SD_ID128_ALLF</constant> defines an ID consisting of only <constant>0xFF</constant> bytes
 160     (i.e. all bits on).</para>
 161
 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
 164     such:</para>
 165
 166     <programlisting>#include &lt;stdio.h&gt;
 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)
 168
 169 int main(int argc, char **argv) {
 170   puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
 171 }</programlisting>
 172
 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));
 177 }</programlisting>
 178
 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>
 183
 184     <programlisting>int main(int argc, char *argv[]) {
 185   sd_id128_t id;
 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));
 188   return 0;
 189 }</programlisting>
 190
 191     <para><constant>SD_ID128_UUID_FORMAT_STR</constant> and <function>SD_ID128_MAKE_UUID_STR()</function>
 192     are similar to
 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>
 201
 202     <para><function>sd_id128_equal()</function> compares two 128-bit IDs:</para>
 203
 204     <programlisting>int main(int argc, char *argv[]) {
 205   sd_id128_t a, b, c;
 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);
 208   c = a;
 209   assert(sd_id128_equal(a, c));
 210   assert(!sd_id128_equal(a, b));
 211   return 0;
 212 }</programlisting>
 213
 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>
 217
 218     <para><function>sd_id128_is_null()</function> checks if an ID consists of only <constant>NUL</constant>
 219     bytes:</para>
 220
 221     <programlisting>assert(sd_id128_is_null(SD_ID128_NULL));</programlisting>
 222
 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>
 225
 226     <programlisting>assert(sd_id128_is_allf(SD_ID128_ALLF));</programlisting>
 227
 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>
 231
 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>
 234
 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)
 243                           SD_ID128_ALLF));
 244   return 0;
 245 }
 246 </programlisting>
 247
 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>
 253
 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>
 256     argument.</para>
 257
 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>
 261
 262     <para>See
 263     <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 264     <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 265     and
 266     <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 267     for information about other implemented functions.</para>
 268   </refsect1>
 269
 270   <xi:include href="libsystemd-pkgconfig.xml" />
 271
 272   <refsect1>
 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>
 281   </refsect1>
 282
 283   <refsect1>
 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>
 295     </simplelist></para>
 296   </refsect1>
 297
 298 </refentry>