t_bind(3xti)


t_bind -- bind an address to a transport endpoint

Synopsis

cc [options] file -lnsl
#include <xti.h>

int t_bind(int fd, struct t_bind *req, struct t_bind *ret)

Description

This function is a TLI/XTI local management routine that associates a protocol address with the transport endpoint specified by fd and activates the endpoint.

If fd refers to a connection-mode service, the transport provider may then begin listening for connect indications on that endpoint (t_listen), or the provider may begin sending connection requests from that transport endpoint (t_connect).

If fd refers to a connectionless service, the transport user may then proceed with sending or receiving data units through the transport endpoint (t_snd, t_rcv).

Parameters


fd
the file descriptor for the transport endpoint

req
points to the t_bind structure used to identify the request.

ret
points to the t_bind structure used to identify the return.

Structure definitions

The req and ret arguments point to a t_bind structure containing the following members:
   struct netbuf addr;     /* address               */
   unsigned qlen;          /* connect indications   */
The netbuf addr fields (len, maxlen and buf) are described in intro(3xti). len specifies the number of bytes in the address, buf points to the address buffer, and maxlen is the maximum size of the address buffer. The qlen field, in connection mode only, is used to indicate the maximum number of outstanding connect indications.

In req, len and buf are used to specify the protocol address to be bound to the transport endpoint. maxlen has no meaning for the req argument.

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, ret contains the bound address. This is the same as the address specified by the user in req. 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 requested address is not available, t_bind fails with an error and t_errno is set to TADDRBUSY.

If no address is specified in req (the len field in addr is 0 or req is NULL), the transport provider will assign an appropriate address to be bound, and will return that address in ret.

req may be NULL if the user does not want to specify the protocol address to be bound. Here, the value of qlen is assumed to be zero, and the transport provider must assign an address to the transport endpoint. Similarly, ret may be NULL 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 also valid to set req and ret to NULL 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 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. A value of qlen greater than 0 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 connect indications. On return, the qlen field in ret will contain the negotiated value.

State transitions

On entry, T_UNBND; T_IDLE on exit.

Files


/usr/lib/libxti.so
X/Open® Transport Interface Library (shared object)

/usr/lib/libnsl.so
Network Services Library (shared object)

Usage

The following notes are for connection-mode service.

This function allows more than one transport endpoint to be bound to the same protocol address (however, the transport provider must support this capability also), but it is not allowable 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 connect 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 0. 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 0, t_bind will fail with TADDRBUSY.

A transport provider may not allow an explicit binding of more than one endpoint to the same protocol address, although it allows more than one connection to be accepted (see t_accept) for the same protocol address. To ensure portability, it is recommended not to bind transport endpoints that are used as responding endpoints (resfd) in a call to t_accept, if the responding address is to be the same as the called address.

If 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 that connection. No other transport endpoints may be bound for listening while that initial listening endpoint is in the data transfer phase. This will prevent more than one transport endpoint bound to the same protocol address from accepting connect indications.

Return values

t_bind returns 0 on success and -1 on failure and t_errno is set to indicate the error.

Errors

On failure, 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 (maxlen) allocated for an incoming argument is greater than zero but 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 ret will be discarded.

TSYSERR
A system error has occurred during execution of this function.

TADDRBUSY
In connection mode, the requested address has already been bound to another transport endpoint.

TPROTO
A communication problem has been detected with the transport provider and there is no other value of t_errno to describe the error condition.

Warnings

Note that the behavior of t_bind has changed in order to conform to X/OPEN's TLI/XTI specifications. Previously, if req was specified t_bind returned an alternate address if the one requested was busy. Now, t_bind will fail and t_error will be set to TADDRBUSY. Thus now, in case of failure, applications need to check the value of t_errno and repeat the call with a different address if the one requested is busy (or not request a specific address). Also, applications need not verify the address they were bound to if they requested an address and t_bind succeeded.

References

fork(2), intro(3xti), t_accept(3xti), t_alloc(3xti), t_connect(3xti), t_listen(3xti), t_open(3xti), t_optmgmt(3xti), t_unbind(3xti)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004