sd-id128.3 4.52 KB
Newer Older
Michael Biebl's avatar
Michael Biebl committed
1
'\" t
Michael Biebl's avatar
Michael Biebl committed
2
.TH "SD\-ID128" "3" "" "systemd 215" "sd-id128"
Michael Biebl's avatar
Michael Biebl committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
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
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-id128\&.h>
.fi
.ft
31 32
.HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u
\fBpkg\-config \-\-cflags \-\-libs libsystemd\fR
Michael Biebl's avatar
Michael Biebl committed
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
.SH "DESCRIPTION"
.PP
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]\fBRFC 4122\fR\m[]\&\s-2\u[1]\d\s+2
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\&.
.PP
See
\fBsd_id128_to_string\fR(3),
\fBsd_id128_randomize\fR(3)
and
\fBsd_id128_get_machine\fR(3)
for more information about the implemented functions\&.
.PP
A 128\-bit ID is implemented as the following union type:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef union sd_id128 {
        uint8_t bytes[16];
        uint64_t qwords[2];
} sd_id128_t;
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
A couple of macros are defined to denote and decode 128\-bit IDs:
.PP
\fBSD_ID128_MAKE()\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)
.fi
.if n \{\
.RE
.\}
.PP
\fBSD_ID128_CONST_STR()\fR
may be used to convert constant 128\-bit IDs into constant strings for output\&. The following example code will output the string "fc2e22bc6ee647b6b90729ab34a250b1":
.sp
.if n \{\
.RS 4
.\}
.nf
int main(int argc, char *argv[]) {
        puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
}
.fi
.if n \{\
.RE
.\}
.PP
\fBSD_ID128_FORMAT_STR\fR
and
\fBSD_ID128_FORMAT_VAL()\fR
may be used to format a 128\-bit ID in a
\fBprintf\fR(3)
format string, as shown in the following example:
.sp
.if n \{\
.RS 4
.\}
.nf
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 "\&.\en", SD_ID128_FORMAT_VAL(id));
        return 0;
}
.fi
.if n \{\
.RE
.\}
.PP
Use
\fBsd_id128_equal()\fR
to compare two 128\-bit IDs:
.sp
.if n \{\
.RS 4
.\}
.nf
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;
}
.fi
.if n \{\
.RE
.\}
.PP
Note that new, randomized IDs may be generated with
\fBjournalctl\fR(1)\*(Aqs
\fB\-\-new\-id\fR
option\&.
.SH "NOTES"
.PP
These APIs are implemented as a shared library, which can be compiled and linked to with the
145
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
Michael Biebl's avatar
Michael Biebl committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd_id128_to_string\fR(3),
\fBsd_id128_randomize\fR(3),
\fBsd_id128_get_machine\fR(3),
\fBprintf\fR(3),
\fBjournalctl\fR(1),
\fBsd-journal\fR(7),
\fBpkg-config\fR(1),
\fBmachine-id\fR(5)
.SH "NOTES"
.IP " 1." 4
RFC 4122
.RS 4
\%https://tools.ietf.org/html/rfc4122
.RE