t_bind(3)						     Library Functions Manual							 t_bind(3)

NAME

       t_bind() - bind an address to a transport endpoint

SYNOPSIS

DESCRIPTION

       The  function  associates a protocol address with the transport endpoint specified by fd and activates that transport endpoint.	In connec-
       tion mode, the transport provider may begin enqueuing incoming connect indications or servicing a connection request on the transport  end-
       point.  In connectionless mode, the transport user may send or receive data units through the transport endpoint.

       The req and ret arguments point to a structure containing the following members:

       The type structure is defined in the or header file.  This structure, which is used to define buffer parameters, has the following members:

       maximum byte length of the data buffer

       actual byte length of data written to buffer

       points to buffer location

       The addr field of the structure specifies a protocol address.  The qlen field is used to indicate the maximum number of outstanding connect
       indications.

       The parameter req is used to request that an address, represented by the structure, be bound to the given transport endpoint.  The  parame-
       ter  len  specifies  the number of bytes in the address, and buf points to the address buffer.  The parameter maxlen has no meaning for the
       req argument.  On return, ret contains the address of that the transport provider actually bound to the transport endpoint.   This  is  the
       same  as  the  address specified in req.  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 is not large enough to hold the returned address, an error will result.

       If  the request address is not available, will return -1 with 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, will fail with set to [TNOADDR].  HP OSI does not support the
       automatic generation of an address.

       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  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 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 others 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.   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 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
       (however,  the  transport provider must also support this capability), but it is not possible 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 the connect indications associated with that protocol address.  In other words, only one for a given protocol address may spec-
       ify a value of qlen greater than zero.  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 zero, will return -1 and set to [TADDRBUSY] (XTI) or [TBADADDR] (TLI).  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 or call has been issued.  No other transport endpoints may be bound for listening on the same protocol address while that initial listen-
       ing  endpoint is active (in the data transfer phase or in the state).  This will prevent more than one transport endpoint bound to the same
       protocol address from accepting connect indications.

       If fd refers to a connectionless-mode service, only one endpoint may be associated with a protocol address.  If a user attempts to  bind  a
       second transport endpoint to an already bound address, will return -1 and set to [TADDRBUSY].

   Valid States
   Note
       HP XTI does not support automatic generation of addresses. Therefore a valid local transport address must be specified in req.

   Caveats
       The  requirement  that  the  value  of  qlen  never  be	negotiated from a requested value greater than zero to zero implies that transport
       providers, rather than the XTI implementation itself, accept this restriction.

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

   Fork Safety
       is not fork-safe.

RETURN VALUE

       Upon successful completion, a value of 0 is returned.  Otherwise, a value of -1 is returned and is set to indicate the error.

ERRORS

       On failure, is 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 and the information to be returned in ret will be discarded.

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

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

       [TPROTO] 	   (XTI only) This error indicates that a communication problem has been detected between XTI and the  transport  provider
			   for which there is no suitable XTI (

FILES

       XTI data structures

       XTI data structures

       TLI data structures

SEE ALSO

       t_alloc(3), t_close(3), t_open(3), t_unbind(3), thread_safety(5).

STANDARDS CONFORMANCE

																	 t_bind(3)