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 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 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 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 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 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 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. 

­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 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 process 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 component of the tuple returned by the other functions follows the same convention. 

BUGS

Note that ­listen does not open the ­data file. 

Plan 9  —  June 29, 2000