OSDN Git Service

Import translated manuals from JM CVS Repository.
[linuxjm/jm.git] / manual / procmail / original / man5 / procmailrc.5
1 .\"if n .pl +(135i-\n(.pu)
2 .de Id
3 .ds Rv \\$3
4 .ds Dt \\$4
5 ..
6 .Id $Id: procmailrc.5,v 1.1 2003/06/16 17:06:43 motoki Exp $
7 .TH PROCMAILRC 5 \*(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 .na
48 .SH NAME
49 procmailrc \- procmail rcfile
50 .SH SYNOPSIS
51 .B $HOME/.procmailrc
52 .ad
53 .SH DESCRIPTION
54 For a quick start, see
55 .B NOTES
56 at the end of the
57 .BR procmail (1)
58 man page.
59 .PP
60 The rcfile can contain a mixture of environment variable assignments (some
61 of which have special meanings to procmail), and recipes.  In their most
62 simple appearance, the recipes are simply one line regular expressions
63 that are searched for in the header of the arriving mail.  The first recipe
64 that matches is used to determine where the mail has to go (usually a file).
65 If processing falls off the end of the rcfile, procmail will deliver the mail
66 to
67 .BR $DEFAULT .
68 .PP
69 There are two kinds of recipes: delivering and non-delivering recipes.
70 If a
71 .I delivering recipe
72 is found to match, procmail considers the mail (you guessed it) delivered and
73 will
74 .I cease processing
75 the rcfile after having successfully executed the action line of the recipe.
76 If a
77 .I non-delivering recipe
78 is found to match, processing of the rcfile will
79 .I continue
80 after the action line of this recipe has been executed.
81 .PP
82 Delivering recipes are those that cause header and/or body of the mail to
83 be: written into a file, absorbed by a program or forwarded to a mailaddress.
84 .PP
85 Non-delivering recipes are: those that cause the output of a program or
86 filter to be captured back by procmail or those that start a nesting block.
87 .PP
88 You can tell procmail to treat a
89 .I delivering recipe
90 as if it were a non-delivering recipe by specifying the `c' flag on
91 such a recipe.  This will make procmail generate a
92 .I carbon copy
93 of the mail by delivering it to this recipe, yet continue processing the
94 rcfile.
95 .PP
96 By using any number of recipes you can presort your mail extremely
97 straightforward into several mailfolders.  Bear in mind though that the mail
98 can arrive concurrently in these mailfolders (if several procmail programs
99 happen to run at the same time, not unlikely if a lot of mail arrives).  To
100 make sure this does not result in a mess, proper use of lockfiles is highly
101 recommended.
102 .PP
103 The environment variable
104 .B assignments
105 and
106 .B recipes
107 can be freely intermixed in the rcfile. If any environment variable has
108 a special meaning to procmail, it will be used appropriately the moment
109 it is parsed (i.e., you can change the current directory whenever you
110 want by specifying a new
111 .BR MAILDIR ,
112 switch lockfiles by specifying a new
113 .BR LOCKFILE ,
114 change the umask at any time, etc., the possibilities are endless :\-).
115 .PP
116 The assignments and substitutions of these environment variables are handled
117 exactly like in
118 .BR sh (1)
119 (that includes all possible quotes and escapes),
120 with the added bonus that blanks around the '=' sign are ignored and that,
121 if an environment variable appears without a trailing '=', it will be
122 removed from the environment.  Any program in backquotes started by procmail
123 will have the entire mail at its stdin.
124 .PP
125 .SS Comments
126 A word beginning with # and all the following characters up to a NEWLINE
127 are ignored.  This does not apply to condition lines, which cannot be
128 commented.
129 .SS Recipes
130 .PP
131 A line starting with ':' marks the beginning of a recipe.  It has the
132 following format:
133 .Sx 3
134 :0 [\fIflags\fP] [ : [\fIlocallockfile\fP] ]
135 <zero or more conditions (one per line)>
136 <exactly one action line>
137 .Ex
138 Conditions start with a leading `*', everything after that character
139 is passed on to the internal egrep
140 .BR literally ,
141 except for leading and trailing whitespace.
142 These regular expressions are
143 .B completely
144 compatible to the normal
145 .BR egrep (1)
146 extended regular expressions.  See also
147 .BR "Extended regular expressions" .
148 .PP
149 Conditions are anded; if there are no conditions the result will be true
150 by default.
151 .PP
152 .I Flags
153 can be any of the following:
154 .TP 0.5i
155 .B H
156 Egrep the header (default).
157 .TP
158 .B B
159 Egrep the body.
160 .TP
161 .B D
162 Tell the internal egrep to distinguish between upper and lower case (contrary
163 to the default which is to ignore case).
164 .TP
165 .B A
166 This recipe will not be executed unless the conditions on the last preceding
167 recipe (on the current block-nesting level) without the `A' or
168 `a' flag matched as well.  This allows you to chain actions
169 that depend on a common condition.
170 .TP
171 .B a
172 Has the same meaning as the `A' flag, with the additional
173 condition that the immediately preceding recipe must have been
174 .I successfully
175 completed before this recipe is executed.
176 .TP
177 .B E
178 This recipe only executes if the immediately preceding recipe was not
179 executed.  Execution of this recipe also disables any immediately
180 following recipes with the 'E' flag.  This allows you to specify
181 `else if' actions.
182 .TP
183 .B e
184 This recipe only executes if the immediately preceding recipe
185 .IR failed
186 (i.e., the action line was attempted, but resulted in an error).
187 .TP
188 .B h
189 Feed the header to the pipe, file or mail destination (default).
190 .TP
191 .B b
192 Feed the body to the pipe, file or mail destination (default).
193 .TP
194 .B f
195 Consider the pipe as a filter.
196 .TP
197 .B c
198 Generate a
199 .B carbon copy
200 of this mail.  This only makes sense on
201 .I delivering
202 recipes.  The only non-delivering recipe this flag has an effect on is
203 on a nesting block, in order to generate a carbon copy this will
204 .B clone
205 the running procmail process (lockfiles will not be inherited), whereby
206 the clone will proceed as usual and the parent will jump across the block.
207 .TP
208 .B w
209 Wait for the filter or program to finish and check its exitcode (normally
210 ignored); if the filter is unsuccessful, then the text will not have been
211 filtered.
212 .TP
213 .B W
214 Has the same meaning as the `w' flag, but will suppress any
215 `Program failure' message.
216 .TP
217 .B i
218 Ignore any write errors on this recipe (i.e., usually due to an early closed
219 pipe).
220 .TP
221 .B r
222 Raw mode, do not try to ensure the mail ends with an empty line, write
223 it out as is.
224 .PP
225 There are some special conditions you can use that are not straight regular
226 expressions.  To select them, the condition must start with:
227 .TP 0.5i
228 .B !
229 Invert the condition.
230 .TP
231 .B $
232 Evaluate the remainder of this condition according to
233 .BR sh (1)
234 substitution rules inside double quotes, skip leading whitespace,
235 then reparse it.
236 .TP
237 .B ?
238 Use the exitcode of the specified program.
239 .TP
240 .B <
241 Check if the total length of the mail is shorter than the specified (in
242 decimal) number of bytes.
243 .TP
244 .B >
245 Analogous to '<'.
246 .TP
247 .B "variablename \fI??\fP"
248 Match the remainder of this condition against the value of this environment
249 variable (which cannot be a pseudo variable).  A special case is if
250 variablename is equal to `B', `H', `HB' or `BH'; this merely overrides the
251 default header/body search area defined by the initial flags on this recipe.
252 .TP
253 .B \e
254 To quote any of the above at the start of the line.
255 .SS "Local lockfile"
256 .PP
257 If you put a second (trailing) ':' on the first recipe line, then procmail
258 will use a
259 .I locallockfile
260 (for this recipe only).  You can optionally specify the locallockfile
261 to use; if you don't however, procmail will use the destination filename
262 (or the filename following the first '>>') and will append $LOCKEXT to it.
263 .SS "Recipe action line"
264 .PP
265 The action line can start with the following characters:
266 .TP
267 .B !
268 Forwards to all the specified mail addresses.
269 .TP
270 .B |
271 Starts the specified program, possibly in $SHELL if any
272 of the characters $SHELLMETAS are spotted.  You can optionally prepend this
273 pipe symbol with
274 .IR variable= ,
275 which will cause stdout of the program to be captured in the environment
276 .I variable
277 (procmail will
278 .B not
279 terminate processing the rcfile at this point).
280 If you specify just this pipe symbol, without any program, then procmail will
281 pipe the mail to stdout.
282 .TP
283 .B {
284 Followed by at least one space, tab or newline will mark the start of a
285 nesting block.  Everything up till the next closing brace will depend on
286 the conditions specified for this recipe.  Unlimited nesting is permitted.
287 The closing brace exists merely to delimit the block, it will
288 .I not
289 cause procmail to terminate in any way.  If the end of a block is reached
290 processing will continue as usual after the block.
291 On a nesting block, the flags `H' and `B' only affect
292 the conditions leading up to the block, the flags `h' and
293 `b' have no effect whatsoever.
294 .PP
295 Anything else will be taken as a mailbox name (either a filename or a
296 directory, absolute or relative to the current directory (see MAILDIR)).
297 If it is a (possibly yet nonexistent) filename, the mail will be appended to
298 it.
299 .PP
300 If it is a directory, the mail will be delivered to a newly created,
301 guaranteed to be unique file named $MSGPREFIX* in the specified directory.
302 If the mailbox name ends in "/.", then this directory is
303 presumed to be an MH folder; i.e., procmail will use the next number it
304 finds available.  If the mailbox name ends in "/", then this
305 directory is presumed to be a maildir folder; i.e., procmail will deliver
306 the message to a file in a subdirectory named "tmp" and rename it to be
307 inside a subdirectory named "new".  If the mailbox is specified to be an MH
308 folder or maildir folder, procmail will create the necessary directories if
309 they don't exist, rather than treat the mailbox as a non-existent
310 filename.  When procmail is delivering to directories, you can specify
311 multiple directories to deliver to (procmail will do so utilising
312 hardlinks).
313 .SS "Environment variable defaults"
314 .TP 2.2i
315 .B "LOGNAME, HOME and SHELL"
316 Your (the recipient's) defaults
317 .TP
318 .B PATH
319 .na
320 \&$HOME/bin\h'-\w' 'u' :/bin\h'-\w' 'u' :/usr/bin\h'-\w' 'u' :/usr/local/bin\h'-\w' 'u' :/usr/bin/X11
321 (Except
322 .ad
323 during the processing of an /etc/procmailrc file, when it will be set
324 to
325 .na
326 `\&/bin\h'-\w' 'u' :/usr/bin\h'-\w' 'u' :/usr/local/bin\h'-\w' 'u' :/usr/bin/X11'.)
327 .ad
328 .TP
329 .B SHELLMETAS
330 \&&\h'-\w' 'u' |<>~;?*[
331 .TP
332 .B SHELLFLAGS
333 \&-c
334 .TP
335 .BR ORGMAIL
336 \&/var/spool/mail/$LOGNAME
337 .br
338 (Unless
339 .B \-m
340 has been specified, in which case it is unset)
341 .TP
342 .B MAILDIR
343 \&$HOME
344 .br
345 (Unless the name of the first successfully opened rcfile starts with
346 `./' or if
347 .B \-m
348 has been specified, in which case it defaults to `.')
349 .TP
350 .B DEFAULT
351 \&$ORGMAIL
352 .TP
353 .B MSGPREFIX
354 \&msg.
355 .TP
356 .B SENDMAIL
357 \&/usr/sbin/sendmail
358 .TP
359 .B SENDMAILFLAGS
360 \&-oi
361 .TP
362 .B HOST
363 The current hostname
364 .TP
365 .B COMSAT
366 \&no
367 .br
368 (If an rcfile is specified on the command line)
369 .TP
370 .B PROCMAIL_VERSION
371 \&3.22
372 .TP
373 .B LOCKEXT
374 \&.lock
375 .na
376 .PP
377 Other cleared or preset environment variables are IFS, ENV and PWD.
378 .ad
379 .PP
380 For security reasons, upon startup procmail will wipe out all environment variables that are suspected of modifying the behavior of the runtime linker.
381 .SS Environment
382 .PP
383 Before you get lost in the multitude of environment variables, keep in mind
384 that all of them have reasonable defaults.
385 .TP 1.2i
386 .B MAILDIR
387 Current directory while procmail is executing (that means that all paths
388 are relative to $MAILDIR).
389 .TP
390 .B DEFAULT
391 Default
392 .B mailbox
393 file (if not told otherwise, procmail will dump mail in this mailbox).
394 Procmail will automatically use $DEFAULT$LOCKEXT as lockfile prior to writing
395 to this mailbox.  You do not need to set this variable, since it already
396 points to the standard system mailbox.
397 .TP
398 .B LOGFILE
399 This file will also contain any error or diagnostic messages from procmail
400 (normally none :\-) or any other programs started by procmail.  If this file
401 is not specified, any diagnostics or error messages will
402 be mailed back to the sender.
403 See also
404 .BR LOGABSTRACT .
405 .TP
406 .B VERBOSE
407 You can turn on
408 .I extended diagnostics
409 by setting this variable to `yes' or `on', to turn it off again set it to `no'
410 or `off'.
411 .TP
412 .B LOGABSTRACT
413 Just before procmail exits it logs an abstract of the delivered message in
414 $LOGFILE showing the `From ' and `Subject:' fields of the header, what folder
415 it finally went to and how long (in bytes) the message was.  By setting this
416 variable to `no', generation of this abstract is suppressed.  If you set
417 it to `all', procmail will log an abstract for every successful
418 .I delivering recipe
419 it processes.
420 .TP
421 .B LOG
422 Anything assigned to this variable will be appended to $LOGFILE.
423 .TP
424 .B ORGMAIL
425 Usually the system mailbox (\fBOR\fPi\fBG\fPinal \fBMAIL\fPbox).  If, for
426 some obscure reason (like `\fBfilesystem full\fP') the mail could not be
427 delivered, then this mailbox will be the last resort.  If procmail
428 fails to save the mail in here (deep, deep trouble :\-), then the mail
429 will bounce back to the sender.
430 .TP
431 .B LOCKFILE
432 Global semaphore file.  If this file already exists, procmail
433 will wait until it has gone before proceeding, and will create it itself
434 (cleaning it up when ready, of course).  If more than one
435 .I lockfile
436 are specified, then the previous one will be removed before trying to create
437 the new one.  The use of a global lockfile is discouraged, whenever possible
438 use locallockfiles (on a per recipe basis) instead.
439 .TP
440 .B LOCKEXT
441 Default extension that is appended to a destination file to determine
442 what local
443 .I lockfile
444 to use (only if turned on, on a per-recipe basis).
445 .TP
446 .B LOCKSLEEP
447 Number of seconds procmail will sleep before retrying on a
448 .I lockfile
449 (if it already existed); if not specified, it defaults to 8
450 seconds.
451 .TP
452 .B LOCKTIMEOUT
453 Number of seconds that have to have passed since a
454 .I lockfile
455 was last modified/created before procmail decides that this must be an
456 erroneously leftover lockfile that can be removed by force now.  If zero,
457 then no timeout will be used and procmail will wait forever until the
458 lockfile is removed; if not specified, it defaults to 1024 seconds.
459 This variable is useful to prevent indefinite hangups of
460 .BR sendmail /procmail.
461 Procmail is immune to clock skew across machines.
462 .TP
463 .B TIMEOUT
464 Number of seconds that have to have passed before procmail decides that
465 some child it started must be hanging.  The offending program will receive
466 a TERMINATE signal from procmail, and processing of the rcfile will continue.
467 If zero, then no timeout will be used and procmail will wait forever until the
468 child has terminated; if not specified, it defaults to 960 seconds.
469 .TP
470 .B MSGPREFIX
471 Filename prefix that is used when delivering to a directory (not used when
472 delivering to a maildir or an MH directory).
473 .TP
474 .B HOST
475 If this is not the
476 .I hostname
477 of the machine, processing of the current
478 .I rcfile
479 will immediately cease. If other rcfiles were specified on the
480 command line, processing will continue with the next one.  If all rcfiles
481 are exhausted, the program will terminate, but will not generate an error
482 (i.e., to the mailer it will seem that the mail has been delivered).
483 .TP
484 .B UMASK
485 The name says it all (if it doesn't, then forget about this one :\-).
486 Anything assigned to UMASK is taken as an
487 .B octal
488 number.  If not specified, the umask defaults to 077.  If the umask
489 permits o+x, all the mailboxes procmail delivers to directly will receive
490 an o+x mode change.  This can be used to check if new mail arrived.
491 .TP
492 .B SHELLMETAS
493 If any of the characters in SHELLMETAS appears in the line specifying
494 a filter or program, the line will be fed to $SHELL
495 instead of being executed directly.
496 .TP
497 .B SHELLFLAGS
498 Any invocation of $SHELL will be like:
499 .br
500 "$SHELL" "$SHELLFLAGS" "$*";
501 .TP
502 .B SENDMAIL
503 If you're not using the
504 .I forwarding
505 facility don't worry about this one.  It specifies the program being
506 called to forward any mail.
507 .br
508 It gets invoked as: "$SENDMAIL" $SENDMAILFLAGS "$@";
509 .TP
510 .B NORESRETRY
511 Number of retries that are to be made if any `\fBprocess table full\fP',
512 `\fBfile table full\fP', `\fBout of memory\fP' or
513 `\fBout of swap space\fP' error should occur.  If this number is negative,
514 then procmail will retry indefinitely; if not specified, it defaults to
515 4 times.  The retries occur with a $SUSPEND second interval.  The
516 idea behind this is that if, e.g., the
517 .I swap
518 .I space
519 has been exhausted or the
520 .I process
521 .I table
522 is full, usually several other programs will either detect this as well
523 and abort or crash 8\-), thereby freeing valuable
524 .I resources
525 for procmail.
526 .TP
527 .B SUSPEND
528 Number of seconds that procmail will pause if it has to wait for something
529 that is currently unavailable (memory, fork, etc.); if not specified, it will
530 default to 16 seconds.  See also:
531 .BR LOCKSLEEP .
532 .TP
533 .B LINEBUF
534 Length of the internal line buffers, cannot be set smaller than 128.
535 All lines read from the
536 .I rcfile
537 should not exceed $LINEBUF characters before and after expansion.  If not
538 specified, it defaults to 2048.  This limit, of course, does
539 .I not
540 apply to the mail itself, which can have arbitrary line lengths, or could
541 be a binary file for that matter.  See also PROCMAIL_OVERFLOW.
542 .TP
543 .B DELIVERED
544 If set to `yes' procmail will pretend (to the mail agent) the mail
545 has been delivered.  If mail cannot be delivered after having met this
546 assignment (set to `yes'), the mail will be lost (i.e., it will not bounce).
547 .TP
548 .B TRAP
549 When procmail terminates of its own accord and not because it
550 received a signal, it will execute the contents of this variable.
551 A copy of the mail can be read from stdin.  Any output produced by this
552 command will be appended to $LOGFILE.  Possible uses for TRAP are: removal
553 of temporary files, logging customised abstracts, etc.  See also
554 .B EXITCODE
555 and
556 .BR LOGABSTRACT .
557 .TP
558 .B EXITCODE
559 By default, procmail returns an exitcode of zero (success) if it
560 successfully delivered the message or if the
561 .B HOST
562 variable was misset and there were no more rcfiles on the command
563 line; otherwise it returns failure.  Before doing so, procmail
564 examines the value of this variable.  If it is set to a positive
565 numeric value, procmail will instead use that value as its exitcode.
566 If this variable is set but empty and
567 .B TRAP
568 is set, procmail will set the exitcode to whatever the
569 .B TRAP
570 program returns.  If this variable is not set, procmail will set
571 it shortly before calling up the
572 .B TRAP
573 program.
574 .TP
575 .B LASTFOLDER
576 This variable is assigned to by procmail whenever it is delivering
577 to a folder or program.  It always contains the name of the last file
578 (or program) procmail delivered to.  If the last delivery was to
579 several directory folders together then $LASTFOLDER will contain
580 the hardlinked filenames as a space separated list.
581 .TP
582 .B MATCH
583 This variable is assigned to by procmail whenever it is told to extract
584 text from a matching regular expression.  It will contain all text
585 matching the regular expression past the `\fB\e/\fP' token.
586 .TP
587 .B SHIFT
588 Assigning a positive value to this variable has the same effect as
589 the `shift' command in
590 .BR sh (1).
591 This command is most useful to extract extra arguments passed to procmail
592 when acting as a generic mailfilter.
593 .TP
594 .B INCLUDERC
595 Names an rcfile (relative to the current directory) which will be
596 included here as if it were part of the current rcfile.  Nesting is
597 permitted and only limited by systems resources (memory and file
598 descriptors).  As no checking is done on the permissions or ownership
599 of the rcfile, users of
600 .B INCLUDERC
601 should make sure that only trusted users have write access to the included
602 rcfile or the directory it is in.  Command line assignments to
603 .B INCLUDERC
604 have no effect.
605 .TP
606 .B SWITCHRC
607 Names an rcfile (relative to the current directory) to which processing
608 will be switched.  If the named rcfile doesn't exist or is not a normal
609 file or /dev/null then an error will be logged and processing will
610 continue in the current rcfile.  Otherwise, processing of the current
611 rcfile will be aborted and the named rcfile started.  Unsetting
612 .B SWITCHRC
613 aborts processing of the current rcfile as if it had ended at the
614 assignment.  As with
615 .BR INCLUDERC ,
616 no checking is done on the permissions or ownership of the rcfile
617 and command line assignments have no effect.
618 .TP
619 .B PROCMAIL_VERSION
620 The version number of the running procmail binary.
621 .TP
622 .B PROCMAIL_OVERFLOW
623 This variable will be set to a non-empty value if procmail detects a
624 buffer overflow.  See the
625 .B BUGS
626 section below for other details of operation when overflow occurs.
627 .TP
628 .B COMSAT
629 .BR Comsat (8)/ biff (1)
630 notification is on by default, it can be turned off by setting this variable
631 to `no'.  Alternatively the biff-service can be customised by setting it to
632 either `service@', `@hostname', or
633 `service@hostname'.  When not specified it defaults
634 to biff@localhost.
635 .TP
636 .B DROPPRIVS
637 If set to `yes' procmail will drop all privileges it might have had (suid or sgid).  This is only useful if you want to guarantee that the bottom half of the /etc/procmailrc file is executed on behalf of the recipient.
638 .SS "Extended regular expressions"
639 The following tokens are known to both the procmail internal egrep and the
640 standard
641 .BR egrep (1)
642 (beware that some egrep implementations include other non-standard extensions):
643 .TP 1.0i
644 .B ^
645 Start of a line.
646 .TP
647 .B $
648 End of a line.
649 .TP
650 .B .
651 Any character except a newline.
652 .TP
653 .B a*
654 Any sequence of zero or more a's.
655 .TP
656 .B a+
657 Any sequence of one or more a's.
658 .TP
659 .B a?
660 Either zero or one a.
661 .TP
662 .B [^-a-d]
663 Any character which is
664 .B not
665 either a dash, a, b, c, d or newline.
666 .TP
667 .B de|abc
668 Either the sequence `de' or `abc'.
669 .TP
670 .B (abc)*
671 Zero or more times the sequence `abc'.
672 .TP
673 .B \e.
674 Matches a single dot; use \e to quote any of the magic characters to get
675 rid of their special meaning.  See also $\e variable substitution.
676 .PP
677 These were only samples, of course, any more complex combination is valid
678 as well.
679 .PP
680 The following token meanings are special procmail extensions:
681 .TP 1.0i
682 \fB^\fP or \fB$\fP
683 Match a newline (for multiline matches).
684 .TP
685 .B ^^
686 Anchor the expression at the very start of the search area, or if encountered
687 at the end of the expression, anchor it at the very end of the search area.
688 .TP
689 \fB\e<\fP or \fB\e>\fP
690 Match the character before or after a word.  They are merely a shorthand
691 for `[^a-zA-Z0-9_]', but can also match newlines.
692 Since they match actual characters, they are only suitable to delimit
693 words, not to delimit inter-word space.
694 .TP
695 .B \e/
696 Splits the expression in two parts.  Everything matching the right part
697 will be assigned to the MATCH environment variable.
698 .SH EXAMPLES
699 Look in the
700 .BR procmailex (5)
701 man page.
702 .SH CAVEATS
703 Continued lines in an action line that specifies a program always have to end
704 in a backslash, even if the underlying shell would not need or want the
705 backslash to indicate continuation.  This is due to the two pass parsing
706 process needed (first procmail, then the shell (or not, depending on
707 .BR SHELLMETAS )).
708 .PP
709 Don't put comments on the regular expression condition lines in a
710 recipe, these lines are fed to the internal egrep
711 .I literally
712 (except for continuation backslashes at the end of a line).
713 .PP
714 Leading whitespace on continued regular expression condition lines
715 is usually ignored (so that they can be indented), but
716 .B not
717 on continued condition lines that are evaluated according to the
718 .BR sh (1)
719 substitution rules inside double quotes.
720 .PP
721 Watch out for deadlocks when doing unhealthy things like forwarding mail
722 to your own account.  Deadlocks can be broken by proper use of
723 .BR LOCKTIMEOUT .
724 .PP
725 Any default values that procmail has for some environment variables will
726 .B always
727 override the ones that were already defined.  If you really want to
728 override the defaults, you either have to put them in the
729 .B rcfile
730 or on the command line as arguments.
731 .PP
732 The /etc/procmailrc file cannot change the PATH setting seen by user rcfiles
733 as the value is reset when procmail finishes the /etc/procmailrc file.  While
734 future enhancements are expected in this area, recompiling procmail
735 with the desired value is currently the only correct solution.
736 .PP
737 Environment variables set
738 .B inside
739 the shell-interpreted-`|' action part of a recipe will
740 .B not
741 retain their value after the recipe has finished since they are set in a
742 subshell of procmail.  To make sure the value of an environment variable is
743 retained you have to put the assignment to the variable before the leading `|'
744 of a recipe, so that it can capture stdout of the program.
745 .PP
746 If you specify only a `h' or a `b' flag on a delivering
747 recipe, and the recipe matches, then, unless the `c' flag is
748 present as well, the body respectively the header of the mail will be silently
749 lost.
750 .SH "SEE ALSO"
751 .na
752 .nh
753 .BR procmail (1),
754 .BR procmailsc (5),
755 .BR procmailex (5),
756 .BR sh (1),
757 .BR csh (1),
758 .BR mail (1),
759 .BR mailx (1),
760 .BR binmail (1),
761 .BR uucp (1),
762 .BR aliases (5),
763 .BR sendmail (8),
764 .BR egrep (1),
765 .BR regexp (5),
766 .BR grep (1),
767 .BR biff (1),
768 .BR comsat (8),
769 .BR lockfile (1),
770 .BR formail (1)
771 .hy
772 .ad
773 .SH BUGS
774 The only substitutions of environment variables that can be handled by
775 procmail itself are of the type $name, ${name}, ${name:-text}, ${name:+text},
776 ${name-text}, ${name+text}, $\ename, $#, $n, $$, $?, $_, $\- and $=;
777 whereby $\ename will be substituted by the
778 all-magic-regular-expression-characters-disarmed
779 equivalent of $name, $_ by the name of the current rcfile, $\- by
780 $LASTFOLDER and $= will contain the score of the last recipe.
781 Furthermore, the result of $\ename substitution will never be split on
782 whitespace.  When the
783 .B \-a
784 or
785 .B \-m
786 options are used, $# will expand to the number of arguments so
787 specified and "$@" (the quotes are required) will expand to the
788 specified arguments.  However, "$@" will only be expanded when
789 used in the argument list to a program, and
790 then only one such occurrence will be expanded.
791 .PP
792 Unquoted variable expansions performed by procmail are always split on
793 space, tab, and newline characters; the IFS variable is not used internally.
794 .PP
795 Procmail does not support the expansion of `~'.
796 .PP
797 A line buffer of length $LINEBUF is used when processing the
798 .IR rcfile ,
799 any expansions that don't fit within this limit will be truncated and
800 PROCMAIL_OVERFLOW will be set.  If the overflowing line is a condition
801 or an action line, then it will be considered failed and procmail will
802 continue processing.  If it is a variable assignment or recipe start
803 line then procmail will abort the entire rcfile.
804 .PP
805 If the global lockfile has a
806 .I relative
807 path, and the current directory
808 is not the same as when the global lockfile was created, then the global
809 lockfile will not be removed if procmail exits at that point (remedy:
810 use
811 .I absolute
812 paths to specify global lockfiles).
813 .PP
814 If an rcfile has a
815 .I relative
816 path and when the rcfile is first opened
817 .B MAILDIR
818 contains a relative path, and if at one point procmail is instructed to
819 clone itself and the current directory has changed since the rcfile was
820 opened, then procmail will not be able to clone itself (remedy: use an
821 .I absolute
822 path to reference the rcfile or make sure MAILDIR contains an absolute
823 path as the rcfile is opened).
824 .PP
825 A locallockfile on the recipe that marks the start of a non-forking nested
826 block does not work as expected.
827 .PP
828 When capturing stdout from a recipe into an environment variable, exactly
829 one trailing newline will be stripped.
830 .PP
831 Some non-optimal and non-obvious regexps set MATCH to an incorrect
832 value.  The regexp can be made to work by removing one or more unneeded
833 '*', '+', or '?' operator on the left-hand side of the \e/ token.
834 .SH MISCELLANEOUS
835 If the regular expression contains `\fB^TO_\fP' it will be substituted by
836 .na
837 .nh
838 `\fB(^((Original-)?(Resent-)?(To\h'-\w' 'u' |Cc\h'-\w' 'u' |Bcc)\h'-\w' 'u' |(X-Envelope\h'-\w' 'u' |Apparently(-Resent)?)-To)\h'-\w' 'u' :(.*[^-a-zA-Z0-9_.])?)\fP',
839 which should catch all destination specifications containing a specific
840 .IR address .
841 .hy
842 .ad
843 .PP
844 If the regular expression contains `\fB^TO\fP' it will be substituted by
845 .na
846 .nh
847 `\fB(^((Original-)?(Resent-)?(To\h'-\w' 'u' |Cc\h'-\w' 'u' |Bcc)\h'-\w' 'u' |(X-Envelope\h'-\w' 'u' |Apparently(-Resent)?)-To)\h'-\w' 'u' :(.*[^a-zA-Z])?)\fP',
848 which should catch all destination specifications containing a specific
849 .IR word .
850 .hy
851 .ad
852 .PP
853 If the regular expression contains `\fB^FROM_DAEMON\fP' it will be
854 substituted by
855 .na
856 .nh
857 `\fB(^(Mailing-List\h'-\w' 'u' :\h'-\w' 'u' |Precedence\h'-\w' 'u' :.*(junk\h'-\w' 'u' |bulk\h'-\w' 'u' |list)\h'-\w' 'u' |To\h'-\w' 'u' : Multiple recipients of |(((Resent-)?(From\h'-\w' 'u' |Sender)\h'-\w' 'u' |X-Envelope-From)\h'-\w' 'u' :\h'-\w' 'u' |>?From )([^>]*[^(.%@a-z0-9])?(Post(ma?(st(e?r)?\h'-\w' 'u' |n)\h'-\w' 'u' |office)\h'-\w' 'u' |(send)?Mail(er)?\h'-\w' 'u' |daemon\h'-\w' 'u' |m(mdf\h'-\w' 'u' |ajordomo)\h'-\w' 'u' |n?uucp\h'-\w' 'u' |LIST(SERV\h'-\w' 'u' |proc)\h'-\w' 'u' |NETSERV\h'-\w' 'u' |o(wner\h'-\w' 'u' |ps)\h'-\w' 'u' |r(e(quest\h'-\w' 'u' |sponse)\h'-\w' 'u' |oot)\h'-\w' 'u' |b(ounce\h'-\w' 'u' |bs\e.smtp)\h'-\w' 'u' |echo\h'-\w' 'u' |mirror\h'-\w' 'u' |s(erv(ices?\h'-\w' 'u' |er)\h'-\w' 'u' |mtp(error)?\h'-\w' 'u' |ystem)\h'-\w' 'u' |A(dmin(istrator)?\h'-\w' 'u' |MMGR\h'-\w' 'u' |utoanswer))(([^).!\h'-\w' 'u' :a-z0-9][-_a-z0-9]*)?[%@>\\t ][^<)]*(\e(.*\e).*)?)?$([^>]\h'-\w' 'u' |$)))\fP',
858 which should catch mails coming from most daemons (how's that for a regular
859 expression :\-).
860 .hy
861 .ad
862 .PP
863 If the regular expression contains `\fB^FROM_MAILER\fP' it will be
864 substituted by
865 .na
866 .nh
867 `\fB(^(((Resent-)?(From\h'-\w' 'u' |Sender)\h'-\w' 'u' |X-Envelope-From)\h'-\w' 'u' :\h'-\w' 'u' |>?From )([^>]*[^(.%@a-z0-9])?(Post(ma(st(er)?\h'-\w' 'u' |n)\h'-\w' 'u' |office)\h'-\w' 'u' |(send)?Mail(er)?\h'-\w' 'u' |daemon\h'-\w' 'u' |mmdf\h'-\w' 'u' |n?uucp\h'-\w' 'u' |ops\h'-\w' 'u' |r(esponse\h'-\w' 'u' |oot)\h'-\w' 'u' |(bbs\e.)?smtp(error)?\h'-\w' 'u' |s(erv(ices?\h'-\w' 'u' |er)\h'-\w' 'u' |ystem)\h'-\w' 'u' |A(dmin(istrator)?\h'-\w' 'u' |MMGR))(([^).!\h'-\w' 'u' :a-z0-9][-_a-z0-9]*)?[%@>\\t ][^<)]*(\e(.*\e).*)?)?$([^>]\h'-\w' 'u' |$))\fP'
868 (a stripped down version of `\fB^FROM_DAEMON\fP'),
869 which should catch mails coming from most mailer-daemons.
870 .hy
871 .ad
872 .PP
873 When assigning boolean values to variables like VERBOSE, DELIVERED or COMSAT,
874 procmail accepts as true every string starting with: a non-zero value, `on',
875 `y', `t' or `e'.  False is every string starting with: a zero value, `off',
876 `n', `f' or `d'.
877 .PP
878 If the action line of a recipe specifies a program, a sole backslash-newline
879 pair in it on an otherwise empty line will be converted into a newline.
880 .PP
881 The regular expression engine built into procmail does not support named
882 character classes.
883 .SH NOTES
884 Since unquoted leading whitespace is generally ignored in the rcfile you can
885 indent everything to taste.
886 .PP
887 The leading `|' on the action line to specify a program or filter is stripped
888 before checking for $SHELLMETAS.
889 .PP
890 Files included with the INCLUDERC directive containing only environment
891 variable assignments can be shared with sh.
892 .PP
893 The current behavior of assignments on the command line to
894 .B INCLUDERC
895 and
896 .B SWITCHRC
897 is not guaranteed, has been changed once already, and may be changed
898 again or removed in future releases.
899 .PP
900 For
901 .I really
902 complicated processing you can even consider calling
903 .B procmail
904 recursively.
905 .PP
906 In the old days, the `:0' that marks the beginning of a recipe, had to
907 be changed to `:n', whereby `n' denotes the number of conditions that
908 follow.
909 .SH AUTHORS
910 Stephen R. van den Berg
911 .RS
912 <srb@cuci.nl>
913 .RE
914 Philip A. Guenther
915 .RS
916 <guenther@sendmail.com>
917 .RE
918 .\".if n .pl -(\n(.tu-1i)
919 .rm SH
920 .rn Sh SH
921 .rm SS
922 .rn Ss SS
923 .rm TP
924 .rn Tp TP
925 .rm RS
926 .rn Rs RS
927 .rm RE
928 .rn Re RE