From 4226e548662339ea1ca37b45385a7cf9b237ff1e Mon Sep 17 00:00:00 2001 From: Daniel Wilhelm Date: Fri, 18 Apr 2014 17:07:43 +0200 Subject: 3.8 --- shared/ossp_uuid/uuid.pod | 529 ---------------------------------------------- 1 file changed, 529 deletions(-) delete mode 100644 shared/ossp_uuid/uuid.pod (limited to 'shared/ossp_uuid/uuid.pod') diff --git a/shared/ossp_uuid/uuid.pod b/shared/ossp_uuid/uuid.pod deleted file mode 100644 index 4ad3742b..00000000 --- a/shared/ossp_uuid/uuid.pod +++ /dev/null @@ -1,529 +0,0 @@ -## -## OSSP uuid - Universally Unique Identifier -## Copyright (c) 2004-2008 Ralf S. Engelschall -## Copyright (c) 2004-2008 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 IETF 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 IETF 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: - - [4] - version - -->| |<-- - | | - | | [16] - [32] [16] | |time_hi - time_low time_mid | _and_version - |<---------------------------->||<------------>||<------------>| - | MSB || || | | - | / || || | | - |/ || || | | - - +------++------++------++------++------++------++------++------+~~ - | 15 || 14 || 13 || 12 || 11 || 10 |####9 || 8 | - | MSO || || || || || |#### || | - +------++------++------++------++------++------++------++------+~~ - 7654321076543210765432107654321076543210765432107654321076543210 - - ~~+------++------++------++------++------++------++------++------+ - ##* 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0 | - ##* || || || || || || || LSO | - ~~+------++------++------++------++------++------++------++------+ - 7654321076543210765432107654321076543210765432107654321076543210 - - | | || || /| - | | || || / | - | | || || LSB | - |<---->||<---->||<-------------------------------------------->| - |clk_seq clk_seq node - |_hi_res _low [48] - |[5-6] [8] - | | - -->| |<-- - variant - [2-3] - -An example of a UUID binary representation is the octet stream C<0xF8 -0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B -0xF6>. 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 IETF 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_high_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". The string representation -format is exactly what the B API functions B() -and B() deal with under C. - -Notice: a corresponding URL can be generated out of a ASCII string -representation of an UUID by prefixing with "C" as in -"C". - -=head2 UUID Single Integer Value Representation - -According to the ISO/IEC 11578:1996 and ITU-T Rec. X.667 standards, a -DCE 1.1 variant UUID can be also represented as a single integer value -consisting of a decimal number with up to 39 digits. - -An example of a UUID single integer value representation is the decimal -number "C<329800735698586629295641978511506172918>". The string -representation format is exactly what the B API functions -B() and B() deal with under C. - -Notice: a corresponding ISO OID can be generated under the -"{joint-iso-itu-t(2) uuid(25)}" arc out of a single integer value -representation of a UUID by prefixing with "C<2.25.>". An example OID -is "C<2.25.329800735698586629295641978511506172918>". Additionally, -an URL can be generated by further prefixing with "C" as in -"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, B - -The number of octets of the UUID binary and string representations. -Notice that the lengths of the string representation (B) -and the lengths of the single integer value representation -(B) 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, 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), the B -indicates the UUID single integer value representation (of maximum -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, 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. Valid values for I are B, B, -B and B. - -The data is written to the buffer whose location is obtained -by dereferencing I after a "cast" to the appropriate -pointer-to-pointer type. Hence the generic pointer argument I -is expected to be a pointer to a "pointer of a particular type", i.e., -it has to be of type "C" for B and -"C" for B, B and B. - -The buffer has to be room for at least C<*>I bytes. If the -value of the pointer after "casting" and dereferencing I -is C, I is ignored as input and a new buffer is -allocated and returned in the pointer after "casting" and dereferencing -I (the caller has to free(3) it later on). - -If I is not C, the number of available bytes in the -buffer has to be provided in C<*>I and the number of actually -written bytes are returned in C<*>I again. The minimum -required buffer length depends on the external representation as -specified by I and is at least B for B, -B for B and B for -B. For B a buffer of unspecified length is -required and hence it is recommended to allow B to allocate -the buffer as necessary. - -=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 -arguments are expected: first, a namespace UUID object (C). -Second, a name string of arbitrary length (C). 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, &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, &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 RFC-4122, -July 2005, 32 pages, -http://www.ietf.org/rfc/rfc4122.txt - -=item - -Information Technology -- Open Systems Interconnection (OSI), -B, -ISO/IEC 9834-8:2004 / ITU-T Rec. X.667, 2004, -December 2004, 25 pages, -http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf - -=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 - -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-RELEASE - -=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 - -- cgit