t_bind(3)t_bind(3)NAMEt_bind() - bind an address to a transport endpoint
SYNOPSISDESCRIPTION
The function associates a protocol address with the transport endpoint
specified by fd and activates that transport endpoint. In connection
mode, the transport provider may begin enqueuing incoming connect indi‐
cations 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 arguments point to a structure containing the following
members:
The type structure is defined in the or header file. This structure,
which is used to define buffer parameters, has the following members:
maximum byte length of the data buffer
actual byte length of data written to buffer
points to buffer location
The addr field of the structure specifies a protocol address. The qlen
field is used to indicate the maximum number of outstanding connect
indications.
The parameter req is used to request that an address, represented by
the structure, be bound to the given transport endpoint. The parameter
len specifies the number of bytes in the address, and buf points to the
address buffer. The parameter maxlen has no meaning for the req argu‐
ment. On return, ret contains the address of that the transport
provider actually bound to the transport endpoint. This is the same as
the address specified 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 will result.
If the request address is not available, will return −1 with set as
appropriate. If no address is specified in req (the len field of addr
in req is zero or req is NULL), the transport provider will assign an
appropriate address to be bound, and will return that address in the
addr field of ret. If the transport provider could not allocate an
address, will fail with set to [TNOADDR]. HP OSI does not support the
automatic generation of an address.
The parameter req may be a null pointer 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 transport provider will assign an address to the
transport endpoint. Similarly, ret may be a null pointer if the user
does not care what address was bound by the provider and is not inter‐
ested in the negotiated value of qlen. It is valid to set req and ret
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.
The qlen field has meaning only when initializing a connection-mode
service. It specifies the number of outstanding connect indications
that the transport provider should support for the given transport end‐
point. 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 value of qlen greater than zero is only mean‐
ingful when issued by a passive transport user that expects others 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 number of outstanding connect indications. However, this
value of qlen will never be negotiated from a requested value greater
than zero to zero. This is a requirement on transport providers; see
below. On return, the qlen field in ret will contain the negotiated
value.
If fd 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),
but it is not possible to bind more than one protocol address to the
same transport endpoint. If a user binds more than one transport end‐
point to the same protocol address, only one endpoint can be used to
listen for the connect indications associated with that protocol
address. In other words, only one for a given protocol address may
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, will return −1 and set to [TADDRBUSY] (XTI) or [TBADADDR]
(TLI). 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
listening on the same protocol address while that initial listening
endpoint is active (in the data transfer phase or in the state). This
will prevent more than one transport endpoint bound to the same proto‐
col address from accepting connect indications.
If fd refers to a connectionless-mode service, only one endpoint may be
associated with a protocol address. If a user attempts to bind a sec‐
ond transport endpoint to an already bound address, will return −1 and
set to [TADDRBUSY].
Valid States
Note
HP XTI does not support automatic generation of addresses. Therefore a
valid local transport address must be specified in req.
Caveats
The requirement that the value of qlen never be negotiated from a
requested value greater than zero to zero implies that transport
providers, rather than the XTI 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 (resfd) in a call to if
the responding address is to be the same as the called address.
Fork Safety
is not fork-safe.
RETURN VALUE
Upon successful completion, a value of 0 is returned. Otherwise, a
value of −1 is returned and is set to indicate the error.
ERRORS
On failure, 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 will change to and
the information to be returned in ret will be dis‐
carded.
[TSYSERR] A system error has occurred during execution of
this function.
[TADDRBUSY] The address requested is in use and the transport
provider could not allocate a new address.
[TPROTO] (XTI only) This error indicates that a communica‐
tion problem has been detected between XTI and the
transport provider for which there is no suitable
XTI (
FILES
XTI data structures
XTI data structures
TLI data structures
SEE ALSOt_alloc(3), t_close(3), t_open(3), t_unbind(3), thread_safety(5).
STANDARDS CONFORMANCEt_bind(3)