.. _uuid_api:

UUID

Overview

Universally Unique Identifiers (UUID), also known as Globally Unique IDentifiers (GUIDs), are 128-bit identifiers intended to guarantee uniqueness across space and time. They are defined by :rfc:9562.

The UUID subsystem provides utility functions for the generation, parsing, and manipulation of UUIDs. It supports generating version 4 (random) and version 5 (name-based) UUIDs.

Usage

To use the UUID API, include the header file:

.. code-block:: c

#include <zephyr/sys/uuid.h>

Generating a UUIDv4

UUIDv4 is based on random numbers (hence requires an entropy generator), and can be generated using the :c:func:uuid_generate_v4 function. :kconfig:option:CONFIG_UUID_V4 must also be enabled.

.. code-block:: c

struct uuid my_uuid; char uuid_str[UUID_STR_LEN];

int ret = uuid_generate_v4(&my_uuid);

if (ret != 0) { printk("Failed to generate UUID v4 (err %d)\n", ret); return ret; }

ret = uuid_to_string(&my_uuid, uuid_str); if (ret != 0) { printk("Failed to convert UUID to string (err %d)\n", ret); return ret; }

printk("UUID: %s\n", uuid_str);

Generating a UUIDv5

UUIDv5 is generated from a namespace UUID and a name (binary data), and can be generated using the :c:func:uuid_generate_v5 function. :kconfig:option:CONFIG_UUID_V5 must also be enabled.

UUIDv5 is deterministic: the same namespace and name will always result in the same UUID.

.. code-block:: c

struct uuid ns_uuid; struct uuid my_uuid; char uuid_str[UUID_STR_LEN];

/* Well-known namespace ID for URLs (RFC 9562) */ uuid_from_string("6ba7b811-9dad-11d1-80b4-00c04fd430c8", &ns_uuid);

const char *name = "https://zephyrproject.org/"; int ret = uuid_generate_v5(&ns_uuid, name, strlen(name), &my_uuid);

if (ret != 0) { printk("Failed to generate UUID v5 (err %d)\n", ret); return ret; }

ret = uuid_to_string(&my_uuid, uuid_str); if (ret != 0) { printk("Failed to convert UUID to string (err %d)\n", ret); return ret; }

/* outputs: "UUID: abdb72b5-b342-5882-925b-4ce0e3cb4790" */ printk("UUID: %s\n", uuid_str);

Configuration

Related configuration options:

:kconfig:option:CONFIG_UUID
:kconfig:option:CONFIG_UUID_V4
:kconfig:option:CONFIG_UUID_V5
:kconfig:option:CONFIG_UUID_BASE64

API Reference

.. doxygengroup:: uuid