DIAL(2) 							System Calls Manual							   DIAL(2)

NAME

       dial, hangup, announce, listen, accept, reject, netmkaddr - 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)

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

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];

		   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("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/port

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.

																	   DIAL(2)