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