DIAL(2)                                                   DIAL(2)

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

     SYNOPSIS
          #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)

          void  setnetmtpt(char *to, int tolen, char *from)

          NetConnInfo*  getnetconninfo(char *conndir, int fd)

          void freenetconninfo(NetConnInfo*)

     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, which 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,
          including terminating NUL, is guaranteed to fit in
          `NETPATHLEN' (40) bytes.  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 ip(3) for messages that can be written to the

     DIAL(2)                                                   DIAL(2)

          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 par-
          allel all addresses on networks in common between source and
          destination 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 con-
          tains the address called.  If the network allows the local
          address to be set, as is the case with UDP and TCP port num-
          bers, 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 netaddr used
          in announce may be a local address or an asterisk, to indi-
          cate all local addresses, e.g.  tcp!*!echo.  The listen rou-
          tine 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 received by listen, while reject refuses the
          call because of cause. Accept returns a file descriptor for
          the data file opened ORDWR.

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

          Getnetconninfo returns a structure containing information
          about a network connection.  The structure is:
            typedef struct NetConnInfo NetConnInfo;
            struct NetConnInfo
            {
               char *dir;          /* connection directory */
               char *root;         /* network root */
               char *spec;         /* binding spec */
               char *lsys;         /* local system */
               char *lserv;        /* local service */
               char *rsys;         /* remote system */
               char *rserv;        /* remote service */
               char *laddr;        /* local address */
               char *raddr;        /* remote address */
            };

     DIAL(2)                                                   DIAL(2)

          The information is obtained from the connection directory,
          conndir. If conndir is nil, the directory is obtained by
          performing fd2path(2) on fd. Getnetconninfo returns either a
          completely specified structure, or nil if either the struc-
          ture can't be allocated or the network directory can't be
          determined.  The structure is freed using freenetconninfo.

          Setnetmtpt copies the name of the network mount point into
          the buffer to, whose length is tolen. It exists to merge two
          pre-existing conventions for specifying the mount point.
          Commands that take a network mount point as a parameter
          (such as dns, cs (see ndb(8)), and ipconfig(8)) should now
          call setnetmtpt. If from is nil, the mount point is set to
          the default, /net.  If from points to a string starting with
          a slash, the mount point is that path.  Otherwise, the mount
          point is the string pointed to by from appended to the
          string /net.  The last form is obsolete and is should be
          avoided.  It exists only to aid in conversion.

     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 TCP/IP and loop forever receiving
          calls and echoing back to the caller anything sent:

               int
               bekremvax(void)
               {
                    int dfd, acfd, lcfd;
                    char adir[NETPATHLEN], ldir[NETPATHLEN];
                    int n;
                    char buf[256];

                    acfd = announce("tcp!*!7", adir);
                    if(acfd < 0)
                         return -1;
                    for(;;){
                         /* listen for a call */
                         lcfd = listen(adir, ldir);

     DIAL(2)                                                   DIAL(2)

                         if(lcfd < 0)
                              return -1;
                         /* fork a process to echo */
                         switch(fork()){
                         case -1:
                              perror("forking");
                              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;
                         }
                    }
               }

     SOURCE
          /sys/src/libc/9sys, /sys/src/libc/port

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

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