diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/sd-id128.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/sd-id128.3 | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/sd-id128.3 b/upstream/opensuse-tumbleweed/man3/sd-id128.3 new file mode 100644 index 00000000..4fa384e5 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/sd-id128.3 @@ -0,0 +1,332 @@ +'\" t +.TH "SD\-ID128" "3" "" "systemd 254" "sd-id128" +.\" ----------------------------------------------------------------- +.\" * 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_ALLF, SD_ID128_CONST_STR, SD_ID128_FORMAT_STR, SD_ID128_FORMAT_VAL, SD_ID128_MAKE, SD_ID128_MAKE_STR, SD_ID128_MAKE_UUID_STR, SD_ID128_NULL, SD_ID128_UUID_FORMAT_STR, sd_id128_equal, sd_id128_string_equal, sd_id128_in_set, sd_id128_in_set_sentinel, sd_id128_in_setv, sd_id128_is_allf, sd_id128_is_null, sd_id128_t \- APIs for processing 128\-bit IDs +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include <systemd/sd\-id128\&.h> +.fi +.ft +.PP +\fBSD_ID128_ALLF\fR +.PP +\fBSD_ID128_NULL\fR +.PP +\fBSD_ID128_CONST_STR(\fR\fB\fIid\fR\fR\fB)\fR +.PP +\fBSD_ID128_FORMAT_STR\fR +.PP +\fBSD_ID128_FORMAT_VAL(\fR\fB\fIid\fR\fR\fB)\fR +.PP +\fBSD_ID128_MAKE(\fR\fB\fIv0\fR\fR\fB, \fR\fB\fIv1\fR\fR\fB, \fR\fB\fIv2\fR\fR\fB, \fR\fB\fIv3\fR\fR\fB, \fR\fB\fIv4\fR\fR\fB, \fR\fB\fIv5\fR\fR\fB, \fR\fB\fIv6\fR\fR\fB, \fR\fB\fIv7\fR\fR\fB, \fR\fB\fIv8\fR\fR\fB, \fR\fB\fIv9\fR\fR\fB, \fR\fB\fIvA\fR\fR\fB, \fR\fB\fIvB\fR\fR\fB, \fR\fB\fIvC\fR\fR\fB, \fR\fB\fIvD\fR\fR\fB, \fR\fB\fIvE\fR\fR\fB, \fR\fB\fIvF\fR\fR\fB)\fR +.PP +\fBSD_ID128_MAKE_STR(\fR\fB\fIv0\fR\fR\fB, \fR\fB\fIv1\fR\fR\fB, \fR\fB\fIv2\fR\fR\fB, \fR\fB\fIv3\fR\fR\fB, \fR\fB\fIv4\fR\fR\fB, \fR\fB\fIv5\fR\fR\fB, \fR\fB\fIv6\fR\fR\fB, \fR\fB\fIv7\fR\fR\fB, \fR\fB\fIv8\fR\fR\fB, \fR\fB\fIv9\fR\fR\fB, \fR\fB\fIvA\fR\fR\fB, \fR\fB\fIvB\fR\fR\fB, \fR\fB\fIvC\fR\fR\fB, \fR\fB\fIvD\fR\fR\fB, \fR\fB\fIvE\fR\fR\fB, \fR\fB\fIvF\fR\fR\fB)\fR +.PP +\fBSD_ID128_MAKE_UUID_STR(\fR\fB\fIv0\fR\fR\fB, \fR\fB\fIv1\fR\fR\fB, \fR\fB\fIv2\fR\fR\fB, \fR\fB\fIv3\fR\fR\fB, \fR\fB\fIv4\fR\fR\fB, \fR\fB\fIv5\fR\fR\fB, \fR\fB\fIv6\fR\fR\fB, \fR\fB\fIv7\fR\fR\fB, \fR\fB\fIv8\fR\fR\fB, \fR\fB\fIv9\fR\fR\fB, \fR\fB\fIvA\fR\fR\fB, \fR\fB\fIvB\fR\fR\fB, \fR\fB\fIvC\fR\fR\fB, \fR\fB\fIvD\fR\fR\fB, \fR\fB\fIvE\fR\fR\fB, \fR\fB\fIvF\fR\fR\fB)\fR +.PP +\fBSD_ID128_UUID_FORMAT_STR\fR +.HP \w'int\ sd_id128_equal('u +.BI "int sd_id128_equal(sd_id128_t\ " "a" ", sd_id128_t\ " "b" ");" +.HP \w'int\ sd_id128_string_equal('u +.BI "int sd_id128_string_equal(const\ char\ *" "a" ", sd_id128_t\ " "b" ");" +.HP \w'int\ sd_id128_is_null('u +.BI "int sd_id128_is_null(sd_id128_t\ " "id" ");" +.HP \w'int\ sd_id128_is_allf('u +.BI "int sd_id128_is_allf(sd_id128_t\ " "id" ");" +.HP \w'int\ sd_id128_in_setv('u +.BI "int sd_id128_in_setv(sd_id128_t\ " "id" ", va_list\ " "ap" ");" +.HP \w'int\ sd_id128_in_set_sentinel('u +.BI "int sd_id128_in_set_sentinel(sd_id128_t\ " "id" ", \&..., \fBSD_ID128_NULL\fR);" +.HP \w'int\ sd_id128_in_set('u +.BI "int sd_id128_in_set(sd_id128_t\ " "id" ", \&...);" +.HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u +\fBpkg\-config \-\-cflags \-\-libs libsystemd\fR +.SH "DESCRIPTION" +.PP +sd\-id128\&.h +is part of +\fBlibsystemd\fR(3) +and provides APIs to generate, convert, and compare 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 mostly compatible with those types of IDs\&. +.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 by value (as opposed to pass\-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 +is used to write a constant ID in source code\&. A commonly used idiom is to assign a name to an 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_NULL\fR +defines an ID consisting of only +\fBNUL\fR +bytes (i\&.e\&. all bits off)\&. +.PP +\fBSD_ID128_ALLF\fR +defines an ID consisting of only +\fB0xFF\fR +bytes (i\&.e\&. all bits on)\&. +.PP +\fBSD_ID128_MAKE_STR()\fR +is similar to +\fBSD_ID128_MAKE()\fR, but creates a +\fBconst char*\fR +expression that can be conveniently used in message formats and such: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#include <stdio\&.h> +#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); +} +.fi +.if n \{\ +.RE +.\} +.PP +\fBSD_ID128_CONST_STR()\fR +converts constant 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("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); +} +.fi +.if n \{\ +.RE +.\} +.PP +\fBSD_ID128_FORMAT_STR\fR +and +\fBSD_ID128_FORMAT_VAL()\fR +is used to format an 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 +\fBSD_ID128_UUID_FORMAT_STR\fR +and +\fBSD_ID128_MAKE_UUID_STR()\fR +are similar to +\fBSD_ID128_FORMAT_STR\fR +and +\fBSD_ID128_MAKE_STR()\fR, but include separating hyphens to conform to the "\m[blue]\fBcanonical representation\fR\m[]\&\s-2\u[2]\d\s+2"\&. They format the string based on +\m[blue]\fBRFC4122\fR\m[]\&\s-2\u[1]\d\s+2 +Variant 1 rules, i\&.e\&. converting from Big Endian byte order\&. This matches behaviour of most other Linux userspace infrastructure\&. It\*(Aqs probably best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities\&. All 128\-bit IDs generated by the sd\-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122\&. +.PP +\fBsd_id128_equal()\fR +compares 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 +\fBsd_id128_string_equal()\fR +is similar to +\fBsd_id128_equal()\fR, but the first ID is formatted as +\fBconst char*\fR\&. The same restrictions apply as to the first argument of +\fBsd_id128_from_string()\fR\&. +.PP +\fBsd_id128_is_null()\fR +checks if an ID consists of only +\fBNUL\fR +bytes: +.sp +.if n \{\ +.RS 4 +.\} +.nf +assert(sd_id128_is_null(SD_ID128_NULL)); +.fi +.if n \{\ +.RE +.\} +.PP +Similarly, +\fBsd_id128_is_allf()\fR +checks if an ID consists of only +\fB0xFF\fR +bytes (all bits on): +.sp +.if n \{\ +.RS 4 +.\} +.nf +assert(sd_id128_is_allf(SD_ID128_ALLF)); +.fi +.if n \{\ +.RE +.\} +.PP +\fBsd_id128_in_set_sentinel()\fR +takes a list of IDs and returns true if the first argument is equal to any of the subsequent arguments\&. The argument list is terminated by an +\fBSD_ID128_NULL\fR +sentinel, which must be present\&. +.PP +\fBsd_id128_in_set()\fR +is a convenience function that takes a list of IDs and returns true if the first argument is equal to any of the subsequent arguments: +.sp +.if n \{\ +.RS 4 +.\} +.nf +int main(int argc, char *argv[]) { + sd_id12_t a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + assert(sd_id128_in_set(a, a)); + assert(sd_id128_in_set(a, a, a)); + assert(!sd_id128_in_set(a)); + assert(!sd_id128_in_set(a, + SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e) + SD_ID128_MAKE(2f,88,28,5f,9c,44,09,9d,d7,15,77,04,bc,85,7e,e3) + SD_ID128_ALLF)); + return 0; +} +.fi +.if n \{\ +.RE +.\} +.PP +\fBsd_id128_in_set()\fR +is defined as a macro over +\fBsd_id128_in_set_sentinel()\fR, adding the +\fBSD_ID128_NULL\fR +sentinel automatically\&. Since +\fBsd_id128_in_set_sentinel()\fR +uses +\fBSD_ID128_NULL\fR +as the sentinel, +\fBSD_ID128_NULL\fR +cannot be otherwise placed in the argument list\&. +.PP +\fBsd_id128_in_setv()\fR +is similar to +\fBsd_id128_in_set_sentinel()\fR, but takes a +struct varargs +argument\&. +.PP +New randomized IDs may be generated with +\fBsystemd-id128\fR(1)\*(Aqs +\fBnew\fR +command\&. +.PP +See +\fBsd_id128_to_string\fR(3), +\fBsd_id128_randomize\fR(3) +and +\fBsd_id128_get_machine\fR(3) +for information about other implemented functions\&. +.SH "NOTES" +.PP +Functions described here are available as a shared library, which can be compiled against and linked to with the +\fBlibsystemd\fR\ \&\fBpkg-config\fR(1) +file\&. +.PP +The code described here uses +\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call +\fBsetenv\fR(3) +from a parallel thread\&. It is recommended to only do calls to +\fBsetenv()\fR +from an early phase of the program when no other threads have been started\&. +.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 +.IP " 2." 4 +canonical representation +.RS 4 +\%https://en.wikipedia.org/wiki/Universally_unique_identifier#Format +.RE |