man/sd-id128.xml

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