--- uuid.pod 2004/01/11 08:54:18 1.4
+++ uuid.pod 2004/01/11 12:14:19 1.5
@@ -41,90 +41,194 @@
(UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and node
based), version 3 (name based) and version 4 (random number based).
-This is the ISO-C application programming interface (API).
-
-=head2 Overview
-
-B<UUID> stands for B<U>niversal B<U>nique B<ID>entifier (aka B<GUID>
-which stands for B<G>lobally B<U>nique B<ID>entifier). B<UUID>s are 128
-bit numbers assigned to any object and which are intended to have a high
-likelihood of uniqueness over space and time and are computationally
-difficult to guess.
-
UUIDs are 128 bit numbers which are intended to have a high likelihood
of uniqueness over space and time and are computationally difficult
to guess. They are globally unique identifiers which can be locally
-generated without contacting a global registration authority. UUIDs are
-intended as unique identifiers for both mass tagging objects with an
-extremely short lifetime and to reliably identifying very persistent
-objects across a network.
-
-A B<UUID> is usually encoded using the ASCII character string
-representation described in ISO/IEC 11578:1996: a string
-consisting of 8 hexadecimal digits followed by a hyphen,
-then three groups of 4 hexadecimal digits each followed by a
-hyphen, then 12 hexadecimal digits. An example of a B<UUID> is
-"C<54531d28-402b-11d8-af12-0002a5094c23>".
-
-=head2 Uniqueness
-
-The mechanism used to guarantee that B<UUID>s are unique is
-through combinations of hardware addresses, time stamps and random
-seeds.
-
-There is a reference in the B<UUID> to the hardware (MAC) address of
-the first network interface card (NIC) on the host which generated the
-B<UUID> -- this reference is intended to ensure the B<UUID> will be
-unique in space as the MAC address of every network card is assigned by
-a single global authority (IEEE) and is guaranteed to be unique.
-
-The next component in a B<UUID> is a timestamp which, as clock always
-(should) move forward, will be unique in time.
-
-Just in case some part of the above goes wrong (the hardware address
-cannot be determined or the clock moved a step backward), there is
-a random component placed into the B<UUID> as a "catch-all" for
-uniqueness.
+generated without contacting a global registration authority. UUIDs
+are intended as unique identifiers for both mass tagging objects
+with an extremely short lifetime and to reliably identifying very
+persistent objects across a network.
+
+This is the ISO-C application programming interface (API) of B<OSSP uuid>.
+
+=head2 UUID Binary Representation
+
+According to the DCE 1.1 and ISO/IEC 11578:1996 standards, a DCE 1.1
+variant UUID is a 128 bit number defined out of 7 fields, each field a
+multiple of an octet in size and stored in network byte order:
+
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ 0| time_low |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ 1| time_mid | time_hi_and_version |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ 2|clk_seq_hi_res | clk_seq_low | node (0-1) |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ 3| node (2-5) |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+An example of a UUID binary representation is the octet stream "C<0xEC
+0xB9 0xF3 0x5F 0x44 0x2A 0x11 0xD8 0x8A 0x24 0x00 0x90 0x27 0x2F 0xF7
+0x25>". The binary representation format is exactly what the B<OSSP uuid>
+API functions B<uuid_pack>() and B<uuid_unpack>() deal with.
+
+=head2 UUID ASCII String Representation
+
+According to the DCE 1.1 and ISO/IEC 11578:1996 standards, a DCE
+1.1 variant UUID is represented as an ASCII string consisting
+of 8 hexadecimal digits followed by a hyphen, then three groups
+of 4 hexadecimal digits each followed by a hyphen, then 12
+hexadecimal digits. Formally, the string representation is defined by
+the following grammar:
+
+ uuid = <time_low> "-" <time_mid> "-"
+ <time_high_and_version> "-"
+ <clock_seq_and_reserved>
+ <clock_seq_low> "-" <node>
+ time_low = 4*<hexOctet>
+ time_mid = 2*<hexOctet>
+ time_high_and_version = 2*<hexOctet>
+ clock_seq_and_reserved = <hexOctet>
+ clock_seq_low = <hexOctet>
+ node = 6*<hexOctet>
+ hexOctet = <hexDigit> <hexDigit>
+ hexDigit = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
+ |"a"|"b"|"c"|"d"|"e"|"f"
+ |"A"|"B"|"C"|"D"|"E"|"F"
+
+An example of a UUID string representation is the ASCII string
+"C<54531d28-402b-11d8-af12-0002a5094c23>". The string representation
+format is exactly what the B<OSSP uuid> API functions B<uuid_parse>() and
+B<uuid_format>() deal with.
+
+=head2 UUID Variants and Versions
+
+A UUID has a variant and version. The variant defines the layout of the
+UUID. The version defines the content of the UUID. The UUID variant
+supported in B<OSSP uuid> is the DCE 1.1 variant only. The DCE 1.1 UUID
+variant versions supported in B<OSSP uuid> are version 1 (time and node
+based), version 3 (name based) and version 4 (random data based).
+
+=head2 UUID Uniqueness
+
+Version 1 UUIDs are guaranteed to be unique through combinations of
+hardware addresses, time stamps and random seeds. There is a reference
+in the UUID to the hardware (MAC) address of the first network interface
+card (NIC) on the host which generated the UUID -- this reference
+is intended to ensure the UUID will be unique in space as the MAC
+address of every network card is assigned by a single global authority
+(IEEE) and is guaranteed to be unique. The next component in a UUID
+is a timestamp which, as clock always (should) move forward, will
+be unique in time. Just in case some part of the above goes wrong
+(the hardware address cannot be determined or the clock moved steps
+backward), there is a random clock sequence component placed into the
+UUID as a "catch-all" for uniqueness.
+
+Version 3 UUIDs are guaranteed to be inherently globally unique if the
+combination of namespace and name used to generate them is unique.
+
+Version 4 UUIDs are not guaranteed to be globally unique, because they
+are generated out of locally gathered pseudo-random numbers only.
+Nevertheless there is still a high likelihood of uniqueness over space
+and time and that they are computationally difficult to guess.
+
+=head2 Nil UUID
+
+There is a special I<Nil> UUID consisting of all octets set to zero in
+the binary representation. It can be used as a special UUID value which does
+not conflict with real UUIDs.
=head1 APPLICATION PROGRAMMING INTERFACE
+The ISO-C Application Programming Interface (API) of B<OSSP uuid>
+consists of the following components.
+
+=head2 CONSTANTS
+
+The following constants are provided:
+
+=over 4
+
+=item B<UUID_LEN_BIN>, B<UUID_LEN_STR>
+
+The number of octets of the UUID binary and string representations.
+Notice that the lengths of the string representation does I<not> include
+the necessary C<NUL> termination character.
+
+=item B<UUID_VERSION1>, B<UUID_VERSION3>, B<UUID_VERSION4>, B<UUID_MCASTRND>
+
+The I<mode> bits for use with B<uuid_generate>(). The
+B<UUID_VERSION>I<N> specify which UUID version to generate. The
+B<UUID_MCASTRND> forces the use of a random multi-cast MAC address
+instead of the real physical MAC address in version 1 UUIDs.
+
+=item B<UUID_RC_OK>, B<UUID_RC_ARG>, B<UUID_RC_MEM>, B<UUID_RC_SYS>, B<UUID_RC_INT>
+
+The possible numerical return-codes of API functions.
+Use B<uuid_error>() to translate them into string versions.
+
+=back
+
+=head2 FUNCTIONS
+
+The following functions are provided:
+
=over 4
=item uuid_rc_t B<uuid_create>(uuid_t **I<uuid>);
-FIXME
+Create a new UUID object and store a pointer to it in C<*>I<uuid>.
+A UUID object consists of an internal representation of a UUID, the
+internal PRNG and MD5 generator contexts, and cached MAC address and
+timestamp information. The initial UUID is the I<Nil> UUID.
=item uuid_rc_t B<uuid_destroy>(uuid_t *I<uuid>);
-FIXME
+Destroy UUID object I<uuid>.
=item uuid_rc_t B<uuid_nil>(uuid_t *I<uuid>);
-FIXME
+Sets or resets the UUID in I<uuid> to the I<Nil> UUID.
-=item uuid_rc_t B<uuid_compare>(uuid_t *I<uuid>, uuid_t *I<uuid2>, int *I<result>);
+=item uuid_rc_t B<uuid_isnil>(uuid_t *I<uuid>, int *I<result>);
-FIXME
+Checks whether the UUID in I<uuid> is the I<Nil> UUID.
+If this is the case, it returns I<true> in C<*>I<result>.
+Else it returns I<false> in C<*>I<result>.
-=item uuid_rc_t B<uuid_isnil>(uuid_t *I<uuid>, int *I<result>);
+=item uuid_rc_t B<uuid_compare>(uuid_t *I<uuid>, uuid_t *I<uuid2>, int *I<result>);
-FIXME
+Compares the order of the two UUIDs in I<uuid1> and I<uuid2>
+and returns the result in C<*>I<result>: C<-1> if I<uuid1> is
+smaller than I<uuid2>, C<0> if I<uuid1> is equal to I<uuid2>
+and C<+1> if I<uuid1> is greater than I<uuid2>.
=item uuid_rc_t B<uuid_unpack>(uuid_t *I<uuid>, const void *I<buf>);
-FIXME
+Imports the value of the UUID in I<uuid> by unpacking the binary
+representation of length C<UUID_LEN_BIN> starting at I<buf>.
=item uuid_rc_t B<uuid_pack>(uuid_t *I<uuid>, void **I<buf>);
-FIXME
+Exports the value of the UUID in I<uuid> by packing it into the
+binary representation and storing it (with length C<UUID_LEN_BIN>)
+at I<buf>. If I<buf> points to a C<NULL> pointer, a buffer of length
+C<UUID_LEN_BIN> is allocated and stored into C<*>I<buf> first.
=item uuid_rc_t B<uuid_parse>(uuid_t *I<uuid>, const char *I<str>);
-FIXME
+Imports the value of the UUID in I<uuid> by parsing the string
+representation of length C<UUID_LEN_STR> starting at I<str>.
=item uuid_rc_t B<uuid_format>(uuid_t *I<uuid>, char **I<str>);
-FIXME
+Exports the value of the UUID in I<uuid> by formatting it into the
+C<NUL>-terminated string representation and storing it (with length
+C<UUID_LEN_STR>+1) at I<str>. If I<str> points to a C<NULL> pointer,
+a buffer of length C<UUID_LEN_STR>+1 is allocated and stored into
+C<*>I<str> first.
=item uuid_rc_t B<uuid_generate>(uuid_t *I<uuid>, unsigned int I<mode>, ...);
|
