.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "uuid 3pm"
.TH uuid 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
OSSP::uuid \- OSSP uuid Perl Binding
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBOSSP uuid\fR 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 \fIUniversally Unique
Identifier\fR (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.
.PP
\&\fBOSSP::uuid\fR is the Perl binding to the \fBOSSP uuid\fR API.
Three variants are provided:
.SS "TIE-STYLE API"
.IX Subsection "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:
.ie n .IP """use OSSP::uuid;""" 4
.el .IP "\f(CWuse OSSP::uuid;\fR" 4
.IX Item "use OSSP::uuid;"
.PD 0
.ie n .IP "\fBtie\fR"" my $uuid, \*(AqOSSP::uuid::tie\*(Aq, $mode, ...;""" 4
.el .IP "\fBtie\fR\f(CW my $uuid, \*(AqOSSP::uuid::tie\*(Aq, $mode, ...;\fR" 4
.IX Item "tie my $uuid, OSSP::uuid::tie, $mode, ...;"
.ie n .IP """$uuid = [ $mode, ... ];""" 4
.el .IP "\f(CW$uuid = [ $mode, ... ];\fR" 4
.IX Item "$uuid = [ $mode, ... ];"
.ie n .IP """print ""UUID=$uuid\en"";""" 4
.el .IP "\f(CWprint ""UUID=$uuid\en"";\fR" 4
.IX Item "print ""UUID=$uuidn"";"
.ie n .IP """untie $uuid;""" 4
.el .IP "\f(CWuntie $uuid;\fR" 4
.IX Item "untie $uuid;"
.PD
.SS "OO-STYLE API"
.IX Subsection "OO-STYLE API"
The OO-style API is a wrapper around the C\-style API and intended for
high-level regular programming.
.ie n .IP """use OSSP::uuid;""" 4
.el .IP "\f(CWuse OSSP::uuid;\fR" 4
.IX Item "use OSSP::uuid;"
.PD 0
.ie n .IP """my $uuid = ""\fBnew\fR"" OSSP::uuid;""" 4
.el .IP "\f(CWmy $uuid = \fR\fBnew\fR\f(CW OSSP::uuid;\fR" 4
.IX Item "my $uuid = new OSSP::uuid;"
.ie n .IP """$uuid\->""\fBload\fR""($name);""" 4
.el .IP \f(CW$uuid\->\fR\fBload\fR\f(CW($name);\fR 4
.IX Item "$uuid->load($name);"
.ie n .IP """$uuid\->""\fBmake\fR""($mode, ...);""" 4
.el .IP "\f(CW$uuid\->\fR\fBmake\fR\f(CW($mode, ...);\fR" 4
.IX Item "$uuid->make($mode, ...);"
.ie n .IP """$result = $uuid\->""\fBisnil\fR""();""" 4
.el .IP "\f(CW$result = $uuid\->\fR\fBisnil\fR\f(CW();\fR" 4
.IX Item "$result = $uuid->isnil();"
.ie n .IP """$result = $uuid\->""\fBcompare\fR""($uuid2);""" 4
.el .IP "\f(CW$result = $uuid\->\fR\fBcompare\fR\f(CW($uuid2);\fR" 4
.IX Item "$result = $uuid->compare($uuid2);"
.ie n .IP """$uuid\->""\fBimport\fR""($fmt, $data_ptr);""" 4
.el .IP "\f(CW$uuid\->\fR\fBimport\fR\f(CW($fmt, $data_ptr);\fR" 4
.IX Item "$uuid->import($fmt, $data_ptr);"
.ie n .IP """$data_ptr = $uuid\->""\fBexport\fR""($fmt);""" 4
.el .IP "\f(CW$data_ptr = $uuid\->\fR\fBexport\fR\f(CW($fmt);\fR" 4
.IX Item "$data_ptr = $uuid->export($fmt);"
.ie n .IP """[(]$str[, $rc)] = $uuid\->""\fBerror\fR""();""" 4
.el .IP "\f(CW[(]$str[, $rc)] = $uuid\->\fR\fBerror\fR\f(CW();\fR" 4
.IX Item "[(]$str[, $rc)] = $uuid->error();"
.ie n .IP """$ver = $uuid\->""\fBversion\fR""();""" 4
.el .IP "\f(CW$ver = $uuid\->\fR\fBversion\fR\f(CW();\fR" 4
.IX Item "$ver = $uuid->version();"
.ie n .IP """undef $uuid;""" 4
.el .IP "\f(CWundef $uuid;\fR" 4
.IX Item "undef $uuid;"
.PD
.PP
Additionally, the strings \f(CW"v1"\fR, \f(CW"v3"\fR, \f(CW"v4"\fR, \f(CW"v5"\fR and \f(CW"mc"\fR
can be used in \f(CW$mode\fR and the strings \f(CW"bin"\fR, \f(CW"str"\fR, and \f(CW"txt"\fR
can be used for \f(CW$fmt\fR.
.SS "C\-STYLE API"
.IX Subsection "C-STYLE API"
The C\-style API is a direct mapping
of the \fBOSSP uuid\fR ISO-C API to Perl and is intended for low-level
programming. See \fBuuid\fR\|(3) for a description of the functions and
their expected arguments.
.ie n .IP """use OSSP::uuid qw(:all);""" 4
.el .IP "\f(CWuse OSSP::uuid qw(:all);\fR" 4
.IX Item "use OSSP::uuid qw(:all);"
.PD 0
.ie n .IP """my $uuid; $rc = ""\fBuuid_create\fR""($uuid);""" 4
.el .IP "\f(CWmy $uuid; $rc = \fR\fBuuid_create\fR\f(CW($uuid);\fR" 4
.IX Item "my $uuid; $rc = uuid_create($uuid);"
.ie n .IP """$rc = ""\fBuuid_load\fR""($uuid, $name);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_load\fR\f(CW($uuid, $name);\fR" 4
.IX Item "$rc = uuid_load($uuid, $name);"
.ie n .IP """$rc = ""\fBuuid_make\fR""($uuid, $mode, ...);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_make\fR\f(CW($uuid, $mode, ...);\fR" 4
.IX Item "$rc = uuid_make($uuid, $mode, ...);"
.ie n .IP """$rc = ""\fBuuid_isnil\fR""($uuid, $result);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_isnil\fR\f(CW($uuid, $result);\fR" 4
.IX Item "$rc = uuid_isnil($uuid, $result);"
.ie n .IP """$rc = ""\fBuuid_compare\fR""($uuid, $uuid2, $result);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_compare\fR\f(CW($uuid, $uuid2, $result);\fR" 4
.IX Item "$rc = uuid_compare($uuid, $uuid2, $result);"
.ie n .IP """$rc = ""\fBuuid_import\fR""($uuid, $fmt, $data_ptr, $data_len);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_import\fR\f(CW($uuid, $fmt, $data_ptr, $data_len);\fR" 4
.IX Item "$rc = uuid_import($uuid, $fmt, $data_ptr, $data_len);"
.ie n .IP """$rc = ""\fBuuid_export\fR""($uuid, $fmt, $data_ptr, $data_len);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_export\fR\f(CW($uuid, $fmt, $data_ptr, $data_len);\fR" 4
.IX Item "$rc = uuid_export($uuid, $fmt, $data_ptr, $data_len);"
.ie n .IP """$str = ""\fBuuid_error\fR""($rc);""" 4
.el .IP "\f(CW$str = \fR\fBuuid_error\fR\f(CW($rc);\fR" 4
.IX Item "$str = uuid_error($rc);"
.ie n .IP """$ver = ""\fBuuid_version\fR""();""" 4
.el .IP "\f(CW$ver = \fR\fBuuid_version\fR\f(CW();\fR" 4
.IX Item "$ver = uuid_version();"
.ie n .IP """$rc = ""\fBuuid_destroy\fR""($uuid);""" 4
.el .IP "\f(CW$rc = \fR\fBuuid_destroy\fR\f(CW($uuid);\fR" 4
.IX Item "$rc = uuid_destroy($uuid);"
.PD
.PP
Additionally, the following constants are exported for use in \f(CW$rc\fR, \f(CW$mode\fR, \f(CW$fmt\fR and \f(CW$ver\fR:
.PP
\&\f(CW\*(C`UUID_VERSION\*(C'\fR,
\&\f(CW\*(C`UUID_LEN_BIN\*(C'\fR,
\&\f(CW\*(C`UUID_LEN_STR\*(C'\fR,
\&\f(CW\*(C`UUID_RC_OK\*(C'\fR,
\&\f(CW\*(C`UUID_RC_ARG\*(C'\fR,
\&\f(CW\*(C`UUID_RC_MEM\*(C'\fR,
\&\f(CW\*(C`UUID_RC_SYS\*(C'\fR,
\&\f(CW\*(C`UUID_RC_INT\*(C'\fR,
\&\f(CW\*(C`UUID_RC_IMP\*(C'\fR,
\&\f(CW\*(C`UUID_MAKE_V1\*(C'\fR,
\&\f(CW\*(C`UUID_MAKE_V3\*(C'\fR,
\&\f(CW\*(C`UUID_MAKE_V4\*(C'\fR,
\&\f(CW\*(C`UUID_MAKE_V5\*(C'\fR,
\&\f(CW\*(C`UUID_MAKE_MC\*(C'\fR,
\&\f(CW\*(C`UUID_FMT_BIN\*(C'\fR,
\&\f(CW\*(C`UUID_FMT_STR\*(C'\fR,
\&\f(CW\*(C`UUID_FMT_SIV\*(C'\fR,
\&\f(CW\*(C`UUID_FMT_TXT\*(C'\fR.
.SH EXAMPLES
.IX Header "EXAMPLES"
The following two examples create the version 3 UUID
\&\f(CW\*(C`02d9e6d5\-9467\-382e\-8f9b\-9300a64ac3cd\*(C'\fR, 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.
.PP
.Vb 8
\&  #   TIE\-style API (very high\-level)
\&  use OSSP::uuid;
\&  tie my $uuid, \*(AqOSSP::uuid::tie\*(Aq;
\&  $uuid = [ "v1" ];
\&  print "UUIDs: $uuid, $uuid, $uuid\en";
\&  $uuid = [ "v3", "ns:URL", "http://www.ossp.org/" ];
\&  print "UUIDs: $uuid, $uuid, $uuid\en";
\&  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\en";
\&
\&  #   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\en";
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBuuid\fR\|(1), \fBuuid\-config\fR\|(1), \fBuuid\fR\|(3).
.SH HISTORY
.IX Header "HISTORY"
The Perl binding \fBOSSP::uuid\fR to \fBOSSP uuid\fR was implemented in
November 2004 by Ralf S. Engelschall <rse@engelschall.com>.