UUID(3)

📦
version 0.360.0 · 8 versions
, in opensuse-leap 16.0

✨ NAME ✨

okay bestie, welcome to the UUID(3) page — it's literally the Universally Unique Identifier library for Perl, and it's giving main character energy for IDs. 💅🦋

🌈 SYNOPSIS 🌈

        # SIMPLE
        use UUID qw(uuid);    # see EXPORTS
        my $str = uuid();     # generate version 4 UUID string

        # SPECIFIC
        $str = uuid1();                   # new version 1 UUID string
        $str = uuid4();                   # new version 4 UUID string
        $str = uuid6();                   # new version 6 UUID string
        $str = uuid7();                   # new version 7 UUID string

        # NAMESPACE is 'dns', 'url', 'oid', or 'x500'; case-insensitive.
        $str = uuid3(dns => 'www.example.com');
        $str = uuid5(url => 'https://www.example.com/foo.html');

        UUID::generate_v1($bin);          # new version 1 binary UUID
        UUID::generate_v4($bin);          # new version 4 binary UUID
        UUID::generate_v6($bin);          # new version 6 binary UUID
        UUID::generate_v7($bin);          # new version 7 binary UUID

        UUID::generate_v3($bin, dns => 'www.example.com');
        UUID::generate_v5($bin, url => 'https://www.example.com/foo.txt');

        UUID::generate($bin);             # alias for generate_v1()
        UUID::generate_time($bin);        # alias for generate_v1()
        UUID::generate_random($bin);      # alias for generate_v4()

        UUID::unparse($bin, $str);        # stringify $bin; prefer lowercase
        UUID::unparse_lower($bin, $str);  # force lowercase stringify
        UUID::unparse_upper($bin, $str);  # force uppercase stringify

        UUID::parse($str, $bin);          # map string to binary UUID

        UUID::compare($bin1, $bin2);      # compare binary UUIDs
        UUID::copy($dst, $src);           # copy binary UUID from $src to $dst

        UUID::clear($bin);                # set binary UUID to NULL
        UUID::is_null($bin);              # compare binary UUID to NULL

        UUID::time($bin);                 # return UUID time
        UUID::type($bin);                 # return UUID type
        UUID::variant($bin);              # return UUID variant
        UUID::version($bin);              # return UUID version

🦋 DESCRIPTION 🦋

So here's the vibe: the UUID library is used to generate unique identifiers for objects that may be accessible beyond the local system. Think unique HTTP cookies across multiple web servers — no communication between the servers, and no fear of a name clash. 🍓

The generated UUIDs can be reasonably expected to be unique within a system, and unique across all systems, and are compatible with those created by the Open Software Foundation (OSF) Distributed Computing Environment (DCE). Iconic cross-system behavior, fr fr. ✨

All generated UUIDs are either version 1, 3, 4, 5, 6, or version 7. And all are variant 1, meaning compliant with the OSF DCE standard as described in RFC4122. 👑

Versions 6 and 7 are not standardized. They are presented here as proposed in RFC4122bis, version 14, and may change in the future. RFC4122bis is noted to replace RFC4122, if approved. So yeah, those two are the experimental girlies for now. 💀

🔥 FUNCTIONS 🔥

Most of the UUID functions expose the historically underlying libuuid C interface rather directly. That is, many return their values in their parameters and nothing else. It's not very Perlish, but it's been like that for a long time so not likely to change any time soon. 😭

All take or return UUIDs in either binary or string format. The string format resembles the following:

21b081a3-de83-4480-a14f-e89a1dcf8f0f

Or, in terms of printf(3) format:

"%08x-%04x-%04x-%04x-%012x"

The binary form is simply a packed 16 byte binary value. cute and compact. 🎀

🧹 clear( $uuid )

Sets binary $uuid equal to the value of the NULL UUID. That's it. No drama. 💅

⚖️ compare( $uuid1, $uuid2 )

Compares two binary UUIDs.

Returns an integer less than, equal to, or greater than zero if $uuid1 is less than, equal to, or greater than $uuid2.

If one is defined and the other not, the defined value is deemed the larger.

