## ## OSSP uuid - Universally Unique Identifier ## Copyright (c) 2004 Ralf S. Engelschall ## Copyright (c) 2004 The OSSP Project ## ## This file is part of OSSP uuid, a library for the generation ## of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/ ## ## Permission to use, copy, modify, and distribute this software for ## any purpose with or without fee is hereby granted, provided that ## the above copyright notice and this permission notice appear in all ## copies. ## ## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF ## SUCH DAMAGE. ## ## uuid_cli.pod: manual page ## =pod =head1 NAME B - B =head1 VERSION OSSP uuid UUID_VERSION_STR =head1 SYNOPSIS B [B<-v> I] [B<-m>] [B<-n> I] [B<-1>] [B<-r>] [B<-o> I] [I I] B B<-d> [B<-r>] [B<-o> I] I =head1 DESCRIPTION B is a ISO-C and Perl application programming interface (API) and corresponding command line interface (CLI) for the generation of DCE 1.1 and ISO/IEC 11578:1996 compliant I (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and node based), version 3 (name based) and version 4 (random number based). UUIDs are 128 bit numbers which are intended to have a high likelihood of uniqueness over space and time and are computationally difficult to guess. They are globally unique identifiers which can be locally generated without contacting a global registration authority. UUIDs are intended as unique identifiers for both mass tagging objects with an extremely short lifetime and to reliably identifying very persistent objects across a network. This is the command line interface (CLI) of B. For a detailed description of UUIDs see the documentation of the application programming interface (API) in uuid(3). =head1 OPTIONS =over 3 =item B<-v> I Sets the version of the generated DCE 1.1 variant UUID. Supported are I "C<1>", "C<3>" and "C<4>". The default is "C<1>". For version 3 UUIDs the additional command line arguments I and I have to be given. The I is either a UUID in string representation or an identifier for internally pre-defined namespace UUIDs (currently known are "C", "C", "C", and "C"). The I is a string of arbitrary length. =item B<-m> Forces the use of a random multi-cast MAC address when generating version 1 UUIDs. By default the real physical MAC address of the system is used. =item B<-n> I Generate I UUIDs instead of just a single one (the default). =item B<-1> If option B<-n> is used with a I greater than C<1>, then this option can enforce the reset the UUID context for each generated UUID. This makes no difference for I C<3> and C<4> UUIDs. But version C<1> UUIDs are based on the previously generated UUID which is remembered in the UUID context of the API. Option B<-1> deletes the remembered UUID on each iteration. =item B<-r> Output the generated UUID in 128 bit (network byte order) raw binary representation format. The default is to output the generated UUID in the standardized ASCII string representation. =item B<-o> I Write output to I instead of to F. =item B<-d> Decode a given UUID (given as a command line argument or if the command line argument is "C<->" the UUID is read from F) and dump textual information about the UUID. =back =head1 EXAMPLES # generate DCE 1.1 v1 UUID (time and node based) $ uuid -v1 01c47915-4777-11d8-bc70-0090272ff725 # decode and dump DCE 1.1 v1 UUID (time and node based) $ uuid -d 01c47915-4777-11d8-bc70-0090272ff725 UUID: 01c47915-4777-11d8-bc70-0090272ff725 variant: DCE 1.1, ISO/IEC 11578:1996 version: 1 (time and node based) content: time: 2004-01-15 16:22:26.376322.1 UTC clock: 15472 (usually random) node: 00:90:27:2f:f7:25 (global unicast) # generate DCE 1.1 v3 UUID (name based) $ uuid -v3 ns:URL http://www.ossp.org/ 02d9e6d5-9467-382e-8f9b-9300a64ac3cd # decode and dump DCE 1.1 v3 UUID (name based) $ uuid -d 02d9e6d5-9467-382e-8f9b-9300a64ac3cd UUID: 02d9e6d5-9467-382e-8f9b-9300a64ac3cd variant: DCE 1.1, ISO/IEC 11578:1996 version: 3 (name based) content: 02:D9:E6:D5:94:67:08:2E:0F:9B:93:00:A6:4A:C3:CD (not decipherable, because message digest only) # generate DCE 1.1 v4 UUID 4 (random data based) $ uuid -v4 eb424026-6f54-4ef8-a4d0-bb658a1fc6cf # decode and dump DCE 1.1 v4 UUID 4 (random data based) $ uuid -d eb424026-6f54-4ef8-a4d0-bb658a1fc6cf UUID: eb424026-6f54-4ef8-a4d0-bb658a1fc6cf variant: DCE 1.1, ISO/IEC 11578:1996 version: 4 (random data based) content: EB:42:40:26:6F:54:0E:F8:24:D0:BB:65:8A:1F:C6:CF (no semantics, because random data only) =head1 SEE ALSO uuid(3), OSSP::uuid(3). =cut