Provided by: libossp-uuid-dev_1.6.2-1.5build2_amd64 bug

NAME

       uuid - Universally Unique Identifier

VERSION

       OSSP uuid 1.6.2 (04-Jul-2008)

DESCRIPTION

       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 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 OSSP uuid.

   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 0xF8 0x1D 0x4F 0xAE 0x7D
       0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B 0xF6. The binary representation format
       is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with
       under UUID_FMT_BIN.

   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
       "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". The string representation format is exactly what
       the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_STR.

       Notice: a corresponding URL can be generated out of a ASCII string representation of an
       UUID by prefixing with "urn:uuid:" as in "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6".

   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
       "329800735698586629295641978511506172918". The string representation format is exactly
       what the OSSP uuid API functions uuid_import() and uuid_export() deal with under
       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 "2.25.". An
       example OID is "2.25.329800735698586629295641978511506172918". Additionally, an URL can be
       generated by further prefixing with "urn:oid:" as in
       "urn:oid:2.25.329800735698586629295641978511506172918".

   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 OSSP uuid is the DCE 1.1
       variant only. The DCE 1.1 UUID variant versions supported in OSSP uuid are:

       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.

       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.

       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.

       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.

   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.

   Nil UUID
       There is a special 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.

APPLICATION PROGRAMMING INTERFACE

       The ISO-C Application Programming Interface (API) of OSSP uuid consists of the following
       components.

   CONSTANTS
       The following constants are provided:

       UUID_VERSION
           The hexadecimal encoded OSSP uuid version. This allows compile-time checking of the
           OSSP uuid version. For run-time checking use uuid_version() instead.

           The hexadecimal encoding for a version "$v.$r$t$l" is calculated with the GNU shtool
           version command and is (in Perl-style for concise description)
           "sprintf('0x%x%02x%d%02x', $v, $r, {qw(s 9 . 2 b 1 a 0)}->{$t}, ($t eq 's' ? 99 :
           $l))", i.e., the version 0.9.6 is encoded as "0x009206".

       UUID_LEN_BIN, UUID_LEN_STR, UUID_LEN_SIV
           The number of octets of the UUID binary and string representations.  Notice that the
           lengths of the string representation (UUID_LEN_STR) and the lengths of the single
           integer value representation (UUID_LEN_SIV) does not include the necessary NUL
           termination character.

       UUID_MAKE_V1, UUID_MAKE_V3, UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_MC
           The mode bits for use with uuid_make(). The UUID_MAKE_VN specify which UUID version to
           generate. The UUID_MAKE_MC forces the use of a random multi-cast MAC address instead
           of the real physical MAC address in version 1 UUIDs.

       UUID_RC_OK, UUID_RC_ARG, UUID_RC_MEM, UUID_RC_SYS, UUID_RC_INT, UUID_RC_IMP
           The possible numerical return-codes of API functions.  The UUID_RC_OK indicates
           success, the others indicate errors.  Use uuid_error() to translate them into string
           versions.

       UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV, UUID_FMT_TXT
           The fmt formats for use with uuid_import() and uuid_export().  The UUID_FMT_BIN
           indicates the UUID binary representation (of length UUID_LEN_BIN), the UUID_FMT_STR
           indicates the UUID string representation (of length UUID_LEN_STR), the UUID_FMT_SIV
           indicates the UUID single integer value representation (of maximum length
           UUID_LEN_SIV) and the UUID_FMT_TXT indicates the textual description (of arbitrary
           length) of a UUID.

   FUNCTIONS
       The following functions are provided:

       uuid_rc_t uuid_create(uuid_t **uuid);
           Create a new UUID object and store a pointer to it in *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 Nil UUID.

       uuid_rc_t uuid_destroy(uuid_t *uuid);
           Destroy UUID object uuid.

       uuid_rc_t uuid_clone(const uuid_t *uuid, uuid_t **uuid_clone);
           Clone UUID object uuid and store new UUID object in uuid_clone.

       uuid_rc_t uuid_isnil(const uuid_t *uuid, int *result);
           Checks whether the UUID in uuid is the Nil UUID.  If this is the case, it returns true
           in *result.  Else it returns false in *result.

       uuid_rc_t uuid_compare(const uuid_t *uuid, const uuid_t *uuid2, int *result);
           Compares the order of the two UUIDs in uuid1 and uuid2 and returns the result in
           *result: -1 if uuid1 is smaller than uuid2, 0 if uuid1 is equal to uuid2 and +1 if
           uuid1 is greater than uuid2.

       uuid_rc_t uuid_import(uuid_t *uuid, uuid_fmt_t fmt, const void *data_ptr, size_t
       data_len);
           Imports a UUID uuid from an external representation of format fmt.  The data is read
           from the buffer at data_ptr which contains at least data_len bytes.

           The format of the external representation is specified by fmt and the minimum expected
           length in data_len depends on it. Valid values for fmt are UUID_FMT_BIN, UUID_FMT_STR
           and UUID_FMT_SIV.

       uuid_rc_t uuid_export(const uuid_t *uuid, uuid_fmt_t fmt, void *data_ptr, size_t
       *data_len);
           Exports a UUID uuid into an external representation of format fmt. Valid values for
           fmt are UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV and UUID_FMT_TXT.

           The data is written to the buffer whose location is obtained by dereferencing data_ptr
           after a "cast" to the appropriate pointer-to-pointer type. Hence the generic pointer
           argument data_ptr is expected to be a pointer to a "pointer of a particular type",
           i.e., it has to be of type "unsigned char **" for UUID_FMT_BIN and "char **" for
           UUID_FMT_STR, UUID_FMT_SIV and UUID_FMT_TXT.

           The buffer has to be room for at least *data_len bytes. If the value of the pointer
           after "casting" and dereferencing data_ptr is NULL, data_len is ignored as input and a
           new buffer is allocated and returned in the pointer after "casting" and dereferencing
           data_ptr (the caller has to free(3) it later on).

           If data_len is not NULL, the number of available bytes in the buffer has to be
           provided in *data_len and the number of actually written bytes are returned in
           *data_len again. The minimum required buffer length depends on the external
           representation as specified by fmt and is at least UUID_LEN_BIN for UUID_FMT_BIN,
           UUID_LEN_STR for UUID_FMT_STR and UUID_LEN_SIV for UUID_FMT_SIV. For UUID_FMT_TXT a
           buffer of unspecified length is required and hence it is recommended to allow OSSP
           uuid to allocate the buffer as necessary.

       uuid_rc_t uuid_load(uuid_t *uuid, const char *name);
           Loads a pre-defined UUID value into the UUID object uuid. The following name arguments
           are currently known:

           name      UUID
           nil       00000000-0000-0000-0000-000000000000
           ns:DNS    6ba7b810-9dad-11d1-80b4-00c04fd430c8
           ns:URL    6ba7b811-9dad-11d1-80b4-00c04fd430c8
           ns:OID    6ba7b812-9dad-11d1-80b4-00c04fd430c8
           ns:X500   6ba7b814-9dad-11d1-80b4-00c04fd430c8

           The "ns:XXX" are names of pre-defined name-space UUIDs for use in the generation of
           DCE 1.1 version 3 and version 5 UUIDs.

       uuid_rc_t uuid_make(uuid_t *uuid, unsigned int mode, ...);
           Generates a new UUID in uuid according to mode and optional arguments (dependent on
           mode).

           If mode contains the UUID_MAKE_V1 bit, a DCE 1.1 variant UUID of version 1 is
           generated. Then optionally the bit 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 mode contains the UUID_MAKE_V3 or 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 (uuid_t *).  Second, a name string of arbitrary length (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 mode contains the 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.

       char *uuid_error(uuid_rc_t rc);
           Returns a constant string representation corresponding to the return-code rc for use
           in displaying OSSP uuid errors.

       unsigned long uuid_version(void);
           Returns the hexadecimal encoded OSSP uuid version as compiled into the library object
           files. This allows run-time checking of the OSSP uuid version. For compile-time
           checking use UUID_VERSION instead.

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;
        }

SEE ALSO

       The following are references to UUID documentation and specifications:

       ·   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

       ·   Information Technology -- Open Systems Interconnection (OSI), 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

       ·   DCE 1.1: Remote Procedure Call, appendix 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

       ·   Information technology -- Open Systems Interconnection (OSI), Remote Procedure Call
           (RPC), ISO/IEC 11578:1996, August 2001, 570 pages, (CHF 340,00),
           http://www.iso.ch/cate/d2229.html

       ·   HTTP Extensions for Distributed Authoring (WebDAV), section 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

       ·   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

HISTORY

       OSSP uuid was implemented in January 2004 by Ralf S. Engelschall <rse@engelschall.com>. It
       was prompted by the use of UUIDs in the OSSP as and OpenPKG projects. It is a clean room
       implementation intended to be strictly standards compliant and maximum portable.

SEE ALSO

       uuid(1), uuid-config(1), OSSP::uuid(3).