NAME

IO::File::Log - IO::File abstraction on logging files

SYNOPSIS

  use IO::File::Log;

  my $fh = new IO::File::Log "mylogfile";

  while (my $line = $fh->readline) {
      # Your code here...
  }

  my @remaining = $fh->getlines;

DESCRIPTION

Under this discussion, a log file refers to the classical notion of a daemon's log file, that is, a file that can be appended to at any time or that can be "rotated" (ie, the original file can be rename()d and a new file with the same name created in its place).

This method provides an abstraction that allows reading operations to occur almost transparently from those files (see CAVEATS later on for more information). This extension deals with the possibility of the file being rotated, appended to, etc.

Note however that the basic assumption for reading a log file, is that it never ends. The general algorythm for this module is as follows:

At ->new(), set the file pointer to the beginning of the file and store the file's metadata as object state.

At any traditional IO::File operation, perform it on the current file position and store the resulting file ponter's position.

At EOF, poll the system to detect a new file with the same name given to ->new() but different metadata. When found, open this new file and fulfill the pending operation in the new file.

CAVEATS

Note that ->getlines() will only return the list of lines on the file, up to the EOF. Otherwise, this method would block forever as the basic assumption is that log files always grow. It is important to note that if the daemon (or the sysadmin) is not careful about proper log rotation, it might be possible to hang or to read a block of text in an unexpected format.

As a caveat, IO::File::Log only supports reading from standard files, therefore the only valid way to call ->new() is to specify the desired file name of the log file to read. Writing may or may not work, and is unsupported and deprecated.

Also, not all the functions of the IO::* family are supported. Currently, only getlines and getline are supported. More functions may be added in the future, as the need arise.

Care must be taken when working with seek() and friends. It might be possible for a log to be rotated between a tell() and a seek(). This would cause unexpected results.

Note that if the log file is truncated, there's a very good chance of this event being missed altogether, as in this case the file's metadata does not change. In order to try to catch this event in more situations, the current file length is compared with the current file position. If the file position is beyond the current file length, the file is assumed to have changed.

Users are encouraged to write the login of the program that uses this module to reset the log file manually when a read from it returns undef or whenever an EOF condition is seen. The ->_reset() method can be used to force the module to close and re-open the log file.

EXPORT

None by default.

HISTORY

1.00

Original version; created by h2xs 1.1.1.4 with options

  -ACOXcfkn
        IO::File::Log
        -v
        1.00

Tested under Darwin (Mac OS X 10.1.3).

1.01

Fixes for cases where log rotation is too slow (ie, a lot of time passes between the rename() of the existing log file and its creation). This produced a small change on semantics, where an operation blocked at the enf-of-file will return as soon as the new file is created and data is written to it.

AUTHOR

Luis E. Munoz <luismunoz@cpan.org>

SEE ALSO

perl(1).