304 lines
6.9 KiB
HTML
304 lines
6.9 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of SD-ID128</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>SD-ID128</H1>
|
|
Section: sd-id128 (3)<BR>Updated: <BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
sd-id128, sd_id128_t, SD_ID128_MAKE, SD_ID128_MAKE_STR, SD_ID128_NULL, SD_ID128_CONST_STR, SD_ID128_FORMAT_STR, SD_ID128_UUID_FORMAT_STR, SD_ID128_FORMAT_VAL, sd_id128_equal, sd_id128_is_null - APIs for processing 128-bit IDs
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<P>
|
|
<B>
|
|
</B><PRE>
|
|
#include <<A HREF="file:///usr/include/systemd/sd-id128.h">systemd/sd-id128.h</A>>
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">
|
|
<B>pkg-config --cflags --libs libsystemd</B>
|
|
</DL>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<P>
|
|
|
|
<DD>sd-id128.h
|
|
provides APIs to process and generate 128-bit ID values. The 128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by
|
|
m[blue]<B>RFC 4122</B>m[]<FONT SIZE="-2">[1]</FONT>
|
|
but use a simpler string format. These functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are fully compatible with those types of IDs.
|
|
<P>
|
|
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sd_id128_to_string">sd_id128_to_string</A></B>(3),
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sd_id128_randomize">sd_id128_randomize</A></B>(3)
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sd_id128_get_machine">sd_id128_get_machine</A></B>(3)
|
|
for more information about the implemented functions.
|
|
<P>
|
|
|
|
A 128-bit ID is implemented as the following union type:
|
|
<P>
|
|
<DL COMPACT><DT id="2"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
typedef union sd_id128 {
|
|
uint8_t bytes[16];
|
|
uint64_t qwords[2];
|
|
} sd_id128_t;
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<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 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>
|
|
|
|
A couple of macros are defined to denote and decode 128-bit IDs:
|
|
<P>
|
|
|
|
<B>SD_ID128_MAKE()</B>
|
|
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 ID using this macro:
|
|
<P>
|
|
<DL COMPACT><DT id="3"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>SD_ID128_NULL</B>
|
|
may be used to refer to the 128bit ID consisting of only NUL bytes.
|
|
<P>
|
|
|
|
<B>SD_ID128_MAKE_STR()</B>
|
|
is similar to
|
|
<B>SD_ID128_MAKE()</B>, but creates a
|
|
<B>const char*</B>
|
|
expression that can be conveniently used in message formats and such:
|
|
<P>
|
|
<DL COMPACT><DT id="4"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
#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)
|
|
|
|
int main(int argc, char **argv) {
|
|
puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>SD_ID128_CONST_STR()</B>
|
|
may be used to convert constant 128-bit IDs into constant strings for output. The following example code will output the string "fc2e22bc6ee647b6b90729ab34a250b1":
|
|
<P>
|
|
<DL COMPACT><DT id="5"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
int main(int argc, char *argv[]) {
|
|
puts("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
|
|
}
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>SD_ID128_FORMAT_STR()</B>
|
|
and
|
|
<B>SD_ID128_FORMAT_VAL()</B>
|
|
may be used to format a 128-bit ID in a
|
|
<B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3)
|
|
format string, as shown in the following example:
|
|
<P>
|
|
<DL COMPACT><DT id="6"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
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;
|
|
}
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>SD_ID128_UUID_FORMAT_STR()</B>
|
|
is similar to
|
|
<B>SD_ID128_FORMAT_STR()</B>
|
|
but includes separating hyphens to conform to the "m[blue]<B>canonical representation</B>m[]<FONT SIZE="-2">[2]</FONT>".
|
|
<P>
|
|
|
|
Use
|
|
<B>sd_id128_equal()</B>
|
|
to compare two 128-bit IDs:
|
|
<P>
|
|
<DL COMPACT><DT id="7"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
int main(int argc, char *argv[]) {
|
|
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>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
Use
|
|
<B>sd_id128_is_null()</B>
|
|
to check if an 128bit ID consists of only NUL bytes:
|
|
<P>
|
|
<DL COMPACT><DT id="8"><DD>
|
|
|
|
|
|
|
|
<PRE>
|
|
int main(int argc, char *argv[]) {
|
|
assert(sd_id128_is_null(SD_ID128_NULL));
|
|
}
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
Note that new, randomized IDs may be generated with
|
|
<B><A HREF="/cgi-bin/man/man2html?1+systemd-id128">systemd-id128</A></B>(1)'s
|
|
<B>new</B>
|
|
command.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<P>
|
|
|
|
These APIs are implemented as a shared library, which can be compiled and linked to with the
|
|
<B>libsystemd</B> <B><A HREF="/cgi-bin/man/man2html?1+pkg-config">pkg-config</A></B>(1)
|
|
file.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<P>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+systemd">systemd</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sd_id128_to_string">sd_id128_to_string</A></B>(3),
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sd_id128_randomize">sd_id128_randomize</A></B>(3),
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sd_id128_get_machine">sd_id128_get_machine</A></B>(3),
|
|
<B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+journalctl">journalctl</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?7+sd-journal">sd-journal</A></B>(7),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+pkg-config">pkg-config</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?5+machine-id">machine-id</A></B>(5)
|
|
<A NAME="lbAG"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="9"> 1.<DD>
|
|
RFC 4122
|
|
<DL COMPACT><DT id="10"><DD>
|
|
<A HREF="https://tools.ietf.org/html/rfc4122">https://tools.ietf.org/html/rfc4122</A>
|
|
</DL>
|
|
|
|
<DT id="11"> 2.<DD>
|
|
canonical representation
|
|
<DL COMPACT><DT id="12"><DD>
|
|
<A HREF="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">https://en.wikipedia.org/wiki/Universally_unique_identifier#Format</A>
|
|
</DL>
|
|
|
|
<P>
|
|
</DL>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="13"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="14"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="15"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="16"><A HREF="#lbAE">NOTES</A><DD>
|
|
<DT id="17"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
<DT id="18"><A HREF="#lbAG">NOTES</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:55 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|