libmount: Add libselinux dependency to pkgconfig file

[thirdparty/util-linux.git] / misc-utils / uuidgen.1

diff --git a/misc-utils/uuidgen.1 b/misc-utils/uuidgen.1
index 4d64a10e1cf158db16102d6913ac1fdea77c050f..75fef5df605b1805947fc79efa9219b814a9d6bc 100644 (file)
--- a/misc-utils/uuidgen.1
+++ b/misc-utils/uuidgen.1
@@ -1,16 +1,12 @@
 .\" Copyright 1999 Andreas Dilger (adilger@enel.ucalgary.ca)
 .\"
-.\" This man page was created for libuuid.so.1.1 from e2fsprogs-1.14.
-.\"
 .\" This file may be copied under the terms of the GNU Public License.
-.\"
-.\" Created  Wed Mar 10 17:42:12 1999, Andreas Dilger
 .TH UUIDGEN 1 "June 2011" "util-linux" "User Commands"
 .SH NAME
 uuidgen \- create a new UUID value
 .SH SYNOPSIS
 .B uuidgen
-[\fIoptions\fR]
+[options]
 .SH DESCRIPTION
 The
 .B uuidgen
@@ -22,18 +18,41 @@ all UUIDs created on the local system,
 and among UUIDs created on other systems in the past
 and in the future.
 .PP
-There are two types of UUIDs which
+There are three types of UUIDs which
 .B uuidgen
-can generate: time-based UUIDs and random-based UUIDs.  By default
+can generate: time-based UUIDs, random-based UUIDs, and hash-based UUIDs.
+By default
 .B uuidgen
 will generate a random-based UUID if a high-quality random number
 generator is present.  Otherwise, it will choose a time-based UUID.
-It is possible to force the generation of one of these two
+It is possible to force the generation of one of these first two
 UUID types by using the
-.B \-r
+.B \-\-random
 or
-.B \-t
+.B \-\-time
 options.
+.PP
+The third type of UUID is generated with the
+.B \-\-md5
+or
+.B \-\-sha1
+options, followed by
+\fB\-\-namespace\fR \fInamespace\fR
+and
+\fB\-\-name\fR \fIname\fR.
+The \fInamespace\fR may either be a well-known UUID, or else
+an alias to one of the well-known UUIDs defined in RFC 4122, that is
+.BR @dns ,
+.BR @url ,
+.BR @oid ,
+or
+.BR @x500 .
+The \fIname\fR is an arbitrary string value.  The generated UUID is the
+digest of the concatenation of the namespace UUID and the name value, hashed
+with the MD5 or SHA1 algorithms.  It is, therefore, a predictable value
+which may be useful when UUIDs are being used as handles or nonces for
+more complex values or values which shouldn't be disclosed directly.
+See the RFC for more information.
 .SH OPTIONS
 .TP
 .BR \-r , " \-\-random"
@@ -51,13 +70,33 @@ Display help text and exit.
 .TP
 .BR \-V , " \-\-version"
 Display version information and exit.
+.TP
+.BR \-m , " \-\-md5"
+Use MD5 as the hash algorithm.
+.TP
+.BR \-s , " \-\-sha1"
+Use SHA1 as the hash algorithm.
+.TP
+.BR \-n , " \-\-namespace " \fInamespace\fP
+Generate the hash with the \fInamespace\fP prefix. The \fInamespace\fP is UUID,
+or '@ns' where "ns" is well-known predefined UUID addressed by namespace name
+(see above).
+.TP
+.BR \-N , " \-\-name " \fIname\fR
+Generate the hash of the \fIname\fR.
+.TP
+.BR \-x , " \-\-hex"
+Interpret name \fIname\fR as a hexadecimal string.
 .SH "CONFORMING TO"
 OSF DCE 1.1
+.SH EXAMPLES
+uuidgen \-\-sha1 \-\-namespace @dns \-\-name "www.example.com"
 .SH AUTHOR
 .B uuidgen
 was written by Andreas Dilger for libuuid.
 .SH SEE ALSO
-.BR libuuid (3)
+.BR libuuid (3),
+.B "RFC 4122"
 .SH AVAILABILITY
 The uuidgen command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+https://www.kernel.org/pub/linux/utils/util-linux/.