GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  UUID::TINY (3)

.ds Aq ’

NAME

UUID::Tiny - Pure Perl UUID Support With Functional Interface

CONTENTS

VERSION

Version 1.04

SYNOPSIS

Create version 1, 3, 4 and 5 UUIDs:



    use UUID::Tiny :std;

    my $v1_mc_UUID      = create_uuid();
    my $v1_mc_UUID_2    = create_uuid(UUID_V1);
    my $v1_mc_UUID_3    = create_uuid(UUID_TIME);
    my $v3_md5_UUID     = create_uuid(UUID_V3, $str);
    my $v3_md5_UUID_2   = create_uuid(UUID_MD5, UUID_NS_DNS, caugustin.de);
    my $v4_rand_UUID    = create_uuid(UUID_V4);
    my $v4_rand_UUID_2  = create_uuid(UUID_RANDOM);
    my $v5_sha1_UUID    = create_uuid(UUID_V5, $str);
    my $v5_with_NS_UUID = create_uuid(UUID_SHA1, UUID_NS_DNS, caugustin.de);

    my $v1_mc_UUID_string  = create_uuid_as_string(UUID_V1);
    my $v3_md5_UUID_string = uuid_to_string($v3_md5_UUID);

    if ( version_of_uuid($v1_mc_UUID) == 1   ) { ... };
    if ( version_of_uuid($v5_sha1_UUID) == 5 ) { ... };
    if ( is_uuid_string($v1_mc_UUID_string)  ) { ... };
    if ( equal_uuids($uuid1, $uuid2)         ) { ... };

    my $uuid_time    = time_of_uuid($v1_mc_UUID);
    my $uuid_clk_seq = clk_seq_of_uuid($v1_mc_UUID);



DESCRIPTION

UUID::Tiny is a lightweight, low dependency Pure Perl module for UUID creation and testing. This module provides the creation of version 1 time based UUIDs (using random multicast MAC addresses), version 3 MD5 based UUIDs, version 4 random UUIDs, and version 5 SHA-1 based UUIDs.

ATTENTION! UUID::Tiny uses Perl’s rand() to create the basic random numbers, so the created v4 UUIDs are <B>notB> cryptographically strong!

No fancy OO interface, no plethora of different UUID representation formats and transformations - just string and binary. Conversion, test and time functions equally accept UUIDs and UUID strings, so don’t bother to convert UUIDs for them!

Continuing with 1.0x versions all constants and public functions are exported by default, but this will change in the future (see below).

UUID::Tiny deliberately uses a minimal functional interface for UUID creation (and conversion/testing), because in this case OO looks like overkill to me and makes the creation and use of UUIDs unnecessarily complicated.

If you need raw performance for UUID creation, or the real MAC address in version 1 UUIDs, or an OO interface, and if you can afford module compilation and installation on the target system, then better look at other CPAN UUID modules like Data::UUID.

This module is fork safe, especially for random UUIDs (it works around Perl’s rand() problem when forking processes).

This module is currently <B>notB> thread safe. Even though I’ve incorporated some changes proposed by Michael G. Schwern (thanks!), Digest::MD5 and Digest::SHA seem so have trouble with threads. There is a test file for threads, but it is de-activated. So use at your own risk!

DEPENDENCIES

This module should run from Perl 5.8 up and uses mostly standard (5.8 core) modules for its job. No compilation or installation required. These are the modules UUID::Tiny depends on:



    Carp
    Digest::MD5   Perl 5.8 core
    Digest::SHA   Perl 5.10 core (or Digest::SHA1, or Digest::SHA::PurePerl)
    MIME::Base64  Perl 5.8 core
    Time::HiRes   Perl 5.8 core
    POSIX         Perl 5.8 core



If you are using this module on a Perl prior to 5.10 and you don’t have Digest::SHA1 installed, you can use Digest::SHA::PurePerl instead.

ATTENTION! NEW STANDARD INTERFACE

After some debate I’m convinced that it is more Perlish (and far easier to write) to use all-lowercase function names - without exceptions. And that it is more polite to export symbols only on demand.

