208 lines
5.7 KiB
Plaintext
208 lines
5.7 KiB
Plaintext
##
|
|
## OSSP uuid - Universally Unique Identifier
|
|
## Copyright (c) 2004-2007 Ralf S. Engelschall <rse@engelschall.com>
|
|
## Copyright (c) 2004-2007 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.pod: Perl Binding (Perl/POD part)
|
|
##
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSP::uuid - B<OSSP uuid> Perl Binding
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<OSSP uuid> is a ISO-C:1999 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). Additional API bindings are
|
|
provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional
|
|
backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID
|
|
APIs.
|
|
|
|
B<OSSP::uuid> is the Perl binding to the B<OSSP uuid> API.
|
|
Three variants are provided:
|
|
|
|
=head2 TIE-STYLE API
|
|
|
|
The TIE-style API is a functionality-reduced wrapper around the OO-style
|
|
API and intended for very high-level convenience programming:
|
|
|
|
=over 4
|
|
|
|
=item C<use OSSP::uuid;>
|
|
|
|
=item B<tie>C< my $uuid, 'OSSP::uuid::tie', $mode, ...;>
|
|
|
|
=item C<$uuid = [ $mode, ... ];>
|
|
|
|
=item C<print "UUID=$uuid\n";>
|
|
|
|
=item C<untie $uuid;>
|
|
|
|
=back
|
|
|
|
=head2 OO-STYLE API
|
|
|
|
The OO-style API is a wrapper around the C-style API and intended for
|
|
high-level regular programming.
|
|
|
|
=over 4
|
|
|
|
=item C<use OSSP::uuid;>
|
|
|
|
=item C<my $uuid = >B<new>C< OSSP::uuid;>
|
|
|
|
=item C<$uuid-E<gt>>B<load>C<($name);>
|
|
|
|
=item C<$uuid-E<gt>>B<make>C<($mode, ...);>
|
|
|
|
=item C<$result = $uuid-E<gt>>B<isnil>C<();>
|
|
|
|
=item C<$result = $uuid-E<gt>>B<compare>C<($uuid2);>
|
|
|
|
=item C<$uuid-E<gt>>B<import>C<($fmt, $data_ptr);>
|
|
|
|
=item C<$data_ptr = $uuid-E<gt>>B<export>C<($fmt);>
|
|
|
|
=item C<[(]$str[, $rc)] = $uuid-E<gt>>B<error>C<();>
|
|
|
|
=item C<$ver = $uuid-E<gt>>B<version>C<();>
|
|
|
|
=item C<undef $uuid;>
|
|
|
|
=back
|
|
|
|
Additionally, the strings C<"v1">, C<"v3">, C<"v4">, C<"v5"> and C<"mc">
|
|
can be used in C<$mode> and the strings C<"bin">, C<"str">, and C<"txt">
|
|
can be used for C<$fmt>.
|
|
|
|
=head2 C-STYLE API
|
|
|
|
The C-style API is a direct mapping
|
|
of the B<OSSP uuid> ISO-C API to Perl and is intended for low-level
|
|
programming. See uuid(3) for a description of the functions and
|
|
their expected arguments.
|
|
|
|
=over 4
|
|
|
|
=item C<use OSSP::uuid qw(:all);>
|
|
|
|
=item C<my $uuid; $rc = >B<uuid_create>C<($uuid);>
|
|
|
|
=item C<$rc = >B<uuid_load>C<($uuid, $name);>
|
|
|
|
=item C<$rc = >B<uuid_make>C<($uuid, $mode, ...);>
|
|
|
|
=item C<$rc = >B<uuid_isnil>C<($uuid, $result);>
|
|
|
|
=item C<$rc = >B<uuid_compare>C<($uuid, $uuid2, $result);>
|
|
|
|
=item C<$rc = >B<uuid_import>C<($uuid, $fmt, $data_ptr, $data_len);>
|
|
|
|
=item C<$rc = >B<uuid_export>C<($uuid, $fmt, $data_ptr, $data_len);>
|
|
|
|
=item C<$str = >B<uuid_error>C<($rc);>
|
|
|
|
=item C<$ver = >B<uuid_version>C<();>
|
|
|
|
=item C<$rc = >B<uuid_destroy>C<($uuid);>
|
|
|
|
=back
|
|
|
|
Additionally, the following constants are exported for use in C<$rc>, C<$mode>, C<$fmt> and C<$ver>:
|
|
|
|
C<UUID_VERSION>,
|
|
C<UUID_LEN_BIN>,
|
|
C<UUID_LEN_STR>,
|
|
C<UUID_RC_OK>,
|
|
C<UUID_RC_ARG>,
|
|
C<UUID_RC_MEM>,
|
|
C<UUID_RC_SYS>,
|
|
C<UUID_RC_INT>,
|
|
C<UUID_RC_IMP>,
|
|
C<UUID_MAKE_V1>,
|
|
C<UUID_MAKE_V3>,
|
|
C<UUID_MAKE_V4>,
|
|
C<UUID_MAKE_V5>,
|
|
C<UUID_MAKE_MC>,
|
|
C<UUID_FMT_BIN>,
|
|
C<UUID_FMT_STR>,
|
|
C<UUID_FMT_SIV>,
|
|
C<UUID_FMT_TXT>.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
The following two examples create the version 3 UUID
|
|
C<02d9e6d5-9467-382e-8f9b-9300a64ac3cd>, both via the OO-style and the
|
|
C-style API. Error handling is omitted here for easier reading, but has
|
|
to be added for production-quality code.
|
|
|
|
# TIE-style API (very high-level)
|
|
use OSSP::uuid;
|
|
tie my $uuid, 'OSSP::uuid::tie';
|
|
$uuid = [ "v1" ];
|
|
print "UUIDs: $uuid, $uuid, $uuid\n";
|
|
$uuid = [ "v3", "ns:URL", "http://www.ossp.org/" ];
|
|
print "UUIDs: $uuid, $uuid, $uuid\n";
|
|
untie $uuid;
|
|
|
|
# OO-style API (high-level)
|
|
use OSSP::uuid;
|
|
my $uuid = new OSSP::uuid;
|
|
my $uuid_ns = new OSSP::uuid;
|
|
$uuid_ns->load("ns:URL");
|
|
$uuid->make("v3", $uuid_ns, "http://www.ossp.org/");
|
|
undef $uuid_ns;
|
|
my $str = $uuid->export("str");
|
|
undef $uuid;
|
|
print "$str\n";
|
|
|
|
# C-style API (low-level)
|
|
use OSSP::uuid qw(:all);
|
|
my $uuid; uuid_create($uuid);
|
|
my $uuid_ns; uuid_create($uuid_ns);
|
|
uuid_load($uuid_ns, "ns:URL");
|
|
uuid_make($uuid, UUID_MAKE_V3, $uuid_ns, "http://www.ossp.org/");
|
|
uuid_destroy($uuid_ns);
|
|
my $str; uuid_export($uuid, UUID_FMT_STR, $str, undef);
|
|
uuid_destroy($uuid);
|
|
print "$str\n";
|
|
|
|
=head1 SEE ALSO
|
|
|
|
uuid(1), uuid-config(1), uuid(3).
|
|
|
|
=head1 HISTORY
|
|
|
|
The Perl binding B<OSSP::uuid> to B<OSSP uuid> was implemented in
|
|
November 2004 by Ralf S. Engelschall E<lt>rse@engelschall.comE<gt>.
|
|
|
|
=cut
|
|
|