Subversion Repositories planix.SVN

.TH DIAL 2

.SH NAME

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

.SH SYNOPSIS

.B #include <u.h>

.br

.B #include <libc.h>

.PP

.B

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

.PP

.B

int   hangup(int ctl)

.PP

.B

int   announce(char *addr, char *dir)

.PP

.B

int   listen(char *dir, char *newdir)

.PP

.B

int   accept(int ctl, char *dir)

.PP

.B

int   reject(int ctl, char *dir, char *cause)

.PP

.B

char* netmkaddr(char *addr, char *defnet, char *defservice)

.PP

.B

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

.PP

.B

NetConnInfo*  getnetconninfo(char *conndir, int fd)

.PP

.B

void freenetconninfo(NetConnInfo*)

.SH DESCRIPTION

For these routines,

.I addr

is a network address of the form

.IB network ! netaddr ! service\f1,

.IB network ! netaddr\f1,

or simply

.IR netaddr .

.I Network

is any directory listed in 

.B /net

or the special token,

.BR net .

.B Net

is a free variable that stands for any network in common

between the source and the host

.IR netaddr .

.I Netaddr

can be a host name, a domain name, a network address,

or a meta-name of the form

.BI $ attribute\f1,

which

is replaced by

.I value

from the value-attribute pair

.IB attribute = value

most closely associated with the source host in the

network data base (see

.IR ndb (6)).

.PP

If a connection attempt is successful and

.I dir

is non-zero,

the path name of a

.I line directory

that has files for accessing the connection

is copied into

.IR dir .

The path name, including terminating

.SM NUL\c

, is guaranteed to fit in

.L NETPATHLEN

(40)

bytes.

One line directory exists for each possible connection.

The

.B data

file in the line directory should be used to communicate with the destination.

The

.B ctl

file in the line directory can be used to send commands to the line.

See

.IR ip (3)

for messages that can be written to the

.B ctl

file.

The last close of the

.B data

or

.B ctl

file will close the connection.

.PP

.I Dial

makes a call to destination

.I addr

on a multiplexed network.

If the network in

.I addr

is

.BR net ,

.I dial

will try in parallel 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

.B data

file in the line directory.

The

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

.IR local

is non-zero, the local address will be set to

.IR local .

If

.I cfdp

is non-zero,

.BI * cfdp

is set to a file descriptor open for reading and

writing the control file.

.PP

.I Hangup

is a means of forcing a connection to hang up without

closing the

.B ctl

and

.B data

files.

.P

.I Announce

and

.I listen

are the complements of

.IR dial .

.I Announce

establishes a network

name to which calls can be made.

Like

.IR dial ,

.I announce

returns an open

.B ctl

file.

The 

.I netaddr

used in announce may be a local address or an asterisk,

to indicate all local addresses, e.g.

.BR tcp!*!echo .

The

.I listen

routine takes as its first argument the

.I dir

of a previous

.IR announce .

When a call is received,

.I listen

returns an open

.B ctl

file for the line the call was received on.

It sets

.I newdir

to the path name of the new line directory.

.I Accept

accepts a call received by

.IR listen ,

while

.I reject

refuses the call because of

.IR cause .

.I Accept

returns a file descriptor for the data file opened

.BR ORDWR .

.PP

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

.PP

.I Getnetconninfo

returns a structure containing information about a

network connection.  The structure is:

.EX

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

  };

.EE

.PP

The information is obtained from the connection directory,

.IR conndir .

If

.I conndir

is nil, the directory is obtained by performing

.IR fd2path (2)

on

.IR fd .

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

.IR freenetconninfo .

.PP

.I Setnetmtpt

copies the name of the network mount point into

the buffer

.IR to ,

whose length is

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

.BR dns ,

.BR cs

(see

.IR ndb (8)),

and

.IR ipconfig (8))

should now call

.IR setnetmtpt .

If

.I from

is

.BR nil ,

the mount point is set to the default,

.BR /net .

If

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

.I from

appended to the string

.BR /net .

The last form is obsolete and is should be avoided.

It exists only to aid in conversion.

.SH EXAMPLES

Make a call and return an open file descriptor to

use for communications:

.IP

.EX

int callkremvax(void)

{

	return dial("kremvax", 0, 0, 0);

}

.EE

.PP

Call the local authentication server:

.IP

.EX

int dialauth(char *service)

{

	return dial(netmkaddr("$auth", 0, service), 0, 0, 0);

}

.EE

.PP

Announce as

.B kremvax

on TCP/IP and

loop forever receiving calls and echoing back

to the caller anything sent:

.IP

.EX

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;

		}

	}

}

.EE

.SH SOURCE

.BR /sys/src/libc/9sys ,

.B /sys/src/libc/port

.SH "SEE ALSO"

.IR auth (2),

.IR ip (3),

.IR ndb (8)

.SH DIAGNOSTICS

.IR Dial ,

.IR announce ,

and

.I listen

return \-1 if they fail.

.I Hangup

returns nonzero if it fails.