<refnamediv>
<refname>sd_id128_to_string</refname>
<refname>sd_id128_from_string</refname>
- <refpurpose>Format or parse 128 bit IDs as strings</refpurpose>
+ <refpurpose>Format or parse 128-bit IDs as strings</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcprototype>
<funcdef>int <function>sd_id128_from_string</function></funcdef>
- <paramdef>const char <parameter>s</parameter>[33], sd_id128_t* <parameter>ret</parameter></paramdef>
+ <paramdef>const char* <parameter>s</parameter>, sd_id128_t* <parameter>ret</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<title>Description</title>
<para><function>sd_id128_to_string()</function>
- formats a 128 bit ID as character string. It expects
+ formats a 128-bit ID as a character string. It expects
the ID and a string array capable of storing 33
characters. The ID will be formatted as 32 lowercase
- hexadecimal digits and be terminated by a NUL
- byte.</para>
+ hexadecimal digits and be terminated by a
+ <constant>NUL</constant> byte.</para>
<para><function>sd_id128_from_string()</function>
implements the reverse operation: it takes a 33
- character array with 32 hexadecimal digits
- (terminated by NUL) and parses them back into an
- 128 bit ID returned in
- <parameter>ret</parameter>.</para>
+ character string with 32 hexadecimal digits (either
+ lowercase or uppercase, terminated by
+ <constant>NUL</constant>) and parses them back into a
+ 128-bit ID returned in
+ <parameter>ret</parameter>. Alternatively, this call
+ can also parse a 37-character string with a 128-bit ID
+ formatted as RFC UUID.</para>
<para>For more information about the
<literal>sd_id128_t</literal> type see
- <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+ <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note
+ that these calls operate the same way on all
+ architectures, i.e. the results do not depend on
+ endianness.</para>
- <para>When formatting a 128 bit ID into a string it is
+ <para>When formatting a 128-bit ID into a string, it is
often easier to use a format string for
<citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
is easily done using the
<para><function>sd_id128_to_string()</function> always
succeeds and returns a pointer to the string array
- passed in. <function>sd_id128_from_string</function>
- returns 0 on success (in which case
- <parameter>ret</parameter> is filled in), or a negative
+ passed in. <function>sd_id128_from_string</function>
+ returns 0 on success, in which case
+ <parameter>ret</parameter> is filled in, or a negative
errno-style error code.</para>
</refsect1>
<para>The <function>sd_id128_to_string()</function>
and <function>sd_id128_from_string()</function> interfaces are
- available as shared library, which can be compiled and
- linked to with the <literal>libsystemd-id128</literal>
- <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ available as a shared library, which can be compiled and
+ linked to with the <literal>libsystemd</literal> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>