diff options
| -rw-r--r-- | lib/libc/sys/uuidgen.2 | 78 |
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 |
