[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 2
t_bind Subroutine for X/Open Transport Interface
Purpose
Bind an address to a transport endpoint.
Library
X/Open Transport Interface Library (libxti.a)
Syntax
#include <xti.h>
int t_bind (fd, req, ret)
int fd;
const struct t_bind *req;
struct t_bind *ret;
Description
The t_bind subroutine associates
a protocol address with the transport endpoint specified by the fd parameter and activates that transport endpoint. In connection mode,
the transport provider may begin enqueuing incoming connect indications or
servicing a connection request on the transport endpoint. In connectionless
mode, the transport user may send or receive data units through the transport
endpoint.
The req and ret parameters point to a t_bind structure containing
the following members:
struct netbuf addr;
unsigned qlen;
Within this structure, the fields have the following
meaning:
Field |
Description |
addr |
Specifies a protocol address. |
qlen |
Indicates the maximum number of outstanding connect indications. |
If the requested address is not available, the t_bind subroutine returns -1 with t_errno set as appropriate. If no address is specified
in the req parameter, (that is, the len field of the addr field in the req parameter is zero or the req parameter is
NULL), the transport provider assigns an appropriate address to be bound,
and returns that address in the addr field of the ret parameter. If the transport provider could not allocate
an address, the t_bind subroutine fails with t_errno set to TNOADDR.
The qlen field has meaning
only when initializing a connection-mode service. This field 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 which has not been accepted or rejected. A qlen
field value of greater than zero is only meaningful when issued by a passive
transport user that expects other users to call it. The value of the qlen field 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 of the qlen field is never negotiated from a requested value greater than zero
to zero. This is a requirement on transport providers. See "Implementation
Specifics" for more information. On return, the qlen
field in the ret parameter contains the negotiated
value.
The requirement that the value of the qlen field never be negotiated from a requested value greater than zero
to zero implies that transport providers, rather than the X/Open Transport Interface implementation
itself, accept this restriction.
A transport provider may not allow an explicit binding
of more than one transport endpoint to the same protocol address, although
it allows more than one connection to be accepted for the same protocol address.
To ensure portability, it is, therefore, recommended not to bind transport
endpoints that are used as responding endpoints, (those specified in the resfd parameter), in a call to the t_accept subroutine, if the responding address is to be the same as the called
address.
Parameters
fd |
Specifies the transport endpoint. If the fd
parameter refers to a connection-mode service, this function allows more
than one transport endpoint to be bound to the same protocol address. However,
the transport provider must also support this capability and it is not possible
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 endpoint can be used to listen for connect indications associated
with that protocol address. In other words, only one t_bind for a given protocol address may specify a qlen field value 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 a qlen field value greater than zero, t_bind will return -1 and set 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 t_unbind or t_close call has been issued. No other transport endpoints
may be bound for listening on that same protocol address while that initial
listening endpoint is active (in the data transfer phase or in the T_IDLE state). This will prevent more than one transport endpoint bound
to the same protocol address from accepting connect indications.
If the fd parameter refers to a connectionless-mode service,
only one endpoint may be associated with a protocol address. If a user attempts
to bind a second transport endpoint to an already bound protocol address, t_bind will return -1 and set t_errno to TADDRBUSY. |
req |
Specifies the address to be bound to the given transport endpoint.
The req parameter is used to request that an address,
represented by the netbuf structure, be bound to the
given transport endpoint. The netbuf structure is described
in the xti.h file. In the req
parameter, the netbuf structure addr fields have the following meanings:
- buf
- Points to the address buffer.
- len
- Specifies the number of bytes in the address.
- maxlen
- Has no meaning for the req parameter.
The req parameter may
be a null pointer if the user does not specify an address to be bound. Here,
the value of the qlen field is assumed to be zero,
and the transport provider assigns an address to the transport endpoint.
Similarly, the ret parameter may be a null pointer
if the user does not care what address was bound by the provider and is not
interested in the negotiated value of the qlen field.
It is valid to set the req and ret parameters to the null pointer for the same call, in which case
the provider chooses the address to bind to the transport endpoint and does
not return that information to the user. |
ret |
Specifies the maximum size of the address buffer. On return, the
ret parameter contains the address that the transport
provider actually bound to the transport endpoint; this is the same as the
address specified by the user in the req parameter.
In the ret parameter, the netbuf structure fields have the following meanings:
- buf
- Points to the buffer where the address is to be placed. On return,
this points to the bound address.
- len
- Specifies the number of bytes in the bound address on return.
- maxlen
- Specifies the the maximum size of the address buffer. If the value
of the maxlen field is not large enough to hold the
returned address, an error will result.
|
Valid States
T_UNBIND.
Return Values
0 |
Successful completion. |
-1 |
t_errno is set to indicate an error. |
Error Codes
On failure, t_errno is set to
one of the following:
Value |
Description |
TACCES |
The user does not have permission to use the specified address. |
TADDRBUSY |
The requested address is in use. |
TBADADDR |
The specified protocol address was in an incorrect format or contained
illegal information. |
TBADF |
The specified file descriptor does not refer to a transport endpoint. |
TBUFOVLW |
The number of bytes allowed for an incoming argument (maxlen) is greater than 0 but 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 ret will be
discarded. |
TNOADDR |
The transport provider could not allocate an address. |
TOUTSTATE |
The function was issued in the wrong sequence. |
TPROTO |
This error indicates that a communication problem has been detected
between the X/Open Transport Interface and the transport provider for which there is no
other suitable X/Open Transport Interface (t_errno). |
TSYSERR |
A system error has occurred during execution of this function. |
Related Information
The t_alloc subroutine, t_close
subroutine, t_open subroutine, t_optmgmt subroutine, t_unbind subroutine.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]