bionic (3) uuid_generate_time_safe.3.gz

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);

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 UUID, 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 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 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.

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

       OSF DCE 1.1

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)