Debian Codegraph @

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