<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="sd_id128_to_string">

<refentryinfo>

<title>sd_id128_to_string</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_id128_to_string</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_id128_to_string</refname>

<refname>sd_id128_from_string</refname>

<refpurpose>Format or parse 128-bit IDs as strings</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-id128.h&gt;</funcsynopsisinfo>

<funcprototype>

<funcdef>char* <function>sd_id128_to_string</function></funcdef>

<paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[33]</paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_id128_from_string</function></funcdef>

<paramdef>const char* <parameter>s</parameter>, sd_id128_t* <parameter>ret</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_id128_to_string()</function>

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>

<para><function>sd_id128_from_string()</function>

implements the reverse operation: it takes a 33

character string with 32 hexadecimal digits

(either lowercase or uppercase, terminated by NUL) 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>. 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

often easier to use a format string for

<citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This

is easily done using the

<function>SD_ID128_FORMAT_STR</function> and

<function>SD_ID128_FORMAT_VAL()</function> macros. For

more information see

<citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<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

errno-style error code.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<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>

file.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>