uuid(3)

📦
version 1.6.2 · 2 versions
, in fedora 43

🌸 uuid(3) 🌸

hey bestie 💖 you just cracked open the uuid(3) page from the User Contributed Perl Documentation set, and honestly? you picked a good one. this is the OSSP::uuid saga, and it is giving three whole interfaces. grab a strawberry 🍓, get comfy, let's go.

✨ NAME ✨

OSSP::uuid — the OSSP uuid Perl Binding. that's the whole name. short, sweet, iconic. 💅

🦋 DESCRIPTION 🦋

okay so. OSSP uuid is an ISO-C:1999 application programming interface (API) plus a matching command line interface (CLI), and its entire job is generating Universally Unique Identifiers (UUIDs) that comply with DCE 1.1, ISO/IEC 11578:1996 and RFC 4122. no cap. 🫶

and it does not do just one flavour, it does the whole menu. it supports DCE 1.1 variant UUIDs of:

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

and there's more bindings where that came from: additional API bindings are provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. plus, if you're feeling nostalgic, optional backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID APIs. the way they just... kept the old stuff working? we love to see it. 😭

so, OSSP::uuid is the Perl binding to the OSSP uuid API, and it comes in three variants. pick your fighter 👑

🎀 TIE-STYLE API 🎀

this one is a functionality-reduced wrapper around the OO-style API, and it exists purely for very high-level convenience programming. it's the "just let me print a uuid" option and honestly, valid.

"use OSSP::uuid;"
tie" my $uuid, 'OSSP::uuid::tie', $mode, ...;"
"$uuid = [ $mode, ... ];"
"print "UUID=$uuid\n";"
"untie $uuid;"

💅 OO-STYLE API 💅

this one wraps the C-style API and is meant for high-level regular programming. it's the everyday main-character choice.

"use OSSP::uuid;"
"my $uuid = "new" OSSP::uuid;"
"$uuid->"load"($name);"
"$uuid->"make"($mode, ...);"
"$result = $uuid->"isnil"();"
"$result = $uuid->"compare"($uuid2);"
"$uuid->"import"($fmt, $data_ptr);"
"$data_ptr = $uuid->"export"($fmt);"
"[(]$str[, $rc)] = $uuid->"error"();"
"$ver = $uuid->"version"();"
"undef $uuid;"

also, heads up: the strings v1, v3, v4, v5 and mc can be used in $mode, and the strings bin, str, and txt can be used for $fmt. shortcut szn ✨

👑 C-STYLE API 👑

this is the low-level one — a direct mapping of the OSSP uuid ISO-C API to Perl, intended for low-level programming. for a description of the functions and their expected arguments, go see uuid(3).

"use OSSP::uuid qw(:all);"
"my $uuid; $rc = "uuid_create"($uuid);"
"$rc = "uuid_load"($uuid, $name);"
"$rc = "uuid_make"($uuid, $mode, ...);"
"$rc = "uuid_isnil"($uuid, $result);"
"$rc = "uuid_compare"($uuid, $uuid2, $result);"
"$rc = "uuid_import"($uuid, $fmt, $data_ptr, $data_len);"
"$rc = "uuid_export"($uuid, $fmt, $data_ptr, $data_len);"
"$str = "uuid_error"($rc);"
"$ver = "uuid_version"();"
"$rc = "uuid_destroy"($uuid);"

and because constants are the love language of low-level code 💖, these ones get exported too, for use in $rc, $mode, $fmt and $ver:

"UUID_VERSION", "UUID_LEN_BIN", "UUID_LEN_STR", "UUID_RC_OK",
"UUID_RC_ARG", "UUID_RC_MEM", "UUID_RC_SYS", "UUID_RC_INT",
"UUID_RC_IMP", "UUID_MAKE_V1", "UUID_MAKE_V3", "UUID_MAKE_V4",
"UUID_MAKE_V5", "UUID_MAKE_MC", "UUID_FMT_BIN", "UUID_FMT_STR",
"UUID_FMT_SIV", "UUID_FMT_TXT".

🌈 EXAMPLES 🌈

bestie, here's the moment you've been waiting for. the two examples below both create the version 3 UUID 02d9e6d5-9467-382e-8f9b-9300a64ac3cd, one via the OO-style API and one via the C-style API. (yes, the tie-style one is in there too, being extra. we support her.) 🎀

real talk though: error handling is omitted here so it's easier to read, but you have to add it for production-quality code. don't be out here shipping the no-error-handling version, i'm begging 😭
#   TIE-style API (very high-level)
use OSSP::uuid;
tie my $uuid, 'OSSP::uuid::tie';
$uuid = [ "v1" ];
print "UUIDs: $uuid, $uuid, $uuid\n";
$uuid = [ "v3", "ns:URL", "http://www.ossp.org/" ];
print "UUIDs: $uuid, $uuid, $uuid\n";
untie $uuid;

#   OO-style API (high-level)
use OSSP::uuid;
my $uuid    = new OSSP::uuid;
my $uuid_ns = new OSSP::uuid;
$uuid_ns->load("ns:URL");
$uuid->make("v3", $uuid_ns, "http://www.ossp.org/");
undef $uuid_ns;
my $str = $uuid->export("str");
undef $uuid;
print "$str\n";

#   C-style API (low-level)
use OSSP::uuid qw(:all);
my $uuid;    uuid_create($uuid);
my $uuid_ns; uuid_create($uuid_ns);
uuid_load($uuid_ns, "ns:URL");
uuid_make($uuid, UUID_MAKE_V3, $uuid_ns, "http://www.ossp.org/");
uuid_destroy($uuid_ns);
my $str; uuid_export($uuid, UUID_FMT_STR, $str, undef);
uuid_destroy($uuid);
print "$str\n";

🫶 SEE ALSO 🫶

go read these next, they're the whole friend group:

📜 HISTORY 📜

the Perl binding OSSP::uuid to OSSP uuid was implemented in November 2004 by Ralf S. Engelschall <rse@engelschall.com>. a legend, fr fr 👑

and that's the whole page, bestie 🦋 this was uuid(3) as shipped with perl v5.42.0, dated 2025-07-25. go make some UUIDs, you've got this. mwah 💖🧚‍♀️

📦 where this page comes from