378 lines
11 KiB
HTML
378 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of UUID</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>UUID</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-10-18<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
UUID - DCE compatible Universally Unique Identifier library for Perl
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use UUID 'uuid';
|
|
|
|
$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
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">UUID</FONT> 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 <FONT SIZE="-1">HTTP</FONT> cookies across multiple web servers without
|
|
communication between the servers, and without fear of a name clash.
|
|
<P>
|
|
|
|
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 (<FONT SIZE="-1">OSF</FONT>) Distributed Computing
|
|
Environment (<FONT SIZE="-1">DCE</FONT>) utility uuidgen.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>FUNCTIONS</H2>
|
|
|
|
|
|
|
|
Most of the <FONT SIZE="-1">UUID</FONT> functions expose the underlying <I>libuuid</I> C interface
|
|
rather directly. That is, many return their values in their parameters
|
|
and nothing else.
|
|
<P>
|
|
|
|
Not very Perlish, is it? It's been like that for a long time though, so
|
|
not very likely to change any time soon.
|
|
<P>
|
|
|
|
All take or return UUIDs in either binary or string format. The string
|
|
format resembles the following:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
1b4e28ba-2fa1-11d2-883f-0016d3cca427
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Or, in terms of <B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3) format:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
"%08x-%04x-%04x-%04x-%012x"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The binary format is simply a packed 16 byte binary value.
|
|
<A NAME="lbAF"> </A>
|
|
<H3><B>generate(</B> <I></I>$uuid<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Generates a new binary <FONT SIZE="-1">UUID</FONT> based on high quality randomness from
|
|
<I>/dev/urandom</I>, if available.
|
|
<P>
|
|
|
|
Alternately, the current time, the local ethernet <FONT SIZE="-1">MAC</FONT> address (if
|
|
available), and random data generated using a pseudo-random generator
|
|
are used.
|
|
<P>
|
|
|
|
The previous content of <I></I>$uuid<I></I>, if any, is lost.
|
|
<A NAME="lbAG"> </A>
|
|
<H3><B>generate_random(</B> <I></I>$uuid<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Generates a new binary <FONT SIZE="-1">UUID</FONT> but forces the use of the all-random
|
|
algorithm, even if a high-quality random number generator (i.e.,
|
|
<I>/dev/urandom</I>) is not available, in which case a pseudo-random
|
|
generator is used.
|
|
<P>
|
|
|
|
Note that the use of a pseudo-random generator may compromise the
|
|
uniqueness of UUIDs generated in this fashion.
|
|
<A NAME="lbAH"> </A>
|
|
<H3><B>generate_time(</B> <I></I>$uuid<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Generates a new binary <FONT SIZE="-1">UUID</FONT> but forces the use of the alternative
|
|
algorithm which uses the current time and the local ethernet <FONT SIZE="-1">MAC</FONT> address
|
|
(if available).
|
|
<P>
|
|
|
|
This algorithm used to be the default one used to generate UUIDs, but
|
|
because of the use of the ethernet <FONT SIZE="-1">MAC</FONT> address, it can leak information
|
|
about when and where the <FONT SIZE="-1">UUID</FONT> was generated.
|
|
<P>
|
|
|
|
This can cause privacy problems in some applications, so the <B>generate()</B>
|
|
function only uses this algorithm if a high-quality source of randomness
|
|
is not available.
|
|
<A NAME="lbAI"> </A>
|
|
<H3><B>unparse(</B> <I></I>$uuid<I></I><B>,</B> <I></I>$string<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Converts the binary <FONT SIZE="-1">UUID</FONT> in <I></I>$uuid<I></I> to string format and returns in
|
|
<I></I>$string<I></I>. The previous content of <I></I>$string<I></I>, if any, is lost.
|
|
<P>
|
|
|
|
The case of the hex digits returned may be upper or lower case, and is
|
|
dependent on the system-dependent local default.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3><B>unparse_lower(</B> <I></I>$uuid<I></I><B>,</B> <I></I>$string<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Same as <B>unparse()</B> but <I></I>$string<I></I> is forced to lower case.
|
|
<A NAME="lbAK"> </A>
|
|
<H3><B>unparse_upper(</B> <I></I>$uuid<I></I><B>,</B> <I></I>$string<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Same as <B>unparse()</B> but <I></I>$string<I></I> is forced to upper case.
|
|
<A NAME="lbAL"> </A>
|
|
<H3><B></B>$rc<B> = parse(</B> <I></I>$string<I></I><B>,</B> <I></I>$uuid<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Converts the string format <FONT SIZE="-1">UUID</FONT> in <I></I>$string<I></I> to binary and returns in
|
|
<I></I>$uuid<I></I>. The previous content of <I></I>$uuid<I></I>, if any, is lost.
|
|
<P>
|
|
|
|
Returns 0 on success and -1 on failure. Additionally on failure, the
|
|
content of <I></I>$uuid<I></I> is unchanged.
|
|
<A NAME="lbAM"> </A>
|
|
<H3><B>clear(</B> <I></I>$uuid<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Sets <I></I>$uuid<I></I> equal to the value of the <FONT SIZE="-1">NULL UUID.</FONT>
|
|
<A NAME="lbAN"> </A>
|
|
<H3><B>is_null(</B> <I></I>$uuid<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Compares the value of <I></I>$uuid<I></I> to the <FONT SIZE="-1">NULL UUID.</FONT>
|
|
<P>
|
|
|
|
Returns 1 if <FONT SIZE="-1">NULL,</FONT> and 0 otherwise.
|
|
<A NAME="lbAO"> </A>
|
|
<H3><B>copy(</B> <I></I>$dst<I></I><B>,</B> <I></I>$src<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Copies the binary <I></I>$src<I></I> <FONT SIZE="-1">UUID</FONT> to <I></I>$dst<I></I>.
|
|
<P>
|
|
|
|
If <I></I>$src<I></I> isn't a <FONT SIZE="-1">UUID,</FONT> <I></I>$dst<I></I> is set to the <FONT SIZE="-1">NULL UUID.</FONT>
|
|
<A NAME="lbAP"> </A>
|
|
<H3><B>compare(</B> <I></I>$uuid1<I></I><B>,</B> <I></I>$uuid2<I></I> <B>)</B></H3>
|
|
|
|
|
|
|
|
Compares two binary UUIDs.
|
|
<P>
|
|
|
|
Returns an integer less than, equal to, or greater than zero if
|
|
<I></I>$uuid1<I></I> is less than, equal to, or greater than <I></I>$uuid2<I></I>.
|
|
<P>
|
|
|
|
However, if either operand is not a <FONT SIZE="-1">UUID,</FONT> falls back to a simple string
|
|
comparison returning similar values.
|
|
<A NAME="lbAQ"> </A>
|
|
<H3><B></B><I></I>$string<I></I> <B>= uuid()</B></H3>
|
|
|
|
|
|
|
|
Creates a new string format <FONT SIZE="-1">UUID</FONT> and returns it in a more Perlish way.
|
|
<P>
|
|
|
|
Functionally the equivalent of calling <B>generate()</B> and then <B>unparse()</B>, but
|
|
throwing away the intermediate binary <FONT SIZE="-1">UUID.</FONT>
|
|
<A NAME="lbAR"> </A>
|
|
<H2>UUID LIBRARY</H2>
|
|
|
|
|
|
|
|
On some systems external packages will need to be installed first.
|
|
Notably, uuid-dev, libuuid-devel, or uuid-devel, depending on your
|
|
platform.
|
|
<P>
|
|
|
|
Some may also have more than one package available. It should be safe to
|
|
install all variations. The <FONT SIZE="-1">UUID</FONT> installer will then opt towards the
|
|
older, faster library.
|
|
<A NAME="lbAS"> </A>
|
|
<H2>EXPORTS</H2>
|
|
|
|
|
|
|
|
None by default. All functions may be imported in the usual manner,
|
|
either individually or all at once using the "<I>:all</I>" tag.
|
|
<A NAME="lbAT"> </A>
|
|
<H2>TODO</H2>
|
|
|
|
|
|
|
|
Need more tests and sanity checks.
|
|
<A NAME="lbAU"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
This software is Copyright (c) 2014-2016 by Rick Myers.
|
|
<P>
|
|
|
|
This is free software, licensed under:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
The Artistic License 2.0 (GPL Compatible)
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Details of this license can be found within the 'License' text file.
|
|
<A NAME="lbAV"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Current maintainer:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Rick Myers <<A HREF="mailto:jrm@cpan.org">jrm@cpan.org</A>>.
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Authors and/or previous maintainers:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Lukas Zapletal <<A HREF="mailto:lzap@cpan.org">lzap@cpan.org</A>>
|
|
|
|
Joseph N. Hall <<A HREF="mailto:joseph.nathan.hall@gmail.com">joseph.nathan.hall@gmail.com</A>>
|
|
|
|
Colin Faber <<A HREF="mailto:cfaber@clusterfs.com">cfaber@clusterfs.com</A>>
|
|
|
|
Peter J. Braam <<A HREF="mailto:braam@mountainviewdata.com">braam@mountainviewdata.com</A>>
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAW"> </A>
|
|
<H2>CONTRIBUTORS</H2>
|
|
|
|
|
|
|
|
David E. Wheeler
|
|
<P>
|
|
|
|
William Faulk
|
|
<P>
|
|
|
|
gregor herrmann
|
|
<P>
|
|
|
|
Slaven Rezic
|
|
<A NAME="lbAX"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid">uuid</A>(3)</B>, <B><A HREF="/cgi-bin/man/man2html?3+uuid_clear">uuid_clear</A>(3)</B>, <B><A HREF="/cgi-bin/man/man2html?3+uuid_compare">uuid_compare</A>(3)</B>, <B><A HREF="/cgi-bin/man/man2html?3+uuid_copy">uuid_copy</A>(3)</B>,
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_generate">uuid_generate</A>(3)</B>, <B><A HREF="/cgi-bin/man/man2html?3+uuid_is_null">uuid_is_null</A>(3)</B>, <B><A HREF="/cgi-bin/man/man2html?3+uuid_parse">uuid_parse</A>(3)</B>,
|
|
<B><A HREF="/cgi-bin/man/man2html?3+uuid_unparse">uuid_unparse</A>(3)</B>, <B><A HREF="/cgi-bin/man/man2html?1+perl">perl</A>(1)</B>.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="4"><A HREF="#lbAE">FUNCTIONS</A><DD>
|
|
<DL>
|
|
<DT id="5"><A HREF="#lbAF"><B>generate(</B> <I></I>$uuid<I></I> <B>)</B></A><DD>
|
|
<DT id="6"><A HREF="#lbAG"><B>generate_random(</B> <I></I>$uuid<I></I> <B>)</B></A><DD>
|
|
<DT id="7"><A HREF="#lbAH"><B>generate_time(</B> <I></I>$uuid<I></I> <B>)</B></A><DD>
|
|
<DT id="8"><A HREF="#lbAI"><B>unparse(</B> <I></I>$uuid<I></I><B>,</B> <I></I>$string<I></I> <B>)</B></A><DD>
|
|
<DT id="9"><A HREF="#lbAJ"><B>unparse_lower(</B> <I></I>$uuid<I></I><B>,</B> <I></I>$string<I></I> <B>)</B></A><DD>
|
|
<DT id="10"><A HREF="#lbAK"><B>unparse_upper(</B> <I></I>$uuid<I></I><B>,</B> <I></I>$string<I></I> <B>)</B></A><DD>
|
|
<DT id="11"><A HREF="#lbAL"><B></B>$rc<B> = parse(</B> <I></I>$string<I></I><B>,</B> <I></I>$uuid<I></I> <B>)</B></A><DD>
|
|
<DT id="12"><A HREF="#lbAM"><B>clear(</B> <I></I>$uuid<I></I> <B>)</B></A><DD>
|
|
<DT id="13"><A HREF="#lbAN"><B>is_null(</B> <I></I>$uuid<I></I> <B>)</B></A><DD>
|
|
<DT id="14"><A HREF="#lbAO"><B>copy(</B> <I></I>$dst<I></I><B>,</B> <I></I>$src<I></I> <B>)</B></A><DD>
|
|
<DT id="15"><A HREF="#lbAP"><B>compare(</B> <I></I>$uuid1<I></I><B>,</B> <I></I>$uuid2<I></I> <B>)</B></A><DD>
|
|
<DT id="16"><A HREF="#lbAQ"><B></B><I></I>$string<I></I> <B>= uuid()</B></A><DD>
|
|
</DL>
|
|
<DT id="17"><A HREF="#lbAR">UUID LIBRARY</A><DD>
|
|
<DT id="18"><A HREF="#lbAS">EXPORTS</A><DD>
|
|
<DT id="19"><A HREF="#lbAT">TODO</A><DD>
|
|
<DT id="20"><A HREF="#lbAU">COPYRIGHT AND LICENSE</A><DD>
|
|
<DT id="21"><A HREF="#lbAV">AUTHOR</A><DD>
|
|
<DT id="22"><A HREF="#lbAW">CONTRIBUTORS</A><DD>
|
|
<DT id="23"><A HREF="#lbAX">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:59 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|