Given that we have 3 places to document UUID related information,

namely uuidgen(1), uuidgen(2) and uuid(3), the following division
has been choosen:
	uuidgen(1)	A description of the command line utility,
			and other user oriented UUID information.
	uuidgen(2)	A mostly technical description of UUIDs.
	uuid(3)		A description of the functions and other
			programmer oriented UUID information.

According to the division: add more technical contents.

Contributed by: Hiten Pandya <hiten@uk.FreeBSD.org>
Edited and enhanced: marcel

1 files changed, 69 insertions, 9 deletions

diff --git a/lib/libc/sys/uuidgen.2 b/lib/libc/sys/uuidgen.2
index 61b2fe0..726039a 100644
--- a/lib/libc/sys/uuidgen.2
+++ b/lib/libc/sys/uuidgen.2
@@ -35,7 +35,7 @@
 .Sh SYNOPSIS
 .In sys/uuid.h
 .Ft int
-.Fn uuidgen "uuid_t *store" "int count"
+.Fn uuidgen "struct uuid *store" "int count"
 .Sh DESCRIPTION
 The
 .Nm
@@ -46,18 +46,71 @@ pointed to by
 .Fa store .
 The identifiers are generated according to the syntax and semantics of the
 DCE version 1 variant of universally unique identifiers.
+See below for a more in-depth description of the identifiers.
 When no IEEE 802
-address is available for the node field a random multicast address is
-generated for each call.
+address is available for the node field, a random multicast address is
+generated for each invocation of the system call.
+According to the algorithm of generating time-based UUIDs, this will also
+force a new random clock sequence, thereby increasing the likelyhood for
+the identifier to be unique.
 .Pp
-When multiple identifiers are requested, the
+When multiple identifiers are to be generated, the
 .Nm
-system call will generate identifiers that are adjacent in time.
+system call will generate a set of identifiers that is dense in such a way
+that there is no identifier that is larger than the smallest identifier in the
+set and smaller than the largest identifier in the set and that is not already
+in the set.
 .Pp
-Universally unique identifiers, also known as globally unique identifiers,
-are normally represented as:
+Universally unique identifiers, also known as globally unique identifiers
+(GUIDs), have a binary representation of 128-bits.
+The grouping and meaning of these bits is described by the following
+structure and its description of the fields that follow it:
+.Bd -literal
+struct uuid {
+	uint32_t	time_low;
+	uint16_t	time_mid;
+	uint16_t	time_hi_and_version;
+	uint8_t		clock_seq_hi_and_reserved;
+	uint8_t		clock_seq_low;
+	uint8_t		node[_UUID_NODE_LEN];
+};
+.Ed
 .Pp
-.Dl 63d81915-7140-11d6-903d-00022d09712b
+.Bl -tag -width _clock_seq_hi_and_reserved_
+.It time_low
+The least significant 32 bits of a 60-bit timestamp.
+This field is stored in the native byte-order.
+.It time_mid
+The least significant 16 bits of the most significant 28 bits of the 60-bit
+timestamp.
+This field is stored in the native byte-order.
+.It time_hi_and_reserved
+The most significant 12 bits of the 60-bit timestamp multiplexed with a 4-bit
+version number.
+The version number is stored in the most significant 4 bits of the 16-bit
+field.
+This field is stored in the native byte-order.
+.It clock_seq_hi_and_reserved
+The most significant 6 bits of a 14-bit sequence number multiplexed with a
+2-bit variant value.
+Note that the width of the variant value is determined by the variant itself.
+Identifiers generated by the
+.Nm
+system call have variant value 10b.
+the variant value is stored in the most significant bits of the field.
+.It clock_seq_low
+The least significant 8 bits of a 14-bit sequence number.
+.It node
+The 6-byte IEEE 802 (MAC) address of one of the interfaces of the node.
+If no such interface exists, a random multi-cast address is used instead.
+.El
+.Pp
+The binary representation is sensitive to byte ordering.
+Any multi-byte field is to be stored in the local or native byte-order and
+identifiers must be converted when transmitted to hosts that do not agree
+on the byte-order.
+The specification does not however document what this means in concrete
+terms and is otherwise beyond the scope of this system call.
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS
@@ -75,7 +128,14 @@ The
 parameter is less than 1 or larger than the hard upper limit of 2048.
 .El
 .Sh SEE ALSO
-.Xr uuidgen 1
+.Xr uuidgen 1 ,
+.Xr uuid 3
+.Sh STANDARDS
+The identifiers are represented and generated in conformance with the DCE 1.1
+RPC specification.
+The
+.Nm
+system call is itself not part of the specification.
 .Sh HISTORY
 The
 .Nm