ossp-pkg/uuid/uuid_cli.pod
1.2
##
## 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 SYNOPSIS
B<uuid>
[B<-v> I<version>]
[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 Identifiers>
(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).
This is the command line interface (CLI). For a brief overview 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>".
=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 (either on F<stdin> or as an argument on the command
line) and dump textual information about the UUID.
=back
=head1 EXAMPLES
# generate DCE 1.1 variant UUID of version 1 (time and node based)
$ uuid -v1
1430fcde-43a9-11d8-8000-0090272ff725
# generate DCE 1.1 variant UUID of version 3 (name based)
$ uuid -v3 URL http://www.ossp.org/
02d9e6d5-9467-382e-8f9b-9300a64ac3cd
# generate DCE 1.1 variant UUID of version 4 (random data based)
$ ./uuid -v4
eb424026-6f54-4ef8-a4d0-bb658a1fc6cf
=head1 SEE ALSO
uuid(3).
=cut