If either operand is not a binary UUID, falls back to a simple string comparison returning similar values. flexible but still judgmental, lowkey. ✨

📋 copy( $dst, $src )

Copies the binary $src UUID to $dst.

If $src isn't a UUID, $dst is set to the NULL UUID. safety reset behavior, we love to see it. 🫶

🌱 generate( $uuid )

Alias for generate_v4().

Prior to version 0.33, this function provided either a binary version 4 UUID or fell back to version 1 in some cases. This is no longer the case. The fallback feature was removed with the addition of an onboard crypto-strength number generator. so no secret fallback era anymore, bestie. 😭

🎲 generate_random( $uuid )

Alias for generate_v4().

⏰ generate_time( $uuid )

Alias for generate_v1().

1️⃣ generate_v1( $uuid )

Generates a new version 1 binary UUID using the current time and the local ethernet MAC address, if available.

If the MAC address is not available at startup, or a randomized address is requested (see :mac in EXPORTS), a random address is used. The multicast bit of this address is set to avoid conflict with addresses returned from network cards. very mindful, very demure. 🌸

3️⃣ generate_v3( $uuid, NAMESPACE => NAME )

Generate a new version 3 binary UUID using the given namespace and name hashed through the MD5 algorithm.

Namespace is one of "dns", "url", "oid", or "x500", and case-insensitive. It is used to select the namespace UUID to hash with the name.

Name should be an entity from the given namespace, but can really be any text. no cap, any text goes. 💜

4️⃣ generate_v4( $uuid )

Generates a new version 4 binary UUID using mostly random data. There are 6 bits used for the UUID format, leaving 122 bits for randomness. random girlie with structure, periodt. 🎀

5️⃣ generate_v5( $uuid, NAMESPACE => NAME )

Generate a new version 5 binary UUID using the given namespace and name hashed through the SHA1 algorithm.

Namespace is one of "dns", "url", "oid", or "x500", and case-insensitive. It is used to select the namespace UUID to hash with the name.

Name should be an entity from the given namespace, but can really be any text. same namespace energy, SHA1 flavor. 🦋

6️⃣ generate_v6( $uuid )

Generates a new version 6 binary UUID using the current time and the local ethernet MAC address, if available.

If the MAC address is not available at startup, or a randomized address is requested (see :mac in EXPORTS), a random address is used. The multicast bit of this address is set to avoid conflict with addresses returned from network cards.

Version 6 is the same as version 1, with reversed time fields to make it more database friendly. database bestie behavior. 👑

7️⃣ generate_v7( $uuid )

Generates a new version 7 binary UUID using the current time and random data. There are 6 bits used for the UUID format and 48 bits for timestamp, leaving 74 bits for randomness.

Version 7 is the same as version 6, in that it uses reversed timestamp fields, but also uses a Unix epoch time base instead of Gregorian. Unix epoch girlie with reversed timestamp slay. ⭐

🕳️ is_null( $uuid )

Compares the value of $uuid to the NULL UUID.

Returns 1 if NULL, and 0 otherwise. simple binary answer, no overthinking. 💅

🔍 parse( $string, $uuid )

Converts the string format UUID in $string to binary and returns in $uuid. The previous content of $uuid, if any, is lost.

Returns 0 on success and -1 on failure. Additionally on failure, the content of $uuid is unchanged. so on failure it's like nothing happened. 🙈

⏳ time( $uuid )

Returns the time element of a binary UUID in seconds since the epoch, the same as Perl's time function.

Keep in mind this only works for version 1, 6, and version 7 UUIDs. Values returned from other versions are always 0. not every UUID has time tea to spill. 🍓

🔁 type( $uuid )

Alias for version().

🧵 unparse( $uuid, $string )

Alias for unparse_lower().

Prior to version 0.32, casing of the return value was system-dependent. Later versions are lowercase, per RFC4122. lowercase supremacy, fr fr. 💖

🔡 unparse_lower( $uuid, $string )

Converts the binary UUID in $uuid to string format and returns in $string. The previous content of $string, if any, is lost.

🔠 unparse_upper( $uuid, $string )

Same as unparse_lower() but $string is forced to upper case. shouty UUID moment. 📣

