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