term% ls -F
term% cat index.txt
DIAL(2)                       System Calls Manual                      DIAL(2)

       dial,  hangup,  announce,  listen, accept, reject, netmkaddr - make and
       break network connections

       #include <u.h>
       #include <libc.h>

       int   dial(char *addr, char *local, char *dir, int *cfdp)

       int   hangup(int ctl)

       int   announce(char *addr, char *dir)

       int   listen(char *dir, char *newdir)

       int   accept(int ctl, char *dir)

       int   reject(int ctl, char *dir, char *cause)

       char* netmkaddr(char *addr, char *defnet, char *defservice)

       For these routines, addr is a network address of the  form  network!ne‐
       taddr!service,  network!netaddr, or simply netaddr.  Network is any di‐
       rectory listed in /net or the special token, net.  Net is a free  vari‐
       able  that  stands for any network in common between the source and the
       host netaddr.  Netaddr can be a host name, a domain name, a network ad‐
       dress,  or  a  meta-name  of  the form $attribute, which is replaced by
       value from the value-attribute pair attribute=value most closely  asso‐
       ciated with the source host in the network data base (see ndb(6)).

       If  a  connection  attempt  is successful and dir is non-zero, the path
       name of a line directory that has files for accessing the connection is
       copied  into dir.  The path name is guaranteed to be less than 40 bytes
       long.  One line directory exists for  each  possible  connection.   The
       data  file in the line directory should be used to communicate with the
       destination.  The ctl file in the line directory can be  used  to  send
       commands  to  the  line.   See dk(3) and 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.

       Dial makes a call to destination addr on a multiplexed network.  If the
       network in addr is net, dial will try in  succession  all  networks  in
       common  between  source  and destination until a call succeeds.  It re‐
       turns a file descriptor open for reading and writing the data  file  in
       the  line  directory.  The addr file in the line directory contains the
       address called.  If the network allows the local address to be set,  as
       is  the  case with UDP and TCP port numbers, and local is non-zero, the
       local address will be set to local.  If cfdp is non-zero, *cfdp is  set
       to a file descriptor open for reading and writing the control file.

       Hangup  is  a  means of forcing a connection to hang up without closing
       the ctl and data files.

       Announce and listen are the complements of dial.  Announce  establishes
       a network name to which calls can be made.  Like dial, announce returns
       an open ctl file.  The listen routine takes as its first  argument  the
       dir of a previous announce.  When a call is received, listen returns an
       open ctl file for the line the call was received on.  It sets newdir to
       the  path  name  of  the new line directory.  Accept accepts a call re‐
       ceived by listen, while reject refuses the call because of cause.   Ac‐
       cept returns a file descriptor for the data file opened ORDWR.

       Netmkaddr  makes  an  address  suitable  for dialing or announcing.  It
       takes an address along with a default network and  service  to  use  if
       they  are not specified in the address.  It returns a pointer to static
       data holding the actual address to use.

       Make a call and return an open file descriptor to  use  for  communica‐

              int callkremvax(void)
                   return dial("kremvax", 0, 0, 0);

       Call the local authentication server:

              int dialauth(char *service)
                   return dial(netmkaddr("$auth", 0, service), 0, 0, 0);

       Announce  as  kremvax  on  Datakit and loop forever receiving calls and
       echoing back to the caller anything sent:

                   int dfd, acfd, lcfd;
                   char adir[40], ldir[40];
                   int n;
                   char buf[256];

                   afd = announce("dk!kremvax", adir);
                   if(afd < 0)
                        return -1;
                        /* listen for a call */
                        lcfd = listen(adir, ldir);
                        if(lcfd < 0)
                             return -1;
                        /* fork a process to echo */
                        case -1:
                        case 0:
                             /* accept the call and open the data file */
                             dfd = accept(lcfd, ldir);
                             if(dfd < 0)
                                  return -1;

                             /* echo until EOF */
                             while((n = read(dfd, buf, sizeof(buf))) > 0)
                                  write(dfd, buf, n);


       auth(2), dk(3), ip(3), stream(3), ndb(8)

       Dial, announce, and listen return -1 if they fail.  Hangup returns non‐
       zero if it fails.