Debian Codegraph @

upstream/debian-trixie/man7/maildropfilter.7

raw
1 '\" t
2 .\"<!-- Copyright 1998 - 2014 Double Precision, Inc. See COPYING for -->
3 .\"<!-- distribution information. -->
4 .\" Title: maildropfilter
5 .\" Author: Sam Varshavchik
6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
7 .\" Date: 07/13/2024
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Courier Mail Server
10 .\" Language: English
11 .\"
12 .TH "MAILDROPFILTER" "7" "07/13/2024" "Courier Mail Server" "Double Precision, Inc\&."
13 .\" -----------------------------------------------------------------
14 .\" * Define some portability stuff
15 .\" -----------------------------------------------------------------
16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 .\" http://bugs.debian.org/507673
18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .ie \n(.g .ds Aq \(aq
21 .el .ds Aq '
22 .\" -----------------------------------------------------------------
23 .\" * set default formatting
24 .\" -----------------------------------------------------------------
25 .\" disable hyphenation
26 .nh
27 .\" disable justification (adjust text to left margin only)
28 .ad l
29 .\" -----------------------------------------------------------------
30 .\" * MAIN CONTENT STARTS HERE *
31 .\" -----------------------------------------------------------------
32 .SH "NAME"
33 maildropfilter \- maildrop\*(Aqs filtering language
34 .SH "SYNOPSIS"
35 .sp
36 /etc/maildroprc, $HOME/\&.mailfilter, $HOME/\&.mailfilters/*, and friends\&.\&.\&.
37 .SH "DESCRIPTION"
38 .PP
39 This manual page describes the language used by
40 \fBmaildrop\fR
41 to filter E\-mail messages\&. The mail filtering instructions are read from a file\&. The language is loosely structured, it is based on pattern matching\&. The language has a distinct lexical and syntactical structure, very similar to Perl\*(Aqs, but it is important to note that it is not Perl, and is very different from Perl, in certain cases\&.
42 .PP
43 If the filtering instructions do not exist,
44 \fBmaildrop\fR
45 delivers the message to the default mailbox without doing any additional processing, making it indistinguishable from the usual mail delivery agent\&.
46 .PP
47 It is important to note that
48 \fBmaildrop\fR
49 reads and parses the
50 filter file
51 before doing anything\&. If there are any errors
52 \fBmaildrop\fR
53 prints an error message, and terminates with the exit code set to
54 \fBEX_TEMPFAIL\fR\&. A compliant mail transport agent should re\-queue the message for a later delivery attempt\&. Hopefully, most simple syntax errors will not cause mail to be bounced back if the error is caught and fixed quickly\&.
55 .SS "Environment"
56 .PP
57
58 \fBmaildrop\fR
59 uses variables to access and manipulate messages\&. Variables are arbitrary text accessed by referring to the name of the variable, such as
60 \fIHOME\fR, or
61 \fIDEFAULT\fR\&. Text is placed into a variable by using an assignment statement, such as:
62 .sp
63 .if n \{\
64 .RS 4
65 .\}
66 .nf
67 FILE="IN\&.junk"
68
69 .fi
70 .if n \{\
71 .RE
72 .\}
73 .PP
74 This statement puts the text "IN\&.junk" (without the quotes) into a variable whose name is
75 \fIFILE\fR\&. Later, the contents of a variable are accessed by using the $ symbol and the name for the variable\&. For example:
76 .sp
77 .if n \{\
78 .RS 4
79 .\}
80 .nf
81 to $FILE
82
83 .fi
84 .if n \{\
85 .RE
86 .\}
87 .PP
88 This will deliver the current message to the mailbox file (or a maildir directory) named "IN\&.junk"\&.
89 .PP
90 \fBmaildrop\fR
91 initially creates variables from the environment variables of the operating system, UNLESS
92 \fBmaildrop\fR
93 runs in delivery mode\&. Each operating system environment variable becomes a
94 \fBmaildrop\fR
95 variable\&. When running in delivery mode,
96 \fBmaildrop\fR
97 does not import the environment for security reasons, except for the environment variables that define the process locale (\fILANG\fR,
98 \fILANGUAGE\fR, and
99 \fILC_\fR\fI\fI*\fR\fR), which are still imported\&.
100 .PP
101 In all cases
102 \fBmaildrop\fR
103 resets the following variables to their default values:
104 \fIHOME\fR,
105 \fIDEFAULT\fR,
106 \fISHELL\fR,
107 \fIPATH\fR,
108 \fILOCKEXT\fR,
109 \fILOCKREFRESH\fR,
110 \fILOCKSLEEP\fR,
111 \fILOCKTIMEOUT\fR,
112 \fIMAILDIRQUOTA\fR,
113 \fISENDMAIL\fR
114 and
115 \fILOGNAME\fR\&.
116 .PP
117 There\*(Aqs one exception to this rule which applies to the version of
118 \fBmaildrop\fR
119 that comes with the
120 \m[blue]\fBCourier mail server\fR\m[]\&\s-2\u[1]\d\s+2\&. The following does not apply to the standalone version of
121 \fBmaildrop\fR: when running in delivery mode, if the
122 \fB\-d\fR
123 flag was not used, or if it specifies the same userid as the one that\*(Aqs running
124 \fBmaildrop\fR: the following variables are automatically imported from the environment:
125 \fIHOME\fR,
126 \fISHELL\fR,
127 \fILOGNAME\fR
128 and
129 \fIMAILDIRQUOTA\fR\&. These environment variables are initialized by the
130 Courier
131 mail server prior to running
132 \fBmaildrop\fR\&. Additionally, the initial value for the
133 \fIDEFAULT\fR
134 maildrop variable is imported from the
135 \fIMAILDROPDEFAULT\fR
136 environment variable\&. This is because the
137 Courier
138 mail server overloads the DEFAULT environment variable to store the defaulted portion of the local mailbox address\&. See the
139 \m[blue]\fB\fBdot-courier\fR(5)\fR\m[]\&\s-2\u[2]\d\s+2
140 man page in the
141 Courier
142 mail server distribution\&. You can get the
143 Courier
144 mail server\*(Aqs
145 \fIDEFAULT\fR
146 value by using the
147 \fBimport\fR
148 command\&. Note, however, that this will clobber the old contents of
149 \fIDEFAULT\fR, which is probably not what you want\&. The right way to do this would be something like this:
150 .sp
151 .if n \{\
152 .RS 4
153 .\}
154 .nf
155 SAVEDEFAULT=$DEFAULT
156 import DEFAULT
157 LOCALDEFAULT=$DEFAULT
158 DEFAULT=$SAVEDEFAULT
159
160 .fi
161 .if n \{\
162 .RE
163 .\}
164 .PP
165 All internal variables are exported back as environment variables when
166 \fBmaildrop\fR
167 runs an external command\&. Changes to internal variables, made by the
168 filter file, are reflected in the exported environment\&.
169 .SS "Lexical structure"
170 .PP
171 Most whitespace is generally ignored\&. The
172 #
173 character introduces a comment running to the end of the line, which is also ignored\&. Unlike other mail filters,
174 \fBmaildrop\fR
175 parses the
176 filter file
177 before taking any action with the message\&. If there are syntax errors in the file,
178 \fBmaildrop\fR
179 displays an error message, and returns
180 \fBEX_TEMPFAIL\fR\&. That should cause the mail message to remain in the queue, and, hopefully allow the problem to be corrected, without bouncing any mail\&.
181 .if n \{\
182 .sp
183 .\}
184 .RS 4
185 .it 1 an-trap
186 .nr an-no-space-flag 1
187 .nr an-break-flag 1
188 .br
189 .ps +1
190 \fBNote\fR
191 .ps -1
192 .br
193 .PP
194 In
195 \fBmaildrop\fR, the end of line is a lexical token\&. In order to continue a long statement on the next line, terminate the line with a backslash character\&.
196 .sp .5v
197 .RE
198 .SS "Literal text"
199 .PP
200 Literal text in the
201 \fBmaildrop\fR
202 filtering language is surrounded by either single or double quotes\&. In order to enter a single quote into a text literal surrounded by single quotes, or a double quote into a literal surrounded by double quotes, prefix it with a backslash character\&. Use two backslash characters characters to enter one backslash character in the text literal\&.
203 .if n \{\
204 .sp
205 .\}
206 .RS 4
207 .it 1 an-trap
208 .nr an-no-space-flag 1
209 .nr an-break-flag 1
210 .br
211 .ps +1
212 \fBNote\fR
213 .ps -1
214 .br
215 .PP
216 A backslash followed by either a backslash, or a matching quote, is the only situation where the backslash character is actually removed, leaving only the following character in the actual text literal\&. If a backslash character is followed by any other character, the backslash is NOT removed\&.
217 .sp .5v
218 .RE
219 .PP
220 Multiple text literals in a row are automatically concatenated, even if they use different quotes\&. For example:
221 .sp
222 .if n \{\
223 .RS 4
224 .\}
225 .nf
226 FOOBAR="Foo"\*(Aqbar\*(Aq
227
228 .fi
229 .if n \{\
230 .RE
231 .\}
232 .PP
233 This sets the variable
234 \fIFOOBAR\fR
235 to the text "Foobar"\&.
236 .SS "Variable substitution"
237 .PP
238
239 Variable substitution is performed on text literals that\*(Aqs surrounded by double quotation marks\&. The "$" character, followed by a variable name, is replaced by that variable\*(Aqs contents\&.
240 .sp
241 .if n \{\
242 .RS 4
243 .\}
244 .nf
245 MAILBOX="$HOME/Mailbox"
246
247 .fi
248 .if n \{\
249 .RE
250 .\}
251 .PP
252 This sets the variable
253 \fIMAILBOX\fR
254 to the contents of the variable
255 \fIHOME\fR
256 followed by
257 "/Mailbox"\&. Variable names must begin with an uppercase letter, a lowercase letter, or an underscore\&. Following that, all letters, digits, and underscores are taken as a variable name, and its contents replace the
258 $
259 sign, and the variable name\&. It is possible to access variables whose name includes other characters, by using braces as follows:
260 .sp
261 .if n \{\
262 .RS 4
263 .\}
264 .nf
265 MAILBOX="${HOME\-WORD}/Mailbox"
266
267 .fi
268 .if n \{\
269 .RE
270 .\}
271 .PP
272 Inserts the contents of the
273 \fIHOME\-WORD\fR
274 variable\&. If the variable does not exist, the empty text literal is used to replace the variable name\&. It is not possible to access variables whose names include the
275 }
276 character\&.
277 .PP
278 If the
279 $
280 character is not followed by a left brace, letter, or an underscore, the
281 $
282 character remains unmolested in the text literal\&. A backslash followed by the
283 $
284 character results in a
285 $
286 character in the text literal, without doing any variable substitution\&.
287 .PP
288 Variable substitution is not done in text literals which are surrounded by single quotes (apostrophes)\&.
289 .SS "Command line arguments"
290 .PP
291 \fBmaildrop\fR
292 initializes special variables:
293 \fI$1\fR,
294 \fI$2\fR, and so on, with additional parameters specified on the
295 \fBmaildrop\fR
296 command line\&. A
297 filter file
298 may use those variables just like any other variables\&.
299 .SS "Predefined variables"
300 .PP
301 The following variables are automatically defined by
302 \fBmaildrop\fR\&. The default values for the following variables may be changed by the system administrator\&. For security reasons, the values of the following variables are always reset to their default values, and are never imported from the environment:
303 .PP
304 \fIDEFAULT\fR
305 .RS 4
306 The default mailbox to deliver the message to\&. If the
307 filter file
308 does not indicate a mailbox to deliver this message to, the message is delivered to this mailbox\&. The default mailbox is defined by the system administrator\&.
309 .RE
310 .PP
311 \fIFROM\fR
312 .RS 4
313 Message envelope sender\&. This is usually the same address as what appears in the
314 From:
315 header, but may not be\&. This information may or may not be available to
316 \fBmaildrop\fR
317 on your system\&. The message envelope sender is usually specified with the
318 \fB\-f\fR
319 option to
320 \fBmaildrop\fR\&. If the
321 \fB\-f\fR
322 option is not given,
323 \fBmaildrop\fR
324 looks for the
325 Return\-Path:
326 header in the message\&. As the last resort,
327 FROM
328 defaults to
329 \(lqMAILER\-DAEMON\(rq\&. Note that
330 \fIFROM\fR
331 may be empty \- the message envelope sender is empty for bounce messages\&.
332 .RE
333 .PP
334 \fIHOME\fR
335 .RS 4
336 Home directory of the user running
337 \fBmaildrop\fR\&.
338 .RE
339 .PP
340 \fIHOSTNAME\fR
341 .RS 4
342 Network name of the machine running maildrop\&. Obtained from
343 \fBgethostname\fR(3)\&.
344 .RE
345 .PP
346 \fILOCKEXT\fR
347 .RS 4
348 Extension for dot\-lock files (default:
349 \&.lock)\&.
350 .RE
351 .PP
352 \fILOCKREFRESH\fR
353 .RS 4
354 Refresh interval, in seconds, for dot\-locks (default:
355 15)\&. When
356 \fBmaildrop\fR
357 dot\-locks a mailbox,
358 \fBmaildrop\fR
359 tries to refresh the lock periodically in order to keep other programs from removing a stale dot\-lock\&. This is only required if a dot\-lock exists for a prolonged period of time, which should be discouraged anyway\&.
360 .RE
361 .PP
362 \fILOCKSLEEP\fR
363 .RS 4
364 Number of seconds to wait to try again to create a dot\-lock file, if one already exists (default: 5)\&.
365 .RE
366 .PP
367 \fILOCKTIMEOUT\fR
368 .RS 4
369 Number of seconds to wait before removing a stale dot\-lock file (default:
370 60)\&. If a dot\-lock file still exists after
371 \fILOCKTIMEOUT\fR
372 seconds,
373 \fBmaildrop\fR
374 assumes that the process holding the lock no longer exists, and the dot\-lock file can be safely removed\&. After removing the dot\-lock file,
375 \fBmaildrop\fR
376 waits
377 \fILOCKSLEEP\fR
378 seconds before trying to create its own dot\-lock file, in order to avoid a race condition with another process which is also trying to remove the same stale dot\-lock, at the same time\&.
379 .RE
380 .PP
381 \fILOGNAME\fR
382 .RS 4
383 Name of the user to who the message is being delivered\&.
384 .RE
385 .PP
386 \fIMAILFILTER\fR
387 .RS 4
388 This is the name of the original
389 filter file
390 that was given to
391 \fBmaildrop\fR
392 on the command line\&. This is mostly useful to
393 \-default
394 filter files, it allows them to obtain the
395 \m[blue]\fBvalue of the \-M option\fR\m[]\&\s-2\u[3]\d\s+2
396 specified on the command line\&.
397 .RE
398 .PP
399 \fIPATH\fR
400 .RS 4
401 Command execution path\&.
402 \fBmaildrop\fR
403 resets PATH to the system default (usually
404 /bin:/usr/bin:/usr/local/bin)\&.
405 .RE
406 .PP
407 \fISENDMAIL\fR
408 .RS 4
409 The mail delivery agent\&. When
410 \fBmaildrop\fR
411 is instructed to deliver the message to a mailbox whose name begins with the ! character, this is interpreted as a request to forward the message\&. The
412 \fISENDMAIL\fR
413 command is executed to forward the message\&.
414 .RE
415 .PP
416 \fISHELL\fR
417 .RS 4
418 The login shell\&. The shell is used to execute all commands invoked by
419 \fBmaildrop\fR\&.
420 .RE
421 .PP
422 \fIVERBOSE\fR
423 .RS 4
424 Current Debug level (default:
425 0)\&. Setting
426 \fIVERBOSE\fR
427 to progressive higher values, between 1 and 9, produces debugging output on standard error\&.
428 \fBmaildrop\fR
429 ignores the
430 \fIVERBOSE\fR
431 variable in delivery mode (in order not to confuse the mail transport agent)\&.
432 .RE
433 .PP
434 \fIUMASK\fR
435 .RS 4
436 The file creation mode mask, in octal\&. The default setting of
437 077
438 creates mailboxes that are readable and writable by the owner only\&. Use
439 007
440 to create mailboxes that are readable/writable by both owner and the group\&. Use
441 037
442 to create mailboxes that are readable by both owner and group, but writable by owner only\&. Permissions on existing mailboxes are not changed, this setting affects only new mailboxes\&. When delivering to maildirs this setting sets the permissions on new messages only\&. Access permissions on messages in maildirs are also affected by the permissions on the maildir directories\&.
443 .RE
444 .SS "Other special variables"
445 .PP
446 The following variables are automatically used by
447 \fBmaildrop\fR
448 when the
449 filter file
450 is being processed:
451 .PP
452 \fIEXITCODE\fR
453 .RS 4
454 Return code for
455 \fBmaildrop\fR\&. When
456 \fBmaildrop\fR
457 successfully delivers a message, it terminates with this exit code, which defaults to 0\&. When the
458 \fBto\fR
459 or the
460 \fBcc\fR
461 command is used to deliver the message to an external process, via a pipe,
462 \fBmaildrop\fR
463 will set this variable to the exit code of the external process\&. Since
464 \fBmaildrop\fR
465 immediately terminates after completing the
466 \fBto\fR
467 command this means that
468 \fBmaildrop\fR\*(Aqs exit code will be the exit code of the external process\&. If the
469 \fBto\fR
470 command does not deliver the message to a process you must set
471 \fIEXITCODE\fR
472 before the
473 \fBto\fR
474 command, since
475 \fBmaildrop\fR
476 terminates immediately after finishing the delivery\&.
477 .RE
478 .PP
479 \fIFLAGS\fR
480 .RS 4
481 The
482 \fIFLAGS\fR
483 variable is used only when delivering a message to a maildir, and may contain only the following letters:
484 \(lqD\(rq,
485 \(lqF\(rq,
486 \(lqR\(rq, and
487 \(lqS\(rq\&. They may appear in any order\&. When the message gets delivered to the maildir, the message will be marked with a draft, flag, replied, or seen, attribute, correspondingly\&.
488 .sp
489 \fIFLAGS\fR
490 must be set before the message is delivered to a maildir\&. The contents of
491 \fIFLAGS\fR
492 are ignored, when delivering on an mbox folder\&.
493 .RE
494 .PP
495 \fIKEYWORDS\fR
496 .RS 4
497 The
498 \fIKEYWORDS\fR
499 variable is used only when delivering a message to a maildir, and implements the optional IMAP keyword extension as implemented in the
500 \m[blue]\fBCourier IMAP server\fR\m[]\&\s-2\u[1]\d\s+2\&. It may be optionally initialized to contain a comma\-separate list of keywords\&. The
501 \fBto\fR, or the
502 \fBcc\fR
503 command, delivers the message to the maildir normally, but also associated the list of keywords in
504 \fIKEYWORDS\fR
505 with the newly delivered message\&.
506 .sp
507 \fIKEYWORDS\fR
508 must be set before the message is delivered to a maildir\&. The contents of
509 \fIKEYWORDS\fR
510 are ignored, when delivering on an mbox folder\&.
511 .RE
512 .PP
513 \fILINES\fR
514 .RS 4
515 Number of lines in the current message\&. Note that this may be an approximation\&. It may or may not take into account the \-A option\&. Use this as criteria for filtering, nothing more\&.
516 .RE
517 .PP
518 \fIMAILDIRQUOTA\fR
519 .RS 4
520 Set this variable in order to manually enforce a maximum size on ANY maildir where the message is delivered\&. This is an optional feature that must be enabled by the system administrator, see
521 \m[blue]\fB\fBmaildirquota\fR(8)\fR\m[]\&\s-2\u[4]\d\s+2
522 for more information\&.
523 .RE
524 .PP
525 \fIRETURNCODE\fR
526 .RS 4
527 This variable is set when
528 \fBmaildrop\fR
529 runs the
530 \m[blue]\fBsystem\fR\m[]\&\s-2\u[5]\d\s+2
531 command,
532 \m[blue]\fBxfilter\fR\m[]\&\s-2\u[6]\d\s+2
533 command, or a command that\*(Aqs specified within a pair of backtick characters ( command substitution )\&. The
534 \fIRETURNCODE\fR
535 variable will be set to the exit code of the command, after it completes\&.
536 .RE
537 .PP
538 \fISIZE\fR
539 .RS 4
540 Number of bytes in the message\&. This may or may not include the \-A option\&. Use this as a criteria for filtering, nothing more\&.
541 .RE
542 .SS "Unquoted text"
543 .PP
544 All text strings in
545 filter files should be in single, or double quotes\&. However, for convenience sake, quotes can be omitted under certain circumstances\&.
546 .PP
547 Text that includes ONLY letters, digits, and the following characters:
548 _\-\&.:/${}@
549 may appear without quotes\&. Note that this does not allow spaces, or backslashes to be entered, however the text is still variable\-substituted, and the substituted text may contain other characters\&.
550 .PP
551 Also, note that patterns (see below) begin with the slash character\&. Normally, anything that begins with the slash is interpreted as a pattern\&. However, text immediately after
552 \(lqVARIABLE=\(rq
553 is interpreted as a string even if it begins with a slash\&. This is why something like:
554 .sp
555 .if n \{\
556 .RS 4
557 .\}
558 .nf
559 MAILDIR=/var/mail
560
561 .fi
562 .if n \{\
563 .RE
564 .\}
565 .PP
566 works as expected\&. Using quotes, though, is highly recommended\&. You must use quotes to set a variable to a lone slash, because an unquoted slash is interpreted as a division sign\&.
567 .PP
568 Long double or singly\-quoted text can be broken across multiple lines by ending the line with a lone backslash character, like this:
569 .sp
570 .if n \{\
571 .RS 4
572 .\}
573 .nf
574 TEXT="This is a long \e
575 text string"
576
577 .fi
578 .if n \{\
579 .RE
580 .\}
581 .PP
582 The backslash, the newline, and all leading whitespace on the next line is removed, resulting in "This is a long text string"\&.
583 .SS "Command substitution"
584 .PP
585 Text enclosed in back\-tick characters is interpreted as a shell command\&. The shell command is executed as a child process by
586 \fBmaildrop\fR\&. Its output is used in place of the command\&. For example:
587 .sp
588 .if n \{\
589 .RS 4
590 .\}
591 .nf
592 DIR=`ls`
593
594 .fi
595 .if n \{\
596 .RE
597 .\}
598 .PP
599 places the names of the files in the current directory into the DIR variable\&.
600 .PP
601 The output of the command will have all newline characters replaced by spaces, and leading and trailing spaces will be stripped (multiple spaces are not removed, though)\&. Also, the contents of the message being delivered is made available to the command on standard input\&.
602 .SS "Patterns"
603 .PP
604 The pattern syntax in
605 \fBmaildrop\fR
606 is similar to the
607 \fBgrep\fR
608 command\*(Aqs syntax, with some minor differences\&. A pattern takes the following form in the
609 filter file:
610 .sp
611 .if n \{\
612 .RS 4
613 .\}
614 .nf
615 /\fIpattern\fR/:\fIoptions\fR
616
617 .fi
618 .if n \{\
619 .RE
620 .\}
621 .PP
622 \fIpattern\fR
623 specifies the text to look for in the message, in the
624 UTF\-8
625 codeset\&.
626 \fIpattern\fR
627 must not begin with a space, otherwise the leading slash will then be interpreted as a division sign\&. If you must search for text that starts with a space, use something like
628 "/[ ] \&.\&.\&. /"\&.
629 .PP
630 The general syntax of
631 \fBmaildrop\fR\*(Aqs patterns is described in the
632 \fBpcrepattern\fR(3)
633 manual page, with certain exceptions noted below\&.
634 \fBmaildrop\fR
635 uses the
636 \m[blue]\fBPCRE\fR\m[]\&\s-2\u[7]\d\s+2
637 library to implement pattern matching\&. Not all features in
638 PCRE
639 are available in
640 \fBmaildrop\fR, and the
641 \(lqoptions\(rq
642 part, which follows the pattern specification, changes the pattern matching further\&. Consult the
643 \fBpcrepattern\fR(3)
644 manual page for more information, but note the following exceptions:
645 .sp
646 .RS 4
647 .ie n \{\
648 \h'-04'\(bu\h'+03'\c
649 .\}
650 .el \{\
651 .sp -1
652 .IP \(bu 2.3
653 .\}
654 Internal options settings are not supported (but see the
655 \(lqD\(rq
656 maildrop option, below)\&. Do not include option settings in the
657 \fIpattern\fR, doing so will lead to undefined results\&.
658 .RE
659 .sp
660 .RS 4
661 .ie n \{\
662 \h'-04'\(bu\h'+03'\c
663 .\}
664 .el \{\
665 .sp -1
666 .IP \(bu 2.3
667 .\}
668 Named subpatterns are not implemented\&. Numbered subpatterns are implemented, see
669 the section called \(lqPattern Match Results\(rq, below\&.
670 .RE
671 .sp
672 .RS 4
673 .ie n \{\
674 \h'-04'\(bu\h'+03'\c
675 .\}
676 .el \{\
677 .sp -1
678 .IP \(bu 2.3
679 .\}
680 The search pattern gets executed not against the raw message text, but the message transcoded into a canonical UTF\-8\-based format\&. This process involves transcoding any non\-UTF\-8 message content into UTF\-8\&. Additionally, message headers get converted into a canonical format before the search pattern gets executed\&.
681 .sp
682 For structured headers with email addresses, the process involves removing extraneous punctuation, or adding missing ones (in situations where a missing punctuation character can be deduced)\&. Additionally certain pre\-RFC822 obsolete header formats get converted to canonical form\&.
683 .sp
684 This means that header search patterns that include punctuation character may appear not to work against obviously\-matching message text\&. Use
685 \(lqreformime \-u <message\&.txt\(rq, with
686 message\&.txt
687 containing the sample message, to see exactly the actual text that gets searched by patterns\&.
688 .RE
689 .SS "Pattern options"
690 .PP
691 Following
692 /\fIpattern\fR/,
693 there may be an optional colon, followed by one\&. or more options\&. The following options may be specified in any order:
694 .PP
695 h
696 .RS 4
697 Match this pattern in the message\*(Aqs header, and the header of any attachments in the message\&.
698 .RE
699 .PP
700 H
701 .RS 4
702 Match this pattern in the message\*(Aqs main header\&. Do not match this pattern in the headers of the message\*(Aqs attachments\&.
703 .RE
704 .PP
705 b
706 .RS 4
707 Match this pattern against the message body\&.
708 .RE
709 .PP
710 D
711 .RS 4
712 This is a case sensitive match\&. Normally the patterns match either uppercase or lowercase text\&.
713 /john/
714 will match "John", "john", or "JOHN"\&. Specify the D option for a case\-sensitive search: lowercase letters in the pattern must match lowercase letters in the message; ditto for uppercase\&.
715 .RE
716 .PP
717 If neither \*(Aqh\*(Aq, \*(AqH\*(Aq, or \*(Aqb\*(Aq is specified, \*(Aqh\*(Aq is the default, matching the pattern in the message\*(Aqs header, and all attachments\*(Aq headers\&. Specifying the \*(Aqb\*(Aq option causes the pattern to be matched against the message body\&. Specifying \*(Aqb\*(Aq and \*(Aqh\*(Aq causes the pattern to be matched against the entire message\&.
718 .PP
719 Normally, each line in the message gets matched against the pattern individually\&. When applying patterns to a header, multi\-line headers (headers split on several lines by beginning each continuation line with whitespace) are silently combined into a single line, before the pattern is applied\&.
720 .SS "MIME encoding"
721 .PP
722 The pattern must be a valid text string in the
723 UTF\-8
724 codeset, and
725 \fBmaildrop\fR
726 should handle messages that use MIME encodings in other known character sets\&.
727 Options
728 that specify a message header search result in
729 \fBmaildrop\fR
730 searching the initial message headers, and any headers of additional MIME sections, in a multipart MIME message\&. Options that specify a message body search will search through all "text" MIME content\&.
731 .PP
732 For a MIME search to succeed, the message must be a well\-formed MIME message (with a Mime\-Version: 1\&.0 header)\&.
733 .SS "Weighted scoring"
734 .PP
735 Patterns are evaluated by
736 \fBmaildrop\fR
737 as any other numerical expression\&. If a pattern is found,
738 \fBmaildrop\fR\*(Aqs filter interprets the results of the pattern match as number 1, or true, for filtering purposes\&. If a pattern is not found the results of the pattern search is zero\&. Once a pattern is found, the search stops\&. Second, and subsequent occurrences of the same pattern are NOT searched for\&.
739 .PP
740 \fBmaildrop\fR
741 can also do weighted scoring\&. In weighted scoring, multiple occurrences of the same pattern are used to calculate a numerical score\&.
742 .PP
743 To use a weighted search, specify the pattern as follows:
744 .sp
745 .if n \{\
746 .RS 4
747 .\}
748 .nf
749 /\fIpattern\fR/:\fIoptions\fR,\fIxxx\fR,\fIyyy\fR
750
751 .fi
752 .if n \{\
753 .RE
754 .\}
755 .PP
756 where
757 \fIxxx\fR
758 and
759 \fIyyy\fR
760 are two numbers\&.
761 \fIyyy\fR
762 is optional \-\- it will default to 1, if missing\&.
763 .PP
764 The first occurrence of the pattern is evaluated as xxx\&. The second occurrence of the pattern is evaluated as xxx*yyy, the third as xxx*yyy*yyy, etc\&.\&.\&. All occurrences of the pattern are added up to calculate the final score\&.
765 .if n \{\
766 .sp
767 .\}
768 .RS 4
769 .it 1 an-trap
770 .nr an-no-space-flag 1
771 .nr an-break-flag 1
772 .br
773 .ps +1
774 \fBNote\fR
775 .ps -1
776 .br
777 .PP
778 \fBmaildrop\fR
779 does not recognize multiple occurrences of the same pattern in the same line\&. Multiple occurences of the same pattern in one line count as one occurence\&.
780 .sp .5v
781 .RE
782 .SS "Pattern Match Results"
783 .PP
784 After a pattern is successfully matched, the actual text that is matched is placed in the
785 \fIMATCH\fR
786 variable\&. For example:
787 .sp
788 .if n \{\
789 .RS 4
790 .\}
791 .nf
792 /^From:\&.*/
793
794 .fi
795 .if n \{\
796 .RE
797 .\}
798 .PP
799 matches a line of the form:
800 .sp
801 .if n \{\
802 .RS 4
803 .\}
804 .nf
805 From: postmaster@localhost
806
807 .fi
808 .if n \{\
809 .RE
810 .\}
811 .PP
812 Here the variable
813 \fIMATCH\fR
814 will be set to "From: postmaster@localhost", which can be used in subsequent statements\&.
815 .PP
816 If the pattern contains subpatterns, the portions of the text that match the first subpattern is placed in the
817 \fIMATCH1\fR
818 variable\&. The second subpattern, if any, is placed in
819 \fIMATCH2\fR, and so on:
820 .sp
821 .if n \{\
822 .RS 4
823 .\}
824 .nf
825 /^From:\es+(\&.*)@(\&.*)/
826
827 .fi
828 .if n \{\
829 .RE
830 .\}
831 .PP
832 matched against the same line will set
833 \fIMATCH\fR
834 to
835 \(lqFrom: postmaster@localhost\(rq,
836 \fIMATCH1\fR
837 to
838 \(lqpostmaster\(rq, and
839 \fIMATCH2\fR
840 to
841 \(lqlocalhost\(rq\&. Of course, in real world the
842 \(lqFrom:\(rq
843 header is usually much more complicated, and can\*(Aqt be handled that easily\&. This is just an illustrative example\&.
844 .if n \{\
845 .sp
846 .\}
847 .RS 4
848 .it 1 an-trap
849 .nr an-no-space-flag 1
850 .nr an-break-flag 1
851 .br
852 .ps +1
853 \fBNote\fR
854 .ps -1
855 .br
856 .PP
857 The contents of all
858 \fIMATCH\fR
859 variables use UTF\-8 encoding\&. As explained in
860 the section called \(lqPatterns\(rq
861 the message gets transcoded into a canonical UTF\-8 format, replacing MIME\-encoded headers with their UTF\-8 equivalent\&. Consequently,
862 \fIMATCH\fR
863 variables that represent matched text are in UTF\-8\&. For example:
864 .sp
865 .if n \{\
866 .RS 4
867 .\}
868 .nf
869 if (/^Subject: *(\&.*)/)
870 .fi
871 .if n \{\
872 .RE
873 .\}
874 .PP
875 This sets
876 \fIMATCH\fR
877 to what\*(Aqs in the
878 \(lqSubject\(rq
879 header, which could possibly use MIME\-encoding, for example:
880 \(lqSubject: =?UTF\-8?B?SMOzbGEh?=\(rq\&. The resulting
881 \fIMATCH\fR
882 shows
883 \(lqHóla!\(rq\&.
884 .sp .5v
885 .RE
886 .SS "Conversion of maildrop 1\&.x patterns to 2\&.0"
887 .PP
888 Although the new
889 PCRE\-based pattern matching code in
890 \fBmaildrop\fR
891 is completely different from the built\-in pattern matching code in
892 \fBmaildrop\fR
893 1\&.x, very few changes will be required to convert recipes to the new syntax\&. The only major differences are:
894 .sp
895 .RS 4
896 .ie n \{\
897 \h'-04'\(bu\h'+03'\c
898 .\}
899 .el \{\
900 .sp -1
901 .IP \(bu 2.3
902 .\}
903 The subexpression format has changed\&. Any pattern that uses subexpression needs to be converted\&. Additionally, references to
904 \fIMATCH2\fR
905 must be replaced with
906 \fIMATCH1\fR,
907 \fIMATCH3\fR
908 to
909 \fIMATCH2\fR, and so on\&. References to plain old
910 \fIMATCH\fR
911 will remain the same\&.
912 .RE
913 .sp
914 .RS 4
915 .ie n \{\
916 \h'-04'\(bu\h'+03'\c
917 .\}
918 .el \{\
919 .sp -1
920 .IP \(bu 2.3
921 .\}
922 The
923 \(lqw\(rq
924 pattern option is no longer possible, with
925 PCRE\&. The very few recipes that use this option, if any actually exist, will have to be rewritten in some other fashion\&.
926 .RE
927 .SS "Expressions"
928 .PP
929 Although
930 \fBmaildrop\fR
931 evaluates expressions numerically, results of expressions are stored as text literals\&. When necessary, text literals are converted to numbers, then the results of a mathematical operation is converted back into a text literal\&.
932 .sp
933 .it 1 an-trap
934 .nr an-no-space-flag 1
935 .nr an-break-flag 1
936 .br
937 .ps +1
938 \fBOperators\fR
939 .RS 4
940 .PP
941 The following operators carry their usual meaning, and are listed in order from lowest precedence, to the highest:
942 .sp
943 .if n \{\
944 .RS 4
945 .\}
946 .nf
947
948 ||
949 &&
950 < <= > >= == != lt le gt ge eq ne
951 |
952 &
953 + \-
954 * /
955 =~ /\fIpattern\fR/
956 /\fIpattern\fR/ ! ~ \fIfunction()\fR
957
958 .fi
959 .if n \{\
960 .RE
961 .\}
962 .RE
963 .sp
964 .it 1 an-trap
965 .nr an-no-space-flag 1
966 .nr an-break-flag 1
967 .br
968 .ps +1
969 \fBVariable assignment\fR
970 .RS 4
971 .sp
972 .if n \{\
973 .RS 4
974 .\}
975 .nf
976 VARIABLE=\fIexpression\fR
977
978 .fi
979 .if n \{\
980 .RE
981 .\}
982 .PP
983 Assigns the result of the expression to
984 \fIVARIABLE\fR
985 (note no leading $ in front of variable)\&.
986 .if n \{\
987 .sp
988 .\}
989 .RS 4
990 .it 1 an-trap
991 .nr an-no-space-flag 1
992 .nr an-break-flag 1
993 .br
994 .ps +1
995 \fBNote\fR
996 .ps -1
997 .br
998 .PP
999 If
1000 \fIVARIABLE\fR
1001 is NOT surrounded by quotes, then it may contain only letters, numbers, underscores, dashes, and a selected few other characters\&. In order to initialize a variable whose name contains non\-standard punctuation marks, surround the name of the variable with quotes\&.
1002 .sp .5v
1003 .RE
1004 .RE
1005 .sp
1006 .it 1 an-trap
1007 .nr an-no-space-flag 1
1008 .nr an-break-flag 1
1009 .br
1010 .ps +1
1011 \fBcc - deliver a copy of the message\fR
1012 .RS 4
1013 .sp
1014 .if n \{\
1015 .RS 4
1016 .\}
1017 .nf
1018 cc \fIexpression\fR
1019
1020 .fi
1021 .if n \{\
1022 .RE
1023 .\}
1024 .PP
1025 The
1026 \fBcc\fR
1027 statement is very similar to the
1028 \fBto\fR
1029 statement, except that after delivering the message
1030 \fBmaildrop\fR
1031 continues to process the
1032 filter file, unlike the
1033 \fBto\fR
1034 statement which immediately terminates
1035 \fBmaildrop\fR
1036 after the delivery is complete\&. Essentially, the message is carbon copied to the given mailbox, and may be delivered again to another mailbox by another
1037 \fBcc\fR
1038 or
1039 \fBto\fR
1040 statement\&.
1041 .PP
1042 \m[blue]\fBSee the \fBto\fR statement\fR\m[]\&\s-2\u[8]\d\s+2
1043 for more details\&. When
1044 \fBcc\fR
1045 is used to deliver a message to a process
1046 \fBmaildrop\fR
1047 will set the
1048 \fIEXITCODE\fR
1049 variable to the process\*(Aqs exit code\&.
1050 .RE
1051 .sp
1052 .it 1 an-trap
1053 .nr an-no-space-flag 1
1054 .nr an-break-flag 1
1055 .br
1056 .ps +1
1057 \fBdotlock - create a manual dot-lock\fR
1058 .RS 4
1059 .sp
1060 .if n \{\
1061 .RS 4
1062 .\}
1063 .nf
1064 dotlock \fIexpression\fR {
1065
1066 \&.\&.\&.
1067
1068 }
1069
1070 .fi
1071 .if n \{\
1072 .RE
1073 .\}
1074 .PP
1075 \fBmaildrop\fR
1076 automatically creates a lock when a message is delivered to a mailbox\&. Depending upon your system configuration,
1077 \fBmaildrop\fR
1078 will use either dot\-locks, or the flock() system call\&.
1079 .PP
1080 The
1081 \fBdotlock\fR
1082 statement creates an explicit dot\-lock file\&. Use the
1083 \m[blue]\fB\fBflock\fR statement\fR\m[]\&\s-2\u[9]\d\s+2
1084 to create an explicit flock() lock\&.
1085 .PP
1086 The
1087 \fIexpression\fR
1088 is a filename that should be used as a lock file\&.
1089 \fBmaildrop\fR
1090 creates the indicated dot\-lock, executes the filtering instructions contained within the { \&.\&.\&. } block, and removes the lock\&. The expression
1091 \fImust\fR
1092 be the name of the dot\-lock file itself,
1093 \fINOT\fR
1094 the name of the mailbox file you want to lock\&.
1095 .if n \{\
1096 .sp
1097 .\}
1098 .RS 4
1099 .it 1 an-trap
1100 .nr an-no-space-flag 1
1101 .nr an-break-flag 1
1102 .br
1103 .ps +1
1104 \fBNote\fR
1105 .ps -1
1106 .br
1107 .PP
1108 With manual locking, it is possible to deadlock multiple
1109 \fBmaildrop\fR
1110 processes (or any other processes that try to claim the same locks)\&.
1111 .PP
1112 No deadlock detection is possible with dot\-locks, and since
1113 \fBmaildrop\fR
1114 automatically refreshes all of its dot\-locks regularly, they will never go stale\&. You\*(Aqll have
1115 \fBmaildrop\fR
1116 processes hanging in limbo, until their watchdog timers go off, aborting the mail delivery\&.
1117 .sp .5v
1118 .RE
1119 .RE
1120 .sp
1121 .it 1 an-trap
1122 .nr an-no-space-flag 1
1123 .nr an-break-flag 1
1124 .br
1125 .ps +1
1126 \fBecho - output diagnostic information\fR
1127 .RS 4
1128 .sp
1129 .if n \{\
1130 .RS 4
1131 .\}
1132 .nf
1133 echo \fIexpression\fR
1134
1135 .fi
1136 .if n \{\
1137 .RE
1138 .\}
1139 .PP
1140 \fBmaildrop\fR
1141 will print the given text\&. This is usually used when
1142 \fBmaildrop\fR
1143 runs in embedded mode, but can be used for debugging purposes\&. Normally, a newline is printed after the text\&. If text is terminated with a \ec, no newline will be printed\&.
1144 .RE
1145 .sp
1146 .it 1 an-trap
1147 .nr an-no-space-flag 1
1148 .nr an-break-flag 1
1149 .br
1150 .ps +1
1151 \fBexception - trap fatal errors\fR
1152 .RS 4
1153 .sp
1154 .if n \{\
1155 .RS 4
1156 .\}
1157 .nf
1158 exception {
1159
1160 \&.\&.\&.
1161
1162 }
1163
1164 .fi
1165 .if n \{\
1166 .RE
1167 .\}
1168 .PP
1169 The
1170 \fBexception\fR
1171 statement traps errors that would normally cause
1172 \fBmaildrop\fR
1173 to terminate\&. If a fatal error is encountered anywhere within the block of statements enclosed by the
1174 \fBexception\fR
1175 clause, execution will resume immediately following the
1176 \fBexception\fR
1177 clause\&.
1178 .RE
1179 .sp
1180 .it 1 an-trap
1181 .nr an-no-space-flag 1
1182 .nr an-break-flag 1
1183 .br
1184 .ps +1
1185 \fBexit - terminate filtering unconditionally\fR
1186 .RS 4
1187 .sp
1188 .if n \{\
1189 .RS 4
1190 .\}
1191 .nf
1192 exit
1193
1194 .fi
1195 .if n \{\
1196 .RE
1197 .\}
1198 .PP
1199 The
1200 \fBexit\fR
1201 statement immediately terminates filtering\&.
1202 \fBmaildrop\fR\*(Aqs return code is set to the value of the
1203 \fIEXITCODE\fR
1204 variable\&. Normally,
1205 \fBmaildrop\fR
1206 terminates immediately after
1207 \m[blue]\fBsuccessfully delivering the message\fR\m[]\&\s-2\u[8]\d\s+2
1208 to a mailbox\&. The
1209 \fBexit\fR
1210 statement causes
1211 \fBmaildrop\fR
1212 to terminate without delivering the message anywhere\&.
1213 .PP
1214 The
1215 \fBexit\fR
1216 statement is usually used when
1217 \fBmaildrop\fR
1218 runs in
1219 \m[blue]\fBembedded mode\fR\m[]\&\s-2\u[10]\d\s+2, when message delivery instructions are not allowed\&.
1220 .RE
1221 .sp
1222 .it 1 an-trap
1223 .nr an-no-space-flag 1
1224 .nr an-break-flag 1
1225 .br
1226 .ps +1
1227 \fBflock - create an manual flock() lock\fR
1228 .RS 4
1229 .sp
1230 .if n \{\
1231 .RS 4
1232 .\}
1233 .nf
1234 flock \fIexpression\fR {
1235
1236 \&.\&.\&.
1237
1238 }
1239
1240 .fi
1241 .if n \{\
1242 .RE
1243 .\}
1244 .PP
1245 \fBmaildrop\fR
1246 automatically creates a lock when a message is delivered to a mailbox\&. Depending upon your system configuration,
1247 \fBmaildrop\fR
1248 will use either dot\-locks, or the flock() system call\&.
1249 .PP
1250 The
1251 \fBflock\fR
1252 statement creates a manual flock() lock\&. Use the
1253 \m[blue]\fB\fBdotlock\fR statement\fR\m[]\&\s-2\u[11]\d\s+2
1254 to create a manual dot\-lock file\&.
1255 .PP
1256 The
1257 \fIexpression\fR
1258 is the name of the file that should be locked\&.
1259 \fBmaildrop\fR
1260 creates the lock on the indicated file, executes the filtering instructions contained within the { \&.\&.\&. } block, and removes the lock\&.
1261 .if n \{\
1262 .sp
1263 .\}
1264 .RS 4
1265 .it 1 an-trap
1266 .nr an-no-space-flag 1
1267 .nr an-break-flag 1
1268 .br
1269 .ps +1
1270 \fBNote\fR
1271 .ps -1
1272 .br
1273 .PP
1274 With manual locking, it is possible to deadlock multiple
1275 \fBmaildrop\fR
1276 processes (or any other processes that try to claim the same locks)\&. The operating system will automatically break flock() deadlocks\&. When that happens, one of the
1277 \fBmaildrop\fR
1278 processes will terminate immediately\&. Use the
1279 \fBexception\fR
1280 statement in order to trap this exception condition, and execute an alternative set of filtering instructions\&.
1281 .sp .5v
1282 .RE
1283 .RE
1284 .sp
1285 .it 1 an-trap
1286 .nr an-no-space-flag 1
1287 .nr an-break-flag 1
1288 .br
1289 .ps +1
1290 \fBforeach - iterate over text sections matched by a pattern\fR
1291 .RS 4
1292 .sp
1293 .if n \{\
1294 .RS 4
1295 .\}
1296 .nf
1297 foreach /pattern/:options
1298 {
1299 \&.\&.\&.
1300 }
1301
1302 foreach (expression) =~ /pattern/:options
1303 {
1304 \&.\&.\&.
1305 }
1306
1307 .fi
1308 .if n \{\
1309 .RE
1310 .\}
1311 .PP
1312 The
1313 \fBforeach\fR
1314 statement executes a block of statements for each occurrence of the given pattern in the given message, or expression\&. On every iteration
1315 \fIMATCH\fR
1316 variable will be set to the matched string\&. Subpatterns set
1317 \fIMATCH1\fR,
1318 \fIMATCH2\fR, and so on, before beginning each iteration\&.
1319 .PP
1320 All the usual options may be applied to the pattern match, EXCEPT the following:
1321 .PP
1322 ,xxx,yyy
1323 .RS 4
1324 Weighted scoring is meaningless, in this context\&.
1325 .RE
1326 .RE
1327 .sp
1328 .it 1 an-trap
1329 .nr an-no-space-flag 1
1330 .nr an-break-flag 1
1331 .br
1332 .ps +1
1333 \fBif - conditional execution\fR
1334 .RS 4
1335 .sp
1336 .if n \{\
1337 .RS 4
1338 .\}
1339 .nf
1340 if (\fIexpression\fR)
1341 {
1342 \&.\&.\&.
1343 }
1344 else
1345 {
1346 \&.\&.\&.
1347 }
1348
1349 .fi
1350 .if n \{\
1351 .RE
1352 .\}
1353 .PP
1354 Conditional execution\&. If
1355 \fIexpression\fR
1356 evaluates to a logical true (note \- parenthesis are required) then the first set of statements is executed\&. The
1357 \fBelse\fR
1358 keyword, and the subsequent statements, are optional\&. If present, and the expression evaluates to a logical false, the
1359 \fBelse\fR
1360 part is executed\&.
1361 .PP
1362 \fBmaildrop\fR
1363 evaluates all expression as text strings\&. In the context of a logical expression, an empty string, or the number 0 constitutes a logical false value, anything else is a logical true value\&.
1364 .PP
1365 If the
1366 \fBif\fR
1367 part, or the
1368 \fBelse\fR
1369 part consists of only one statement, the braces may be omitted\&.
1370 .if n \{\
1371 .sp
1372 .\}
1373 .RS 4
1374 .it 1 an-trap
1375 .nr an-no-space-flag 1
1376 .nr an-break-flag 1
1377 .br
1378 .ps +1
1379 \fBNote\fR
1380 .ps -1
1381 .br
1382 .PP
1383 The grammar of this
1384 \fBif\fR
1385 statement is stricter than usual\&. If you get baffling syntax errors from
1386 \fBmaildrop\fR, make sure that the braces, and the if statement, appear on separate lines\&. Specifically: the closing parenthesis, the closing braces, and the else statement, must be at the end of the line (comments are allowed), and there may not be any blank lines in between (not even ones containing comments only)\&.
1387 .sp .5v
1388 .RE
1389 .PP
1390 If the
1391 \fBelse\fR
1392 part contains a single
1393 \fBif\fR, and nothing else, this may be combined into an
1394 \fBelsif\fR:
1395 .sp
1396 .if n \{\
1397 .RS 4
1398 .\}
1399 .nf
1400 if (\fIexpression\fR)
1401 {
1402 \&.\&.\&.
1403 }
1404 elsif (\fIexpression\fR)
1405 {
1406 \&.\&.\&.
1407 }
1408
1409 .fi
1410 .if n \{\
1411 .RE
1412 .\}
1413 .PP
1414 The above example is logically identical to:
1415 .sp
1416 .if n \{\
1417 .RS 4
1418 .\}
1419 .nf
1420 if (\fIexpression\fR)
1421 {
1422 \&.\&.\&.
1423 }
1424 else
1425 {
1426 if (\fIexpression\fR)
1427 {
1428 \&.\&.\&.
1429 }
1430 }
1431
1432 .fi
1433 .if n \{\
1434 .RE
1435 .\}
1436 .PP
1437 Consecutive
1438 \fBelsif\fR
1439 sequences are allowed:
1440 .sp
1441 .if n \{\
1442 .RS 4
1443 .\}
1444 .nf
1445 if (\fIexpression\fR)
1446 {
1447 \&.\&.\&.
1448 }
1449 elsif (\fIexpression\fR)
1450 {
1451 \&.\&.\&.
1452 }
1453 elsif (\fIexpression\fR)
1454 {
1455 \&.\&.\&.
1456 }
1457
1458 .fi
1459 .if n \{\
1460 .RE
1461 .\}
1462 .PP
1463 Consecutive occurences of
1464 \fBelsif\fR
1465 commands eliminate a significant amount of indentation, and the resulting code is more readable\&.
1466 .RE
1467 .sp
1468 .it 1 an-trap
1469 .nr an-no-space-flag 1
1470 .nr an-break-flag 1
1471 .br
1472 .ps +1
1473 \fBimport - access original environment variable\fR
1474 .RS 4
1475 .sp
1476 .if n \{\
1477 .RS 4
1478 .\}
1479 .nf
1480 import \fIvariable\fR
1481
1482 .fi
1483 .if n \{\
1484 .RE
1485 .\}
1486 .PP
1487 When
1488 \fBmaildrop\fR
1489 starts, it normally imports the contents of the environment variables, and assigns them to internal
1490 \fBmaildrop\fR
1491 variables\&. For example, if there was an environment variable
1492 \fIFOO\fR, the internal
1493 \fBmaildrop\fR
1494 variable
1495 \fIFOO\fR
1496 will have the contents of the environment variable\&. From then on,
1497 \fIFOO\fR
1498 will be no different than any other variable, and when
1499 \fBmaildrop\fR
1500 runs an external command, the contents of
1501 \fBmaildrop\fR\*(Aqs variables will be exported as the environment for the command\&.
1502 .PP
1503 Certain variables, like
1504 \fIHOME\fR
1505 and
1506 \fIPATH\fR, are always reset to fixed defaults, for security reasons\&. Also, in delivery and embedded modes, the environment is not imported at all (with the exception of system locale environment variables), and
1507 \fBmaildrop\fR
1508 starts with only the fixed default variables\&.
1509 .PP
1510 The
1511 \fBimport\fR
1512 statement initializes the specified variable with the contents of the original environment variable when
1513 \fBmaildrop\fR
1514 started\&. For example:
1515 .sp
1516 .if n \{\
1517 .RS 4
1518 .\}
1519 .nf
1520 echo "PATH is $PATH"
1521 PATH="/bin"
1522 echo "PATH is $PATH"
1523 import PATH
1524 echo "PATH is $PATH"
1525 exit
1526
1527 .fi
1528 .if n \{\
1529 .RE
1530 .\}
1531 .PP
1532 This results in the following output:
1533 .sp
1534 .if n \{\
1535 .RS 4
1536 .\}
1537 .nf
1538 PATH is /bin:/usr/bin:/usr/local/bin
1539 PATH is /bin
1540 PATH is /home/root/bin:/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
1541
1542 .fi
1543 .if n \{\
1544 .RE
1545 .\}
1546 .PP
1547 This shows that when
1548 \fBmaildrop\fR
1549 starts
1550 \fIPATH\fR
1551 is set to the fixed default of
1552 /bin:/usr/bin:/usr/local/bin\&. However, the original contents of the
1553 \fIPATH\fR
1554 environment variable we different, and the
1555 \fBimport\fR
1556 statement shows what it was\&.
1557 .RE
1558 .sp
1559 .it 1 an-trap
1560 .nr an-no-space-flag 1
1561 .nr an-break-flag 1
1562 .br
1563 .ps +1
1564 \fBinclude - execute filtering instructions from another file\fR
1565 .RS 4
1566 .sp
1567 .if n \{\
1568 .RS 4
1569 .\}
1570 .nf
1571 include \fIexpression\fR
1572
1573 .fi
1574 .if n \{\
1575 .RE
1576 .\}
1577 .PP
1578 The include statement reads a file, and executes filtering instructions contained in that file\&. Note that the include statement is processed when the current
1579 filter file
1580 is being executed\&. When
1581 \fBmaildrop\fR
1582 reads the initial
1583 filter file, any syntax errors in the filtering instructions are immediately reported, and
1584 \fBmaildrop\fR
1585 will terminate with a return code of
1586 \fBEX_TEMPFAIL\fR\&. Any errors in files specified by
1587 \fBinclude\fR
1588 statements are NOT reported, because those files will not be read until the
1589 \fBinclude\fR
1590 statement is itself executed\&.
1591 .PP
1592 If the specified file does not exist, or if there are any syntax errors in the file,
1593 \fBmaildrop\fR
1594 reports the error, and terminates with a return code of
1595 \fBEX_TEMPFAIL\fR\&.
1596 .RE
1597 .sp
1598 .it 1 an-trap
1599 .nr an-no-space-flag 1
1600 .nr an-break-flag 1
1601 .br
1602 .ps +1
1603 \fBlog, logfile - log message deliveries\fR
1604 .RS 4
1605 .sp
1606 .if n \{\
1607 .RS 4
1608 .\}
1609 .nf
1610 logfile \fIexpression\fR
1611
1612 log \fIexpression\fR
1613
1614 .fi
1615 .if n \{\
1616 .RE
1617 .\}
1618 .PP
1619 Logging in
1620 \fBmaildrop\fR
1621 is normally turned off\&. The
1622 \fBlogfile\fR
1623 statement specifies the file where
1624 \fBmaildrop\fR
1625 will log how the message has been disposed of\&. The parameter is then name of the file\&. If the file exists
1626 \fBmaildrop\fR
1627 appends to the file\&.
1628 .PP
1629 For each delivery (the
1630 \m[blue]\fB\fBto\fR\fR\m[]\&\s-2\u[8]\d\s+2
1631 and
1632 \m[blue]\fB\fBcc\fR\fR\m[]\&\s-2\u[12]\d\s+2
1633 statements, and default deliveries)
1634 \fBmaildrop\fR
1635 records the
1636 From:
1637 and the
1638 Subject:
1639 fields, together with the current time, in the log file\&.
1640 .PP
1641 The
1642 \fBlog\fR
1643 statement adds additional logging text to the log file\&. The
1644 \fBlog\fR
1645 statement works exactly like the
1646 \fBecho\fR
1647 statement, except that the text is written to the logfile, instead of standard output\&.
1648 .RE
1649 .sp
1650 .it 1 an-trap
1651 .nr an-no-space-flag 1
1652 .nr an-break-flag 1
1653 .br
1654 .ps +1
1655 \fBsystem - execute a system command\fR
1656 .RS 4
1657 .sp
1658 .if n \{\
1659 .RS 4
1660 .\}
1661 .nf
1662 system \fIexpression\fR
1663
1664 .fi
1665 .if n \{\
1666 .RE
1667 .\}
1668 .PP
1669 \fIexpression\fR
1670 specifies an external program that
1671 \fBmaildrop\fR
1672 runs as a subprocess\&. The subprocess\*(Aqs standard input gets connected to
1673 /dev/null, and the subprocess inherits the standard output and error from
1674 \fBmaildrop\fR\&.
1675 .RE
1676 .sp
1677 .it 1 an-trap
1678 .nr an-no-space-flag 1
1679 .nr an-break-flag 1
1680 .br
1681 .ps +1
1682 \fBto - deliver message to a mailbox\fR
1683 .RS 4
1684 .sp
1685 .if n \{\
1686 .RS 4
1687 .\}
1688 .nf
1689 to \fIexpression\fR
1690
1691 .fi
1692 .if n \{\
1693 .RE
1694 .\}
1695 .PP
1696 The
1697 \fBto\fR
1698 statement delivers the message to a mailbox\&.
1699 \fIexpression\fR
1700 must evaluate to a valid mailbox\&. A valid mailbox is either a mailbox file, a maildir, or an external program (which includes forwarding to another address)\&.
1701 .PP
1702 The
1703 \fBto\fR
1704 statement is the final delivery statement\&.
1705 \fBmaildrop\fR
1706 delivers message, then immediately terminates, with its return code set to the
1707 \fIEXITCODE\fR
1708 variable\&. If there was an error while delivering the message,
1709 \fBmaildrop\fR
1710 terminates with the
1711 \fBEX_TEMPFAIL\fR
1712 exit code\&. A properly\-written mail transport agent should re\-queue the message, and re\-attempt delivery at some later time\&.
1713 .PP
1714 An
1715 \fIexpression\fR
1716 that begins with the "|" character specifies an external program to run to handle the actual delivery\&. The
1717 \fISHELL\fR
1718 variable specifies the shell to execute the given command\&. The message is provided to the command on standard input\&.
1719 \fBmaildrop\fR\*(Aqs exit code will be the process\*(Aqs exit code\&.
1720 .PP
1721 An
1722 \fIexpression\fR
1723 that begins with an exclamation mark, "!" specifies a whitespace\-delimited list of E\-mail addresses to forward the message to\&. The program specified by the
1724 \fISENDMAIL\fR
1725 variable is run as an external program, with the list of E\-mail addresses provided as parameters to the program\&.
1726 .PP
1727 Otherwise,
1728 \fIexpression\fR
1729 names the mailbox where
1730 \fBmaildrop\fR
1731 delivers the message\&. If
1732 \fIexpression\fR
1733 is a directory,
1734 \fBmaildrop\fR
1735 assumes that the directory is a maildir directory\&. Otherwise,
1736 \fBmaildrop\fR
1737 will deliver the message to a file, formatted in traditional mailbox format\&.
1738 \fBmaildrop\fR
1739 will use either dot\-locking, or flock()\-locking when delivering the message to the file\&.
1740 .RE
1741 .sp
1742 .it 1 an-trap
1743 .nr an-no-space-flag 1
1744 .nr an-break-flag 1
1745 .br
1746 .ps +1
1747 \fBwhile - repeatedly execute a block of statements\fR
1748 .RS 4
1749 .sp
1750 .if n \{\
1751 .RS 4
1752 .\}
1753 .nf
1754 while (\fIexpression\fR)
1755 {
1756 \&.\&.\&.
1757 }
1758
1759 .fi
1760 .if n \{\
1761 .RE
1762 .\}
1763 .PP
1764 The
1765 \fIexpression\fR
1766 is repeatedly evaluated\&. Each time it
1767 \m[blue]\fBevaluates to a logical true\fR\m[]\&\s-2\u[13]\d\s+2, the statements inside the braces are executed\&. When
1768 \fIexpression\fR
1769 evaluates to a logical false, the while loop is over\&. Take care to avoid infinite loops\&.
1770 .RE
1771 .sp
1772 .it 1 an-trap
1773 .nr an-no-space-flag 1
1774 .nr an-break-flag 1
1775 .br
1776 .ps +1
1777 \fBxfilter - filter message through another program\fR
1778 .RS 4
1779 .sp
1780 .if n \{\
1781 .RS 4
1782 .\}
1783 .nf
1784 xfilter \fIexpression\fR
1785
1786 .fi
1787 .if n \{\
1788 .RE
1789 .\}
1790 .PP
1791 \fIexpression\fR
1792 specifies an external program that
1793 \fBmaildrop\fR
1794 runs to filter the current message\&. The current message will be piped to the filter program as standard input\&. The output of the filter program replaces the current message being delivered\&. The external program must terminate with an exit code of 0\&. If the external program does not terminate with an exit code of 0, or if it does not read the message from the standard input,
1795 \fBmaildrop\fR
1796 terminates with an exit code of
1797 \fBEX_TEMPFAIL\fR\&.
1798 .RE
1799 .sp
1800 .it 1 an-trap
1801 .nr an-no-space-flag 1
1802 .nr an-break-flag 1
1803 .br
1804 .ps +1
1805 \fB|| - logical or\fR
1806 .RS 4
1807 .sp
1808 .if n \{\
1809 .RS 4
1810 .\}
1811 .nf
1812 \fIexpression1\fR || \fIexpression2\fR
1813
1814
1815 .fi
1816 .if n \{\
1817 .RE
1818 .\}
1819 .PP
1820 If
1821 \fIexpression1\fR
1822 evaluates to a logical true, the result of the
1823 ||
1824 is
1825 \fIexpression1\fR, otherwise it\*(Aqs
1826 \fIexpression2\fR, which is evaluated\&.
1827 .PP
1828 \fBmaildrop\fR
1829 uses the following concept of true/false: an empty text literal, or a text literal that consists of the single character "0" is a logical false value\&. Anything else is a logical true value\&.
1830 .RE
1831 .sp
1832 .it 1 an-trap
1833 .nr an-no-space-flag 1
1834 .nr an-break-flag 1
1835 .br
1836 .ps +1
1837 \fB&& - logical and\fR
1838 .RS 4
1839 .sp
1840 .if n \{\
1841 .RS 4
1842 .\}
1843 .nf
1844 \fIexpression1\fR && \fIexpression2\fR
1845
1846
1847 .fi
1848 .if n \{\
1849 .RE
1850 .\}
1851 .PP
1852 If
1853 \fIexpression1\fR
1854 evaluates to a logical false, the result of the
1855 &&
1856 is
1857 \fIexpression1\fR, otherwise it\*(Aqs
1858 \fIexpression2\fR, which is evaluated\&.
1859 .PP
1860 \fBmaildrop\fR
1861 uses the following concept of true/false: an empty text literal, or a text literal that consists of the single character "0" is a logical false value\&. Anything else is a logical true value\&.
1862 .RE
1863 .sp
1864 .it 1 an-trap
1865 .nr an-no-space-flag 1
1866 .nr an-break-flag 1
1867 .br
1868 .ps +1
1869 \fB<, <=, >, >=, ==, != - numerical comparison\fR
1870 .RS 4
1871 .sp
1872 .if n \{\
1873 .RS 4
1874 .\}
1875 .nf
1876 \fIexpression1\fR < \fIexpression2\fR
1877
1878 \fIexpression1\fR <= \fIexpression2\fR
1879
1880 \fIexpression1\fR > \fIexpression2\fR
1881
1882 \fIexpression1\fR >= \fIexpression2\fR
1883
1884 \fIexpression1\fR == \fIexpression2\fR
1885
1886 \fIexpression1\fR != \fIexpression2\fR
1887
1888
1889 .fi
1890 .if n \{\
1891 .RE
1892 .\}
1893 .PP
1894 These operators compare their left hand side expression against their right hand side\&. These operators compare the numerical values of each side, as floating point numbers\&. If the numbers compare as indicated, the result of the comparison is the text string "1", otherwise it is the text string 0\&.
1895 .if n \{\
1896 .sp
1897 .\}
1898 .RS 4
1899 .it 1 an-trap
1900 .nr an-no-space-flag 1
1901 .nr an-break-flag 1
1902 .br
1903 .ps +1
1904 \fBNote\fR
1905 .ps -1
1906 .br
1907 .PP
1908 Ccomparisons are not associative: "a < b < c" is an error\&. If it is absolutely necessary, use "(a < b) < c"\&.
1909 .sp .5v
1910 .RE
1911 .RE
1912 .sp
1913 .it 1 an-trap
1914 .nr an-no-space-flag 1
1915 .nr an-break-flag 1
1916 .br
1917 .ps +1
1918 \fBlt, le, gt, ge, eq, ne - text comparison\fR
1919 .RS 4
1920 .sp
1921 .if n \{\
1922 .RS 4
1923 .\}
1924 .nf
1925 \fIexpression1\fR lt \fIexpression2\fR
1926
1927 \fIexpression1\fR le \fIexpression2\fR
1928
1929 \fIexpression1\fR gt \fIexpression2\fR
1930
1931 \fIexpression1\fR ge \fIexpression2\fR
1932
1933 \fIexpression1\fR eq \fIexpression2\fR
1934
1935 \fIexpression1\fR ne \fIexpression2\fR
1936
1937
1938 .fi
1939 .if n \{\
1940 .RE
1941 .\}
1942 .PP
1943 These operators compare their left hand side expression against their right hand side\&. These operators compare each side as text strings (alphabetically, although the text may include anything)\&. If the text strings compare as indicated, the result of the comparison is the text string "1", otherwise it is the text string 0\&.
1944 .if n \{\
1945 .sp
1946 .\}
1947 .RS 4
1948 .it 1 an-trap
1949 .nr an-no-space-flag 1
1950 .nr an-break-flag 1
1951 .br
1952 .ps +1
1953 \fBNote\fR
1954 .ps -1
1955 .br
1956 .PP
1957 Comparisons are not associative: "a lt b lt c" is an error\&. If it is absolutely necessary, use "(a lt b) lt c"\&. (But why would you?)\&.
1958 .sp .5v
1959 .RE
1960 .RE
1961 .sp
1962 .it 1 an-trap
1963 .nr an-no-space-flag 1
1964 .nr an-break-flag 1
1965 .br
1966 .ps +1
1967 \fB| - bitwise or\fR
1968 .RS 4
1969 .sp
1970 .if n \{\
1971 .RS 4
1972 .\}
1973 .nf
1974 \fIexpression1\fR | \fIexpression2\fR
1975
1976 .fi
1977 .if n \{\
1978 .RE
1979 .\}
1980 .PP
1981 This is the bitwise or operator\&. Its result is a 32 bit integer, which is a bitwise\-or combination of the left hand side and the right hand side\&.
1982 .RE
1983 .sp
1984 .it 1 an-trap
1985 .nr an-no-space-flag 1
1986 .nr an-break-flag 1
1987 .br
1988 .ps +1
1989 \fB& - bitwise and\fR
1990 .RS 4
1991 .sp
1992 .if n \{\
1993 .RS 4
1994 .\}
1995 .nf
1996 \fIexpression1\fR & \fIexpression2\fR
1997
1998 .fi
1999 .if n \{\
2000 .RE
2001 .\}
2002 .PP
2003 This is the bitwise and operator\&. Its result is a 32 bit integer, which is a bitwise\-and combination of the left hand side and the right hand side\&.
2004 .RE
2005 .sp
2006 .it 1 an-trap
2007 .nr an-no-space-flag 1
2008 .nr an-break-flag 1
2009 .br
2010 .ps +1
2011 \fB+, -, *, / - numerical operations\fR
2012 .RS 4
2013 .sp
2014 .if n \{\
2015 .RS 4
2016 .\}
2017 .nf
2018 \fIexpression1\fR + \fIexpression2\fR
2019
2020 \fIexpression1\fR \- \fIexpression2\fR
2021
2022 \fIexpression1\fR * \fIexpression2\fR
2023
2024 \fIexpression1\fR / \fIexpression2\fR
2025
2026
2027 .fi
2028 .if n \{\
2029 .RE
2030 .\}
2031 .PP
2032 These are numerical, floating point, operators\&.
2033 .RE
2034 .sp
2035 .it 1 an-trap
2036 .nr an-no-space-flag 1
2037 .nr an-break-flag 1
2038 .br
2039 .ps +1
2040 \fB=~ /pattern/:options - pattern match against string\fR
2041 .RS 4
2042 .sp
2043 .if n \{\
2044 .RS 4
2045 .\}
2046 .nf
2047 \fIexpression\fR =~ /\fIpattern\fR/:\fIoption\fR
2048
2049 .fi
2050 .if n \{\
2051 .RE
2052 .\}
2053 .PP
2054 The left hand side of the
2055 =~
2056 operator can be any expression\&. The right hand side is always a pattern specification\&. The result of the operator is the weighted match of the pattern against
2057 \fIexpression\fR
2058 (if the options do not specify weighted scoring, the result is simply 1 if the pattern was found, 0 if not)\&.
2059 .PP
2060 See "\m[blue]\fBPatterns\fR\m[]\&\s-2\u[14]\d\s+2" for more information\&.
2061 .RE
2062 .sp
2063 .it 1 an-trap
2064 .nr an-no-space-flag 1
2065 .nr an-break-flag 1
2066 .br
2067 .ps +1
2068 \fB/pattern/:options - pattern match against message\fR
2069 .RS 4
2070 .sp
2071 .if n \{\
2072 .RS 4
2073 .\}
2074 .nf
2075 /\fIpattern\fR/:\fIoption\fR
2076
2077 .fi
2078 .if n \{\
2079 .RE
2080 .\}
2081 .PP
2082 The result of this operator is the weighted match of the pattern against the current message (if the options do not specify weighted scoring, the result is simply 1 if the pattern was found, 0 if not)\&.
2083 .PP
2084 See "\m[blue]\fBPatterns\fR\m[]\&\s-2\u[14]\d\s+2" for more information\&.
2085 .RE
2086 .sp
2087 .it 1 an-trap
2088 .nr an-no-space-flag 1
2089 .nr an-break-flag 1
2090 .br
2091 .ps +1
2092 \fB!, ~ - logical/bitwise not operator.\fR
2093 .RS 4
2094 .sp
2095 .if n \{\
2096 .RS 4
2097 .\}
2098 .nf
2099 ! \fIexpression\fR
2100
2101 ~ \fIexpression\fR
2102
2103 .fi
2104 .if n \{\
2105 .RE
2106 .\}
2107 .PP
2108 The result of the
2109 !
2110 operator is a logical opposite of its right hand side expression\&. If the right hand side expression evaluated to a logical true, the result is a logical false\&. If it evaluated to a logical false, the result is a logical true\&.
2111 .PP
2112 \fBmaildrop\fR
2113 uses the following concept of true/false: an empty text literal, or a text literal that consists of the single character "0" is a logical false value\&. Anything else is a logical true value\&.
2114 .PP
2115 The result of the
2116 ~
2117 operator is a bitwise complement of its right hand side expression\&. The right hand side expression is evaluated as a 32 bit integer, and the result of this operator is a bitwise complement of the result\&.
2118 .RE
2119 .sp
2120 .it 1 an-trap
2121 .nr an-no-space-flag 1
2122 .nr an-break-flag 1
2123 .br
2124 .ps +1
2125 \fBescape(string) - escape special characters in a string.\fR
2126 .RS 4
2127 .sp
2128 .if n \{\
2129 .RS 4
2130 .\}
2131 .nf
2132 \fBescape\fR(\fIexpression\fR)
2133
2134 .fi
2135 .if n \{\
2136 .RE
2137 .\}
2138 .PP
2139 The
2140 \fBescape\fR
2141 function returns its sole argument with every occurrence of a special character prefixed by a backslash\&. A special character is any of the following characters:
2142 .sp
2143 .if n \{\
2144 .RS 4
2145 .\}
2146 .nf
2147 |!$()[]\e+*?\&.&;`\*(Aq\-~<>^{}"
2148
2149 .fi
2150 .if n \{\
2151 .RE
2152 .\}
2153 .PP
2154 This can used when
2155 \m[blue]\fBmatching pattern sections\fR\m[]\&\s-2\u[15]\d\s+2, and then taking one section and matching it again\&. For example:
2156 .sp
2157 .if n \{\
2158 .RS 4
2159 .\}
2160 .nf
2161 if ( /^From:\es*(\&.*)/ )
2162 {
2163 MATCH1=escape($MATCH1)
2164 if ( /^Subject:\&.*$MATCH1/ )
2165 {
2166 \&.\&.\&.
2167 }
2168 }
2169
2170 .fi
2171 .if n \{\
2172 .RE
2173 .\}
2174 .PP
2175 This example checks if the contents of the
2176 From:
2177 header can also be found in the
2178 Subject:
2179 header\&. If the
2180 \fBescape\fR
2181 function were not used, then any special characters in the
2182 From:
2183 header that are also used in regular expressions, such as
2184 *
2185 or
2186 +, would introduce unpredictable behavior, most likely a syntax error\&.
2187 .PP
2188 The reason why this list of special characters also includes characters not used in
2189 \fBmaildrop\fR\*(Aqs regular expressions is to allow
2190 \fBmaildrop\fR\*(Aqs variables to be used on the command line of a shell command executed by the
2191 \fBxfilter\fR
2192 command, backtick characters, or
2193 \fBto\fR
2194 or
2195 \fBcc\fR
2196 commands\&.
2197 .PP
2198 Although using data from an external data source is dangerous, and it may result in inadvertent exploits, using the escape function should hopefully result in fewer surprises\&.
2199 .RE
2200 .sp
2201 .it 1 an-trap
2202 .nr an-no-space-flag 1
2203 .nr an-break-flag 1
2204 .br
2205 .ps +1
2206 \fBgdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop\fR
2207 .RS 4
2208 .PP
2209 These functions provide support for GDBM database files\&. See
2210 \m[blue]\fB\fBmaildropgdbm\fR(5)\fR\m[]\&\s-2\u[16]\d\s+2
2211 for more information\&.
2212 .if n \{\
2213 .sp
2214 .\}
2215 .RS 4
2216 .it 1 an-trap
2217 .nr an-no-space-flag 1
2218 .nr an-break-flag 1
2219 .br
2220 .ps +1
2221 \fBNote\fR
2222 .ps -1
2223 .br
2224 .PP
2225 The system administrator can disable GDBM support in
2226 \fBmaildrop\fR, so these commands may not be available to you\&.
2227 .sp .5v
2228 .RE
2229 .RE
2230 .sp
2231 .it 1 an-trap
2232 .nr an-no-space-flag 1
2233 .nr an-break-flag 1
2234 .br
2235 .ps +1
2236 \fBgetaddr(string) - extract RFC 2822 addresses from a header.\fR
2237 .RS 4
2238 .sp
2239 .if n \{\
2240 .RS 4
2241 .\}
2242 .nf
2243 if ( /^From:\es*(\&.*)/ )
2244 {
2245 ADDR=getaddr($MATCH1)
2246 }
2247
2248 .fi
2249 .if n \{\
2250 .RE
2251 .\}
2252 .PP
2253 This function is usually applied to a header that contains
2254 \m[blue]\fBRFC 2822\fR\m[]\&\s-2\u[17]\d\s+2
2255 addresses\&. It extracts the actual addresses from the header, without any comments or extraneous punctuation\&. Each address is followed by a newline character\&. For example, if
2256 \fIstring\fR
2257 contains:
2258 .sp
2259 .if n \{\
2260 .RS 4
2261 .\}
2262 .nf
2263 joe@domain\&.com (Joe Brown), "Alex Smith" <alex@domain\&.com>, tom@domain\&.com
2264
2265 .fi
2266 .if n \{\
2267 .RE
2268 .\}
2269 .PP
2270 The result of the
2271 \fBgetaddr\fR
2272 function is the following string:
2273 .sp
2274 .if n \{\
2275 .RS 4
2276 .\}
2277 .nf
2278 joe@domain\&.com<NL>alex@domain\&.com<NL>tom@domain\&.com<NL>
2279
2280 .fi
2281 .if n \{\
2282 .RE
2283 .\}
2284 .if n \{\
2285 .sp
2286 .\}
2287 .RS 4
2288 .it 1 an-trap
2289 .nr an-no-space-flag 1
2290 .nr an-break-flag 1
2291 .br
2292 .ps +1
2293 \fBNote\fR
2294 .ps -1
2295 .br
2296 .PP
2297 Because
2298 \fBgetaddr\fR() interprets
2299 \m[blue]\fBRFC 2822\fR\m[]\&\s-2\u[18]\d\s+2
2300 loosely, it is not necessary to strip off the "To:" or the "Cc:" header from the string, before feeding it to
2301 \fBgetaddr()\fR\&. For example, the following snippet of code takes all addresses in the message, and concatenates them into a single string, separated by spaces:
2302 .sp
2303 .if n \{\
2304 .RS 4
2305 .\}
2306 .nf
2307 ADDRLIST=""
2308 foreach /^(To|Cc): \&.*/
2309 {
2310 foreach (getaddr $MATCH) =~ /\&.+/
2311 {
2312 ADDRLIST="$ADDRLIST $MATCH"
2313 }
2314 }
2315
2316 .fi
2317 .if n \{\
2318 .RE
2319 .\}
2320 .sp .5v
2321 .RE
2322 .if n \{\
2323 .sp
2324 .\}
2325 .RS 4
2326 .it 1 an-trap
2327 .nr an-no-space-flag 1
2328 .nr an-break-flag 1
2329 .br
2330 .ps +1
2331 \fBNote\fR
2332 .ps -1
2333 .br
2334 .PP
2335 In certain rare situations,
2336 \m[blue]\fBRFC 2822\fR\m[]\&\s-2\u[18]\d\s+2
2337 allows spaces to be included in E\-mail addresses, so this example is just educational\&.
2338 .sp .5v
2339 .RE
2340 .RE
2341 .sp
2342 .it 1 an-trap
2343 .nr an-no-space-flag 1
2344 .nr an-break-flag 1
2345 .br
2346 .ps +1
2347 \fBhasaddr(string) - Search for an address.\fR
2348 .RS 4
2349 .sp
2350 .if n \{\
2351 .RS 4
2352 .\}
2353 .nf
2354 if ( hasaddr(\fIstring\fR) )
2355 {
2356 \&.\&.\&.
2357 }
2358
2359 .fi
2360 .if n \{\
2361 .RE
2362 .\}
2363 .PP
2364 "\fIstring\fR" is of the form
2365 user@domain\&. The hasaddr function returns 1 if this address is included in any
2366 To:,
2367 Cc:,Resent\-To:, or
2368 Resent\-Cc:, header in the message, otherwise this function returns 0\&.
2369 .PP
2370 This is more than just a simple text search\&. Each header is parsed according to
2371 RFC822\&. Addresses found in the header are extracted, ignoring all comments and names\&. The remaining addresses are checked, and if "\fIstring\fR" is one of them,
2372 \fBhasaddr\fR
2373 returns 1, otherwise it returns 0\&.
2374 .PP
2375 The comparison is case\-insensitive\&. This actually violates
2376 RFC822
2377 (and several others) a little bit, because the user part of the address may be (but is not required to be) case sensitive\&.
2378 .RE
2379 .sp
2380 .it 1 an-trap
2381 .nr an-no-space-flag 1
2382 .nr an-break-flag 1
2383 .br
2384 .ps +1
2385 \fBlength (string) - length of a string\fR
2386 .RS 4
2387 .sp
2388 .if n \{\
2389 .RS 4
2390 .\}
2391 .nf
2392 if (length(\fIstring\fR) > 80)
2393 {
2394 \&.\&.\&.
2395 }
2396
2397 .fi
2398 .if n \{\
2399 .RE
2400 .\}
2401 .PP
2402 The
2403 \fBlength\fR
2404 function returns the number of characters in
2405 \fIstring\fR\&.
2406 .RE
2407 .sp
2408 .it 1 an-trap
2409 .nr an-no-space-flag 1
2410 .nr an-break-flag 1
2411 .br
2412 .ps +1
2413 \fBlookup (expr, 'filename', 'options') - read file for patterns\fR
2414 .RS 4
2415 .sp
2416 .if n \{\
2417 .RS 4
2418 .\}
2419 .nf
2420 if (lookup(\fIexpr\fR, file, "\fIoption\fR"))
2421 {
2422 \&.\&.\&.
2423 }
2424
2425 .fi
2426 .if n \{\
2427 .RE
2428 .\}
2429 .PP
2430 \fIexpr\fR
2431 is any expression\&.
2432 filename
2433 is a name of a file containing a list of patterns\&. Note that
2434 filename
2435 is relative to the current directory, which is the home directory of the user when
2436 \fBmaildrop\fR
2437 runs in delivery mode, or embedded mode\&.
2438 \fBmaildrop\fR
2439 then reads the file\&. Blank lines will be ignored, as well as any lines that begin with the # character (comments)\&.
2440 .PP
2441 Leading whitespace (but not trailing whitespace, take care) is removed, and the remaining contents of each line are interpreted as a pattern which is matched against
2442 \fIexpr\fR\&. As soon as the match is found,
2443 \fBlookup\fR
2444 returns "1"\&. If no match is found after reading the entire file,
2445 \fBlookup\fR
2446 returns "0"\&. For example:
2447 .sp
2448 .if n \{\
2449 .RS 4
2450 .\}
2451 .nf
2452 if ( /^To:\es*(\&.*)/ && lookup( $MATCH1, "badto\&.dat" ))
2453 {
2454 exit
2455 }
2456
2457 .fi
2458 .if n \{\
2459 .RE
2460 .\}
2461 .PP
2462 The file badto\&.dat contains the following two lines:
2463 .sp
2464 .if n \{\
2465 .RS 4
2466 .\}
2467 .nf
2468 friend@public
2469 ^[^@]*$
2470
2471 .fi
2472 .if n \{\
2473 .RE
2474 .\}
2475 .PP
2476 If a message has a
2477 To:
2478 header that contains the text "friend@public", or does not contain at least one
2479 @
2480 character, then the message will be silently dropped on the floor (
2481 \fBmaildrop\fR
2482 will terminate without delivering the message anywhere)\&.
2483 .PP
2484 \fIoptions\fR
2485 are the pattern matching options to use\&. The only supported option is "D" (the rest are meaningless, in this case)\&.
2486 .if n \{\
2487 .sp
2488 .\}
2489 .RS 4
2490 .it 1 an-trap
2491 .nr an-no-space-flag 1
2492 .nr an-break-flag 1
2493 .br
2494 .ps +1
2495 \fBNote\fR
2496 .ps -1
2497 .br
2498 .PP
2499 Be careful with discarding messages like that\&. Pattern matching can be tricky, and a slight miscalculation can cause mail to be unintentionally discarded\&. It is much desirable to first deliver message to a separate folder or mailbox, and once the filter is verified to work correctly, change it so the messages are discarded completely\&.
2500 .sp .5v
2501 .RE
2502 .RE
2503 .sp
2504 .it 1 an-trap
2505 .nr an-no-space-flag 1
2506 .nr an-break-flag 1
2507 .br
2508 .ps +1
2509 \fBsubstr(string,start [,count]) - return substring\fR
2510 .RS 4
2511 .sp
2512 .if n \{\
2513 .RS 4
2514 .\}
2515 .nf
2516 foo=substr($foo, 1, 10)
2517
2518 .fi
2519 .if n \{\
2520 .RE
2521 .\}
2522 .PP
2523 The
2524 \fBsubstr\fR
2525 function extracts characters from
2526 \fIstring\fR
2527 beginning with character #\fIstart\fR\&. If
2528 \fIcount\fR
2529 is specified, at most
2530 \fIcount\fR
2531 characters starting at position
2532 \fIstart\fR
2533 are kept, any excess is trimmed\&.
2534 .RE
2535 .sp
2536 .it 1 an-trap
2537 .nr an-no-space-flag 1
2538 .nr an-break-flag 1
2539 .br
2540 .ps +1
2541 \fBtime - return current time\fR
2542 .RS 4
2543 .sp
2544 .if n \{\
2545 .RS 4
2546 .\}
2547 .nf
2548 foo=time
2549
2550 .fi
2551 .if n \{\
2552 .RE
2553 .\}
2554 .PP
2555 The
2556 \fBtime\fR
2557 function returns the current time, in seconds, since January 1, 1970\&. This function is useful when using GDBM files\&. See
2558 \m[blue]\fB\fBmaildropex\fR(7)\fR\m[]\&\s-2\u[19]\d\s+2
2559 for an example of using the
2560 \fBtime\fR
2561 function\&.
2562 .RE
2563 .sp
2564 .it 1 an-trap
2565 .nr an-no-space-flag 1
2566 .nr an-break-flag 1
2567 .br
2568 .ps +1
2569 \fBtolower(string) - Convert string to lowercase.\fR
2570 .RS 4
2571 .sp
2572 .if n \{\
2573 .RS 4
2574 .\}
2575 .nf
2576 foo=tolower(\fIstring\fR)
2577
2578 .fi
2579 .if n \{\
2580 .RE
2581 .\}
2582 .PP
2583 This function returns the
2584 \fIstring\fR
2585 with all uppercase characters replaced by lowercase characters\&.
2586 .RE
2587 .sp
2588 .it 1 an-trap
2589 .nr an-no-space-flag 1
2590 .nr an-break-flag 1
2591 .br
2592 .ps +1
2593 \fBtoupper(string) - Convert string to uppercase.\fR
2594 .RS 4
2595 .sp
2596 .if n \{\
2597 .RS 4
2598 .\}
2599 .nf
2600 foo=toupper(\fIstring\fR)
2601
2602 .fi
2603 .if n \{\
2604 .RE
2605 .\}
2606 .PP
2607 This function returns the
2608 \fIstring\fR
2609 with all lowercase characters replaced by uppercase characters\&.
2610 .RE
2611 .SS "Statements"
2612 .PP
2613 The
2614 filter file
2615 is read by
2616 \fBmaildrop\fR
2617 ($HOME/\&.mailfilter
2618 or another file), and it contains filtering statements, one per line\&. The filtering language used by
2619 \fBmaildrop\fR
2620 has a loosely \- defined grammatical structure\&.
2621 .PP
2622 Statements are listed one per line\&. Multiple statements may be listed on the same line by separating them with semicolons\&. To continue a long statement on the next line, terminate the line with a backslash character\&.
2623 .SH "BUGS"
2624 .PP
2625 If
2626 \fBgetaddr\fR() or
2627 \fBhasaddr\fR() functions are used on broken headers, the results are unpredictable\&.
2628 .PP
2629 \fBhasaddr\fR() is completely case insensitive\&. This actually violates a few RFCs, because the userid portion of the address could be case\-sensitive, but it\*(Aqs not in too many cases, so there\&.
2630 .SH "SEE ALSO"
2631 .PP
2632 \m[blue]\fB\fBlockmail\fR(1)\fR\m[]\&\s-2\u[20]\d\s+2,
2633 \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[21]\d\s+2,
2634 \m[blue]\fB\fBmaildropgdbm\fR(5)\fR\m[]\&\s-2\u[16]\d\s+2,
2635 \m[blue]\fB\fBmaildirquota\fR(8)\fR\m[]\&\s-2\u[4]\d\s+2,
2636 \m[blue]\fB\fBreformail\fR(1)\fR\m[]\&\s-2\u[22]\d\s+2,
2637 \fBegrep\fR(1),
2638 \fBsendmail\fR(8)\&.
2639 .SH "AUTHOR"
2640 .PP
2641 \fBSam Varshavchik\fR
2642 .RS 4
2643 Author
2644 .RE
2645 .SH "NOTES"
2646 .IP " 1." 4
2647 Courier mail server
2648 .RS 4
2649 \%https://www.courier-mta.org/
2650 .RE
2651 .IP " 2." 4
2652 \fBdot-courier\fR(5)
2653 .RS 4
2654 \%http://www.courier-mta.org/maildrop/dot-courier.html
2655 .RE
2656 .IP " 3." 4
2657 value of the -M option
2658 .RS 4
2659 \%http://www.courier-mta.org/maildrop/maildrop.html#moption
2660 .RE
2661 .IP " 4." 4
2662 \fBmaildirquota\fR(8)
2663 .RS 4
2664 \%http://www.courier-mta.org/maildrop/maildirquota.html
2665 .RE
2666 .IP " 5." 4
2667 system
2668 .RS 4
2669 \%http://www.courier-mta.org/maildrop/#system
2670 .RE
2671 .IP " 6." 4
2672 xfilter
2673 .RS 4
2674 \%http://www.courier-mta.org/maildrop/#xfilter
2675 .RE
2676 .IP " 7." 4
2677 PCRE
2678 .RS 4
2679 \%http://www.pcre.org
2680 .RE
2681 .IP " 8." 4
2682 See the \fBto\fR statement
2683 .RS 4
2684 \%http://www.courier-mta.org/maildrop/#to
2685 .RE
2686 .IP " 9." 4
2687 \fBflock\fR statement
2688 .RS 4
2689 \%http://www.courier-mta.org/maildrop/#flock
2690 .RE
2691 .IP "10." 4
2692 embedded mode
2693 .RS 4
2694 \%http://www.courier-mta.org/maildrop/maildrop.html#embedded
2695 .RE
2696 .IP "11." 4
2697 \fBdotlock\fR statement
2698 .RS 4
2699 \%http://www.courier-mta.org/maildrop/#dotlock
2700 .RE
2701 .IP "12." 4
2702 \fBcc\fR
2703 .RS 4
2704 \%http://www.courier-mta.org/maildrop/#cc
2705 .RE
2706 .IP "13." 4
2707 evaluates to a logical true
2708 .RS 4
2709 \%http://www.courier-mta.org/maildrop/#if
2710 .RE
2711 .IP "14." 4
2712 Patterns
2713 .RS 4
2714 \%http://www.courier-mta.org/maildrop/#patterns
2715 .RE
2716 .IP "15." 4
2717 matching pattern sections
2718 .RS 4
2719 \%http://www.courier-mta.org/maildrop/#patmatch
2720 .RE
2721 .IP "16." 4
2722 \fBmaildropgdbm\fR(5)
2723 .RS 4
2724 \%http://www.courier-mta.org/maildrop/maildropgdbm.html
2725 .RE
2726 .IP "17." 4
2727 RFC 2822
2728 .RS 4
2729 \%http://www.rfc-editor.org/rfc/rfc2822.txt
2730 .RE
2731 .IP "18." 4
2732 RFC 2822
2733 .RS 4
2734 \%http://www.rfc-editor.org/rfc/rfc822.txt
2735 .RE
2736 .IP "19." 4
2737 \fBmaildropex\fR(7)
2738 .RS 4
2739 \%http://www.courier-mta.org/maildrop/maildropex.html
2740 .RE
2741 .IP "20." 4
2742 \fBlockmail\fR(1)
2743 .RS 4
2744 \%http://www.courier-mta.org/maildrop/lockmail.html
2745 .RE
2746 .IP "21." 4
2747 \fBmaildrop\fR(1)
2748 .RS 4
2749 \%http://www.courier-mta.org/maildrop/maildrop.html
2750 .RE
2751 .IP "22." 4
2752 \fBreformail\fR(1)
2753 .RS 4
2754 \%http://www.courier-mta.org/maildrop/reformail.html
2755 .RE