man/SD_ID128_MAKE.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd-id128</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 204</span><hr><div class="refentry"><a name="sd-id128"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd-id128, sd_id128_t, SD_ID128_MAKE, SD_ID128_CONST_STR, SD_ID128_FORMAT_STR, SD_ID128_FORMAT_VAL, sd_id128_equal — APIs for processing 128 bit IDs</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-id128.h&gt;</pre></div><div class="cmdsynopsis"><p><code class="command">pkg-config --cflags --libs libsystemd-id128</code> </p></div></div><div class="refsect1"><a name="idm259785214528"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="filename">sd-id128.h</code> provides APIs to
  23                 process and generate 128 bit ID values. The 128 bit ID
  24                 values processed and generated by these APIs are a
  25                 generalization of OSF UUIDs as defined by <a class="ulink" href="http://tools.ietf.org/html/rfc4122" target="_top">RFC
  26                 4122</a>, though use a simpler string
  27                 formatting. These functions impose no structure on the
  28                 used IDs, much unlike OSF UUIDs or Microsoft GUIDs,
  29                 but are fully compatible with those types of IDs.
  30                 </p><p>See
  31                 <a href="sd_id128_to_string.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_to_string</span>(3)</span></a>,
  32                 <a href="sd_id128_randomize.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_randomize</span>(3)</span></a> and
  33                 <a href="sd_id128_get_machine.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_get_machine</span>(3)</span></a>
  34                 for more information about the implemented
  35                 functions.</p><p>A 128 bit ID is implemented as the following
  36                 union type:</p><pre class="programlisting">typedef union sd_id128 {
  37         uint8_t bytes[16];
  38         uint64_t qwords[2];
  39 } sd_id128_t;</pre><p>This union type allows accessing the 128 bit ID
  40                 as 16 separate bytes or two 64 bit words. It is generally
  41                 safer to access the ID components by their 8 bit array
  42                 to avoid endianness issues. This union is intended to
  43                 be passed call-by-value (as opposed to
  44                 call-by-reference) and may be directly manipulated by
  45                 clients.</p><p>A couple of macros are defined to denote and
  46                 decode 128 bit IDs:</p><p><code class="function">SD_ID128_MAKE()</code> may be used
  47                 to denote a constant 128 bit ID in source code. A
  48                 commonly used idiom is to assign a name to a 128 bit
  49                 ID using this macro:</p><pre class="programlisting">#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</pre><p><code class="function">SD_ID128_CONST_STR()</code> may be
  50                 used to convert constant 128bit IDs into constant
  51                 strings for output. The following example code will
  52                 output the string
  53                 "fc2e22bc6ee647b6b90729ab34a250b1":</p><pre class="programlisting">int main(int argc, char *argv[]) {
  54         puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
  55 }</pre><p><code class="function">SD_ID128_FORMAT_STR</code> and
  56                 <code class="function">SD_ID128_FORMAT_VAL()</code> may be used
  57                 to format a 128 bit ID in a
  58                 <a href="printf.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>
  59                 format string, as shown in the following
  60                 example:</p><pre class="programlisting">int main(int argc, char *argv[]) {
  61         sd_id128_t id;
  62         id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
  63         printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id));
  64         return 0;
  65 }</pre><p>Use <code class="function">sd_id128_equal()</code> to compare two 128 bit IDs:</p><pre class="programlisting">int main(int argc, char *argv[]) {
  66         sd_id128_t a, b, c;
  67         a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
  68         b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e);
  69         c = a;
  70         assert(sd_id128_equal(a, c));
  71         assert(!sd_id128_equal(a, b));
  72         return 0;
  73 }</pre><p>Note that new, randomized IDs may be generated
  74                 with
  75                 <a href="journalctl.html"><span class="citerefentry"><span class="refentrytitle">journalctl</span>(1)</span></a>'s
  76                 <code class="literal">--new-id</code> option.</p></div><div class="refsect1"><a name="idm259785313216"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>These APIs are implemented as a shared library,
  77                 which can be compiled and linked to with the
  78                 <code class="literal">libsystemd-id128</code>
  79                 <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  80                 file.</p></div><div class="refsect1"><a name="idm259785310368"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  81                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  82                         <a href="sd_id128_to_string.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_to_string</span>(3)</span></a>,
  83                         <a href="sd_id128_randomize.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_randomize</span>(3)</span></a>,
  84                         <a href="sd_id128_get_machine.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_get_machine</span>(3)</span></a>,
  85                         <a href="printf.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>,
  86                         <a href="journalctl.html"><span class="citerefentry"><span class="refentrytitle">journalctl</span>(1)</span></a>,
  87                         <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(7)</span></a>,
  88                         <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>,
  89                         <a href="machine-id.html"><span class="citerefentry"><span class="refentrytitle">machine-id</span>(5)</span></a>
  90                 </p></div></div></body></html>