.\" DSTART
.\" 
.\"           maildrop - mail delivery agent with filtering abilities
.\"                                      
.\"  Copyright 1998, Double Precision Inc.
.\"    
.\"  This program is distributed under the terms of the GNU General Public
.\"  License. See COPYING for additional information.
.\" DEND
.TH maildropfilter 5 "August 31, 1998" "Double Precision, Inc." ""
.\" $Id: maildropfilterhead.html 1.6 1998/08/11 03:50:56 mrsam Exp $
.SH NAME
maildropfilter \- filtering language used by maildrop
.br
.br
.SH "SYNOPSIS
/etc/maildroprc, $HOME/.mailfilter, $HOME/.mailfilters/*, and friends...
.br
.br
.SH "DESCRIPTION
This manual page describes the language used by \fImaildrop\fP to filter mail
messages.
.PP
Instructions for filtering messages come from a file, using a simple
language. The language is loosely structured, it is based on pattern matching.
The language has a distinct lexical, and syntactical structure, but uses
common features found in other UNIX pseudo-languages.
.PP
If the filtering instructions do not exist, \fImaildrop\fP delivers the
message to the default mailbox, without doing any additional processing,
making it indistinguishable from the usual mail delivery agent.
.PP
It is important to note that \fImaildrop\fP reads and parses the \fIfilter
file\fP before doing anything. \fImaildrop\fP will print an error message,
and terminate with the exit code set to EX_TEMPFAIL, if the \fIfilter\fP
file has any syntax errors. 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. 
.SS "Environment
\fImaildrop\fP uses variables to access and manipulate messages. Variables
are arbitrary text manipulated by referring to the name of the variable,
such as HOME, or DEFAULT. Text is placed into a variable
by using an assignment statement, such as:
.nf

FILE="IN.junk"
.fi
.PP
This statement puts the text "IN.junk" (without the quotes) into a variable
whose name is FILE. Later, the contents of a variable are accessed by using
the $ symbol and the name for the variable. For example:
.nf

to $FILE
.fi
.PP
This will deliver the current message to the mailbox file (or a maildir
directory) named "IN.junk".
.PP
\fImaildrop\fP initially creates variables from the environment variables
of the operating system, UNLESS \fImaildrop\fP runs in delivery mode. Each
variable in the operating system environment becomes a variable in \fImaildrop\fP.
When running in delivery mode, \fImaildrop\fP does not import any environment
for security reasons. In all cases, \fImaildrop\fP resets the HOME, DEFAULT,
SHELL, PATH, LOCKEXT, LOCKREFRESH, LOCKSLEEP, LOCKTIMEOUT, SENDMAIL
and LOGNAME variables to their default values.
.PP
All environment variables become internal variables in the filtering
language. When \fImaildrop\fP runs a command, all internal variables are exported
back as environment variables. Changes to internal variables, made by the
\fIfilter file\fP, are reflected in the exported environment.
.SS "Lexical structure
Most whitespace is generally ignored. The # character introduces a comment,
which runs to the end of the line, which is also ignored. Unlike other
mail filters, \fImaildrop\fP parses the filter file before taking any action
with the message. If there are syntax errors in the file, \fImaildrop\fP displays
an error message, and returns EX_TEMPFAIL. That should cause the
mail message to remain in the queue, and, hopefully allow the problem to
be corrected, without bouncing any mail.
.PP
In \fImaildrop\fP 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.
.SS "Literal text
Literal text in the \fImaildrop\fP 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.
.PP
NOTE: 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.
.PP
Multiple text literals in a row are automatically concatenated, even
if they use different quotes. For example:
.nf

   FOOBAR="Foo"'bar'
.fi
.PP
Sets the variable FOOBAR to the text "Foobar".
.PP
.SS "Variable substitution
Variable substitution is performed on text literals that's surrounded by
double quotation marks. The "$" sign is used to insert contents of a variable
into the literal. For example:
.nf

   MAILBOX="$HOME/Mailbox"
.fi
.PP
Sets the variable MAILBOX to the contents of the variable HOME
followed by "/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 $ sign, and the variable name. It is possible to access variables whose
name includes other characters, by using braces as follows:
.nf

   MAILBOX="${HOME-WORD}/Mailbox"
.fi
.PP
Inserts the contents of the HOME-WORD 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 }
character.
.PP
If the $ character is not followed by a left brace, letter, or an underscore,
the $ character remains unmolested in the text literal. A backslash followed
by the $ character results in a $ character in the text literal, without
doing any variable substitution.
.PP
Variable substitution is not done in text literals which are surrounded
by single quotes.
.SS "Command line arguments
\fImaildrop\fP initializes special variables: $1, $2, and so on, with additional
parameters specified on the \fImaildrop\fP command line. A filter file may
use those variables just like any other variables.
.SS "Predefined variables
The following variables are automatically defined by \fImaildrop\fP. 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:
.TP 14
.B "DEFAULT
the default mailbox to deliver the message to. If the
filter file does not specify a mailbox to deliver this message to, the
message is delivered to this mailbox. The default mailbox is defined by
the system administrator.
.br 
.TP 14
.B "HOME
home directory of the user running \fImaildrop\fP.
.br 
.TP 14
.B "LOCKEXT
extension for dot-lock files (default: .lock).
.br 
.TP 14
.B "LOCKREFRESH
refresh interval, in seconds, for dot-locks (default:
15). When \fImaildrop\fP dot-locks a mailbox, \fImaildrop\fP 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.
.br 
.TP 14
.B "LOCKSLEEP
number of seconds to wait to try again to create a
dot-lock file, if one already exists (default: 5).
.br 
.TP 14
.B "LOCKTIMEOUT
number of seconds to wait before removing a stale
dot-lock file (default: 60). If a dot-lock file still exists after LOCKTIMEOUT
seconds, \fImaildrop\fP 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, \fImaildrop\fP waits LOCKSLEEP 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.
.br 
.TP 14
.B "LOGNAME
name of the user to who the message is being delivered.
.br 
.TP 14
.B "MAILFILTER
this is the name of the original filter file that
was given to \fImaildrop\fP on the command line. This is mostly usefull to
-default filter files, it allows them to obtain the value
of the -M option specified on the command line.
.br 
.TP 14
.B "PATH
command execution path. \fImaildrop\fP resets PATH to the system
default (usually /bin:/usr/bin:/usr/local/bin).
.br 
.TP 14
.B "SENDMAIL
mail delivery agent. When \fImaildrop\fP 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 SENDMAIL
command is executed to forward the message.
.br 
.TP 14
.B "SHELL
login shell. The shell is used to execute all commands
invoked by \fImaildrop\fP.
.br 
.TP 14
.B "VERBOSE
debug level (default: 0). Setting VERBOSE to progressive
higher values, between 1 and 9, produces debugging output on standard error.
\fImaildrop\fP ignores the VERBOSE variable in delivery mode (in order not
to confuse the mail transport agent).
.SS "Other special variables
The following variables are automatically used by \fImaildrop\fP when the \fIfilter
file\fP is being processed:
.TP 14
.B "EXITCODE
return code for \fImaildrop\fP. When \fImaildrop\fP successfully
delivers a message, it terminates with this exit code, which defaults to
0. NOTE - this environment variable must be set BEFORE \fImaildrop\fP is to
deliver a message into a mailbox, since \fImaildrop\fP terminates immediately
after a successful delivery (except in case of carbon-copy deliveries,
see "Statements" below).
.br 
.TP 14
.B "LINES
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,
or any mbox "From " lines. Use this as criteria for filtering, nothing
more.
.br 
.TP 14
.B "RETURNCODE
This variable is set when \fImaildrop\fP runs the xfilter
command, or a command that's specified within a pair of backtick characters
( command substitution ). The RETURNCODE variable will be set
to the exit code of the command, after it completes.
.br 
.TP 14
.B "SIZE
number of bytes in the message. This may or may not include
the -A option, and the mbox 'From ' line. Use this as a criteria for filtering,
nothing more.
.SS "Unquoted text
All text strings in filter files should be in single, or double quotes.
However, for convenience sake, quotes can be omitted under certain circumstances.
.PP
Text that includes ONLY letters, digits, and the following characters:
_-.:/${}@ 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.
.PP
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 "VARIABLE=" is interpreted as
a string even if it begins with a slash. This is why something like
.nf

      MAILDIR=/var/spool/mail
.fi
.PP
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.
.SS "Command substitution
Text enclosed in back-tick characters is interpreted as a shell command.
The shell command is executed as a child process, by \fImaildrop\fP, and its
output is used in place of the command. For example:
.nf

      DIR=`ls`
.fi
.PP
Loads the names of the files in the current directory into the DIR variable.
.PP
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. 
.SS "Patterns
The pattern syntax in \fImaildrop\fP is generally the same syntax as what's
used by \fIgrep\fP, with minor differences. A pattern takes the following
form in the filter file:
.nf

   /pattern/\fI:options\fP
.fi
.PP
"pattern" specifies the text to look for in the message.
.PP
"pattern" may not start with a space, because the leading slash will
be interpreted as a division sign. If you must search for something that
starts with a space, use something like "/[ ] ... /".
.PP
With the exception of the following characters, an exact match is looked
for. The following special characters are used to specify complex patterns.
If it is necessary to look for one of the following characters, verbatim,
in the message, put a backslash in front of it. "x" and "abc" designates
an arbitrary character, or a pattern, which may include other special characters
as well.
.TP 14
.B "x*
look for zero, or more, occurrences of one character x.
.br 
.TP 14
.B "(abc)*
look for zero or more occurrences of "abc".
.br 
.TP 14
.B "x+
look for at least one, may be more, occurrences of one character
x.
.br 
.TP 14
.B "(abc)+
look for at least one, may be more, occurrences of "abc".
.br 
.TP 14
.B "x?
look for zero, or one occurrence of one character x.
.br 
.TP 14
.B ".
the period matches any character except the newline character.
(This is also applicable within sets - see below).
.br 
.TP 14
.B "(abc)?
look for zero, or one occurrence, of "abc".
.br 
.TP 14
.B "abc!def
The exclamation mark is used to separate sections of matched
pattern. See "Pattern Match Results" below.
.br 
.TP 14
.B "[abc]
specifies a set of characters - this matches one character.
either a, b, or c. Between the brackets, list all characters that can be
matched at this point in the pattern. One or more characters can be listed.
For example, [~=+] matches either a tilde, an equals sign, or a +. It is
EXACTLY equivalent to (~|=|+), however, with large list of characters,
this notation is shorter. In addition, [a-b] matches any character between
"a" and "b", inclusive. For example [0-9] matches any character between
zero and nine, [0-9A-Za-z_] matches either a digit, a letter, or an underscore.
.PP
To include the dash, or the left or the right bracket characters in
the set itself, prefix them with a backslash. Use two backslashes to include
the backslash character itself. (Other, historical ways of including these
special characters are permitted, but discouraged).
.br 
.TP 14
.B "[^abc]
specifies a set of characters that is NOT the given characters
indicated. If the set begins with the ^ symbol, it matches a single character
that is NOT any of the characters listed.
.br 
.TP 14
.B "\\\\x
where "x" is a character. Specifies that the given character
must be matched exactly. In order to match any special character verbatim
(suppose you want to match the asterisk, *) you must prefix it with a backslash
character. Use two backslashes in order to match a backslash character
verbatim. Also, there are several characters reserved for matching control
characters, without having to enter them verbatim into the pattern. See
below for more information.
In addition, the following shorthand notation can be used to specify some
common sets:
.TP 14
.B "[:alnum:]
alphanumeric character, same as [0-9A-Za-z].
.br 
.TP 14
.B "[:alpha:]
an uppercase or a lowercase letter, same as [A-Za-z].
.br 
.TP 14
.B "[:cntrl:]
a control character.
.br 
.TP 14
.B "[:digit:]
a digit, same as [0-9].
.br 
.TP 14
.B "[:graph:]
a "graphable" character (a non-control character that's
not a space).
.br 
.TP 14
.B "[:lower:]
a lowercase letter, same as [a-z].
.br 
.TP 14
.B "[:print:]
a printable character (not a control character).
.br 
.TP 14
.B "[:punct:]
a punctuation character.
.br 
.TP 14
.B "[:space:]
any whitespace character.
.br 
.TP 14
.B "[:upper:]
uppercase letter, same as [A-Z].
.br 
.TP 14
.B "[:wbreak:]
any character other than a letter, digit, or an underscore,
same as [^a-zA-Z0-9_].
.br 
.TP 14
.B "[:xdigit:]
a hexadecimal digit, same as [0-9A-Fa-f].
To match any special character, put a backslash in front of it. For example,
\\? matches the question mark. To match a backslash, use \\\\.
.PP
Normally, the pattern can be found anywhere within the message header
or body (see below). However, putting the character ^ at the beginning
of the pattern forces the pattern to be matched against the beginning of
the line only. Putting the character $ at the end of the pattern forces
the pattern to be matched against the end of the line only.
.PP
Elsewhere in the pattern, the $ sign is used for variable substitution
(see above). To include the $ character in the pattern, prefix it with
a backslash. 
.SS "Other backslash substitutions
The following backslashed characters are interpreted as follows, when used
in a pattern specification:
.TP 14
.B "\\\\n
matches a newline character. Note - this is only effective
if the w option is specified, because without this
option \fImaildrop\fP does not recognize multi-line patterns.
.br 
.TP 14
.B "\\\\r
matches a carriage return. Note - \fImaildrop\fP automatically
ignores carriage returns at the end of each line. I don't know why you'd
want to use \\r, but it's there if you need it.
.br 
.TP 14
.B "\\\\t
matches a tab.
.br 
.TP 14
.B "\\\\f
matches a form feed.
.br 
.TP 14
.B "\\\\v
matches a vertical tab.
Long double or singly-quoted text can be broken across multiple lines by
ending the line with a lone backslash character, like this:
.nf

      TEXT="This is a long \\
         text string"
.fi
.PP
The backslash, the newline, and all leading whitespace on the next line
is removed, resulting in "This is a long text string". 
.SS "Pattern options
After /pattern/, there is an optional colon, followed by one-letter options.
The following options may be specified in any order:
.TP 14
.B "h
match pattern against the message header.
.br 
.TP 14
.B "b
match pattern against the message body.
.br 
.TP 14
.B "w
match pattern against the entire message and/or body.
.br 
.TP 14
.B "D
case sensitive search. Normally patterns are matched without distinguishing
between uppercase, and lowercase. Specifying the D option results in a
case-sensitive search: lowercase letters in the pattern must match lowercase
letters in the message, ditto for uppercase.
Please note that the 'b' and the 'w' options consume an excessive amount
of CPU time, and should be avoided, if possible.  HINT: If possible,
use the SIZE environment variable to avoid using patterns with
these flags.
.PP
If neither 'h' or 'b' is specified, the pattern is matched against the
header only. Specifying the 'b' option causes the pattern to be matched
against the message body. Specifying both causes the pattern to be matched
against the entire message.
.PP
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.
Specifying the 'w' flag causes the pattern to be applied to the whole part
of the message that's being searched (which is specified via the presence,
or the absence, of the h and b flags). Also, if the 'w' flag is used, but
neither 'h' nor 'b' flags are used, the 'b' flag is the default, instead
of the 'h' flag.
.PP
This flag also changes the way that ^ and $ is interpreted in patterns.
Normally, those characters anchor the pattern at the beginning, or the
end, of each line. When the 'w' flag is specified, ^ and $ anchors the
pattern against the beginning, or the end, of either the header, body,
or both.
.SS "Weighted scoring
Patterns are evaluated by \fImaildrop\fP as any other numerical expression.
If a pattern is found, \fImaildrop\fP's 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.
.PP
\fImaildrop\fP can also do weighted scoring. In weighted scoring, multiple
occurrences of the same pattern are used to calculate a numerical value.
.PP
To use a weighted search, specify the pattern as follows:
.nf

   /pattern/:options,xxx,yyy
.fi
.PP
where xxx and yyy are two numbers. yyy is optional, if missing, it defaults
to 1.
.PP
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.
.PP
IMPORTANT: when the w option is not specified, \fImaildrop\fP does not recognize
multiple occurrences of the same pattern in the same line. This is required
in order to have the ^ and $ operators working correctly. For example:
.nf

    /^Received:/:1
.fi
.PP
This pattern counts how many Received: headers the message has, and does
not recognize any occurrences of the text "Received:" anywhere else in
the headers.
.PP
You must specify the 'w' option in order to take into account multiple
occurrences of the same pattern in the message. This also activates all
the usual semantics of the 'w' option. For example:
.nf

    /[:upper:]/:wbD,1
.fi
.PP
Counts the number of uppercase letters in the body of the message.
.PP
 
.SS "Pattern Match Results
After a pattern is successfully matched, the actual text that is matched
is placed in the MATCH variable. For example:
.nf

    /^From:.*/
