Concept
-------

This is a rewriting of Mike Wang's 'pguuid' library
to use the libuuid from the ext2fs utilities,  which is
built as a separate dynamic library on Linux.

My goal is to get this to compile on Postgres 8.0 through
8.2; the UUID type is included in 8.3,  although no
native generator is provided.

UUIDs are a cool concept,  but a simple attempt at
generating them is likely to fall short of the "universal"
selling point, especially for a user-level process that's
suppposed to compile and run on any POSIX-compliant system
Modern Linux is a little bit better.  /dev/urandom is 
probably random enough to use literally (or as a seed)
for random UUIDs.  I don't like some of the choices 
in e2fs-libuuid;  for instance,  the PID is used to
initialize 16 bits, but then those same bits are mixed
with randomness,  meaning that if two processes both
use the library,  there's a 1-in-65000 chance they 
will be depending on only time-resolution for uniquness.

However, Mike Wang's code was more stripped-down than 
that,  and it's better to have all the bugs in one place.

Installation
------------

Choose the version that most closely matches your Postgres
version; the C UDF ABI has changed slightly from version to 
version, and the uuid type (but no generator-functions such
as the ones provided here) was merged into core during the
8.3 development phase.  Follow the instructions in 'INSTALL'
in the corresponding directory.

Usage
-----

The "for-8.1" and "for-8.2" versions provide a "uuid" type
definition which is stored internally as 16-byte binary
but accepts text input in 38-, 36- or 32-character form
and gives output in standard 26-character form.

All three versions provide the following functions for
generating and working with UUIDs:

newid() - generates a new UUID, randomly if it feels like it

newid_time() - generates a new UUID, using time- and MAC-information

newid_random() - generates a new UUID, always randomly

newid_nil() - makes a copy of the all-zeroes UUID

uuid_variant() - return the "variant" code,  always 1 for 
the UUIDs these functions generate

uuid_type() - return the type, 1=time, 4=random

uuid_time() - return the time when a time-based UUID was generated
(only accurate to the second; NULL for random ones)

uuid_macaddr() - return the MAC address where a time-based UUID
was generated (NULL for random ones)

In addition, it is simple to define the following functions to
replace calls to "ossp-uuid" with calls to this library:

uuid_generate_v1() - generates a new UUID, using time- and MAC-information

uuid_generate_v4() - generates a new UUID, always randomly

A note on the license
---------------------

I originally based this library on work by Mike Wang, who said
that he had used the GPL only because he copied in some generator
code that had been covered by the GPL.  I attempted to contact
him for clarification and was unable to do so.  I have removed all
actual generator code, and what remains from that initial import
is arguably more similar to the code in (BSD-licensed) core and 
other (BSD-licensed) generators than to his code.

I personally have no objection to this code being used under a
standard 3-clause BSD license; but a commercial developer and 
redistributor might want to carry out independent due diligence.

In any case, the ext2fs library is distributed under the LGPL.

Author
------

David L. Lambert <davidl@lmert.com>

