/ 
Data-ID-Exim-0.001
River stage zero No dependents
/ Data::ID::Exim

NAME

Data::ID::Exim - generate Exim message IDs

SYNOPSIS

use Data::ID::Exim qw(exim_mid);

$mid = exim_mid;

use Data::ID::Exim qw(read_exim_mid);

($sec, $usec, $pid) = read_exim_mid($mid);

DESCRIPTION

This module exports one function, exim_mid, which generates IDs using the algorithm that the Exim MTA uses to generate message IDs.

FUNCTIONS

exim_mid

Generates an Exim message ID. (This ID may, of course, be used to label things other than mail messages, but Exim refers to them as message IDs.) The ID is based on the time and process ID, such that it is guaranteed to be unique among IDs generated by this algorithm on this host. This function is completely interoperable with Exim, in the sense that it uses exactly the same algorithm so that the uniqueness guarantee applies between IDs generated by this function and by Exim itself.

The format of the message ID is three groups of base 62 digits, separated by hyphens. The first group, of six digits, gives the integral number of seconds since the epoch. The second group, also of six digits, gives the process ID. The third group, of two digits, gives the fractional part of the number of seconds since the epoch, in units of 1/2000 of a second (500us). The function does not return until the clock has advanced far enough that another call would generate a different ID.

The strange structure of the ID comes from compatibility with earlier versions of Exim, in which the last two digits were a sequence number.

exim_mid(HOST_NUMBER)

Exim has limited support for making message IDs unique among a group of hosts. Each host is assigned a number in the range 0 to 16 inclusive. The last two digits of the message IDs give the host number multiplied by 200 plus the fractional part of the number of seconds since the epoch in units of 1/200 of a second (5ms). This makes message IDs unique across the group of hosts, at the expense of generation rate.

To generate this style of ID, pass the host number to exim_mid. The host number must be configured by some out-of-band mechanism.

read_exim_mid(MID)

This function extracts the information encoded in an Exim message ID. This is a slightly naughty thing to do: the ID should really only be used as a unique identifier. Nevertheless, the time encoded in an ID is sometimes useful.

The function returns a three-element list. The first two elements encode the time at which the ID was generated, as a (seconds, microseconds) pair giving the time since the epoch. This is the same time format as is returned by gettimeofday. The message ID does not encode the time with a resolution as great as a microsecond; the returned microseconds value is rounded down appropriately. The third item in the result list is the encoded PID.

read_exim_mid(MID, HOST_NUMBER_P)

The optional HOST_NUMBER_P argument is a boolean indicating whether the message ID was encoded using the variant algorithm that includes a host number in the ID. It is essential to decode the ID using the correct algorithm. The host number, if present, is returned as a fourth item in the result list.

BUGS

Can theoretically generate duplicate message IDs during a leap second. Exim suffers the same problem.

SEE ALSO

Data::ID::Maildir, UUID, Win32::Genguid, http://www.exim.org

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2004 Andrew Main (Zefram) <zefram@fysh.org>

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.