.fi
.PP
matches a line of the form:
.nf

    From: postmaster@localhost
.fi
.PP
In this case, the variable MATCH will be set to "From: postmaster@localhost",
which can be used in subsequent statements. It is possible to use selective
parts of the matched string by using the ! character in patterns. For example:
.nf

    /^From: *!.*/
.fi
.PP
matched against the same line will set MATCH to "From: " and MATCH2
to "postmaster@localhost". More than one ! character may be used. Subsequent
matched text will be assigned to MATCH3, MATCH4, and
so on.
.PP
When there is more than one way to match a string, \fImaildrop\fP favors
matching as much as possible initially. For example:
.nf

    /^To:.*,!.*/
.fi
.PP
when matched against
.nf

    To: joe@somewhere,bob@somewhere.else,gary@whoknowswhere
.fi
.PP
will set MATCH to "To: joe@somewhere,bob@somewhere.else," and
MATCH2 to "gary@whoknowswhere".
.PP
The MATCH variables are NOT set when weighted scoring is used,
since the same pattern is matched multiple times.
.br
.br
.SH "EXPRESSIONS
Although \fImaildrop\fP 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.
.SS "Operators
The following operators carry their usual meaning, and are listed in order
from lowest precedence, to the highest:
.nf

   ||
   &&
   <  <=  >  >=  ==  !=  lt  le  gt  ge  eq  ne
   |
   &
   +  -
   *  /
   =~ /\fIpattern\fP/
   /\fIpattern\fP/  !  ~  \fIfunction()\fP
