UUID(3ossp)

📦
version 1.6.6 · 6 versions
, in ubuntu resolute, ubuntu stonking

🌈 uuid — Universally Unique IDentifier 🌈

hey bestie!! you just opened UUID(3ossp) — that's the LOCAL section, iykyk — and ngl this page is a whole journey. grab a snack, we're doing this. 💅✨

🎀 NAME 🎀

uuid — Universally Unique IDentifier 💖

🦋 SYNOPSIS 🦋

#include <uuid.h>
cc $(pkg-config --libs --cflags ossp-uuid) ...

💜 DESCRIPTION 💜

okay so OSSP uuid is a ISO-C:1999 application programming interface (API) and a matching command line interface (CLI) for generating RFC 9562, ISO/IEC 11578:1996 and IETF RFC-4122 compliant Universally Unique Identifiers (UUIDs). she supports DCE 1.1 variant UUIDs in these flavors:

  • version 1 — time and node based 🕐
  • version 3 — name based, MD5 🔤
  • version 4 — random number based 🎲
  • version 5 — name based, SHA-1 🔐

bonus content: there are additional API bindings for the Perl:5 language, and optional backward compatibility for the ISO-C DCE-1.1 and Perl Data::UUID APIs. obsessed.

UUIDs are 128 bit numbers that are intended to have a high likelihood of uniqueness over space and time, and they're computationally difficult to guess. they're globally unique identifiers that can be locally generated — no need to hit up a global registration authority, no cap. UUIDs are meant as unique identifiers both for mass tagging objects with an extremely short lifetime and for reliably identifying very persistent objects across a network. versatile queen. 👑

also heads up: this page is specifically the ISO-C application programming interface (API) of OSSP uuid.

🧬 UUID Binary Representation 🧬

per RFC 9562, ISO/IEC 11578:1996 and IETF RFC-4122, a DCE 1.1 variant UUID is a 128 bit number defined out of 7 fields, each field a multiple of an octet in size, and stored in network byte order:

                                                          [4]
                                                         version
                                                       -->|  |<--
                                                          |  |
                                                          |  |  [16]
                      [32]                      [16]      |  |time_hi
                    time_low                  time_mid    | _and_version
          |<---------------------------->||<------------>||<------------>|
          | MSB                          ||              ||  |           |
          | /                            ||              ||  |           |
          |/                             ||              ||  |           |

          +------++------++------++------++------++------++------++------+~~
          |  15  ||  14  ||  13  ||  12  ||  11  ||  10  |####9  ||   8  |
          | MSO  ||      ||      ||      ||      ||      |####   ||      |
          +------++------++------++------++------++------++------++------+~~
          7654321076543210765432107654321076543210765432107654321076543210

        ~~+------++------++------++------++------++------++------++------+
          ##* 7  ||   6  ||   5  ||   4  ||   3  ||   2  ||   1  ||   0  |
          ##*    ||      ||      ||      ||      ||      ||      ||  LSO |
        ~~+------++------++------++------++------++------++------++------+
          7654321076543210765432107654321076543210765432107654321076543210

          | |    ||      ||                                             /|
          | |    ||      ||                                            / |
          | |    ||      ||                                          LSB |
          |<---->||<---->||<-------------------------------------------->|
          |clk_seq clk_seq                      node
          |_hi_res _low                         [48]
          |[5-6]    [8]
          | |
       -->| |<--
        variant
         [2-3]

an example of a UUID binary representation is the octet stream 0xF8 0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B 0xF6. ✨ and fr fr, this binary representation format is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_BIN. 💅

🔤 UUID ASCII String Representation 🔤

per RFC 9562, ISO/IEC 11578:1996 and IETF RFC-4122, a DCE 1.1 variant UUID is represented as an ASCII string made of 8 hexadecimal digits, then a hyphen, then three groups of 4 hexadecimal digits each followed by a hyphen, then 12 hexadecimal digits. formally, the string representation is defined by this grammar:

uuid                        = <time_low> "-"
                              <time_mid> "-"
                              <time_high_and_version> "-"
                              <clock_seq_high_and_reserved>
                              <clock_seq_low> "-"
                              <node>
time_low                    = 4*<hex_octet>
time_mid                    = 2*<hex_octet>
time_high_and_version       = 2*<hex_octet>
clock_seq_high_and_reserved = <hex_octet>
clock_seq_low               = <hex_octet>
node                        = 6*<hex_octet>
hex_octet                   = <hex_digit> <hex_digit>
hex_digit                   = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
                            |"a"|"b"|"c"|"d"|"e"|"f"
                            |"A"|"B"|"C"|"D"|"E"|"F"

