 |
Click this button to go to the index for this section. |
t_bind(3)
NAME
t_bind - Binds an address to a transport endpoint
LIBRARY
XTI Library (libxti.a)
SYNOPSIS
#include <xti.h>
int t_bind(
int fd,
struct t_bind *req,
struct t_bind *ret) ;
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
t_bind: XPG4-UNIX
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 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:
y This is a meaningful parameter.
n This is not a meaningful parameter.
o This is an optional parameter.
(y) The content of the object pointed to by y is meaningful.
(o) The content of the object pointed to by o is optional.
fd 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].
req Specifies a pointer to a type t_bind() structure that has the following
members:
struct netbuf addr
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:
unsigned int maxlen
Specifies the maximum byte length of the data buffer. This
parameter has no meaning for the req argument.
unsigned int len
Specifies the number of bytes in the address.
char *buf
Points to the address buffer location.
unsigned qlen
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.
ret 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 the actual 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.
VALID STATES
The t_bind() function can be called only in the T_UNBND transport provider
state.
DESCRIPTION
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.
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.
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 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 specified address.
[TBUFOVFLW]
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.
[TSYSERR] A system error occurred during execution of this function.
[TADDRBUSY]
The address requested is in use and the transport provider could
not allocate a new address.
[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(t_errno).
RELATED INFORMATION
Functions: t_accept(3), t_alloc(3), t_close(3), t_open(3), t_optmgmt(3),
t_unbind(3).
Network information: xti(7), xti_internet(7).