t_bind(3)

NAME

t_bind − bind an address to a transport endpoint

SYNOPSIS

#include <xti.h> (for XTI)

#include <tiuser.h> (for TLI)

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

DESCRIPTION

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

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

struct netbuf addr;
unsigned qlen;

The type netbuf structure is defined in the <xti.h> or <tiuser.h> header file. This structure, which is used to define buffer parameters, has the following members:

unsigned int maxlen maximum byte length of the data buffer

unsigned int len actual byte length of data written to buffer

char *buf points to buffer location

The addr field of the t_bind structure uses a netbuf to specify a protocol address.

qlen field is used to indicate the maximum number of outstanding connect indications.

req is used to request that an address, represented by the netbuf structure, be bound to the given transport endpoint. len specifies the number of bytes in the address and buf points to the address buffer. maxlen has no meaning for the req argument. On return, ret contains the address that the transport provider actually bound to the transport endpoint; this may be different from the address specified by the user 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 requested address is not available, or if no address is specified in req (the len field of addr in req is zero) the transport provider will assign an appropriate address to be bound only if automatic generation of an address is supported by the transport provider, and will return that address in the addr field of ret . HP OSI does not support the automatic generation of an address.

The user can compare the addresses in req and ret to determine whether the transport provider bound the transport endpoint to a different address than that requested. If the transport provider does not allocate a local transport address, then the returned address is always the same as the input address and the structure req->addr must be filled by the user before the call; otherwise, if the local address is not furnished for the call (req->addr.len = 0), t_bind will return −1 with t_errno set to [TNOADDR].

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 must 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 a 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 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 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.

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 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, the transport provider will assign another address to be bound to that endpoint or, if automatic generation of addresses is not supported, the transport provider will return -1 and set t_errno to [TADDRBUSY] (for XTI) or [TBADADDR] (for 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 t_unbind (3) or t_close (3) call has been issued. No other transport endpoints may be bound for listening on that same protocol address while that initial listening endpoint is active (in the data transfer phase or in the T_IDLE state). This will prevent more than one transport endpoint bound to the same protocol address from accepting connect indications.

t_bind can only be called in the T_UNBND transport provider state.

ERRORS

On failure, t_errno 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 state.

[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 ret will be discarded.

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

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

RETURN VALUE

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

FILES

For more information on data structures refer to /usr/include/xti.h and /usr/include/xti_iso.h for XTI, or /usr/include/tiuser.h for TLI.

NOTE

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

In HP-UX 9.0, XTI (X/Open Transport Interface) supports only OSI as a transport provider, and is available only as part of the OSI Transport Services 9000 product. Users of this product can access XTI versions of the t_* routines by linking with /usr/lib/libxti.a. For more information on XTI, see "HP-UX/9000 XTI Programmer’s Guide".

In HP-UX 9.0, TLI (Transport Layer Interface) supports any transport provider which is compliant with TPI (Transport Provider Interface). TLI is available only as part of the STREAMS product. Users of this product can access TLI versions of the t_* routines by linking with /usr/lib/libnsl_s.a. For more information on TLI, see the TLI section of "STREAMS/UX for HP 9000 Reference Manual".

Museum

Related Articles