t_bind(3N) t_bind(3N)
NAME
t_bind - bind an address to a transport endpoint
SYNOPSIS
cc [options] file -lnsl
#include <xti.h>
int t_bind(int fd, struct t_bind *req, struct t_bind *ret)
Parameters
fd the file descriptor for the transport endpoint
req points to the t_bind structure used to identify the
request.
ret points to the t_bind structure used to identify the
return.
DESCRIPTION
This function is a TLI/XTI local management routine that
associates a protocol address with the transport endpoint
specified by fd and activates the endpoint.
If fd refers to a connection-mode service, the transport
provider may then begin listening for connect indications on
that endpoint (t_listen), or the provider may begin sending
connection requests from that transport endpoint (t_connect).
If fd refers to a connectionless service, the transport user
may then proceed with sending or receiving data units through
the transport endpoint (t_snd, t_rcv).
Structure Definitions
The req and ret arguments point to a t_bind structure
containing the following members:
struct netbuf addr; /* address */
unsigned qlen; /* connect indications */
The netbuf addr fields (len, maxlen and buf) are described in
intro(3). len specifies the number of bytes in the address,
buf points to the address buffer, and maxlen is the maximum
size of the address buffer. The qlen field, in connection
mode only, is used to indicate the maximum number of
outstanding connect indications.
Copyright 1994 Novell, Inc. Page 1
t_bind(3N) t_bind(3N)
In req, len and buf are used to specify the protocol address
to be bound to the transport endpoint. maxlen has no meaning
for the req argument.
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, ret contains the bound address. This is the same
as the address specified by the user in req. 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, t_bind fails with an error and
t_errno is set to TADDRBUSY.
If no address is specified in req (the len field in addr is 0
or req is NULL), the transport provider will assign an
appropriate address to be bound, and will return that address
in ret.
req may be NULL if the user does not want to specify the
protocol 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
provider and is not interested in the negotiated value of
qlen.
It is also 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
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. A value of qlen
greater than 0 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
Copyright 1994 Novell, Inc. Page 2
t_bind(3N) t_bind(3N)
value.
Return Values
t_bind returns 0 on success and -1 on failure and t_errno is
set to indicate the error.
Errors
On failure, t_errno may be 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 (maxlen) allocated for an
incoming argument is greater than zero but 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
In connection mode, the requested address has already
been bound to another transport endpoint.
TPROTO A communication problem has been detected with the
transport provider and there is no other value of
t_errno to describe the error condition.
State Transitions
On entry, T_UNBND; T_IDLE on exit.
Copyright 1994 Novell, Inc. Page 3
t_bind(3N) t_bind(3N)
Files
/usr/lib/libxti.so
X/Open Transport Interface Library (shared
object)
/usr/lib/libnsl.so
Network Services Library (shared object)
USAGE
The following notes are for connection-mode service.
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 0. 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 0, t_bind
will fail with TADDRBUSY.
A transport provider may not allow an explicit binding of more
than one endpoint to the same protocol address, although it
allows more than one connection to be accepted (see t_accept)
for the same protocol address. To ensure portability, it is
recommended not to bind transport endpoints that are used as
responding endpoints (resfd) in a call to t_accept, if the
responding address is to be the same as the called address.
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
connection. No other transport endpoints may be bound for
listening 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.
Copyright 1994 Novell, Inc. Page 4
t_bind(3N) t_bind(3N)
Warnings
Note that the behavior of t_bind has changed in order to
conform to X/OPEN's TLI/XTI specifications. Previously, if
req was specified t_bind returned an alternate address if the
one requested was busy. Now, t_bind will fail and t_error
will be set to TADDRBUSY. Thus now, in case of failure,
applications need to check the value of t_errno and repeat the
call with a different address if the one requested is busy (or
not request a specific address). Also, applications need not
verify the address they were bound to if they requested an
address and t_bind succeeded.
REFERENCES
fork(2), intro(3), t_accept(3N), t_alloc(3N), t_connect(3N),
t_listen(3N), t_open(3N), t_optmgmt(3N), t_unbind(3N)
Copyright 1994 Novell, Inc. Page 5