While the 1.0x versions will continue to export the old, legacy interface on default, the future standard interface is available using the :std tag on import from version 1.02 on:



    use UUID::Tiny :std;
    my $md5_uuid = create_uuid(UUID_MD5, $str);



In preparation for future version of UUID::Tiny you have to use the :legacy tag if you want to stay with the version 1.0 interface:



    use UUID::Tiny :legacy;
    my $md5_uuid = create_UUID(UUID_V3, $str);



CONSTANTS

<B>NIL UUIDB> This module provides the NIL UUID (shown with its string representation):



    UUID_NIL: 00000000-0000-0000-0000-000000000000



<B>Pre-defined Namespace UUIDsB> This module provides the common pre-defined namespace UUIDs (shown with their string representation):



    UUID_NS_DNS:  6ba7b810-9dad-11d1-80b4-00c04fd430c8
    UUID_NS_URL:  6ba7b811-9dad-11d1-80b4-00c04fd430c8
    UUID_NS_OID:  6ba7b812-9dad-11d1-80b4-00c04fd430c8
    UUID_NS_X500: 6ba7b814-9dad-11d1-80b4-00c04fd430c8



<B>UUID versionsB> This module provides the UUID version numbers as constants:



    UUID_V1
    UUID_V3
    UUID_V4
    UUID_V5



With use UUID::Tiny :std; you get additional, speaking constants:



    UUID_TIME
    UUID_MD5
    UUID_RANDOM
    UUID_SHA1



<B>UUID_SHA1_AVAILB>


    my $uuid = create_UUID( UUID_SHA1_AVAIL? UUID_V5 : UUID_V3, $str );



This function returns 1 if a module to create SHA-1 digests could be loaded, 0 otherwise.

UUID::Tiny (since version 1.02) tries to load Digest::SHA, Digest::SHA1 or Digest::SHA::PurePerl, but does not die if none of them is found. Instead create_UUID() and create_UUID_as_string() die when trying to create an SHA-1 based UUID without an appropriate module available.

FUNCTIONS

All public functions are exported by default (they should not collide with other functions).

create_UUID() creates standard binary UUIDs in network byte order (MSB first), create_UUID_as_string() creates the standard string representation of UUIDs.

All query and test functions (except is_UUID_string) accept both representations.
<B>B>create_UUID()<B>B>, <B>B>create_uuid()<B>B> (:std)


    my $v1_mc_UUID   = create_UUID();
    my $v1_mc_UUID   = create_UUID(UUID_V1);
    my $v3_md5_UUID  = create_UUID(UUID_V3, $ns_uuid, $name_or_filehandle);
    my $v3_md5_UUID  = create_UUID(UUID_V3, $name_or_filehandle);
    my $v4_rand_UUID = create_UUID(UUID_V4);
    my $v5_sha1_UUID = create_UUID(UUID_V5, $ns_uuid, $name_or_filehandle);
    my $v5_sha1_UUID = create_UUID(UUID_V5, $name_or_filehandle);



Creates a binary UUID in network byte order (MSB first). For v3 and v5 UUIDs a SCALAR (normally a string), GLOB (classic file handle) or IO object (i.e. IO::File) can be used; files have to be opened for reading.

I found no hint if and how UUIDs should be created from file content. It seems to be undefined, but it is useful - so I would suggest to use UUID_NIL as the namespace UUID, because no real name is used; UUID_NIL is used by default if a namespace UUID is missing (only 2 arguments are used).

<B>B>create_UUID_as_string()<B>B>, <B>B>create_uuid_as_string()<B>B> (:std) Similar to create_UUID, but creates a UUID string.
<B>B>is_UUID_string()<B>B>, <B>B>is_uuid_string()<B>B> (:std)


    my $bool = is_UUID_string($str);



<B>B>UUID_to_string()<B>B>, <B>B>uuid_to_string()<B>B> (:std)


    my $uuid_str = UUID_to_string($uuid);



This function returns $uuid unchanged if it is a UUID string already.

<B>B>string_to_UUID()<B>B>, <B>B>string_to_uuid()<B>B> (:std)


    my $uuid = string_to_UUID($uuid_str);



