3.1

1 files changed, 529 insertions, 0 deletions

diff --git a/shared/ossp_uuid/uuid.pod b/shared/ossp_uuid/uuid.pod
new file mode 100644
index 00000000..4ad3742b
--- /dev/null
+++ b/shared/ossp_uuid/uuid.pod
@@ -0,0 +1,529 @@
+##
+##  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
+