.th TcpOpen III 4/21/86
.sh "NAME"
TcpOpen - establish a TCP connection
.sh "C SYNOPSIS"
.nf
/*
 * TCP Connection Type Definition
 */
#define	TCP_ACTIVE	1	/* actively pursue this connection	*/
#define	TCP_PASSIVE	2	/* listen for a remote TCP connection	*/

/*
 * TCP Connection Mode Definition
 */
#define	TCP_READ	1	/* user will read on connection		*/
#define	TCP_WRITE	2	/* user will write on connection	*/

/*
 * Internet Address Definition
 */
typedef	struct
{
	char	in_net;		/* internet network component	*/
	char	in_host;	/* internet host component	*/
	int	in_imp;		/* internet imp component	*/
} Internet_Addr;

/*
 * TCP Socket Definition
 */
typedef	struct
{
	long	skt_addr;	/* internet address component	*/
	int	skt_port;	/* TCP port component		*/
} Socket;

/*
 * TCP Open Request (Parameter Block Structure)
 */
typedef	struct
{
	char	o_type;		/* type of connection		*/
	char	o_mode;		/* mode of connection		*/
	int	o_timeout;	/* time allowed to establish	*/
	int	o_prec;		/* type of service (precedence)	*/
	int	o_sectcc;	/* connection's security & tcc	*/
	Socket	o_locskt;	/* local socket			*/
	Socket	o_forskt;	/* foreign socket		*/
} Tcp_Open;
 . . .
 seid        Daemon_Seid;
 Tcp_Open    *Open_Param;
 int         *Loc_Name;
 int         stat;
 . . .
 stat = TcpOpen (Daemon_Seid, Open_Param, Loc_Name);
.fi
.sh "DESCRIPTION"
The TcpOpen primitive is used to establish a TCP connection based on
the information supplied in the Tcp_Open data structure.  This
primitive is used to listen for incoming TCP connections or to initiate
an outgoing TCP connection.  If the connection is successfully
established, the local connection identifier is assigned for the
connection and stored in the location pointed to by the Loc_Name
parameter.  All subsequent TCP service requests that refer to this
connection must use the Loc_Name as the local connection identifier.
.s3
The Daemon_Seid parameter must contain the process seid of the TCP
Daemon that will be responsible for handling and managing the
connection.  This process seid can be obtained using the TcpFind
primitive given the well-known UNIX directory pathname associated with
the TCP Daemon.
.s3
The Open_Param parameter is a pointer to a data structure containing
attributes and parameters which specify how this connection is to be
established.  This information must be contained in a data structure
which conforms to the Tcp_Open data structure definition.
.s3
Specifically, this data structure will contain the following information:
.sp
.lp 10 2
.bn type
.br
specifies the type of connection (active or passive)
.i0
.sp
.lp 10 2
.bn mode
.br
specifies how the connection will be used (read, write, both)
.i0
.sp
.sp
.lp 10 2
.bn timeout
.br
specifies how much time (ticks) to allow for the connection to be established
.i0
.sp
.lp 10 2
.bn "local port"
.br
specifies the local port (16-bits) to be used
.i0
.sp
.lp 10 2
.bn "remote socket"
.br
specifies the remote socket (32-bit internet address, 16-bit port) to be
used
.i0
.s3
Depending on the type of connection to be established, the TCP Daemon will
generate default values to be used if not specified in the original open
parameter structure.
.s3
For example, if the type of connection is passive (i.e., waiting for an
incoming connection message), the open parameter structure must specify
the local port to wait for the connection.  However, the daemon will allow
a fully specified remote socket (internet address and port) as well
as a unspecified remote socket.  In the latter case, the daemon will
proceed with the connection synchronization messages from any remote host.
Also, the daemon will allow the connection timeout variable to be unspecified
for passive connections.  This will allow a connection server process to 
block indefinitely until a connection is established.
.s3
If the type of connection is active (i.e., initiate
the connection handshake), the open parameter structure must specify the
complete remote socket.  However, the daemon will allow either a specified
local port or a unspecified local port.  The daemon will dynamically assign
a local port to be used in the latter case.
.sh "EXCEPTIONS"
TcpOpen
returns the following error codes:
.lp 10 0
.nf
XtcpOK      (0)      Successful
XtcpNoX     (3)      Non-existent TCP Daemon
XtcpTooMany (4)      Exceeded connections per user limit
XtcpBadArg  (5)      Invalid argument to primitive
.fi
.i0
.sh "FILES"
.nf
/ksb/include/tcp.h     TCP Interface Definitions for C
/ksb/lib/TCP.a   TCP Interface Library for C
.fi
.sh "SEE ALSO"
TcpFind (III)

