NAME
UUID - Universally Unique Identifier library for Perl
SYNOPSIS
use UUID 'uuid';
$string = uuid(); # generate UUID string, prefer v4, fallback v1
$string = uuid1(); # generate UUID string, always v1
$string = uuid4(); # generate UUID string, always v4
UUID::generate($uuid); # new binary UUID; prefer random
UUID::generate_random($uuid); # new binary UUID; use random
UUID::generate_time($uuid); # new binary UUID; use time
UUID::unparse($uuid, $string); # stringify $uuid; system casing
UUID::unparse_lower($uuid, $string); # force lowercase stringify
UUID::unparse_upper($uuid, $string); # force uppercase stringify
$rc = UUID::parse($string, $uuid); # map string to UUID; -1 on error
UUID::copy($dst, $src); # copy binary UUID from $src to $dst
UUID::compare($uuid1, $uuid2); # compare binary UUIDs
UUID::clear( $uuid ); # set binary UUID to NULL
UUID::is_null( $uuid ); # compare binary UUID to NULL
UUID::type( $uuid ); # return UUID type
UUID::variant( $uuid ); # return UUID variant
UUID::time( $uuid ); # return internal UUID timeDESCRIPTION
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) utility uuidgen.
All generated UUIDs are either type 1 from UUID::generate_time(), or type 4 from UUID::generate_random(). And all are variant 1, meaning compliant with the OSF DCE standard as described in RFC4122.
FUNCTIONS
Most of the UUID functions expose the 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 though, so not very 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.
copy( $dst, $src )
Copies the binary $src UUID to $dst.
If $src isn't a UUID, $dst is set to 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.
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 which uses the current time and the local ethernet MAC address, if available.
If the MAC address is not available, it is replaced randomly from best source with the multicast bit set to avoid conflict with addresses returned from network cards.
This algorithm used to be the default used to generate UUIDs, but because of inclusion of the ethernet MAC address, it can leak information about where the UUID was generated.
This can cause privacy problems in some applications, so the generate() function only uses this algorithm if a high-quality source of randomness is not available.
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 OtherUUID LIBRARY
Prior to version 0.32, UUID required libuuid or similar be installed first. This is no longer the case. UUID now builds against a bundled copy of the e2fsprogs UUID code.
EXPORTS
None by default. All functions may be imported in the usual manner, either individually or all at once using the ":all" tag.
THREAD SAFETY
This module is believed to be thread safe.
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).