]>
Commit | Line | Data |
---|---|---|
12355095 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
12355095 | 5 | |
7d6b2723 | 6 | <refentry id="sd_id128_to_string" xmlns:xi="http://www.w3.org/2001/XInclude"> |
12355095 | 7 | |
798d3a52 ZJS |
8 | <refentryinfo> |
9 | <title>sd_id128_to_string</title> | |
10 | <productname>systemd</productname> | |
798d3a52 ZJS |
11 | </refentryinfo> |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>sd_id128_to_string</refentrytitle> | |
15 | <manvolnum>3</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>sd_id128_to_string</refname> | |
c970388b | 20 | <refname>SD_ID128_TO_STRING</refname> |
c970388b | 21 | <refname>SD_ID128_STRING_MAX</refname> |
b7416360 LP |
22 | <refname>sd_id128_to_uuid_string</refname> |
23 | <refname>SD_ID128_TO_UUID_STRING</refname> | |
24 | <refname>SD_ID128_UUID_STRING_MAX</refname> | |
25 | <refname>sd_id128_from_string</refname> | |
798d3a52 ZJS |
26 | <refpurpose>Format or parse 128-bit IDs as strings</refpurpose> |
27 | </refnamediv> | |
28 | ||
29 | <refsynopsisdiv> | |
30 | <funcsynopsis> | |
31 | <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> | |
32 | ||
c970388b LP |
33 | <funcsynopsisinfo>#define SD_ID128_STRING_MAX 33U</funcsynopsisinfo> |
34 | ||
b7416360 LP |
35 | <funcsynopsisinfo>#define SD_ID128_UUID_STRING_MAX 37U</funcsynopsisinfo> |
36 | ||
c970388b LP |
37 | <funcsynopsisinfo>#define SD_ID128_TO_STRING(id) …</funcsynopsisinfo> |
38 | ||
b7416360 LP |
39 | <funcsynopsisinfo>#define SD_ID128_TO_UUID_STRING(id) …</funcsynopsisinfo> |
40 | ||
798d3a52 ZJS |
41 | <funcprototype> |
42 | <funcdef>char *<function>sd_id128_to_string</function></funcdef> | |
c970388b | 43 | <paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[static SD_ID128_STRING_MAX]</paramdef> |
798d3a52 ZJS |
44 | </funcprototype> |
45 | ||
b7416360 LP |
46 | <funcprototype> |
47 | <funcdef>char *<function>sd_id128_uuid_string</function></funcdef> | |
48 | <paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[static SD_ID128_UUID_STRING_MAX]</paramdef> | |
49 | </funcprototype> | |
50 | ||
798d3a52 ZJS |
51 | <funcprototype> |
52 | <funcdef>int <function>sd_id128_from_string</function></funcdef> | |
53 | <paramdef>const char *<parameter>s</parameter>, sd_id128_t *<parameter>ret</parameter></paramdef> | |
54 | </funcprototype> | |
55 | ||
56 | </funcsynopsis> | |
57 | </refsynopsisdiv> | |
58 | ||
59 | <refsect1> | |
60 | <title>Description</title> | |
61 | ||
c970388b LP |
62 | <para><function>sd_id128_to_string()</function> formats a 128-bit ID as a character string. It expects |
63 | the ID and a string array capable of storing 33 characters | |
64 | (<constant>SD_ID128_STRING_MAX</constant>). The ID will be formatted as 32 lowercase hexadecimal digits | |
65 | and be terminated by a <constant>NUL</constant> byte.</para> | |
66 | ||
67 | <para><function>SD_ID128_TO_STRING()</function> is a macro that wraps | |
68 | <function>sd_id128_to_string()</function> and passes an appropriately sized buffer as second argument, | |
69 | allocated as C99 compound literal. Each use will thus implicitly acquire a suitable buffer on the stack | |
70 | which remains valid until the end of the current code block. This is usually the simplest way to acquire | |
71 | a string representation of a 128-bit ID in a buffer that is valid in the current code block.</para> | |
798d3a52 | 72 | |
b7416360 | 73 | <para><function>sd_id128_to_uuid_string()</function> and <function>SD_ID128_TO_UUID_STRING()</function> |
da890466 | 74 | are similar to these two functions/macros, but format the 128-bit values as RFC4122 UUIDs, i.e. a series |
b7416360 LP |
75 | of 36 lowercase hexadeciaml digits and dashes, terminated by a <constant>NUL</constant> byte.</para> |
76 | ||
c970388b LP |
77 | <para><function>sd_id128_from_string()</function> implements the reverse operation: it takes a 33 |
78 | character string with 32 hexadecimal digits (either lowercase or uppercase, terminated by | |
79 | <constant>NUL</constant>) and parses them back into a 128-bit ID returned in | |
80 | <parameter>ret</parameter>. Alternatively, this call can also parse a 37-character string with a 128-bit | |
81 | ID formatted as RFC UUID. If <parameter>ret</parameter> is passed as <constant>NULL</constant> the | |
82 | function will validate the passed ID string, but not actually return it in parsed form.</para> | |
798d3a52 | 83 | |
b7416360 | 84 | <para>Note that when formatting and parsing 36 character UUIDs this is done strictly in Big Endian byte order, |
c970388b LP |
85 | i.e. according to <ulink url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, even |
86 | if the UUID encodes a different variant. This matches behaviour in various other Linux userspace | |
87 | tools. It's probably wise to avoid UUIDs of other variant types.</para> | |
88 | ||
89 | <para>For more information about the <literal>sd_id128_t</literal> type see | |
90 | <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note that | |
91 | these calls operate the same way on all architectures, i.e. the results do not depend on | |
92 | endianness.</para> | |
93 | ||
94 | <para>When formatting a 128-bit ID into a string, it is often easier to use a format string for | |
95 | <citerefentry | |
96 | project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This | |
97 | is easily done using the <constant>SD_ID128_FORMAT_STR</constant> and | |
98 | <function>SD_ID128_FORMAT_VAL()</function> macros. For more information see | |
798d3a52 ZJS |
99 | <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> |
100 | </refsect1> | |
101 | ||
102 | <refsect1> | |
103 | <title>Return Value</title> | |
104 | ||
c970388b LP |
105 | <para><function>sd_id128_to_string()</function> always succeeds and returns a pointer to the string array |
106 | passed in. <function>sd_id128_from_string()</function> returns 0 on success, in which case | |
107 | <parameter>ret</parameter> is filled in, or a negative errno-style error code.</para> | |
798d3a52 ZJS |
108 | </refsect1> |
109 | ||
7d6b2723 | 110 | <xi:include href="libsystemd-pkgconfig.xml" /> |
798d3a52 | 111 | |
69106f47 AK |
112 | <refsect1> |
113 | <title>History</title> | |
00f95506 AK |
114 | <para><function>sd_id128_to_string()</function> and |
115 | <function>sd_id128_from_string()</function> were added in version 187.</para> | |
69106f47 AK |
116 | <para><function>sd_id128_uuid_string()</function> was added in version 251.</para> |
117 | </refsect1> | |
118 | ||
798d3a52 ZJS |
119 | <refsect1> |
120 | <title>See Also</title> | |
121 | ||
13a69c12 DT |
122 | <para><simplelist type="inline"> |
123 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
124 | <member><citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
125 | <member><citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
126 | </simplelist></para> | |
798d3a52 | 127 | </refsect1> |
12355095 LP |
128 | |
129 | </refentry> |