OSSP::uuid man page

OSSP::uuid — OSSP uuid Perl Binding


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 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.

OSSP::uuid is the Perl binding to the OSSP uuid API. Three variants are provided:

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:

"use OSSP::uuid;"

tie" my $uuid, 'OSSP::uuid::tie', $mode, ...;"

"$uuid = [ $mode, ... ];"

"print "UUID=$uuid\n";"

"untie $uuid;"

Oo-Style API

The OO-style API is a wrapper around the C-style API and intended for high-level regular programming.

"use OSSP::uuid;"

"my $uuid = "new" OSSP::uuid;"


"$uuid->"make"($mode, ...);"

"$result = $uuid->"isnil"();"

"$result = $uuid->"compare"($uuid2);"

"$uuid->"import"($fmt, $data_ptr);"

"$data_ptr = $uuid->"export"($fmt);"

"[(]$str[, $rc)] = $uuid->"error"();"

"$ver = $uuid->"version"();"

"undef $uuid;"

Additionally, the strings "v1", "v3", "v4", "v5" and "mc" can be used in $mode and the strings "bin", "str", and "txt" can be used for $fmt.

C-Style API

The C-style API is a direct mapping of the 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.

"use OSSP::uuid qw(:all);"

"my $uuid; $rc = "uuid_create"($uuid);"

"$rc = "uuid_load"($uuid, $name);"

"$rc = "uuid_make"($uuid, $mode, ...);"

"$rc = "uuid_isnil"($uuid, $result);"

"$rc = "uuid_compare"($uuid, $uuid2, $result);"

"$rc = "uuid_import"($uuid, $fmt, $data_ptr, $data_len);"

"$rc = "uuid_export"($uuid, $fmt, $data_ptr, $data_len);"

"$str = "uuid_error"($rc);"

"$ver = "uuid_version"();"

"$rc = "uuid_destroy"($uuid);"

Additionally, the following constants are exported for use in $rc, $mode, $fmt and $ver:



The following two examples create the version 3 UUID "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->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/");
my $str; uuid_export($uuid, UUID_FMT_STR, $str, undef);
print "$str\n";

See Also

uuid(1), uuid-config(1), uuid(3).


The Perl binding OSSP::uuid to OSSP uuid was implemented in November 2004 by Ralf S. Engelschall <rse@engelschall.com>.

Referenced By

ossp-uuid(3), uuid(1), uuid-config(1).

Explore man page connections for OSSP::uuid(3).