Index: ossp-pkg/uuid/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/ChangeLog,v rcsdiff -q -kk '-r1.2' '-r1.3' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/ChangeLog,v' 2>/dev/null --- ChangeLog 2004/01/11 08:54:17 1.2 +++ ChangeLog 2004/01/11 12:14:19 1.3 @@ -13,6 +13,9 @@ Changes between 0.9.0 and 0.9.1 (11-Jan-2004 to xx-Jan-2004) - o ... + o + [Ralf S. Engelschall] + + o cleaned up source tree documentation files. [Ralf S. Engelschall] Index: ossp-pkg/uuid/uuid.c RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.c,v rcsdiff -q -kk '-r1.21' '-r1.22' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.c,v' 2>/dev/null --- uuid.c 2004/01/10 22:43:40 1.21 +++ uuid.c 2004/01/11 12:14:19 1.22 @@ -193,6 +193,28 @@ return UUID_RC_OK; } +/* check whether UUID object represents 'nil UUID' */ +uuid_rc_t uuid_isnil(uuid_t *uuid, int *result) +{ + const unsigned char *ucp; + int i; + + /* sanity check argument(s) */ + if (uuid == NULL || result == NULL) + return UUID_RC_ARG; + + /* a "nil UUID" is defined as all octets zero, so check for this case */ + *result = TRUE; + for (i = 0, ucp = (unsigned char *)&(uuid->obj); i < UUID_LEN_BIN; i++) { + if (*ucp++ != '\0') { + *result = FALSE; + break; + } + } + + return UUID_RC_OK; +} + /* compare UUID objects */ uuid_rc_t uuid_compare(uuid_t *uuid1, uuid_t *uuid2, int *result) { @@ -244,28 +266,6 @@ return UUID_RC_OK; } -/* check whether UUID object represents 'nil UUID' */ -uuid_rc_t uuid_isnil(uuid_t *uuid, int *result) -{ - const unsigned char *ucp; - int i; - - /* sanity check argument(s) */ - if (uuid == NULL || result == NULL) - return UUID_RC_ARG; - - /* a "nil UUID" is defined as all octets zero, so check for this case */ - *result = TRUE; - for (i = 0, ucp = (unsigned char *)&(uuid->obj); i < UUID_LEN_BIN; i++) { - if (*ucp++ != '\0') { - *result = FALSE; - break; - } - } - - return UUID_RC_OK; -} - /* unpack UUID binary presentation into UUID object (allows in-place operation for internal efficiency!) */ uuid_rc_t uuid_unpack(uuid_t *uuid, const void *buf) Index: ossp-pkg/uuid/uuid.h RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.h,v rcsdiff -q -kk '-r1.7' '-r1.8' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.h,v' 2>/dev/null --- uuid.h 2004/01/10 12:16:03 1.7 +++ uuid.h 2004/01/11 12:14:19 1.8 @@ -98,8 +98,8 @@ extern uuid_rc_t uuid_nil (uuid_t *uuid); /* UUID comparison */ -extern uuid_rc_t uuid_compare (uuid_t *uuid, uuid_t *uuid2, int *result); extern uuid_rc_t uuid_isnil (uuid_t *uuid, int *result); +extern uuid_rc_t uuid_compare (uuid_t *uuid, uuid_t *uuid2, int *result); /* binary representation handling */ extern uuid_rc_t uuid_unpack (uuid_t *uuid, const void *buf); Index: ossp-pkg/uuid/uuid.pod RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.pod,v rcsdiff -q -kk '-r1.4' '-r1.5' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.pod,v' 2>/dev/null --- 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 stands for Bniversal Bnique Bentifier (aka B -which stands for Blobally Bnique Bentifier). Bs 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 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 is -"C<54531d28-402b-11d8-af12-0002a5094c23>". - -=head2 Uniqueness - -The mechanism used to guarantee that Bs are unique is -through combinations of hardware addresses, time stamps and random -seeds. - -There is a reference in the B to the hardware (MAC) address of -the first network interface card (NIC) on the host which generated the -B -- this reference is intended to ensure the B 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 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 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. + +=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 +API functions B() and B() 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 = 4* + time_mid = 2* + time_high_and_version = 2* + clock_seq_and_reserved = + clock_seq_low = + node = 6* + hexOctet = + 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 API functions B() and +B() 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 is the DCE 1.1 variant only. The DCE 1.1 UUID +variant versions supported in B 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 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 +consists of the following components. + +=head2 CONSTANTS + +The following constants are provided: + +=over 4 + +=item B, B + +The number of octets of the UUID binary and string representations. +Notice that the lengths of the string representation does I include +the necessary C termination character. + +=item B, B, B, B + +The I bits for use with B(). The +BI specify which UUID version to generate. The +B forces the use of a random multi-cast MAC address +instead of the real physical MAC address in version 1 UUIDs. + +=item B, B, B, B, B + +The possible numerical return-codes of API functions. +Use B() to translate them into string versions. + +=back + +=head2 FUNCTIONS + +The following functions are provided: + =over 4 =item uuid_rc_t B(uuid_t **I); -FIXME +Create a new UUID object and store a pointer to it in C<*>I. +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 UUID. =item uuid_rc_t B(uuid_t *I); -FIXME +Destroy UUID object I. =item uuid_rc_t B(uuid_t *I); -FIXME +Sets or resets the UUID in I to the I UUID. -=item uuid_rc_t B(uuid_t *I, uuid_t *I, int *I); +=item uuid_rc_t B(uuid_t *I, int *I); -FIXME +Checks whether the UUID in I is the I UUID. +If this is the case, it returns I in C<*>I. +Else it returns I in C<*>I. -=item uuid_rc_t B(uuid_t *I, int *I); +=item uuid_rc_t B(uuid_t *I, uuid_t *I, int *I); -FIXME +Compares the order of the two UUIDs in I and I +and returns the result in C<*>I: C<-1> if I is +smaller than I, C<0> if I is equal to I +and C<+1> if I is greater than I. =item uuid_rc_t B(uuid_t *I, const void *I); -FIXME +Imports the value of the UUID in I by unpacking the binary +representation of length C starting at I. =item uuid_rc_t B(uuid_t *I, void **I); -FIXME +Exports the value of the UUID in I by packing it into the +binary representation and storing it (with length C) +at I. If I points to a C pointer, a buffer of length +C is allocated and stored into C<*>I first. =item uuid_rc_t B(uuid_t *I, const char *I); -FIXME +Imports the value of the UUID in I by parsing the string +representation of length C starting at I. =item uuid_rc_t B(uuid_t *I, char **I); -FIXME +Exports the value of the UUID in I by formatting it into the +C-terminated string representation and storing it (with length +C+1) at I. If I points to a C pointer, +a buffer of length C+1 is allocated and stored into +C<*>I first. =item uuid_rc_t B(uuid_t *I, unsigned int I, ...); Index: ossp-pkg/uuid/uuid_cli.pod RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/uuid_cli.pod,v rcsdiff -q -kk '-r1.3' '-r1.4' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/uuid_cli.pod,v' 2>/dev/null --- uuid_cli.pod 2004/01/11 08:54:18 1.3 +++ uuid_cli.pod 2004/01/11 12:14:20 1.4 @@ -57,9 +57,17 @@ (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 command line interface (CLI). For a brief overview of UUIDs -see the documentation of the application programming interface (API) in -uuid(3). +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. + +This is the command line interface (CLI) of B. For a +detailed description of UUIDs see the documentation of the application +programming interface (API) in uuid(3). =head1 OPTIONS