Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!mailrus!cornell!ken
From: ken@gvax.cs.cornell.edu (Ken Birman)
Newsgroups: comp.sys.isis
Subject: Another proposed interface, more comments solicited
Message-ID: <30421@cornell.UUCP>
Date: 27 Jul 89 17:29:53 GMT
Sender: nobody@cornell.UUCP
Reply-To: ken@cs.cornell.edu (Ken Birman)
Distribution: comp
Organization: Cornell Univ. CS Dept, Ithaca NY
Lines: 48

.SH NAME
isis_connect \- Make a TCP steam connection to another ISIS process
.SH SYNOPSIS
.B #include "isis.h"
.PP
.B
fdes = isis_connect (who_p)
.RS
.B int fdes;
.br
.B address who_p;
.RE

.SH DESCRIPTION

isis_connect provides a way for a pair of cooperating processes to construct
a high bandwidth channel for stream or message communication.
Both processes call isis_connect, each specifying the address of the other.
The calls block until a rendezvous occurs, at which time a TCP connection
is made, an exchange of data occurs to verify correct functioning of the
channel (this also ensures that both calls return more or less at the same
time), and the file descriptors created are returned to the callers.
 
The file descriptors obtained from isis_connect can be used within calls 
to msg_read and msg_write, or directly in calls to read(3) and write(3). 
Performance will generally be substantially better than for transmissions 
that pass through ISIS.  
 
The overhead of making a channel in this way is high. 
Use of a dedicated channel is consequently recommended only in 
cases where the channel will subsequently be used over a long period of time 
or for large volumes of data. 
The routines isis_input and isis_input_sig can be used to monitor such 
a channel for data if necessary. 

.SH DIAGNOSTICS

If an error occurs, -1 is returned and the UNIX error code (in the global errno variable)
may be examined
by the caller or printed using `perror'.

.SH NOTE

Calls to isis_connect will block until the connection is established or the
remote process fails.  In the latter case, ECONNABORTED is returned.

.SH "SEE ALSO"
isis_input(3), ISIS(3)