Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019



uuid_clear, uuid_compare, uuid_copy, uuid_generate, uuid_generate_random, uuid_generate_time, uuid_is_null, uuid_parse, uuid_time, uuid_unparse - universally unique identifier (UUID) operations


cc [ flag … ] file… -luuid [ library … ]
#include <uuid/uuid.h>

void uuid_clear(uuid_t uu);
int uuid_compare(const uu1, const uu2);
void uuid_copy(uuid_t dst, const src);
void uuid_generate(uuid_t out);
void uuid_generate_random(uuid_t out);
void uuid_generate_time(uuid_t out);
int uuid_is_null(const uu);
int uuid_parse(char *in, const uu);
time_t uuid_time(const uu, struct timeval *ret_tv);
void uuid_unparse(const uu, char *out);


The uuid_clear() function sets the value of the specified universally unique identifier (UUID) variable uu to the NULL value.

The uuid_compare() function compares the two specified UUID variables uu1 and uu2 to each other. It returns an integer less than, equal to, or greater than zero if uu1 is found to be, respectively, lexicographically less than, equal, or greater than uu2.

The uuid_copy() function copies the UUID variable src to dst.

The uuid_generate() function creates a new UUID that is generated based on high-quality randomness from /dev/urandom, if available. If /dev/urandom is not available, the uuid_generate() function calls the uuid_generate_time() function. Because the use of this algorithm provides information about when and where the UUID was generated, it could cause privacy problems for some applications.

The uuid_generate_random() function produces a UUID with a random or pseudo-randomly generated time and Ethernet MAC address that corresponds to a DCE version 4 UUID.

The uuid_generate_time() function uses the current time and the randomly generated 47-bit cryptographic MAC address that corresponds to a DCE version 1 UUID. The randomly generated 47-bit cryptographic MAC address is used as the low 47 bits of the node ID, with the most significant bit of the first octet of the node ID set to 1. This bit is the multicast bit, which will never be set in IEEE 802 addresses obtained from network cards. The uniqueness of time based UUID's created by both root and normal users are guaranteed with or without zones.

The uuid_is_null() function compares the value of the specified UUID variable uu to the NULL value. If the value is equal to the NULL UUID, 1 is returned. Otherwise 0 is returned.

The uuid_parse() function converts the UUID string specified by in to the internal uuid_t format. The input UUID is a string of the form cefa7a9c-1dd2-11b2-8350-880020adbeef. In printf(3C) format, the string is “%08x-%04x-%04x-%04x-%012x”, 36 bytes plus the trailing null character. If the input string is parsed successfully, 0 is returned and the UUID is stored in the location pointed to by uu. Otherwise -1 is returned.

The uuid_time() function extracts the time at which the specified UUID uu was created. Since the UUID creation time is encoded within the UUID, this function can reasonably be expected to extract the creation time only for UUID's created with the uuid_generate_time() function. The time at which the UUID was created, in seconds since January 1, 1970 GMT (the epoch), is returned. For more information, see the time(2) man page. The time at which the UUID was created, in seconds and microseconds since the epoch is also stored in the location pointed to by ret_tv. For more information, see the gettimeofday(3C) man page.

The uuid_unparse() function converts the specified UUID uu from the internal binary format to a string of the length defined in the uuid.h macro, UUID_PRINTABLE_STRING_LENGTH, which includes the trailing null character. The resulting value is stored in the character string pointed to by out.


See attributes(7) for descriptions of the following attributes:

Interface Stability

See Also

time(2), gettimeofday(3C), printf(3C), libuuid(3LIB), attributes(7), inetd(8)