💫 uuid()

Alias for uuid4().

🫧 uuid0()

Returns a new string format NULL UUID. the all-null string girlie has arrived. 🎀

1️⃣ uuid1()

Returns a new string format version 1 UUID. Functionally the equivalent of calling generate_v1() then unparse(), but throwing away the intermediate binary UUID. efficient and mysterious. 💅

3️⃣ uuid3(NAMESPACE = NAME)>

Same as uuid1() but version 3. See generate_v3(). namespace hashing but make it string format. 🦋

4️⃣ uuid4()

Same as uuid1() but version 4.

5️⃣ uuid5(NAMESPACE = NAME)>

Same as uuid1() but version 5. See generate_v5(). SHA1 namespace energy, string format edition. ✨

6️⃣ uuid6()

Same as uuid1() but version 6.

7️⃣ uuid7()

Same as uuid1() but version 7.

🧬 variant( $uuid )

Returns the variant of binary $uuid.

This module only generates variant 1 UUIDs. Others may be found in the wild.

Known variants:

0  NCS
1  DCE
2  Microsoft
3  Other

🏷️ version( $uuid> )

Returns the version of binary $uuid.

This module only generates version 1, 3, 4, 5, 6, and version 7 UUIDs. Others may be found in the wild.

Known versions:

v1  date/time and node address
v2  date/time and node address, security version
v3  namespace based, MD5 hash
v4  random
v5  namespace based, SHA-1 hash
v6  reverse date/time and node address
v7  reverse unix date/time and random
v8  custom

🧚 MAINTAINING STATE 🧚

Internal state is optionally maintained for timestamped UUIDs (versions 1, 6, and 7) via a file designated by the :persist export tag. See EXPORTS for details. 👀

The file records various internal states at the time the last UUID is generated, preventing future instances from overlapping the prior UUID sequence. This allows the sequence to absolutely survive reboots and, more importantly, backwards resetting of system time. resilience queen behavior. 👑

If :persist is not used, time resets will still be detected while the module is loaded and handled by incrementing the UUID clock_seq field. The clock_seq field is randomly initialized in this case anyway, so the chance of overlap is low but still exists since clock_seq is only 14 bits wide. Using a random MAC will help (see :mac in EXPORTS), adding an additional 48 bits of randomness. so there's still some luck involved, but it's a calculated vibe. 🍀

NOTE: Using :persist incurs a serious performance penalty, in excess of 95% on tested platforms. You can run make compare in the distribution directory to see how this might affect your application, but unless you need many thousands of UUIDs/sec it's probably a non-issue. 💀✨

🌈 RANDOM NUMBERS 🌈

Okay so versions 4 and 7 UUIDs are partially filled with random numbers, and same goes for versions 1 and 6 when you’re using the :mac option. ✨

Before version 0.33, UUID got its randomness from the system’s /dev/random device, or a similar interface. On some platforms it called getrandom(), on others it read straight from /dev/urandom. And Win32? Win32 did something completely different. 💀

Starting in 0.33, UUID generates random numbers itself using the ChaCha20 algorithm, which is considered crypto-strength in most circles. It’s the same algo used as the basis for many modern kernel RNGs — except without the same entropy gathering ability. 🫶

To compensate, UUID mixes the output from ChaCha with output from another RNG, Xoshiro. The idea: by mixing the two, the true output from either is effectively hidden, making discovery of either’s key much more unlikely than it already is. And without the keys, you can’t predict the future. 🔮

Well, that’s the theory anyway. 🙈

🦋 NAMESPACES 🦋

Versions 3 and 5 generate UUIDs within namespaces. What that really means is the NAME value is concatenated with a dedicated NAMESPACE UUID before hashing. 🧚

Available namespaces and UUIDs:

dns   6ba7b810-9dad-11d1-80b4-00c04fd430c8
url   6ba7b811-9dad-11d1-80b4-00c04fd430c8
oid   6ba7b812-9dad-11d1-80b4-00c04fd430c8
x500  6ba7b814-9dad-11d1-80b4-00c04fd430c8

For example, if you need to create some UUIDs within your own "questions" and "answers" namespaces using SHA1:

