t_bind(3xti)t_bind(3xti)Namet_bind - bind an address to a transport endpoint
Syntax
#include <xti.h>
int t_bind(fd, req, ret)
int fd;
struct t_bind *req;
struct t_bind *ret;
Arguments
fd Refers to the transport endpoint which will be associated
with a protocol address.
req Points to a t_bind structure containing the following mem‐
bers:
struct netbuf addr;
unsigned qlen;
The addr field of the structure specifies a protocol address,
and the qlen field is used to indicate the maximum number of
outstanding connect indications.
ret Points to a structure. See the req argument.
Description
This function associates a protocol address with the transport endpoint
specified by fd and activates the transport endpoint. In connection
mode, the transport provider can begin enqueuing incoming connect indi‐
cations or servicing a connection request on the transport endpoint. In
connectionless mode, the transport user can send or receive data units
through the transport endpoint.
Parameters Before Call After Call
────────────────────────────────────────────
fd x /
req->addr.maxlen / /
req->addr.len x>=0 /
req->addr.buf x(x) /
req->qlen x>=0 /
ret->addr.maxlen x /
ret->addr.len / x
ret->addr.buf x (x)
ret->qlen / x>=0
────────────────────────────────────────────
The req argument is used to request that an address, represented by the
netbuf structure, be bound to the given transport endpoint. The len
specifies the number of bytes in the address, and buf points to the
address buffer. The maxlen has no meaning for the req argument. On
return, ret contains the address that the transport provider actually
bound to the transport endpoint; this may be different from the address
specified by the user in req. In ret, the user specifies maxlen, which
is the maximum size of the address buffer, and buf, which points to the
buffer where the address is to be placed. On return, len specifies the
number of bytes in the bound address, and buf points to the bound
address. If maxlen is not large enough to hold the returned address, an
error results.
If the requested address is not available, or if no address is speci‐
fied in req (the len field of addr in req is zero), the transport
provider assigns an appropriate address to be bound only if automatic
generation of an address is supported and returns that address in the
addr field of ret. The user can compare the addresses in req and ret to
determine whether the transport provider bound the transport endpoint
to a different address than that requested. In any XTI implementation,
if the function does not allocate a local transport address, then the
returned address is always the same as the input address and the struc‐
ture req->addr must be filled by the user before the call. If the local
address is not furnished for the call (req->addr.len=0), the returns -1
with t_errno set to [TNOADDR].
The req may be NULL if the user does not wish to specify an address to
be bound. Here, the value of qlen is assumed to be zero, and the trans‐
port provider must assign an address to the transport endpoint. Simi‐
larly, ret may be NULL if the user does not care what address was bound
by the provider and is not interested in the negotiated value of qlen.
It is valid to set req and ret to NULL for the same call, in which case
the provider chooses the address to bind to the transport endpoint and
does not return the information to the user.
The qlen field has meaning only when initializing a connection-mode
service. It specifies the number of outstanding connect indications 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. A value of qlen greater than zero is meaningful only when
issued by a passive transport user that expects other users to call it.
The value of qlen will be negotiated by the transport provider and may
be changed if the transport provider cannot support the specified num‐
ber of outstanding connect indications. On return, the qlen field in
ret contains the negotiated value.
This function allows more than one transport endpoint to be bound to
the same protocol address. The transport provider, however, must sup‐
port this capability also, it is not allowable to bind more than one
protocol address to the same transport endpoint. If a user binds more
than one transport endpoint to the same protocol address, only one end‐
point can be used to listen for connect indications associated with the
protocol address.
In other words, only one for a given protocol address can specify a
value of qlen greater than zero. In this way, the transport provider
can identify which transport endpoint should be notified of an incoming
connect indication. If a user attempts to bind a protocol address to a
second transport endpoint with a value of qlen greater than zero, the
transport provider assigns another address to be bound to that endpoint
or, if automatic generation of addresses is not supported, returns -1
and sets t_errno to [TADDRBUSY].
When a user accepts a connection on the transport endpoint that is
being used as the listening endpoint, the bound protocol address will
be found to be busy for the duration of the connection, until a or call
has been issued. No other transport endpoints may be bound for listen‐
ing on that same protocol address while that initial listening endpoint
is active (in the data transfer phase or in the T_IDLE state). This
prevents more than one transport endpoint bound to the same protocol
address from accepting connect indications.
Return Values
Upon successful completion, returns 0 and -1 on failure, and t_errno is
set to indicate the error.
Diagnostics
On failure, t_errno is set to one of the following:
[TBADF] The specified file descriptor does not refer to a
transport endpoint.
[TOUTSTATE] The function was issued in the wrong sequence.
[TBADADDR] The specified protocol address was in an incorrect
format or contained illegal information.
[TNOADDR] The transport provider could not allocate an
address.
[TACCES] The user does not have permission to use the speci‐
fied address.
[TBUFOVFLW] The number of bytes allowed for an incoming argu‐
ment is not sufficient to store the value of that
argument. The provider's state changes to T_IDLE
and the information to be returned in ret is dis‐
carded.
[TSYSERR] A system error has occurred during execution of
this function.
[TADDRBUSY] The address requested is in use and the transport
provider cannot be allocate a new address.
See Alsot_alloc(3xti), t_close(3xti), t_open(3xti), t_optmgmt(3xti),
t_unbind(3xti)t_bind(3xti)
