grepmail - search mailboxes for a particular email

Grepmail searches a normal, gzip'd, bzip'd, or tzip'd mailbox for a given
regular expression, and returns those emails that match it. Piped input is
allowed, and date and size restrictions are supported.

New in version 4.70:

- Fixed signal handling to make grepmail easier to debug.
- Fixed a possible performance problem in reading of emails (Perl
  implementation), and documented the settings in the README.
- Expanded the pattern for matching the start of emails to allow different
  types of emails to be parsed.
- Fixed a bug where -R was reported as not recognized.
- "anonymize_mailbox" utility included to help people submit bug reports
- If a mailbox can not be found, grepmail now searches the $home/mail,
  $home/Mail, $home/Mailbox directories (or the directory specified by the
  MAIL environment variable).
- Added -X flag to allow the user to specify a pattern for the signature
  separator.
- Added -Y flag to search specific headers.


MODULE DEPENDENCIES

grepmail, by itself, can search mailboxes based on regular expression
patterns. However, if you want to search based on date, the
Date::Parse module is required. If you want to use more complex date
specifications, then Date::Manip should be installed as well.

Starting with version 4.44, an additional module is distributed with
grepmail, called Mail::Folder::FastReader. It implements the email
reading capability in C for 10-20% faster execution, depending on your
system. This module is compiled and installed during the installation
of grepmail (see below). You will need Inline version 0.41 or better.

The Date::Parse module is part of the TimeDate distribution, which can be
downloaded from:

  http://www.perl.com/CPAN/authors/id/GBARR/

Date::Manip is at:

  http://www.perl.com/CPAN/authors/id/SBECK/

Alternatively, installation can be done automatically using the CPAN module:

  perl -MCPAN -e 'install Date::Parse'
  perl -MCPAN -e 'install Date::Manip'


INSTALLATION

=> On Non-Windows systems:

  % perl Makefile.PL
  % make
  % make test
  % make install

By default, "perl Makefile.PL" does an interactive installation. You can avoid
the question about installing Mail::Folder::FastReader by specifying either
"FASTREADER=0" or "FASTREADER=1". You can avoid the question about the
installation location by specifying either "PREFIX=/installation/path" (for
installation into a custom location), "INSTALLDIRS=site" (for installation
into site-specific Perl directories), or "INSTALLDIRS=perl" (for installation
into standard Perl directories).

If make test fails, please see the INSTALLATION PROBLEMS section below.

=> On Windows systems:

- Just copy "grepmail" to a place in your path. You may want to rename it
  "grepmail.pl" if you've associated .pl files with perl.exe.


CONFIGURATION

You may want to set your MAIL environment variable so that grepmail will know
the default location to search for mailboxes.

If you are terribly concerned about performance, you may want to modify the
value of the variable READ_CHUNK_SIZE located in the code. This variable
controls how much text is read from the mailbox at a time. If the value is set
to 0, the entire file is read into memory. (There is no user-visible option
for setting this value.)

If you frequently use the same set of flags, you may wish to alias "grepmail"
to "grepmail -flags" within your command interpreter (shell). See the
documentation for your shell for details on how to do this.


INSTALLATION PROBLEMS

If "make test" fails, run

  make testfunc

and see which test(s) are failing. Please email, to the address below, the
test##.stderr and test##.stdout files for the test, which are located in
t/results. Also email the output of running the test with the -D flag. e.g.:

  blib/script/grepmail library -D -d "before July 9 1998" t/mailarc-1.txt \
    > test##.debug

If you see errors about your timezone, and you are in an uncommon timezone, it
may be the case that Date::Manip does not support your timezone yet. Try this:

  perl -MDate::Manip -e 'print "TIMEZONE: ".&Date::Manip::Date_TimeZone."\n"'

If you get an error, contact the author of Date::Manip.

For other bugs, see the section REPORTING BUGS below.


DOCUMENTATION

Just "perldoc grepmail". After installation on Unix systems, you can also do
"man grepmail".


HOMEPAGE

Visit http://grepmail.sourceforge.net/ for the latest version, mailing lists,
discussion forums, CVS access, and more.


REPORTING BUGS

You can report bugs at http://sourceforge.net/bugs/?group_id=2207.  Please
attach the output of running grepmail with the -D switch. If the bug is
related to processing of a particular mailbox, try to trim the mailbox to the
smallest set of emails that still exhibit the problem.  Then use the
"anonymize_mailbox" program that comes with grepmail to remove any sensitive
information, and attach the mailbox to the bug report.


PRIMARY AUTHOR

Written by David Coppit (david@coppit.org, http://coppit.org/), with the
generous help of many kind people. See the file CHANGES for detailed
information.


LICENSE

This code is distributed under the GNU General Public License (GPL). See
http://www.opensource.org/gpl-license.html and http://www.opensource.org/.