NAME
    UUID - Universally Unique Identifier library for Perl

SYNOPSIS
        use UUID qw(uuid uuid1 uuid4);    # see EXPORTS

        $str = uuid();                    # new stringified UUID; prefer v4
        $str = uuid1();                   # new stringified UUID; always v1
        $str = uuid4();                   # new stringified UUID; always v4
        $str = uuid6();                   # new stringified UUID; always v6
        $str = uuid7();                   # new stringified UUID; always v7

        UUID::generate($bin);             # new binary UUID; prefer v4
        UUID::generate_v1($bin);          # new binary UUID; always v1
        UUID::generate_v4($bin);          # new binary UUID; always v4
        UUID::generate_v6($bin);          # new binary UUID; always v6
        UUID::generate_v7($bin);          # new binary UUID; always v7

        UUID::generate_time($bin);        # alias for generate_v1()
        UUID::generate_random($bin);      # alias for generate_v4()

        UUID::unparse($bin, $str);        # stringify $bin; prefer lowercase
        UUID::unparse_lower($bin, $str);  # force lowercase stringify
        UUID::unparse_upper($bin, $str);  # force uppercase stringify

        UUID::parse($str, $bin);          # map string to binary UUID

        UUID::compare($bin1, $bin2);      # compare binary UUIDs
        UUID::copy($dst, $src);           # copy binary UUID from $src to $dst

        UUID::clear($bin);                # set binary UUID to NULL
        UUID::is_null($bin);              # compare binary UUID to NULL

        UUID::time($bin);                 # return UUID time
        UUID::type($bin);                 # return UUID type
        UUID::variant($bin);              # return UUID variant
        UUID::version($bin);              # return UUID version

DESCRIPTION
    The UUID library is used to generate unique identifiers for objects that
    may be accessible beyond the local system. For instance, they could be
    used to generate unique HTTP cookies across multiple web servers without
    communication between the servers, and without fear of a name clash.

    The generated UUIDs can be reasonably expected to be unique within a
    system, and unique across all systems, and are compatible with those
    created by the Open Software Foundation (OSF) Distributed Computing
    Environment (DCE).

    All generated UUIDs are either version 1 or version 4. And all are
    variant 1, meaning compliant with the OSF DCE standard as described in
    RFC4122.

FUNCTIONS
    Most of the UUID functions expose the historically underlying libuuid
    C interface rather directly. That is, many return their values in their
    parameters and nothing else.

    Not very Perlish, is it? It's been like that for a long time now, so not
    likely to change any time soon.

    All take or return UUIDs in either binary or string format. The string
    format resembles the following:

        21b081a3-de83-4480-a14f-e89a1dcf8f0f

    Or, in terms of printf(3) format:

        "%08x-%04x-%04x-%04x-%012x"

    The binary form is simply a packed 16 byte binary value.

  clear( $uuid )
    Sets $uuid equal to the value of the NULL UUID.

  compare( $uuid1, $uuid2 )
    Compares two binary UUIDs.

    Returns an integer less than, equal to, or greater than zero if $uuid1
    is less than, equal to, or greater than $uuid2.

    However, if either operand is not a UUID, falls back to a simple string
    comparison returning similar values.

  copy( $dst, $src )
    Copies the binary $src UUID to $dst.

    If $src isn't a UUID, $dst is set to the NULL UUID.

  generate( $uuid )
    Generates a new version 4 binary UUID based on high quality randomness
    from /dev/urandom or /dev/random, if available.

    If not, a new version 1 binary UUID is returned.

    The previous content of $uuid, if any, is lost.

  generate_random( $uuid )
    Generates a new version 4 binary UUID even if a high-quality random
    number generator (e.g., /dev/urandom) is not available, in which case
    a pseudo-random generator is used.

    Note that the use of a pseudo-random generator may compromise the
    uniqueness of UUIDs generated in this fashion.

    If /dev/urandom and/or /dev/random are present, the system calls
    get_random() and/or get_entropy() are used first, if available.

    If the system calls are not available, randomness is read directly from
    the random devices, preferring /dev/urandom but falling back to
    /dev/random in non-blocking mode.

  generate_time( $uuid )
    Generates a new version 1 binary UUID using the current time and the
    local ethernet MAC address, if available.

    If the MAC address is not available at startup, or a randomized address
    is requested (see :mac in EXPORTS), a random address is used. The
    multicast bit of this address is set to avoid conflict with addresses
    returned from network cards.

    This algorithm used to be the default for generating UUIDs, but because
    of privacy concerns, the generate() function only uses it if a
    high-quality source of randomness is not available.

  generate_v1( $uuid )
    Alias for generate_time().

  generate_v4( $uuid )
    Alias for generate_random().

  is_null( $uuid )
    Compares the value of $uuid to the NULL UUID.

    Returns 1 if NULL, and 0 otherwise.

  parse( $string, $uuid )
    Converts the string format UUID in $string to binary and returns in
    $uuid. The previous content of $uuid, if any, is lost.

    Returns 0 on success and -1 on failure. Additionally on failure, the
    content of $uuid is unchanged.

  time( $uuid )
    Returns the time element of a binary UUID in seconds since the epoch,
    the same as Perl's time function.

    Keep in mind this only works for type 1 UUIDs. Values returned from
    other types range from non-standardized to totally random.

  type( $uuid )
    Returns the type of binary $uuid.

    This module only generates type 1 (time) and type 4 (random) UUIDs, but
    others may be found in the wild.

    Known types: 1 a.k.a. Version 1 - date/time and MAC address 2 a.k.a.
    Version 2 - date/time and MAC address, security version 3 a.k.a. Version
    3 - namespace based, MD5 hash 4 a.k.a. Version 4 - random 5 a.k.a.
    Version 5 - namespace based, SHA-1 hash

  unparse( $uuid, $string )
    Converts the binary UUID in $uuid to string format and returns in
    $string. The previous content of $string, if any, is lost.

    Prior to version 0.32, casing of the return value was system-dependent.
    Later versions are lower case, per RFC4122.

  unparse_lower( $uuid, $string )
    Same as unparse().

  unparse_upper( $uuid, $string )
    Same as unparse() but $string is forced to upper case.

  uuid()
    Creates a new string format UUID and returns it in a more Perlish way.

    Functionally the equivalent of calling generate() and then unparse(),
    but throwing away the intermediate binary UUID.

  uuid1()
    Same as uuid() but always version 1.

  uuid4()
    Same as uuid() but always version 4.

  variant( $uuid )
    Returns the variant of binary $uuid.

    This module only generates variant 1 UUIDs, but others may be found in
    the wild.

    Known variants:

        0  NCS
        1  DCE
        2  Microsoft
        3  Other

  version( $uuid> )
    Alias for type().