$ns_base = uuid5( dns => 'www.example.com' );

$ns_questions = uuid5( $ns_base, 'questions' );
$ns_answers   = uuid5( $ns_base, 'answers'   );

for $topic ( next_qa_aref() ) {
    ($q, $a) = @$topic;
    $uuid_question = uuid5( $ns_questions, $q );
    $uuid_answer   = uuid5( $ns_answers,   $a );
    ...
}

This way, you can deterministically convert existing (and likely colliding) namespaces over to one UUID namespace, which is often useful when merging datasets. 👑

You also don’t need to publish your base and namespace UUIDs. Anyone using the same logic can generate the same question and answer UUIDs. 💖

✨ EXPORTS ✨

None by default. All functions may be imported in the usual manner, either individually or all at once using the :all tag. 🎀

Beware that importing :all clobbers Perl’s time(), not to mention a few other commonly used subs, like copy() from File::Copy. 😭

🍓 :mac=mode 🍓

The MAC address used for MAC-inclusive UUIDs (versions 1 and 6) is forced to always be random in one of two modes:

  • random — The MAC address is generated once at startup and used through the lifetime of the process. This is the default if a real MAC cannot be found. ✨
  • unique — A new MAC address is generated for each new UUID. It is not guaranteed to be unique beyond the probability of randomness. 🦋

🌸 :persist=path/to/state.txt 🌸

Path to timestamp state maintenance file. (See MAINTAINING STATE.) The path may be either relative or absolute. 🧚

If the file does not exist, it will be created provided the path exists and the user has permission. 💅

If the file cannot be opened, cannot be created, or is a symlink, UUID will ignore it. No state will be maintained. 💀

WARNING: Do not :persist in a public directory. See CVE-2013-4184. UUID attempts to avoid this, but nothing is foolproof. Only YOU can prevent symlink attacks! 🚨

🎀 :defer[=N] 🎀

Persistence of state is deferred N seconds when generating time-based UUIDs. More precisely, state is only saved every N seconds. If UUIDs are generated more often, those within the N second window will not save state. ⏳

Defer values greater than some platform-specific interval greatly reduce the performance penalty introduced through persistence. While the default, :defer=0.001, is probably fine, you can run make persist in the distribution directory to see the effect of various values. 🔥

💜 THREAD SAFETY 💜

This module is believed to be thread safe. 🧵✨

👑 UUID LIBRARY 👑

Releases prior to UUID-0.32 required libuuid or similar be installed first. This is no longer the case. Version 0.33 bundled the e2fsprogs UUID code, and version 0.34 removed it altogether. 💅

🔥 BENCHMARKS 🔥

There are a few benchmarks in the distribution ubin directory which can be run either standalone or through the Makefile. 🛠️

⭐ make compare ⭐

Runs all three of the following tests. 🎯

⭐ make speeds ⭐

Runs ubin/cmp_speeds.pl to compare the speeds of various UUID versions. 🏎️

⭐ make styles ⭐

Runs ubin/cmp_styles.pl to compare different UUID calling styles. 💃

⭐ make persist ⭐

Runs ubin/cmp_persist.pl to compare different deferral values for persistent state. 🕰️

This software is Copyright (c) 2014-2024 by Rick Myers. 💖

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

Details of this license can be found within the 'LICENSE' text file. 📜

🦋 AUTHOR 🦋

Current maintainer:

Rick Myers <jrm@cpan.org>.

Authors and/or previous maintainers:

Lukas Zapletal <lzap@cpan.org>

Joseph N. Hall <joseph.nathan.hall@gmail.com>

Colin Faber <cfaber@clusterfs.com>

Peter J. Braam <braam@mountainviewdata.com>

🌸 CONTRIBUTORS 🌸

  • David E. Wheeler
  • William Faulk
  • gregor herrmann
  • Slaven Rezic
  • twata
  • Christopher Rasch-Olsen Raa
  • Petr Pisar

✨ SEE ALSO ✨

💖 And that’s the whole UUID(3) page, bestie — footer says perl v5.42.0, dated 2024-06-23. Byeeee! 👑✨

📦 where this page comes from