1## 2## OSSP uuid - Universally Unique Identifier 3## Copyright (c) 2004-2008 Ralf S. Engelschall <rse@engelschall.com> 4## Copyright (c) 2004-2008 The OSSP Project <http://www.ossp.org/> 5## 6## This file is part of OSSP uuid, a library for the generation 7## of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/ 8## 9## Permission to use, copy, modify, and distribute this software for 10## any purpose with or without fee is hereby granted, provided that 11## the above copyright notice and this permission notice appear in all 12## copies. 13## 14## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 15## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 16## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR 18## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 20## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 21## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 22## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 24## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25## SUCH DAMAGE. 26## 27## uuid_cli.pod: manual page 28## 29 30=pod 31 32=head1 NAME 33 34B<OSSP uuid> - B<Universally Unique Identifier Command-Line Tool> 35 36=head1 VERSION 37 38OSSP uuid UUID_VERSION_STR 39 40=head1 SYNOPSIS 41 42B<uuid> 43[B<-v> I<version>] 44[B<-m>] 45[B<-n> I<count>] 46[B<-1>] 47[B<-F> I<format>] 48[B<-o> I<filename>] 49[I<namespace> I<name>] 50 51B<uuid> 52B<-d> 53[B<-r>] 54[B<-o> I<filename>] 55I<uuid> 56 57=head1 DESCRIPTION 58 59B<OSSP uuid> is a ISO-C:1999 application programming interface (API) and 60corresponding command line interface (CLI) for the generation of DCE 611.1, ISO/IEC 11578:1996 and IETF RFC-4122 compliant I<Universally Unique 62Identifier> (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time 63and node based), version 3 (name based, MD5), version 4 (random number 64based) and version 5 (name based, SHA-1). Additional API bindings are 65provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional 66backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID 67APIs. 68 69UUIDs are 128 bit numbers which are intended to have a high likelihood 70of uniqueness over space and time and are computationally difficult 71to guess. They are globally unique identifiers which can be locally 72generated without contacting a global registration authority. UUIDs 73are intended as unique identifiers for both mass tagging objects 74with an extremely short lifetime and to reliably identifying very 75persistent objects across a network. 76 77This is the command line interface (CLI) of B<OSSP uuid>. For a 78detailed description of UUIDs see the documentation of the application 79programming interface (API) in uuid(3). 80 81=head1 OPTIONS 82 83=over 3 84 85=item B<-v> I<version> 86 87Sets the version of the generated DCE 1.1 variant UUID. Supported 88are I<version> "C<1>", "C<3>", "C<4>" and "C<5>". The default is "C<1>". 89 90For version 3 and version 5 UUIDs the additional command line arguments 91I<namespace> and I<name> have to be given. The I<namespace> is either 92a UUID in string representation or an identifier for internally 93pre-defined namespace UUIDs (currently known are "C<ns:DNS>", 94"C<ns:URL>", "C<ns:OID>", and "C<ns:X500>"). The I<name> is a string of 95arbitrary length. 96 97=item B<-m> 98 99Forces the use of a random multi-cast MAC address when generating 100version 1 UUIDs. By default the real physical MAC address of the system 101is used. 102 103=item B<-n> I<count> 104 105Generate I<count> UUIDs instead of just a single one (the default). 106 107=item B<-1> 108 109If option B<-n> is used with a I<count> greater than C<1>, then this 110option can enforce the reset the UUID context for each generated UUID. 111This makes no difference for I<version> C<3>, C<4> and C<5> UUIDs. But 112version C<1> UUIDs are based on the previously generated UUID which is 113remembered in the UUID context of the API. Option B<-1> deletes the 114remembered UUID on each iteration. 115 116=item B<-F> I<format> 117 118Representation format for importing or exporting an UUID. The 119following (case insensitive) format identifiers are currently recognized: 120 121=over 4 122 123=item C<BIN> (binary representation) 124 125This is the raw 128 bit network byte order binary representation of a 126UUID. Example is the octet stream C<0xF8 0x1D 0x4F 0xAE 0x7D 0xEC 0x11 1270xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B 0xF6>. 128 129=item C<STR> (string representation) 130 131This is the 36 character hexadecimal ASCII string representation of a 132UUID. Example is the string "C<f81d4fae-7dec-11d0-a765-00a0c91e6bf6>". 133 134=item C<SIV> (single integer value representation) 135 136This is the maximum 39 character long single integer 137value representation of a UUID. Example is the string 138"C<329800735698586629295641978511506172918>". 139 140=back 141 142=item B<-o> I<filename> 143 144Write output to I<filename> instead of to F<stdout>. 145 146=item B<-d> 147 148Decode a given UUID (given as a command line argument or if the command 149line argument is "C<->" the UUID is read from F<stdin>) and dump textual 150information about the UUID. 151 152=back 153 154=head1 EXAMPLES 155 156 # generate DCE 1.1 v1 UUID (time and node based) 157 $ uuid -v1 158 01c47915-4777-11d8-bc70-0090272ff725 159 160 # decode and dump DCE 1.1 v1 UUID (time and node based) 161 $ uuid -d 01c47915-4777-11d8-bc70-0090272ff725 162 encode: STR: 01c47915-4777-11d8-bc70-0090272ff725 163 SIV: 2349374037528578887923094374772111141 164 decode: variant: DCE 1.1, ISO/IEC 11578:1996 165 version: 1 (time and node based) 166 content: time: 2004-01-15 16:22:26.376322.1 UTC 167 clock: 15472 (usually random) 168 node: 00:90:27:2f:f7:25 (global unicast) 169 170 # generate DCE 1.1 v3 UUID (name based) 171 $ uuid -v3 ns:URL http://www.ossp.org/ 172 02d9e6d5-9467-382e-8f9b-9300a64ac3cd 173 174 # decode and dump DCE 1.1 v3 UUID (name based) 175 $ uuid -d 02d9e6d5-9467-382e-8f9b-9300a64ac3cd 176 encode: STR: 02d9e6d5-9467-382e-8f9b-9300a64ac3cd 177 SIV: 3789866285607910888100818383505376205 178 decode: variant: DCE 1.1, ISO/IEC 11578:1996 179 version: 3 (name based, MD5) 180 content: 02:D9:E6:D5:94:67:08:2E:0F:9B:93:00:A6:4A:C3:CD 181 (not decipherable: MD5 message digest only) 182 183 # generate DCE 1.1 v4 UUID 4 (random data based) 184 $ uuid -v4 185 eb424026-6f54-4ef8-a4d0-bb658a1fc6cf 186 187 # decode and dump DCE 1.1 v4 UUID 4 (random data based) 188 $ uuid -d eb424026-6f54-4ef8-a4d0-bb658a1fc6cf 189 encode: STR: eb424026-6f54-4ef8-a4d0-bb658a1fc6cf 190 SIV: 312712571721458096795100956955942831823 191 decode: variant: DCE 1.1, ISO/IEC 11578:1996 192 version: 4 (random data based) 193 content: EB:42:40:26:6F:54:0E:F8:24:D0:BB:65:8A:1F:C6:CF 194 (no semantics: random data only) 195 196=head1 SEE ALSO 197 198uuid(3), OSSP::uuid(3). 199 200=cut 201 202