[Top] [Prev] [Next]

dial, announce, export, listen - make network connections

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;


These routines establish network connections.

dial (addr, local)

The dial function establishes a connection to destination addr.

The addr Argument

The address must be of the form:


For more information about the structure of this address, see Request Format in Chapter 6

The Connection Server

If the connection server is running, the dial function will pass addr to that daemon for the translation of host names, symbolic service names, and so on, to addresses of the designated network (the first component). See cs - connection server daemon for description of the supported conversion.

If the connection server daemon is not running, the dial function silently skips the translation stage and attempts to open a network connection with addr as received.

The cs daemon is accessed by an interface file also called cs. The dial function looks for this file in the following directories in the OR'ed listed:

  1. A directory named in an optional prefix to the addr argument. The format in such cases is: /dir/network!destination!serviceport
  2. The /net directory
  3. The /net.alt directory. If the connection server returns several network addresses for the named destination, the dial function tries each in the order received until a connection is made.

The local Argument

If the network allows the local address to be set, and local is non-empty, the local address will be set to local. For IP, local addresses correspond to the port number.

At the completion of dial, local can be read from the local file of the network interface.

The Return Values

The dial function returns a tuple consisting of an integer and a Connection adt.

On failure, the dial function returns -1 in the integer portion of the tuple.

On success, the members of the returned Connection adt have been initialized to the following values:

The pathname to the directory containing the network interface files for the connection. For example, /net/tcp/5.


A file descriptor to the data file of the connection. This is used to read and write data to the destination.


A file descriptor for the ctl file of the connection. Commands can be sent to this file to control the connection.

See the appropriate Network device pages (for example, ip - TCP, UDP network protocols over IP in Chapter 2) for further details of using this interface.

announce (addr)

The announce function and the listen function described in this section are the complements of the dial function. Their actions allow completion of connection requests from clients using the dial function.

The Argument, addr

The announce function establishes a network name (service port) to which incoming calls can be made. The format of the addr, the single argument is:


The localname component is translated (if possible) by the connection server. The result is stored in the local file of the network interface. That file can be used for display purposes. The localname value is not used by the underlying network. The setting of local file is skipped if localname is'*'.

The Connection Server

The announce function uses the connection server to translate any symbolic components of the argument to values acceptable to the network. See the cs daemon for a description of the supported translations.

The cs daemon is accessed by an interface file also called cs. The announce function looks for that file in two directories in the following order:

  1. A directory named in an optional prefix to the addr argument. The format in such cases is: /dir/network!*!serviceport
  2. The /net directory

The Return Value

The return value of the announce function follows the same conventions as used by the dial function. If the call succeeds, the returned Connection adt can be used as an argument to the listen function.


The listen function allows the completion of a connection to a process calling the dial function.


The listen function takes as its only argument the Connection adt of a successful call to announce.

Return Values

The return values from the listen function have the same form as those returned from the dial function.

When a call is received, listen includes an open Connection adt that leads to a network interface file. The data file of that interface is cross connected (read-to-write and write-to-read) to the data file associated with the Connection adt returned by the dial function to the client process.

export (fd, flag)

The export function responds to client requests for file operations on the server's file name space. This is the server end of a client's mount call.


Requests for pathname resolution occur relative to the current root directory of the process calling export. That process can control the set of files available for mounts requests by clients by defining the root directory of its name space using the operations described on the bind page.


The export functions first argument is the dfd member of a Connection returned from listen on service port stags.

The export function can take two mutually exclusive flags

The export function blocks until all client requests are complete.


Client requests are handled by a background thread, while export returns immediately


Return Values

The export function returns 0 on success and -1 on failure.


Make a call and return an open file descriptor to use for communications:

callkremvax( ): (int, Connection)
    return sys->dial("tcp!kremvax!mpeg", nil);

Call the local authentication server:

dialauth(service: string): (int, Connection) { return sys->dial("net!$SIGNER!inflogin", nil); }

See Also
bind, mount, unmount - change file name space

cs - connection server daemon in Chapter 6

[Top] [Prev] [Next]

Copyright © 1996,Lucent Technologies, Inc. All rights reserved.