an example of a UUID string representation is the ASCII string "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". the string representation format is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_STR. 💖

Notice: a corresponding URL can be generated out of an ASCII string representation of a UUID by prefixing with urn:uuid: as in "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6". 🦋

🔢 UUID Single Integer Value Representation 🔢

per the ISO/IEC 11578:1996 and ITU-T Rec. X.667 standards, a DCE 1.1 variant UUID can also be represented as a single integer value consisting of a decimal number with up to 39 digits.

an example of a UUID single integer value representation is the decimal number "329800735698586629295641978511506172918". the string representation format is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_SIV. ✨

Notice: a corresponding ISO OID can be generated under the "{joint-iso-itu-t(2) uuid(25)}" arc out of a single integer value representation of a UUID by prefixing with 2.25.. an example OID is "2.25.329800735698586629295641978511506172918". additionally, a URL can be generated by further prefixing with urn:oid: as in "urn:oid:2.25.329800735698586629295641978511506172918". 🎀

👑 UUID Variants and Versions 👑

a UUID has a variant and a version. the variant defines the layout of the UUID. the version defines the content of the UUID. the UUID variant supported in OSSP uuid is the DCE 1.1 variant only. the DCE 1.1 UUID variant versions supported in OSSP uuid are:

Version 1 (time and node based) these are the classical UUIDs, created out of a 60-bit system time, a 14-bit local clock sequence and 48-bit system MAC address. the MAC address can be either the real one of a physical network interface card (NIC) or a random multi-cast MAC address. Version 1 UUIDs are usually used as one-time global unique identifiers. 🕐

Version 3 (name based, MD5) these are UUIDs based on the 128-bit MD5 message digest of the concatenation of a 128-bit namespace UUID and a name string of arbitrary length. Version 3 UUIDs are usually used for non-unique but repeatable message digest identifiers. 🔤

Version 4 (random data based) these are UUIDs based on just 128-bit of random data. Version 4 UUIDs are usually used as one-time local unique identifiers. 🎲

Version 5 (name based, SHA-1) these are UUIDs based on the 160-bit SHA-1 message digest of the concatenation of a 128-bit namespace UUID and a name string of arbitrary length. Version 5 UUIDs are usually used for non-unique but repeatable message digest identifiers. 🔐

Version 5 (name based, SHA-1) these are UUIDs based on the 160-bit SHA-1 message digest of the concatenation of a 128-bit namespace UUID and a name string of arbitrary length. Version 5 UUIDs are usually used for non-unique but repeatable message digest identifiers. 🔐

not me noticing version 5 is listed twice 💀 yeah bestie, the page really does say it twice — keeping it exactly as it is, no editing, that's the vibe. 🫶

Version 6 (time (reverse) and node based) these are compatible with and very similar to Version 1 UUIDs, except the time is stored from the most significant parts to the least significant parts. this improves locality in some database implementations. 🔄

Version 7 (UNIX time based) these UUIDs consist of a 48-bit UNIX time (with 1ms precision) in big-endian, then 10 bytes of random data. RFC 9562 recommends these for new designs. 🔥

💫 UUID Uniqueness 💫

Version 1/6 UUIDs are guaranteed to be unique through combinations of hardware addresses, time stamps and random seeds. there is a reference in the UUID to the hardware (MAC) address of the first network interface card (NIC) on the host which generated the UUID — this reference is intended to ensure the UUID will be unique in space, since the MAC address of every network card is assigned by a single global authority (IEEE) and is guaranteed to be unique. the next component in a UUID is a timestamp which, as the clock always (should) move forward, will be unique in time. just in case some part of the above goes wrong (the hardware address cannot be determined, or the clock moved steps backward), there's a random clock sequence component placed into the UUID as a "catch-all" for uniqueness. 🕐💪

Version 3/5 UUIDs are guaranteed to be inherently globally unique if the combination of namespace and name used to generate them is unique. 🔤🔐

Version 4 UUIDs are not guaranteed to be globally unique, because they're generated out of locally gathered random numbers only. nevertheless there is still a high likelihood of uniqueness over space and time, and that they're computationally difficult to guess. 🎲✨

Version 7 UUIDs attempt to guarantee uniqueness by subdividing each millisecond of real time into 2^80 (10^24) possible values. 🔥

🌙 Nil UUID 🌙

there is a special Nil UUID consisting of all octets set to zero in the binary representation. it can be used as a special UUID value which does not conflict with real UUIDs. 🕳️

⭐ Max UUID ⭐

similarly to the Nil UUID, the Max UUID consists of all octets set to 0xFF (255, all bits set) in the binary representation. it can be used as a special UUID value which does not conflict with real UUIDs, but it sorts after everything else. 👑

