uuid_generate(3)

1UUID_GENERATE(3)                  Libuuid API                 UUID_GENERATE(3)
2
3
4

NAME

6       uuid_generate,  uuid_generate_random,  uuid_generate_time,  uuid_gener‐
7       ate_time_safe - create a new unique UUID value
8

SYNOPSIS

10       #include <uuid.h>
11
12       void uuid_generate(uuid_t out);
13       void uuid_generate_random(uuid_t out);
14       void uuid_generate_time(uuid_t out);
15       int uuid_generate_time_safe(uuid_t out);
16

DESCRIPTION

18       The uuid_generate function creates a new universally unique  identifier
19       (UUID).   The  uuid  will be generated based on high-quality randomness
20       from  /dev/urandom,  if  available.   If  it  is  not  available,  then
21       uuid_generate  will use an alternative algorithm which uses the current
22       time, the local ethernet MAC address (if available),  and  random  data
23       generated using a pseudo-random generator.
24
25       The uuid_generate_random function forces the use of the all-random UUID
26       format,  even  if  a  high-quality  random  number   generator   (i.e.,
27       /dev/urandom) is not available, in which case a pseudo-random generator
28       will be substituted.  Note that the use of  a  pseudo-random  generator
29       may compromise the uniqueness of UUIDs generated in this fashion.
30
31       The uuid_generate_time function forces the use of the alternative algo‐
32       rithm which uses the current time and the local  ethernet  MAC  address
33       (if available).  This algorithm used to be the default one used to gen‐
34       erate UUID, but because of the use of the ethernet MAC address, it  can
35       leak information about when and where the UUID was generated.  This can
36       cause privacy problems in some applications, so the uuid_generate func‐
37       tion only uses this algorithm if a high-quality source of randomness is
38       not available.  To guarantee uniqueness of UUIDs generated  by  concur‐
39       rently  running  processes,  the  uuid  library uses global clock state
40       counter (if the process has permissions to  gain  exclusive  access  to
41       this  file) and/or the uuidd daemon, if it is running already or can be
42       spawned by the process (if installed and the process has enough permis‐
43       sions  to  run it).  If neither of these two synchronization mechanisms
44       can be used, it is theoretically possible that two concurrently running
45       processes  obtain  the same UUID(s).  To tell whether the UUID has been
46       generated in a safe manner, use uuid_generate_time_safe.
47
48       The uuid_generate_time_safe is similar  to  uuid_generate_time,  except
49       that  it  returns a value which denotes whether any of the synchroniza‐
50       tion mechanisms (see above) has been used.
51
52       The UUID is  16  bytes  (128  bits)  long,  which  gives  approximately
53       3.4x10^38  unique values (there are approximately 10^80 elementary par‐
54       ticles in the universe according to Carl Sagan's Cosmos).  The new UUID
55       can  reasonably  be  considered  unique  among all UUIDs created on the
56       local system, and among UUIDs created on other systems in the past  and
57       in the future.
58

RETURN VALUE

60       The newly created UUID is returned in the memory location pointed to by
61       out.  uuid_generate_time_safe returns zero if the UUID has been  gener‐
62       ated in a safe manner, -1 otherwise.
63

CONFORMING TO

65       OSF DCE 1.1
66

AUTHOR

68       Theodore Y. Ts'o
69

AVAILABILITY

71       libuuid  is  part of the util-linux package since version 2.15.1 and is
72       available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
73