DESCRIPTION
This routine is part of the
XTI interfaces that evolved from the
TLI interfaces.
XTI represents the future evolution of these interfaces. However,
TLI interfaces are supported for compatibility. When using a
TLI routine that has the same name as an
XTI routine, the
<tiuser.h> header file must be used. Refer to the
TLI COMPATIBILITY section for a description of differences between the two interfaces.
This 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 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 arguments point to a
t_bind structure containing the following members:
-
struct netbuf addr;
-
unsigned qlen;
The
addr field of the
t_bind structure specifies a protocol address, and the
qlen field is used to indicate the maximum number of outstanding connection indications.
The parameter
req is used to request that an address, represented by the
netbuf 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. For
tcp(7P) and
udp(7P) transports,
buf points to either a
struct sockaddr_in or
struct sockaddr_in6 buffer (depending on if IPv4 or IPv6 is being used). The parameter
maxlen has no meaning for the
req argument.
On return,
ret contains an encoding for the address that the transport provider actually bound to the transport endpoint; if an address was specified in
req, this will be an encoding of the same address. 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 equals zero, no address is returned. If
maxlen is greater than zero and less than the length of the address,
t_bind() fails with
t_errno set to
TBUFOVFLW.
If the requested address is not available,
t_bind() will return -1 with
t_errno 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,
t_bind() will fail with
t_errno set to
TNOADDR.
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 connection indications that the transport provider should support for the given transport endpoint. An outstanding connection 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 other users 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 connection 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
WARNINGS 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. It is not possible to bind more than one protocol address to the same transport endpoint. However, the transport provider must also support this capability. If a user binds more than one transport endpoint to the same protocol address, only one endpoint can be used to listen for connection indications associated with that protocol address. In other words, only one
t_bind() 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 connection indication. If a user attempts to bind a protocol address to a second transport endpoint with a value of
qlen 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(3NSL) or
t_close(3NSL) 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 connection indications.
If
fd refers to connectionless mode service, this function allows for more than one transport endpoint to be associated with a protocol address, where the underlying transport provider supports this capability (often in conjunction with value of a protocol-specific option). If a user attempts to bind a second transport endpoint to an already bound protocol address when such capability is not supported for a transport provider,
t_bind() will return -1 and set
t_errno to
TADDRBUSY.