4.12 Variables

Variables represent regions of memory used to hold variable data. These memory regions are identified by variable names. A variable name must begin with a letter or underscore and must consist of letters, digits and underscores.

Each variable is associated with its scope of visibility, which defines the part of source code where it can be used (see scope of visibility). Depending on the scope, we discern three main classes of variables: public, static and automatic (or local).

Public variables have indefinite lexical scope, so they may be referred to anywhere in the program. Static are variables visible only within their module (see Modules). Automatic or local variables are visible only within the given function or handler.

Public and static variables are sometimes collectively called global.

These variable classes occupy separate namespaces, so that an automatic variable can have the same name as an existing public or static one. In this case this variable is said to shadow its global counterpart. All references to such a name will refer to the automatic variable until the end of its scope is reached, where the global one becomes visible again.

Likewise, a static variable may have the same name as a static variable defined in another module. However, it may not have the same name as a public variable.

A variable is declared using the following syntax:

[qualifiers] type name

where name is the variable name, type is the type of the data it is supposed to hold. It is ‘string’ for string variables and ‘number’ for numeric ones.

For example, this is a declaration of a string variable ‘var’:

string var

If a variable declaration occurs within a function (see User-defined) or handler (see Handlers), it declares an automatic variable, local to this function or handler. Otherwise, it declares a global variable.

Optional qualifiers are allowed only in global declarations, i.e. in the variable declarations that appear outside of functions. They specify the scope of the variable. The public qualifier declares the variable as public and the static qualifier declares it as static. The default scope is ‘public’, unless specified otherwise in the module declaration (see module structure).

Additionally, qualifiers may contain the word precious, which instructs the compiler to mark this variable as precious. (see precious variables). The value of the precious variable is not affected by the SMTP ‘RSET’ command. If both scope qualifier and precious are used, they may appear in any order, e.g.:

static precious string rcpt_list

or

precious static string rcpt_list

Declaration can be followed by any valid MFL expression, which supplies the initial value or initializer for the variable, for example:

string var "test"

A variable declared without initializer is implicitly initialized to a null value, no matter what its scope: a numeric variable assumes initial value 0, a string variables is initialized to an empty string.

A variable is assigned a value using the set statement:

set name expr

where name is the variable name and expr is a mailfromd expression (see Expressions). The effect of this statement is that the expr is evaluated and the value it yields is assigned to the variable name.

If the set statement is located outside a function or handler definition, the expr must be a constant expression, i.e. the compiler should be able to evaluate it immediately. See optimizer.

It is not an error to assign a value to a variable that is not declared. In this case the assignment first declares a global or automatic variable having the type of expr and then assigns a value to it. Automatic variable is created if the assignment occurs within a function or handler, global variable is declared if it occurs at topmost lexical level. This is called implicit variable declaration.

In the MFL program, variables are referenced by their name. When appearing inside a double-quoted string, variables are referenced using the notation ‘%name’. Any variable being referenced must have been declared earlier (either explicitly or implicitly).

4.12.1 Predefined Variables

Several variables are predefined. In mailfromd version 9.0 these are:

Predefined Variable: number milter_state

Identifies the current milter state (see milter state). The module milter.mfl defines the following symbolic names:

milter_state_none

milter_state_startup

milter_state_shutdown

milter_state_begin

milter_state_end

milter_state_connect

milter_state_helo

milter_state_envfrom

milter_state_envrcpt

milter_state_data

milter_state_header

milter_state_eoh

milter_state_body

milter_state_eom

milter_action

Use the milter_state_name function to obtain the corresponding textual string (see milter_state_name).

Predefined Variable: string milter_server_id

Identifier of the milter server which executes the code. This is the string passed to the id statement in the server section of the configuration file (see conf-server),

Predefined Variable: string milter_server_address

Address of the socket the milter server is listening to. This is defined by the listen statement in the server section of the configuration file (see conf-server),

Predefined Variable: number milter_server_family

Address family of the milter server address, as defined by the listen statement in the server section of the configuration file (see conf-server). See the FAMILY_ constants in Table 4.3.

Predefined Variable: string milter_client_address

Address of the milter client which initiated the connection.

Predefined Variable: number milter_client_family

Address family of milter_client_address. See the FAMILY_ constants in Table 4.3.

Predefined Variable: number cache_used

This variable is set by stdpoll and strictpoll built-ins (and, consequently, by the on poll statement). Its value is ‘1’ if the function used the cached data instead of directly polling the host, and ‘0’ if the polling took place. See SMTP Callout functions.

You can use this variable to make your reject message more informative for the remote party. The common paradigm is to define a function, returning empty string if the result was obtained from polling, or some notice if cached data were used, and to use the function in the reject text, for example:

func cachestr() returns string
do
  if cache_used
    return "[CACHED] "
  else
    return ""
  fi
done

Then, in prog envfrom one can use:

on poll $f
do
when not_found or failure:
  reject 550 5.1.0 cachestr() . "Sender validity not confirmed"
done

Predefined Variable: string clamav_virus_name

Name of virus identified by ClamAV. Set by clamav function (see ClamAV).

Predefined Variable: number greylist_seconds_left

Number of seconds left to the end of greylisting period. Set by greylist and is_greylisted functions (see Special test functions).

Predefined Variable: string ehlo_domain

Name of the domain used by polling functions in SMTP EHLO or HELO command. Default value is the fully qualified domain name of the host where mailfromd is run. See Polling.

Predefined Variable: string last_poll_greeting

Callout functions (see SMTP Callout functions) set this variable before returning. It contains the initial SMTP reply from the last polled host.

Predefined Variable: string last_poll_helo

Callout functions (see SMTP Callout functions) set this variable before returning. It contains the reply to the HELO (EHLO) command, received from the last polled host.

Predefined Variable: string last_poll_host

Callout functions (see SMTP Callout functions) set this variable before returning. It contains the host name or IP address of the last polled host.

Predefined Variable: string last_poll_recv

Callout functions (see SMTP Callout functions) set this variable before returning. It contains the last SMTP reply received from the remote host. In case of multi-line replies, only the first line is stored. If nothing was received the variable contains the string ‘nothing’.

Predefined Variable: string last_poll_sent

Callout functions (see SMTP Callout functions) set this variable before returning. It contains the last SMTP command sent to the polled host. If nothing was sent, last_poll_sent contains the string ‘nothing’.

Predefined Variable: string mailfrom_address

Email address used by polling functions in SMTP MAIL FROM command (see Polling.). Default is ‘<>’. Here is an example of how to change it:

set mailfrom_address "postmaster@my.domain.com"

You can set this value to a comma-separated list of email addresses, in which case the probing will try each address until either the remote party accepts it or the list of addresses is exhausted, whichever happens first.

It is not necessary to enclose emails in angle brackets, as they will be added automatically where appropriate. The only exception is null return address, when used in a list of addresses. In this case, it should always be written as ‘<>’. For example:

set mailfrom_address "postmaster@my.domain.com, <>"

Predefined Variable: number sa_code

Spam score for the message, set by sa function (see sa).

Predefined Variable: number rcpt_count

The variable rcpt_count keeps the number of recipients given so far by RCPT TO commands. It is defined only in ‘envrcpt’ handlers.

Predefined Variable: number sa_threshold

Spam threshold, set by sa function (see sa).

Predefined Variable: string sa_keywords

Spam keywords for the message, set by sa function (see sa).

Predefined Variable: number safedb_verbose

This variable controls the verbosity of the exception-safe database functions. See safedb_verbose.