💖 APPLICATION PROGRAMMING INTERFACE 💖

okay bestie, the ISO-C Application Programming Interface (API) of OSSP uuid is literally built from the following components. No skips, no cuts, we're covering every single one. ✨

✨ CONSTANTS ✨

The following constants are provided, and they are all iconic in their own way:

  • UUID_VERSION — the hexadecimal encoded OSSP uuid version. This allows compile-time checking of the OSSP uuid version. For run-time checking use uuid_version() instead. The current value 0x10626 encodes 1.6.6. slay 💅
  • UUID_LEN_BIN, UUID_LEN_STR, UUID_LEN_SIV — the number of octets of the UUID binary and string representations. Notice that the lengths of the string representation (UUID_LEN_STR) and the lengths of the single integer value representation (UUID_LEN_SIV) does not include the necessary NUL termination character. important detail, bestie 🫶
  • UUID_MAKE_V1, UUID_MAKE_V3, UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_V6, UUID_MAKE_V7, UUID_MAKE_MC — the mode bits for use with uuid_make(). UUID_MAKE_Vn specify which UUID version to generate. UUID_MAKE_MC forces the use of a random multi-cast MAC address instead of the real physical MAC address in version 1 and 6 UUIDs. choices, choices 🌈
  • UUID_RC_OK, UUID_RC_ARG, UUID_RC_MEM, UUID_RC_SYS, UUID_RC_INT, UUID_RC_IMP — the possible numerical return-codes of API functions. UUID_RC_OK indicates success, the others indicate errors. Use uuid_error() to translate them into string versions. errors? not today 💀
  • UUID_FMT_BIN, UID_FMT_STR, UID_FMT_SIV, UID_FMT_TXT — the fmt formats for use with uuid_import() and uuid_export():
    • UUID_FMT_BIN indicates the UUID binary representation (of length UUID_LEN_BIN),
    • UUID_FMT_STR indicates the UUID string representation (of length UUID_LEN_STR),
    • UUID_FMT_SIV indicates the UUID single integer value representation (of maximum length UUID_LEN_SIV), and
    • UUID_FMT_TXT indicates the textual description (of arbitrary length) of a UUID (this powers uuid(1) -d). the range? iconic 👑

🔥 FUNCTIONS 🔥