.fi
.PP
 
.\" $Id: 0010lor.html 1.1 1998/04/24 01:02:01 mrsam Exp $
.SS "|| - logical or
If the left-hand side of the || operator evaluates as true, the result
of the || operator is the result of the left-hand side operator. Otherwise,
the result of the || operator is the result of the right-hand side operator.
.PP
\fImaildrop\fP 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.
.\" $Id: 0020land.html 1.1 1998/04/24 01:02:02 mrsam Exp $
.SS "&& - logical and
If the left-hand side of the && operator evaluates as false, the
result of the || operator is the result of the left-hand side operator.
Otherwise, the result of the && operator is the result of the right-hand
side operator.
.PP
\fImaildrop\fP 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.
.\" $Id: 0030numcompare.html 1.1 1998/04/24 01:02:02 mrsam Exp $
.SS "<, <=, >, >=, ==, !=   - numerical comparison
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.
.PP
NOTE - comparisons are not associative: a < b < c is an error.
If it is absolutely necessary, use (a < b) < c.
.\" $Id: 0040textcompare.html 1.1 1998/04/24 01:02:02 mrsam Exp $
.SS "lt, le, gt, ge, eq, ne - text comparison
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.
.PP
NOTE - 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?).
.\" $Id: 0050bitwiseor.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "| - bitwise or
This is the bitwise or operator. The result of the operator is a 32 bit
integer, which is a bitwise-or combination of the left hand size and the
right hand side.
.\" $Id: 0060bitwiseand.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "& - bitwise and
This is the bitwise and operator. The result of the operator is a 32 bit
integer, which is a bitwise-or combination of the left hand size and the
right hand side.
.\" $Id: 0070numerical.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "+, -, *, / - numerical operations
These are floating point operators.
.\" $Id: 0080patmatchstr.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "=~ /pattern/:options - pattern match against string
The left hand side of the =~ 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 the given string (if the options
do not specify a weighted scoring, the result is simply 1 if the pattern
was found, 0 if not).
.PP
See "Patterns" for more information.
.\" $Id: 0090patmatch.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "/pattern/:options - pattern match against message
The result of this operator is the weighted match of the pattern against
the current message (if the options do not specify a weighted scoring,
the result is simply 1 if the pattern was found, 0 if not).
.PP
See "Patterns" for more information.
.\" $Id: 0100not.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "!, ~ - logical/bitwise not operator.
The result of the ! 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.
.PP
\fImaildrop\fP 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.
.PP
The result of the ~ 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.
.\" $Id: escape.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "escape(string) - escape special characters in a string.
The escape function returns its sole argument with every occurence of a
special character prefixed by a backslash. A special character is any of
the following characters: "|!$()[]\\+*?." (quotes not included).
This is often used when matching pattern sections,
and then taking one section and matching it again. For example:
.nf

   if ( /^From: *!.*/ )
   {
        MATCH2=escape($MATCH2)
        if ( /^Subject:.*$MATCH2/ )
        {
                .
                .
                .
        }
   }
