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) ;

PARAMETERS

The t_bind() function can only be called in the T_UNBND transport provider state. The following table summarizes the relevance of input and output parameters before and after t_bind() is called:

Notes to table:

yThis is a meaningful parameter.
nThis is not a meaningful parameter.
(y)The content of the object pointed to by y is meaningful.

fd Specifies a file descriptor returned by the t_open() function that identifies the local transport endpoint. More than a single transport endpoint may be bound to the same protocol address, but only one protocol address can be bound to a transport endpoint.

  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 is called. 

  No other transport endpoint may be bound for listening to that same protocol address when the initial listening endpoint is active, during data transfer, or during the T_IDLE state. This prevents more than one transport endpoint, which is bound to the same protocol address, from accepting any connect indication. 

req Points to a type t_bind() structure used to define the protocol address of the caller and to hold the allowable number of outstanding connect indications in connection-oriented transport protocol service. An outstanding connect indication is one that has been passed to the transport provider, but has not been accepted or rejected. The t_bind() structure has the following two members:

struct netbuf    addr
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:

unsigned int   maxlen
Specifies the maximum byte length of the data buffer.

unsigned int   len
Specifies the actual byte length of data written to the buffer.

char   ∗buf
Points to the buffer location.

unsigned    qlen
Specifies the allowable number of outstanding connect indications in connection-oriented 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. 

  When the protocol address is not available, or when 0 (zero) is specified for ­req->addr.len, the transport provider assigns an alternate protocol address whenever automatic address generation is supported. A pointer to the returned alternate protocol address is specified by ­req->addr.buf. 

  When a transport user does not specify a protocol address, the value 0 (zero) is used for ­req->addr.len. When the transport provider does not support automatic address generation and the value 0 (zero) is specified by ­req->addr.len as the data buffer length, a t_bind() call returns the value -1 and sets t_errno to [TNOADDR]. 

  A value greater than 0 (zero) for ­req->qlen has meaning whenever it is specified by a transport user expecting other transport users to call it. When the transport provider can not support the requested number of allowable outstanding connections, the value returned in ­ret->qlen may be different than the one requested. 

  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 req parameter may also be specified as a null pointer when the protocol address is not significant. 

  When the protocol addresses pointed to by the req and ret parameters are not the same, a protocol address different than the one specified by req has been bound to the transport endpoint by the transport provider. 

  When the t_bind() function does not allocate a local transport protocol address (that is, automatic address generation is not supported), the protocol address pointed to by the ret parameter is always the same as the protocol address pointed to by the req parameter. In this case, values for variables pointed to by this parameter must be specified before the t_bind() function is called.

ret Points 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. The bound address may be different than the address pointed to by the transport user with the ­req->addr.buf parameter. 

  The transport user must specify the maximum size in bytes of the protocol address with the  ­ret->addr.maxlen parameter. On return, the ret->addr.len parameter specifies the actual number of bytes in the bound protocol address. When the ­ret->addr.maxlen parameter is not large enough to hold the returned protocol address, an error occurs. 

  The ­ret->qlen parameter, which specifies the allowable number of outstanding connect indications that the transport provider can support, is meaningful only when initializing connection-oriented transport provider service. 

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. 

RETURN VALUE

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 values:

[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 T_IDLE and the information to be returned in the ret parameter will be discarded. 

[TSYSERR] A system error occurred during execution of this function. 

[TADDRBUSY]
The address requested is in use and the transport provider could not allocate a new address.

RELATED INFORMATION

Functions: t_alloc(3), t_close(3), t_open(3), t_optmgmt(3), t_unbind(3)