man/sd_id128_randomize.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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_id128_randomize" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_id128_randomize</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_id128_randomize</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_id128_randomize</refname>
  20     <refpurpose>Generate 128-bit IDs</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <funcsynopsis>
  25       <funcsynopsisinfo>#include &lt;systemd/sd-id128.h&gt;</funcsynopsisinfo>
  26
  27       <funcprototype>
  28         <funcdef>int <function>sd_id128_randomize</function></funcdef>
  29         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  30       </funcprototype>
  31
  32     </funcsynopsis>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37
  38     <para><function>sd_id128_randomize()</function> generates a new randomized 128-bit ID and returns it in
  39     <parameter>ret</parameter>. Every invocation returns a new randomly generated ID. This uses the
  40     <citerefentry
  41     project='man-pages'><refentrytitle>getrandom</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  42     kernel random number generator.</para>
  43
  44     <para>Note that <function>sd_id128_randomize()</function> always returns a UUID Variant 1 Version 4
  45     compatible ID. It is hence guaranteed that this function will never return the ID consisting of all zero
  46     or all one bits (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>).</para>
  47
  48     <para>For more information about the <literal>sd_id128_t</literal>
  49     type, see
  50     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  51
  52     <para><citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  53     <command>new</command> command may be used as a command line front-end for
  54     <function>sd_id128_randomize()</function>.</para>
  55   </refsect1>
  56
  57   <refsect1>
  58     <title>Return Value</title>
  59
  60     <para>The call returns 0 on success (in which case
  61     <parameter>ret</parameter> is filled in), or a negative
  62     errno-style error code.</para>
  63   </refsect1>
  64
  65   <xi:include href="libsystemd-pkgconfig.xml" />
  66
  67   <refsect1>
  68     <title>History</title>
  69     <para><function>sd_id128_randomize()</function> was added in version 187.</para>
  70   </refsect1>
  71
  72   <refsect1>
  73     <title>See Also</title>
  74
  75     <para><simplelist type="inline">
  76       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
  77       <member><citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
  78       <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
  79       <member><citerefentry project='man-pages'><refentrytitle>getrandom</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
  80       <member><citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry></member>
  81       <member><citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
  82     </simplelist></para>
  83   </refsect1>
  84
  85 </refentry>