These are the functions, and they are all that and a bag of chips. Error handling? Not in the examples, but you know the vibe. Let's go function by function, no cap:

  • uuid_rc_t uuid_create(uuid_t **uuid) — Create a new UUID object and store a pointer to it in *uuid. A UUID object consists of an internal representation of a UUID, potential internal RNG context, and timestamp information. The initial UUID is the Nil UUID. fresh start energy 🧚
  • uuid_rc_t uuid_destroy(uuid_t *uuid) — Destroy UUID object uuid. bye bye 👋
  • uuid_rc_t uuid_clone(const uuid_t *uuid, uuid_t **uuid_clone) — Clone UUID object uuid and store new UUID object in *uuid_clone. copy paste but make it fashion 💜
  • uuid_rc_t uuid_isnil(const uuid_t *uuid, int *result) — Checks whether the UUID in uuid is the Nil UUID. If this is the case, it returns 1 in *result. Else it returns false in *result. nil check, periodt 💅
  • uuid_rc_t uuid_ismax(const uuid_t *uuid, int *result) — Checks whether the UUID in uuid is the Max UUID. If this is the case, it returns 1 in *result. Else it returns false in *result. maxxed out 🔥
  • uuid_rc_t uuid_compare(const uuid_t *uuid, const uuid_t *uuid2, int *result) — Compares the order of the two UUIDs and returns the result in *result: -1 if uuid < uuid2, 0 if uuid = uuid2, and +1 if uuid > uuid2. who's bigger? we compare 📏
  • uuid_rc_t uuid_import(uuid_t *uuid, uuid_fmt_t fmt, const void *data_ptr, size_t data_len) — Imports uuid from an external representation of format fmt. The data is read from the buffer at data_ptr which contains at least data_len bytes. The format of the external representation is specified by fmt and the minimum expected length in data_len depends on it. Valid values for fmt are UUID_FMT_BIN, UUID_FMT_STR, and UUID_FMT_SIV. bring it in 🍓
  • uuid_rc_t uuid_export(const uuid_t *uuid, uuid_fmt_t fmt, void *data_ptr, size_t *data_len) — Exports uuid into an external representation of format fmt. Valid values for fmt are UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV, and UUID_FMT_TXT. The data is written to the buffer located at *(type **)data_ptr, where type is uint8_t for UUID_FMT_BIN and char for other formats. The buffer has to have room for at least *data_len bytes. If *(type **)data_ptr is NULL, data_len is ignored as input and a new buffer is allocated with malloc(3) and returned in *(type **)data_ptr. If data_len is not NULL, the number of available bytes in the buffer has to be provided in *data_len. The number of actually written bytes are returned in *data_len again. The minimum required buffer length depends on the external representation as specified by fmt (see above). For UUID_FMT_TXT, a buffer of unspecified length is required, and hence it is recommended to allow OSSP uuid to allocate the buffer as necessary. buffer management? we love to see it 🫶
  • uuid_rc_t uuid_load(uuid_t *uuid, const char *name) — Loads a pre-defined UUID value into uuid. The following name arguments are currently known:
    • nil 00000000-0000-0000-0000-000000000000
    • max ffffffff-ffff-ffff-ffff-ffffffffffff
    • ns:DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8
    • ns:URL 6ba7b811-9dad-11d1-80b4-00c04fd430c8
    • ns:OID 6ba7b812-9dad-11d1-80b4-00c04fd430c8
    • ns:X500 6ba7b814-9dad-11d1-80b4-00c04fd430c8 ns:XXX are names of pre-defined name-space UUIDs for use in the generation of DCE 1.1 version 3 and version 5 UUIDs. pre-made, pre-loved 💜
  • uuid_rc_t uuid_make(uuid_t *uuid, unsigned int mode, ...) — Generates a new UUID in uuid according to mode and optional arguments (dependent on mode). If mode contains the UUID_MAKE_V1 or UUID_MAKE_V6 bit, a DCE 1.1 variant UUID of version 1 or 6 is generated. Then optionally the bit UUID_MAKE_MC forces the use of random multi-cast MAC address instead of the real physical MAC address (the default). The UUID is generated out of the 60-bit current system time, a 12-bit clock sequence (initialised to random, then incremental in v1; always random in v6) and the 48-bit MAC address. If mode contains the UUID_MAKE_V3 or UUID_MAKE_V5 bit, a DCE 1.1 variant UUID of version 3 or 5 is generated and two additional arguments are expected: first, a namespace UUID object (uuid_t *). Second, a name string of arbitrary length (const char *). The UUID is generated out of the 128-bit MD5 or 160-bit SHA-1 from the concatenated octet stream of namespace UUID and name string. If mode contains the UUID_MAKE_V4 bit, a DCE 1.1 variant UUID of version 4 is generated. The UUID is generated out of 128-bit random data. If mode contains the UUID_MAKE_V7 bit, a DCE 1.1 variant UUID of version 7 is generated. The UUID is generated out of 48 bits of time and 80 bits of random data. the main event, literally 🌈
  • char * uuid_error(uuid_rc_t rc) — Returns a constant string representation corresponding to the return-code rc for use in displaying OSSP uuid errors. error translator, bestie 💀
  • unsigned long uuid_version() — Returns the hexadecimal encoded OSSP uuid version as compiled into the library object files. This allows run-time checking of the OSSP version. For compile-time checking use UUID_VERSION instead. version check, no cap ✨

🌈 EXAMPLES 🌈

The following shows an example usage of the API. Error handling is omitted for code simplification and has to be re-added for production code. don't forget to add it back, bestie 🫶

       /* generate a RFC 9562 v1 UUID from system environment */
       char *uuid_v1() {
               uuid_t *uuid;
               uuid_create(&uuid);
               uuid_make(uuid, UUID_MAKE_V1);

               char *str = NULL;
               uuid_export(uuid, UUID_FMT_STR, &str, NULL);
               uuid_destroy(uuid);
               return str;
       }

       /* generate a RFC 9562 v3 UUID from an URL */
       char *uuid_v3(const char *url) {
               uuid_t *uuid_ns;
               uuid_create(&uuid_ns);
               uuid_load(uuid_ns, "ns:URL");

               uuid_t *uuid;
               uuid_create(&uuid);
               uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url);

               char *str = NULL;
               uuid_export(uuid, UUID_FMT_STR, &str, NULL);
               uuid_destroy(uuid_ns);
               uuid_destroy(uuid);
               return str;
       }

👑 SEE ALSO 👑

uuid(1), OSSP::uuid(3)

The following are references to UUID documentation and specifications:

💜 HISTORY 💜

OSSP uuid was implemented in January 2004 by Ralf S. Engelschall <rse@engelschall.com>. It was prompted by the use of UUIDs in the OSSP as and OpenPKG projects. It is a clean room implementation intended to be strictly standards compliant and maximally portable. a legend, periodt 👑

This iconic page is from ossp-uuid 1.6.6, dated December 8, 2025, and it's UUID(3ossp), periodt. 💅✨

📦 where this page comes from