t_connect(3)t_connect(3)NAMEt_connect - Establish a connection with another transport user
SYNOPSIS
#include <xti.h>
int t_connect(
int fd,
struct t_call *sndcall,
struct t_call *rcvcall );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
t_connect(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
The following table summarizes the relevance of input and output param‐
eters before and after t_connect() is called.
─────────────────────────────────────────────────
Parameters Before Call After Call
─────────────────────────────────────────────────
fd y n
sndcall->addr.maxlen n n
sndcall->addr.len y n
sndcall->addr.buf y(y) n
sndcall->opt.maxlen n n
sndcall->opt.len y n
sndcall->opt.buf y(y) n
sndcall->udata.maxlen n n
sndcall->udata.len y n
sndcall->udata.buf o(o) n
sndcall->sequence n n
rcvcall->addr.maxlen y n
rcvcall->addr.len n y
rcvcall->addr.buf o (o)
rcvcall->opt.maxlen y n
rcvcall->opt.len n y
rcvcall->opt.buf o (o)
rcvcall->udata.maxlen y n
rcvcall->udata.len n y
rcvcall->udata.buf o (o)
rcvcall->sequence n n
─────────────────────────────────────────────────
Notes to table: This is a meaningful parameter. This is not a meaning‐
ful parameter. This is an optional parameter. The content of the
object pointed to by o is optional. Specifies a file descriptor
returned by the t_open() function that identifies the local transport
endpoint where the connection will be established. Points to a type
t_call structure. The t_call structure pointed to by the sndcall param‐
eter provides information required by the transport provider to estab‐
lish a connection at the transport endpoint specified by the fd parame‐
ter. The t_call structure has the following four members: Specifies
protocol address parameters of the destination transport user needed by
the transport provider. The type netbuf structure referenced by this
member is defined in the xti.h include file. This structure, which is
used to define buffer parameters explicitly, has the following members:
Specifies the maximum byte length of the data buffer. Specifies the
actual byte length of the data written to the buffer. Points to the
buffer location. Specifies protocol-specific information needed by the
transport provider. Specifies user-data parameters passed to the des‐
tination transport user. This parameter is not meaningful.
The sndcall->addr.maxlen, sndcall->opt.maxlen, and snd‐
call->udata.maxlen parameters have no meaning when the t_con‐
nect() function is called.
When options are used, the sndcall->opt.buf parameter must spec‐
ify the established options structure (such as isoco_options,
isocl_options or tcp_options). A transport user may choose not
to negotiate protocol options by setting the sndcall->opt.len
parameter to 0 (zero). When options are not specified by the
transport user, the transport provider has the option of return‐
ing default option values.
The amount of transport user data passed to the destination
transport user must not exceed the limits specified by the
transport provider as returned to the info->connect parameter of
the t_open() or t_getinfo() function.
The sndcall->opt.len and sndcall->udata.len parameters must be
set before the t_connect() function is called. Points to a type
t_call structure. The t_call structure pointed to by the rcvcall
parameter reserves storage for information associated with the
connection established at the transport endpoint specified by
the fd parameter. When rcvcall is a null pointer, no data is
returned to the caller. The structure pointed to by rcvcall has
the following members: Specifies protocol address parameters
associated with the responding transport endpoint. Specifies
protocol-specific information associated with the transport
provider. Specifies parameters for user data that may be
optionally returned to the caller from the destination transport
user. This parameter is not meaningful.
The rcvcall->addr.maxlen, rcvcall->opt.maxlen, and rcv‐
call->udata.maxlen parameters must be set before the t_connect()
function is called.
When it is provided, the rcvcall()->udata.len parameter speci‐
fies the actual destination user user-data byte length and the
data buffer pointed to by rcvcall()->udata.buf contains destina‐
tion transport user data.
DESCRIPTION
The t_connect() XTI function is a connection-oriented service function
issued by a transport user to request connection to the specified des‐
tination transport user. By default, this function executes in the syn‐
chronous operating mode. In this mode, the t_connect() function waits
for the destination user to respond and the connection to be set up
before returning control to the transport user who called this func‐
tion.
When the transport endpoint, specified by the file descriptor, has been
previously opened with the O_NONBLOCK option set in the t_open() or
fcntl() function, the t_connect() function executes in asynchronous
mode and does not wait for the transport user at the specified endpoint
to respond before returning control to the caller, but returns a [TNO‐
DATA] error, which indicates that the connection has not yet been
established. In asynchronous mode, use the t_rcvconnect() function to
determine the status of a connect request.
The t_connect() function uses type t_call and netbuf structures, which
are defined in the xti.h include file.
ERRORS
If the t_connect() function fails, t_errno may be set to one of the
following values: File descriptor fd does not refer to a valid trans‐
port endpoint. The t_connect() function was issued in the wrong
sequence. Asynchronous mode is indicated because O_NONBLOCK was set,
but no data is currently available from the transport provider. The
specified protocol address was in an incorrect format or contained
illegal information. The specified protocol options were in an incor‐
rect format or contained illegal information The amount of user data
specified was not within the bounds allowed by the transport provider.
The user does not have permission to use the specified protocol address
or options. The number of bytes allocated for incoming data is not
sufficient for storage of that data. In asynchronous mode only, the
connect information normally returned to the rcvcall was discarded. The
transport provider state was changed to T_DATAXFER. An asynchronous
event that requires immediate attention has occurred on the transport
endpoint specified by the fd parameter. A system error occurred during
execution of this function. This function is not supported by the
underlying transport provider. This transport provider does not pro‐
vide multiple connections with the same local and remote addresses.
This error indicates that a connection already exists. This error
indicates that a communication problem has been detected between XTI
and the transport provider for which there is no other suitable
XTI(t_errno).
VALID STATES
The t_connect() function can only be called in the T_IDLE transport
provider state.
RETURN VALUE
Upon successful completion, a value of 0 (zero) is returned. Otherwise,
a value of -1 is returned and t_errno is set to indicate an error.
SEE ALSO
Functions: fcntl(2), t_accept(3), t_alloc(3), t_getinfo(3), t_lis‐
ten(3), t_open(3), t_optmgmt(3), t_rcvconnect(3)
Standards: standards(5).
Network Programmer's Guide
t_connect(3)