*** /dev/null Fri Nov 22 15:02:00 2024
--- - Fri Nov 22 15:02:12 2024
***************
*** 0 ****
--- 1,175 ----
+ ##
+ ## OSSP uuid - Universally Unique Identifier
+ ## Copyright (c) 2004-2005 Ralf S. Engelschall <rse@engelschall.com>
+ ## Copyright (c) 2004-2005 The OSSP Project <http://www.ossp.org/>
+ ##
+ ## 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<OSSP uuid> - B<Universally Unique Identifier Command-Line Tool>
+
+ =head1 VERSION
+
+ OSSP uuid UUID_VERSION_STR
+
+ =head1 SYNOPSIS
+
+ B<uuid>
+ [B<-v> I<version>]
+ [B<-m>]
+ [B<-n> I<count>]
+ [B<-1>]
+ [B<-r>]
+ [B<-o> I<filename>]
+ [I<namespace> I<name>]
+
+ B<uuid>
+ B<-d>
+ [B<-r>]
+ [B<-o> I<filename>]
+ I<uuid>
+
+ =head1 DESCRIPTION
+
+ B<OSSP uuid> is a ISO-C and Perl application programming interface (API)
+ and corresponding command line interface (CLI) for the generation of DCE
+ 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant I<Universally Unique
+ Identifier> (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time
+ and node based), version 3 (name based, MD5), version 4 (random number
+ based) and version 5 (name based, SHA-1).
+
+ 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<OSSP uuid>. 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<version>
+
+ Sets the version of the generated DCE 1.1 variant UUID. Supported
+ are I<version> "C<1>", "C<3>", "C<4>" and "C<5>". The default is "C<1>".
+
+ For version 3 and version 5 UUIDs the additional command line arguments
+ I<namespace> and I<name> have to be given. The I<namespace> is either
+ a UUID in string representation or an identifier for internally
+ pre-defined namespace UUIDs (currently known are "C<ns:DNS>",
+ "C<ns:URL>", "C<ns:OID>", and "C<ns:X500>"). The I<name> 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<count>
+
+ Generate I<count> UUIDs instead of just a single one (the default).
+
+ =item B<-1>
+
+ If option B<-n> is used with a I<count> greater than C<1>, then this
+ option can enforce the reset the UUID context for each generated UUID.
+ This makes no difference for I<version> C<3>, C<4> and C<5> 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<filename>
+
+ Write output to I<filename> instead of to F<stdout>.
+
+ =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<stdin>) 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
+
|
