D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
lib
/
x86_64-linux-gnu
/
perl5
/
5.34
/
OSSP
/
Filename :
uuid.pod
back
Copy
## ## 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