| 1 |
.\"if n .pl +(135i-\n(.pu) |
| 2 |
.de Id |
| 3 |
.ds Rv \\$3 |
| 4 |
.ds Dt \\$4 |
| 5 |
.. |
| 6 |
.Id $Id: formail.man,v 1.46 2001/08/04 06:08:17 guenther Exp $ |
| 7 |
.TH FORMAIL 1 \*(Dt BuGless |
| 8 |
.rn SH Sh |
| 9 |
.de SH |
| 10 |
.br |
| 11 |
.ne 11 |
| 12 |
.Sh "\\$1" |
| 13 |
.. |
| 14 |
.rn SS Ss |
| 15 |
.de SS |
| 16 |
.br |
| 17 |
.ne 10 |
| 18 |
.Ss "\\$1" |
| 19 |
.. |
| 20 |
.rn TP Tp |
| 21 |
.de TP |
| 22 |
.br |
| 23 |
.ne 9 |
| 24 |
.Tp \\$1 |
| 25 |
.. |
| 26 |
.rn RS Rs |
| 27 |
.de RS |
| 28 |
.na |
| 29 |
.nf |
| 30 |
.Rs |
| 31 |
.. |
| 32 |
.rn RE Re |
| 33 |
.de RE |
| 34 |
.Re |
| 35 |
.fi |
| 36 |
.ad |
| 37 |
.. |
| 38 |
.de Sx |
| 39 |
.PP |
| 40 |
.ne \\$1 |
| 41 |
.RS |
| 42 |
.. |
| 43 |
.de Ex |
| 44 |
.RE |
| 45 |
.PP |
| 46 |
.. |
| 47 |
.SH NAME |
| 48 |
formail \- mail (re)formatter |
| 49 |
.SH SYNOPSIS |
| 50 |
.na |
| 51 |
.B formail |
| 52 |
.RI [ "\fB\+\fPskip" ] |
| 53 |
.RI [ "\fB\-\fPtotal" ] |
| 54 |
.RB [ \-bczfrktedqBY ] |
| 55 |
.RB [ \-p |
| 56 |
.IR prefix ] |
| 57 |
.if n .ti +0.5i |
| 58 |
.RB [ \-D |
| 59 |
.IR "maxlen idcache" ] |
| 60 |
.if n .ti +0.5i |
| 61 |
.RB [ \-l |
| 62 |
.IR folder ] |
| 63 |
.if n .ti +0.5i |
| 64 |
.RB [ \-x |
| 65 |
.IR headerfield ] |
| 66 |
.RB [ \-X |
| 67 |
.IR headerfield ] |
| 68 |
.if n .ti +0.5i |
| 69 |
.RB [ \-a |
| 70 |
.IR headerfield ] |
| 71 |
.RB [ \-A |
| 72 |
.IR headerfield ] |
| 73 |
.if n .ti +0.5i |
| 74 |
.RB [ \-i |
| 75 |
.IR headerfield ] |
| 76 |
.RB [ \-I |
| 77 |
.IR headerfield ] |
| 78 |
.if n .ti +0.5i |
| 79 |
.RB [ \-u |
| 80 |
.IR headerfield ] |
| 81 |
.RB [ \-U |
| 82 |
.IR headerfield ] |
| 83 |
.if n .ti +0.5i |
| 84 |
.RB [ \-R |
| 85 |
.I oldfield |
| 86 |
.IR newfield ] |
| 87 |
.if n .ti +0.5i |
| 88 |
.RB [ \-n |
| 89 |
.RI [ maxprocs |
| 90 |
]] |
| 91 |
.RB [ \-m |
| 92 |
.IR minfields ] |
| 93 |
.RB [ \-s |
| 94 |
.RI [ command |
| 95 |
.RI [ arg |
| 96 |
\&.\|.\|.\|]]] |
| 97 |
.br |
| 98 |
.B formail |
| 99 |
.B \-v |
| 100 |
.ad |
| 101 |
.SH DESCRIPTION |
| 102 |
.B formail |
| 103 |
is a filter that can be used to force mail into mailbox format, perform |
| 104 |
`From ' escaping, generate auto-replying headers, do simple |
| 105 |
header munging/extracting or split up a |
| 106 |
mailbox/digest/articles file. The mail/mailbox/article contents will be |
| 107 |
expected on stdin. |
| 108 |
.PP |
| 109 |
If formail is supposed to determine the sender of the mail, but is unable |
| 110 |
to find any, it will substitute `foo@bar'. |
| 111 |
.PP |
| 112 |
If formail is started without any command line options, it will force any |
| 113 |
mail coming from stdin into mailbox format and will escape |
| 114 |
.B all |
| 115 |
bogus `From ' lines with a `>'. |
| 116 |
.SH OPTIONS |
| 117 |
.TP 0.5i |
| 118 |
.B \-v |
| 119 |
Formail will print its version number and exit. |
| 120 |
.TP |
| 121 |
.B \-b |
| 122 |
Don't escape any bogus mailbox headers (i.e., lines starting with `From '). |
| 123 |
.TP |
| 124 |
.I "\fB\-p\fP prefix" |
| 125 |
Define a different quotation prefix. If unspecified it defaults to `>'. |
| 126 |
.TP |
| 127 |
.B \-Y |
| 128 |
Assume traditional Berkeley mailbox format, ignoring any |
| 129 |
.B Content-Length: |
| 130 |
fields. |
| 131 |
.TP |
| 132 |
.B \-c |
| 133 |
Concatenate continued fields in the header. Might be convenient when |
| 134 |
postprocessing mail with standard (line oriented) text utilities. |
| 135 |
.TP |
| 136 |
.B \-z |
| 137 |
Ensure a whitespace exists between field name and content. |
| 138 |
Zap fields which contain only a single whitespace character. |
| 139 |
Zap leading and trailing whitespace on fields extracted with |
| 140 |
.BR \-x . |
| 141 |
.TP |
| 142 |
.B \-f |
| 143 |
Force formail to simply pass along any non-mailbox format (i.e., don't |
| 144 |
generate a `From ' line as the first line). |
| 145 |
.TP |
| 146 |
.B \-r |
| 147 |
Generate an auto-reply header. This will normally throw away all the existing |
| 148 |
fields (except X-Loop:) in the original message, fields you wish to preserve |
| 149 |
need to be named using the |
| 150 |
.B \-i |
| 151 |
option. If you use this option in conjunction with |
| 152 |
.BR \-k , |
| 153 |
you can prevent the body from being `escaped' by also specifying |
| 154 |
.BR \-b . |
| 155 |
.TP |
| 156 |
.B \-k |
| 157 |
When generating the auto-reply header or when extracting fields, keep |
| 158 |
the body as well. |
| 159 |
.TP |
| 160 |
.B \-t |
| 161 |
Trust the sender to have used a valid return address in his header. This |
| 162 |
causes formail to select the |
| 163 |
.I header sender |
| 164 |
instead of the |
| 165 |
.I envelope sender |
| 166 |
for the reply. This option should be used when generating auto-reply |
| 167 |
headers from news articles or when the sender of the message is |
| 168 |
expecting a reply. |
| 169 |
.TP |
| 170 |
.B \-s |
| 171 |
The input will be split up into separate mail messages, and piped into |
| 172 |
a program one by one (a new program is started for every part). |
| 173 |
.B \-s |
| 174 |
has to be the last option specified, the first argument following it is |
| 175 |
expected to be the name of a program, any other arguments will be |
| 176 |
passed along to it. If you omit the program, then formail will simply |
| 177 |
concatenate the split mails on stdout again. See |
| 178 |
.BR FILENO . |
| 179 |
.TP |
| 180 |
.I "\fB\-n\fP [maxprocs]" |
| 181 |
Tell formail not to wait for every program to finish before starting |
| 182 |
the next (causes splits to be processed in parallel). |
| 183 |
.I Maxprocs |
| 184 |
optionally specifies an upper limit on the number of concurrently |
| 185 |
running processes. |
| 186 |
.TP |
| 187 |
.B \-e |
| 188 |
Do not require empty lines to be preceding the header of a new message |
| 189 |
(i.e., the messages could start on every line). |
| 190 |
.TP |
| 191 |
.B \-d |
| 192 |
Tell formail that the messages it is supposed to split need not be in |
| 193 |
strict mailbox format (i.e., allows you to split digests/articles or |
| 194 |
non-standard mailbox formats). This disables recognition of the |
| 195 |
.B Content-Length: |
| 196 |
field. |
| 197 |
.TP |
| 198 |
.B \-l folder |
| 199 |
Generate a log summary in the same style as procmail. This includes |
| 200 |
the entire "From " line, the Subject: header field, the folder, and |
| 201 |
the size of the message in bytes. The mailstat command can be used |
| 202 |
to summarize logs in this format. |
| 203 |
.TP |
| 204 |
.B \-B |
| 205 |
Makes formail assume that it is splitting up a BABYL rmail file. |
| 206 |
.TP |
| 207 |
.I "\fB\-m\fP minfields" |
| 208 |
Allows you to specify the number of consecutive headerfields formail |
| 209 |
needs to find before it decides it found the start of a new message, it |
| 210 |
defaults to 2. |
| 211 |
.TP |
| 212 |
.B \-q |
| 213 |
Tells formail to (still detect but) be quiet about write errors, |
| 214 |
duplicate messages and mismatched |
| 215 |
.B Content-Length: |
| 216 |
fields. This option is on by default, to make it display the messages |
| 217 |
use |
| 218 |
.BR \-q\- . |
| 219 |
.TP |
| 220 |
.I "\fB\-D\fP maxlen idcache" |
| 221 |
Formail will detect if the Message-ID of the current message has |
| 222 |
already been seen using an |
| 223 |
.I idcache |
| 224 |
file of approximately |
| 225 |
.I maxlen |
| 226 |
size. If not splitting, it will return success if a duplicate has been |
| 227 |
found. If splitting, it will not output duplicate messages. If used |
| 228 |
in conjunction with |
| 229 |
.BR \-r , |
| 230 |
formail will look at the |
| 231 |
.I mail address |
| 232 |
of the envelope sender |
| 233 |
.I instead |
| 234 |
at the Message-ID. |
| 235 |
.TP |
| 236 |
.I "\fB\-x\fP headerfield" |
| 237 |
Extract the contents of this |
| 238 |
.I headerfield |
| 239 |
from the header. Line continuations will be left intact; if you |
| 240 |
want the value on a single line then you'll also need the |
| 241 |
.B \-c |
| 242 |
option. |
| 243 |
.TP |
| 244 |
.I "\fB\-X\fP headerfield" |
| 245 |
Same as |
| 246 |
.BR \-x , |
| 247 |
but also preserves/includes the field name. |
| 248 |
.TP |
| 249 |
.I "\fB\-a\fP headerfield" |
| 250 |
Append a custom |
| 251 |
.I headerfield |
| 252 |
onto the header; but only if a similar field does not exist yet. If |
| 253 |
you specify either one of the field names |
| 254 |
.B Message-ID: |
| 255 |
or |
| 256 |
.B Resent-Message-ID: |
| 257 |
with no field contents, then formail will generate a unique message-ID |
| 258 |
for you. |
| 259 |
.TP |
| 260 |
.I "\fB\-A\fP headerfield" |
| 261 |
Append a custom |
| 262 |
.I headerfield |
| 263 |
onto the header in any case. |
| 264 |
.TP |
| 265 |
.I "\fB\-i\fP headerfield" |
| 266 |
Same as |
| 267 |
.BR \-A , |
| 268 |
except that any existing similar fields are renamed by prepending an |
| 269 |
``Old-'' prefix. If |
| 270 |
.I headerfield |
| 271 |
consists only of a field-name, it will not be appended. |
| 272 |
.TP |
| 273 |
.I "\fB\-I\fP headerfield" |
| 274 |
Same as |
| 275 |
.BR \-i , |
| 276 |
except that any existing similar fields are simply removed. If |
| 277 |
.I headerfield |
| 278 |
consists only of a field-name, it effectively deletes the field. |
| 279 |
.TP |
| 280 |
.I "\fB\-u\fP headerfield" |
| 281 |
Make the first occurrence of this field unique, and thus delete all |
| 282 |
subsequent occurrences of it. |
| 283 |
.TP |
| 284 |
.I "\fB\-U\fP headerfield" |
| 285 |
Make the last occurrence of this field unique, and thus delete all |
| 286 |
preceding occurrences of it. |
| 287 |
.TP |
| 288 |
.I "\fB\-R\fP oldfield newfield" |
| 289 |
Renames all occurrences of the fieldname |
| 290 |
.I oldfield |
| 291 |
into |
| 292 |
.IR newfield . |
| 293 |
.TP |
| 294 |
.I "\fB\+\fPskip" |
| 295 |
Skip the first |
| 296 |
.I skip |
| 297 |
messages while splitting. |
| 298 |
.TP |
| 299 |
.I "\fB\-\fPtotal" |
| 300 |
Output at most |
| 301 |
.I total |
| 302 |
messages while splitting. |
| 303 |
.SH NOTES |
| 304 |
When renaming, removing, or extracting fields, partial fieldnames may |
| 305 |
be used to specify all fields that start with the specified value. |
| 306 |
.PP |
| 307 |
By default, when generating an auto-reply header procmail selects the |
| 308 |
envelope sender from the input message. This is correct for vacation |
| 309 |
messages and other automatic replies regarding the routing or delivery |
| 310 |
of the original message. If the sender is expecting a reply or the |
| 311 |
reply is being generated in response to the contents of the original |
| 312 |
message then the \-t option should be used. |
| 313 |
.PP |
| 314 |
.BR RFC822 , |
| 315 |
the original standard governing the format of Internet mail |
| 316 |
messages, did not specify whether Resent header fields (those that |
| 317 |
begin with `Resent\-', such as `Resent\-From:') should be considered |
| 318 |
when generating a reply. Since then, the recommended usage of the |
| 319 |
Resent headers has evolved to consider them as purely informational and |
| 320 |
not for use when generating a reply. This has been codified in |
| 321 |
.BR RFC2822 , |
| 322 |
the new Internet Message Format standard, which states in part: |
| 323 |
.IP |
| 324 |
Resent fields are used to identify a message as having been |
| 325 |
reintroduced into the transport system by a user. The purpose of |
| 326 |
using resent fields is to have the message appear to the final |
| 327 |
recipient as if it were sent directly by the original sender, with |
| 328 |
all of the original fields remaining the same.\|\|.\|.\|.\|\|They |
| 329 |
MUST NOT be used in the normal processing of replies or other such |
| 330 |
automatic actions on messages. |
| 331 |
.PP |
| 332 |
While formail now |
| 333 |
ignores Resent headers when generating header replies, versions of |
| 334 |
formail prior to 3.14 gave such headers a high precedence. If the old |
| 335 |
behavior is needed for established applications it can be specified by |
| 336 |
calling formail with the option `-a Resent-' in addition |
| 337 |
to the \-r and \-t options. This usage is deprecated |
| 338 |
and should not be used in new applications. |
| 339 |
.SH ENVIRONMENT |
| 340 |
.TP .5i |
| 341 |
.B FILENO |
| 342 |
While splitting, formail assigns the message number currently being output to |
| 343 |
this variable. By presetting FILENO, you can change the initial message |
| 344 |
number being used and the width of the zero-padded output. If FILENO is |
| 345 |
unset it will default to 000. If FILENO is non-empty and |
| 346 |
does not contain a number, FILENO generation is disabled. |
| 347 |
.SH EXAMPLES |
| 348 |
To split up a digest one usually uses: |
| 349 |
.RS |
| 350 |
formail +1 \-ds >>the_mailbox_of_your_choice |
| 351 |
.RE |
| 352 |
or |
| 353 |
.RS |
| 354 |
formail +1 \-ds procmail |
| 355 |
.RE |
| 356 |
.PP |
| 357 |
To remove all Received: fields from the header: |
| 358 |
.RS |
| 359 |
formail \-I Received: |
| 360 |
.RE |
| 361 |
.PP |
| 362 |
To remove all fields except From: and Subject: from the header: |
| 363 |
.RS |
| 364 |
formail \-k \-X From: \-X Subject: |
| 365 |
.RE |
| 366 |
.PP |
| 367 |
To supersede the Reply-To: field in a header you could use: |
| 368 |
.RS |
| 369 |
formail \-i "Reply-To: foo@bar" |
| 370 |
.RE |
| 371 |
.PP |
| 372 |
To convert a non-standard mailbox file into a standard mailbox file you can |
| 373 |
use: |
| 374 |
.RS |
| 375 |
formail \-ds <old_mailbox >>new_mailbox |
| 376 |
.RE |
| 377 |
.PP |
| 378 |
Or, if you have a very tolerant mailer: |
| 379 |
.RS |
| 380 |
formail \-a Date: \-ds <old_mailbox >>new_mailbox |
| 381 |
.RE |
| 382 |
.PP |
| 383 |
To extract the header from a message: |
| 384 |
.RS |
| 385 |
formail \-X "" |
| 386 |
.RE |
| 387 |
or |
| 388 |
.RS |
| 389 |
sed \-e '/^$/ q' |
| 390 |
.RE |
| 391 |
.PP |
| 392 |
To extract the body from a message: |
| 393 |
.RS |
| 394 |
formail \-I "" |
| 395 |
.RE |
| 396 |
or |
| 397 |
.RS |
| 398 |
sed \-e '1,/^$/ d' |
| 399 |
.RE |
| 400 |
.SH "SEE ALSO" |
| 401 |
.na |
| 402 |
.nh |
| 403 |
.BR mail (1), |
| 404 |
.BR sendmail (8), |
| 405 |
.BR procmail (1), |
| 406 |
.BR sed (1), |
| 407 |
.BR sh (1), |
| 408 |
.BR RFC822 , |
| 409 |
.BR RFC2822 , |
| 410 |
.B RFC1123 |
| 411 |
.hy |
| 412 |
.ad |
| 413 |
.SH DIAGNOSTICS |
| 414 |
.TP 2.3i |
| 415 |
Can't fork |
| 416 |
Too many processes on this machine. |
| 417 |
.TP |
| 418 |
Content-Length: field exceeds actual length by nnn bytes |
| 419 |
The Content-Length: field in the header specified a length that was longer |
| 420 |
than the actual body. This causes this message to absorb a number of |
| 421 |
subsequent messages following it in the same mailbox. |
| 422 |
.TP |
| 423 |
Couldn't write to stdout |
| 424 |
The program that formail was trying to pipe into didn't accept all the data |
| 425 |
formail sent to it; this diagnostic can be suppressed by the |
| 426 |
.B \-q |
| 427 |
option. |
| 428 |
.TP |
| 429 |
Duplicate key found: x |
| 430 |
The Message-ID or sender x in this message was found in the idcache; this |
| 431 |
diagnostic can be suppressed by the |
| 432 |
.B \-q |
| 433 |
option. |
| 434 |
.TP |
| 435 |
Failed to execute "x" |
| 436 |
Program not in path, or not executable. |
| 437 |
.TP |
| 438 |
File table full |
| 439 |
Too many open files on this machine. |
| 440 |
.TP |
| 441 |
Invalid field-name: "x" |
| 442 |
The specified field-name "x" contains control characters, or cannot be a |
| 443 |
partial field-name for this option. |
| 444 |
.SH WARNINGS |
| 445 |
You can save yourself and others a lot of grief if you try to avoid using |
| 446 |
this autoreply feature on mails coming through mailinglists. Depending |
| 447 |
on the format of the incoming mail (which in turn depends on both the |
| 448 |
original sender's mail agent and the mailinglist setup) formail could |
| 449 |
decide to generate an autoreply header that replies to the list. |
| 450 |
.PP |
| 451 |
In the tradition of UN*X utilities, formail will do exactly what |
| 452 |
you ask it to, even if it results in a |
| 453 |
.RB non- RFC822 |
| 454 |
compliant message. In particular, formail will let you generate |
| 455 |
header fields whose name ends in a space instead of a colon. While |
| 456 |
this is correct for the leading `From ' line, that line is not a |
| 457 |
header field so much as the message separator for the mbox mailbox |
| 458 |
format. Multiple occurrences of such a line or any other colonless |
| 459 |
header field will be considered by many mail programs, including |
| 460 |
formail itself, as the beginning of a new message. Others will |
| 461 |
consider the message to be corrupt. Because of this, you should |
| 462 |
not use the |
| 463 |
.B \-i |
| 464 |
option with the `From ' line as the resulting renamed line, |
| 465 |
`Old-From ', will probably not do what you want it to. If |
| 466 |
you want to save the original `From ' line, rename it with the |
| 467 |
.B \-R |
| 468 |
option to a legal header field such as `X-From_:'. |
| 469 |
.SH BUGS |
| 470 |
When formail has to generate a leading `From ' line it normally will contain |
| 471 |
the current date. If formail is given the option `\-a Date:', |
| 472 |
it will use the date from the `Date:' field in the header (if present). |
| 473 |
However, since formail copies it verbatim, the format will differ from that |
| 474 |
expected by most mail readers. |
| 475 |
.PP |
| 476 |
If formail is instructed to delete or rename the leading `From ' line, it |
| 477 |
will not automatically regenerate it as usual. To force formail to regenerate |
| 478 |
it in this case, include \fB\-a 'From '\fP. |
| 479 |
.PP |
| 480 |
If formail is not called as the first program in a pipe and it is told to |
| 481 |
split up the input in several messages, then formail will not terminate until |
| 482 |
the program it receives the input from closes its output or terminates itself. |
| 483 |
.PP |
| 484 |
If formail is instructed to generate an autoreply mail, it will |
| 485 |
.B never |
| 486 |
put more than one address in the `To:' field. |
| 487 |
.SH MISCELLANEOUS |
| 488 |
Formail is eight-bit clean. |
| 489 |
.PP |
| 490 |
When formail has to determine the sender's address, every |
| 491 |
.B RFC822 |
| 492 |
conforming |
| 493 |
mail address is allowed. Formail will always strip down the address to |
| 494 |
its minimal form (deleting excessive comments and whitespace). |
| 495 |
.PP |
| 496 |
The regular expression that is used to find `real' postmarks is: |
| 497 |
.RS |
| 498 |
"\en\enFrom [\et ]*[^\et\en ]+[\et ]+[^\en\et ]" |
| 499 |
.RE |
| 500 |
.PP |
| 501 |
If a |
| 502 |
.B Content-Length: |
| 503 |
field is found in a header, formail will copy the number of specified bytes in |
| 504 |
the body verbatim before resuming the regular scanning for message boundaries |
| 505 |
(except when splitting digests or Berkeley mailbox format is assumed). |
| 506 |
.PP |
| 507 |
Any header lines immediately following the leading `From ' line |
| 508 |
that start with `>From ' are considered to be a continuation |
| 509 |
of the `From ' line. If instructed to rename the `From ' line, |
| 510 |
formail will change each leading `>' into a space, thereby |
| 511 |
transforming those lines into normal |
| 512 |
.B RFC822 |
| 513 |
continuations. |
| 514 |
.SH NOTES |
| 515 |
Calling up formail with the \-h or \-? options will cause |
| 516 |
it to display a command-line help page. |
| 517 |
.Sh SOURCE |
| 518 |
This program is part of the |
| 519 |
.I procmail mail-processing-package |
| 520 |
(v3.23pre) available at http://www.procmail.org/ or |
| 521 |
ftp.procmail.org in |
| 522 |
.BR pub/procmail/ . |
| 523 |
.Sh MAILINGLIST |
| 524 |
There exists a mailinglist for questions relating to any program in the |
| 525 |
procmail package: |
| 526 |
.RS |
| 527 |
<[email protected]> |
| 528 |
.RS |
| 529 |
for submitting questions/answers. |
| 530 |
.RE |
| 531 |
<[email protected]> |
| 532 |
.RS |
| 533 |
for subscription requests. |
| 534 |
.RE |
| 535 |
.PP |
| 536 |
.RE |
| 537 |
If you would like to stay informed about new versions and official patches send |
| 538 |
a subscription request to |
| 539 |
.RS |
| 540 |
[email protected] |
| 541 |
.RE |
| 542 |
(this is a readonly list). |
| 543 |
.SH AUTHORS |
| 544 |
Stephen R. van den Berg |
| 545 |
.RS |
| 546 |
<[email protected]> |
| 547 |
.RE |
| 548 |
Philip A. Guenther |
| 549 |
.RS |
| 550 |
<[email protected]> |
| 551 |
.RE |
| 552 |
.\".if n .pl -(\n(.tu-1i) |
| 553 |
.rm SH |
| 554 |
.rn Sh SH |
| 555 |
.rm SS |
| 556 |
.rn Ss SS |
| 557 |
.rm TP |
| 558 |
.rn Tp TP |
| 559 |
.rm RS |
| 560 |
.rn Rs RS |
| 561 |
.rm RE |
| 562 |
.rn Re RE |