1SD_ID128_TO_STRING(3)         sd_id128_to_string         SD_ID128_TO_STRING(3)
2
3
4

NAME

6       sd_id128_to_string, SD_ID128_TO_STRING, sd_id128_from_string,
7       SD_ID128_STRING_MAX - Format or parse 128-bit IDs as strings
8

SYNOPSIS

10       #include <systemd/sd-id128.h>
11
12       #define SD_ID128_STRING_MAX 33U
13
14       #define SD_ID128_TO_STRING(id) ...
15
16       char
17                                *sd_id128_to_string(sd_id128_t id, char s[static SD_ID128_STRING_MAX]);
18
19       int sd_id128_from_string(const char *s, sd_id128_t *ret);
20

DESCRIPTION

22       sd_id128_to_string() formats a 128-bit ID as a character string. It
23       expects the ID and a string array capable of storing 33 characters
24       (SD_ID128_STRING_MAX). The ID will be formatted as 32 lowercase
25       hexadecimal digits and be terminated by a NUL byte.
26
27       SD_ID128_TO_STRING() is a macro that wraps sd_id128_to_string() and
28       passes an appropriately sized buffer as second argument, allocated as
29       C99 compound literal. Each use will thus implicitly acquire a suitable
30       buffer on the stack which remains valid until the end of the current
31       code block. This is usually the simplest way to acquire a string
32       representation of a 128-bit ID in a buffer that is valid in the current
33       code block.
34
35       sd_id128_from_string() implements the reverse operation: it takes a 33
36       character string with 32 hexadecimal digits (either lowercase or
37       uppercase, terminated by NUL) and parses them back into a 128-bit ID
38       returned in ret. Alternatively, this call can also parse a 37-character
39       string with a 128-bit ID formatted as RFC UUID. If ret is passed as
40       NULL the function will validate the passed ID string, but not actually
41       return it in parsed form.
42
43       Note that when parsing 37 character UUIDs this is done strictly in Big
44       Endian byte order, i.e. according to RFC4122[1] Variant 1 rules, even
45       if the UUID encodes a different variant. This matches behaviour in
46       various other Linux userspace tools. It's probably wise to avoid UUIDs
47       of other variant types.
48
49       For more information about the "sd_id128_t" type see sd-id128(3). Note
50       that these calls operate the same way on all architectures, i.e. the
51       results do not depend on endianness.
52
53       When formatting a 128-bit ID into a string, it is often easier to use a
54       format string for printf(3). This is easily done using the
55       SD_ID128_FORMAT_STR and SD_ID128_FORMAT_VAL() macros. For more
56       information see sd-id128(3).
57

RETURN VALUE

59       sd_id128_to_string() always succeeds and returns a pointer to the
60       string array passed in.  sd_id128_from_string() returns 0 on success,
61       in which case ret is filled in, or a negative errno-style error code.
62

NOTES

64       These APIs are implemented as a shared library, which can be compiled
65       and linked to with the libsystemd pkg-config(1) file.
66

SEE ALSO

68       systemd(1), sd-id128(3), printf(3)
69

NOTES

71        1. RFC4122
72           https://tools.ietf.org/html/rfc4122
73
74
75
76systemd 250                                              SD_ID128_TO_STRING(3)