.fi
.PP
Performs the indicated activity if the contents of the From: header can
also be found in the Subject: header. If the escape function is not used,
then any special characters in the From: header would introduce unpredictable
behavior, most likely a syntax error.
.\" $Id: getaddr.html 1.2 1998/04/28 00:50:11 mrsam Exp $
.SS "getaddr(string) - extract RFC822 addresses from a header.
This function is usually applied to a header that contains RFC822
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 \fIstring\fP contains:
.nf

   joe@domain.com (Joe Brown), "Alex Smith" <alex@domain.com>, tom@domain.com
.fi
.PP
The result of the \fIgetaddr\fP function is the following string:
.nf

   joe@domain.com\fI<NL>\fPalex@domain.com\fI<NL>\fPtom@domain.com\fI<NL>\fP
.fi
.PP
Where \fI<NL>\fP is the newline character.
.PP
Note - because getaddr() interprets RFC822 loosely, it is not necessary
to strip off the "To:" or the "Cc:" header from the string, before feeding
it to getaddr(). For example, the following snippet of code takes
all addresses in the message, and concatenates them into a single string,
separated by spaces:
.nf

   ADDRLIST=""
   foreach /^(To|Cc): .*/
   {
       foreach (getaddr $MATCH) =~ /.+/
       {
          ADDRLIST="$ADDRLIST $MATCH"
       }
   }
