maildropfilter

title: maildropfilter(7)

summary: maildrop\*(Aqs filtering language

text:
# maildropfilter(7)

## NAME
maildropfilter - maildrop's filtering language

## SYNOPSIS
/etc/courier-imap/maildroprc, $HOME/.mailfilter, $HOME/.mailfilters/*, and friends...

## DESCRIPTION
This manual page describes the language used by maildrop 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's, but it is important to note that it is not Perl, and is very different from Perl, in certain cases.

If the filtering instructions do not exist, maildrop delivers the message to the default mailbox without doing any additional processing, making it indistinguishable from the usual mail delivery agent.

It is important to note that maildrop reads and parses the filter file before doing anything. If there are any errors maildrop prints an error message, and terminates with the exit code set to EX_TEMPFAIL. 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.

### Environment
maildrop uses variables to access and manipulate messages. Variables are arbitrary text accessed 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:

```
FILE="IN.junk"

```

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:

```
to $FILE

```

This will deliver the current message to the mailbox file (or a maildir directory) named "IN.junk".

maildrop initially creates variables from the environment variables of the operating system, UNLESS maildrop runs in delivery mode. Each operating system environment variable becomes a maildrop variable. When running in delivery mode, maildrop does not import the environment for security reasons, except for the environment variables that define the process locale (LANG, LANGUAGE, and LC_*), which are still imported.

In all cases maildrop resets the following variables to their default values: HOME, DEFAULT, SHELL, PATH, LOCKEXT, LOCKREFRESH, LOCKSLEEP, LOCKTIMEOUT, MAILDIRQUOTA, SENDMAIL and LOGNAME.

There's one exception to this rule which applies to the version of maildrop that comes with the Courier mail server[1]. The following does not apply to the standalone version of maildrop: when running in delivery mode, if the -d flag was not used, or if it specifies the same userid as the one that's running maildrop: the following variables are automatically imported from the environment: HOME, SHELL, LOGNAME and MAILDIRQUOTA. These environment variables are initialized by the Courier mail server prior to running maildrop. Additionally, the initial value for the DEFAULT maildrop variable is imported from the MAILDROPDEFAULT environment variable. This is because the Courier mail server overloads the DEFAULT environment variable to store the defaulted portion of the local mailbox address. See the dot-courier(5)[2] man page in the Courier mail server distribution. You can get the Courier mail server's DEFAULT value by using the import command. Note, however, that this will clobber the old contents of DEFAULT, which is probably not what you want. The right way to do this would be something like this:

```
SAVEDEFAULT=$DEFAULT
import DEFAULT
LOCALDEFAULT=$DEFAULT
DEFAULT=$SAVEDEFAULT

```

All internal variables are exported back as environment variables when maildrop runs an external command. Changes to internal variables, made by the filter file, are reflected in the exported environment.

### Lexical structure
Most whitespace is generally ignored. The # character introduces a comment running to the end of the line, which is also ignored. Unlike other mail filters, maildrop parses the filter file before taking any action with the message. If there are syntax errors in the file, maildrop 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.

Note

In maildrop, 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.

### Literal text
Literal text in the maildrop 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.

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.

Multiple text literals in a row are automatically concatenated, even if they use different quotes. For example:

```
FOOBAR="Foo"'bar'

```

This sets the variable FOOBAR to the text "Foobar".

### Variable substitution
Variable substitution is performed on text literals that's surrounded by double quotation marks. The "$" character, followed by a variable name, is replaced by that variable's contents.

```
MAILBOX="$HOME/Mailbox"

```

This 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:

```
MAILBOX="${HOME-WORD}/Mailbox"

```

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.

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.

Variable substitution is not done in text literals which are surrounded by single quotes (apostrophes).

### Command line arguments
maildrop initializes special variables: $1, $2, and so on, with additional parameters specified on the maildrop command line. A filter file may use those variables just like any other variables.

### Predefined variables
The following variables are automatically defined by maildrop. 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:

DEFAULT

The default mailbox to deliver the message to. If the filter file 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.

FROM

Message envelope sender. This is usually the same address as what appears in the From: header, but may not be. This information may or may not be available to maildrop on your system. The message envelope sender is usually specified with the -f option to maildrop. If the -f option is not given, maildrop looks for the Return-Path: header in the message. As the last resort, FROM defaults to “MAILER-DAEMON”. Note that FROM may be empty - the message envelope sender is empty for bounce messages.

HOME

Home directory of the user running maildrop.

HOSTNAME

Network name of the machine running maildrop. Obtained from gethostname(3).

LOCKEXT

Extension for dot-lock files (default: .lock).

LOCKREFRESH

Refresh interval, in seconds, for dot-locks (default: 15). When maildrop dot-locks a mailbox, maildrop 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.

LOCKSLEEP

Number of seconds to wait to try again to create a dot-lock file, if one already exists (default: 5).

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, maildrop 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, maildrop 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.

LOGNAME

Name of the user to who the message is being delivered.

MAILDROP_OLD_REGEXP

Revert to using the old legacy pattern matching engine. Versions of maildrop prior to version 2.0 (included in the Courier mail server 0.51, and earlier), used a built-in pattern matching engine, instead of using the PCRE library (see the “Patterns” section). maildrop 1.x used a different syntax for patterns, which is no longer described in this manual page. The old pattern matching engine is still available, by setting MAILDROP_OLD_REGEXP to “1”. Setting this variable will use the legacy pattern matching engine for the rest of the maildrop recipe file. The pattern matching engine will be removed completely in a future version of maildrop. This setting provides for a transitional period of converting old recipes. MAILDROP_OLD_REGEXP can be set to “1” in the global maildroprc file, then reset to “0” in each individual maildrop recipe file, after it gets converted to the new syntax.

MAILFILTER

This is the name of the original filter file that was given to maildrop on the command line. This is mostly useful to -default filter files, it allows them to obtain the value of the -M option[3] specified on the command line.

PATH

Command execution path. maildrop resets PATH to the system default (usually /bin:/usr/bin:/usr/local/bin).

SENDMAIL

The mail delivery agent. When maildrop 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.

SHELL

The login shell. The shell is used to execute all commands invoked by maildrop.

VERBOSE

Current Debug level (default: 0). Setting VERBOSE to progressive higher values, between 1 and 9, produces debugging output on standard error. maildrop ignores the VERBOSE variable in delivery mode (in order not to confuse the mail transport agent).

UMASK

The file creation mode mask, in octal. The default setting of 077 creates mailboxes that are readable and writable by the owner only. Use 007 to create mailboxes that are readable/writable by both owner and the group. Use 037 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.

### Other special variables
The following variables are automatically used by maildrop when the filter file is being processed:

EXITCODE

Return code for maildrop. When maildrop successfully delivers a message, it terminates with this exit code, which defaults to 0. When the to or the cc command is used to deliver the message to an external process, via a pipe, maildrop will set this variable to the exit code of the external process. Since maildrop immediately terminates after completing the to command this means that maildrop's exit code will be the exit code of the external process. If the to command does not deliver the message to a process you must set EXITCODE before the to command, since maildrop terminates immediately after finishing the delivery.

FLAGS

The FLAGS variable is used only when delivering a message to a maildir, and may contain only the following letters: “D”, “F”, “R”, and “S”. 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. FLAGS must be set before the message is delivered to a maildir. The contents of FLAGS are ignored, when delivering on an mbox folder.

KEYWORDS

The KEYWORDS variable is used only when delivering a message to a maildir, and implements the optional IMAP keyword extension as implemented in the Courier IMAP server[1]. It may be optionally initialized to contain a comma-separate list of keywords. The to, or the cc command, delivers the message to the maildir normally, but also associated the list of keywords in KEYWORDS with the newly delivered message. KEYWORDS must be set before the message is delivered to a maildir. The contents of KEYWORDS are ignored, when delivering on an mbox folder.

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. Use this as criteria for filtering, nothing more.

MAILDIRQUOTA

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 maildirquota(8)[4] for more information.

RETURNCODE

This variable is set when maildrop runs the system[5] command, xfilter[6] 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.

SIZE

Number of bytes in the message. This may or may not include the -A option. Use this as a criteria for filtering, nothing more.

### 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.

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.

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:

```
MAILDIR=/var/mail

```

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.

Long double or singly-quoted text can be broken across multiple lines by ending the line with a lone backslash character, like this:

```
TEXT="This is a long \

   text string"

```

The backslash, the newline, and all leading whitespace on the next line is removed, resulting in "This is a long text string".

### Command substitution
Text enclosed in back-tick characters is interpreted as a shell command. The shell command is executed as a child process by maildrop. Its output is used in place of the command. For example:

```
DIR=`ls`

```

places the names of the files in the current directory into the DIR variable.

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.

### Patterns
The pattern syntax in maildrop is similar to the grep command's syntax, with some minor differences. A pattern takes the following form in the filter file:

```
/pattern/:options

```

pattern specifies the text to look for in the message, in the UTF-8 codeset. pattern 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 "/[ ] ... /".

The general syntax of maildrop's patterns is described in the pcrepattern(3) manual page, with certain exceptions noted below. maildrop uses the PCRE[7] library to implement pattern matching. Not all features in PCRE are available in maildrop, and the “options” part, which follows the pattern specification, changes the pattern matching further. Consult the pcrepattern(3) manual page for more information, but note the following exceptions:

•Internal options settings are not supported (but see the “D” maildrop option, below). Do not include option settings in the pattern, doing so will lead to undefined results.

•Named subpatterns are not implemented. Numbered subpatterns are implemented, see “Pattern Match Results”, below.

•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. 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.

This means that header search patterns that include punctuation character may appear not to work against obviously-matching message text. Use “reformime -u <message.txt”, with message.txt containing the sample message, to see exactly the actual text that gets searched by patterns.

### Pattern options
Following /pattern/, there may be an optional colon, followed by one. or more options. The following options may be specified in any order:

h

Match this pattern in the message's header, and the header of any attachments in the message.

H

Match this pattern in the message's main header. Do not match this pattern in the headers of the message's attachments.

b

Match this pattern against the message body.

D

This is a case sensitive match. Normally the patterns match either uppercase or lowercase text. /john/ 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.

If neither 'h', 'H', or 'b' is specified, 'h' is the default, matching the pattern in the message's header, and all attachments' headers. Specifying the 'b' option causes the pattern to be matched against the message body. Specifying 'b' and 'h' causes the pattern to be matched against the entire message.

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.

### MIME encoding
The pattern must be a valid text string in the UTF-8 codeset, and maildrop should handle messages that use MIME encodings in other known character sets. Options that specify a message header search result in maildrop 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.

For a MIME search to succeed, the message must be a well-formed MIME message (with a Mime-Version: 1.0 header).

### Weighted scoring
Patterns are evaluated by maildrop as any other numerical expression. If a pattern is found, maildrop'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.

maildrop can also do weighted scoring. In weighted scoring, multiple occurrences of the same pattern are used to calculate a numerical score.

To use a weighted search, specify the pattern as follows:

```
/pattern/:options,xxx,yyy

```

where xxx and yyy are two numbers. yyy is optional -- it will default to 1, if missing.

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.

Note

maildrop 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.

### Pattern Match Results
After a pattern is successfully matched, the actual text that is matched is placed in the MATCH variable. For example:

```
/^From:.*/

```

matches a line of the form:

```
From: postmaster@localhost

```

Here the variable MATCH will be set to "From: postmaster@localhost", which can be used in subsequent statements.

If the pattern contains subpatterns, the portions of the text that match the first subpattern is placed in the MATCH1 variable. The second subpattern, if any, is placed in MATCH2, and so on:

```
/^From:\s+(.*)@(.*)/

```

matched against the same line will set MATCH to “From: postmaster@localhost”, MATCH1 to “postmaster”, and MATCH2 to “localhost”. Of course, in real world the “From:” header is usually much more complicated, and can't be handled that easily. This is just an illustrative example.

Note

Subpatterns are not processed in the foreach statement.

### Conversion of maildrop 1.x patterns to 2.0
Although the new PCRE-based pattern matching code in maildrop is completely different from the built-in pattern matching code in maildrop 1.x, very few changes will be required to convert recipes to the new syntax. The only major differences are:

•The subexpression format has changed. Any pattern that uses subexpression needs to be converted. Additionally, references to MATCH2 must be replaced with MATCH1, MATCH3 to MATCH2, and so on. References to plain old MATCH will remain the same.

•The “w” pattern option is no longer possible, with PCRE. The very few recipes that use this option, if any actually exist, will have to be rewritten in some other fashion.

### Expressions
Although maildrop 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.

Operators

The following operators carry their usual meaning, and are listed in order from lowest precedence, to the highest:

```
||
&&
<  <=  >  >=  ==  !=  lt  le  gt  ge  eq  ne
|
&
+  -
*  /
=~ /pattern/
/pattern/  !  ~  function()

```

Variable assignment

```
VARIABLE=expression

```

Assigns the result of the expression to VARIABLE (note no leading $ in front of variable).

Note

If VARIABLE 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.

cc - deliver a copy of the message

```
cc expression

```

The cc statement is very similar to the to statement, except that after delivering the message maildrop continues to process the filter file, unlike the to statement which immediately terminates maildrop 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 cc or to statement.

See the to statement[8] for more details. When cc is used to deliver a message to a process maildrop will set the EXITCODE variable to the process's exit code.

dotlock - create a manual dot-lock

```
dotlock expression {

   ...
}

```

maildrop automatically creates a lock when a message is delivered to a mailbox. Depending upon your system configuration, maildrop will use either dot-locks, or the flock() system call.

The dotlock statement creates an explicit dot-lock file. Use the flock statement[9] to create an explicit flock() lock.

The expression is a filename that should be used as a lock file. maildrop 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.

Note

With manual locking, it is possible to deadlock multiple maildrop processes (or any other processes that try to claim the same locks).

No deadlock detection is possible with dot-locks, and since maildrop automatically refreshes all of its dot-locks regularly, they will never go stale. You'll have maildrop processes hanging in limbo, until their watchdog timers go off, aborting the mail delivery.

echo - output diagnostic information

```
echo expression

```

maildrop will print the given text. This is usually used when maildrop 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 \c, no newline will be printed.

exception - trap fatal errors

```
exception {

   ...
}

```

The exception 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 exception clause, execution will resume immediately following the exception clause.

exit - terminate filtering unconditionally

```
exit

```

The exit statement immediately terminates filtering. maildrop's return code is set to the value of the EXITCODE variable. Normally, maildrop terminates immediately after successfully delivering the message[8] to a mailbox. The exit statement causes maildrop to terminate without delivering the message anywhere.

The exit statement is usually used when maildrop runs in embedded mode[10], when message delivery instructions are not allowed.

flock - create an manual flock() lock

```
flock expression {

   ...
}

```

maildrop automatically creates a lock when a message is delivered to a mailbox. Depending upon your system configuration, maildrop will use either dot-locks, or the flock() system call.

The flock statement creates a manual flock() lock. Use the dotlock statement[11] to create a manual dot-lock file.

The expression is the name of the file that should be locked. maildrop creates the lock on the indicated file, executes the filtering instructions contained within the { ... } block, and removes the lock.

Note

With manual locking, it is possible to deadlock multiple maildrop 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 maildrop processes will terminate immediately. Use the exception statement in order to trap this exception condition, and execute an alternative set of filtering instructions.

foreach - iterate over text sections matched by a pattern

```
foreach /pattern/:options
{

   ...
}
foreach (expression) =~ /pattern/:options
{

   ...
}

```

The foreach 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:

,xxx,yyy

Weighted scoring is meaningless, in this context.

( ... )

Subpatterns are not processed. Only the MATCH variable will be set for each found pattern.

if - conditional execution

```
if (expression)
{

   ...
}
else
{

   ...
}

```

Conditional execution. If expression evaluates to a logical true (note - parenthesis are required) then the first set of statements is executed. The else keyword, and the subsequent statements, are optional. If present, and the expression evaluates to a logical false, the else part is executed.

maildrop 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.

If the if part, or the else part consists of only one statement, the braces may be omitted.

Note

The grammar of this if statement is stricter than usual. If you get baffling syntax errors from maildrop, 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).

If the else part contains a single if, and nothing else, this may be combined into an elsif:

```
if (expression)
{

   ...
}
elsif (expression)
{

   ...
}

```

The above example is logically identical to:

```
if (expression)
{

   ...
}
else
{

   if (expression)

   {

      ...

   }
}

```

Consecutive elsif sequences are allowed:

```
if (expression)
{

   ...
}
elsif (expression)
{

   ...
}
elsif (expression)
{

   ...
}

```

Consecutive occurences of elsif commands eliminate a significant amount of indentation, and the resulting code is more readable.

import - access original environment variable

```
import variable

```

When maildrop starts, it normally imports the contents of the environment variables, and assigns them to internal maildrop variables. For example, if there was an environment variable FOO, the internal maildrop variable FOO will have the contents of the environment variable. From then on, FOO will be no different than any other variable, and when maildrop runs an external command, the contents of maildrop's variables will be exported as the environment for the command.

Certain variables, like HOME and PATH, 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 maildrop starts with only the fixed default variables.

The import statement initializes the specified variable with the contents of the original environment variable when maildrop started. For example:

```
echo "PATH is $PATH"
PATH="/bin"
echo "PATH is $PATH"
import PATH
echo "PATH is $PATH"
exit

```

This results in the following output:

```
PATH is /bin:/usr/bin:/usr/local/bin
PATH is /bin
PATH is /home/root/bin:/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin

```

This shows that when maildrop starts PATH is set to the fixed default of /bin:/usr/bin:/usr/local/bin. However, the original contents of the PATH environment variable we different, and the import statement shows what it was.

include - execute filtering instructions from another file

```
include expression

```

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 maildrop reads the initial filter file, any syntax errors in the filtering instructions are immediately reported, and maildrop will terminate with a return code of EX_TEMPFAIL. Any errors in files specified by include statements are NOT reported, because those files will not be read until the include statement is itself executed.

If the specified file does not exist, or if there are any syntax errors in the file, maildrop reports the error, and terminates with a return code of EX_TEMPFAIL.

log, logfile - log message deliveries

```
logfile expression
log expression

```

Logging in maildrop is normally turned off. The logfile statement specifies the file where maildrop will log how the message has been disposed of. The parameter is then name of the file. If the file exists maildrop appends to the file.

For each delivery (the to[8] and cc[12] statements, and default deliveries) maildrop records the From: and the Subject: fields, together with the current time, in the log file.

The log statement adds additional logging text to the log file. The log statement works exactly like the echo statement, except that the text is written to the logfile, instead of standard output.

system - execute a system command

```
system expression

```

expression specifies an external program that maildrop runs as a subprocess. The subprocess's standard input gets connected to /dev/null, and the subprocess inherits the standard output and error from maildrop.

to - deliver message to a mailbox

```
to expression

```

The to statement delivers the message to a mailbox. expression 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).

The to statement is the final delivery statement. maildrop delivers message, then immediately terminates, with its return code set to the EXITCODE variable. If there was an error while delivering the message, maildrop 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.

An expression that begins with the "|" character 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. maildrop's exit code will be the process's exit code.

An expression 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 SENDMAIL variable is run as an external program, with the list of E-mail addresses provided as parameters to the program.

Otherwise, expression names the mailbox where maildrop delivers the message. If expression is a directory, maildrop assumes that the directory is a maildir directory. Otherwise, maildrop will deliver the message to a file, formatted in traditional mailbox format. maildrop will use either dot-locking, or flock()-locking when delivering the message to the file.

while - repeatedly execute a block of statements

```
while (expression)
{

   ...
}

```

The expression is repeatedly evaluated. Each time it evaluates to a logical true[13], the statements inside the braces are executed. When expression evaluates to a logical false, the while loop is over. Take care to avoid infinite loops.

xfilter - filter message through another program

```
xfilter expression

```

expression specifies an external program that maildrop 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, maildrop terminates with an exit code of EX_TEMPFAIL.

|| - logical or

```
expression1 || expression2

```

If expression1 evaluates to a logical true, the result of the || is expression1, otherwise it's expression2, which is evaluated.

maildrop 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.

&& - logical and

```
expression1 && expression2

```

If expression1 evaluates to a logical false, the result of the && is expression1, otherwise it's expression2, which is evaluated.

maildrop 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.

<, <=, >, >=, ==, != - numerical comparison

```
expression1 < expression2
expression1 <= expression2
expression1 > expression2
expression1 >= expression2
expression1 == expression2
expression1 != expression2

```

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.

Note

Ccomparisons are not associative: "a < b < c" is an error. If it is absolutely necessary, use "(a < b) < c".

lt, le, gt, ge, eq, ne - text comparison

```
expression1 lt expression2
expression1 le expression2
expression1 gt expression2
expression1 ge expression2
expression1 eq expression2
expression1 ne expression2

```

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.

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?).

| - bitwise or

```
expression1 | expression2

```

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.

& - bitwise and

```
expression1 & expression2

```

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.

+, -, *, / - numerical operations

```
expression1 + expression2
expression1 - expression2
expression1 * expression2
expression1 / expression2

```

These are numerical, floating point, operators.

=~ /pattern/:options - pattern match against string

```
expression =~ /pattern/:option

```

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 expression (if the options do not specify weighted scoring, the result is simply 1 if the pattern was found, 0 if not).

See "Patterns[14]" for more information.

/pattern/:options - pattern match against message

```
/pattern/:option

```

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).

See "Patterns[14]" for more information.

!, ~ - logical/bitwise not operator.

```
! expression
~ expression

```

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.

maildrop 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.

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.

escape(string) - escape special characters in a string.

```
escape(expression)

```

The escape 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:

```
|!$()[]\+*?.&;`'-~<>^{}"

```

This can used when matching pattern sections[15], and then taking one section and matching it again. For example:

```
if ( /^From:\s*(.*)/ )
{

   MATCH1=escape($MATCH1)

   if ( /^Subject:.*$MATCH1/ )

   {

      ...

   }
}

```

This example checks if the contents of the From: header can also be found in the Subject: header. If the escape function were not used, then any special characters in the From: header that are also used in regular expressions, such as * or +, would introduce unpredictable behavior, most likely a syntax error.

The reason why this list of special characters also includes characters not used in maildrop's regular expressions is to allow maildrop's variables to be used on the command line of a shell command executed by the xfilter command, backtick characters, or to or cc commands.

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.

gdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop

These functions provide support for GDBM database files. See maildropgdbm(5)[16] for more information.

Note

The system administrator can disable GDBM support in maildrop, so these commands may not be available to you.

getaddr(string) - extract RFC 2822 addresses from a header.

```
if ( /^From:\s*(.*)/ )
{

   ADDR=getaddr($MATCH1)
}

```

This function is usually applied to a header that contains RFC 2822[17] 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 string contains:

```
joe@domain.com (Joe Brown), "Alex Smith" <alex@domain.com>, tom@domain.com

```

The result of the getaddr function is the following string:

```
joe@domain.com<NL>alex@domain.com<NL>tom@domain.com<NL>

```

Note

Because getaddr() interprets RFC 2822[18] 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:

```
ADDRLIST=""
foreach /^(To|Cc): .*/
{

    foreach (getaddr $MATCH) =~ /.+/

    {

        ADDRLIST="$ADDRLIST $MATCH"

    }
}

```

Note

In certain rare situations, RFC 2822[18] allows spaces to be included in E-mail addresses, so this example is just educational.

hasaddr(string) - Search for an address.

```
if ( hasaddr(string) )
{

   ...
}

```

"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.

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.

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.

length (string) - length of a string

```
if (length(string) > 80)
{

   ...
}

```

The length function returns the number of characters in string.

lookup (expr, 'filename', 'options') - read file for patterns

```
if (lookup(expr, file, "option"))
{

   ...
}

```

expr is any expression. filename is a name of a file containing a list of patterns. Note that filename is relative to the current directory, which is the home directory of the user when maildrop runs in delivery mode, or embedded mode. maildrop then reads the file. Blank lines will be ignored, as well as any lines that begin with the # character (comments).

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 expr. As soon as the match is found, lookup returns "1". If no match is found after reading the entire file, lookup returns "0". For example:

```
if ( /^To:\s*(.*)/ && lookup( $MATCH1, "badto.dat" ))
{

    exit
}

```

The file badto.dat contains the following two lines:

```
friend@public
^[^@]*$

```

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 ( maildrop will terminate without delivering the message anywhere).

options are the pattern matching options to use. The only supported option is "D" (the rest are meaningless, in this case).

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.

substr(string,start [,count]) - return substring

```
foo=substr($foo, 1, 10)

```

The substr function extracts characters from string beginning with character #start. If count is specified, at most count characters starting at position start are kept, any excess is trimmed.

time - return current time

```
foo=time

```

The time function returns the current time, in seconds, since January 1, 1970. This function is useful when using GDBM files. See maildropex(7)[19] for an example of using the time function.

tolower(string) - Convert string to lowercase.

```
foo=tolower(string)

```

This function returns the string with all uppercase characters replaced by lowercase characters.

toupper(string) - Convert string to uppercase.

```
foo=toupper(string)

```

This function returns the string with all lowercase characters replaced by uppercase characters.

### Statements
The filter file is read by maildrop ($HOME/.mailfilter or another file), and it contains filtering statements, one per line. The filtering language used by maildrop has a loosely - defined grammatical structure.

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.

## BUGS
If getaddr() or hasaddr() functions are used on broken headers, the results are unpredictable.

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.

## SEE ALSO
lockmail(1)[20], maildrop(1)[21], maildropgdbm(5)[16], maildirquota(8)[4], reformail(1)[22], egrep(1), sendmail(8).

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

Courier mail server

http://www.courier-mta.org/

2.

dot-courier(5)

http://www.courier-mta.org/maildrop/dot-courier.html

3.

value of the -M option

http://www.courier-mta.org/maildrop/maildrop.html#moption

4.

maildirquota(8)

http://www.courier-mta.org/maildrop/maildirquota.html

5.

system

http://www.courier-mta.org/maildrop/#system

6.

xfilter

http://www.courier-mta.org/maildrop/#xfilter

7.

PCRE

http://www.pcre.org

8.

See the to statement

http://www.courier-mta.org/maildrop/#to

9.

flock statement

http://www.courier-mta.org/maildrop/#flock

10.

embedded mode

http://www.courier-mta.org/maildrop/maildrop.html#embedded

11.

dotlock statement

http://www.courier-mta.org/maildrop/#dotlock

12.

cc

http://www.courier-mta.org/maildrop/#cc

13.

evaluates to a logical true

http://www.courier-mta.org/maildrop/#if

14.

Patterns

http://www.courier-mta.org/maildrop/#patterns

15.

matching pattern sections

http://www.courier-mta.org/maildrop/#patmatch

16.

maildropgdbm(5)

http://www.courier-mta.org/maildrop/maildropgdbm.html

17.

RFC 2822

http://www.rfc-editor.org/rfc/rfc2822.txt

18.

RFC 2822

http://www.rfc-editor.org/rfc/rfc822.txt

19.

maildropex(7)

http://www.courier-mta.org/maildrop/maildropex.html

20.

lockmail(1)

http://www.courier-mta.org/maildrop/lockmail.html

21.

maildrop(1)

http://www.courier-mta.org/maildrop/maildrop.html

22.

reformail(1)

http://www.courier-mta.org/maildrop/reformail.html


maildropgdbm

package: courier-maildrop

title: maildropgdbm(7)

summary: GDBM/DB support in maildrop

text:
# maildropgdbm(7)

## NAME
maildropgdbm - GDBM/DB support in maildrop

## SYNOPSIS

```
gdbmopen(filename, mode)
gdbmclose
gdbmfetch(key [,default])
gdbmstore(key,value)
```

## DESCRIPTION
The gdbm family of functions provides access to the GDBM library - a library of routines that manage simple database files. The library provides a way of quickly storing and looking up key/data pairs.

GDBM support in maildrop is optional, and may not be available to you.

GDBM support in maildrop can optionally be implemented using the DB library. This option is selected by the system administrator. If this is the case, these functions still work exactly as described below, except that they will operate on DB hash files, instead of GDBM files.

To see whether GDBM or DB support is used, run the command "maildrop -v".

GDBM support is minimal, and simplistic. A filter file may have only one gdbm file open at the same time. However, the filter file can close the current gdbm file, and open another one. If another filter file is included using the include statement, the included filter file may open its own, separate, gdbm file.

A GDBM file contains a list of key/value pairs. All keys in the GDBM file are unique. After storing an arbitrary key/value pair in the GDBM file, the value associated with the given key can be quickly located and retrieved.

### gdbmclose - close gdbm file

```
gdbmclose
```

This function closes the current GDBM file.

### gdbmfetch - retrieve data

```
gdbmfetch (key [, options] [, default])
```

This function retrieves the data for the given key. key is the key to retrieve. The gdbmfetch function returns the data associated with this key. If the key does not exist in the GDBM file, gdbmfetch returns the default argument. If the default argument is not specified, gdbmfetch returns empty text. Please note that the default argument is not actually evaluated unless the key does not exist in the GDBM file.

The options argument specifies additional maildrop value-added features. The following functionality is not available in the GDBM library, but is rather provided by maildrop.

If the options argument is set to "D", and the key could not be found in the GDBM database, and the key is of the form "user@domain", maildrop will then attempt to look up the key "user@". If that key is also not found, maildrop finally looks up the key "domain".

If "domain" is also not found, and domain is of the form "a.b.c.d.tld" (with variable number of period-separated sections), maildrop then attempts to look up the key "b.c.d.tld". If that key is not found, maildrop tries "c.d.tld", and so on, until a key is found, or there are no more subdomains to remove, at which point gdbmfetch will return either the default argument, or empty text.

If the options argument is set to "D", and the key could not be found in the GDBM database, and the key is of the form "a.b.c.d.tld" (with variable number of period-separated sections), maildrop will also attempt to look up keys for successive higher-level domains in the GDBM database.

Note

GDBM databases are case sensitive. Make sure that the GDBM database is created using lowercase letters only, and use the tolower[1] function to convert the key to lowercase.

If the options argument is "I", and the key is not in the GDBM database, and the key is of the form "w.x.y.z" (with variable number of period-separated sections), maildrop then tries to look up the key "w.x.y", then "w.x", until a key is found, or there are no more sections to remove. Use this feature to look up IP-address based GDBM lists.

Note

These features are implemented by brute force: if the query doesn't succeed, try again. Take note of potential denial-of-service attacks where key is set to a long text string consisting mostly of periods, which will result in numerous GDBM queries that will take an excessive amount of time to complete.

### gdbmopen - open gdbm file

```
gdbmopen (file [, mode])
```

gdbmopen opens the indicated GDBM file. The optional second argument specifies the following:

"R"

Open this GDBM file for reading.

"W"

Open this GDBM file for reading and writing.

"C"

Open this GDBM file for reading and writing. If the GBDM file doesn't exist, create it.

"N"

Create a new GDBM file. If the file exists, the existing file is deleted. The file is opened for reading and writing.

The mode argument defaults to "R" is used. In embedded mode, only "R" is allowed.

The GDBM library allows multiple processes to read the same GDBM file at the same time, but it does not allow multiple access when the GDBM file is open for writing. Using flock[2] or dotlock[3] is highly recommended.

In delivery mode, maildrop runs from the recipient's home directory. Keep that in mind while specifying the filename.

The gdbmopen function returns 0 if the GDBM file was successfully opened, non-zero otherwise.

### gdbmstore - store data

```
gdbmstore(key, value)
```

key is the key value to store in the GDBM file. value is the value to store. If key already exists in the GDBM file, value replacest the old value. The gdbmstore function is only permitted if the GDBM file is opened for writing. If gdbmopen opened the GDBM file for reading only, gdbmstore will return -1. Otherwise, gdbmstore returns 0.

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

tolower

http://www.courier-mta.org/maildrop/maildropfilter.html#tolower

2.

flock

http://www.courier-mta.org/maildrop/maildropfilter.html#flock

3.

dotlock

http://www.courier-mta.org/maildrop/maildropfilter.html#dotlock


courier-unicode

package: courier-unicode-devel

title: courier-unicode(7)

summary: Courier Unicode Library

text:
# courier-unicode(7)

## NAME
courier-unicode - Courier Unicode Library

## SYNOPSIS

```
#include <courier-unicode.h>
```

## DESCRIPTION
This library implements several algorithms related to the Unicode Standard[1]. This library uses iconv(3)[2] to convert text in a given character set to unicode. Any character set displayed by iconv --list can be specified for the corresponding character set parameter. Additionally, courier-unicode.h defines a special character string unicode_x_imap_modutf7 that specifies the pseudo-character set for the modified-UTF7 encoding used in IMAP. This string can also be appended by a space, and up to fifteen additional US-ASCII characters. The resulting character set also encodes these additional characters, in addition to unicode characters, with modified-UTF7.

The C++ compiler must have C++11 support. Minimum usable version of gcc appears to be gcc 4.4 with the -std=c++0x flag. Current versions of gcc use C++11, or higher, by default and do not require extra flags. Consult the packaging documentation for the Courier Unicode Library for information on any compiler flags that are needed to build software that links with this library.

## SEE ALSO
unicode_bidi(3), unicode_canonical(3), unicode_category_lookup(3), unicode_convert(3), unicode_default_chset(3), unicode_emoji_lookup(3), unicode_html40ent_lookup(3), unicode_grapheme_break(3), unicode_line_break(3), unicode_script(3), unicode_uc(3), unicode_word_break(3), unicode::bidi(3), unicode::canonical(3), unicode::iconvert::convert(3), unicode::iconvert::convert_tocase(3), unicode::iconvert::fromu(3), unicode::iconvert::tou(3), unicode::tolower(3), unicode::linebreak(3), unicode::wordbreak(3).

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

Unicode Standard

https://www.unicode.org/standard/standard.html

2.

iconv(3)

https://manpages.courier-mta.org/htmlman3/iconv.3.html


backend

package: cups

title: backend(7)

summary: cups backend transmission interfaces

text:
# backend(7)

## NAME
backend - cups backend transmission interfaces

## SYNOPSIS
backend

backend job user title num-copies options [ filename ]

```
#include <cups/cups.h>
const char *cupsBackendDeviceURI(char **argv);
void cupsBackendReport(const char *device_scheme,

                       const char *device_uri,

                       const char *device_make_and_model,

                       const char *device_info,

                       const char *device_id,

                       const char *device_location);
ssize_t cupsBackChannelWrite(const char *buffer,

                             size_t bytes, double timeout);
int cupsSideChannelRead(cups_sc_command_t *command,

                        cups_sc_status_t *status, char *data,

                        int *datalen, double timeout);
int cupsSideChannelWrite(cups_sc_command_t command,

                         cups_sc_status_t status, const char *data,

                         int datalen, double timeout);
```

## DESCRIPTION
Backends are a special type of filter(7) which is used to send print data to and discover different devices on the system.

Like filters, backends must be capable of reading from a filename on the command-line or from the standard input, copying the standard input to a temporary file as required by the physical interface.

The command name (argv[0]) is set to the device URI of the destination printer. Authentication information in argv[0] is removed, so backend developers are urged to use the DEVICE_URI environment variable whenever authentication information is required. The cupsBackendDeviceURI() function may be used to retrieve the correct device URI.

Back-channel data from the device should be relayed to the job filters using the cupsBackChannelWrite function.

Backends are responsible for reading side-channel requests using the cupsSideChannelRead() function and responding with the cupsSideChannelWrite() function. The CUPS_SC_FD constant defines the file descriptor that should be monitored for incoming requests.

### DEVICE DISCOVERY
When run with no arguments, the backend should list the devices and schemes it supports or is advertising to the standard output. The output consists of zero or more lines consisting of any of the following forms:

```
    device-class scheme "Unknown" "device-info"

    device-class device-uri "device-make-and-model" "device-info"

    device-class device-uri "device-make-and-model" "device-info" "device-id"

    device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location"
```

The cupsBackendReport() function can be used to generate these lines and handle any necessary escaping of characters in the various strings.

The device-class field is one of the following values:

direct

The device-uri refers to a specific direct-access device with no options, such as a parallel, USB, or SCSI device.

file

The device-uri refers to a file on disk.

network

The device-uri refers to a networked device and conforms to the general form for network URIs.

serial

The device-uri refers to a serial device with configurable baud rate and other options. If the device-uri contains a baud value, it represents the maximum baud rate supported by the device.

The scheme field provides the URI scheme that is supported by the backend. Backends should use this form only when the backend supports any URI using that scheme. The device-uri field specifies the full URI to use when communicating with the device.

The device-make-and-model field specifies the make and model of the device, e.g. "Example Foojet 2000". If the make and model is not known, you must report "Unknown".

The device-info field specifies additional information about the device. Typically this includes the make and model along with the port number or network address, e.g. "Example Foojet 2000 USB #1".

The optional device-id field specifies the IEEE-1284 device ID string for the device, which is used to select a matching driver.

The optional device-location field specifies the physical location of the device, which is often used to pre-populate the printer-location attribute when adding a printer.

### PERMISSIONS
Backends without world read and execute permissions are run as the root user. Otherwise, the backend is run using an unprivileged user account, typically "lp".

## EXIT STATUS
The following exit codes are defined for backends:

CUPS_BACKEND_OK

The print file was successfully transmitted to the device or remote server.

CUPS_BACKEND_FAILED

The print file was not successfully transmitted to the device or remote server. The scheduler will respond to this by canceling the job, retrying the job, or stopping the queue depending on the state of the printer-error-policy attribute.

CUPS_BACKEND_AUTH_REQUIRED

The print file was not successfully transmitted because valid authentication information is required. The scheduler will respond to this by holding the job and adding the 'cups-held-for-authentication' keyword to the "job-reasons" Job Description attribute.

CUPS_BACKEND_HOLD

The print file was not successfully transmitted because it cannot be printed at this time. The scheduler will respond to this by holding the job.

CUPS_BACKEND_STOP

The print file was not successfully transmitted because it cannot be printed at this time. The scheduler will respond to this by stopping the queue.

CUPS_BACKEND_CANCEL

The print file was not successfully transmitted because one or more attributes are not supported or the job was canceled at the printer. The scheduler will respond to this by canceling the job.

CUPS_BACKEND_RETRY

The print file was not successfully transmitted because of a temporary issue. The scheduler will retry the job at a future time - other jobs may print before this one.

CUPS_BACKEND_RETRY_CURRENT

The print file was not successfully transmitted because of a temporary issue. The scheduler will retry the job immediately without allowing intervening jobs.

All other exit code values are reserved.

## ENVIRONMENT
In addition to the environment variables listed in cups(1) and filter(7), CUPS backends can expect the following environment variable:

DEVICE_URI

The device URI associated with the printer.

## FILES
/etc/cups/cups-files.conf

## NOTES
CUPS backends are not generally designed to be run directly by the user. Aside from the device URI issue ( argv[0] and DEVICE_URI environment variable contain the device URI), CUPS backends also expect specific environment variables and file descriptors, and typically run in a user session that (on macOS) has additional restrictions that affect how it runs. Backends can also be installed with restricted permissions (0500 or 0700) that tell the scheduler to run them as the "root" user instead of an unprivileged user (typically "lp") on the system.

Unless you are a developer and know what you are doing, please do not run backends directly. Instead, use the lp(1) or lpr(1) programs to send print jobs or lpinfo(8) to query for available printers using the backend. The one exception is the SNMP backend - see cups-snmp(8) for more information.

## NOTES
CUPS printer drivers and backends are deprecated and will no longer be supported in a future feature release of CUPS. Printers that do not support IPP can be supported using applications such as ippeveprinter(1).

## SEE ALSO
cups(1), cups-files.conf(5), cups-snmp(8), cupsd(8), filter(7), lp(1), lpinfo(8), lpr(1),

CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


filter

title: filter(7)

summary: cups file conversion filter interface

text:
# filter(7)

## NAME
filter - cups file conversion filter interface

## SYNOPSIS
filter job user title num-copies options [ filename ]

```
#include <cups/cups.h>
ssize_t cupsBackChannelRead(char *buffer, size_t bytes,

                            double timeout);
cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,

                                          char *data, int *datalen,

                                          double timeout);
#include <cups/ppd.h>
const char *cupsGetOption(const char *name, int num_options,

                 cups_option_t *options);
int cupsMarkOptions(ppd_file_t *ppd, int num_options,

                    cups_option_t *options);
int cupsParseOptions(const char *arg, int num_options,

                     cups_option_t **options);
ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
void ppdMarkDefaults(ppd_file_t *ppd);
ppd_file_t *ppdOpenFile(const char *filename);
```

## DESCRIPTION
The CUPS filter interface provides a standard method for adding support for new document types or printers to CUPS. Each filter is capable of converting from one or more input formats to another format that can either be printed directly or piped into another filter to get it to a printable format.

Filters MUST be capable of reading from a filename on the command-line or from the standard input, copying the standard input to a temporary file as required by the file format. All output MUST be sent to the standard output. Filters MUST NOT attempt to communicate directly with the printer, other processes, or other services.

The command name (argv[0]) is set to the name of the destination printer but is also available in the PRINTER environment variable.

## OPTIONS
Options are passed in argv[5] and are encoded from the corresponding IPP attributes used when the job was submitted. Use the cupsParseOptions() function to load the options into a cups_option_t array and the cupsGetOption() function to get the value of a specific attribute. Be careful to look for common aliases of IPP attributes such as "landscape" for the IPP "orientation-requested" attribute.

Options passed on the command-line typically do not include the default choices the printer's PPD file. Use the ppdMarkDefaults() and cupsMarkOptions() functions in the CUPS library to apply the options to the PPD defaults and map any IPP attributes to the corresponding PPD options. Use ppdFindMarkedChoice() to get the user-selected choice for a PPD option. For example, a filter might use the following code to determine the current value of the Duplex PPD option:

```
    ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));

    cups_option_t *options = NULL;

    int num_options = cupsParseOptions(argv[5], 0, &options);

    ppdMarkDefaults(ppd);

    cupsMarkOptions(ppd, num_options, options);

    ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex");
```

Raster filters should use option choices set through the raster page header, as those reflect the options in effect for a given page. Options specified on the command-line determine the default values for the entire job, which can be overridden on a per-page basis.

## LOG MESSAGES
Messages sent to the standard error are generally stored in the printer's "printer-state-message" attribute and the current ErrorLog file. Each line begins with a standard prefix:

ALERT: message

Sets the "printer-state-message" attribute and adds the specified message to the current ErrorLog using the "alert" log level.

ATTR: attribute=value [ ... attribute=value]

Sets the named job or printer attribute(s). The following job attributes can be set: "job-media-progress". The following printer attributes can be set: "auth-info-required", "marker-colors", "marker-high-levels", "marker-levels", "marker-low-levels", "marker-message", "marker-names", "marker-types", "printer-alert", and "printer-alert-description".

CRIT: message

Sets the "printer-state-message" attribute and adds the specified message to the current ErrorLog using the "critical" log level.

DEBUG: message

Adds the specified message to the current ErrorLog using the "debug" log level. DEBUG messages are never stored in the "printer-state-message" attribute.

DEBUG2: message

Adds the specified message to the current ErrorLog using the "debug2" log level. DEBUG2 messages are never stored in the "printer-state-message" attribute.

EMERG: message

Sets the "printer-state-message" attribute and adds the specified message to the current ErrorLog using the "emergency" log level.

ERROR: message

Sets the "printer-state-message" attribute and adds the specified message to the current ErrorLog using the "error" log level.

INFO: message

Sets the "printer-state-message" attribute. If the current LogLevel is set to "debug2", also adds the specified message to the current ErrorLog using the "info" log level.

NOTICE: message

Sets the "printer-state-message" attribute and adds the specified message to the current ErrorLog using the "notice" log level.

PAGE: page-number #-copies

PAGE: total #-pages

Adds an entry to the current PageLog. The first form adds #-copies to the "job-media-sheets-completed" attribute. The second form sets the "job-media-sheets-completed" attribute to #-pages.

PPD: Keyword=Value [ ... KeywordN=Value ]

Sets the named keywords in the printer's PPD file. This is typically used to update default option keywords such as DefaultPageSize and the various installable options in the PPD file.

STATE: printer-state-reason [ ... printer-state-reason ]

STATE: + printer-state-reason [ ... printer-state-reason ]

STATE: - printer-state-reason [ ... printer-state-reason ]

Sets, adds, or removes "printer-state-reason" keywords for the current queue. Typically this is used to indicate media, ink, and toner conditions on a printer.

WARNING: message

Sets the "printer-state-message" attribute and adds the specified message to the current ErrorLog using the "warning" log level.

## ENVIRONMENT VARIABLES
The following environment variables are defined by the CUPS server when executing the filter:

CHARSET

The default text character set, typically "utf-8".

CLASS

When a job is submitted to a printer class, contains the name of the destination printer class. Otherwise this environment variable will not be set.

CONTENT_TYPE

The MIME media type associated with the submitted job file, for example "application/postscript".

CUPS_CACHEDIR

The directory where semi-persistent cache files can be found and stored.

CUPS_DATADIR

The directory where data files can be found.

CUPS_FILETYPE

The type of file being printed: "job-sheet" for a banner page and "document" for a regular print file.

CUPS_MAX_MESSAGE

The maximum size of a message sent to stderr, including any leading prefix and the trailing newline.

CUPS_SERVERROOT

The root directory of the server.

FINAL_CONTENT_TYPE

The MIME media type associated with the output destined for the printer, for example "application/vnd.cups-postscript".

LANG

The default language locale (typically C or en).

PATH

The standard execution path for external programs that may be run by the filter.

PPD

The full pathname of the PostScript Printer Description (PPD) file for this printer.

PRINTER

The name of the printer.

RIP_CACHE

The recommended amount of memory to use for Raster Image Processors (RIPs).

SOFTWARE

The name and version number of the server (typically CUPS/major.minor).

TZ

The timezone of the server.

USER

The user executing the filter, typically "lp" or "root"; consult the cups-files.conf file for the current setting.

## CONFORMING TO
While the filter interface is compatible with System V interface scripts, CUPS does not support System V interface scripts.

## NOTES
CUPS printer drivers and backends are deprecated and will no longer be supported in a future feature release of CUPS. Printers that do not support IPP can be supported using applications such as ippeveprinter(1).

CUPS filters are not meant to be run directly by the user. Aside from the legacy System V interface issues (argv[0] is the printer name), CUPS filters also expect specific environment variables and file descriptors, and typically run in a user session that (on macOS) has additional restrictions that affect how it runs. Unless you are a developer and know what you are doing, please do not run filters directly. Instead, use the cupsfilter(8) program to use the appropriate filters to do the conversions you need.

## SEE ALSO
backend(7), cups(1), cups-files.conf(5), cupsd(8), cupsfilter(8),

CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


ippevepcl

title: ippevepcl(7)

text:
# ippevepcl(7)

## NAME
ippevepcl/ps - pcl and postscript print commands for ippeveprinter

## SYNOPSIS
ippevepcl [ filename ]

ippeveps [ filename ]

## DESCRIPTION
ippevepcl and ippeveps are print commands for ippeveprinter(1). As with all print commands, these commands read either the filename specified on the command-line or from the standard input. Output is sent to the standard output. Status and progress messages are sent to the standard error.

ippevepcl prints to B&W HP PCL laser printers and supports printing of HP PCL (application/vnd.hp-pcl), PWG Raster (image/pwg-raster), and Apple Raster (image/urf) print files.

ippeveps print to Adobe PostScript printers and supports printing of PDF (application/pdf), PostScript (application/postscript), JPEG (image/jpeg), PWG Raster (image/pwg-raster), and Apple Raster (image/urf) print files. Printer-specific commands are read from a supplied PPD file. If no PPD file is specified, generic commands suitable for any Level 2 or Level 3 PostScript printer are used instead to specify duplex printing and media size.

## EXIT STATUS
These programs return 1 on error and 0 on success.

## ENVIRONMENT
These program inherit the environment provided by the ippeveprinter program.

## SEE ALSO
ippeveprinter(8)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


notifier

title: notifier(7)

summary: cups notification interface

text:
# notifier(7)

## NAME
notifier - cups notification interface

## SYNOPSIS
notifier recipient [ user-data ]

## DESCRIPTION
The CUPS notifier interface provides a standard method for adding support for new event notification methods to CUPS. Each notifier delivers one or more IPP events from the standard input to the specified recipient.

Notifiers MUST read IPP messages from the standard input using the ippNew() and ippReadFile() functions and exit on error. Notifiers are encouraged to exit after a suitable period of inactivity, however they may exit after reading the first message or stay running until an error is seen. Notifiers inherit the environment and can use the logging mechanism documented in filter(7).

## SEE ALSO
cupsd(8), filter(7), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


custodia

package: custodia

title: custodia(7)

text:
# custodia(7)

## NAME
custodia

## DESCRIPTION
Custodia is a modular and pluggable Secrets Manager. It allows to serve retrieve, manage and store secrets for other applications. It is useful for distributed, stateless applications that use an image file base approach for instantiation like container based images. But it is also useful to manage distribution of key material across a multiple machines over a network.


dconf

package: dconf

title: dconf(7)

summary: A configuration system

text:
# dconf(7)

## NAME
dconf - A configuration system

## DESCRIPTION
dconf is a simple key/value storage system that is heavily optimised for reading. This makes it an ideal system for storing user preferences (which are read 1000s of times for each time the user changes one). It was created with this usecase in mind.

All preferences are stored in a single large binary file. Layering of preferences is possible using multiple files (ie: for site defaults). Lock-down is also supported. The binary file for the defaults can optionally be compiled from a set of plain text keyfiles.

dconf has a partial client/server architecture. It uses D-Bus. The server is only involved in writes (and is not activated in the user session until the user modifies a preference). The service is stateless and can exit freely at any time (and is therefore robust against crashes). The list of paths that each process is watching is stored within the D-Bus daemon itself (as D-Bus signal match rules).

Reads are performed by direct access (via mmap) to the on-disk database which is essentially a hashtable. For this reason, dconf reads typically involve zero system calls and are comparable to a hashtable lookup in terms of speed. Practically speaking, in simple non-layered setups, dconf is less than 10 times slower than GHashTable.

Writes are assumed only to happen in response to explicit user interaction (like clicking on a checkbox in a preferences dialog) and are therefore not optimised at all. On some file systems, dconf-service will call fsync() for every write, which can introduce a latency of up to 100ms. This latency is hidden by the client libraries through a clever "fast" mechanism that records the outstanding changes locally (so they can be read back immediately) until the service signals that a write has completed.

The binary database format that dconf uses by default is not suitable for use on NFS, where mmap does not work well. To handle this common use case, dconf can be configured to place its binary database in XDG_RUNTIME_DIR (which is guaranteed to be local, but non-persistent) and synchronize it with a plain text keyfile in the users home directory.

## PROFILES
A profile is a list of configuration databases that dconf consults to find the value for a key. The user's personal database always takes the highest priority, followed by the system databases in the order prescribed by the profile.

On startup, dconf consults the DCONF_PROFILE environment variable. If set, dconf will attempt to open the named profile, aborting if that fails. If the environment variable is not set, it will attempt to open the profile named "user" and if that fails, it will fall back to an internal hard-wired configuration. dconf stores its profiles in text files. DCONF_PROFILE can specify a relative path to a file in /etc/dconf/profile/, or an absolute path (such as in a user's home directory). The profile name can only use alphanumeric characters or '_'.

A profile file might look like the following:

```
user-db:user
system-db:local
system-db:site

```

Each line in a profile specifies one dconf database. The first line indicates the database used to write changes, and the remaining lines indicate read-only databases. (The first line should specify a user-db or service-db, so that users can actually make configuration changes.)

A "user-db" line specifies a user database. These databases are found in $XDG_CONFIG_HOME/dconf/. The name of the file to open in that directory is exactly as it is written in the profile. This file is expected to be in the binary dconf database format. Note that XDG_CONFIG_HOME cannot be set/modified per terminal or session, because then the writer and reader would be working on different DBs (the writer is started by DBus and cannot see that variable).

A "service-db" line instructs dconf to place the binary database file for the user database in XDG_RUNTIME_DIR. Since this location is not persistent, the rest of the line instructs dconf how to store the database persistently. A typical line is service-db:keyfile/user, which tells dconf to synchronize the binary database with a plain text keyfile in $XDG_CONFIG_HOME/dconf/user.txt. The synchronization is bi-directional.

A "system-db" line specifies a system database. These databases are found in /etc/dconf/db/. Again, the name of the file to open in that directory is exactly as it is written in the profile and the file is expected to be in the dconf database format.

If the DCONF_PROFILE environment variable is unset and the "user" profile can not be opened, then the effect is as if the profile was specified by this file:

```
user-db:user

```

That is, the user's personal database is consulted and there are no system settings.

## KEY FILES
To facilitate system configuration with a text editor, dconf can populate databases from plain text keyfiles. For any given system database, keyfiles can be placed into the /etc/dconf/db/database.d/ directory. The keyfiles contain groups of settings as follows:

```
# Some useful default settings for our site
[system/proxy/http]
host='172.16.0.1'
enabled=true
[org/gnome/desktop/background]
picture-uri='file:///usr/local/rupert-corp/company-wallpaper.jpeg'

```

After changing keyfiles, the database needs to be updated with the dconf(1) tool.

## LOCKS
System databases can contain 'locks' for keys. If a lock for a particular key or subpath is installed into a database then no database listed above that one in the profile will be able to modify any of the affected settings. This can be used to enforce mandatory settings.

To add locks to a database, place text files in the /etc/dconf/db/database.d/locks directory, where database is the name of a system database, as specified in the profile. The files contain list of keys to lock, on per line. Lines starting with a # are ignored. Here is an example:

```
# prevent changes to the company wallpaper
/org/gnome/desktop/background/picture-uri

```

After changing locks, the database needs to be updated with the dconf(1) tool.

## PORTABILITY
dconf mostly targets Free Software operating systems. It will theoretically run on Mac OS but there isn't much point to that (since Mac OS applications want to store preferences in plist files). It is not possible to use dconf on Windows because of the inability to rename over a file that's still in use (which is what the dconf-service does on every write).

## API STABILITY
The dconf API is not particularly friendly, and is not guaranteed to be stable. Because of this and the lack of portability, you almost certainly want to use some sort of wrapper API around it. The wrapper API used by GTK+ and GNOME applications is GSettings[1], which is included as part of GLib. GSettings has backends for Windows (using the registry) and Mac OS (using property lists) as well as its dconf backend and is the proper API to use for graphical applications.

## SEE ALSO
dconf-service(1), dconf-editor(1), dconf(1), GSettings[1]

## NOTES
1.

GSettings

http://developer.gnome.org/gio/stable/GSettings.html