DIAL(3)                                                   DIAL(3)

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

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

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

          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)

          NetConnInfo*  getnetconninfo(char *dir, int fd)

          void freenetconninfo(NetConnINfo*)

          int   dialparse(char *addr, char **net, char **unix,
                    u32int *host, int *port)

     DESCRIPTION
          For these routines, addr is a network address of the form
          network!netaddr!service, network!netaddr, or simply netaddr.
          Network is tcp, udp, unix, or the special token, net.  Net
          is a free variable that stands for any network in common
          between the source and the host netaddr. Netaddr can be a
          host name, a domain name, or a network address.

          On Plan 9, the dir argument is a path name to a line
          directory that has files for accessing the connection.  To
          keep the same function signatures, the Unix port of these
          routines uses strings of the form /dev/fd/n instead of line
          directory paths.  These strings should be treated as opaque
          data and ignored.

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

     DIAL(3)                                                   DIAL(3)

          address will be set to local. Dial's dir and cfdp arguments
          are not supported and must be zero.

          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.

          Netmkaddr also translates Unix conventions into Plan 9 syn-
          tax.  If addr is the name of a local file or Unix domain
          socket, netmkaddr will return unix!addr.  If addr is of the
          form host:port, netmkaddr will return net!host!port.

          Dialparse parses a network address as described above into a
          network name, a Unix domain socket address, an IPv4 host
          address, and an IPv4 port number.

          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 */
            };

          The information is obtained from the `line directory' dir,
          or if dir is nil, from the connection file descriptor fd.
          Getnetconninfo returns either a completely specified struc-
          ture, or nil if either the structure can't be allocated or

     DIAL(3)                                                   DIAL(3)

          the network directory can't be determined.  The structure is
          freed using freenetconninfo.

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

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

          Connect to a Unix socket served by acme(4):

               int dialacme(void)
               {
                    return dial("unix!/tmp/ns.ken.:0/acme", 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[40], ldir[40];
                    int n;
                    char buf[256];

                    acfd = announce("tcp!*!7", adir);
                    if(acfd < 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("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)

     DIAL(3)                                                   DIAL(3)

                                   write(dfd, buf, n);
                              exits(0);
                         default:
                              close(lcfd);
                              break;
                         }
                    }
               }

     SOURCE
          /src/lib9/dial.c
          /src/lib9/announce.c
          /src/lib9/_p9dialparse.c
          /src/lib9/getnetconn.c

     DIAGNOSTICS
          Dial, announce, and listen return -1 if they fail.

     BUGS
          To avoid name conflicts with the underlying system, dial,
          announce, listen, netmkaddr, and reject are preprocessor
          macros defined as p9dial, p9announce, and so on; see
          intro(3).