.fi
.PP
Please note that in certain rare situations, RFC822 permits spaces
to be included in E-mail addresses, so this example is just educational.
.br 
.\" $Id: hasaddr.html 1.3 1998/08/31 22:35:13 mrsam Exp $
.SS "hasaddr(string) - Search for an address.
"string" is of the form user@domain. The hasaddr function
returns 1 if this address is included in any To:, Cc:,
Resent-To:, or Resent-Cc:, header in the message, otherwise
this function returns 0.
.PP
This is more than just a simple text search. Each header is parsed according
to RFC822. Addresses found in the header are extracted, ignoring
all comments and names. The remaining addresses are checked, and if "string"
is one of them, hasaddr returns 1, otherwise it returns 0.
.PP
The comparison is case-insensitive. This actually violates RFC822
(and several others) a little bit, because the user part of the address
may be (but is not required to be) case sensitive.
.\" $Id: length.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "length (string) - length of a string
The \fIlength\fP operator returns the number of characters in \fIstring\fP.
.\" $Id: lookup.html 1.1 1998/04/24 01:02:03 mrsam Exp $
.SS "lookup (expr, 'filename', 'options') - read file for patterns
\fIexpr\fP is any expression. \fIfilename\fP is a name of a file containing
a list of patterns. Please note that \fIfilename\fP is relative to the
current directory, which is the home directory of the user when \fImaildrop\fP
runs in delivery mode, or embedded mode. \fImaildrop\fP will read the file.
Blank lines will be ignored, as well as any lines that begin with the #
character (comments).
.PP
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 \fIexpr\fP. As soon as the match is found, \fIlookup\fP
returns "1". If no match is found after reading the entire file, \fIlookup\fP
returns "0". For example:
.nf

