Debian Codegraph @

upstream/debian-unstable/man1/formail.1

raw
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