1uuid(3)               User Contributed Perl Documentation              uuid(3)
2
3
4

NAME

6       OSSP::uuid - OSSP uuid Perl Binding
7

DESCRIPTION

9       OSSP uuid is a ISO-C:1999 application programming interface (API) and
10       corresponding command line interface (CLI) for the generation of DCE
11       1.1, ISO/IEC 11578:1996 and RFC 4122 compliant Universally Unique Iden‐
12       tifier (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and
13       node based), version 3 (name based, MD5), version 4 (random number
14       based) and version 5 (name based, SHA-1). Additional API bindings are
15       provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional
16       backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID
17       APIs.
18
19       OSSP::uuid is the Perl binding to the OSSP uuid API.  Three variants
20       are provided:
21
22       TIE-STYLE API
23
24       The TIE-style API is a functionality-reduced wrapper around the OO-
25       style API and intended for very high-level convenience programming:
26
27       "use OSSP::uuid;"
28       tie" my $uuid, 'OSSP::uuid::tie', $mode, ...;"
29       "$uuid = [ $mode, ... ];"
30       "print "UUID=$uuid\n";"
31       "untie $uuid;"
32
33       OO-STYLE API
34
35       The OO-style API is a wrapper around the C-style API and intended for
36       high-level regular programming.
37
38       "use OSSP::uuid;"
39       "my $uuid = "new" OSSP::uuid;"
40       "$uuid->"load"($name);"
41       "$uuid->"make"($mode, ...);"
42       "$result = $uuid->"isnil"();"
43       "$result = $uuid->"compare"($uuid2);"
44       "$uuid->"import"($fmt, $data_ptr);"
45       "$data_ptr = $uuid->"export"($fmt);"
46       "[(]$str[, $rc)] = $uuid->"error"();"
47       "$ver = $uuid->"version"();"
48       "undef $uuid;"
49
50       Additionally, the strings "v1", "v3", "v4", "v5" and "mc" can be used
51       in $mode and the strings "bin", "str", and "txt" can be used for $fmt.
52
53       C-STYLE API
54
55       The C-style API is a direct mapping of the OSSP uuid ISO-C API to Perl
56       and is intended for low-level programming. See uuid(3) for a descrip‐
57       tion of the functions and their expected arguments.
58
59       "use OSSP::uuid qw(:all);"
60       "my $uuid; $rc = "uuid_create"($uuid);"
61       "$rc = "uuid_load"($uuid, $name);"
62       "$rc = "uuid_make"($uuid, $mode, ...);"
63       "$rc = "uuid_isnil"($uuid, $result);"
64       "$rc = "uuid_compare"($uuid, $uuid2, $result);"
65       "$rc = "uuid_import"($uuid, $fmt, $data_ptr, $data_len);"
66       "$rc = "uuid_export"($uuid, $fmt, $data_ptr, $data_len);"
67       "$str = "uuid_error"($rc);"
68       "$ver = "uuid_version"();"
69       "$rc = "uuid_destroy"($uuid);"
70
71       Additionally, the following constants are exported for use in $rc,
72       $mode, $fmt and $ver:
73
74       "UUID_VERSION", "UUID_LEN_BIN", "UUID_LEN_STR", "UUID_RC_OK",
75       "UUID_RC_ARG", "UUID_RC_MEM", "UUID_RC_SYS", "UUID_RC_INT",
76       "UUID_RC_IMP", "UUID_MAKE_V1", "UUID_MAKE_V3", "UUID_MAKE_V4",
77       "UUID_MAKE_V5", "UUID_MAKE_MC", "UUID_FMT_BIN", "UUID_FMT_STR",
78       "UUID_FMT_SIV", "UUID_FMT_TXT".
79

EXAMPLES

81       The following two examples create the version 3 UUID
82       "02d9e6d5-9467-382e-8f9b-9300a64ac3cd", both via the OO-style and the
83       C-style API. Error handling is omitted here for easier reading, but has
84       to be added for production-quality code.
85
86         #   TIE-style API (very high-level)
87         use OSSP::uuid;
88         tie my $uuid, 'OSSP::uuid::tie';
89         $uuid = [ "v1" ];
90         print "UUIDs: $uuid, $uuid, $uuid\n";
91         $uuid = [ "v3", "ns:URL", "http://www.ossp.org/" ];
92         print "UUIDs: $uuid, $uuid, $uuid\n";
93         untie $uuid;
94
95         #   OO-style API (high-level)
96         use OSSP::uuid;
97         my $uuid    = new OSSP::uuid;
98         my $uuid_ns = new OSSP::uuid;
99         $uuid_ns->load("ns:URL");
100         $uuid->make("v3", $uuid_ns, "http://www.ossp.org/");
101         undef $uuid_ns;
102         my $str = $uuid->export("str");
103         undef $uuid;
104         print "$str\n";
105
106         #   C-style API (low-level)
107         use OSSP::uuid qw(:all);
108         my $uuid;    uuid_create($uuid);
109         my $uuid_ns; uuid_create($uuid_ns);
110         uuid_load($uuid_ns, "ns:URL");
111         uuid_make($uuid, UUID_MAKE_V3, $uuid_ns, "http://www.ossp.org/");
112         uuid_destroy($uuid_ns);
113         my $str; uuid_export($uuid, UUID_FMT_STR, $str, undef);
114         uuid_destroy($uuid);
115         print "$str\n";
116

SEE ALSO

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

HISTORY

121       The Perl binding OSSP::uuid to OSSP uuid was implemented in November
122       2004 by Ralf S. Engelschall <rse@engelschall.com>.
123
124
125
126perl v5.8.8                       2006-05-11                           uuid(3)
Impressum