t_bind - Bind an address to a transport endpoint
#include <xti.h>
int t_bind(
int fd,
struct t_bind *req,
struct t_bind *ret );
XTI Library (libxti.a)
Interfaces documented on this reference page conform to
industry standards as follows:
t_bind(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
The following table summarizes the relevance of input and
output parameters before and after t_bind() is called:
--------------------------------------------
Parameter Before Call After Call
--------------------------------------------
fd y n
req->addr.maxlen n n
req->addr.len y>= 0 n
req->addr.buf y(y) n
req->qlen y>=0 n
ret->addr.maxlen y n
ret->addr.len n y
ret->addr.buf o (o)
ret->qlen n y>= 0
--------------------------------------------
Notes to table: This is a meaningful parameter. This is
not a meaningful parameter. This is an optional parameter.
The content of the object pointed to by y is meaningful.
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.
For connection-mode service, this function allows
more than a single transport endpoint to be bound
to the same protocol address, provided the transport
provider allows this. However, only one protocol
address can be bound to a transport endpoint.
See the xti_internet(7) reference page for more
information.
When a transport user binds more than one transport
endpoint to the same protocol address, only one
endpoint can be used to listen for connect indications
associated with that protocol address using
the t_listen() function. Consequently, for a given
protocol address, only one t_bind() function may
specify a value greater than 0 (zero) for the
req->qlen parameter. In this way, the transport
provider can identify the transport endpoint that
should be notified of an incoming connect indication.
If a transport user attempts to bind a protocol
address to a second transport endpoint with a qlen
value greater than zero, the t_bind() functions
returns -1 and sets t_errno to [TADDRBUSY]. When a
user accepts a connection on a transport endpoint
that is already the listening endpoint, the bound
protocol address is considered busy for the duration
of the connection until a t_unbind() or
t_close() call is issued. There can be only one
passive listening endpoint on a protocol address at
any one time.
For connectionless-mode service, only one endpoint
can be associated with a protocol address. If a
user attempts to bind a second transport endpoint
to a protocol address that is already bound,
t_bind() returns -1 and sets t_errno to [TADDRBUSY].
Specifies a pointer to a type t_bind()
structure that has the following members: Specifies
a buffer for protocol address information sent by
the calling transport user. The type netbuf structure
referenced by this member is defined in the
xti.h include file. This structure, which is used
to specify the address to be bound to the endpoint,
has the following members: Specifies the maximum
byte length of the data buffer. This parameter has
no meaning for the req argument. Specifies the
number of bytes in the address. Points to the
address buffer location. Specifies the number of
outstanding connect indications that the transport
provider should support for the given transport
endpoint. An outstanding connect indication is one
that has been passed to the transport user by the
transport provider but has not been accepted or
rejected. This field has meaning only when initializing
a connection-mode service.
The req parameter is used to request that the protocol
address, pointed to by req->addr.buf be bound
to the transport endpoint specified by the fd
parameter. The req->addr.maxlen parameter has no
meaning. If the requested address is not available,
the t_bind() call returns the value -1 and
sets t_errno to indicate the error.
If the transport user does not specify a protocol
address, either by specifying a ret as a NULL
pointer or by specifying req->addr.len as 0 (zero),
the transport provider assigns an alternate protocol
address and returns it in the req->addr.buf
field. If the transport provider does not support
automatic address generation, the t_bind() call
returns the value -1 and sets t_errno to [TNOADDR].
The req parameter may be specified as a null
pointer when a transport user does not need to use
a protocol address for binding. The ret parameter
may also be specified as a null pointer when the
protocol address is not significant.
A value of req->qlen greater than 0 (zero) is meaningful
only when it is issued by a transport user
expecting other transport users to call it. The
value of qlen is negotiated by the transport
provider and may be changed if the transport
provider cannot support the specified number of
outstanding connect indications. However, this
value qlen is never be negotiated from a request
value greater than zero to zero; this is a requirement
on transport providers. On return, the qlen
field in ret contains the negotiated value. Specifies
a pointer to a type t_bind() structure. The
addr structure member returned by t_bind() specifies
variables for the protocol address actually
bound to the transport endpoint specified by the fd
parameter. If specified, the address in ret is the
same as in req.
The transport user must specify the maximum size
(in bytes) of the protocol address with the
ret->addr.maxlen parameter and the location into
which to place the address with the ret->addr.buf
parameter. On return, the ret->addr.len parameter
specifies theactual number of bytes in the bound
protocol address and the ret->addr.buf parameter
points to the bound address. When the
ret->addr.maxlen parameter is not large enough to
hold the returned protocol address, an error
occurs.
The t_bind() XTI function is used in connectionless and
connection-oriented transport service to associate a protocol
address with the transport endpoint returned by the
t_open() function and to activate that transport endpoint.
This function uses type t_bind() and netbuf structures,
which are defined in the xti.h include file.
When connection-oriented transport service is in effect,
and once this function has been called, the transport
provider may begin enqueuing incoming connect indications
or may service a connection request on the transport endpoint.
When connectionless transport service is in effect and
once this function has been called, the transport user may
send or receive data units through the transport endpoint.
Upon successful completion, a value of 0 (zero) is
returned. Otherwise, a value of -1 is returned and t_errno
is set to indicate the error.
If the t_bind() function fails, t_errno may be set to one
of the following: The specified file descriptor does not
refer to a transport endpoint. The function was issued in
the wrong sequence. The specified protocol address was in
an incorrect format or contained illegal information. The
transport provider could not allocate an address. The
user does not have permission to use the specified
address. The number of bytes allowed for an incoming
argument is not sufficient to store the value of that
argument. The provider's state will change to T_IDLE and
the information to be returned in the ret parameter will
be discarded. A system error occurred during execution of
this function. The address requested is in use and the
transport provider could not allocate a new address. 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).
The t_bind() function can be called only in the T_UNBND
transport provider state.
A transport provider might not allow more than one transport
endpoint to be explicitly bound to the same protocol
address, even though more than one connection can be
accepted for the same protocol address. Therefore, to
ensure code portability do not bind transport endpoints
that are also responding endpoints (resfd) in a call to
t_accept() when the reponding address and the called
address are the same.
Functions: t_accept(3), t_alloc(3), t_close(3), t_open(3),
t_optmgmt(3), t_unbind(3).
Standards: standards(5).
Network information: xti(7), xti_internet(7).
Network Programmer's Guide
t_bind(3)
[ Back ] |
