Module uuid

Description
Data Types
Function Index
Function Details

Erlang UUID Generation

http://www.ietf.org/rfc/rfc4122.txt is the reference for official UUIDs. This implementation provides a version 1 UUID that includes both the Erlang pid identifier (ID, Serial, Creation) and the distributed Erlang node name within the 48 bit node ID. To make room for the Erlang pid identifier, the 48 bits from the MAC address (i.e., 3 OCI (Organizationally Unique Identifier) bytes and 3 NIC (Network Interface Controller) specific bytes) and the distributed Erlang node name are bitwise-XORed down to 16 bits. The Erlang pid is bitwise-XORed from 72 bits down to 32 bits. The version 3 (MD5), version 4 (random), and version 5 (SHA) methods are provided as specified within the RFC.

The ordered version 1 variant is not present in the RFC, though it is the most standards-compliant way of providing timestamp UUID ordering.

Version: 1.8.0 Apr 17 2026 10:57:00 ------------------------------------------------------------------------

Authors: Michael Truog (mjtruog at protonmail dot com).

Description

Erlang UUID Generation

The ordered version 1 variant is not present in the RFC, though it is the most standards-compliant way of providing timestamp UUID ordering. Timestamp ordering has been used in many non-standard UUID formats based on version 1 and typically limited to the same data present in the version 1 UUID (e.g., "Version 6" at http://gh.peabody.io/uuidv6/).

Data Types

state()

state() = #uuid_state{variant = v1_variant(), node_id = <<_:48>>, clock_seq = 0..16383, timestamp_type = timestamp_type_internal(), timestamp_last = integer()}

timestamp_type()

timestamp_type() = erlang | os | warp

timestamp_type_internal()

timestamp_type_internal() = erlang_timestamp | os | warp

uuid()

uuid() = <<_:128>>

v1_variant()

v1_variant() = rfc4122 | ordered

Function Index

get_v1/1	Get a v1 UUID. .
get_v1_datetime/1	Get an ISO8601 datetime in UTC from a v1 UUID's time value. http://www.w3.org/TR/NOTE-datetime.
get_v1_datetime/2	Get an ISO8601 datetime in UTC from a v1 UUID's time value with an offset in microseconds. http://www.w3.org/TR/NOTE-datetime.
get_v1_time/0	Get the current time value in a manner consistent with the v1 UUID. The result is an integer in microseconds.
get_v1_time/1	Get the current time value in a manner consistent with the v1 UUID. The result is an integer in microseconds.
get_v3/1	Get a v3 UUID. .
get_v3/2	Get a v3 UUID in a particular namespace. .
get_v3_compat/1	Get a compatible v3 UUID. Do not use all bits from the checksum so that the UUID matches external implementations.
get_v3_compat/2	Get a compatible v3 UUID in a particular namespace. Do not use all bits from the checksum so that the UUID matches external implementations.
get_v4/0	Get a v4 UUID (using crypto/openssl). crypto:strong_rand_bytes/1 repeats in the same way as RAND_bytes within OpenSSL.
get_v4/1
get_v4_urandom/0	Get a v4 UUID (using Wichmann-Hill 2006). random_wh06_int:uniform/1 repeats every 2.66e36 (2^121) approx.
get_v5/1	Get a v5 UUID. .
get_v5/2	Get a v5 UUID in a particular namespace. .
get_v5_compat/1	Get a compatible v5 UUID. Do not use all bits from the checksum so that the UUID matches external implementations.
get_v5_compat/2	Get a compatible v5 UUID in a particular namespace. Do not use all bits from the checksum so that the UUID matches external implementations.
increment/1	Increment the clock sequence of v1 UUID state or a UUID. Call to increment the clock sequence counter after the system clock has been set backwards (see the RFC).
is_uuid/1	Is the term a UUID? .
is_v1/1	Is the binary a v1 UUID? .
is_v3/1	Is the binary a v3 UUID? .
is_v4/1	Is the binary a v4 UUID? .
is_v5/1	Is the binary a v5 UUID? .
mac_address/0	Provide a usable network interface MAC address. .
new/1	Create new UUID state for v1 UUID generation. .
new/2	Create new UUID state for v1 UUID generation using a specific type of timestamp. The timestamp can either be based on erlang's adjustment of time (for only strictly monotonically increasing time values) or the operating system's time without any adjustment (with timestamp_type values `erlang` and `os`, respectively).
string_to_uuid/1	Convert a string representation to a UUID. .
test/0	Regression test. .
uuid_to_list/1	Convert a UUID to a list. .
uuid_to_string/1	Convert a UUID to a string representation. .
uuid_to_string/2	Convert a UUID to a string representation based on an option. .

Function Details

get_v1/1

get_v1(State::state()) -> {uuid(), StateNew::state()}

Get a v1 UUID.

get_v1_datetime/1

get_v1_datetime(Value::timestamp_type() | state() | uuid() | erlang:timestamp()) -> string()

Get an ISO8601 datetime in UTC from a v1 UUID's time value.

http://www.w3.org/TR/NOTE-datetime

get_v1_datetime/2

get_v1_datetime(Value::timestamp_type() | state() | uuid() | erlang:timestamp(), MicroSecondsOffset::integer()) -> string()

Get an ISO8601 datetime in UTC from a v1 UUID's time value with an offset in microseconds.

http://www.w3.org/TR/NOTE-datetime

get_v1_time/0

get_v1_time() -> non_neg_integer()

Get the current time value in a manner consistent with the v1 UUID.

The result is an integer in microseconds.

get_v1_time/1

get_v1_time(Uuid_state::timestamp_type() | state() | uuid()) -> non_neg_integer()

Get the current time value in a manner consistent with the v1 UUID.

The result is an integer in microseconds.

get_v3/1

get_v3(Data::binary()) -> uuid()

Get a v3 UUID.

get_v3/2

get_v3(Namespace::dns | url | oid | x500 | binary(), Data::binary() | iolist()) -> uuid()

Get a v3 UUID in a particular namespace.

get_v3_compat/1

get_v3_compat(Data::binary()) -> uuid()

Get a compatible v3 UUID.

Do not use all bits from the checksum so that the UUID matches external implementations.

get_v3_compat/2

get_v3_compat(Namespace::dns | url | oid | x500 | binary(), Data::binary() | iolist()) -> uuid()

Get a compatible v3 UUID in a particular namespace.

Do not use all bits from the checksum so that the UUID matches external implementations.

get_v4/0

get_v4() -> uuid()

Get a v4 UUID (using crypto/openssl).

crypto:strong_rand_bytes/1 repeats in the same way as RAND_bytes within OpenSSL.

get_v4/1

get_v4(Cache::strong | cached | quickrand_cache:state()) -> uuid() | {uuid(), quickrand_cache:state()}

get_v4_urandom/0

get_v4_urandom() -> uuid()

Get a v4 UUID (using Wichmann-Hill 2006).

random_wh06_int:uniform/1 repeats every 2.66e36 (2^121) approx. (see B.A. Wichmann and I.D.Hill, in 'Generating good pseudo-random numbers', Computational Statistics and Data Analysis 51 (2006) 1614-1622) a single random_wh06_int:uniform/1 call can provide a maximum of 124 bits (see random_wh06_int.erl for details)

get_v5/1

get_v5(Data::binary()) -> uuid()

Get a v5 UUID.

get_v5/2

get_v5(Namespace::dns | url | oid | x500 | binary(), Data::binary() | iolist()) -> uuid()

Get a v5 UUID in a particular namespace.

get_v5_compat/1

get_v5_compat(Data::binary()) -> uuid()

Get a compatible v5 UUID.

Do not use all bits from the checksum so that the UUID matches external implementations.

get_v5_compat/2

get_v5_compat(Namespace::dns | url | oid | x500 | binary(), Data::binary() | iolist()) -> uuid()

Get a compatible v5 UUID in a particular namespace.

Do not use all bits from the checksum so that the UUID matches external implementations.

increment/1

increment(Uuid_state::state() | uuid()) -> state() | uuid()

Increment the clock sequence of v1 UUID state or a UUID.

Call to increment the clock sequence counter after the system clock has been set backwards (see the RFC). This is only necessary if the os or warp timestamp_type is used with a v1 UUID. The v3, v4 and v5 UUIDs are supported for completeness.

is_uuid/1

is_uuid(X1::any()) -> boolean()

Is the term a UUID?

is_v1/1

is_v1(Value::any()) -> boolean()

Is the binary a v1 UUID?

is_v3/1

is_v3(Value::any()) -> boolean()

Is the binary a v3 UUID?

is_v4/1

is_v4(Value::any()) -> boolean()

Is the binary a v4 UUID?

is_v5/1

is_v5(Value::any()) -> boolean()

Is the binary a v5 UUID?

mac_address/0

mac_address() -> [non_neg_integer()]

Provide a usable network interface MAC address.

new/1

new(Pid::pid()) -> state()

Create new UUID state for v1 UUID generation.

new/2

new(Pid::pid(), Options::timestamp_type() | [{timestamp_type, timestamp_type()} | {mac_address, [non_neg_integer()]} | {variant, v1_variant()}]) -> state()

Create new UUID state for v1 UUID generation using a specific type of timestamp.

The timestamp can either be based on erlang's adjustment of time (for only strictly monotonically increasing time values) or the operating system's time without any adjustment (with timestamp_type values erlang and os, respectively). If you want erlang's adjustment of time without enforcement of increasing time values, use the warp timestamp_type value with Erlang >= 18.0.