UUID_COMPARE(3) | Library Functions Manual | UUID_COMPARE(3)

# NAME

`uuid_compare`, `uuid_create`, `uuid_create_nil`, `uuid_equal`, `uuid_from_string`, `uuid_hash`, `uuid_is_nil`, `uuid_to_string`, `uuid_enc_le`, `uuid_dec_le`, `uuid_enc_be`, `uuid_dec_be` — Universally Unique Identifier routines

# SYNOPSIS

`#include <uuid.h>`

int32_t
`uuid_compare`(const uuid_t *uuid1, const uuid_t *uuid2, uint32_t *status);

void
`uuid_create`(uuid_t *uuid, uint32_t *status);

void
`uuid_create_nil`(uuid_t *uuid, uint32_t *status);

int32_t
`uuid_equal`(const uuid_t *uuid1, const uuid_t *uuid2, uint32_t *status);

void
`uuid_from_string`(const char *str, uuid_t *uuid, uint32_t *status);

uint16_t
`uuid_hash`(const uuid_t *uuid, uint32_t *status);

int32_t
`uuid_is_nil`(const uuid_t *uuid, uint32_t *status);

void
`uuid_to_string`(const uuid_t *uuid, char **str, uint32_t *status);

void
`uuid_enc_le`(void *buf, const uuid_t *uuid);

void
`uuid_dec_le`(const void *buf, uuid_t *uuid);

void
`uuid_enc_be`(void *buf, const uuid_t *uuid);

void
`uuid_dec_be`(const void *buf, uuid_t *uuid);

# DESCRIPTION

These routines provide for the creation and manipulation of Universally Unique Identifiers (UUIDs), also referred to as Globally Unique Identifiers (GUIDs).

The `uuid_compare`() function compares two UUIDs. It returns -1 if uuid1 precedes uuid2, 0 if they are equal, or 1 if uuid1 follows uuid2.

The `uuid_create`() function creates a new UUID. Storage for the new UUID must be pre-allocated by the caller.

The `uuid_create_nil`() function creates a nil-valued UUID. Storage for the new UUID must be pre-allocated by the caller.

The `uuid_equal`() function compares two UUIDs to determine if they are equal. It returns 1 if they are equal, and 0 if they are not equal.

The `uuid_from_string`() function parses a 36-character string representation of a UUID and converts it to binary representation. Storage for the UUID must be pre-allocated by the caller.

The `uuid_hash`() function generates a hash value for the specified UUID. Note that the hash value is not a cryptographic hash, and should not be assumed to be unique given two different UUIDs.

The `uuid_is_nil`() function returns 1 if the UUID is nil-valued and 0 if it is not.

The `uuid_to_string`() function converts a UUID from binary representation to string representation. Storage for the string is dynamically allocated and returned via the str argument. This pointer should be passed to free(3) to release the allocated storage when it is no longer needed.

The `uuid_enc_le`() and `uuid_enc_be`() functions encode a binary representation of a UUID into an octet stream in little-endian and big-endian byte order, respectively. The destination buffer must be pre-allocated by the caller, and must be large enough to hold the 16-octet binary UUID.

The `uuid_dec_le`() and `uuid_dec_be`() functions decode a UUID from an octet stream in little-endian and big-endian byte order, respectively.

# RETURN VALUES

The `uuid_compare`(), `uuid_create`(), `uuid_create_nil`(), `uuid_equal`(), `uuid_from_string`(), `uuid_hash`(), `uuid_is_nil`(), and `uuid_to_string`() functions return successful or unsuccessful completion status in the status argument unless it is `NULL`. Possible values are:

`uuid_s_ok`
  The function completed successfully.
`uuid_s_bad_version`
  The UUID does not have a known version.
`uuid_s_invalid_string_uuid`
  The string representation of a UUID is not valid.
`uuid_s_no_memory`
  Memory could not be allocated for the operation.

# STANDARDS

The `uuid_compare`(), `uuid_create`(), `uuid_create_nil`(), `uuid_equal`(), `uuid_from_string`(), `uuid_hash`(), `uuid_is_nil`(), and `uuid_to_string`() functions are compatible with the DCE 1.1 RPC specification.

`uuid_create`() generates version 4 UUIDs, specified by section 4.4 of RFC 4122.

July 3, 2023 | Debian