TBIND(3N-SVR4) RISC/os Reference Manual TBIND(3N-SVR4)
NAME
t_bind - bind an address to a transport endpoint
SYNOPSIS
#include <tiuser.h>
int tbind (fd, req, ret)
int fd;
struct tbind *req;
struct tbind *ret;
DESCRIPTION
This function associates a protocol address with the tran-
sport endpoint specified by fd and activates that transport
endpoint. In connection mode, the transport provider may
begin accepting or requesting connections 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 tbind structure con-
taining the following members:
struct netbuf addr;
unsigned qlen;
netbuf is described in intro(3). The addr field of the
tbind structure specifies a protocol address and the 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 [see netbuf in intro(3); also for buf and maxlen] speci-
fies the number of bytes in the address and buf points to
the address buffer. maxlen has no meaning for the req argu-
ment. On return, ret contains the address that the tran-
sport 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 may assign an appropriate address to
be bound, and will return that address in the addr field of
ret. 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.
Printed 11/19/92 Page 1
TBIND(3N-SVR4) RISC/os Reference Manual TBIND(3N-SVR4)
req may be NULL 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 NULL if
the user does not care what address was bound by the pro-
vider and is not interested in the negotiated value of qlen.
It is valid to set req and ret to NULL 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 out-
standing connect indications the transport provider should
support for the given transport endpoint. An outstanding
connect indication is one that has been passed to the tran-
sport user by the transport provider. A value of qlen
greater than zero is only meaningful when issued by a pas-
sive transport user that expects other users to call it.
The value of qlen will be negotiated by the transport pro-
vider and may be changed if the transport provider cannot
support the specified number of outstanding connect indica-
tions. 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 tbind 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. If 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 that connec-
tion. No other transport endpoints may be bound for listen-
ing while that initial listening endpoint is in the data
transfer phase. This will prevent more than one transport
endpoint bound to the same protocol address from accepting
connect indications.
On failure, t_errno may be set to one of the following:
[TBADF] The specified file descriptor does not
Page 2 Printed 11/19/92
TBIND(3N-SVR4) RISC/os Reference Manual TBIND(3N-SVR4)
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 incom-
ing 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 execu-
tion of this function.
SEE ALSO
intro(3), t_open(3N), t_optmgmt(3N), t_unbind(3N).
DIAGNOSTICS
tbind returns 0 on success and -1 on failure and t_errno is
set to indicate the error.
Printed 11/19/92 Page 3