t_bind(3)t_bind(3)NAMEt_bind - Bind an address to a transport endpoint
SYNOPSIS
#include <xti.h>
int t_bind(
int fd,
struct t_bind *req,
struct t_bind *ret );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
t_bind(): 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_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 meaning‐
ful 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 lis‐
ten 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 [TADDR‐
BUSY]. 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 asso‐
ciated 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 indica‐
tions 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 bind‐
ing. 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 trans‐
port provider and may be changed if the transport provider can‐
not support the specified number of outstanding connect indica‐
tions. 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 con‐
tains 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.
DESCRIPTION
The t_bind() XTI function is used in connectionless and connection-ori‐
ented transport service to associate a protocol address with the trans‐
port endpoint returned by the t_open() function and to activate that
transport endpoint. This function uses type t_bind() and netbuf struc‐
tures, 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 func‐
tion has been called, the transport user may send or receive data units
through the transport endpoint.
RETURN VALUES
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.
ERRORS
If the t_bind() function fails, t_errno may be set to one of the fol‐
lowing: The specified file descriptor does not refer to a transport
endpoint. The function was issued in the wrong sequence. The speci‐
fied 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).
VALID STATES
The t_bind() function can be called only in the T_UNBND transport
provider state.
USAGE
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.
SEE ALSO
Functions: t_accept(3), t_alloc(3), t_close(3), t_open(3), t_opt‐
mgmt(3), t_unbind(3).
Standards: standards(5).
Network information: xti(7), xti_internet(7).
Network Programmer's Guide
t_bind(3)
