diff options
Diffstat (limited to 'shared/ossp_uuid/perl/uuid.pod')
-rw-r--r-- | shared/ossp_uuid/perl/uuid.pod | 207 |
1 files changed, 0 insertions, 207 deletions
diff --git a/shared/ossp_uuid/perl/uuid.pod b/shared/ossp_uuid/perl/uuid.pod deleted file mode 100644 index 7c6172f0..00000000 --- a/shared/ossp_uuid/perl/uuid.pod +++ /dev/null @@ -1,207 +0,0 @@ -## -## 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 - |