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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   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
  39     randomized 128-bit ID and returns it in
  40     <parameter>ret</parameter>. Every invocation returns a new
  41     randomly generated ID. This uses the
  42     <filename>/dev/urandom</filename> kernel random number
  43     generator.</para>
  44
  45     <para>Note that <function>sd_id128_randomize()</function> always
  46     returns a UUID v4-compatible ID.</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>See Also</title>
  69
  70     <para>
  71       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  72       <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  73       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  74       <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
  75       <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  76     </para>
  77   </refsect1>
  78
  79 </refentry>