Networking Services Library Functions tconnect(3NSL)
NAME
tconnect - establish a connection with another transport
user
SYNOPSIS
#include
int tconnect(int fd, const struct tcall *sndcall,
struct tcall *rcvcall);
DESCRIPTION
This routine is part of the XTI interfaces which evolved
from the TLI interfaces. XTI represents the future evolution
of these interfaces. However, TLI interfaces are supported
for compatibility. When using a TLI routine that has the
same name as an XTI routine, the tiuser.h header file must
be used. Refer to the TLI COMPATIBILITY section for a
description of differences between the two interfaces. This
function enables a transport user to request a connection to
the specified destination transport user.
This function can only be issued in the TIDLE state. The
parameter fd identifies the local transport endpoint where
communication will be established, while sndcall and rcvcall
point to a tcall structure which contains the following
members:
struct netbuf addr;
struct netbuf opt;
struct netbuf udata;
int sequence;
The parameter sndcall specifies information needed by the
transport provider to establish a connection and rcvcall
specifies information that is associated with the newly
established connection.
In sndcall, addr specifies the protocol address of the des-
tination transport user, opt presents any protocol-specific
information that might be needed by the transport provider,
udata points to optional user data that may be passed to the
destination transport user during connection establishment,
and sequence has no meaning for this function.
On return, in rcvcall, addr contains the protocol address
associated with the responding transport endpoint, opt
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions tconnect(3NSL)
represents any protocol-specific information associated with
the connection, udata points to optional user data that may
be returned by the destination transport user during connec-
tion establishment, and sequence has no meaning for this
function.
The opt argument permits users to define the options that
may be passed to the transport provider. The user may choose
not to negotiate protocol options by setting the len field
of opt to zero. In this case, the provider uses the option
values currently set for the communications endpoint.
If used, sndcall->opt.buf must point to a buffer with the
corresponding options, and sndcall->opt.len must specify
its length. The maxlen and buf fields of the netbuf struc-
ture pointed by rcvcall->addr and rcvcall->opt must be set
before the call.
The udata argument enables the caller to pass user data to
the destination transport user and receive user data from
the destination user during connection establishment. How-
ever, the amount of user data must not exceed the limits
supported by the transport provider as returned in the con-
nect field of the info argument of topen(3NSL) or
tgetinfo(3NSL). If the len of udata is zero in sndcall, no
data will be sent to the destination transport user.
On return, the addr, opt and udata fields of rcvcall will be
updated to reflect values associated with the connection.
Thus, the maxlen field of each argument must be set before
issuing this function to indicate the maximum size of the
buffer for each. However, maxlen can be set to zero, in
which case no information to this specific argument is given
to the user on the return from tconnect(). If maxlen is
greater than zero and less than the length of the value,
tconnect() fails with terrno set to TBUFOVFLW. If
rcvcall is set to NUL, no information at all is returned.
By default, tconnect() executes in synchronous mode, and
will wait for the destination user's response before return-
ing control to the local user. A successful return (that is,
return value of zero) indicates that the requested connec-
tion has been established. However, if ONONBLOCK is set
by means of topen(3NSL) or fcntl(2), tconnect() 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 terrno
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions tconnect(3NSL)
set to TNODATA to indicate that the connection has not yet
been established. In this way, the function simply initiates
the connection establishment procedure by sending a connec-
tion request to the destination transport user. The
trcvconnect(3NSL) function is used in conjunction with
tconnect() to determine the status of the requested connec-
tion.
When a synchronous tconnect() call is interrupted by the
arrival of a signal, the state of the corresponding tran-
sport endpoint is TOUTCON, allowing a further call to
either trcvconnect(3NSL), trcvdis(3NSL) or tsnddis(3NSL).
When an asynchronous tconnect() call is interrupted by the
arrival of a signal, the state of the corresponding tran-
sport endpoint is TIDLE.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Oth-
erwise, a value of -1 is returned and terrno is set to
indicate an error.
VALID STATES
TIDLE
ERORS
On failure, terrno is set to one of the following:
TACES The user does not have permission to use the
specified address or options.
TADRBUSY This transport provider does not support mul-
tiple connections with the same local and
remote addresses. This error indicates that a
connection already exists.
TBADADR The specified protocol address was in an
incorrect format or contained illegal infor-
mation.
TBADATA The amount of user data specified was not
within the bounds allowed by the transport
provider.
TBADF The specified file descriptor does not refer
to a transport endpoint.
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions tconnect(3NSL)
TBADOPT The specified protocol options were in an
incorrect format or contained illegal infor-
mation.
TBUFOVFLW The number of bytes allocated for an incoming
argument (maxlen) is greater than 0 but not
sufficient to store the value of that argu-
ment. If executed in synchronous mode, the
provider's state, as seen by the user,
changes to TDATAXFER, and the information to
be returned in rcvcall is discarded.
TLOK An asynchronous event has occurred on this
transport endpoint and requires immediate
attention.
TNODATA ONONBLOCK was set, so the function success-
fully initiated the connection establishment
procedure, but did not wait for a response
from the remote user.
TNOTSUPORT This function is not supported by the under-
lying transport provider.
TOUTSTATE The communications endpoint referenced by fd
is not in one of the states in which a call
to this function is valid.
TPROTO This error indicates that a communication
problem has been detected between XTI and the
transport provider for which there is no
other suitable XTI error (terrno).
TSYSER A system error has occurred during execution
of this function.
TLI COMPATIBILITY
The XTI and TLI interface definitions have common names but
use different header files. This, and other semantic differ-
ences between the two interfaces are described in the sub-
sections below.
Interface Header
SunOS 5.11 Last change: 7 May 1998 4
Networking Services Library Functions tconnect(3NSL)
The XTI interfaces use the header file, xti.h. TLI inter-
faces should not use this header. They should use the
header:
#include
Error Description Values
The TPROTO and TADRBUSY terrno values can be set by the
XTI interface but not by the TLI interface.
A terrno value that this routine can return under different
circumstances than its XTI counterpart is TBUFOVFLW. It can
be returned even when the maxlen field of the corresponding
buffer has been set to zero.
Option Buffers
The format of the options in an opt buffer is dictated by
the transport provider. Unlike the XTI interface, the TLI
interface does not fix the buffer format.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
fcntl(2), taccept(3NSL), talloc(3NSL), tgetinfo(3NSL),
tlisten(3NSL), topen(3NSL), toptmgmt(3NSL),
trcvconnect(3NSL), trcvdis(3NSL), tsnddis(3NSL), attri-
butes
SunOS 5.11 Last change: 7 May 1998 5
|
