A line beginning with white space continues the preceding line. Anything following `#' on an input line is ignored.

A list of host-to-host connections consists of a ``from'' host in column 1, followed by white space, followed by a comma-separated list of ``to' hosts, called links. A link may be preceded or followed by a network character to use in the route. Valid network characters are `!' (default), `@', `:', and `%'. A link (and network character, if present) may be followed by a ``cost'' enclosed in parentheses. Costs may be arbitrary arithmetic expressions involving numbers, parentheses, `+', `-', `*', and `/'. Negative costs are prohibited. The following symbolic costs are recognized:

LOCAL	25	(local-area network connection)
DEDICATED	95	(high speed dedicated link)
DIRECT	200	(toll-free call)
DEMAND	300	(long-distance call)
HOURLY	500	(hourly poll)
EVENING	1800	(time restricted call)
DAILY	5000	(daily poll, also called POLLED)
WEEKLY	30000	(irregular poll)

In addition, DEAD is a very large number (effectively infinite), HIGH and LOW are -5 and +5 respectively, for baud-rate or quality bonuses/penalties, and FAST is -80, for adjusting costs of links that use high-speed (9.6 Kbaud or more) modems. These symbolic costs represent an imperfect measure of bandwidth, monetary cost, and frequency of connections. For most mail traffic, it is important to minimize the number of hosts in a route, thus, e.g., HOURLY * 24 is much larger than DAILY. If no cost is given, a default of 4000 is used.

For the most part, arithmetic expressions that mix symbolic constants other than HIGH, LOW, and FAST make no sense. E.g., if a host calls a local neighbor whenever there is work, and additionally polls every evening, the cost is DIRECT, not DIRECT+EVENING.

Some examples:

down	princeton!(DEDICATED), tilt,
	%thrash(LOCAL)
princeton	topaz!(DEMAND+LOW)
topaz	@rutgers(LOCAL+1)

If a link is encountered more than once, the least-cost occurrence dictates the cost and network character. Links are treated as bidirectional but asymmetric: for each link declared in the input, a DEAD reverse link is assumed.

If the ``to'' host in a link is surrounded by angle brackets, the link is considered terminal, and further links beyond this one are heavily penalized. E.g., with input

seismo	<research>(10), research(1), ihnp4(1)
research	allegra(1)
ihnp4	allegra(5)

the path from seismo to research is direct, but the path from seismo to allegra uses ihnp4 as a relay, not research.

The set of names by which a host is known to its neighbors is called its aliases. Aliases are declared as follows:

name = alias, alias ...

The name used in the route to or through aliased hosts is the name by which the host is known to its predecessor in the route.

Fully connected networks, such as the ARPANET or a local-area network, are declared as follows:

net = {host, host, ...}

The host-list may be preceded or followed by a routing character (`!' default), and may be followed by a cost (default 4000). The network name is optional; if not given, pathalias makes one up.

etherhosts = {rahway, milan, joliet}!(LOCAL)
ringhosts = @{gimli, alida, almo}(DEDICATED)
= {etherhosts, ringhosts}(0)

The routing character used in a route to a network member is the one encountered when ``entering'' the network. See also the sections on gateways and domains .

Connection data may be given while hiding host names by declaring

private {host, host, ...}

Pathalias will not generate routes for private hosts, but may produce routes through them. The scope of a private declaration extends from the declaration to the end of the input file in which it appears, or to a private declaration with an empty host list, whichever comes first. The latter scope rule offers a way to retain the semantics of private declarations when reading from the standard input.

Dead hosts, links, or networks may be presented in the input stream by declaring

dead {arg, ...}

where arg has the same form as the argument to the -d option.

To force a specific cost for a link, delete all prior declarations with

delete {host-1!host-2}

and declare the link as desired. To delete a host and all its links, use

delete {host}

Error diagnostics refer to the file in which the error was found. To alter the file name, use

file {filename}

Fine-tuning is possible by adjusting the weights of all links from a given host, as in

adjust {host-1, host-2(LOW), host-3(-1)}

If no cost is given a default of 4000 is used.

Input from compressed (and uncompressed) files can be piped into pathalias with the following script.

for i in $*; do
	case $i in
	*.Z)	echo "file {`expr $i : '\(.*\).Z'`}"
		zcat $i ;;
	*)	echo "file {$i}"
		cat $i ;;
	esac
	echo "private {}"
done | pathalias

A list of host-route pairs is written to the standard output, where route is a string appropriate for use with printf(3), e.g.,

rutgers	princeton!topaz!%s@rutgers

The ``%s'' in the route string should be replaced by the user name at the destination host. (This task is normally performed by a mailer.)

Except for domains, the name of a network is never used in routes. Thus, in the earlier example, the path from down to up would be ``up!%s,'' not ``princeton-ethernet!up!%s.''

A network is represented by a pseudo-host and a set of network members. Links from the members to the network have the weight given in the input, while the cost from the network to the members is zero. If a network is declared dead, the member-to-network links are marked dead, which effectively prohibits access to the network from its members.

However, if the input also shows an explicit link from any host to the network, then that host can be used as a gateway. (In particular, the gateway need not be a network member.)

E.g., if CSNET is declared dead and the input contains

CSNET = {...}
csnet-relay	CSNET

then routes to CSNET hosts will use csnet-relay as a gateway.

A network whose name begins with `.' is called a domain. Domains are presumed to require gateways, i.e., they are DEAD. The route given by a path through a domain is similar to that for a network, but here the domain name is tacked onto the end of the next host. Subdomains are permitted.

E.g.,

harvard	.EDU	# harvard is gateway to .EDU domain
.EDU	= {.BERKELEY, .UMICH}
.BERKELEY	= {ernie}

yields

ernie	...!harvard!ernie.BERKELEY.EDU!%s

Output is given for the nearest gateway to a domain, e.g., the example above gives

.EDU	...!harvard!%s

Output is given for a subdomain if it has a different route than its parent domain, or if all its ancestor domains are private.

If the -D option is given on the command line, pathalias treats a link from a domain to a host member of that domain as terminal. This property extends to host members of subdomains, etc, and discourages routes that use any domain member as a relay.

Makedb builds a dbm(3) database from the standard input or from the named files. Input is expected to be sequence of ASCII records, each consisting of a key field and a data field separated by a single tab. If the tab is missing, the data field is assumed to be empty.