if ( /^To: *!.*/ && lookup( $MATCH2, "badto.dat" )
{
   exit
}
.fi
.PP
And the file badto.dat contains the following two lines:
.nf

friend@public
^[^@]*$
.fi
.PP
If a message has a To: header that contains the text "friend@public", or
does not contain at least one @ character, then the message will be silently
dropped on the floor ( \fImaildrop\fP will terminate without delivering the
message anywhere).
.PP
\fIoptions\fP are the pattern matching options to use. The only supported
option is "D" (the rest are meaningless, in this case).
.PP
NOTE: 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.
.PP
In embedded mode, the lookup() function is restricted as follows. The
name of the file may not begin with a slash, or contain periods. Furthermore,
".mailfilters/.lists/" is automatically prepended to the filename. When
writing filtering recipes that go into $HOME/.mailfilters, please keep
in mind that any files loaded by the lookup() function must be placed in
$HOME/.mailfilters/.lists.
.\" $Id: substr.html 1.1 1998/04/24 01:02:04 mrsam Exp $
.SS "substr(string,start [,count]) - return substring
The \fIsubstr\fP operator removes \fIstart\fP number of characters from
\fIstring\fP. If \fIcount\fP is specified, at most \fIcount\fP characters
starting at position \fIstart\fP are kept, any excess is trimmed.
.\" $Id: tolower.html 1.1 1998/04/24 01:02:04 mrsam Exp $
.SS "tolower(string) - Convert string to lowercase.
This function returns the indicated string with all uppercase characters
replaced by lowercase characters.
.\" $Id: toupper.html 1.1 1998/04/24 01:02:04 mrsam Exp $
.SS "toupper(string) - Convert string to uppercase.
This function returns the indicated string with all lowercase characters
replaced by uppercase characters.
.\" $Id: maildropfiltermid.html 1.2 1998/08/11 01:36:28 mrsam Exp $
.br
.br
.SH "STATEMENTS
The \fIfilter file\fP read by \fImaildrop\fP ($HOME/.mailfilter or
another file) contains filtering statements, one per line. The filtering
language used by \fImaildrop\fP has a loosely - defined grammatical structure.
.PP
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.
.\" $Id: assignment.html 1.1 1998/04/23 00:24:34 mrsam Exp $
.SS "Variable assignment
.nf

   VARIABLE=\fIexpression\fP
.fi
.PP
Assigns the result of the expression to VARIABLE (note no leading $ in
front of variable).
.PP
Please note that if \fIVARIABLE\fP is NOT surrounded by quotes that
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.
.\" $Id: cc.html 1.1 1998/04/23 00:24:39 mrsam Exp $
.SS "cc - deliver a copy of the message
.nf

   cc \fIexpression\fP
.fi
.PP
The \fIcc\fP statement is very similar to the \fIto\fP statement, except
that after delivering the message \fImaildrop\fP continues to process the \fIfilter
file\fP, unlike the \fIto\fP statement which immediately terminates \fImaildrop\fP
after the delivery is complete. Essentially, the message is carbon copied
to the given mailbox, and may be delivered again to another mailbox by
other \fIcc\fP or \fIto\fP statement.
.PP
See the \fIto\fP statement for more details.
.\" $Id: dotlock.html 1.2 1998/04/28 00:50:02 mrsam Exp $
.SS "dotlock - create a manual dot-lock
.nf

   dotlock \fIexpression\fP {

         ...

   }
.fi
.PP
\fImaildrop\fP automatically creates a lock when a message is delivered to
a mailbox. Depending upon your system configuration, \fImaildrop\fP will use
either dot-locks, or the flock() system call.
.PP
The dotlock statement creates an explicit dot-lock file. Use
the flock statement to create an explicit flock()
lock.
.PP
The \fIexpression\fP is a filename that should be used as a lock file.
\fImaildrop\fP creates the indicated dot-lock, executes the filtering instructions
contained within the { ... } block, and removes the lock. The expression
must be the name of the dot-lock file itself, NOT the name
of the mailbox file you want to lock.
.PP
\fIWARNING:\fP with manual locking, it is possible to deadlock multiple
\fImaildrop\fP processes (or any other processes that try to claim the same
locks).
.PP
No deadlock detection is possible with dot-locks, and since \fImaildrop\fP
automatically refreshes all of its dot-locks regularly, they will never
go stale. You'll have \fImaildrop\fP processes hanging in limbo, until their
watchdog timers go off, aborting the mail delivery.
.\" $Id: echo.html 1.1 1998/04/23 00:24:40 mrsam Exp $
.SS "echo - output diagnostic information
.nf

   echo \fIexpression\fP
.fi
.PP
\fImaildrop\fP will print the given text. This is usually used when \fImaildrop\fP
is used in embedded mode, but can be used for debugging purposes. Normally,
a newline is printed after the text. If text is terminated with a \\c, no
newline will be printed.
.\" $Id: exception.html 1.1 1998/04/23 00:24:41 mrsam Exp $
.SS "exception - trap fatal errors
.nf

   exception {
   .
   .
   .
   }
.fi
.PP
The \fIexception\fP statement traps errors that would normally cause maildrop
to terminate. If a fatal error is encountered anywhere within the block
of statements enclosed by the \fIexception\fP clause, execution will resume
immediately following the \fIexception\fP clause.
.\" $Id: exit.html 1.2 1998/04/28 00:50:02 mrsam Exp $
.SS "exit - terminate filtering unconditionally
.nf

   exit
.fi
.PP
The \fIexit\fP statement immediately terminates filtering. \fImaildrop\fP's
return code is set to the value of the EXITCODE variable. Normally,
\fImaildrop\fP terminates immediately after successfully delivering
the message to a mailbox. The \fIexit\fP statement causes \fImaildrop\fP
to terminate without delivering the message anywhere.
.PP
The \fIexit\fP statement is usually used when \fImaildrop\fP is invoked
in embedded mode, when message delivery instructions are not allowed.
.\" $Id: flock.html 1.1 1998/04/23 00:24:41 mrsam Exp $
.SS "flock - create an manual flock() lock
.nf

   flock \fIexpression\fP {

         ...

   }
.fi
.PP
\fImaildrop\fP automatically creates a lock when a message is delivered to
a mailbox. Depending upon your system configuration, \fImaildrop\fP will use
either dot-locks, or the flock() system call.
.PP
The flock statement creates a manual flock() lock. Use the dotlock
statement to create a manual dot-lock file.
.PP
The \fIexpression\fP is the name of the file that should be locked.
\fImaildrop\fP creates the lock on the indicated file, executes the filtering
instructions contained within the { ... } block, and removes the lock.
.PP
\fIWARNING:\fP with manual locking, it is possible to deadlock multiple
\fImaildrop\fP 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 \fImaildrop\fP processes will terminate immediately.
Use the \fIexception\fP statement in order to trap this exception condition,
and execute an alternative set of filtering instructions.
.\" $Id: foreach.html 1.2 1998/04/28 00:50:02 mrsam Exp $
.SS "foreach - iterate over text sections matched by a pattern
.nf

   foreach /pattern/:options
   {
       ...
   }

   foreach (expression) =~ /pattern/:options
   {
       ...
   }
.fi
.PP
The \fIforeach\fP statement executes a block of statements for each occurrence
of the given pattern in the given message, or expression. On every iteration
MATCH variable will be set to the matched string. All the usual
options may be applied to the pattern match, EXCEPT the following:
.TP 14
.B ",xxx,yyy
weighted scoring is meaningless, in this context.
.TP 14
.B "!
the ! operator in the pattern does not work as expected. For each iteration,
only the MATCH variable will be set. If the pattern includes the
! operator, the statements will be executed once for each section in the
matched string, with the MATCH variable set to the contents of
each section.
.\" $Id: if.html 1.1 1998/04/23 00:24:41 mrsam Exp $
.SS "if - conditional execution
.nf

   if (\fIexpression\fP)
   {
       ...
   }
   else
   {
       ...
   }
.fi
.PP
Conditional execution. If the expression evaluates to a logical true (note
- parenthesis are required) then the first set of statements is executed.
The \fIelse\fP keyword, and the subsequent statements, are optional. If
present, and the expression evaluates to a logical false, the else part
is executed.
.PP
\fImaildrop\fP 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.
.PP
If the \fIif\fP part, or the \fIelse\fP part consists of only one
statement, the braces may be omitted.
.PP
NOTE: some grammatical contraptions here that may not be very obvious.
If you get baffling syntax errors from \fImaildrop\fP, 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).
.\" $Id: include.html 1.2 1998/04/28 00:50:02 mrsam Exp $
.SS "include - execute filtering instructions from another file
.nf

   include \fIexpression\fP
