man/systemd-id128.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-id128" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>systemd-id128</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-id128</refentrytitle>
  15     <manvolnum>1</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-id128</refname>
  20     <refpurpose>Generate and print sd-128 identifiers</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <cmdsynopsis>
  25       <command>systemd-id128</command>
  26       <arg choice="opt" rep="repeat">OPTIONS</arg>
  27       <arg choice="plain">new</arg>
  28     </cmdsynopsis>
  29
  30     <cmdsynopsis>
  31       <command>systemd-id128</command>
  32       <arg choice="opt" rep="repeat">OPTIONS</arg>
  33       <arg choice="plain">machine-id</arg>
  34     </cmdsynopsis>
  35
  36     <cmdsynopsis>
  37       <command>systemd-id128</command>
  38       <arg choice="opt" rep="repeat">OPTIONS</arg>
  39       <arg choice="plain">boot-id</arg>
  40     </cmdsynopsis>
  41
  42     <cmdsynopsis>
  43       <command>systemd-id128</command>
  44       <arg choice="opt" rep="repeat">OPTIONS</arg>
  45       <arg choice="plain">invocation-id</arg>
  46     </cmdsynopsis>
  47   </refsynopsisdiv>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para><command>id128</command> may be used to conveniently print
  53     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  54     UUIDs. What identifier is printed depends on the specific verb.</para>
  55
  56     <para>With <command>new</command>, a new random identifier will be generated.</para>
  57
  58     <para>With <command>machine-id</command>, the identifier of the current machine will be
  59     printed. See
  60     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  61     </para>
  62
  63     <para>With <command>boot-id</command>, the identifier of the current boot will be
  64     printed.</para>
  65
  66     <para>Both <command>machine-id</command> and <command>boot-id</command> may be combined
  67     with the <option>--app-specific=<replaceable>app-id</replaceable></option> switch to
  68     generate application-specific IDs. See
  69     <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  70     for the discussion when this is useful.</para>
  71
  72     <para>With <command>invocation-id</command>, the identifier of the current service invocation
  73     will be printed. This is available in systemd services. See
  74     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  75     </para>
  76
  77     <para>With <command>show</command>, well-known IDs are printed (for now, only GPT partition type UUIDs),
  78     along with brief identifier strings. When no arguments are specified, all known IDs are shown. When
  79     arguments are specified, they must be the identifiers or ID values of one or more known IDs, which are
  80     then printed. Combine with <option>--uuid</option> to list the IDs in UUID style, i.e. the way GPT
  81     partition type UUIDs are usually shown.</para>
  82   </refsect1>
  83
  84   <refsect1>
  85     <title>Options</title>
  86
  87     <para>The following options are understood:</para>
  88
  89     <variablelist>
  90       <varlistentry>
  91         <term><option>-p</option></term>
  92         <term><option>--pretty</option></term>
  93
  94         <listitem><para>Generate output as programming language snippets.</para>
  95
  96         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
  97       </varlistentry>
  98
  99       <varlistentry>
 100         <term><option>-a <replaceable>app-id</replaceable></option></term>
 101         <term><option>--app-specific=<replaceable>app-id</replaceable></option></term>
 102
 103         <listitem><para>With this option, an identifier that is the result of hashing the
 104         application identifier <replaceable>app-id</replaceable> and the machine identifier will be
 105         printed. The <replaceable>app-id</replaceable> argument must be a valid sd-id128 string
 106         identifying the application.</para>
 107
 108         <xi:include href="version-info.xml" xpointer="v240"/>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><option>-u</option></term>
 114         <term><option>--uuid</option></term>
 115
 116         <listitem><para>Generate output as a UUID formatted in the "canonical representation", with five
 117         groups of digits separated by hyphens. See the
 118         <ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">wikipedia</ulink>
 119         for more discussion.</para>
 120
 121         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
 122       </varlistentry>
 123
 124       <xi:include href="standard-options.xml" xpointer="help" />
 125       <xi:include href="standard-options.xml" xpointer="version" />
 126     </variablelist>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Exit status</title>
 131
 132     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>See Also</title>
 137     <para>
 138       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 139       <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 140       <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 141     </para>
 142   </refsect1>
 143
 144 </refentry>