.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "uuid 3pm"
.TH uuid 3pm "2007-01-01" "perl v5.20.0" "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"
\&\fB\s-1OSSP\s0 uuid\fR is a \s-1ISO\-C:1999\s0 application programming interface (\s-1API\s0)
and corresponding command line interface (\s-1CLI\s0) for the generation of
\&\s-1DCE 1.1, ISO/IEC 11578:1996\s0 and \s-1RFC 4122\s0 compliant \fIUniversally Unique
Identifier\fR (\s-1UUID\s0). It supports \s-1DCE 1.1\s0 variant UUIDs of version 1 (time
and node based), version 3 (name based, \s-1MD5\s0), version 4 (random number
based) and version 5 (name based, \s-1SHA\-1\s0). Additional \s-1API\s0 bindings are
provided for the languages \s-1ISO\-\*(C+:1998,\s0 Perl:5 and \s-1PHP:4/5.\s0 Optional
backward compatibility exists for the ISO-C \s-1DCE\-1.1\s0 and Perl Data::UUID
APIs.
.PP
\&\fBOSSP::uuid\fR is the Perl binding to the \fB\s-1OSSP\s0 uuid\fR \s-1API.\s0
Three variants are provided:
.SS "TIE-STYLE \s-1API\s0"
.IX Subsection "TIE-STYLE API"
The TIE-style \s-1API\s0 is a functionality-reduced wrapper around the OO-style
\&\s-1API\s0 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 \s-1API\s0"
.IX Subsection "OO-STYLE API"
The OO-style \s-1API\s0 is a wrapper around the C\-style \s-1API\s0 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 \s-1API\s0"
.IX Subsection "C-STYLE API"
The C\-style \s-1API\s0 is a direct mapping
of the \fB\s-1OSSP\s0 uuid\fR ISO-C \s-1API\s0 to Perl and is intended for low-level
programming. See \fIuuid\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 \s-1UUID
\&\s0\f(CW\*(C`02d9e6d5\-9467\-382e\-8f9b\-9300a64ac3cd\*(C'\fR, both via the OO-style and the
C\-style \s-1API.\s0 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"
\&\fIuuid\fR\|(1), \fIuuid\-config\fR\|(1), \fIuuid\fR\|(3).
.SH "HISTORY"
.IX Header "HISTORY"
The Perl binding \fBOSSP::uuid\fR to \fB\s-1OSSP\s0 uuid\fR was implemented in
November 2004 by Ralf S. Engelschall <rse@engelschall.com>.