.fi
.PP
The include statement reads a file, and executes filtering instructions
contained in that file. Note that the include statement is processed when
the current filter file is being executed. When \fImaildrop\fP reads the initial
filter file, any syntax errors in the filtering instructions are immediately
reported, and \fImaildrop\fP will terminate with a return code of EX_TEMPFAIL.
Any errors in files specified by \fIinclude\fP statements are NOT reported,
because those files will not be read until the \fIinclude\fP statement
is itself executed.
.PP
If the specified file does not exist, or if there are any syntax errors
in the file, \fImaildrop\fP reports the error, and terminates with a return
code of EX_TEMPFAIL.
.\" $Id: log.html 1.1 1998/04/23 00:24:42 mrsam Exp $
.SS "log, logfile - log message deliveries
.nf

   logfile \fIexpression

\fP   log \fIexpression\fP
.fi
.PP
Logging in \fImaildrop\fP is normally turned off. The \fIlogfile\fP statement
will instruct \fImaildrop\fP to log how the message has been disposed to the
given file. The parameter is then name of the file. If the file exists
\fImaildrop\fP will append to the file.
.PP
For each delivery (which means the \fIto\fP and \fIcc\fP
statements, including delivery by default) \fImaildrop\fP will record the From:
and the Subject: fields, together with the current time, in the log file.
.PP
The \fIlog\fP statement may be used to add additional logging text
to the log file. The \fIlog\fP statement works exactly like the \fIecho\fP
statement, except that the text is written to the logfile, instead of standard
output.
.\" $Id: to.html 1.2 1998/04/28 00:50:02 mrsam Exp $
.SS "to - deliver message to a mailbox
.nf

   to \fIexpression\fP
