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