'\"macro stdmacro
.if n .pH g3n.t_connect @(#)t_connect	40.6 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} t_connect 3N "Networking Support Utilities" "\&"
.if \nX=1 .ds x} t_connect 3N "Networking Support Utilities"
.if \nX=2 .ds x} t_connect 3N "" "\&"
.if \nX=3 .ds x} t_connect "" "" "\&"
.if \nX=4 .ds x} t_connect "NS_LIB" "EXTENSION" " "
.TH \*(x}
.SH NAME
\f4t_connect\f1 \- establish a connection with another transport user
.SH SYNOPSIS
\f4#include <tiuser.h>\f1
.PP
\f4int t_connect(fd, sndcall, rcvcall)\f1
.br
\f4int fd;\f1
.br
\f4struct t_call *sndcall;\f1
.br
\f4struct t_call *rcvcall;\f1
.SH DESCRIPTION
This function enables a transport user to request a connection to the
specified destination transport user.
\f4fd\f1 identifies the local transport endpoint where communication
will be established, while \f4sndcall\f1 and \f4rcvcall\f1 point to
a \f4t_call\f1 structure that contains the following members:
.PP
.RS
\f4struct netbuf addr;\fP
.br
\f4struct netbuf opt;\fP
.br
\f4struct netbuf udata;\fP
.br
\f4int sequence;\fP
.RE
.PP
\f4sndcall\f1 specifies information needed by the transport provider to
establish a connection and \f4rcvcall\f1
specifies information that is associated with the
newly established connection.
.PP
\f4netbuf\f1 is described in \f4intro\fP(3).
In \f4sndcall\f1, \f4addr\f1
specifies the protocol address of the destination transport user,
\f4opt\f1 presents any protocol-specific information that might be
needed by the transport provider, \f4udata\f1
points to optional user data that may be passed to
the destination transport user during connection establishment,
and \f4sequence\f1 has no meaning for this function.
.PP
On return in \f4rcvcall\f1, \f4addr\f1 returns the protocol address
associated with the responding transport endpoint, \f4opt\f1
presents any protocol-specific information associated with the connection,
\f4udata\f1 points to optional user data that may be returned by
the destination transport user during connection establishment,
and \f4sequence\f1 has no meaning for this function.
.PP
The \f4opt\f1 argument implies no structure on the options that may
be passed to the transport provider.
The transport provider is free to specify the structure of any options
passed to it.
These options are specific to the underlying protocol of the transport
provider.
The user may choose not to negotiate protocol
options by setting the \f4len\f1 field of \f4opt\f1 to zero.
In this case, the provider may use default options.
.PP
The \f4udata\f1 argument enables the caller to pass user data to the
destination transport user and receive user data
from the destination user during connection establishment.
However, the amount of user data must not exceed the limits supported by
the transport provider as returned in the \f4connect\fP field
of the \f4info\fP argument of
\f4t_open\fP(3N) or \f4t_getinfo\fP(3N).
If the \f4len\f1 [see \f4netbuf\f1 in \f4intro\fP(3)] field of
\f4udata\f1 is zero in \f4sndcall\f1,
no data will be sent to the destination transport user.
.PP
On return, the \f4addr\f1, \f4opt\f1, and \f4udata\f1 fields of \f4rcvcall\f1
will be updated to reflect values associated with the connection.
Thus, the \f4maxlen\f1 [see \f4netbuf\f1 in \f4intro\fP(3)]
field of each argument
must be set before issuing this function to indicate the maximum
size of the buffer for each.
However, \f4rcvcall\f1 may be \s-1NULL\s+1, in which case no information
is given to the user on return from \f4t_connect\fP.
.PP
By default, \f4t_connect\fP executes in synchronous mode, and will wait
for the destination
user's response before returning control to the local user.
A successful return (i.e., return value of zero) indicates that the
requested connection has been established.
However, if \f4O_NDELAY\fP or \f4O_NONBLOCK\fP is set (via \f4t_open\fP or
\f4fcntl\fP), \f4t_connect\fP executes in asynchronous mode.
In this case, the call will not wait for the remote user's
response, but will return control immediately to the local user
and return -1 with \f4t_errno\fP set to \f4TNODATA\fP
to indicate that the connection has not yet been established.
In this way, the function simply initiates the connection
establishment procedure by sending a connect request to the
destination transport user.
.P
On failure, \f4t_errno\f1 may be set to one of the following:
.TP 19
\f4[TBADF]\fP
The specified file descriptor does not refer to a transport endpoint.
.TP
\f4[TOUTSTATE]\fP
The function was issued in the wrong sequence.
.TP
\f4[TNODATA]\fP
\f4O_NDELAY\fP or \f4O_NONBLOCK\fP
was set, so the function successfully initiated the connection
establishment procedure, but did not wait for a response from the remote
user.
.TP
\f4[TBADADDR]\fP
The specified protocol address was in an incorrect format or
contained illegal information.
.TP
\f4[TBADOPT]\fP
The specified protocol options were in an incorrect format or contained illegal
information.
.TP
\f4[TBADDATA]\fP
The amount of user data specified was not within the bounds allowed by
the transport provider.
.TP
\f4[TACCES]\fP
The user does not have permission to use the specified address or options.
.TP
\f4[TBUFOVFLW]\fP
The number of bytes allocated for an incoming argument is not
sufficient to store the value of that argument.
If executed in synchronous mode,
the provider's state, as seen by the user, changes to
\f4T_DATAXFER\fP, and the connect indication information to be
returned in \f4rcvcall\fP is discarded.
.TP
\f4[TLOOK]\fP
An asynchronous event has occurred on this transport endpoint and requires
immediate attention.
.TP
\f4[TNOTSUPPORT]\fP
This function is not supported by the underlying transport
provider.
.TP
\f4[TSYSERR]\fP
A system error has occurred during execution of this function.
.SH SEE ALSO
.na
\f4intro\fP(3), t_\f4accept\fP(3N),
t_\f4getinfo\fP(3N),
t_\f4listen\fP(3N),
t_\f4open\fP(3N),
t_\f4optmgmt\fP(3N),
t_\f4rcvconnect\fP(3N).
.sp .2
\f2UNIX System V Network Programmer's Guide\f1.
.ad
.SH DIAGNOSTICS
\f4t_connect\fP
returns 0 on success and \-1 on failure and
\f4t_errno\f1 is set to indicate the error.
.Ee
