SYS-DIAL(2)SYS-DIAL(2)NAME
announce, dial, listen - make network connections
SYNOPSIS
include "sys.m";
sys := load Sys Sys->PATH;
Connection: adt
{
dfd: ref FD; # data file
cfd: ref FD; # control file
dir: string; # pathname of line directory
};
announce: fn(addr: string): (int, Connection);
dial: fn(addr, local: string): (int, Connection);
listen: fn(c: Connection): (int, Connection);
DESCRIPTION
These routines in the Sys module are still used by some existing code.
They are deprecated, and new applications should use the Dial module
described in dial(2).
These routines establish network connections. Their description uses
the following definitions:
addr is a network address in one of the following forms:
network!netaddr!service
network!netaddr
netaddr
network
Any directory listed in /net (eg, tcp), or the special token,
net. The name net acts as a free variable that stands for any
network in common between the source and netaddr. A network
name can be preceded by the full path name of a directory of
networks, using the form /dir/network (eg, /net.alt/tcp).
netaddr
A host name, a domain name, a network address, or a meta-name of
the form $attribute, which is replaced by value from the corre‐
sponding attribute-value pair in the connection server data base
(see db(6)).
The functions dial and announce translate a given addr to an actual
network address using the connection server cs(8). If a logical name
addr corresponds to several network addresses, for instance if a desti‐
nation machine has several interfaces, cs will return them all. In
particular, if addr is net, cs will return addresses on all networks
that are common to source and destination. The translation procedure
accesses cs using its interface file cs, which is sought as follows:
first, in an explicit directory /dir if one was given in network; sec‐
ond, in the standard directory /net; and finally in the directory
/net.alt (dial only). If the connection server cannot be found, the
addr is used as-is.
If a connection attempt is successful, the dir member of the resulting
Connection will be the path name of a line directory that has files for
accessing the connection. One line directory exists for each possible
connection. The data file in the line directory is opened to make a
connection, and read and written to communicate with the destination.
The ctl file in the line directory can be used to send commands to the
line. See ip(3) for messages that can be written to the ctl file. The
last close of the data or ctl file will close the connection. The
remote file in the line directory contains the address called; the file
local contains the local address assigned.
The dial routine makes a call to destination addr on a multiplexed net‐
work. If the connection server returns several addresses, dial tries
each in turn, until a connection is made or no addresses remain to be
tried. It returns a Connection containing a file descriptor dfd open
for reading and writing the data file in the line directory, and a file
descriptor cfd open for reading and writing the ctl file. If local is
non-empty, and the network allows the local address to be set, as is
the case with UDP and TCP port numbers, the local address will be set
to local.
Announce and listen are the complements of dial. Announce establishes
a network name to which incoming calls can be made. In addr, netaddr
gives the name or address of one of the local host's interfaces on
which to listen for calls to the given service; it can be * to listen
for calls on any interface on network. Announce returns a Connection
structure in which only the cfd descriptor is open, on the control file
representing the announcement. Listen takes as its only argument the
Connection structure of a successful call to announce. When a call is
received, listen returns an open Connection structure as if from dial,
except that only the cfd descriptor is open, dfd is nil, and the caller
must open the data file for itself.
EXAMPLES
Make a call and return an open file descriptor to use for communica‐
tions:
callkremvax(): (int, Connection)
{
return sys->dial("tcp!kremvax!80", nil);
}
Call the local certificate signer:
dialsigner(service: string): (int, Connection)
{
return sys->dial("net!$SIGNER!inflogin", nil);
}
SOURCE
/emu/port/inferno.c
/emu/port/dial.c
/os/port/inferno.c
/os/port/dial.c
DIAGNOSTICS
The integer valued functions return 0 on success and -1 on error; the
system error string is set. The integer component of the tuple
returned by the other functions follows the same convention.
BUGS
Note that listen does not open the data file.
SYS-DIAL(2)
