NAME

       uuid_generate,  uuid_generate_random,  uuid_generate_time,  uuid_generate_time_safe - create a new unique
       UUID value

SYNOPSIS

       #include <uuid.h>

       void uuid_generate(uuid_t out);
       void uuid_generate_random(uuid_t out);
       void uuid_generate_time(uuid_t out);
       int uuid_generate_time_safe(uuid_t out);
       void uuid_generate_md5(uuid_t out, const uuid_t ns, const char *name, size_t len);
       void uuid_generate_sha1(uuid_t out, const uuid_t ns, const char *name, size_t len);

DESCRIPTION

       The uuid_generate function creates a  new  universally  unique  identifier  (UUID).   The  uuid  will  be
       generated based on high-quality randomness from /dev/urandom, if available.  If it is not available, then
       uuid_generate  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.

       The uuid_generate_random function forces the use of the all-random UUID format, even  if  a  high-quality
       random  number  generator  (i.e., /dev/urandom) 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.

       The  uuid_generate_time  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
       uuid_generate  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 uuidd 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 uuid_generate_time_safe.

       The  uuid_generate_time_safe  function  is  similar to uuid_generate_time, except that it returns a value
       which denotes whether any of the synchronization mechanisms (see above) has been used.

       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 Cosmos).  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.

       The uuid_generate_md5 and uuid_generate_sha1 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.

RETURN VALUE

       The  newly  created  UUID  is returned in the memory location pointed to by out.  uuid_generate_time_safe
       returns zero if the UUID has been generated in a safe manner, -1 otherwise.

CONFORMING TO

       This library generates UUIDs compatible with OSF DCE 1.1, and hash based UUIDs V3 and V5 compatible  with
       RFC-4122.

AUTHOR

       Theodore Y. Ts'o

AVAILABILITY

       libuuid   is   part   of   the   util-linux   package   since   version  2.15.1  and  is  available  from
       https://www.kernel.org/pub/linux/utils/util-linux/.

SEE ALSO

       uuidgen(1),  uuid(3),  uuid_clear(3),  uuid_compare(3),  uuid_copy(3),  uuid_is_null(3),   uuid_parse(3),
       uuid_time(3), uuid_unparse(3), uuidd(8)

util-linux                                          May 2009                                    UUID_GENERATE(3)