SYS-DIAL(2) SYS-DIAL(2)
NAME
announce, dial, export, 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);
export: fn(fd: ref FD, flag: int): int;
DESCRIPTION
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 spe-
cial token, net. The name net acts as a free vari-
able that stands for any network in common between
the source and netaddr. A network name can be pre-
ceded by the full path name of a directory of net-
works, 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 corresponding 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 destination machine has several
interfaces, cs will return them all. In particular, if addr
is net, cs will return addresses on all networks that are
Page 1 Plan 9 (printed 11/17/24)
SYS-DIAL(2) SYS-DIAL(2)
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; second, 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 connec-
tion, and read and written to communicate with the destina-
tion. 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 mul-
tiplexed network. 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 num-
bers, 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 struc-
ture in which only the cfd descriptor is open, on the con-
trol 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.
Export receives and replies to Styx requests from a client
via fd, for file operations on the current file name space,
which is thus exported. This is the server end of the
client's mount call. Names are interpreted relative to the
root of the name space, which can be adjusted using sys-
pctl(2) and sys-bind(2) before export. The file descriptor
fd must be open for reading and writing, and neither mounted
Page 2 Plan 9 (printed 11/17/24)
SYS-DIAL(2) SYS-DIAL(2)
elsewhere or already exported. Typically export's first
argument is a file descriptor open on the data file in the
dir of a Connection returned by listen. The export function
takes two mutually exclusive flags:
Sys->EXPWAIT
Export blocks until all client requests are complete.
Sys->EXPASYNC
Client requests are handled by a background (kernel)
process. Export returns immediately. The serving pro-
cess terminates when the client hangs up.
EXAMPLES
Make a call and return an open file descriptor to use for
communications:
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/inferno.c
/emu/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 compo-
nent of the tuple returned by the other functions follows
the same convention.
BUGS
Note that listen does not open the data file.
Page 3 Plan 9 (printed 11/17/24)