April 22, 2008 UUID 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

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```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 *`)
```void` uuid_enc_be(```void *buf``, const uuid_t *uuid`)
```void` uuid_dec_be(```const void *buf``, uuid_t *`)

### 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. 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.

### SEE ALSO

uuidgen(1), uuidgen(2)

### 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.

### HISTORY

The UUID functions first appeared in NetBSD3.0.