Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Log::Procmail(3)      User Contributed Perl Documentation     Log::Procmail(3)

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

	   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.

       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", );

	   When	$log reaches the end of	the file "log",	it doesn't close the
	   file.  So, after procmail 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	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:


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

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

		   # 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

	   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

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

	   Additional warning for "MSWin32", "NetWare",	"dos", "VMS", "riscos"
	   and "beos": 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 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.

	   Return the date in the form "yyyymmmddhhmmss" where each field is
	   what	you think it is. ";-)" This method is read-only.

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

	   #/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 );

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

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

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

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

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

       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 interface:


       Philippe	"BooK" Bruhat <>.

       Thanks to Briac "Oeufmayo" PilprA(C) 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

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

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

       This module is free software. It	may be used, redistributed and/or
       modified	under the terms	of the Perl Artistic License (see

       perl(1),	procmail(1).

perl v5.32.0			  2013-01-02		      Log::Procmail(3)


Want to link to this manual page? Use this URL:

home | help