.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 3pm" .TH UUID 3pm "2016-10-11" "perl v5.24.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 \- DCE compatible Universally Unique Identifier library for Perl .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use UUID \*(Aquuid\*(Aq; \& \& $string = uuid(); # generate stringified UUID \& \& 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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1UUID\s0 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 \s-1HTTP\s0 cookies across multiple web servers without communication between the servers, and without fear of a name clash. .PP 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 (\s-1OSF\s0) Distributed Computing Environment (\s-1DCE\s0) utility uuidgen. .SH "FUNCTIONS" .IX Header "FUNCTIONS" Most of the \s-1UUID\s0 functions expose the underlying \fIlibuuid\fR C interface rather directly. That is, many return their values in their parameters and nothing else. .PP Not very Perlish, is it? It's been like that for a long time though, so not very likely to change any time soon. .PP All take or return UUIDs in either binary or string format. The string format resembles the following: .PP .Vb 1 \& 1b4e28ba\-2fa1\-11d2\-883f\-0016d3cca427 .Ve .PP Or, in terms of \fIprintf\fR\|(3) format: .PP .Vb 1 \& "%08x\-%04x\-%04x\-%04x\-%012x" .Ve .PP The binary format is simply a packed 16 byte binary value. .SS "\fBgenerate(\fP \fI\fP\f(CI$uuid\fP\fI\fP \fB)\fP" .IX Subsection "generate( $uuid )" Generates a new binary \s-1UUID\s0 based on high quality randomness from \&\fI/dev/urandom\fR, if available. .PP Alternately, the current time, the local ethernet \s-1MAC\s0 address (if available), and random data generated using a pseudo-random generator are used. .PP The previous content of \fI\f(CI$uuid\fI\fR, if any, is lost. .SS "\fBgenerate_random(\fP \fI\fP\f(CI$uuid\fP\fI\fP \fB)\fP" .IX Subsection "generate_random( $uuid )" Generates a new binary \s-1UUID\s0 but forces the use of the all-random algorithm, even if a high-quality random number generator (i.e., \&\fI/dev/urandom\fR) is not available, in which case a pseudo-random generator is used. .PP Note that the use of a pseudo-random generator may compromise the uniqueness of UUIDs generated in this fashion. .SS "\fBgenerate_time(\fP \fI\fP\f(CI$uuid\fP\fI\fP \fB)\fP" .IX Subsection "generate_time( $uuid )" Generates a new binary \s-1UUID\s0 but forces the use of the alternative algorithm which uses the current time and the local ethernet \s-1MAC\s0 address (if available). .PP This algorithm used to be the default one used to generate UUIDs, but because of the use of the ethernet \s-1MAC\s0 address, it can leak information about when and where the \s-1UUID\s0 was generated. .PP This can cause privacy problems in some applications, so the \fB\f(BIgenerate()\fB\fR function only uses this algorithm if a high-quality source of randomness is not available. .SS "\fBunparse(\fP \fI\fP\f(CI$uuid\fP\fI\fP\fB,\fP \fI\fP\f(CI$string\fP\fI\fP \fB)\fP" .IX Subsection "unparse( $uuid, $string )" Converts the binary \s-1UUID\s0 in \fI\f(CI$uuid\fI\fR to string format and returns in \&\fI\f(CI$string\fI\fR. The previous content of \fI\f(CI$string\fI\fR, if any, is lost. .PP The case of the hex digits returned may be upper or lower case, and is dependent on the system-dependent local default. .SS "\fBunparse_lower(\fP \fI\fP\f(CI$uuid\fP\fI\fP\fB,\fP \fI\fP\f(CI$string\fP\fI\fP \fB)\fP" .IX Subsection "unparse_lower( $uuid, $string )" Same as \fB\f(BIunparse()\fB\fR but \fI\f(CI$string\fI\fR is forced to lower case. .SS "\fBunparse_upper(\fP \fI\fP\f(CI$uuid\fP\fI\fP\fB,\fP \fI\fP\f(CI$string\fP\fI\fP \fB)\fP" .IX Subsection "unparse_upper( $uuid, $string )" Same as \fB\f(BIunparse()\fB\fR but \fI\f(CI$string\fI\fR is forced to upper case. .SS "\fB\fP\f(CB$rc\fP\fB = parse(\fP \fI\fP\f(CI$string\fP\fI\fP\fB,\fP \fI\fP\f(CI$uuid\fP\fI\fP \fB)\fP" .IX Subsection "$rc = parse( $string, $uuid )" Converts the string format \s-1UUID\s0 in \fI\f(CI$string\fI\fR to binary and returns in \&\fI\f(CI$uuid\fI\fR. The previous content of \fI\f(CI$uuid\fI\fR, if any, is lost. .PP Returns 0 on success and \-1 on failure. Additionally on failure, the content of \fI\f(CI$uuid\fI\fR is unchanged. .SS "\fBclear(\fP \fI\fP\f(CI$uuid\fP\fI\fP \fB)\fP" .IX Subsection "clear( $uuid )" Sets \fI\f(CI$uuid\fI\fR equal to the value of the \s-1NULL UUID.\s0 .SS "\fBis_null(\fP \fI\fP\f(CI$uuid\fP\fI\fP \fB)\fP" .IX Subsection "is_null( $uuid )" Compares the value of \fI\f(CI$uuid\fI\fR to the \s-1NULL UUID.\s0 .PP Returns 1 if \s-1NULL,\s0 and 0 otherwise. .SS "\fBcopy(\fP \fI\fP\f(CI$dst\fP\fI\fP\fB,\fP \fI\fP\f(CI$src\fP\fI\fP \fB)\fP" .IX Subsection "copy( $dst, $src )" Copies the binary \fI\f(CI$src\fI\fR \s-1UUID\s0 to \fI\f(CI$dst\fI\fR. .PP If \fI\f(CI$src\fI\fR isn't a \s-1UUID, \s0\fI\f(CI$dst\fI\fR is set to the \s-1NULL UUID.\s0 .SS "\fBcompare(\fP \fI\fP\f(CI$uuid1\fP\fI\fP\fB,\fP \fI\fP\f(CI$uuid2\fP\fI\fP \fB)\fP" .IX Subsection "compare( $uuid1, $uuid2 )" Compares two binary UUIDs. .PP Returns an integer less than, equal to, or greater than zero if \&\fI\f(CI$uuid1\fI\fR is less than, equal to, or greater than \fI\f(CI$uuid2\fI\fR. .PP However, if either operand is not a \s-1UUID,\s0 falls back to a simple string comparison returning similar values. .SS "\fB\fP\fI\fP\f(CI$string\fP\fI\fP \fB= \fP\f(BIuuid()\fP\fB\fP" .IX Subsection "$string = uuid()" Creates a new string format \s-1UUID\s0 and returns it in a more Perlish way. .PP Functionally the equivalent of calling \fB\f(BIgenerate()\fB\fR and then \fB\f(BIunparse()\fB\fR, but throwing away the intermediate binary \s-1UUID.\s0 .SH "UUID LIBRARY" .IX Header "UUID LIBRARY" Note that on some systems external packages will need to be installed first. Notably, uuid-dev or uuid-devel on Debian and RedHat Linux, respectively, and their derivatives. .SH "EXPORTS" .IX Header "EXPORTS" None by default. All functions may be imported in the usual manner, either individually or all at once using the "\fI:all\fR" tag. .SH "TODO" .IX Header "TODO" Need more tests and sanity checks. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2014\-2016 by Rick Myers. .PP This is free software, licensed under: .PP .Vb 1 \& The Artistic License 2.0 (GPL Compatible) .Ve .PP Details of this license can be found within the 'License' text file. .SH "AUTHOR" .IX Header "AUTHOR" Current maintainer: .PP .Vb 1 \& Rick Myers . .Ve .PP Authors and/or previous maintainers: .PP .Vb 1 \& Lukas Zapletal \& \& Joseph N. Hall \& \& Colin Faber \& \& Peter J. Braam .Ve .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" David E. Wheeler .PP William Faulk .PP gregor herrmann .PP Slaven Rezic .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fB\f(BIuuid\fB\|(3)\fR, \fB\f(BIuuid_clear\fB\|(3)\fR, \fB\f(BIuuid_compare\fB\|(3)\fR, \fB\f(BIuuid_copy\fB\|(3)\fR, \&\fB\f(BIuuid_generate\fB\|(3)\fR, \fB\f(BIuuid_is_null\fB\|(3)\fR, \fB\f(BIuuid_parse\fB\|(3)\fR, \&\fB\f(BIuuid_unparse\fB\|(3)\fR, \fB\f(BIperl\fB\|(1)\fR.