.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "UUID::Tiny 3pm" .TH UUID::Tiny 3pm "2018-03-30" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" UUID::Tiny \- Pure Perl UUID Support With Functional Interface .SH "VERSION" .IX Header "VERSION" Version 1.04 .SH "SYNOPSIS" .IX Header "SYNOPSIS" Create version 1, 3, 4 and 5 UUIDs: .PP .Vb 1 \& use UUID::Tiny \*(Aq:std\*(Aq; \& \& 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, \*(Aqcaugustin.de\*(Aq); \& 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, \*(Aqcaugustin.de\*(Aq); \& \& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" UUID::Tiny is a lightweight, low dependency Pure Perl module for \s-1UUID\s0 creation and testing. This module provides the creation of version 1 time based UUIDs (using random multicast \s-1MAC\s0 addresses), version 3 \s-1MD5\s0 based UUIDs, version 4 random UUIDs, and version 5 \s-1SHA\-1\s0 based UUIDs. .PP \&\s-1ATTENTION\s0! UUID::Tiny uses Perl's \f(CW\*(C`rand()\*(C'\fR to create the basic random numbers, so the created v4 UUIDs are \fBnot\fR cryptographically strong! .PP No fancy \s-1OO\s0 interface, no plethora of different \s-1UUID\s0 representation formats and transformations \- just string and binary. Conversion, test and time functions equally accept UUIDs and \s-1UUID\s0 strings, so don't bother to convert UUIDs for them! .PP Continuing with 1.0x versions all constants and public functions are exported by default, but this will change in the future (see below). .PP UUID::Tiny deliberately uses a minimal functional interface for \s-1UUID\s0 creation (and conversion/testing), because in this case \s-1OO\s0 looks like overkill to me and makes the creation and use of UUIDs unnecessarily complicated. .PP If you need raw performance for \s-1UUID\s0 creation, or the real \s-1MAC\s0 address in version 1 UUIDs, or an \s-1OO\s0 interface, and if you can afford module compilation and installation on the target system, then better look at other \s-1CPAN UUID\s0 modules like Data::UUID. .PP This module is \*(L"fork safe\*(R", especially for random UUIDs (it works around Perl's \fIrand()\fR problem when forking processes). .PP This module is currently \fBnot\fR \*(L"thread safe\*(R". 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! .SH "DEPENDENCIES" .IX Header "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: .PP .Vb 6 \& 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 .Ve .PP 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. .SH "ATTENTION! NEW STANDARD INTERFACE" .IX Header "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. .PP While the 1.0x versions will continue to export the old, \*(L"legacy\*(R" interface on default, the future standard interface is available using the \f(CW\*(C`:std\*(C'\fR tag on import from version 1.02 on: .PP .Vb 2 \& use UUID::Tiny \*(Aq:std\*(Aq; \& my $md5_uuid = create_uuid(UUID_MD5, $str); .Ve .PP In preparation for future version of UUID::Tiny you have to use the \&\f(CW\*(C`:legacy\*(C'\fR tag if you want to stay with the version 1.0 interface: .PP .Vb 2 \& use UUID::Tiny \*(Aq:legacy\*(Aq; \& my $md5_uuid = create_UUID(UUID_V3, $str); .Ve .SH "CONSTANTS" .IX Header "CONSTANTS" .IP "\fB\s-1NIL UUID\s0\fR" 4 .IX Item "NIL UUID" This module provides the \s-1NIL UUID\s0 (shown with its string representation): .Sp .Vb 1 \& UUID_NIL: \*(Aq00000000\-0000\-0000\-0000\-000000000000\*(Aq .Ve .IP "\fBPre-defined Namespace UUIDs\fR" 4 .IX Item "Pre-defined Namespace UUIDs" This module provides the common pre-defined namespace UUIDs (shown with their string representation): .Sp .Vb 4 \& UUID_NS_DNS: \*(Aq6ba7b810\-9dad\-11d1\-80b4\-00c04fd430c8\*(Aq \& UUID_NS_URL: \*(Aq6ba7b811\-9dad\-11d1\-80b4\-00c04fd430c8\*(Aq \& UUID_NS_OID: \*(Aq6ba7b812\-9dad\-11d1\-80b4\-00c04fd430c8\*(Aq \& UUID_NS_X500: \*(Aq6ba7b814\-9dad\-11d1\-80b4\-00c04fd430c8\*(Aq .Ve .IP "\fB\s-1UUID\s0 versions\fR" 4 .IX Item "UUID versions" This module provides the \s-1UUID\s0 version numbers as constants: .Sp .Vb 4 \& UUID_V1 \& UUID_V3 \& UUID_V4 \& UUID_V5 .Ve .Sp With \f(CW\*(C`use UUID::Tiny \*(Aq:std\*(Aq;\*(C'\fR you get additional, \*(L"speaking\*(R" constants: .Sp .Vb 4 \& UUID_TIME \& UUID_MD5 \& UUID_RANDOM \& UUID_SHA1 .Ve .IP "\fB\s-1UUID_SHA1_AVAIL\s0\fR" 4 .IX Item "UUID_SHA1_AVAIL" .Vb 1 \& my $uuid = create_UUID( UUID_SHA1_AVAIL? UUID_V5 : UUID_V3, $str ); .Ve .Sp This function returns 1 if a module to create \s-1SHA\-1\s0 digests could be loaded, 0 otherwise. .Sp 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 \&\f(CW\*(C`create_UUID()\*(C'\fR and \f(CW\*(C`create_UUID_as_string()\*(C'\fR die when trying to create an \&\s-1SHA\-1\s0 based \s-1UUID\s0 without an appropriate module available. .SH "FUNCTIONS" .IX Header "FUNCTIONS" All public functions are exported by default (they should not collide with other functions). .PP \&\f(CW\*(C`create_UUID()\*(C'\fR creates standard binary UUIDs in network byte order (\s-1MSB\s0 first), \f(CW\*(C`create_UUID_as_string()\*(C'\fR creates the standard string representation of UUIDs. .PP All query and test functions (except \f(CW\*(C`is_UUID_string\*(C'\fR) accept both representations. .IP "\fB\f(BIcreate_UUID()\fB\fR, \fB\f(BIcreate_uuid()\fB\fR (:std)" 4 .IX Item "create_UUID(), create_uuid() (:std)" .Vb 7 \& 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); .Ve .Sp Creates a binary \s-1UUID\s0 in network byte order (\s-1MSB\s0 first). For v3 and v5 UUIDs a \&\f(CW\*(C`SCALAR\*(C'\fR (normally a string), \f(CW\*(C`GLOB\*(C'\fR (\*(L"classic\*(R" file handle) or \f(CW\*(C`IO\*(C'\fR object (i.e. \f(CW\*(C`IO::File\*(C'\fR) can be used; files have to be opened for reading. .Sp 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 \s-1UUID_NIL\s0 as the namespace \s-1UUID,\s0 because no \*(L"real name\*(R" is used; \s-1UUID_NIL\s0 is used by default if a namespace \s-1UUID\s0 is missing (only 2 arguments are used). .IP "\fB\f(BIcreate_UUID_as_string()\fB\fR, \fB\f(BIcreate_uuid_as_string()\fB\fR (:std)" 4 .IX Item "create_UUID_as_string(), create_uuid_as_string() (:std)" Similar to \f(CW\*(C`create_UUID\*(C'\fR, but creates a \s-1UUID\s0 string. .IP "\fB\f(BIis_UUID_string()\fB\fR, \fB\f(BIis_uuid_string()\fB\fR (:std)" 4 .IX Item "is_UUID_string(), is_uuid_string() (:std)" .Vb 1 \& my $bool = is_UUID_string($str); .Ve .IP "\fB\f(BIUUID_to_string()\fB\fR, \fB\f(BIuuid_to_string()\fB\fR (:std)" 4 .IX Item "UUID_to_string(), uuid_to_string() (:std)" .Vb 1 \& my $uuid_str = UUID_to_string($uuid); .Ve .Sp This function returns \f(CW$uuid\fR unchanged if it is a \s-1UUID\s0 string already. .IP "\fB\f(BIstring_to_UUID()\fB\fR, \fB\f(BIstring_to_uuid()\fB\fR (:std)" 4 .IX Item "string_to_UUID(), string_to_uuid() (:std)" .Vb 1 \& my $uuid = string_to_UUID($uuid_str); .Ve .Sp This function returns \f(CW$uuid_str\fR unchanged if it is a \s-1UUID\s0 already. .Sp In addition to the standard \s-1UUID\s0 string representation and its \s-1URN\s0 forms (starting with \f(CW\*(C`urn:uuid:\*(C'\fR or \f(CW\*(C`uuid:\*(C'\fR), this function accepts 32 digit hex strings, variants with different positions of \f(CW\*(C`\-\*(C'\fR and Base64 encoded UUIDs. .Sp Throws an exception if string can't be interpreted as a \s-1UUID.\s0 .Sp If you want to make sure to have a \*(L"pure\*(R" standard \s-1UUID\s0 representation, check with \f(CW\*(C`is_UUID_string\*(C'\fR! .IP "\fB\f(BIversion_of_UUID()\fB\fR, \fB\f(BIversion_of_uuid()\fB\fR (:std)" 4 .IX Item "version_of_UUID(), version_of_uuid() (:std)" .Vb 1 \& my $version = version_of_UUID($uuid); .Ve .Sp This function accepts binary and string UUIDs. .IP "\fB\f(BItime_of_UUID()\fB\fR, \fB\f(BItime_of_uuid()\fB\fR (:std)" 4 .IX Item "time_of_UUID(), time_of_uuid() (:std)" .Vb 1 \& my $uuid_time = time_of_UUID($uuid); .Ve .Sp This function accepts UUIDs and \s-1UUID\s0 strings. Returns the time as a floating point value, so use \f(CW\*(C`int()\*(C'\fR to get a \f(CW\*(C`time()\*(C'\fR compatible value. .Sp Returns \f(CW\*(C`undef\*(C'\fR if the \s-1UUID\s0 is not version 1. .IP "\fB\f(BIclk_seq_of_UUID()\fB\fR, \fB\f(BIclk_seq_of_uuid()\fB\fR (:std)" 4 .IX Item "clk_seq_of_UUID(), clk_seq_of_uuid() (:std)" .Vb 1 \& my $uuid_clk_seq = clk_seq_of_UUID($uuid); .Ve .Sp This function accepts UUIDs and \s-1UUID\s0 strings. Returns the clock sequence for a version 1 \s-1UUID.\s0 Returns \f(CW\*(C`undef\*(C'\fR if \s-1UUID\s0 is not version 1. .IP "\fB\f(BIequal_UUIDs()\fB\fR, \fB\f(BIequal_uuids()\fB\fR (:std)" 4 .IX Item "equal_UUIDs(), equal_uuids() (:std)" .Vb 1 \& my $bool = equal_UUIDs($uuid1, $uuid2); .Ve .Sp Returns true if the provided UUIDs are equal. Accepts UUIDs and \s-1UUID\s0 strings (can be mixed). .SH "DISCUSSION" .IX Header "DISCUSSION" .IP "\fBWhy version 1 only with random multi-cast \s-1MAC\s0 addresses?\fR" 4 .IX Item "Why version 1 only with random multi-cast MAC addresses?" The random multi-cast \s-1MAC\s0 address gives privacy, and getting the real \s-1MAC\s0 address with Perl is really dirty (and slow); .IP "\fBShould version 3 or version 5 be used?\fR" 4 .IX Item "Should version 3 or version 5 be used?" Using \s-1SHA\-1\s0 reduces the probability of collisions and provides a better \&\*(L"randomness\*(R" of the resulting \s-1UUID\s0 compared to \s-1MD5.\s0 Version 5 is recommended in \s-1RFC 4122\s0 if backward compatibility is not an issue. .Sp Using \s-1MD5\s0 (version 3) has a better performance. This could be important with creating UUIDs from file content rather than names. .SH "UUID DEFINITION" .IX Header "UUID DEFINITION" See \s-1RFC 4122\s0 () for technical details on UUIDs. Wikipedia gives a more palatable description at . .SH "AUTHOR" .IX Header "AUTHOR" Christian Augustin, \f(CW\*(C`\*(C'\fR .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Some of this code is based on UUID::Generator by \s-1ITO\s0 Nobuaki . But that module is announced to be marked as \&\*(L"deprecated\*(R" in the future and it is much too complicated for my liking. .PP So I decided to reduce it to the necessary parts and to re-implement those parts with a functional interface ... .PP Jesse Vincent, \f(CW\*(C`\*(C'\fR, improved version 1.02 with his tips and a heavy refactoring. .PP 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. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-uuid\-tiny at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc UUID::Tiny .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Kudos to \s-1ITO\s0 Nobuaki 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 \s-1RFC\s0 texts and C codes ... .PP Thanks to Jesse Vincent (\f(CW\*(C`\*(C'\fR) for his feedback, tips and refactoring! .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2009, 2010, 2013 Christian Augustin, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP \&\s-1ITO\s0 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 ).