##
##  OSSP uuid - Universally Unique Identifier
##  Copyright (c) 2004 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2004 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 application programming interface (API) and
corresponding command line interface (CLI) for the generation of DCE
1.1 and ISO/IEC 11578:1996 compliant I<Universally Unique Identifier>
(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<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>" and "C<4>". The default is "C<1>".

For version 3 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> 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<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).

=cut

