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

FreeBSD Manual Pages

  
 
  

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

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

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 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 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	it's 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.

	   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
       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 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;
	   }

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" 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
       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).

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

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | TODO | BUGS | AUTHOR | ACKNOWLEDGMENTS | COPYRIGHT | LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Procmail&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help