Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
.::uuid(3)		 Universally Unique Identifier		    .::uuid(3)

NAME
       OSSP 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).

04-Jul-2008			OSSP uuid 1.6.2			    .::uuid(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ossp-uuid&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help