GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LOG::PROCMAIL (3)

.ds Aq ’

NAME

Log::Procmail - Perl extension for reading procmail logfiles.

CONTENTS

SYNOPSIS



    use Log::Procmail;

    my $log = new Log::Procmail procmail.log;

    # loop on every abstract
    while(my $rec = $log->next) {
        # do something with $rec->folder, $rec->size, etc.
    }



DESCRIPTION

    Log::Procmail

Log::Procmail reads procmail(1) logfiles and returns the abstracts one by one.
$log = Log::Procmail->new( @files ); Constructor for the procmail log reader. Returns a reference to a Log::Procmail object.

The constructor accepts a list of file as parameter. This allows you to read records from several files in a row:



    $log = Log::Procmail->new( "$ENV{HOME}/.procmail/log.2",
                               "$ENV{HOME}/.procmail/log.1",
                               "$ENV{HOME}/.procmail/log", );



When $log reaches the end of the file log, it doesn’t close the file. So, after <B>procmailB> processes some incoming mail, the next call to next() will return the new records.

$rec = $log->next Return a Log::Procmail::Abstract object that represent an entry in the log file. Return undef if there is no record left in the file.

When the Log::Procmail object reaches the end of a file, and this file is not the last of the stack, it closes the current file and opens the next one.

When it reaches the end of the last file, the file is not closed. Next time the record method is called, it will check again in case new abstracts were appended.

Procmail(1) log look like the following:



    From karen644552@btinternet.com  Fri Feb  8 20:37:24 2002
     Subject: Stock Market Volatility Beating You Up? (18@2)
      Folder: /var/spool/mail/book                                                 2840



Some informational messages can be put by procmail(1) in the log file. If the errors attribute is true, these lines are returned one at a time.

With errors enabled, you have to check that next() actually returns a Log::Procmail::Abstract object. Here is an example:



    $log->errors(1);

    # fetch data
    while ( $rec = $log->next ) {

        # if its an error line
        if ( !ref $rec ) {
            # this is not a log, but an informational message
            # do something with it
            next;
        }

        # normal log processing
    }



$log->push( $file [, $file2 ...] ); Push one or more files on top of the list of log files to examine. When Log::Procmail runs out of abstracts to return (i.e. it reaches the end of the file), it transparently opens the next file (if there is one) and keeps returning new abstracts.
$log->errors( [bool] ); Set or get the error flag. If set, when the next() method will return the string found in the log file, instead of ignoring it. Be careful: it is a simple string, not a Log::Procmail::Abstract object.

Default is to return no error.

$fh = $log->fh() Returns the currently opened filehandle, from which the next call to next() will try to read a record.
$select = $log->select() Return a IO::Select object that watches the currently opened filehandle.

<B>You are not supposed to use B>add()<B> or B>remove()<B> on the returned IO::Select object.B>

<B>Additional warning for B>MSWin32<B>, B>NetWare<B>, B>dos<B>, B>VMS<B>, B>riscos<B> and B>beos<B>:B> on those systems, select() returns undef. (Check ext/IO/t/io_sel.t in the Perl sources for details. Hint: look for the message 4-arg select is only valid on sockets.)

    Log::Procmail::Abstract

Log::Procmail::Abstract is a class that hold the abstract information. Since the abstract hold From, Date, Subject, Folder and Size information, all this can be accessed and modified through the from(), date(), subject(), folder() and size() methods.

Log::Procmail::next() returns a Log::Procmail::Abstract object.
Log::Procmail::Abstract accessors The Log::Procmail::Abstract object accessors are named from(), date(), subject(), folder() and size(). They return the relevant information when called without argument, and set it to their first argument otherwise.



    # count mail received per folder
    while( $rec = $log->next ) { $folder{ $rec->folder }++ }



The source() accessor returns the name of the log file or the string representation of the handle, if a filehandle was given.

$rec->ymd() Return the date in the form yyyymmmddhhmmss where each field is what you think it is. ;-) This method is read-only.

EXAMPLES

Here is an example procmail biff-like script, courtesy of Ian Langworth:



    #/usr/bin/perl -w
    use strict;
    use Log::Procmail;

    use constant LOGFILE       => "$ENV{HOME}/procmail.log";
    use constant VALID_FOLDERS => [qw( agent inbox perl systems )];
    my $format = "\%8s: \%-30.30s / %s\n";

    my $log = Log::Procmail->new( LOGFILE );
    $log->errors(1);

    while ( $log->select->can_read ) {
        my $rec = $log->next;

        # error?
        warn "$rec\n", next unless ref $rec;

        # ignore mailboxes we dont care about
        next unless grep { $_ eq $rec->folder } @{ VALID_FOLDERS() };

        # print data
        printf $format, From    => $rec->from;
        printf $format, Subject => $rec->subject, $rec->folder;
    }



TODO

The Log::Procmail object should be able to read from STDIN.

BUGS

o Sometimes procmail(1) logs are mixed up. When this happens, I’ve chosen to accept them the way mailstat(1) does: they are discarded unless they have a Folder line.
o If you use Log::Procmail and the select() method to follow a live logfile as in the above example, please not that Log::Procmail will not detect when the file is rotated.
Please report all bugs through the rt.cpan.org interface:

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Log-Procmail>

AUTHOR

Philippe BooK Bruhat <book@cpan.org>.

ACKNOWLEDGMENTS

Thanks to Briac Oeufmayo Pilpre\k:'and David Sniper Rigaudiere for early comments on irc. Thanks to Olivier rs Poitrey for giving me his huge procmail log file (51 Mb spanning over a two-year period) and for probably being the first user of this module. Many thanks to Michael Schwern for insisting so much on the importance of tests and documentation.

Many thanks to Les Mongueurs de Perl for making cvs.mongueurs.net available for Log::Procmail and many other projects.

COPYRIGHT

Copyright (c) 2002-2013, Philippe Bruhat. All Rights Reserved.

LICENSE

This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)

SEE ALSO

perl(1), procmail(1).
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 LOG::PROCMAIL (3) 2013-01-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.