1NAME
2 UUID - DCE compatible Universally Unique Identifier library for Perl
3
4SYNOPSIS
5 use UUID 'uuid';
6
7 $string = uuid(); # generate stringified UUID
8
9 UUID::generate($uuid); # new binary UUID; prefer random
10 UUID::generate_random($uuid); # new binary UUID; use random
11 UUID::generate_time($uuid); # new binary UUID; use time
12
13 UUID::unparse($uuid, $string); # stringify $uuid; system casing
14 UUID::unparse_lower($uuid, $string); # force lowercase stringify
15 UUID::unparse_upper($uuid, $string); # force uppercase stringify
16
17 $rc = UUID::parse($string, $uuid); # map string to UUID; -1 on error
18
19 UUID::copy($dst, $src); # copy binary UUID from $src to $dst
20 UUID::compare($uuid1, $uuid2); # compare binary UUIDs
21
22 UUID::clear( $uuid ); # set binary UUID to NULL
23 UUID::is_null( $uuid ); # compare binary UUID to NULL
24
25DESCRIPTION
26 The UUID library is used to generate unique identifiers for objects that
27 may be accessible beyond the local system. For instance, they could be
28 used to generate unique HTTP cookies across multiple web servers without
29 communication between the servers, and without fear of a name clash.
30
31 The generated UUIDs can be reasonably expected to be unique within a
32 system, and unique across all systems, and are compatible with those
33 created by the Open Software Foundation (OSF) Distributed Computing
34 Environment (DCE) utility uuidgen.
35
36FUNCTIONS
37 Most of the UUID functions expose the underlying libuuid C interface
38 rather directly. That is, many return their values in their parameters
39 and nothing else.
40
41 Not very Perlish, is it? It's been like that for a long time though, so
42 not very likely to change any time soon.
43
44 All take or return UUIDs in either binary or string format. The string
45 format resembles the following:
46
47 1b4e28ba-2fa1-11d2-883f-0016d3cca427
48
49 Or, in terms of printf(3) format:
50
51 "%08x-%04x-%04x-%04x-%012x"
52
53 The binary format is simply a packed 16 byte binary value.
54
55 generate( $uuid )
56 Generates a new binary UUID based on high quality randomness from
57 /dev/urandom, if available.
58
59 Alternately, the current time, the local ethernet MAC address (if
60 available), and random data generated using a pseudo-random generator
61 are used.
62
63 The previous content of $uuid, if any, is lost.
64
65 generate_random( $uuid )
66 Generates a new binary UUID but forces the use of the all-random
67 algorithm, even if a high-quality random number generator (i.e.,
68 /dev/urandom) is not available, in which case a pseudo-random
69 generator is used.
70
71 Note that the use of a pseudo-random generator may compromise the
72 uniqueness of UUIDs generated in this fashion.
73
74 generate_time( $uuid )
75 Generates a new binary UUID but forces the use of the alternative
76 algorithm which uses the current time and the local ethernet MAC address
77 (if available).
78
79 This algorithm used to be the default one used to generate UUIDs, but
80 because of the use of the ethernet MAC address, it can leak information
81 about when and where the UUID was generated.
82
83 This can cause privacy problems in some applications, so the generate()
84 function only uses this algorithm if a high-quality source of randomness
85 is not available.
86
87 unparse( $uuid, $string )
88 Converts the binary UUID in $uuid to string format and returns in
89 $string. The previous content of $string, if any, is lost.
90
91 The case of the hex digits returned may be upper or lower case, and is
92 dependent on the system-dependent local default.
93
94 unparse_lower( $uuid, $string )
95 Same as unparse() but $string is forced to lower case.
96
97 unparse_upper( $uuid, $string )
98 Same as unparse() but $string is forced to upper case.
99
100 $rc = parse( $string, $uuid )
101 Converts the string format UUID in $string to binary and returns in
102 $uuid. The previous content of $uuid, if any, is lost.
103
104 Returns 0 on success and -1 on failure. Additionally on failure, the
105 content of $uuid is unchanged.
106
107 clear( $uuid )
108 Sets $uuid equal to the value of the NULL UUID.
109
110 is_null( $uuid )
111 Compares the value of $uuid to the NULL UUID.
112
113 Returns 1 if NULL, and 0 otherwise.
114
115 copy( $dst, $src )
116 Copies the binary $src UUID to $dst.
117
118 If $src isn't a UUID, $dst is set to the NULL UUID.
119
120 compare( $uuid1, $uuid2 )
121 Compares two binary UUIDs.
122
123 Returns an integer less than, equal to, or greater than zero if $uuid1
124 is less than, equal to, or greater than $uuid2.
125
126 However, if either operand is not a UUID, falls back to a simple string
127 comparison returning similar values.
128
129 $string = uuid()
130 Creates a new string format UUID and returns it in a more Perlish way.
131
132 Functionally the equivalent of calling generate() and then unparse(),
133 but throwing away the intermediate binary UUID.
134
135UUID LIBRARY
136 On some systems external packages will need to be installed first.
137 Notably, uuid-dev, libuuid-devel, or uuid-devel, depending on your
138 platform.
139
140 Some may also have more than one package available. It should be safe to
141 install all variations. The UUID installer will then opt towards the
142 older, faster library.
143
144EXPORTS
145 None by default. All functions may be imported in the usual manner,
146 either individually or all at once using the ":all" tag.
147
148TODO
149 Need more tests and sanity checks.
150
151COPYRIGHT AND LICENSE
152 This software is Copyright (c) 2014-2016 by Rick Myers.
153
154 This is free software, licensed under:
155
156 The Artistic License 2.0 (GPL Compatible)
157
158 Details of this license can be found within the 'License' text file.
159
160AUTHOR
161 Current maintainer:
162
163 Rick Myers <jrm@cpan.org>.
164
165 Authors and/or previous maintainers:
166
167 Lukas Zapletal <lzap@cpan.org>
168
169 Joseph N. Hall <joseph.nathan.hall@gmail.com>
170
171 Colin Faber <cfaber@clusterfs.com>
172
173 Peter J. Braam <braam@mountainviewdata.com>
174
175CONTRIBUTORS
176 David E. Wheeler
177
178 William Faulk
179
180 gregor herrmann
181
182 Slaven Rezic
183
184SEE ALSO
185 uuid(3), uuid_clear(3), uuid_compare(3), uuid_copy(3), uuid_generate(3),
186 uuid_is_null(3), uuid_parse(3), uuid_unparse(3), perl(1).
187
188