NAME
UUID - Universally Unique Identifier library for Perl
SYNOPSIS
use UUID qw(uuid uuid1 uuid4); # see EXPORTS
$str = uuid(); # new stringified UUID; prefer v4
$str = uuid1(); # new stringified UUID; always v1
$str = uuid4(); # new stringified UUID; always v4
UUID::generate($bin); # new binary UUID; prefer v4
UUID::generate_v1($bin); # new binary UUID; always v1
UUID::generate_v4($bin); # new binary UUID; always v4
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 variantDESCRIPTION
The UUID library is used to generate unique identifiers for objects that may be accessible beyond the local system. For instance, they could be used to generate unique HTTP cookies across multiple web servers without communication between the servers, and without 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).
All generated UUIDs are either version 1 or version 4. And all are variant 1, meaning compliant with the OSF DCE standard as described in RFC4122.
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.
Not very Perlish, is it? It's been like that for a long time now, 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-e89a1dcf8f0fOr, in terms of printf(3) format:
"%08x-%04x-%04x-%04x-%012x"The binary form is simply a packed 16 byte binary value.
clear( $uuid )
Sets $uuid equal to the value of the NULL UUID.
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.
However, if either operand is not a UUID, falls back to a simple string comparison returning similar values.
copy( $dst, $src )
Copies the binary $src UUID to $dst.
If $src isn't a UUID, $dst is set to the NULL UUID.
generate( $uuid )
Generates a new version 4 binary UUID based on high quality randomness from /dev/urandom or /dev/random, if available.
If not, a new version 1 binary UUID is returned.
The previous content of $uuid, if any, is lost.
generate_random( $uuid )
Generates a new version 4 binary UUID even if a high-quality random number generator (e.g., /dev/urandom) is not available, in which case a pseudo-random generator is used.
Note that the use of a pseudo-random generator may compromise the uniqueness of UUIDs generated in this fashion.
If /dev/urandom and/or /dev/random are present, the system calls get_random() and/or get_entropy() are used first, if available.
If the system calls are not available, randomness is read directly from the random devices, preferring /dev/urandom but falling back to /dev/random in non-blocking mode.
generate_time( $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.
This algorithm used to be the default for generating UUIDs, but because of privacy concerns, the generate() function only uses it if a high-quality source of randomness is not available.
generate_v1( $uuid )
Alias for generate_time().
generate_v4( $uuid )
Alias for generate_random().
is_null( $uuid )
Compares the value of $uuid to the NULL UUID.
Returns 1 if NULL, and 0 otherwise.
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.
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 type 1 UUIDs. Values returned from other types range from non-standardized to totally random.
type( $uuid )
Returns the type of binary $uuid.
This module only generates type 1 (time) and type 4 (random) UUIDs, but others may be found in the wild.
Known types: 1 a.k.a. Version 1 - date/time and MAC address 2 a.k.a. Version 2 - date/time and MAC address, security version 3 a.k.a. Version 3 - namespace based, MD5 hash 4 a.k.a. Version 4 - random 5 a.k.a. Version 5 - namespace based, SHA-1 hash
unparse( $uuid, $string )
Converts the binary UUID in $uuid to string format and returns in $string. The previous content of $string, if any, is lost.
Prior to version 0.32, casing of the return value was system-dependent. Later versions are lower case, per RFC4122.
unparse_lower( $uuid, $string )
Same as unparse().
unparse_upper( $uuid, $string )
Same as unparse() but $string is forced to upper case.
uuid()
Creates a new string format UUID and returns it in a more Perlish way.
Functionally the equivalent of calling generate() and then unparse(), but throwing away the intermediate binary UUID.
uuid1()
Same as uuid() but always version 1.
uuid4()
Same as uuid() but always version 4.
variant( $uuid )
Returns the variant of binary $uuid.
This module only generates variant 1 UUIDs, but others may be found in the wild.
Known variants:
0 NCS
1 DCE
2 Microsoft
3 OtherMAINTAINING STATE
Internal state is optionally maintained for version 1 UUIDs via a file designated by the :persist export tag (see EXPORTS), if the path exists and the user running the process has read/write permission.
If the file doesn't exist, it is created if the directory path exists.
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.
If :persist is not used, time resets will still be detected while the module is loaded and handled accordingly. And since startup in this case is randomized anyway, the chance of overlap is low but still exists. The randomized clock_seq field is 14 bits wide.
Note that use of this feature incurs a serious performance penalty, upwards of 90% on tested platforms.
Note too that use of a random MAC greatly reduces the chance of overlap. The randomized fields total 62 bits at start.
EXPORTS
None by default. All functions may be imported in the usual manner, either individually or all at once using the :all tag.
:mac=mode
The MAC address used for v1 UUIDS is forced to always be random in one of two modes:
random The MAC address is generated once at startup and used throughout the lifetime of the process. This is the default if the 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 version 1 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!
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.
COPYRIGHT AND LICENSE
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
SEE ALSO
RFC4122
uuid(3), uuid_clear(3), uuid_compare(3), uuid_copy(3), uuid_generate(3), uuid_is_null(3), uuid_parse(3), uuid_unparse(3), perl(1).