summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormarcel <marcel@FreeBSD.org>2002-11-11 00:29:01 +0000
committermarcel <marcel@FreeBSD.org>2002-11-11 00:29:01 +0000
commitad9b0af483750afc5bce8781176ac4f2c28a3c4f (patch)
treef13adcf9ee730f9bbca55d52775cbf35946abcbe
parent5cbd8d2e81d21b8fc30a2ff158944d918b8e8482 (diff)
downloadFreeBSD-src-ad9b0af483750afc5bce8781176ac4f2c28a3c4f.zip
FreeBSD-src-ad9b0af483750afc5bce8781176ac4f2c28a3c4f.tar.gz
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
-rw-r--r--lib/libc/sys/uuidgen.278
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
OpenPOWER on IntegriCloud