.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "mailexec 1"
.TH mailexec 1 "2010-04-11" "Mail Avenger 0.8.1" "Mail Avenger 0.8.1"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
mailexec \- run program on messages in mbox file or maildir
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
mailexec [\-nvFR] \fImailbox\fR \fIprogram\fR [\fIarg\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
mailexec runs a program over every message in \fImailbox\fR, which must
be an mbox-format mail file or maildir directory.  For each message
encountered, mailexec executes \fIprogram\fR with the specified
arguments, supplying the message as standard input.  mailexec
synthesizes a \f(CW\*(C`From\ \*(C'\fR line and a \f(CW\*(C`Return\-Path:\*(C'\fR header field for
each message if the message does not already contain one.  (This
behavior can be modified by the \fB\-F\fR and \fB\-R\fR flags, described
below.)
.PP
When parsing mbox format files, mailexec unescapes \f(CW\*(C`From \*(C'\fR lines.  If
a line begins with one or more \f(CW\*(C`>\*(C'\fR characters followed by \f(CW\*(C`From \*(C'\fR, mailexec deletes one of the \f(CW\*(C`>\*(C'\fR characters.  If you do not
want this unescaping behavior, see the \fIformail\fR\|(1)
utility, which has a \fB\-s\fR flag that performs a similar function to
mailexec.
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
.IP "\fB\-n\fR" 4
.IX Item "-n"
When processing a maildir, causes mailexec to look exclusively at
\&\*(L"new\*(R" messages that have not yet been moved to the \fIcur\fR directory.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Turns on verbose mode.  If \fImailbox\fR is a maildir, mailexec prints
out the name of each file it processes inside the maildir.  If
\&\fImailbox\fR is an mbox format file, mailexec prints the message-id of
each message it processes (as long as messages have a message-id
header).
.IP "\fB\-F\fR" 4
.IX Item "-F"
Suppresses printing of the initial \f(CW\*(C`From \*(C'\fR line at the beginning of
each message.
.IP "\fB\-R\fR" 4
.IX Item "-R"
Suppresses printing of initial \f(CW\*(C`Return\-Path:\*(C'\fR lines.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To get the same behavior as the Unix \fIfrom\fR\|(1) command on a
mail directory \fIdir\fR, you can run either of the following two
commands:
.PP
.Vb 2
\&        mailexec \-n dir head \-1
\&        mailexec \-n dir sed \-ne 1p
.Ve
.PP
To convert an mbox-format file \fImbox\fR into a maildir directory
\&\fIdir\fR, you can run:
.PP
.Vb 1
\&        mailexec mbox deliver dir/
.Ve
.PP
Conversely, to convert maildir \fIdir\fR into an mbox-format file
\&\fImbox\fR, run:
.PP
.Vb 1
\&        mailexec dir deliver mbox
.Ve
.PP
To train the spamassassin filter on a mail folder called \fIspam\fR
containing unwanted messages, run:
.PP
.Vb 1
\&        mailexec spam sa\-learn \-\-spam
.Ve
.PP
Note that this works whether \fIspam\fR is an mbox format file or a
maildir directory.
.PP
If you have an old mbox file or maildir directory \fIbox\fR and wish to
\&\*(L"import\*(R" the old mail into your web mail account, say
\&\fIexample@gmail.com\fR, you can run:
.PP
.Vb 1
\&        mailexec \-F box sendmail example@gmail.com
.Ve
.PP
Note again that this works whether \fIbox\fR is an mbox format file or a
maildir directory.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIavenger\fR\|(1),
\&\fIdeliver\fR\|(1),
\&\fIdotlock\fR\|(1),
\&\fIavenger.local\fR\|(8)
.PP
The Mail Avenger home page: <http://www.mailavenger.org/>.
.SH "BUGS"
.IX Header "BUGS"
When reading from a maildir and synthesizing a \f(CW\*(C`From \*(C'\fR line, mailexec
guesses the delivery date of the message based on the name of the
file, which works in practice but could be considered dangerous since
file names in maildirs are supposed to be opaque.  Thus, while
generally mailexec places sensible dates in \f(CW\*(C`From \*(C'\fR lines and
processes maildir messages in order of delivery, it might be unwise to
rely on this behavior.
.PP
mailexec generates the time for the \f(CW\*(C`From \*(C'\fR line in the local time
zone, as is customary on Unix.  This could lead to loss of information
when transferring mailboxes across time zones or combining mailboxes
created in different timezones.  Moreover, this practice is
incompatible with qmail, which uses \s-1GMT\s0 in the \f(CW\*(C`From \*(C'\fR line.
.PP
mailexec expects that if there is a \f(CW\*(C`Return\-Path:\*(C'\fR header field, it
will be the first header field in the message (possibly after the
initial \f(CW\*(C`From \*(C'\fR line, which is not itself a header field).
.PP
There are many different variants of the mbox message format.
mailexec expects the \*(L"mboxrd\*(R" variant, in which each message is
delimited by a \f(CW\*(C`From \*(C'\fR line at the beginning and a blank line at the
end, and every line beginning with either \f(CW\*(C`From \*(C'\fR or one or more
\&\f(CW\*(C`>\*(C'\fR characters followed by \f(CW\*(C`From \*(C'\fR is escaped by adding another
\&\f(CW\*(C`>\*(C'\fR character.  In particular, this means mailexec will
incorrectly parse System V \*(L"mboxcl2\*(R" files, which use
\&\f(CW\*(C`Content\-Length:\*(C'\fR header fields to determine message boundaries
rather than \f(CW\*(C`From \*(C'\fR lines.
.PP
mailexec attempts to lock mbox format files, but will execute anyway
even if it cannot obtain the lock.  This allows it to work on
read-only files, but if you are highly unlucky could result in the
last message being truncated.
.PP
There is no locking for maildir files.  If a maildir is modified while
mailexec is running over it, mailexec could miss messages.  If you are
concurrently manipulating the maildir with a mail reader, maildir
could even miss old messages that just happen to have been moved from
the \fInew\fR to the \fIcur\fR directory.  mailexec will issue a warning if
it fails to open a file that it had previously seen when scanning the
directory.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Mazie\*`res