uuid_generate

UUID_GENERATE(3)                  Libuuid API                 UUID_GENERATE(3)

NAME
       uuid_generate,  uuid_generate_random,  uuid_generate_time,  uuid_gener-
       ate_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 algo-
       rithm which uses the current time and the local  ethernet  MAC  address
       (if available).  This algorithm used to be the default one used to gen-
       erate 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 func-
       tion only uses this algorithm if a high-quality source of randomness is
       not available.  To guarantee uniqueness of UUIDs generated  by  concur-
       rently  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 permis-
       sions  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 syn-
       chronization 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 par-
       ticles in the universe according to Carl Sagan's Cosmos).  The new UUID
       can  reasonably be considered unique among all UUIDs created on the lo-
       cal 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 gener-
       ated 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)