.fi
.PP
The \fIto\fP statement delivers the message to a mailbox. \fIexpression\fP
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).
.PP
The \fIto\fP statement is the final delivery statement. \fImaildrop\fP
delivers message, then immediately terminates, with the return code set
to the EXITCODE environment variable. If there was an error while
delivering the message, \fImaildrop\fP terminates with the EX_TEMPFAIL
exit code. A properly-written mail transport agent should re-queue the
message, and re-attempt delivery at some later time.
.PP
If \fIexpression\fP begins with the | symbol, the remainder of the
expression specifies an external program to run to handle the actual delivery.
The SHELL variable specifies the shell to execute the given command.
The message is provided to the command on standard input.
.PP
If \fIexpression\fP begins with an exclamation mark - "!" - the remainder
of the expression specifies a list of E-mail addresses to forward the message
to. The list of E-mail addresses must be separated by spaces. The mail
delivery agent specified by the SENDMAIL variable is run as an
external program, with the list of E-mail addresses provided as parameters
to the program.
.PP
Otherwise, \fImaildrop\fP delivers the message to the actual mailbox indicated.
If \fIexpression\fP is a directory, \fImaildrop\fP will assume that the directory
is a \fImaildir\fP directory. \fImaildir\fP is a directory-based format
used by Qmail. Otherwise, \fImaildrop\fP will deliver the message to a file,
formatted in traditional mailbox format. \fImaildrop\fP will use either dot-locking,
or flock()-locking when delivering the message to the file.
.\" $Id: while.html 1.1 1998/04/23 00:24:42 mrsam Exp $
.SS "while - repeatedly execute a block of statements
.nf

   while (\fIexpression\fP)
   {
       ...
   }
.fi
.PP
The \fIexpression\fP is repeatedly evaluated. Each time it evaluates
to a logical true, the statements inside the braces are executed. When
\fIexpression\fP evaluates to a logical false, the while loop is over.
Take care to avoid infinite loops.
.\" $Id: xfilter.html 1.2 1998/04/28 00:50:02 mrsam Exp $
.SS "xfilter - filter message through another program
.nf

   xfilter \fIexpression\fP
.fi
.PP
\fImaildrop\fP will run the given program as a mail filter. 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, \fImaildrop\fP will terminate with an exit code of
EX_TEMPFAIL.
.\" $Id: maildropfiltertail.html 1.1 1998/04/23 00:25:24 mrsam Exp $
.br
.br
.SH "BUGS
If getaddr() or hasaddr() functions are used on broken headers, the results
are unpredictable.
.PP
hasaddr() is completely case insensitive. This actually violates a few
RFCs, because the userid portion of the address could be case-sensitive,
but it's not in too many cases, so there.
.br
.br
.SH "SEE ALSO
dotlock(1), maildrop(1),
reformail(1), egrep(1), sendmail(8)