ossp-pkg/uuid/uuid.pod
1.1
##
## OSSP uuid - Universally Unique Identifier
## Copyright (c) 2004 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2004 The OSSP Project <http://www.ossp.org/>
##
## This file is part of OSSP uuid, a library for the generation
## of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
## uuid.pod: manual page
##
=pod
=head1 NAME
B<OSSP uuid> - B<Universally Unique Identifier>
=head1 SYNOPSIS
...FIXME...
=head1 DESCRIPTION
=head2 Overview
B<UUID> stands for B<U>niversal B<U>nique B<ID>entifier (aka B<GUID>
which stands for B<G>lobally B<U>nique B<ID>entifier). B<UUID>s are 128
bit numbers assigned to any object and which are intended to have a high
likelihood of uniqueness over space and time and are computationally
difficult to guess.
A B<UUID> is usually encoded using the ASCII character string
representation described in ISO/IEC 11578:1996: a string
consisting of 8 hexadecimal digits followed by a hyphen,
then three groups of 4 hexadecimal digits each followed by a
hyphen, then 12 hexadecimal digits. An example of a B<UUID> is
"C<54531d28-402b-11d8-af12-0002a5094c23>".
=head2 Uniqueness
The mechanism used to guarantee that B<UUID>s are unique is
through combinations of hardware addresses, time stamps and random
seeds.
There is a reference in the B<UUID> to the hardware (MAC) address of
the first network interface card (NIC) on the host which generated the
B<UUID> -- this reference is intended to ensure the B<UUID> will be
unique in space as the MAC address of every network card is assigned by
a single global authority (IEEE) and is guaranteed to be unique.
The next component in a B<UUID> is a timestamp which, as clock always
(should) move forward, will be unique in time.
Just in case some part of the above goes wrong (the hardware address
cannot be determined or the clock moved a step backward), there is
a random component placed into the B<UUID> as a "catch-all" for
uniqueness.
=head1 APPLICATION PROGRAMMING INTERFACE
...FIXME...
=head1 SEE ALSO
See the following are references to more B<UUID> documentation and specifications:
=over 4
=item
B<UUIDs and GUIDs>,
IETF Internet Draft (expired),
Paul J. Leach, Rich Salz,
February 1998, 27 pages,
http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt
=item
B<DCE 1.1: Remote Procedure Call>,
appendix B<Universally Unique Identifier>,
Open Group Technical Standard
Document Number C706, August 1997, 737 pages,
(supercedes C309 DCE: Remote Procedure Call 8/1994,
which was basis for ISO/IEC 11578:1996 specification),
http://www.opengroup.org/publications/catalog/c706.htm
=item
B<Information technology -- Open Systems Interconnection (OSI) -- Remote Procedure Call (RPC)>,
ISO/IEC 11578:1996,
August 2001, 570 pages, (CHF 340,00),
http://www.iso.ch/cate/d2229.html
=item
B<HTTP Extensions for Distributed Authoring (WebDAV)>,
section B<6.4.1 Node Field Generation Without the IEEE 802 Address>,
IETF RFC 2518,
February 1999, 94 pages,
http://www.ietf.org/rfc/rfc2518.txt
=item
B<A UUID URN Namespace>,
P. Leach, M. Mealling, R. Salz,
IETF Internet Draft draft-mealling-uuid-urn-01,
October 2003, 31 pages,
http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-01.txt
=item
B<DCE 1.1 compliant UUID functions>,
FreeBSD manual pages uuid(3) and uuidgen(2),
http://www.freebsd.org/cgi/man.cgi?query=uuid&manpath=FreeBSD+5.2-RELEASE
=cut
