sd-id128.xml revision 183de6d7d9def43ec90b94e775fdc49539a950ba
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering This file is part of systemd.
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering Copyright 2012 Lennart Poettering
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering systemd is free software; you can redistribute it and/or modify it
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering under the terms of the GNU Lesser General Public License as published by
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering (at your option) any later version.
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering systemd is distributed in the hope that it will be useful, but
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering Lesser General Public License for more details.
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering You should have received a copy of the GNU Lesser General Public License
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <refentryinfo>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering </authorgroup>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering </refentryinfo>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <refpurpose>APIs for processing 128 bit IDs</refpurpose>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <refsynopsisdiv>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <funcsynopsis>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering </funcsynopsis>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <command>pkg-config --cflags --libs libsystemd-id128</command>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering </cmdsynopsis>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering </refsynopsisdiv>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para><filename>sd-id128.h</filename> provides APIs to
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering process and generate 128 bit ID values. The 128 bit ID
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering values processed and generated by these APIs are a
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering generalization of OSF UUIDs as defined by <ulink
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering url="http://tools.ietf.org/html/rfc4122">RFC
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering 4122</ulink>, though use a simpler string
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering formatting. These functions impose no structure on the
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering used IDs, much unlike OSF UUIDs or Microsoft GUIDs,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering but are fully compatible with those types of IDs.
a4023a43d0312568f0b81b39b4bc6fd9b64880ebLennart Poettering <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
a4023a43d0312568f0b81b39b4bc6fd9b64880ebLennart Poettering <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
a4023a43d0312568f0b81b39b4bc6fd9b64880ebLennart Poettering <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
bfc79e342f7f419adf10cfefd3b27b3af656db0dPaul Menzel for more information about the implemented
bfc79e342f7f419adf10cfefd3b27b3af656db0dPaul Menzel functions.</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para>A 128 bit ID is implemented as the following
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering union type:</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <programlisting>typedef union sd_id128 {
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering uint8_t bytes[16];
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering uint64_t qwords[2];
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering} sd_id128_t;</programlisting>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para>This union type allows accessing the 128 bit ID
bfc79e342f7f419adf10cfefd3b27b3af656db0dPaul Menzel as 16 separate bytes or two 64 bit words. It is generally
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering safer to access the ID components by their 8 bit array
40b90434832c373c1394bc502523bee39c279c24Paul Menzel to avoid endianness issues. This union is intended to
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering be passed call-by-value (as opposed to
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering call-by-reference) and may be directly manipulated by
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering clients.</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para>A couple of macros are defined to denote and
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering decode 128 bit IDs:</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para><function>SD_ID128_MAKE()</function> may be used
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering to denote a constant 128 bit ID in source code. A
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering commonly used idiom is to assign a name to a 128 bit
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering ID using this macro:</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <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>
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering <para><function>SD_ID128_CONST_STR()</function> may be
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering use to convert constant 128bit IDs into constant
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering strings for output. The following example code will
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering output the string
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering "fc2e22bc6ee647b6b90729ab34a250b1":</para>
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering <programlisting>int main(int argc, char *argv[]) {
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
183de6d7d9def43ec90b94e775fdc49539a950baLennart Poettering}</programlisting>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para><function>SD_ID128_FORMAT_STR</function> and
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <function>SD_ID128_FORMAT_VAL()</function> may be used
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering to format a 128 bit ID in a
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering format string, as shown in the following
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering example:</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <programlisting>int main(int argc, char *argv[]) {
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering sd_id128_t id;
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id));
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering}</programlisting>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para>Use <function>sd_id128_equal()</function> to compare two 128 bit IDs:</para>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <programlisting>int main(int argc, char *argv[]) {
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering sd_id128_t a, b, c;
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07);
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e);
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering assert(sd_id128_equal(a, c));
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering assert(!sd_id128_equal(a, b));
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering}</programlisting>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <para>Note that new, randomized IDs may be generated
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
bfc79e342f7f419adf10cfefd3b27b3af656db0dPaul Menzel <para>These APIs are implemented as a shared library,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering which can be compiled and linked to with the
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
a4023a43d0312568f0b81b39b4bc6fd9b64880ebLennart Poettering <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
12355095821fc17529af5b6eaefa31c3c520be39Lennart Poettering <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>