.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` . ds C' 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title ".::uuid 3" .TH .::uuid 3 "OSSP uuid 1.6.2" 04-Jul-2008 "Universally Unique Identifier" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME uuid \- Universally Unique Identifier .SH VERSION .IX Header "VERSION" OSSP uuid 1.6.2 (04-Jul-2008) .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBOSSP uuid\fR 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 \fIUniversally Unique Identifier\fR (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. .PP 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. .PP This is the ISO-C application programming interface (API) of \fBOSSP uuid\fR. .SS "UUID Binary Representation" .IX Subsection "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: .PP .Vb 11 \& [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] .Ve .PP An example of a UUID binary representation is the octet stream \f(CW0xF8 0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B 0xF6\fR. The binary representation format is exactly what the \fBOSSP uuid\fR API functions \fBuuid_import\fR() and \fBuuid_export\fR() deal with under \&\f(CW\*(C`UUID_FMT_BIN\*(C'\fR. .SS "UUID ASCII String Representation" .IX Subsection "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: .PP .Vb 10 \& 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" .Ve .PP An example of a UUID string representation is the ASCII string "\f(CW\*(C`f81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\*(C'\fR". The string representation format is exactly what the \fBOSSP uuid\fR API functions \fBuuid_import\fR() and \fBuuid_export\fR() deal with under \f(CW\*(C`UUID_FMT_STR\*(C'\fR. .PP Notice: a corresponding URL can be generated out of a ASCII string representation of an UUID by prefixing with "\f(CW\*(C`urn:uuid:\*(C'\fR" as in "\f(CW\*(C`urn:uuid:f81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\*(C'\fR". .SS "UUID Single Integer Value Representation" .IX Subsection "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. .PP An example of a UUID single integer value representation is the decimal number "\f(CW329800735698586629295641978511506172918\fR". The string representation format is exactly what the \fBOSSP uuid\fR API functions \&\fBuuid_import\fR() and \fBuuid_export\fR() deal with under \f(CW\*(C`UUID_FMT_SIV\*(C'\fR. .PP Notice: a corresponding ISO OID can be generated under the "{\fBjoint\-iso\-itu\-t\fR\|(2) uuid(25)}" arc out of a single integer value representation of a UUID by prefixing with "\f(CW2.25.\fR". An example OID is "\f(CW2.25.329800735698586629295641978511506172918\fR". Additionally, an URL can be generated by further prefixing with "\f(CW\*(C`urn:oid:\*(C'\fR" as in "\f(CW\*(C`urn:oid:2.25.329800735698586629295641978511506172918\*(C'\fR". .SS "UUID Variants and Versions" .IX Subsection "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 \fBOSSP uuid\fR is the DCE 1.1 variant only. The DCE 1.1 UUID variant versions supported in \fBOSSP uuid\fR are: .IP "\fBVersion 1\fR (time and node based)" 4 .IX Item "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. .IP "\fBVersion 3\fR (name based, MD5)" 4 .IX Item "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. .IP "\fBVersion 4\fR (random data based)" 4 .IX Item "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. .IP "\fBVersion 5\fR (name based, SHA\-1)" 4 .IX Item "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. .SS "UUID Uniqueness" .IX Subsection "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. .PP 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. .PP 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. .SS "Nil UUID" .IX Subsection "Nil UUID" There is a special \fINil\fR 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. .SH "APPLICATION PROGRAMMING INTERFACE" .IX Header "APPLICATION PROGRAMMING INTERFACE" The ISO-C Application Programming Interface (API) of \fBOSSP uuid\fR consists of the following components. .SS CONSTANTS .IX Subsection "CONSTANTS" The following constants are provided: .IP \fBUUID_VERSION\fR 4 .IX Item "UUID_VERSION" The hexadecimal encoded \fBOSSP uuid\fR version. This allows compile-time checking of the \fBOSSP uuid\fR version. For run-time checking use \&\fBuuid_version\fR() instead. .Sp The hexadecimal encoding for a version "$\fIv\fR.$\fIr\fR$\fIt\fR$\fIl\fR" is calculated with the \fBGNU shtool\fR \fBversion\fR command and is (in Perl-style for concise description) "sprintf('0x%x%02x%d%02x', $\fIv\fR, $\fIr\fR, {qw(s 9 . 2 b 1 a 0)}\->{$\fIt\fR}, ($\fIt\fR eq 's' ? 99 : $\fIl\fR))", i.e., the version 0.9.6 is encoded as "0x009206". .IP "\fBUUID_LEN_BIN\fR, \fBUUID_LEN_STR\fR, \fBUUID_LEN_SIV\fR" 4 .IX Item "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 (\fBUUID_LEN_STR\fR) and the lengths of the single integer value representation (\fBUUID_LEN_SIV\fR) does \fInot\fR include the necessary \f(CW\*(C`NUL\*(C'\fR termination character. .IP "\fBUUID_MAKE_V1\fR, \fBUUID_MAKE_V3\fR, \fBUUID_MAKE_V4\fR, \fBUUID_MAKE_V5\fR, \fBUUID_MAKE_MC\fR" 4 .IX Item "UUID_MAKE_V1, UUID_MAKE_V3, UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_MC" The \fImode\fR bits for use with \fBuuid_make\fR(). The \fBUUID_MAKE_V\fR\fIN\fR specify which UUID version to generate. The \fBUUID_MAKE_MC\fR forces the use of a random multi-cast MAC address instead of the real physical MAC address in version 1 UUIDs. .IP "\fBUUID_RC_OK\fR, \fBUUID_RC_ARG\fR, \fBUUID_RC_MEM\fR, \fBUUID_RC_SYS\fR, \fBUUID_RC_INT\fR, \fBUUID_RC_IMP\fR" 4 .IX Item "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 \f(CW\*(C`UUID_RC_OK\*(C'\fR indicates success, the others indicate errors. Use \fBuuid_error\fR() to translate them into string versions. .IP "\fBUUID_FMT_BIN\fR, \fBUUID_FMT_STR\fR, \fBUUID_FMT_SIV\fR, \fBUUID_FMT_TXT\fR" 4 .IX Item "UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV, UUID_FMT_TXT" The \fIfmt\fR formats for use with \fBuuid_import\fR() and \fBuuid_export\fR(). The \fBUUID_FMT_BIN\fR indicates the UUID binary representation (of length \fBUUID_LEN_BIN\fR), the \fBUUID_FMT_STR\fR indicates the UUID string representation (of length \fBUUID_LEN_STR\fR), the \fBUUID_FMT_SIV\fR indicates the UUID single integer value representation (of maximum length \fBUUID_LEN_SIV\fR) and the \fBUUID_FMT_TXT\fR indicates the textual description (of arbitrary length) of a UUID. .SS FUNCTIONS .IX Subsection "FUNCTIONS" The following functions are provided: .IP "uuid_rc_t \fBuuid_create\fR(uuid_t **\fIuuid\fR);" 4 .IX Item "uuid_rc_t uuid_create(uuid_t **uuid);" Create a new UUID object and store a pointer to it in \f(CW\*(C`*\*(C'\fR\fIuuid\fR. 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 \fINil\fR UUID. .IP "uuid_rc_t \fBuuid_destroy\fR(uuid_t *\fIuuid\fR);" 4 .IX Item "uuid_rc_t uuid_destroy(uuid_t *uuid);" Destroy UUID object \fIuuid\fR. .IP "uuid_rc_t \fBuuid_clone\fR(const uuid_t *\fIuuid\fR, uuid_t **\fIuuid_clone\fR);" 4 .IX Item "uuid_rc_t uuid_clone(const uuid_t *uuid, uuid_t **uuid_clone);" Clone UUID object \fIuuid\fR and store new UUID object in \fIuuid_clone\fR. .IP "uuid_rc_t \fBuuid_isnil\fR(const uuid_t *\fIuuid\fR, int *\fIresult\fR);" 4 .IX Item "uuid_rc_t uuid_isnil(const uuid_t *uuid, int *result);" Checks whether the UUID in \fIuuid\fR is the \fINil\fR UUID. If this is the case, it returns \fItrue\fR in \f(CW\*(C`*\*(C'\fR\fIresult\fR. Else it returns \fIfalse\fR in \f(CW\*(C`*\*(C'\fR\fIresult\fR. .IP "uuid_rc_t \fBuuid_compare\fR(const uuid_t *\fIuuid\fR, const uuid_t *\fIuuid2\fR, int *\fIresult\fR);" 4 .IX Item "uuid_rc_t uuid_compare(const uuid_t *uuid, const uuid_t *uuid2, int *result);" Compares the order of the two UUIDs in \fIuuid1\fR and \fIuuid2\fR and returns the result in \f(CW\*(C`*\*(C'\fR\fIresult\fR: \f(CW\-1\fR if \fIuuid1\fR is smaller than \fIuuid2\fR, \f(CW0\fR if \fIuuid1\fR is equal to \fIuuid2\fR and \f(CW+1\fR if \fIuuid1\fR is greater than \fIuuid2\fR. .IP "uuid_rc_t \fBuuid_import\fR(uuid_t *\fIuuid\fR, uuid_fmt_t \fIfmt\fR, const void *\fIdata_ptr\fR, size_t \fIdata_len\fR);" 4 .IX Item "uuid_rc_t uuid_import(uuid_t *uuid, uuid_fmt_t fmt, const void *data_ptr, size_t data_len);" Imports a UUID \fIuuid\fR from an external representation of format \fIfmt\fR. The data is read from the buffer at \fIdata_ptr\fR which contains at least \&\fIdata_len\fR bytes. .Sp The format of the external representation is specified by \fIfmt\fR and the minimum expected length in \fIdata_len\fR depends on it. Valid values for \&\fIfmt\fR are \fBUUID_FMT_BIN\fR, \fBUUID_FMT_STR\fR and \fBUUID_FMT_SIV\fR. .IP "uuid_rc_t \fBuuid_export\fR(const uuid_t *\fIuuid\fR, uuid_fmt_t \fIfmt\fR, void *\fIdata_ptr\fR, size_t *\fIdata_len\fR);" 4 .IX Item "uuid_rc_t uuid_export(const uuid_t *uuid, uuid_fmt_t fmt, void *data_ptr, size_t *data_len);" Exports a UUID \fIuuid\fR into an external representation of format \&\fIfmt\fR. Valid values for \fIfmt\fR are \fBUUID_FMT_BIN\fR, \fBUUID_FMT_STR\fR, \&\fBUUID_FMT_SIV\fR and \fBUUID_FMT_TXT\fR. .Sp The data is written to the buffer whose location is obtained by dereferencing \fIdata_ptr\fR after a "cast" to the appropriate pointer-to-pointer type. Hence the generic pointer argument \fIdata_ptr\fR is expected to be a pointer to a "pointer of a particular type", i.e., it has to be of type "\f(CW\*(C`unsigned char **\*(C'\fR" for \fBUUID_FMT_BIN\fR and "\f(CW\*(C`char **\*(C'\fR" for \fBUUID_FMT_STR\fR, \fBUUID_FMT_SIV\fR and \fBUUID_FMT_TXT\fR. .Sp The buffer has to be room for at least \f(CW\*(C`*\*(C'\fR\fIdata_len\fR bytes. If the value of the pointer after "casting" and dereferencing \fIdata_ptr\fR is \f(CW\*(C`NULL\*(C'\fR, \fIdata_len\fR is ignored as input and a new buffer is allocated and returned in the pointer after "casting" and dereferencing \&\fIdata_ptr\fR (the caller has to \fBfree\fR\|(3) it later on). .Sp If \fIdata_len\fR is not \f(CW\*(C`NULL\*(C'\fR, the number of available bytes in the buffer has to be provided in \f(CW\*(C`*\*(C'\fR\fIdata_len\fR and the number of actually written bytes are returned in \f(CW\*(C`*\*(C'\fR\fIdata_len\fR again. The minimum required buffer length depends on the external representation as specified by \fIfmt\fR and is at least \fBUUID_LEN_BIN\fR for \fBUUID_FMT_BIN\fR, \&\fBUUID_LEN_STR\fR for \fBUUID_FMT_STR\fR and \fBUUID_LEN_SIV\fR for \&\fBUUID_FMT_SIV\fR. For \fBUUID_FMT_TXT\fR a buffer of unspecified length is required and hence it is recommended to allow \fBOSSP uuid\fR to allocate the buffer as necessary. .IP "uuid_rc_t \fBuuid_load\fR(uuid_t *\fIuuid\fR, const char *\fIname\fR);" 4 .IX Item "uuid_rc_t uuid_load(uuid_t *uuid, const char *name);" Loads a pre-defined UUID value into the UUID object \fIuuid\fR. The following \fIname\fR arguments are currently known: .RS 4 .IP "\fIname\fR \fIUUID\fR" 4 .IX Item "name UUID" .PD 0 .IP "nil 00000000\-0000\-0000\-0000\-000000000000" 4 .IX Item "nil 00000000-0000-0000-0000-000000000000" .IP "ns:DNS 6ba7b810\-9dad\-11d1\-80b4\-00c04fd430c8" 4 .IX Item "ns:DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8" .IP "ns:URL 6ba7b811\-9dad\-11d1\-80b4\-00c04fd430c8" 4 .IX Item "ns:URL 6ba7b811-9dad-11d1-80b4-00c04fd430c8" .IP "ns:OID 6ba7b812\-9dad\-11d1\-80b4\-00c04fd430c8" 4 .IX Item "ns:OID 6ba7b812-9dad-11d1-80b4-00c04fd430c8" .IP "ns:X500 6ba7b814\-9dad\-11d1\-80b4\-00c04fd430c8" 4 .IX Item "ns:X500 6ba7b814-9dad-11d1-80b4-00c04fd430c8" .RE .RS 4 .PD .Sp The "\f(CW\*(C`ns:\*(C'\fR\fIXXX\fR" are names of pre-defined name-space UUIDs for use in the generation of DCE 1.1 version 3 and version 5 UUIDs. .RE .IP "uuid_rc_t \fBuuid_make\fR(uuid_t *\fIuuid\fR, unsigned int \fImode\fR, ...);" 4 .IX Item "uuid_rc_t uuid_make(uuid_t *uuid, unsigned int mode, ...);" Generates a new UUID in \fIuuid\fR according to \fImode\fR and optional arguments (dependent on \fImode\fR). .Sp If \fImode\fR contains the \f(CW\*(C`UUID_MAKE_V1\*(C'\fR bit, a DCE 1.1 variant UUID of version 1 is generated. Then optionally the bit \f(CW\*(C`UUID_MAKE_MC\*(C'\fR 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. .Sp If \fImode\fR contains the \f(CW\*(C`UUID_MAKE_V3\*(C'\fR or \f(CW\*(C`UUID_MAKE_V5\*(C'\fR 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 (\f(CW\*(C`uuid_t *\*(C'\fR). Second, a name string of arbitrary length (\f(CW\*(C`const char *\*(C'\fR). 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. .Sp If \fImode\fR contains the \f(CW\*(C`UUID_MAKE_V4\*(C'\fR bit, a DCE 1.1 variant UUID of version 4 is generated. The UUID is generated out of 128\-bit random data. .IP "char *\fBuuid_error\fR(uuid_rc_t \fIrc\fR);" 4 .IX Item "char *uuid_error(uuid_rc_t rc);" Returns a constant string representation corresponding to the return-code \fIrc\fR for use in displaying \fBOSSP uuid\fR errors. .IP "unsigned long \fBuuid_version\fR(void);" 4 .IX Item "unsigned long uuid_version(void);" Returns the hexadecimal encoded \fBOSSP uuid\fR version as compiled into the library object files. This allows run-time checking of the \fBOSSP uuid\fR version. For compile-time checking use \f(CW\*(C`UUID_VERSION\*(C'\fR instead. .SH EXAMPLE .IX Header "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. .PP .Vb 5 \& /* 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; \& } .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" The following are references to \fBUUID\fR documentation and specifications: .IP \(bu 4 \&\fBA Universally Unique IDentifier (UUID) URN Namespace\fR, P. Leach, M. Mealling, R. Salz, IETF RFC\-4122, July 2005, 32 pages, http://www.ietf.org/rfc/rfc4122.txt .IP \(bu 4 Information Technology \-\- Open Systems Interconnection (OSI), \&\fBProcedures for the operation of OSI Registration Authorities: Generation and Registration of Universally Unique Identifiers (UUIDs) and their Use as ASN.1 Object Identifier Components\fR, 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 .IP \(bu 4 \&\fBDCE 1.1: Remote Procedure Call\fR, appendix \fBUniversally Unique Identifier\fR, 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 .IP \(bu 4 Information technology \-\- Open Systems Interconnection (OSI), \&\fBRemote Procedure Call (RPC)\fR, ISO/IEC 11578:1996, August 2001, 570 pages, (CHF 340,00), http://www.iso.ch/cate/d2229.html .IP \(bu 4 \&\fBHTTP Extensions for Distributed Authoring (WebDAV)\fR, section \fB6.4.1 Node Field Generation Without the IEEE 802 Address\fR, IETF RFC\-2518, February 1999, 94 pages, http://www.ietf.org/rfc/rfc2518.txt .IP \(bu 4 \&\fBDCE 1.1 compliant UUID functions\fR, FreeBSD manual pages \fBuuid\fR\|(3) and \fBuuidgen\fR\|(2), http://www.freebsd.org/cgi/man.cgi?query=uuid&manpath=FreeBSD+6.0\-RELEASE .SH HISTORY .IX Header "HISTORY" \&\fBOSSP uuid\fR was implemented in January 2004 by Ralf S. Engelschall . It was prompted by the use of UUIDs in the \fBOSSP as\fR and \fBOpenPKG\fR projects. It is a clean room implementation intended to be strictly standards compliant and maximum portable. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBuuid\fR\|(1), \fBuuid\-config\fR\|(1), \fBOSSP::uuid\fR\|(3).