B. Host Status File Internals

Contents:
Status file lines

"Persistent host status" is described under, and enabled with, the HostStatusDirectory option (see Section 34.8.31, HostStatusDirectory). The format for each directory created by that option, as of V\*[sendmail_version] sendmail, looks like this:

HostStatusDirectory/domain./subdomain./host

That is, the canonical name of the host whose status is being stored is divided into components based on the separating dots in its name. The dot for each component, is moved to the end of each component and all but the host part are created as directories.

To illustrate, consider the following canonical name:

here.uofa.edu

If the HostStatusDirectory option were declared like this:

O HostStatusDirectory=/tmp/.hoststat

the status for the host here.uofa.edu would be stored in the file:

/tmp/.hoststat/edu./uofa./here

B.1 Status file lines

The format of the status file (in the above case here) is one item of information per line, where each line begins with a key letter:

letterwhat

The complete list of key letters is shown in Table 38.3.

Table B.1: Host Status File Key Letters
Letter	Version	Description
D	V8.8 and above	The DSN status text
E	V8.8 and above	The UNIX error number
H	V8.8 and above	The DNS error number
R	V8.8 and above	The SMTP status-code text
S	V8.8 and above	The UNIX exit(2) status
U	V8.8 and above	The time last used
V	V8.8 and above	The version of this status file
.	V8.8 and above	The end of file marker

In the sections that follow, we describe each key letter in alphabetical order, rather than in the order in which they will appear in the status file.

Note that not all these lines are printed with the hoststat(1) command (see Section 36.1.1, "hoststat (V8.8 and Above)"). As of \*[sendmail_version], only the information in the E, R, and U lines is printed.

Also note that the letters that are used and the meaning of each are essentially internal to sendmail and are subject to change without notice.

B.1.1 D line

The DSN status text

(V8.8 and above)

Delivery Status Notification (DSN) gives the status of a returned message in its Status: MIME-body header (see RFC1892). That status is formed from three digits, each separated from the others by a dot, for example:
5.0.1
The meaning of each digit is documented in RFC1893. This D line stores that status as text.

B.1.2 E line

The UNIX error number

(V8.8 and above)

When delivery or a connection fails because of a system error, that error is stored in the E line. Such errors are integer values as defined in <errno.h>. If there was no error, the value stored in this line is a zero.

B.1.3 H line

The DNS error number

(V8.8 and above)

Some connection problems are caused by errors in looking up hosts with the Domain Name System (DNS). The software that provides lookups provides its own set of errors (see <arpa/nameser.h>). If a DNS error occurs, it is stored in this H line as an integer value.

B.1.4 R line

The SMTP status-code text

(V8.8 and above)

The Simple Mail Transfer Protocol (SMTP) specifies that all errors be prefixed with three-digit codes. The meaning of all the three-digit codes is given in RFC821 and several newer RFCs.
The R line stores this three-digit code as text. If there is no code (as when there is a system error instead of an SMTP error), the text is a lone hyphen.

B.1.5 S line

The UNIX exit(2) status

(V8.8 and above)

All UNIX programs return a success or failure value to the program that executed them. These values are called exit(2) values and they may or may not correspond to standard values. The set of values that is understood by sendmail is defined in <sysexits.h>.
This S line stores the integer value that was returned by a delivery agent program. Such programs might be called to deliver SMTP network mail.

B.1.6 U line

The last time used

(V8.8 and above)

Each time connection is made to, or fails to be made to, a host, its persistent status is updated. The date and time of the last update are stored in the U line.
The date and time are represented as an unsigned long and are stored in the U line as a text representation of that value.

B.1.7 V line

The version of this status file

(V8.8 and above)

For V8.8 sendmail this is version 0. If any other version is stored in this V line, sendmail logs the following error:
Unknown host status version bad: 0 max
This is always the first line of the file.

B.1.8 . line

The end of file marker

(V8.8 and above)

A dot on a line by itself indicates the end of the host status file's information. On systems that don't support the ftruncate(2) call, additional data may appear after this line. Since this line marks the end of information, any such extra data will be ignored.


A. The client.cf File		C. The Berkeley DB Database