NAME
UUID - DCE compatible Universally Unique Identifier library for Perl
SYNOPSIS
use UUID ':all';
generate($uuid); # generates a 128 bit uuid
unparse($uuid, $string); # change $uuid to 36 byte string
$rc = parse($string, $uuid); # map string to UUID, return -1 on error
$string = uuid(); # generate new UUID, return string onlyDESCRIPTION
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.
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:
1b4e28ba-2fa1-11d2-883f-0016d3cca427Or, in terms of printf(3) format:
"%08x-%04x-%04x-%04x-%012x"The binary format is simply a packed 16 byte binary value.
generate( $uuid )
Creates a new binary UUID based on high quality randomness from /dev/urandom, if available.
Alternately, the current time, the local ethernet MAC address (if available), and random data generated using a pseudo-random generator are used.
The previous content of $uuid, if any, is lost.
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.
The case of the hex digits returned may be upper or lower case, and is dependent on the system-dependent local default.
$rc = 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.
$string = 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.
EXPORTS
The following functions are exported only by request.
generate
unparse
parse
uuidAll the functions may be imported using the ":all" tag.
TODO
Expose the rest of libuuid.
Status Function
------ --------
. void uuid_clear(uuid_t uu);
. int uuid_compare(const uuid_t uu1, const uuid_t uu2);
. void uuid_copy(uuid_t dst, const uuid_t src);
! void uuid_generate(uuid_t out);
. void uuid_generate_random(uuid_t out);
. void uuid_generate_time(uuid_t out);
. int uuid_is_null(const uuid_t uu);
! int uuid_parse(const char *in, uuid_t uu);
. void uuid_unparse(const uuid_t uu, char *out);
. void uuid_unparse_lower(const uuid_t uu, char *out);
. void uuid_unparse_upper(const uuid_t uu, char *out);
. time_t uuid_time(const uuid_t uu, struct timeval *ret_tv);
? int uuid_type(const uuid_t uu);
? int uuid_variant(const uuid_t uu);
Status Constant
------ --------
? UUID_VARIANT_NCS
? UUID_VARIANT_DCE
? UUID_VARIANT_MICROSOFT
? UUID_VARIANT_OTHER
? UUID_TYPE_DCE_TIME
? UUID_TYPE_DCE_RANDOM
. - todo.
! - done!
? - why?COPYRIGHT AND LICENSE
This software is Copyright (c) 2014 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:
Joseph N. Hall <joseph.nathan.hall@gmail.com>
Colin Faber <cfaber@clusterfs.com>
Peter J. Braam <braam@mountainviewdata.com>
Lukas Zapletal <lzap@cpan.org>SEE ALSO
uuid_generate(3), uuid_parse(3), uuid_unparse(3), perl(1).