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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   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_t</refname>
  22     <refname>SD_ID128_MAKE</refname>
  23     <refname>SD_ID128_MAKE_STR</refname>
  24     <refname>SD_ID128_NULL</refname>
  25     <refname>SD_ID128_CONST_STR</refname>
  26     <refname>SD_ID128_FORMAT_STR</refname>
  27     <refname>SD_ID128_UUID_FORMAT_STR</refname>
  28     <refname>SD_ID128_FORMAT_VAL</refname>
  29     <refname>sd_id128_equal</refname>
  30     <refname>sd_id128_is_null</refname>
  31     <refpurpose>APIs for processing 128-bit IDs</refpurpose>
  32   </refnamediv>
  33
  34   <refsynopsisdiv>
  35     <funcsynopsis>
  36       <funcsynopsisinfo>#include &lt;systemd/sd-id128.h&gt;</funcsynopsisinfo>
  37     </funcsynopsis>
  38
  39     <cmdsynopsis>
  40       <command>pkg-config --cflags --libs libsystemd</command>
  41     </cmdsynopsis>
  42
  43   </refsynopsisdiv>
  44
  45   <refsect1>
  46     <title>Description</title>
  47
  48     <para><filename>sd-id128.h</filename> provides APIs to process and
  49     generate 128-bit ID values. The 128-bit ID values processed and
  50     generated by these APIs are a generalization of OSF UUIDs as
  51     defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
  52     4122</ulink> but use a simpler string format. These functions
  53     impose no structure on the used IDs, much unlike OSF UUIDs or
  54     Microsoft GUIDs, but are fully compatible with those types of IDs.
  55     </para>
  56
  57     <para>See
  58     <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  59     <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  60     and
  61     <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  62     for more information about the implemented functions.</para>
  63
  64     <para>A 128-bit ID is implemented as the following
  65     union type:</para>
  66
  67     <programlisting>typedef union sd_id128 {
  68         uint8_t bytes[16];
  69         uint64_t qwords[2];
  70 } sd_id128_t;</programlisting>
  71
  72     <para>This union type allows accessing the 128-bit ID as 16
  73     separate bytes or two 64-bit words. It is generally safer to
  74     access the ID components by their 8-bit array to avoid endianness
  75     issues. This union is intended to be passed call-by-value (as
  76     opposed to call-by-reference) and may be directly manipulated by
  77     clients.</para>
  78
  79     <para>A couple of macros are defined to denote and decode 128-bit
  80     IDs:</para>
  81
  82     <para><function>SD_ID128_MAKE()</function> may be used to denote a
  83     constant 128-bit ID in source code. A commonly used idiom is to
  84     assign a name to a 128-bit ID using this macro:</para>
  85
  86     <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>
  87
  88     <para><function>SD_ID128_NULL</function> may be used to refer to the 128bit ID consisting of only NUL
  89     bytes.</para>
  90
  91     <para><function>SD_ID128_MAKE_STR()</function> is similar to <function>SD_ID128_MAKE()</function>, but creates a
  92     <type>const char*</type> expression that can be conveniently used in message formats and such:</para>
  93
  94     <programlisting>#include &lt;stdio.h&gt;
  95 #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)
  96
  97 int main(int argc, char **argv) {
  98         puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
  99 }
 100     </programlisting>
 101
 102     <para><function>SD_ID128_CONST_STR()</function> may be used to
 103     convert constant 128-bit IDs into constant strings for output. The
 104     following example code will output the string
 105     "fc2e22bc6ee647b6b90729ab34a250b1":</para>
 106     <programlisting>int main(int argc, char *argv[]) {
 107         puts("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
 108 }</programlisting>
 109
 110     <para><function>SD_ID128_FORMAT_STR()</function> and
 111     <function>SD_ID128_FORMAT_VAL()</function> may be used to format a
 112     128-bit ID in a
 113     <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114     format string, as shown in the following example:</para>
 115
 116     <programlisting>int main(int argc, char *argv[]) {
 117         sd_id128_t id;
 118         id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
 119         printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id));
 120         return 0;
 121 }</programlisting>
 122
 123     <para><function>SD_ID128_UUID_FORMAT_STR()</function> is similar to
 124     <function>SD_ID128_FORMAT_STR()</function> but includes separating hyphens to conform to the
 125     "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
 126     </para>
 127
 128     <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para>
 129
 130     <programlisting>int main(int argc, char *argv[]) {
 131         sd_id128_t a, b, c;
 132         a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
 133         b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e);
 134         c = a;
 135         assert(sd_id128_equal(a, c));
 136         assert(!sd_id128_equal(a, b));
 137         return 0;
 138 }</programlisting>
 139
 140     <para>Use <function>sd_id128_is_null()</function> to check if an 128bit ID consists of only NUL bytes:</para>
 141
 142     <programlisting>int main(int argc, char *argv[]) {
 143         assert(sd_id128_is_null(SD_ID128_NULL));
 144 }</programlisting>
 145
 146     <para>Note that new, randomized IDs may be generated with
 147     <citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 148     <command>new</command> command.</para>
 149   </refsect1>
 150
 151   <xi:include href="libsystemd-pkgconfig.xml" />
 152
 153   <refsect1>
 154     <title>See Also</title>
 155     <para>
 156       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 159       <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 160       <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 161       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 163       <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 165     </para>
 166   </refsect1>
 167
 168 </refentry>