mboxgrep/doc/mboxgrep.texi

280 lines
6.6 KiB
Plaintext
Raw Normal View History

\input texinfo @c -*-texinfo-*-
Bump to version 0.7.10 and import of changes that have been made between 2003 and 2006 and haven't been tracked by any SCM. The changes are the following, in reverse order: * src/mboxgrep.h, src/main.c, src/mbox.c, src/mbox.h, src/scan.c: Temporary mbox file (used for deleting messages) is now created by tmpmbox_create(); tmpp global pointer is killed; portions of code in scan.c are replaced by single call of mbox_write_message(); scan.c no longer includes zlib.h and bzlib.h. * src/mboxgrep.h, src/main.c, src/maildir.c, src/scan.c: Got rid off tmpp and maildir_count global variables (code cleanup). * src/mboxgrep.h, src/main.c, src/scan.c: Introduction of the global runtime_t structure; mailbox counter, MD5 hash and other global variables are now part of it (code cleanup). * src/mboxgrep.h, src/re.c, src/re.h, src/scan.c: Portions of scan_mailbox() have been moved to new functions, pcre_match() and regex_match() (code cleanup). * src/main.c, src/mboxgrep.h, src/re.c, src/re.h, src/scan.c: main() has been partially uncluttered by moving portions of the code to functions pcre_init() and regex_init(). * src/main.c, src/mboxgrep.h, src/misc.c, src/misc.h: Variables regex_s and haveregex are now part of the option_t structure (code cleanup). * src/main.c, src/misc.c, src/misc.h: Parts of main() have been moved to set_default_options() and get_runtime_options() (code cleanup). * src/mbox.c, src/mbox.h: File mode and ownership-altering code has been moved to a separate function, tmpfile_mod_own (code cleanup). * src/mbox.c, src/mbox.h: Portions of the code from tmpfile_open moved to a new function, tmpfile_name (code cleanup). * src/maildir.c, src/mh.c: Removed some unused variables (have_return_path). * src/mboxgrep.h, src/maildir.c, src/mh.c, src/mbox.c, src/scan.c, src/main.c: boxname, outboxname, pipecmd and tmpfilename are now a part of the config_t structure and no longer global variables. * src/scan.c, src/misc.c, src/misc.h: Created postmark_print() to unclutter scan_mailbox(). * src/misc.c, src/misc.h, src/mbox.c, src/maildir.c, src/mh.c: Some repetitive code moved to malloc_message(). * src/mbox.c: Cleanup of mbox_write_message(); use of gzwrite_loop() and bzwrite_loop(). * src/scan.c, src/wrap.h, src/wrap.c: Wrote gzwrite_loop() and bzwrite_loop() to remove some repetitive code from scan.c. * src/scan.c: md5_check_message(): array b and cast in strncmp are no longer unsigned. * src/info.c, src/mboxgrep.h: Updated copyright information, changed author's email address to the one at Panix. * src/mbox.h, src/mbox.c, src/scan.c, src/main.c: mbox_write_message(); further fixes of message deletion code. * src/scan.c: Fixed deleting messages from mbox folders compressed with bzip2. * src/main.c, src/mbox.c: Moved James P. Dugal's ownership-preserving code from main() to tmpfile_open(). * src/info.c: If bzip2 support is compiled in, `--help' command should list `bz2mbox' as a valid option to `--mailbox-format='.
2018-10-04 20:07:27 +00:00
@c $Id: mboxgrep.texi,v 1.20 2006-01-18 00:09:58 dspiljar Exp $
@setfilename mboxgrep.info
@settitle Grep through mailboxes
@finalout
@setchapternewpage odd
@set EDITION 0.7
@set VERSION 0.7.10
@set UPDATED 26 Jan 2023
@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, 2001, 2002, 2003 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=FOLDER
@itemx -o FOLDER
Suppress normal output and write messages to destination folder FOLDER
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.
@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@@homicide\.SFPD\.gov' $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've found a bug.
2018-10-04 20:32:37 +00:00
Please report bugs to @email{dspiljar@@datatipp.se}.
Instructions how to reproduce the bug or output from a debugger would be
highly appreciated. Don't, however, send any coredumps.
@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