X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd-id128.xml;h=5a4146a0f9c044fdc3566b8081c611e82da156fc;hp=d3f995e00803676ebf45fdbffc27287e4afcb514;hb=d86dd07d462fb8502b1c7b4a9a4df4fba8318bdd;hpb=cb07866b1b7c11e687a322d70dd9f9d73bbbe488

diff --git a/man/sd-id128.xml b/man/sd-id128.xml
index d3f995e00..5a4146a0f 100644
--- a/man/sd-id128.xml
+++ b/man/sd-id128.xml
@@ -21,7 +21,8 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="sd-id128">
+<refentry id="sd-id128"
+        xmlns:xi="http://www.w3.org/2001/XInclude">
 
         <refentryinfo>
                 <title>sd-id128</title>
@@ -46,10 +47,11 @@
                 <refname>sd-id128</refname>
                 <refname>sd_id128_t</refname>
                 <refname>SD_ID128_MAKE</refname>
+                <refname>SD_ID128_CONST_STR</refname>
                 <refname>SD_ID128_FORMAT_STR</refname>
                 <refname>SD_ID128_FORMAT_VAL</refname>
                 <refname>sd_id128_equal</refname>
-                <refpurpose>APIs for processing 128 bit IDs</refpurpose>
+                <refpurpose>APIs for processing 128-bit IDs</refpurpose>
         </refnamediv>
 
         <refsynopsisdiv>
@@ -58,7 +60,7 @@
                 </funcsynopsis>
 
                 <cmdsynopsis>
-                        <command>pkg-config --cflags --libs libsystemd-id128</command>
+                        <command>pkg-config --cflags --libs libsystemd</command>
                 </cmdsynopsis>
 
         </refsynopsisdiv>
@@ -67,23 +69,24 @@
                 <title>Description</title>
 
                 <para><filename>sd-id128.h</filename> provides APIs to
-                process and generate 128 bit ID values. The 128 bit ID
+                process and generate 128-bit ID values. The 128-bit ID
                 values processed and generated by these APIs are a
                 generalization of OSF UUIDs as defined by <ulink
-                url="http://tools.ietf.org/html/rfc4122">RFC
-                4122</ulink>, though use a simpler string
-                formatting. These functions impose no structure on the
+                url="https://tools.ietf.org/html/rfc4122">RFC
+                4122</ulink> but use a simpler string
+                format. These functions impose no structure on the
                 used IDs, much unlike OSF UUIDs or Microsoft GUIDs,
                 but are fully compatible with those types of IDs.
                 </para>
 
                 <para>See
-                <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
-                <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+                <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 for more information about the implemented
                 functions.</para>
 
-                <para>A 128 bit ID is implemented as the following
+                <para>A 128-bit ID is implemented as the following
                 union type:</para>
 
                 <programlisting>typedef union sd_id128 {
@@ -91,26 +94,36 @@
         uint64_t qwords[2];
 } sd_id128_t;</programlisting>
 
-                <para>This union type allows accessing the 128 bit ID
-                as 16 separate bytes or two 64 bit words. It is generally
-                safer to access the ID components by their 8 bit array
+                <para>This union type allows accessing the 128-bit ID
+                as 16 separate bytes or two 64-bit words. It is generally
+                safer to access the ID components by their 8-bit array
                 to avoid endianness issues. This union is intended to
                 be passed call-by-value (as opposed to
                 call-by-reference) and may be directly manipulated by
                 clients.</para>
 
                 <para>A couple of macros are defined to denote and
-                decode 128 bit IDs:</para>
+                decode 128-bit IDs:</para>
 
                 <para><function>SD_ID128_MAKE()</function> may be used
-                to write a 128 bit ID in source code. A commonly used
-                idiom is to give 128 bit IDs names using this macro:</para>
+                to denote a constant 128-bit ID in source code. A
+                commonly used idiom is to assign a name to a 128-bit
+                ID using this macro:</para>
 
                 <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting>
 
+                <para><function>SD_ID128_CONST_STR()</function> may be
+                used to convert constant 128-bit IDs into constant
+                strings for output. The following example code will
+                output the string
+                "fc2e22bc6ee647b6b90729ab34a250b1":</para>
+                <programlisting>int main(int argc, char *argv[]) {
+        puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
+}</programlisting>
+
                 <para><function>SD_ID128_FORMAT_STR</function> and
                 <function>SD_ID128_FORMAT_VAL()</function> may be used
-                to format a 128 bit ID in a
+                to format a 128-bit ID in a
                 <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 format string, as shown in the following
                 example:</para>
@@ -122,7 +135,7 @@
         return 0;
 }</programlisting>
 
-                <para>Use <function>sd_id128_equal()</function> to compare two 128 bit IDs:</para>
+                <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para>
 
                 <programlisting>int main(int argc, char *argv[]) {
         sd_id128_t a, b, c;
@@ -137,19 +150,10 @@
                 <para>Note that new, randomized IDs may be generated
                 with
                 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
-                <literal>--new-id</literal> option.</para>
+                <option>--new-id</option> option.</para>
         </refsect1>
 
-        <refsect1>
-                <title>Notes</title>
-
-                <para>These APIs are implemented as a 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>
+        <xi:include href="libsystemd-pkgconfig.xml" />
 
         <refsect1>
                 <title>See Also</title>
@@ -157,6 +161,7 @@
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,