This function returns $uuid_str unchanged if it is a UUID already.

In addition to the standard UUID string representation and its URN forms (starting with urn:uuid: or uuid:), this function accepts 32 digit hex strings, variants with different positions of - and Base64 encoded UUIDs.

Throws an exception if string can’t be interpreted as a UUID.

If you want to make sure to have a pure standard UUID representation, check with is_UUID_string!

<B>B>version_of_UUID()<B>B>, <B>B>version_of_uuid()<B>B> (:std)


    my $version = version_of_UUID($uuid);



This function accepts binary and string UUIDs.

<B>B>time_of_UUID()<B>B>, <B>B>time_of_uuid()<B>B> (:std)


    my $uuid_time = time_of_UUID($uuid);



This function accepts UUIDs and UUID strings. Returns the time as a floating point value, so use int() to get a time() compatible value.

Returns undef if the UUID is not version 1.

<B>B>clk_seq_of_UUID()<B>B>, <B>B>clk_seq_of_uuid()<B>B> (:std)


    my $uuid_clk_seq = clk_seq_of_UUID($uuid);



This function accepts UUIDs and UUID strings. Returns the clock sequence for a version 1 UUID. Returns undef if UUID is not version 1.

<B>B>equal_UUIDs()<B>B>, <B>B>equal_uuids()<B>B> (:std)


    my $bool = equal_UUIDs($uuid1, $uuid2);



Returns true if the provided UUIDs are equal. Accepts UUIDs and UUID strings (can be mixed).

DISCUSSION

<B>Why version 1 only with random multi-cast MAC addresses?B> The random multi-cast MAC address gives privacy, and getting the real MAC address with Perl is really dirty (and slow);
<B>Should version 3 or version 5 be used?B> Using SHA-1 reduces the probability of collisions and provides a better randomness of the resulting UUID compared to MD5. Version 5 is recommended in RFC 4122 if backward compatibility is not an issue.

Using MD5 (version 3) has a better performance. This could be important with creating UUIDs from file content rather than names.

UUID DEFINITION

See RFC 4122 (<http://www.ietf.org/rfc/rfc4122.txt>) for technical details on UUIDs. Wikipedia gives a more palatable description at <http://en.wikipedia.org/wiki/Universally_unique_identifier>.

AUTHOR

Christian Augustin, <mail at caugustin.de>

CONTRIBUTORS

Some of this code is based on UUID::Generator by ITO Nobuaki <banb@cpan.org>. But that module is announced to be marked as deprecated in the future and it is much too complicated for my liking.

So I decided to reduce it to the necessary parts and to re-implement those parts with a functional interface ...

Jesse Vincent, <jesse at bestpractical.com>, improved version 1.02 with his tips and a heavy refactoring.

Michael G. Schwern provided a patch for better thread support (as far as UUID::Tiny can be improved itself) that is incorporated in version 1.04.

BUGS

Please report any bugs or feature requests to bug-uuid-tiny at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=UUID-Tiny>. I will be notified, and then you’ll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.



    perldoc UUID::Tiny



You can also look for information at:
o RT: CPAN’s request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=UUID-Tiny>

o AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/UUID-Tiny>

o CPAN Ratings

<http://cpanratings.perl.org/d/UUID-Tiny>

o Search CPAN

<http://search.cpan.org/dist/UUID-Tiny/>

ACKNOWLEDGEMENTS

Kudos to ITO Nobuaki <banb@cpan.org> for his UUID::Generator::PurePerl module! My work is based on his code, and without it I would’ve been lost with all those incomprehensible RFC texts and C codes ...

Thanks to Jesse Vincent (<jesse at bestpractical.com>) for his feedback, tips and refactoring!

COPYRIGHT & LICENSE

Copyright 2009, 2010, 2013 Christian Augustin, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

ITO Nobuaki has very graciously given me permission to take over copyright for the portions of code that are copied from or resemble his work (see rt.cpan.org #53642 <https://rt.cpan.org/Public/Bug/Display.html?id=53642>).

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 UUID::TINY (3) 2013-08-19

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.