t_bind(3) Library Functions Manual t_bind(3)
NAME
t_bind() - bind an address to a transport endpoint
SYNOPSIS
DESCRIPTION
The function associates a protocol address with the transport endpoint specified by fd and activates that transport endpoint. In connec-
tion mode, the transport provider may begin enqueuing incoming connect indications or servicing a connection request on the transport end-
point. 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 parame-
ter 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 argument. 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 interested 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 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 value of qlen greater than zero is only
meaningful 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 endpoint 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 spec-
ify 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 listen-
ing endpoint is active (in the data transfer phase or in the state). This will prevent more than one transport endpoint bound to the same
protocol 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
second 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 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 and the information to be returned in ret will be discarded.
[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 communication 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 ALSO
t_alloc(3), t_close(3), t_open(3), t_unbind(3), thread_safety(5).
STANDARDS CONFORMANCE
t_bind(3)