man/sd-id128.3

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