glenda.party
term% ls -F
term% cat index.txt
DIAL(2)                       System Calls Manual                      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!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, including terminating NUL, is guaran‐
       teed to fit in (40) bytes.  One line directory exists for each possible
       connection.  The data file in the line directory should be used to com‐
       municate 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 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 parallel all addresses on net‐
       works  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 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 netaddr used in announce may be a local  address
       or an asterisk, to indicate all local addresses, e.g.  tcp!*!echo.  The
       listen routine takes as its first argument the dir of  a  previous  an‐
       nounce.   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 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.

       Getnetconninfo returns a structure containing information about a  net‐
       work 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 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 structure 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 conven‐
       tions  for  specifying  the  mount point.  Commands that take a network
       mount point as a parameter (such as dns, cs (see  ndb(8)),  and  ipcon‐
       fig(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 conver‐
       sion.

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

              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);
                        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 non‐
       zero if it fails.



                                                                       DIAL(2)