Debian Codegraph @

upstream/debian-unstable/man3/sd_id128_to_string.3

raw
1 '\" t
2 .TH "SD_ID128_TO_STRING" "3" "" "systemd 261~rc3" "sd_id128_to_string"
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_to_string, SD_ID128_TO_STRING, SD_ID128_STRING_MAX, sd_id128_to_uuid_string, SD_ID128_TO_UUID_STRING, SD_ID128_UUID_STRING_MAX, sd_id128_from_string \- Format or parse 128\-bit IDs as strings
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-id128\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 #define SD_ID128_STRING_MAX 33U
35 .fi
36 .ft
37 .sp
38 .ft B
39 .nf
40 #define SD_ID128_UUID_STRING_MAX 37U
41 .fi
42 .ft
43 .sp
44 .ft B
45 .nf
46 #define SD_ID128_TO_STRING(id) \&...
47 .fi
48 .ft
49 .sp
50 .ft B
51 .nf
52 #define SD_ID128_TO_UUID_STRING(id) \&...
53 .fi
54 .ft
55 .HP \w'char\ *sd_id128_to_string('u
56 .BI "char *sd_id128_to_string(sd_id128_t\ " "id" ",\ char\ " "s" "[static\ SD_ID128_STRING_MAX]);"
57 .HP \w'char\ *sd_id128_to_uuid_string('u
58 .BI "char *sd_id128_to_uuid_string(sd_id128_t\ " "id" ",\ char\ " "s" "[static\ SD_ID128_UUID_STRING_MAX]);"
59 .HP \w'int\ sd_id128_from_string('u
60 .BI "int sd_id128_from_string(const\ char\ *" "s" ",\ sd_id128_t\ *" "ret" ");"
61 .SH "DESCRIPTION"
62 .PP
63 \fBsd_id128_to_string()\fR
64 formats a 128\-bit ID as a character string\&. It expects the ID and a string array capable of storing 33 characters (\fBSD_ID128_STRING_MAX\fR)\&. The ID will be formatted as 32 lowercase hexadecimal digits and be terminated by a
65 \fBNUL\fR
66 byte\&.
67 .PP
68 \fBSD_ID128_TO_STRING()\fR
69 is a macro that wraps
70 \fBsd_id128_to_string()\fR
71 and passes an appropriately sized buffer as second argument, allocated as C99 compound literal\&. Each use will thus implicitly acquire a suitable buffer on the stack which remains valid until the end of the current code block\&. This is usually the simplest way to acquire a string representation of a 128\-bit ID in a buffer that is valid in the current code block\&.
72 .PP
73 \fBsd_id128_to_uuid_string()\fR
74 and
75 \fBSD_ID128_TO_UUID_STRING()\fR
76 are similar to these two functions/macros, but format the 128\-bit values as RFC4122 UUIDs, i\&.e\&. a series of 36 lowercase hexadecimal digits and dashes, terminated by a
77 \fBNUL\fR
78 byte\&.
79 .PP
80 \fBsd_id128_from_string()\fR
81 implements the reverse operation: it takes a 33 character string with 32 hexadecimal digits (either lowercase or uppercase, terminated by
82 \fBNUL\fR) and parses them back into a 128\-bit ID returned in
83 \fIret\fR\&. Alternatively, this call can also parse a 37\-character string with a 128\-bit ID formatted as RFC UUID\&. If
84 \fIret\fR
85 is passed as
86 \fBNULL\fR
87 the function will validate the passed ID string, but not actually return it in parsed form\&.
88 .PP
89 Note that when formatting and parsing 36 character UUIDs this is done strictly in Big Endian byte order, i\&.e\&. according to
90 \m[blue]\fBRFC4122\fR\m[]\&\s-2\u[1]\d\s+2
91 Variant 1 rules, even if the UUID encodes a different variant\&. This matches behaviour in various other Linux userspace tools\&. It\*(Aqs probably wise to avoid UUIDs of other variant types\&.
92 .PP
93 For more information about the
94 "sd_id128_t"
95 type see
96 \fBsd-id128\fR(3)\&. Note that these calls operate the same way on all architectures, i\&.e\&. the results do not depend on endianness\&.
97 .PP
98 When formatting a 128\-bit ID into a string, it is often easier to use a format string for
99 \fBprintf\fR(3)\&. This is easily done using the
100 \fBSD_ID128_FORMAT_STR\fR
101 and
102 \fBSD_ID128_FORMAT_VAL()\fR
103 macros\&. For more information see
104 \fBsd-id128\fR(3)\&.
105 .SH "RETURN VALUE"
106 .PP
107 \fBsd_id128_to_string()\fR
108 always succeeds and returns a pointer to the string array passed in\&.
109 \fBsd_id128_from_string()\fR
110 returns 0 on success, in which case
111 \fIret\fR
112 is filled in, or a negative errno\-style error code\&.
113 .SH "NOTES"
114 .PP
115 Functions described here are available as a shared library, which can be compiled against and linked to with the
116 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
117 file\&.
118 .PP
119 The code described here uses
120 \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
121 \fBsetenv\fR(3)
122 from a parallel thread\&. It is recommended to only do calls to
123 \fBsetenv()\fR
124 from an early phase of the program when no other threads have been started\&.
125 .SH "HISTORY"
126 .PP
127 \fBsd_id128_to_string()\fR
128 and
129 \fBsd_id128_from_string()\fR
130 were added in version 187\&.
131 .PP
132 \fBsd_id128_to_uuid_string()\fR
133 was added in version 251\&.
134 .SH "SEE ALSO"
135 .PP
136 \fBsystemd\fR(1), \fBsd-id128\fR(3), \fBprintf\fR(3)
137 .SH "NOTES"
138 .IP " 1." 4
139 RFC4122
140 .RS 4
141 \%https://tools.ietf.org/html/rfc4122
142 .RE