MAINTAINING STATE
    Internal state is optionally maintained for version 1 UUIDs via a file
    designated by the :persist export tag (see EXPORTS), if the path exists
    and the user running the process has read/write permission.

    If the file doesn't exist, it is created if the directory path exists.

    The file records various internal states at the time the last UUID is
    generated, preventing future instances from overlapping the prior UUID
    sequence. This allows the sequence to absolutely survive reboots and,
    more importantly, backwards resetting of system time.

    If :persist is not used, time resets will still be detected while the
    module is loaded and handled accordingly. And since startup in this case
    is randomized anyway, the chance of overlap is low but still exists. The
    randomized clock_seq field is 14 bits wide.

    Note that use of this feature incurs a serious performance penalty,
    upwards of 90% on tested platforms.

    Note too that use of a random MAC greatly reduces the chance of overlap.
    The randomized fields total 62 bits at start.

EXPORTS
    None by default. All functions may be imported in the usual manner,
    either individually or all at once using the :all tag.

  :mac=mode
    The MAC address used for v1 UUIDS is forced to always be random in one
    of two modes:

        random The MAC address is generated once at startup and used
        throughout the lifetime of the process. This is the default if the
        real MAC cannot be found.

        unique A new MAC address is generated for each new UUID. It is not
        guaranteed to be unique beyond the probability of randomness.

  :persist=path/to/state.txt
    Path to version 1 state maintenance file. (See MAINTAINING STATE.) The
    path may be either relative or absolute.

    If the file does not exist, it will be created provided the path exists
    and the user has permission.

    If the file cannot be opened, cannot be created, or is a symlink, UUID
    will ignore it. No state will be maintained.

    WARNING: Do not :persist in a public directory. See CVE-2013-4184. UUID
    attempts to avoid this, but nothing is foolproof. Only YOU can prevent
    symlink attacks!

THREAD SAFETY
    This module is believed to be thread safe.

UUID LIBRARY
    Releases prior to UUID-0.32 required libuuid or similar be installed
    first. This is no longer the case. Version 0.33 bundled the e2fsprogs
    UUID code, and version 0.34 removed it altogether.

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2014-2024 by Rick Myers.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

    Details of this license can be found within the 'LICENSE' text file.

AUTHOR
    Current maintainer:

      Rick Myers <jrm@cpan.org>.

    Authors and/or previous maintainers:

      Lukas Zapletal <lzap@cpan.org>

      Joseph N. Hall <joseph.nathan.hall@gmail.com>

      Colin Faber <cfaber@clusterfs.com>

      Peter J. Braam <braam@mountainviewdata.com>

CONTRIBUTORS
    David E. Wheeler

    William Faulk

    gregor herrmann

    Slaven Rezic

    twata

SEE ALSO
    RFC4122

    uuid(3), uuid_clear(3), uuid_compare(3), uuid_copy(3), uuid_generate(3),
    uuid_is_null(3), uuid_parse(3), uuid_unparse(3), perl(1).

