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

FreeBSD Manual Pages


home | help
UUIDGEN(2)		    BSD	System Calls Manual		    UUIDGEN(2)

     uuidgen --	generate universally unique identifiers

     Standard C	Library	(libc, -lc)

     #include <sys/uuid.h>

     uuidgen(struct uuid *store, int count);

     The uuidgen() system call generates count universally unique identifiers
     (UUIDs) and writes	them to	the buffer pointed to by store.	 The identi-
     fiers are generated according to the syntax and semantics of the DCE ver-
     sion 1 variant of universally unique identifiers.	See below for a	more
     in-depth description of the identifiers.  When no IEEE 802	address	is
     available for the node field, a random multicast address is generated for
     each invocation of	the system call.  According to the algorithm of	gener-
     ating time-based UUIDs, this will also force a new	random clock sequence,
     thereby increasing	the likelihood for the identifier to be	unique.

     When multiple identifiers are to be generated, the	uuidgen() system call
     will generate a set of identifiers	that is	dense in such a	way that there
     is	no identifier that is larger than the smallest identifier in the set
     and smaller than the largest identifier in	the set	and that is not	al-
     ready in the set.

     Universally unique	identifiers, also known	as globally unique identifiers
     (GUIDs), have a binary representation of 128-bits.	 The grouping and
     meaning of	these bits is described	by the following structure and its de-
     scription of the fields that follow it:

     struct uuid {
	     uint32_t	     time_low;
	     uint16_t	     time_mid;
	     uint16_t	     time_hi_and_version;
	     uint8_t	     clock_seq_hi_and_reserved;
	     uint8_t	     clock_seq_low;
	     uint8_t	     node[_UUID_NODE_LEN];

     time_low			The least significant 32 bits of a 60-bit
				timestamp.  This field is stored in the	native

     time_mid			The least significant 16 bits of the most sig-
				nificant 28 bits of the	60-bit timestamp.
				This field is stored in	the native byte-order.

     time_hi_and_version	The most significant 12	bits of	the 60-bit
				timestamp multiplexed with a 4-bit version
				number.	 The version number is stored in the
				most significant 4 bits	of the 16-bit field.
				This field is stored in	the native byte-order.

     clock_seq_hi_and_reserved	The most significant 6 bits of a 14-bit	se-
				quence number multiplexed with a 2-bit variant
				value.	Note that the width of the variant
				value is determined by the variant itself.
				Identifiers generated by the uuidgen() system
				call have variant value	10b.  the variant
				value is stored	in the most significant	bits
				of the field.

     clock_seq_low		The least significant 8	bits of	a 14-bit se-
				quence number.

     node			The 6-byte IEEE	802 (MAC) address of one of
				the interfaces of the node.  If	no such	inter-
				face exists, a random multi-cast address is
				used instead.

     The binary	representation is sensitive to byte ordering.  Any multi-byte
     field is to be stored in the local	or native byte-order and identifiers
     must be converted when transmitted	to hosts that do not agree on the
     byte-order.  The specification does not however document what this	means
     in	concrete terms and is otherwise	beyond the scope of this system	call.

     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the

     The uuidgen() system call can fail	with:

     [EFAULT]		The buffer pointed to by store could not be written to
			for any	or all identifiers.

     [EINVAL]		The count argument is less than	1 or larger than the
			hard upper limit of 2048.

     uuidgen(1), uuid(3)

     The identifiers are represented and generated in conformance with the DCE
     1.1 RPC specification.  The uuidgen() system call is itself not part of
     the specification.

     The uuidgen() system call first appeared in FreeBSD 5.0.

BSD				 May 26, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help