*** UNIX MANUAL PAGE BROWSER ***

t_bind(3) Library Functions Manual t_bind(3) 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) ; STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: t_bind: XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS The following table summarizes the relevance of input and output para- meters before and after t_bind() is called: tab(@); lfHB lfHB lfHB l l l. _ 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. 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 ad- dress, 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 lis- ten for connect indications associated with that protocol ad- dress 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 [TADDR- BUSY]. When a user accepts a connection on a transport endpoint that is already the listening endpoint, the bound protocol ad- dress is considered busy for the duration of the connection un- til 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 asso- ciated 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]. Specifies a pointer to a type t_bind() structure that has the following members: Specifies a buffer for protocol address in- formation sent by the calling transport user. The type netbuf structure referenced by this member is defined in the xti.h in- clude file. This structure, which is used to specify the address to be bound to the endpoint, has the following members: Speci- fies the maximum byte length of the data buffer. This parameter has no meaning for the req argument. Specifies the number of bytes in the address. Points to the address buffer location. Specifies the number of outstanding connect indications that the transport provider should support for the given transport end- point. 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, ei- ther by specifying a ret as a NULL pointer or by specifying req->addr.len as 0 (zero), the transport provider assigns an al- ternate protocol address and returns it in the req->addr.buf field. If the transport provider does not support automatic ad- dress 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 bind- ing. 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 trans- port provider and may be changed if the transport provider can- not support the specified number of outstanding connect indica- tions. 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 con- tains the negotiated value. 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 re- turned protocol address, an error occurs. VALID STATES The t_bind() function can be called only in the T_UNBND transport provider state. DESCRIPTION The t_bind() XTI function is used in connectionless and connection-ori- ented transport service to associate a protocol address with the trans- port endpoint returned by the t_open() function and to activate that transport endpoint. This function uses type t_bind() and netbuf struc- tures, 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 func- tion has been called, the transport user may send or receive data units through the transport endpoint. USAGE A 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 VALUES 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 follow- ing: The specified file descriptor does not refer to a transport end- point. The function was issued in the wrong sequence. The specified protocol address was in an incorrect format or contained illegal infor- mation. The transport provider could not allocate an address. The user does not have permission to use the specified address. 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 dis- carded. A system error occurred during execution of this function. The address requested is in use and the transport provider could not allocate a new address. 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 INFORMATION Functions: t_accept(3), t_alloc(3), t_close(3), t_open(3), t_opt- mgmt(3), t_unbind(3). Network information: xti(7), xti_internet(7). delim off t_bind(3)