diff options
Diffstat (limited to 'shared/ossp_uuid/uuid.pod')
| -rw-r--r-- | shared/ossp_uuid/uuid.pod | 529 |
1 files changed, 0 insertions, 529 deletions
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 <rse@engelschall.com> -## Copyright (c) 2004-2008 The OSSP Project <http://www.ossp.org/> -## -## 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<OSSP uuid> - B<Universally Unique Identifier> - -=head1 VERSION - -OSSP uuid UUID_VERSION_STR - -=head1 DESCRIPTION - -B<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 IETF RFC-4122 compliant I<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. - -This is the ISO-C application programming interface (API) of B<OSSP uuid>. - -=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<OSSP uuid> -API functions B<uuid_import>() and B<uuid_export>() deal with under -C<UUID_FMT_BIN>. - -=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> "-" - <time_mid> "-" - <time_high_and_version> "-" - <clock_seq_high_and_reserved> - <clock_seq_low> "-" - <node> - time_low = 4*<hex_octet> - time_mid = 2*<hex_octet> - time_high_and_version = 2*<hex_octet> - clock_seq_high_and_reserved = <hex_octet> - clock_seq_low = <hex_octet> - node = 6*<hex_octet> - hex_octet = <hex_digit> <hex_digit> - 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<f81d4fae-7dec-11d0-a765-00a0c91e6bf6>". The string representation -format is exactly what the B<OSSP uuid> API functions B<uuid_import>() -and B<uuid_export>() deal with under C<UUID_FMT_STR>. - -Notice: a corresponding URL can be generated out of a ASCII string -representation of an UUID by prefixing with "C<urn:uuid:>" as in -"C<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>". - -=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<OSSP uuid> API functions -B<uuid_import>() and B<uuid_export>() deal with under C<UUID_FMT_SIV>. - -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<urn:oid:>" as in -"C<urn:oid:2.25.329800735698586629295641978511506172918>". - -=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: - -=over 4 - -=item B<Version 1> (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<Version 3> (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<Version 4> (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<Version 5> (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<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_VERSION> - -The hexadecimal encoded B<OSSP uuid> version. This allows compile-time -checking of the B<OSSP uuid> version. For run-time checking use -B<uuid_version>() instead. - -The hexadecimal encoding for a version "$I<v>.$I<r>$I<t>$I<l>" is -calculated with the B<GNU shtool> B<version> command and is (in -Perl-style for concise description) "sprintf('0x%x%02x%d%02x', $I<v>, -$I<r>, {qw(s 9 . 2 b 1 a 0)}->{$I<t>}, ($I<t> eq 's' ? 99 : $I<l>))", -i.e., the version 0.9.6 is encoded as "0x009206". - -=item B<UUID_LEN_BIN>, B<UUID_LEN_STR>, B<UUID_LEN_SIV> - -The number of octets of the UUID binary and string representations. -Notice that the lengths of the string representation (B<UUID_LEN_STR>) -and the lengths of the single integer value representation -(B<UUID_LEN_SIV>) does I<not> include the necessary C<NUL> termination -character. - -=item B<UUID_MAKE_V1>, B<UUID_MAKE_V3>, B<UUID_MAKE_V4>, B<UUID_MAKE_V5>, B<UUID_MAKE_MC> - -The I<mode> bits for use with B<uuid_make>(). The B<UUID_MAKE_V>I<N> -specify which UUID version to generate. The B<UUID_MAKE_MC> 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>, B<UUID_RC_IMP> - -The possible numerical return-codes of API functions. -The C<UUID_RC_OK> indicates success, the others indicate errors. -Use B<uuid_error>() to translate them into string versions. - -=item B<UUID_FMT_BIN>, B<UUID_FMT_STR>, B<UUID_FMT_SIV>, B<UUID_FMT_TXT> - -The I<fmt> formats for use with B<uuid_import>() and B<uuid_export>(). -The B<UUID_FMT_BIN> indicates the UUID binary representation (of -length B<UUID_LEN_BIN>), the B<UUID_FMT_STR> indicates the UUID string -representation (of length B<UUID_LEN_STR>), the B<UUID_FMT_SIV> -indicates the UUID single integer value representation (of maximum -length B<UUID_LEN_SIV>) and the B<UUID_FMT_TXT> 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_create>(uuid_t **I<uuid>); - -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>); - -Destroy UUID object I<uuid>. - -=item uuid_rc_t B<uuid_clone>(const uuid_t *I<uuid>, uuid_t **I<uuid_clone>); - -Clone UUID object I<uuid> and store new UUID object in I<uuid_clone>. - -=item uuid_rc_t B<uuid_isnil>(const uuid_t *I<uuid>, int *I<result>); - -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_compare>(const uuid_t *I<uuid>, const uuid_t *I<uuid2>, int *I<result>); - -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_import>(uuid_t *I<uuid>, uuid_fmt_t I<fmt>, const void *I<data_ptr>, size_t I<data_len>); - -Imports a UUID I<uuid> from an external representation of format I<fmt>. -The data is read from the buffer at I<data_ptr> which contains at least -I<data_len> bytes. - -The format of the external representation is specified by I<fmt> and the -minimum expected length in I<data_len> depends on it. Valid values for -I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR> and B<UUID_FMT_SIV>. - -=item uuid_rc_t B<uuid_export>(const uuid_t *I<uuid>, uuid_fmt_t I<fmt>, void *I<data_ptr>, size_t *I<data_len>); - -Exports a UUID I<uuid> into an external representation of format -I<fmt>. Valid values for I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR>, -B<UUID_FMT_SIV> and B<UUID_FMT_TXT>. - -The data is written to the buffer whose location is obtained -by dereferencing I<data_ptr> after a "cast" to the appropriate -pointer-to-pointer type. Hence the generic pointer argument I<data_ptr> -is expected to be a pointer to a "pointer of a particular type", i.e., -it has to be of type "C<unsigned char **>" for B<UUID_FMT_BIN> and -"C<char **>" for B<UUID_FMT_STR>, B<UUID_FMT_SIV> and B<UUID_FMT_TXT>. - -The buffer has to be room for at least C<*>I<data_len> bytes. If the -value of the pointer after "casting" and dereferencing I<data_ptr> -is C<NULL>, I<data_len> is ignored as input and a new buffer is -allocated and returned in the pointer after "casting" and dereferencing -I<data_ptr> (the caller has to free(3) it later on). - -If I<data_len> is not C<NULL>, the number of available bytes in the -buffer has to be provided in C<*>I<data_len> and the number of actually -written bytes are returned in C<*>I<data_len> again. The minimum -required buffer length depends on the external representation as -specified by I<fmt> and is at least B<UUID_LEN_BIN> for B<UUID_FMT_BIN>, -B<UUID_LEN_STR> for B<UUID_FMT_STR> and B<UUID_LEN_SIV> for -B<UUID_FMT_SIV>. For B<UUID_FMT_TXT> a buffer of unspecified length is -required and hence it is recommended to allow B<OSSP uuid> to allocate -the buffer as necessary. - -=item uuid_rc_t B<uuid_load>(uuid_t *I<uuid>, const char *I<name>); - -Loads a pre-defined UUID value into the UUID object I<uuid>. The -following I<name> arguments are currently known: - -=over 4 - -=item I<name> I<UUID> - -=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 "C<ns:>I<XXX>" 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_make>(uuid_t *I<uuid>, unsigned int I<mode>, ...); - -Generates a new UUID in I<uuid> according to I<mode> and optional -arguments (dependent on I<mode>). - -If I<mode> contains the C<UUID_MAKE_V1> bit, a DCE 1.1 variant UUID of -version 1 is generated. Then optionally the bit C<UUID_MAKE_MC> 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<mode> contains the C<UUID_MAKE_V3> or C<UUID_MAKE_V5> 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<uuid_t *>). -Second, a name string of arbitrary length (C<const char *>). 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<mode> contains the C<UUID_MAKE_V4> 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_error>(uuid_rc_t I<rc>); - -Returns a constant string representation corresponding to the -return-code I<rc> for use in displaying B<OSSP uuid> errors. - -=item unsigned long B<uuid_version>(void); - -Returns the hexadecimal encoded B<OSSP uuid> version as compiled into -the library object files. This allows run-time checking of the B<OSSP -uuid> version. For compile-time checking use C<UUID_VERSION> 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<UUID> documentation and specifications: - -=over 4 - -=item - -B<A Universally Unique IDentifier (UUID) URN Namespace>, -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<Procedures for the operation of OSI Registration Authorities: -Generation and Registration of Universally Unique Identifiers (UUIDs) -and their Use as ASN.1 Object Identifier Components>, -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<DCE 1.1: Remote Procedure Call>, -appendix B<Universally Unique Identifier>, -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<Remote Procedure Call (RPC)>, -ISO/IEC 11578:1996, -August 2001, 570 pages, (CHF 340,00), -http://www.iso.ch/cate/d2229.html - -=item - -B<HTTP Extensions for Distributed Authoring (WebDAV)>, -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<DCE 1.1 compliant UUID functions>, -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<OSSP uuid> was implemented in January 2004 by Ralf S. Engelschall -E<lt>rse@engelschall.comE<gt>. It was prompted by the use of UUIDs -in the B<OSSP as> and B<OpenPKG> 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 - |