t_bind Subroutine for Transport Layer Interface

Purpose

Binds an address to a transport end point.

Library

Transport Layer Interface Library (libtli.a)

Syntax

#include <tiuser.h>

Description

The t_bind subroutine associates a protocol address with the transport end point specified by the fd parameter and activates that transport end point. In connection mode, the transport provider may begin accepting or requesting connections on the transport end point. In connectionless mode, the transport user may send or receive data units through the transport end point.

Parameters

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

struct netbuf addr;
unsigned qlen;

The netbuf structure is described in the tiuser.h file. The addr field of the t_bind structure specifies a protocol address and the qlen field is used to indicate the maximum number of outstanding connect indications.

The req parameter is used to request that the address represented by the netbuf structure be bound to the given transport end point. In the req parameter, the netbuf structure fields have the following meanings:

On return, the ret parameter contains the address that the transport provider actually bound to the transport end point; this may be different from the address specified by the user in the req parameter. In the ret parameter, the netbuf structure fields have the following meanings:

If the value of the maxlen field 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 the req parameter (that is, the len field of the addr field in the req parameter is 0) the transport provider assigns an appropriate address to be bound and returns that address in the addr field of the ret parameter. The user can compare the addresses in the req parameter to those in the ret parameter to determine whether the transport provider has bound the transport end point to a different address than that requested. If the transport provider could not allocate an address, the t_bind subroutine fails and t_errno is set to TNOADDR.

The req parameter may be null if the user does not wish to specify an address to be bound. Here, the value of the qlen field is assumed to be 0, and the transport provider must assign an address to the transport end point. Similarly, the ret parameter may be null if the user does not care which address was bound by the provider and is not interested in the negotiated value of the qlen field. It is valid to set the req and ret parameters to null for the same call, in which case the provider chooses the address to bind to the transport end point 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 end point. An outstanding connect indication is one that has been passed to the transport user by the transport provider. A value of the qlen field greater than 0 is only meaningful when issued by a passive transport user that expects other users to call it. The value of the qlen field is negotiated by the transport provider and can be changed if the transport provider cannot support the specified number of outstanding connect indications. On return, the qlen field in the ret parameter contains the negotiated value.

This subroutine allows more than one transport end point to be bound to the same protocol address as long as the transport provider also supports this capability. However, it is not allowable to bind more than one protocol address to the same transport end point. If a user binds more than one transport end point to the same protocol address, only one end point can be used to listen for connect indications associated with that protocol address. In other words, only one t_bind subroutine for a given protocol address may specify a value greater than 0 for the qlen field. In this way, the transport provider can identify which transport end point should be notified of an incoming connect indication. If a user attempts to bind a protocol address to a second transport end point having a qlen value greater than 0, the transport provider instead assigns another address to be bound to that end point. If a user accepts a connection on the transport end point that is being used as the listening end point, the bound protocol address is found to be busy for the duration of that connection. No other transport end points may be bound for listening while that initial listening end point is in the data-transfer phase. This prevents more than one transport end point bound to the same protocol address from accepting connect indications.

Return Values

On successful completion, the t_connect subroutine returns a value of 0. Otherwise, it returns a value of -1, and the t_errno variable is set to indicate the error.

Error Codes

If unsuccessful, the t_errno variable is set to one of the following: