man(1) Manual page archive


     DIAL(2)                                                   DIAL(2)

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

     SYNOPSIS
          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 *dir)

          int  accept(int ctl, char *dir)

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

          char*     netmkaddr(char *addr, char *defnet, char *defser-
          vice)

     DESCRIPTION
          For these routines, addr is a network address of the form
          network!netaddr!service, network!netaddr, or simply netaddr.
          Network is any directory listed in /net or the special
          token, net.  Net is a free variable that stands for any net-
          work in common between the source and the host netaddr.
          Netaddr can be a host name, a domain name, a network
          address, or a meta-name of the form $attribute.  $attribute
          is replaced by value from the value-attribute pair
          attribute=value most closely associated 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 access-
          ing the connection is copied into dir. The path name is
          guaranteed to be less than 40 bytes long.  One line direc-
          tory 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 mes-
          sages 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 net-
          work.  If the network in addr is net, dial will try in suc-
          cession all networks in common between source and destina-
          tion until a call succeeds.  It returns 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

     DIAL(2)                                                   DIAL(2)

          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 dir to the path
          name of the new line directory.  Accept accepts a call
          received by listen, while reject refuses the call because of
          cause. Accept returns a file descriptor for the data file
          opened ORDWR .

          Netmkaddr make an address suitable for dialing or announc-
          ing.  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.

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

               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
               bekremvax(void)
               {
                    int dfd, acfd, lcfd;
                    char adir[40], ldir[40];
                    int n;
                    char buf[256];

     DIAL(2)                                                   DIAL(2)

                    afd = announce("dk!kremvax", adir);
                    if(afd < 0)
                         return -1;

                    for(;;){
                         /* listen for a call */
                         lcfd = listen(adir, ldir);
                         if(lcfd < 0)
                              return -1;

                         /* fork a process to echo */
                         switch(fork()){
                         case -1:
                              perror("forking0);
                              close(lcfd);
                              break;
                         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);
                              exits(0);
                         default:
                              close(lcfd);
                              break;
                         }

                    }
               }

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

     DIAGNOSTICS
          Dial, announce, and listen return -1 if they fail.  Hangup
          returns nonzero if it fails.