Index: ossp-pkg/uuid/README RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/README,v co -q -kk -p'1.31' '/v/ossp/cvs/ossp-pkg/uuid/Attic/README,v' | diff -u /dev/null - -L'ossp-pkg/uuid/README' 2>/dev/null --- ossp-pkg/uuid/README +++ - 2025-04-04 00:40:54.508172560 +0200 @@ -0,0 +1,62 @@ + _ ___ ____ ____ ____ _ _ + |_|_ _ / _ \/ ___/ ___|| _ \ _ _ _ _(_) __| | + _|_||_| | | | \___ \___ \| |_) | | | | | | | | |/ _` | + |_||_|_| | |_| |___) |__) | __/ | |_| | |_| | | (_| | + |_|_|_| \___/|____/____/|_| \__,_|\__,_|_|\__,_| + + OSSP uuid - Universally Unique Identifier + Version 1.3.0 (31-Aug-2005) + + ABSTRACT + + OSSP uuid is a ISO-C:1999 application programming interface (API) + and corresponding command line interface (CLI) for the generation + of DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant Universally + Unique Identifier (UUID). It supports DCE 1.1 variant UUIDs of version + 1 (time and node based), version 3 (name based, MD5), version 4 + (random number based) and version 5 (name based, SHA-1). Additional + API bindings are provided for the languages ISO-C++:1998, Perl:5 and + PHP:4/5. Optional backward compatibility exists for the ISO-C DCE-1.1 + and Perl Data::UUID APIs. + + 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. + + COPYRIGHT AND LICENSE + + Copyright (c) 2004-2005 Ralf S. Engelschall + Copyright (c) 2004-2005 The OSSP Project + + This file is part of OSSP uuid, a library for the generation + of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/ + + Permission to use, copy, modify, and distribute this software for + any purpose with or without fee is hereby granted, provided that + the above copyright notice and this permission notice appear in all + copies. + + THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + + HOME AND DOCUMENTATION + + The documentation and latest release can be found on + + o http://www.ossp.org/pkg/lib/uuid/ + o ftp://ftp.ossp.org/pkg/lib/uuid/ + Index: ossp-pkg/uuid/perl/uuid.pod RCS File: /v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.pod,v rcsdiff -q -kk '-r1.8' '-r1.9' -u '/v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.pod,v' 2>/dev/null --- uuid.pod 2005/08/31 08:55:18 1.8 +++ uuid.pod 2005/09/02 14:00:05 1.9 @@ -35,16 +35,18 @@ =head1 DESCRIPTION -B is the Perl binding to the B API. - -B is an ISO-C and Perl application programming interface -(API) and corresponding command line interface (CLI) for the generation -of DCE 1.1 and ISO/IEC 11578:1996 compliant I is a ISO-C:1999 application programming interface (API) +and corresponding command line interface (CLI) for the generation of +DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant I (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and node based), version 3 (name based, MD5), version 4 (random number -based) and version 5 (name based, SHA-1). +based) and version 5 (name based, SHA-1). Additional API bindings are +provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional +backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID +APIs. -B provides three Perl APIs: +B is the Perl binding to the B API. +Three variants are provided: =head2 TIE-STYLE API Index: ossp-pkg/uuid/uuid.pod RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.pod,v co -q -kk -p'1.31' '/v/ossp/cvs/ossp-pkg/uuid/Attic/uuid.pod,v' | diff -u /dev/null - -L'ossp-pkg/uuid/uuid.pod' 2>/dev/null --- ossp-pkg/uuid/uuid.pod +++ - 2025-04-04 00:40:54.515217220 +0200 @@ -0,0 +1,462 @@ +## +## OSSP uuid - Universally Unique Identifier +## Copyright (c) 2004-2005 Ralf S. Engelschall +## Copyright (c) 2004-2005 The OSSP Project +## +## This file is part of OSSP uuid, a library for the generation +## of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/ +## +## Permission to use, copy, modify, and distribute this software for +## any purpose with or without fee is hereby granted, provided that +## the above copyright notice and this permission notice appear in all +## copies. +## +## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +## SUCH DAMAGE. +## +## uuid.pod: manual page +## + +=pod + +=head1 NAME + +B - B + +=head1 VERSION + +OSSP uuid UUID_VERSION_STR + +=head1 DESCRIPTION + +B is a ISO-C:1999 application programming interface (API) +and corresponding command line interface (CLI) for the generation of +DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant I (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time +and node based), version 3 (name based, MD5), version 4 (random number +based) and version 5 (name based, SHA-1). Additional API bindings are +provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional +backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID +APIs. + +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 ISO-C application programming interface (API) of B. + +=head2 UUID Binary Representation + +According to the DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 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 +under C. + +=head2 UUID ASCII String Representation + +According to the DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 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* + hex_octet = + hex_digit = "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 under C. + +=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: + +=over 4 + +=item B (time and node based) + +These are the classical UUIDs, created out of a 60-bit system time, +a 14-bit local clock sequence and 48-bit system MAC address. The MAC +address can be either the real one of a physical network interface card +(NIC) or a random multi-cast MAC address. Version 1 UUIDs are usually +used as one-time global unique identifiers. + +=item B (name based, MD5) + +These are UUIDs which are based on the 128-bit MD5 message digest of the +concatenation of a 128-bit namespace UUID and a name string of arbitrary +length. Version 3 UUIDs are usually used for non-unique but repeatable +message digest identifiers. + +=item B (random data based) + +These are UUIDs which are based on just 128-bit of random data. Version +4 UUIDs are usually used as one-time local unique identifiers. + +=item B (name based, SHA-1) + +These are UUIDs which are based on the 160-bit SHA-1 message digest of the +concatenation of a 128-bit namespace UUID and a name string of arbitrary +length. Version 5 UUIDs are usually used for non-unique but repeatable +message digest identifiers. + +=back + +=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 and version 5 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 + +The hexadecimal encoded B version. This allows compile-time +checking of the B version. For run-time checking use +B() instead. + +The hexadecimal encoding for a version "$I.$I$I$I" is +calculated with the B B command and is (in +Perl-style for concise description) "sprintf('0x%x%02x%d%02x', $I, +$I, {qw(s 9 . 2 b 1 a 0)}->{$I}, ($I eq 's' ? 99 : $I))", +i.e., the version 0.9.6 is encoded as "0x009206". + +=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, 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, B + +The possible numerical return-codes of API functions. +The C indicates success, the others indicate errors. +Use B() to translate them into string versions. + +=item B, B, B + +The I formats for use with B() and B(). +The B indicates the UUID binary representation (of +length B), the B indicates the UUID string +representation (of length B) and the B +indicates the textual description (of arbitrary length) of a UUID. + +=back + +=head2 FUNCTIONS + +The following functions are provided: + +=over 4 + +=item uuid_rc_t B(uuid_t **I); + +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); + +Destroy UUID object I. + +=item uuid_rc_t B(const uuid_t *I, uuid_t **I); + +Clone UUID object I and store new UUID object in I. + +=item uuid_rc_t B(const uuid_t *I, int *I); + +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(const uuid_t *I, const uuid_t *I, int *I); + +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, uuid_fmt_t I, const void *I, size_t I); + +Imports a UUID I from an external representation of format I. +The data is read from the buffer at I which contains at least +I bytes. + +The format of the external representation is specified by I and the +minimum expected length in I depends on it. Valid values for +I are B and B. + +=item uuid_rc_t B(const uuid_t *I, uuid_fmt_t I, void **I, size_t *I); + +Exports a UUID I into an external representation of format I. +The data is written to the buffer at C<*>I which has to +be room for at least C<*>I bytes. If C<*>I is +C, I is ignored as input and a new buffer is allocated +and returned in C<*>I (the caller has to free(3) it later +on). If I is not C, the number of available bytes at +C<*>I has to be provided in C<*>I and the number of +actually written bytes are returned in C<*>I again. + +The format of the external representation is specified by I and the +minimum required length in C<*>I depends on it. Valid values +for I are B, B and B. + +=item uuid_rc_t B(uuid_t *I, const char *I); + +Loads a pre-defined UUID value into the UUID object I. The +following I arguments are currently known: + +=over 4 + +=item I I + +=item nil 00000000-0000-0000-0000-000000000000 + +=item ns:DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8 + +=item ns:URL 6ba7b811-9dad-11d1-80b4-00c04fd430c8 + +=item ns:OID 6ba7b812-9dad-11d1-80b4-00c04fd430c8 + +=item ns:X500 6ba7b814-9dad-11d1-80b4-00c04fd430c8 + +=back + +The "CI" are names of pre-defined name-space UUIDs for use in +the generation of DCE 1.1 version 3 and version 5 UUIDs. + +=item uuid_rc_t B(uuid_t *I, unsigned int I, ...); + +Generates a new UUID in I according to I and optional +arguments (dependent on I). + +If I contains the C bit, a DCE 1.1 variant UUID of +version 1 is generated. Then optionally the bit C forces +the use of random multi-cast MAC address instead of the real physical +MAC address (the default). The UUID is generated out of the 60-bit current +system time, a 12-bit clock sequence and the 48-bit MAC address. + +If I contains the C or C bit, a DCE +1.1 variant UUID of version 3 or 5 is generated and two additional +C-terminated string arguments of type "C" are +expected: first a namespace, given as an internally pre-defined id +(currently known are ids "C", "C", "C", and "C") +or a UUID in string representation. Second, a name string of arbitrary +length. The UUID is generated out of the 128-bit MD5 or 160-bit SHA-1 +from the concatenated octet stream of namespace UUID and name string. + +If I contains the C bit, a DCE 1.1 variant UUID +of version 4 is generated. The UUID is generated out of 128-bit random +data. + +=item char *B(uuid_rc_t I); + +Returns a constant string representation corresponding to the +return-code I for use in displaying B errors. + +=item unsigned long B(void); + +Returns the hexadecimal encoded B version as compiled into +the library object files. This allows run-time checking of the B version. For compile-time checking use C instead. + +=back + +=head1 EXAMPLE + +The following shows an example usage of the API. Error handling is +omitted for code simplification and has to be re-added for production +code. + + /* generate a DCE 1.1 v1 UUID from system environment */ + char *uuid_v1(void) + { + uuid_t *uuid; + char *str; + + uuid_create(&uuid); + uuid_make(uuid, UUID_MAKE_V1); + str = NULL; + uuid_export(uuid, UUID_FMT_STR, (void **)&str, NULL); + uuid_destroy(uuid); + return str; + } + + /* generate a DCE 1.1 v3 UUID from an URL */ + char *uuid_v3(const char *url) + { + uuid_t *uuid; + uuid_t *uuid_ns; + char *str; + + uuid_create(&uuid); + uuid_create(&uuid_ns); + uuid_load(uuid_ns, "ns:URL"); + uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url); + str = NULL; + uuid_export(uuid, UUID_FMT_STR, (void **)&str, NULL); + uuid_destroy(uuid_ns); + uuid_destroy(uuid); + return str; + } + +=head1 SEE ALSO + +The following are references to B documentation and specifications: + +=over 4 + +=item + +B, +P. Leach, M. Mealling, R. Salz, +IETF Request for Comments: RFC 4122, +July 2005, 32 pages, + +=item + +B, +appendix B, +Open Group Technical Standard +Document Number C706, August 1997, 737 pages, +(supersedes C309 DCE: Remote Procedure Call 8/1994, +which was basis for ISO/IEC 11578:1996 specification), +http://www.opengroup.org/publications/catalog/c706.htm + +=item + +Information technology -- Open Systems Interconnection (OSI), +B, +ISO/IEC 11578:1996, +August 2001, 570 pages, (CHF 340,00), +http://www.iso.ch/cate/d2229.html + +=item + +Information technology -- Open Systems Interconnection (OSI), +B, +ISO/IEC 9834-8:2004 / ITU-T Rec. X.667, 2004, +December 2004, 25 pages. + +=item + +B, +section B<6.4.1 Node Field Generation Without the IEEE 802 Address>, +IETF RFC 2518, +February 1999, 94 pages, +http://www.ietf.org/rfc/rfc2518.txt + +=item + +B, +FreeBSD manual pages uuid(3) and uuidgen(2), +http://www.freebsd.org/cgi/man.cgi?query=uuid&manpath=FreeBSD+6.0-current + +=back + +=head1 HISTORY + +B was implemented in January 2004 by Ralf S. Engelschall +Erse@engelschall.comE. It was prompted by the use of UUIDs +in the B and B projects. It is a clean room +implementation intended to be strictly standards compliant and maximum +portable. + +=head1 SEE ALSO + +uuid(1), uuid-config(1), OSSP::uuid(3). + +=cut + Index: ossp-pkg/uuid/uuid_cli.pod RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/uuid_cli.pod,v rcsdiff -q -kk '-r1.22' '-r1.23' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/uuid_cli.pod,v' 2>/dev/null --- uuid_cli.pod 2005/08/31 20:10:25 1.22 +++ uuid_cli.pod 2005/09/02 14:00:00 1.23 @@ -56,12 +56,15 @@ =head1 DESCRIPTION -B is a ISO-C, ISO-C++ and Perl application programming -interface (API) and corresponding command line interface (CLI) for -the generation of DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant -I (UUID). It supports DCE 1.1 variant -UUIDs of version 1 (time and node based), version 3 (name based, MD5), -version 4 (random number based) and version 5 (name based, SHA-1). +B is a ISO-C:1999 application programming interface (API) +and corresponding command line interface (CLI) for the generation of +DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant I (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time +and node based), version 3 (name based, MD5), version 4 (random number +based) and version 5 (name based, SHA-1). Additional API bindings are +provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional +backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID +APIs. UUIDs are 128 bit numbers which are intended to have a high likelihood of uniqueness over space and time and are computationally difficult