179 lines
5.8 KiB
HTML
179 lines
5.8 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of UUID_GENERATE</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>UUID_GENERATE</H1>
|
|
Section: Libuuid API (3)<BR>Updated: May 2009<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
uuid_generate, uuid_generate_random, uuid_generate_time,
|
|
uuid_generate_time_safe - create a new unique UUID value
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/uuid.h">uuid.h</A>></B>
|
|
|
|
<B>void uuid_generate(uuid_t </B><I>out</I><B>);</B>
|
|
<B>void uuid_generate_random(uuid_t </B><I>out</I><B>);</B>
|
|
<B>void uuid_generate_time(uuid_t </B><I>out</I><B>);</B>
|
|
<B>int uuid_generate_time_safe(uuid_t </B><I>out</I><B>);</B>
|
|
<B>void uuid_generate_md5(uuid_t </B><I>out</I><B>, const uuid_t </B><I>ns</I><B>, const char </B><I>*name</I><B>, size_t </B><I>len</I><B>);</B>
|
|
<B>void uuid_generate_sha1(uuid_t </B><I>out</I><B>, const uuid_t </B><I>ns</I><B>, const char </B><I>*name</I><B>, size_t </B><I>len</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<B>uuid_generate</B>
|
|
|
|
function creates a new universally unique identifier (UUID). The uuid will
|
|
be generated based on high-quality randomness from
|
|
<I>/dev/urandom</I>,
|
|
|
|
if available. If it is not available, then
|
|
<B>uuid_generate</B>
|
|
|
|
will use an alternative algorithm which uses the current time, the
|
|
local ethernet MAC address (if available), and random data generated
|
|
using a pseudo-random generator.
|
|
<P>
|
|
The
|
|
<B>uuid_generate_random</B>
|
|
|
|
function forces the use of the all-random UUID format, even if
|
|
a high-quality random number generator (i.e.,
|
|
<I>/dev/urandom</I>)
|
|
|
|
is not available, in which case a pseudo-random
|
|
generator will be substituted. Note that the use of a pseudo-random
|
|
generator may compromise the uniqueness of UUIDs
|
|
generated in this fashion.
|
|
<P>
|
|
The
|
|
<B>uuid_generate_time</B>
|
|
|
|
function forces the use of the alternative algorithm which uses the
|
|
current time and the local ethernet MAC address (if available).
|
|
This algorithm used to be the default one used to generate UUIDs, but
|
|
because of the use of the ethernet MAC address, it can leak
|
|
information about when and where the UUID was generated. This can cause
|
|
privacy problems in some applications, so the
|
|
<B>uuid_generate</B>
|
|
|
|
function only uses this algorithm if a high-quality source of
|
|
randomness is not available. To guarantee uniqueness of UUIDs generated
|
|
by concurrently running processes, the uuid library uses a global
|
|
clock state counter (if the process has permissions to gain exclusive access
|
|
to this file) and/or the
|
|
<B>uuidd</B>
|
|
|
|
daemon, if it is running already or can be spawned by the process (if
|
|
installed and the process has enough permissions to run it). If neither of
|
|
these two synchronization mechanisms can be used, it is theoretically possible
|
|
that two concurrently running processes obtain the same UUID(s). To tell
|
|
whether the UUID has been generated in a safe manner, use
|
|
<B>uuid_generate_time_safe</B>.
|
|
|
|
<P>
|
|
The
|
|
<B>uuid_generate_time_safe</B>
|
|
|
|
function is similar to
|
|
<B>uuid_generate_time</B>,
|
|
|
|
except that it returns a value which denotes whether any of the synchronization
|
|
mechanisms (see above) has been used.
|
|
<P>
|
|
The UUID is 16 bytes (128 bits) long, which gives approximately 3.4x10^38
|
|
unique values (there are approximately 10^80 elementary particles in
|
|
the universe according to Carl Sagan's
|
|
<I>Cosmos</I>).
|
|
|
|
The new UUID can reasonably be considered unique among all UUIDs created
|
|
on the local system, and among UUIDs created on other systems in the past
|
|
and in the future.
|
|
<P>
|
|
The
|
|
<B>uuid_generate_md5</B>
|
|
|
|
and
|
|
<B>uuid_generate_sha1</B>
|
|
|
|
functions generate an MD5 and SHA1 hashed (predictable) UUID based on a
|
|
well-known UUID providing the namespace and an arbitrary binary string. The UUIDs
|
|
conform to V3 and V5 UUIDs per RFC-4122.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
The newly created UUID is returned in the memory location pointed to by
|
|
<I>out</I>.
|
|
|
|
<B>uuid_generate_time_safe</B>
|
|
|
|
returns zero if the UUID has been generated in a safe manner, -1 otherwise.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
This library generates UUIDs compatible with OSF DCE 1.1, and hash based UUIDs
|
|
V3 and V5 compatible with RFC-4122.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Theodore Y. Ts'o
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
<B>libuuid</B>
|
|
|
|
is part of the util-linux package since version 2.15.1 and is available from
|
|
<A HREF="https://www.kernel.org/pub/linux/utils/util-linux/.">https://www.kernel.org/pub/linux/utils/util-linux/.</A>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+uuidgen">uuidgen</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid">uuid</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_clear">uuid_clear</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_compare">uuid_compare</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_copy">uuid_copy</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_is_null">uuid_is_null</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_parse">uuid_parse</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_time">uuid_time</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_unparse">uuid_unparse</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+uuidd">uuidd</A></B>(8)
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="4"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">CONFORMING TO</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">AUTHOR</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">AVAILABILITY</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:59 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|