Content-type: text/html
Man page of t_bind
t_bind
Section: C Library Functions (3)
Index
Return to Main Contents
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.
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 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:
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).
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).
delim off
Index
- NAME
-
- LIBRARY
-
- SYNOPSIS
-
- STANDARDS
-
- PARAMETERS
-
- VALID STATES
-
- DESCRIPTION
-
- USAGE
-
- RETURN VALUES
-
- ERRORS
-
- RELATED INFORMATION
-
This document was created by
man2html,
using the manual pages.
Time: 02:41:11 GMT, October 02, 2010