mboxgrep/doc/mboxgrep.texi

\input texinfo
@setfilename mboxgrep.info
@settitle Grep through mailboxes
@finalout
@setchapternewpage odd

@set EDITION 0.7
@set VERSION 0.7.12a
@set UPDATED 23 September 2024

@dircategory Mail
@direntry
* mboxgrep: (mboxgrep).		A mail folder scanning utility.
@end direntry

@node Top, , , (dir)

@ifinfo
This file documents @code{mboxgrep} (version @value{VERSION}), a
mailbox scanning utility.

Copyright (C) 2000 - 2003, 2024 Daniel Spiljar
@end ifinfo

@menu
* Introduction::	A short preface.
* Invoking::		Command-line arguments.
* Examples::		A few examples of usage.
* Bugs::		What to do with bugs and similar vermin.

* To Vicky::            Author's dedication.
@end menu

@node Introduction, Invoking, , Top
@chapter Introduction

@cindex introduction
@cindex preface

@code{mboxgrep} is a small, non-interactive utility that scans mail folders 
for messages matching regular expressions.  

It supports basic and extended POSIX regular expressions.  @code{Perl}-style 
regular expressions are supported as well, if @code{mboxgrep} is linked with 
PCRE library.

Found messages can be either displayed on standard output, counted, deleted, 
piped to a specified command, or copied to another mailbox.

It can read and write a variety of folder formats: 

@itemize @bullet
@item
mbox folders, either plain or compressed
@item
MH folders 
@item nnml and nnmh folders used by Gnus 
@item @code{qmail}-style maildirs
@end itemize

Additionally, it can read mbox folders or output from another @code{mboxgrep}
process from standard input.  It does so if a single dash (-) is given
as a file name.

@node Invoking, Examples, Introduction, Top
@chapter Command-Line Arguments
@cindex arguments

The syntax of @code{mboxgrep} invocation is:

@example
mboxgrep [OPTIONS] PATTERN [MAILBOX]
@end example

@menu
* Miscellaneous::
* File locking::
* Regexp selection::
* Output control::
* Search scope selection::
* Mailbox type selection::
@end menu

@node Miscellaneous, File locking, , Invoking

@table @samp
@item --help
@itemx -h
Display a brief help screen and exit.

@item --version
@itemx -V
Display program version and copyright information and exit.

@item --recursive
@itemx -r
Descend into directories recursively.

@end table

@node File locking, Regexp selection, Miscellaneous, Invoking

When accessing mbox folders, @code{mboxgrep} puts a shared lock on
files by default.  Note that mbox folders normally should not be accessed 
without locking.  

@table @samp

@item --file-lock=METHOD
@itemx -l METHOD
Specify file locking METHOD.  @code{mboxgrep} supports @code{flock} and 
@code{fcntl} file locking.  However, one of these methods may be 
unimplemented on your operating system and thus not available in 
@code{mboxgrep} at run time.  To disable file locking, specify @code{none}.

@item --no-file-lock
@itemx -nl
Do not attempt to lock mbox folder files.

@end table

@node Regexp selection, Output control, File locking, Invoking

@table @samp

@item --extended-regexp
@itemx -E
PATTERN is an extended regular expression.

@item --basic-regexp
@itemx -G
PATTERN is a basic regular expression.

@item --perl-regexp
@itemx -P
PATTERN is a Perl regular expression.

@item --regexp=PATTERN
@itemx -e PATTERN
Use PATTERN as a regular expression.

@item --ignore-case
@itemx -i
Perform case-insensitive search.

@item --invert-match
@itemx -v
Invert the sense of matching, i.e. select only non-matching messages.

@end table

@node Output control, Search scope selection, Regexp selection, Invoking

By default, @code{mboxgrep} writes found messages to standard output.
The options below change such behavior.

@table @samp

@item --count
@itemx -c
Suppress normal output and print the count of matching (or non-matching,
if used with the @code{-v} option) messages.

@item --delete
@itemx -d
Suppress normal output and delete selected messages. 

Use with extreme caution.

@item --no-duplicates
@itemx -nd
Ignore duplicate messages.

@item --output=MAILBOX
@itemx -o MAILBOX
Suppress normal output and write messages to destination MAILBOX instead.

Note that @code{mboxgrep} assumes the output folder is of the same format 
as the input folder.  Currently there is no possibility to convert folders.

@item --pipe=COMMAND
@itemx -p COMMAND
Suppress normal output and pipe each selected message to a separate
instance of COMMAND.

@item --no-messages
@itemx -s
Suppress error messages.

@item --debug
Print messages useful for debugging.

@end table

@node Search scope selection, Mailbox type selection, Output control, Invoking

@table @samp

@item --headers
@itemx -H
Match PATTERN against message headers.

@item --body
@itemx -B
Match PATTERN against message body.

@end table

@node Mailbox type selection, , Search scope selection, Invoking

@table @samp

@item --mailbox-format=FORMAT
@itemx -m FORMAT
Specify mailbox FORMAT.  Supported formats are @code{mbox} (default),
@code{zmbox} (gzip compressed mbox), @code{bz2mbox} (bzip2 compressed
mbox) @code{mh}, @code{nnml}, @code{nnmh}, and @code{maildir}.

@end table

@node Examples, Bugs, Invoking, Top
@chapter Examples
@cindex example

Scan @env{$MAIL} for messages from Dirty Harry:

@example
mboxgrep -H '^From:.*callahan@@sanfranciscopolice\.org' $MAIL
@end example

Re-mail to George messages that mention his name:

@example
mboxgrep --pipe="/usr/lib/sendmail george" --ignore-case george ~/Mail/*
@end example

Display all messages in folder @file{~/Mail/incoming}, except those that
appear to originate from AOL:

@example
mboxgrep -v -H '^Received:.*aol\.com' ~/Mail/incoming
@end example

Do a case-insensitive scan of @file{~/Mail/incoming} for messages with subject 
``Weekly News'' and write them to folder @file{~/Mail/archive}:

@example
mboxgrep -o ~/Mail/archive -H -i '^Subject: Weekly News' ~/Mail/incoming
@end example

Count @emph{all} messages stored in folder @file{spam}, ignoring duplicates:

@example
mboxgrep -nd -c . spam
@end example

@node Bugs, To Vicky, Examples, Top
@chapter Detecting Vermin
@cindex bug, insect, vermin, bugreport

Shortly, if @code{mboxgrep} crashes and/or works differently than described
in this manual, you have found a bug.

Please report bugs to @email{dspiljar@@datatipp.se}.  
Instructions how to reproduce the bug or output from a debugger would be 
highly appreciated. Please do not, however, send any core dumps.

@node To Vicky, , Bugs, Top
@chapter Author's Dedication
@cindex vicky, cat, memory, love

@code{Mboxgrep} is dedicated in loving memory of Vicky, my cat who died
of tumor on Sep 12, 2002.

You haven't been long with us, but you gave us a lot of joy and all
your big heart that stopped ticking too early. I will never forget
you. Sleep well, little friend.


@bye @c cruel world