SD_ID128_FORMAT_VAL.html 7.44 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<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>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
Michael Biebl's avatar
Michael Biebl committed
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</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</code> </p></div></div><div class="refsect1"><a name="idm214191197712"></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
Michael Biebl's avatar
Michael Biebl committed
23
                process and generate 128-bit ID values. The 128-bit ID
24
                values processed and generated by these APIs are a
Michael Biebl's avatar
Michael Biebl committed
25 26 27
                generalization of OSF UUIDs as defined by <a class="ulink" href="https://tools.ietf.org/html/rfc4122" target="_top">RFC
                4122</a> but use a simpler string
                format. These functions impose no structure on the
28 29 30 31 32 33 34
                used IDs, much unlike OSF UUIDs or Microsoft GUIDs,
                but are fully compatible with those types of IDs.
                </p><p>See
                <a href="sd_id128_to_string.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_to_string</span>(3)</span></a>,
                <a href="sd_id128_randomize.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_randomize</span>(3)</span></a> and
                <a href="sd_id128_get_machine.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_get_machine</span>(3)</span></a>
                for more information about the implemented
Michael Biebl's avatar
Michael Biebl committed
35
                functions.</p><p>A 128-bit ID is implemented as the following
36 37 38
                union type:</p><pre class="programlisting">typedef union sd_id128 {
        uint8_t bytes[16];
        uint64_t qwords[2];
Michael Biebl's avatar
Michael Biebl committed
39 40 41
} sd_id128_t;</pre><p>This union type allows accessing the 128-bit ID
                as 16 separate bytes or two 64-bit words. It is generally
                safer to access the ID components by their 8-bit array
42 43 44 45
                to avoid endianness issues. This union is intended to
                be passed call-by-value (as opposed to
                call-by-reference) and may be directly manipulated by
                clients.</p><p>A couple of macros are defined to denote and
Michael Biebl's avatar
Michael Biebl committed
46 47 48
                decode 128-bit IDs:</p><p><code class="function">SD_ID128_MAKE()</code> may be used
                to denote a constant 128-bit ID in source code. A
                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
Michael Biebl's avatar
Michael Biebl committed
50
                used to convert constant 128-bit IDs into constant
51 52 53 54 55 56
                strings for output. The following example code will
                output the string
                "fc2e22bc6ee647b6b90729ab34a250b1":</p><pre class="programlisting">int main(int argc, char *argv[]) {
        puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
}</pre><p><code class="function">SD_ID128_FORMAT_STR</code> and
                <code class="function">SD_ID128_FORMAT_VAL()</code> may be used
Michael Biebl's avatar
Michael Biebl committed
57
                to format a 128-bit ID in a
58 59 60 61 62 63 64
                <a href="printf.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>
                format string, as shown in the following
                example:</p><pre class="programlisting">int main(int argc, char *argv[]) {
        sd_id128_t id;
        id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
        printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id));
        return 0;
Michael Biebl's avatar
Michael Biebl committed
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 67 68 69 70 71 72 73 74 75
        sd_id128_t a, b, c;
        a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
        b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e);
        c = a;
        assert(sd_id128_equal(a, c));
        assert(!sd_id128_equal(a, b));
        return 0;
}</pre><p>Note that new, randomized IDs may be generated
                with
                <a href="journalctl.html"><span class="citerefentry"><span class="refentrytitle">journalctl</span>(1)</span></a>'s
Michael Biebl's avatar
Michael Biebl committed
76
                <code class="option">--new-id</code> option.</p></div><div class="refsect1"><a name="idm214187744304"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p><a name="pkgconfig-text"></a>These APIs are implemented as a shared
77 78
  library, which can be compiled and linked to with the
  <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
Michael Biebl's avatar
Michael Biebl committed
79
  file.</p></div><div class="refsect1"><a name="idm214191643840"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
80 81 82 83 84 85 86 87 88 89
                        <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
                        <a href="sd_id128_to_string.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_to_string</span>(3)</span></a>,
                        <a href="sd_id128_randomize.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_randomize</span>(3)</span></a>,
                        <a href="sd_id128_get_machine.html"><span class="citerefentry"><span class="refentrytitle">sd_id128_get_machine</span>(3)</span></a>,
                        <a href="printf.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>,
                        <a href="journalctl.html"><span class="citerefentry"><span class="refentrytitle">journalctl</span>(1)</span></a>,
                        <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(7)</span></a>,
                        <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>,
                        <a href="machine-id.html"><span class="citerefentry"><span class="refentrytitle">machine-id</span>(5)</span></a>
                </p></div></div></body></html>