1 .\"if n .pl +(135i-\n(.pu)
6 .Id $Id: formail.1,v 1.1 2003/06/16 17:06:40 motoki Exp $
7 .TH FORMAIL 1 \*(Dt BuGless
48 formail \- mail (re)formatter
52 .RI [ "\fB\+\fPskip" ]
53 .RI [ "\fB\-\fPtotal" ]
54 .RB [ \-bczfrktedqBY ]
59 .IR "maxlen idcache" ]
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
109 If formail is supposed to determine the sender of the mail, but is unable
110 to find any, it will substitute `foo@bar'.
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
115 bogus `From ' lines with a `>'.
119 Formail will print its version number and exit.
122 Don't escape any bogus mailbox headers (i.e., lines starting with `From ').
124 .I "\fB\-p\fP prefix"
125 Define a different quotation prefix. If unspecified it defaults to `>'.
128 Assume traditional Berkeley mailbox format, ignoring any
133 Concatenate continued fields in the header. Might be convenient when
134 postprocessing mail with standard (line oriented) text utilities.
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
143 Force formail to simply pass along any non-mailbox format (i.e., don't
144 generate a `From ' line as the first line).
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
151 option. If you use this option in conjunction with
153 you can prevent the body from being `escaped' by also specifying
157 When generating the auto-reply header or when extracting fields, keep
161 Trust the sender to have used a valid return address in his header. This
162 causes formail to select the
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
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).
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
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).
184 optionally specifies an upper limit on the number of concurrently
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).
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
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.
205 Makes formail assume that it is splitting up a BABYL rmail file.
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
213 Tells formail to (still detect but) be quiet about write errors,
214 duplicate messages and mismatched
216 fields. This option is on by default, to make it display the messages
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
224 file of approximately
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
230 formail will look at the
232 of the envelope sender
236 .I "\fB\-x\fP headerfield"
237 Extract the contents of this
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
244 .I "\fB\-X\fP headerfield"
247 but also preserves/includes the field name.
249 .I "\fB\-a\fP 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
256 .B Resent-Message-ID:
257 with no field contents, then formail will generate a unique message-ID
260 .I "\fB\-A\fP headerfield"
263 onto the header in any case.
265 .I "\fB\-i\fP headerfield"
268 except that any existing similar fields are renamed by prepending an
271 consists only of a field-name, it will not be appended.
273 .I "\fB\-I\fP headerfield"
276 except that any existing similar fields are simply removed. If
278 consists only of a field-name, it effectively deletes the field.
280 .I "\fB\-u\fP headerfield"
281 Make the first occurrence of this field unique, and thus delete all
282 subsequent occurrences of it.
284 .I "\fB\-U\fP headerfield"
285 Make the last occurrence of this field unique, and thus delete all
286 preceding occurrences of it.
288 .I "\fB\-R\fP oldfield newfield"
289 Renames all occurrences of the fieldname
297 messages while splitting.
302 messages while splitting.
304 When renaming, removing, or extracting fields, partial fieldnames may
305 be used to specify all fields that start with the specified value.
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.
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
322 the new Internet Message Format standard, which states in part:
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.
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.
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.
348 To split up a digest one usually uses:
350 formail +1 \-ds >>the_mailbox_of_your_choice
354 formail +1 \-ds procmail
357 To remove all Received: fields from the header:
359 formail \-I Received:
362 To remove all fields except From: and Subject: from the header:
364 formail \-k \-X From: \-X Subject:
367 To supersede the Reply-To: field in a header you could use:
369 formail \-i "Reply-To: foo@bar"
372 To convert a non-standard mailbox file into a standard mailbox file you can
375 formail \-ds <old_mailbox >>new_mailbox
378 Or, if you have a very tolerant mailer:
380 formail \-a Date: \-ds <old_mailbox >>new_mailbox
383 To extract the header from a message:
392 To extract the body from a message:
417 Too many processes on this machine.
419 Content-Length: field exceeds actual length by nnn bytes
420 The Content-Length: field in the header specified a length that was longer
421 than the actual body. This causes this message to absorb a number of
422 subsequent messages following it in the same mailbox.
424 Couldn't write to stdout
425 The program that formail was trying to pipe into didn't accept all the data
426 formail sent to it; this diagnostic can be suppressed by the
430 Duplicate key found: x
431 The Message-ID or sender x in this message was found in the idcache; this
432 diagnostic can be suppressed by the
436 Failed to execute "x"
437 Program not in path, or not executable.
440 Too many open files on this machine.
442 Invalid field-name: "x"
443 The specified field-name "x" contains control characters, or cannot be a
444 partial field-name for this option.
446 You can save yourself and others a lot of grief if you try to avoid using
447 this autoreply feature on mails coming through mailinglists. Depending
448 on the format of the incoming mail (which in turn depends on both the
449 original sender's mail agent and the mailinglist setup) formail could
450 decide to generate an autoreply header that replies to the list.
452 In the tradition of UN*X utilities, formail will do exactly what
453 you ask it to, even if it results in a
455 compliant message. In particular, formail will let you generate
456 header fields whose name ends in a space instead of a colon. While
457 this is correct for the leading `From ' line, that line is not a
458 header field so much as the message separator for the mbox mailbox
459 format. Multiple occurrences of such a line or any other colonless
460 header field will be considered by many mail programs, including
461 formail itself, as the beginning of a new message. Others will
462 consider the message to be corrupt. Because of this, you should
465 option with the `From ' line as the resulting renamed line,
466 `Old-From ', will probably not do what you want it to. If
467 you want to save the original `From ' line, rename it with the
469 option to a legal header field such as `X-From_:'.
471 When formail has to generate a leading `From ' line it normally will contain
472 the current date. If formail is given the option `\-a Date:',
473 it will use the date from the `Date:' field in the header (if present).
474 However, since formail copies it verbatim, the format will differ from that
475 expected by most mail readers.
477 If formail is instructed to delete or rename the leading `From ' line, it
478 will not automatically regenerate it as usual. To force formail to regenerate
479 it in this case, include \fB\-a 'From '\fP.
481 If formail is not called as the first program in a pipe and it is told to
482 split up the input in several messages, then formail will not terminate until
483 the program it receives the input from closes its output or terminates itself.
485 If formail is instructed to generate an autoreply mail, it will
487 put more than one address in the `To:' field.
489 Formail is eight-bit clean.
491 When formail has to determine the sender's address, every
494 mail address is allowed. Formail will always strip down the address to
495 its minimal form (deleting excessive comments and whitespace).
497 The regular expression that is used to find `real' postmarks is:
499 "\en\enFrom [\et ]*[^\et\en ]+[\et ]+[^\en\et ]"
504 field is found in a header, formail will copy the number of specified bytes in
505 the body verbatim before resuming the regular scanning for message boundaries
506 (except when splitting digests or Berkeley mailbox format is assumed).
508 Any header lines immediately following the leading `From ' line
509 that start with `>From ' are considered to be a continuation
510 of the `From ' line. If instructed to rename the `From ' line,
511 formail will change each leading `>' into a space, thereby
512 transforming those lines into normal
516 Calling up formail with the \-h or \-? options will cause
517 it to display a command-line help page.
519 This program is part of the
520 .I procmail mail-processing-package
521 (v3.22) available at http://www.procmail.org/ or
525 There exists a mailinglist for questions relating to any program in the
528 <procmail-users@procmail.org>
530 for submitting questions/answers.
532 <procmail-users-request@procmail.org>
534 for subscription requests.
538 If you would like to stay informed about new versions and official patches send
539 a subscription request to
541 procmail-announce-request@procmail.org
543 (this is a readonly list).
545 Stephen R. van den Berg
551 <guenther@sendmail.com>
553 .\".if n .pl -(\n(.tu-1i)