|Click this button to go to the index for this section.|
NAMEt_bind - Binds an address to a transport endpoint
LIBRARYXTI Library (libxti.a)
SYNOPSIS#include <xti.h> int t_bind( int fd, struct t_bind *req, struct t_bind *ret) ;
STANDARDSInterfaces documented on this reference page conform to industry standards as follows: t_bind: XPG4-UNIX Refer to the standards(5) reference page for more information about industry standards and associated tags.
PARAMETERSThe following table summarizes the relevance of input and output parameters before and after t_bind() is called: ___________________________________________ Parameter Before Call After Call ___________________________________________ fd y n req->addr.maxlen n n req->addr.len y >= 0 n req->addr.buf y(y) n req->qlen y>=0 n ret->addr.maxlen y n ret->addr.len n y ret->addr.buf o (o) ret->qlen n y>= 0 ___________________________________________ Notes to table: y This is a meaningful parameter. n This is not a meaningful parameter. o This is an optional parameter. (y) The content of the object pointed to by y is meaningful. (o) The content of the object pointed to by o is optional. fd Specifies a file descriptor returned by the t_open() function that identifies the local transport endpoint. For connection-mode service, this function allows more than a single transport endpoint to be bound to the same protocol address, provided the transport provider allows this. However, only one protocol address can be bound to a transport endpoint. See the xti_internet(7) reference page for more information. 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. If a transport user attempts to bind a protocol address to a second transport endpoint with a qlen value greater than zero, the t_bind() functions returns -1 and sets t_errno to [TADDRBUSY]. When a user accepts a connection on a transport endpoint that is already the listening endpoint, the bound protocol address is considered busy for the duration of the connection until a t_unbind() or t_close() call is issued. There can be only one passive listening endpoint on a protocol address at any one time. For connectionless-mode service, only one endpoint can be associated with a protocol address. If a user attempts to bind a second transport endpoint to a protocol address that is already bound, t_bind() returns -1 and sets t_errno to [TADDRBUSY]. req Specifies a pointer to a type t_bind() structure that has the following 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. This parameter has no meaning for the req argument. unsigned int len Specifies the number of bytes in the address. char *buf Points to the address buffer location. unsigned qlen 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 has not been accepted or rejected. This field has meaning only when initializing a connection-mode 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. If the requested address is not available, the t_bind() call returns the value -1 and sets t_errno to indicate the error. If the transport user does not specify a protocol address, either by specifying a ret as a NULL pointer or by specifying req->addr.len as 0 (zero), the transport provider assigns an alternate protocol address and returns it in the req->addr.buf field. If the transport provider does not support automatic address generation, the t_bind() call returns the value -1 and sets t_errno to [TNOADDR]. 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 ret parameter may also be specified as a null pointer when the protocol address is not significant. A value of req->qlen greater than 0 (zero) is meaningful only when it is issued by a transport user expecting other transport users to call it. The value of qlen is 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 qlen is never be negotiated from a request value greater than zero to zero; this is a requirement on transport providers. On return, the qlen field in ret contains the negotiated value. ret Specifies a pointer 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. If specified, the address in ret is the same as in req. The transport user must specify the maximum size (in bytes) of the protocol address with the ret->addr.maxlen parameter and the location into which to place the address with the ret->addr.buf parameter. On return, the ret->addr.len parameter specifies the actual number of bytes in the bound protocol address and the ret->addr.buf parameter points to the bound address. When the ret->addr.maxlen parameter is not large enough to hold the returned protocol address, an error occurs.
VALID STATESThe t_bind() function can be called only in the T_UNBND transport provider state.
DESCRIPTIONThe 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.
USAGEA transport provider might not allow more than one transport endpoint to be explicitly bound to the same protocol address, even though more than one connection can be accepted for the same protocol address. Therefore, to ensure code portability do not bind transport endpoints that are also responding endpoints (resfd) in a call to t_accept() when the reponding address and the called address are the same.
RETURN VALUESUpon 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.
ERRORSIf the t_bind() function fails, 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 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. [TPROTO] This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI(t_errno).
RELATED INFORMATIONFunctions: t_accept(3), t_alloc(3), t_close(3), t_open(3), t_optmgmt(3), t_unbind(3). Network information: xti(7), xti_internet(7).