ChangeLog, gen_uuid.c:

[tools/e2fsprogs.git] / lib / uuid / uuid_generate.3.in

diff --git a/lib/uuid/uuid_generate.3.in b/lib/uuid/uuid_generate.3.in
index 33455f6..cbfdb1a 100644 (file)
--- a/lib/uuid/uuid_generate.3.in
+++ b/lib/uuid/uuid_generate.3.in
@@ -7,22 +7,48 @@
 .\" Created  Wed Mar 10 17:42:12 1999, Andreas Dilger
 .TH UUID_GENERATE 3 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
 .SH NAME
-uuid_generate \- create a new unique UUID value
+uuid_generate, uuid_generate_random, uuid_generate_time \- create a new unique UUID value
 .SH SYNOPSIS
 .nf
 .B #include <uuid/uuid.h>
 .sp
 .BI "void uuid_generate(uuid_t " out );
+.BI "void uuid_generate_random(uuid_t " out );
+.BI "void uuid_generate_time(uuid_t " out );
 .fi
 .SH DESCRIPTION
 The
 .B uuid_generate
-function creates a new universally unique identifier.  Depending on
-compile\- and run\-time availability, the UUID will be based on the
-local ethernet MAC address (if available), random data from /dev/urandom
-or a pseudo\-random generator
-.BR rand "(3) or " random "(3),"
-and the current time.
+function creates a new universally unique identifier (UUID).  The uuid will
+be generated based on high-quality randomness from 
+.IR /dev/urandom , 
+if available.  If it is not available, then 
+.B 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.
+.sp
+The 
+.B uuid_generate_random
+function forces the use of the all-random UUID format, even if
+a high-quality random number generator (i.e., 
+.IR /dev/urandom )
+is not available, in which case a pseudo-random
+generator will be subsituted.  Note that the use of a pseudo-random
+generator may compromise the uniqueness of UUID's
+generated in this fashion.
+.sp
+The
+.B 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
+.B uuid_generate
+function only uses this algorithm if a high-quality source of
+randomness is not available.  
 .sp
 The UUID is 16 bytes (128 bits) long, which gives approximately 3.4x10^38
 unique values (there are approximately 10^80 elemntary particles in