man/sd_id128_randomize.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2012 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_id128_randomize">
  25
  26         <refentryinfo>
  27                 <title>sd_id128_randomize</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>sd_id128_randomize</refentrytitle>
  42                 <manvolnum>3</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>sd_id128_randomize</refname>
  47                 <refname>sd_id128_get_machine</refname>
  48                 <refname>sd_id128_get_boot</refname>
  49                 <refpurpose>Generate or retrieve 128 bit IDs</refpurpose>
  50         </refnamediv>
  51
  52         <refsynopsisdiv>
  53                 <funcsynopsis>
  54                         <funcsynopsisinfo>#include &lt;systemd/sd-id128.h&gt;</funcsynopsisinfo>
  55
  56                         <funcprototype>
  57                                 <funcdef>int <function>sd_id128_randomize</function></funcdef>
  58                                 <paramdef>sd_id128_t* <parameter>ret</parameter></paramdef>
  59                         </funcprototype>
  60
  61                         <funcprototype>
  62                                 <funcdef>int <function>sd_id128_get_machine</function></funcdef>
  63                                 <paramdef>sd_id128_t* <parameter>ret</parameter></paramdef>
  64                         </funcprototype>
  65
  66                         <funcprototype>
  67                                 <funcdef>int <function>sd_id128_get_boot</function></funcdef>
  68                                 <paramdef>sd_id128_t* <parameter>ret</parameter></paramdef>
  69                         </funcprototype>
  70
  71                 </funcsynopsis>
  72         </refsynopsisdiv>
  73
  74         <refsect1>
  75                 <title>Description</title>
  76
  77                 <para><function>sd_id128_randomize()</function>
  78                 generates a new randomized 128 bit ID and returns it
  79                 in <parameter>ret</parameter>. Every invocation
  80                 returns a new randomly generated ID. This uses the
  81                 <filename>/dev/urandom</filename> kernel random number
  82                 generator.</para>
  83
  84                 <para><function>sd_id128_get_machine()</function>
  85                 returns the machine ID of the executing host. This
  86                 reads and parses the
  87                 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  88                 file. This function caches the machine ID internally
  89                 to make retrieving the machine ID a cheap
  90                 operation.</para>
  91
  92                 <para><function>sd_id128_get_boot()</function> returns
  93                 the boot ID of the executing kernel. This reads and
  94                 parses the
  95                 <filename>/proc/sys/kernel/random/boot_id</filename>
  96                 file exposed by the kernel. It is randomly generated
  97                 early at boot and is unique for every running kernel
  98                 instance. See
  99                 <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 100                 for more information. This function also internally
 101                 caches the returned ID to make this call a cheap
 102                 operation.</para>
 103
 104                 <para>Note that
 105                 <function>sd_id128_randomize()</function> and
 106                 <function>sd_id128_get_boot()</function> always return
 107                 a UUID v4 compatible
 108                 ID. <function>sd_id128_get_machine()</function> will
 109                 also return a UUID v4 compatible ID on new
 110                 installations, but might not on older. It is possible
 111                 to convert the machine ID into an UUID v4 compatible
 112                 one. For more information see
 113                 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 114
 115                 <para>For more information about the
 116                 <literal>sd_id128_t</literal> type see
 117                 <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 118
 119                 <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 120                 <literal>--new-id</literal> command may be used as
 121                 command line front-end for
 122                 <function>sd_id128_randomize()</function>.</para>
 123         </refsect1>
 124
 125         <refsect1>
 126                 <title>Return Value</title>
 127
 128                 <para>The three calls returns 0 on success (in which
 129                 case <parameter>ret</parameter> is filled in), or a
 130                 negative errno-style error code.</para>
 131         </refsect1>
 132
 133         <refsect1>
 134                 <title>Notes</title>
 135
 136                 <para>The <function>sd_id128_randomize()</function>,
 137                 <function>sd_id128_get_machine()</function> and
 138                 <function>sd_id128_get_boot()</function> interfaces
 139                 are available as shared library, which can be compiled
 140                 and linked to with the
 141                 <literal>libsystemd-id128</literal>
 142                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 143                 file.</para>
 144         </refsect1>
 145
 146         <refsect1>
 147                 <title>See Also</title>
 148
 149                 <para>
 150                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 151                         <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 152                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 153                         <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 154                 </para>
 155         </refsect1>
 156
 157 </refentry>