]>
Commit | Line | Data |
---|---|---|
754fed0c KZ |
1 | .\" Copyright 1999 Andreas Dilger (adilger@enel.ucalgary.ca) |
2 | .\" | |
3 | .\" %Begin-Header% | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, and the entire permission notice in its entirety, | |
9 | .\" including the disclaimer of warranties. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. The name of the author may not be used to endorse or promote | |
14 | .\" products derived from this software without specific prior | |
15 | .\" written permission. | |
16 | .\" | |
17 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED | |
18 | .\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES | |
19 | .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF | |
20 | .\" WHICH ARE HEREBY DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE | |
21 | .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
22 | .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT | |
23 | .\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR | |
24 | .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | |
25 | .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
26 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE | |
27 | .\" USE OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH | |
28 | .\" DAMAGE. | |
29 | .\" %End-Header% | |
30 | .\" | |
31 | .\" Created Wed Mar 10 17:42:12 1999, Andreas Dilger | |
601d12fb | 32 | .TH UUID_GENERATE 3 "May 2009" "util-linux" "Libuuid API" |
754fed0c | 33 | .SH NAME |
e3d4e31c PU |
34 | uuid_generate, uuid_generate_random, uuid_generate_time, |
35 | uuid_generate_time_safe \- create a new unique UUID value | |
754fed0c KZ |
36 | .SH SYNOPSIS |
37 | .nf | |
8890b913 | 38 | .B #include <uuid.h> |
754fed0c KZ |
39 | .sp |
40 | .BI "void uuid_generate(uuid_t " out ); | |
41 | .BI "void uuid_generate_random(uuid_t " out ); | |
42 | .BI "void uuid_generate_time(uuid_t " out ); | |
e3d4e31c | 43 | .BI "int uuid_generate_time_safe(uuid_t " out ); |
754fed0c KZ |
44 | .fi |
45 | .SH DESCRIPTION | |
46 | The | |
47 | .B uuid_generate | |
48 | function creates a new universally unique identifier (UUID). The uuid will | |
49 | be generated based on high-quality randomness from | |
50 | .IR /dev/urandom , | |
51 | if available. If it is not available, then | |
52 | .B uuid_generate | |
53 | will use an alternative algorithm which uses the current time, the | |
54 | local ethernet MAC address (if available), and random data generated | |
55 | using a pseudo-random generator. | |
56 | .sp | |
57 | The | |
58 | .B uuid_generate_random | |
59 | function forces the use of the all-random UUID format, even if | |
60 | a high-quality random number generator (i.e., | |
61 | .IR /dev/urandom ) | |
62 | is not available, in which case a pseudo-random | |
62b47b3a | 63 | generator will be substituted. Note that the use of a pseudo-random |
333ec749 | 64 | generator may compromise the uniqueness of UUIDs |
754fed0c KZ |
65 | generated in this fashion. |
66 | .sp | |
67 | The | |
68 | .B uuid_generate_time | |
69 | function forces the use of the alternative algorithm which uses the | |
70 | current time and the local ethernet MAC address (if available). | |
71 | This algorithm used to be the default one used to generate UUID, but | |
72 | because of the use of the ethernet MAC address, it can leak | |
73 | information about when and where the UUID was generated. This can cause | |
74 | privacy problems in some applications, so the | |
75 | .B uuid_generate | |
76 | function only uses this algorithm if a high-quality source of | |
e3d4e31c PU |
77 | randomness is not available. To guarantee uniqueness of UUIDs generated |
78 | by concurrently running processes, the uuid library uses global | |
79 | clock state counter (if the process has permissions to gain exclusive access | |
80 | to this file) and/or the | |
81 | .B uuidd | |
f014c1c2 | 82 | daemon, if it is running already or can be spawned by the process (if |
e3d4e31c PU |
83 | installed and the process has enough permissions to run it). If neither of |
84 | these two synchronization mechanisms can be used, it is theoretically possible | |
85 | that two concurrently running processes obtain the same UUID(s). To tell | |
86 | whether the UUID has been generated in a safe manner, use | |
87 | .BR uuid_generate_time_safe . | |
88 | .sp | |
89 | The | |
90 | .B uuid_generate_time_safe | |
91 | is similar to | |
92 | .BR uuid_generate_time , | |
93 | except that it returns a value which denotes whether any of the synchronization | |
94 | mechanisms (see above) has been used. | |
754fed0c KZ |
95 | .sp |
96 | The UUID is 16 bytes (128 bits) long, which gives approximately 3.4x10^38 | |
62b47b3a | 97 | unique values (there are approximately 10^80 elementary particles in |
754fed0c KZ |
98 | the universe according to Carl Sagan's |
99 | .IR Cosmos ). | |
100 | The new UUID can reasonably be considered unique among all UUIDs created | |
101 | on the local system, and among UUIDs created on other systems in the past | |
102 | and in the future. | |
103 | .SH RETURN VALUE | |
104 | The newly created UUID is returned in the memory location pointed to by | |
105 | .IR out . | |
e3d4e31c | 106 | .B uuid_generate_time_safe |
ba0738ea | 107 | returns zero if the UUID has been generated in a safe manner, \-1 otherwise. |
754fed0c KZ |
108 | .SH "CONFORMING TO" |
109 | OSF DCE 1.1 | |
110 | .SH AUTHOR | |
ba0738ea | 111 | Theodore Y.\& Ts'o |
754fed0c | 112 | .SH AVAILABILITY |
af610010 | 113 | .B libuuid |
601d12fb KZ |
114 | is part of the util-linux package since version 2.15.1 and is available from |
115 | ftp://ftp.kernel.org/pub/linux/utils/util-linux/. | |
754fed0c | 116 | .SH "SEE ALSO" |
754fed0c | 117 | .BR uuidgen (1), |
f053ff1e | 118 | .BR uuid (3), |
754fed0c KZ |
119 | .BR uuid_clear (3), |
120 | .BR uuid_compare (3), | |
121 | .BR uuid_copy (3), | |
122 | .BR uuid_is_null (3), | |
123 | .BR uuid_parse (3), | |
124 | .BR uuid_time (3), | |
f053ff1e MK |
125 | .BR uuid_unparse (3), |
126 | .BR uuidd (8) |