Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DIAL(3)			   Library Functions Manual		       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,
		 void *host, int *port)

DESCRIPTION
       For these routines, addr	is a network address of	the  form  network!ne-
       taddr!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 ne-
       taddr.  Netaddr can be a	host name, a domain name,  or  a  network  ad-
       dress.

       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	signa-
       tures,  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 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 re-
       turns 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 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 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.

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

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

       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 `line directory' dir, or if	dir is
       nil,  from  the	connection file	descriptor 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.

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

	      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)
				  write(dfd, buf, n);
			     exits(0);
			default:
			     close(lcfd);
			     break;
			}
		   }
	      }

SOURCE
       /usr/local/plan9/src/lib9/dial.c
       /usr/local/plan9/src/lib9/announce.c
       /usr/local/plan9/src/lib9/_p9dialparse.c
       /usr/local/plan9/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).

								       DIAL(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SOURCE | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dial&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help