libuuid: update manpage, mention uuid_generate_time_safe

Signed-off-by: Petr Uzel <petr.uzel@suse.cz>

diff --git a/shlibs/uuid/man/Makefile.am b/shlibs/uuid/man/Makefile.am
index 38809522bc3134576604255fd6bdf13f2872b0ba..8e9ed6d1f5c686ae2726fb5d6353b42931720944 100644 (file)
--- a/shlibs/uuid/man/Makefile.am
+++ b/shlibs/uuid/man/Makefile.am
@@ -3,7 +3,7 @@ include $(top_srcdir)/config/include-Makefile.am
 dist_man_MANS = uuid.3 uuid_clear.3 uuid_compare.3 uuid_copy.3 uuid_generate.3 \
                uuid_is_null.3 uuid_parse.3 uuid_time.3 uuid_unparse.3
 
-UUID_GENERATE_LINKS = uuid_generate_random.3 uuid_generate_time.3
+UUID_GENERATE_LINKS = uuid_generate_random.3 uuid_generate_time.3 uuid_generate_time_safe.3
 
 man_MANS = $(UUID_GENERATE_LINKS)
 CLEANFILES = $(man_MANS)

diff --git a/shlibs/uuid/man/uuid_generate.3 b/shlibs/uuid/man/uuid_generate.3
index 88062478b3ead2a2d70e5d7dbebffdd0e3f36b07..8185056418ac75fb3c79170648fe9707a04aa512 100644 (file)
--- a/shlibs/uuid/man/uuid_generate.3
+++ b/shlibs/uuid/man/uuid_generate.3
@@ -31,7 +31,8 @@
 .\" Created  Wed Mar 10 17:42:12 1999, Andreas Dilger
 .TH UUID_GENERATE 3 "May 2009" "util-linux" "Libuuid API"
 .SH NAME
-uuid_generate, uuid_generate_random, uuid_generate_time \- create a new unique UUID value
+uuid_generate, uuid_generate_random, uuid_generate_time,
+uuid_generate_time_safe \- create a new unique UUID value
 .SH SYNOPSIS
 .nf
 .B #include <uuid/uuid.h>
@@ -39,6 +40,7 @@ uuid_generate, uuid_generate_random, uuid_generate_time \- create a new unique U
 .BI "void uuid_generate(uuid_t " out );
 .BI "void uuid_generate_random(uuid_t " out );
 .BI "void uuid_generate_time(uuid_t " out );
+.BI "int uuid_generate_time_safe(uuid_t " out );
 .fi
 .SH DESCRIPTION
 The
@@ -72,7 +74,24 @@ 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.
+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
+.B uuidd
+daemon, if it is running already or can be 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
+.BR uuid_generate_time_safe .
+.sp
+The
+.B uuid_generate_time_safe
+is similar to
+.BR uuid_generate_time ,
+except that it returns a value which denotes whether any of the synchronization
+mechanisms (see above) has been used.
 .sp
 The UUID is 16 bytes (128 bits) long, which gives approximately 3.4x10^38
 unique values (there are approximately 10^80 elementary particles in
@@ -84,6 +103,8 @@ and in the future.
 .SH RETURN VALUE
 The newly created UUID is returned in the memory location pointed to by
 .IR out .
+.B uuid_generate_time_safe
+returns zero if the UUID has been generated in a safe manner, -1 otherwise.
 .SH "CONFORMING TO"
 OSF DCE 1.1
 .SH AUTHOR
@@ -95,6 +116,7 @@ ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
 .SH "SEE ALSO"
 .BR uuid (3),
 .BR uuidgen (1),
+.BR uuidd (8),
 .BR uuid_clear (3),
 .BR uuid_compare (3),
 .BR uuid_copy (3),

diff --git a/shlibs/uuid/man/uuid_generate_time_safe.3 b/shlibs/uuid/man/uuid_generate_time_safe.3
new file mode 100644 (file)
index 0000000..8405486
--- /dev/null
+++ b/shlibs/uuid/man/uuid_generate_time_safe.3
@@ -0,0 +1 @@
+.so man3/uuid_generate.3

diff --git a/shlibs/uuid/man/uuid_time.3 b/shlibs/uuid/man/uuid_time.3
index 786e8c4039e52ab61cb1a8720971a9ecfb86e67f..b2d1579cdcaa98f4706bc77a123e5727b3734a11 100644 (file)
--- a/shlibs/uuid/man/uuid_time.3
+++ b/shlibs/uuid/man/uuid_time.3
@@ -47,7 +47,9 @@ was created.  Note that the UUID creation time is only encoded within
 certain types of UUIDs.  This function can only reasonably expect to
 extract the creation time for UUIDs created with the
 .BR uuid_generate_time (3)
-function.  It may or may not work with UUIDs created by other mechanisms.
+and
+.BR uuid_generate_time_safe (3)
+functions.  It may or may not work with UUIDs created by other mechanisms.
 .SH "RETURN VALUES"
 The time at which the UUID was created, in seconds since January 1, 1970 GMT
 (the epoch), is returned (see