D -- Define Macro

Macros are named with a single character or with a word in {braces}. Single character names may be selected from the entire ASCII set, but user-defined macros should be selected from the set of upper case letters only. Lower case letters and special symbols are used internally. Long names beginning with a lower case letter or a punctuation character are reserved for use by sendmail, so user-defined long macro names should begin with an upper case letter.

The syntax for macro definitions is:

D xval
where x is the name of the macro (which may be a single character or a word in braces) and val is the value it should have. There should be no spaces given that do not actually belong in the macro value.

Macros are interpolated using the construct $ x, where x is the name of the macro to be interpolated. This interpolation is done when the configuration file is read, except in M lines. The special construct $& x can be used in R lines to get deferred interpolation.

Conditionals can be specified using the syntax:

$?x text1 $| text2 $.
This interpolates text1 if the macro $x is set, and text2 otherwise. The else ( $|) clause may be omitted.

Lower case macro names are reserved to have special semantics, used to pass information in or out of sendmail, and special characters are reserved to provide conditionals, etc. Upper case names (that is, $A through $Z) are specifically reserved for configuration file authors.

The following macros are defined and/or used internally by sendmail for interpolation into argv's for mailers or for other contexts. The ones marked * are information passed into sendmail[15], the ones marked are information passed both in and out of sendmail, and the unmarked macros are passed out of sendmail but are not otherwise used internally. These macros are:

$a
The origination date in RFC 822 format. This is extracted from the Date: line.
$b
The current date in RFC 822 format.
$c
The hop count. This is a count of the number of Received: lines plus the value of the -h command line flag.
$d
The current date in UNIX (ctime) format.
$e*
(Obsolete; use SmtpGreetingMessage option instead.) The SMTP entry message. This is printed out when SMTP starts up. The first word must be the $j macro as specified by RFC821. Defaults to $j Sendmail $v ready at $b. Commonly redefined to include the configuration version number, e.g., $j Sendmail $v/$Z ready at $b
$f
The envelope sender (from) address.
$g
The sender address relative to the recipient. For example, if $f is foo, $g will be host!foo, foo@host.domain, or whatever is appropriate for the receiving mailer.
$h
The recipient host. This is set in ruleset 0 from the $# field of a parsed address.
$i
The queue id, e.g., HAA12345.
$j
The "official" domain name for this site. This is fully qualified if the full qualification can be found. It must be redefined to be the fully qualified domain name if your system is not configured so that information can find it automatically.
$k
The UUCP node name (from the uname system call).
$l*
(Obsolete; use UnixFromLine option instead.) The format of the UNIX from line. Unless you have changed the UNIX mailbox format, you should not change the default, which is From $g $d.
$m
The domain part of the gethostname return value. Under normal circumstances, $j is equivalent to $w.$m.
$n*
The name of the daemon (for error messages). Defaults to MAILER-DAEMON.
$o*
(Obsolete: use OperatorChars option instead.) The set of "operators" in addresses. A list of characters which will be considered tokens and which will separate tokens when doing parsing. For example, if @ were in the $o macro, then the input a@b would be scanned as three tokens: a, @, and b. Defaults to .:@[], which is the minimum set necessary to do RFC 822 parsing; a richer set of operators is .:%@!/[], which adds support for UUCP, the %-hack, and X.400 addresses.
$p
Sendmail's process id.
$q*
Default format of sender address. The $q macro specifies how an address should appear in a message when it is defaulted. Defaults to <$g>. It is commonly redefined to be $?x$x <$g>$|$g$. or $g$?x ($x)$., corresponding to the following two formats:
Eric Allman <eric@CS.Berkeley.EDU>
eric@CS.Berkeley.EDU (Eric Allman)
Sendmail properly quotes names that have special characters if the first form is used.
$r
Protocol used to receive the message. Set from the -p command line flag or by the SMTP server code.
$s
Sender's host name. Set from the -p command line flag or by the SMTP server code.
$t
A numeric representation of the current time.
$u
The recipient user.
$v
The version number of the sendmail binary.
$w
The hostname of this site. This is the root name of this host (but see below for caveats).
$x
The full name of the sender.
$z
The home directory of the recipient.
$_
The validated sender address.

There are three types of dates that can be used. The $a and $b macros are in RFC 822 format; $a is the time as extracted from the Date: line of the message (if there was one), and $b is the current date and time (used for postmarks). If no Date: line is found in the incoming message, $a is set to the current time also. The $d macro is equivalent to the $b macro in UNIX (ctime) format.

The macros $w, $j, and $m are set to the identity of this host. Sendmail tries to find the fully qualified name of the host if at all possible; it does this by calling gethostname(2) to get the current hostname and then passing that to gethostbyname(3) which is supposed to return the canonical version of that host name.[16] Assuming this is successful, $j is set to the fully qualified name and $m is set to the domain part of the name (everything after the first dot). The $w macro is set to the first word (everything before the first dot) if you have a level 5 or higher configuration file; otherwise, it is set to the same value as $j. If the canonification is not successful, it is imperative that the config file set $j to the fully qualified domain name[17].

The $f macro is the id of the sender as originally determined; when mailing to a specific host the $g macro is set to the address of the sender relative to the recipient. For example, if I send to bollard@matisse.CS.Berkeley.EDU from the machine vangogh.CS.Berkeley.EDU the $f macro will be eric and the $g macro will be eric@vangogh.CS.Berkeley.EDU.

The $x macro is set to the full name of the sender. This can be determined in several ways. It can be passed as flag to sendmail. It can be defined in the environment variable. The third choice is the value of the Full-Name: line in the header if it exists, and the fourth choice is the comment field of a From: line. If all of these fail, and if the message is being originated locally, the full name is looked up in the /etc/passwd file.

When sending, the $h, $u, and $z macros get set to the host, user, and home directory (if local) of the recipient. The first two are set from the $@ and $: part of the rewriting rules, respectively.

The $p and $t macros are used to create unique strings (e.g., for the Message-Id: field). The $i macro is set to the queue id on this host; if put into the timestamp line it can be extremely useful for tracking messages. The $v macro is set to be the version number of sendmail; this is normally put in timestamps and has been proven extremely useful for debugging.

The $c field is set to the hop count, i.e., the number of times this message has been processed. This can be determined by the -h flag on the command line or by counting the timestamps in the message.

The $r and $s fields are set to the protocol used to communicate with sendmail and the sending hostname. They can be set together using the -p command line flag or separately using the -M or -oM flags.

The $_ is set to a validated sender host name. If the sender is running an RFC 1413 compliant IDENT server and the receiver has the IDENT protocol turned on, it will include the user name on that host.


[Contents] [Previous] [Next]


Questions or problems regarding this web site should be directed to Steve Gielda.
Copyright 1999 www.cotse.com.  All rights reserved.
Last modified: Friday April 02, 1999.