Networking Services Library Functions tbind(3NSL)
NAME
tbind - bind an address to a transport endpoint
SYNOPSIS
#include
int tbind(int fd, const struct tbind *req, struct tbind *ret);
DESCRIPTION
This routine is part of the XTI interfaces that evolved from
the TLI interfaces. XTI represents the future evolution of
these interfaces. However, TLI interfaces are supported for
compatibility. When using a TLI routine that has the same
name as an XTI routine, the tiuser.hheader file must be
used. Refer to the TLI COMPATIBILITY section for a
description of differences between the two interfaces.
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 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 tbind structure con-
taining the following members:
struct netbuf addr;
unsigned qlen;
The addr field of the tbind structure specifies a protocol
address, and the qlen field is used to indicate the maximum
number of outstanding connection indications.
The parameter req is used to request that an address,
represented by the netbuf structure, be bound to the given
transport endpoint. The parameter 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 an encoding for the
address that the transport provider actually bound to the
transport endpoint; if an address was specified in req,
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions tbind(3NSL)
this will be an encoding of the same address. 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 equals zero, no address is returned. If
maxlen is greater than zero and less than the length of the
address, tbind() fails with terrno set to TBUFOVFLW.
If the requested address is not available, tbind() will
return -1 with terrno set as appropriate. If no address is
specified in req (the len field of addr in req is zero or
req is NUL), 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, tbind() will fail with
terrno set to TNOADR.
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 nego-
tiated 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 out-
standing connection indications that the transport provider
should support for the given transport endpoint. An out-
standing connection 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 tran-
sport 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 speci-
fied number of outstanding connection 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 WARNINGS 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
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions tbind(3NSL)
same protocol address. but it is not possible to bind more
than one protocol address to the same transport endpoint.
However, the transport provider must also support this capa-
bility. If a user binds more than one transport endpoint to
the same protocol address, only one endpoint can be used to
listen for connection indications associated with that pro-
tocol 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 connec-
tion indication. If a user attempts to bind a protocol
address to a second transport endpoint with a value of qlen
greater than zero, tbind() will return -1 and set terrno
to TADRBUSY. When a user accepts a connection on the tran-
sport 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 tunbind(3NSL) or
tclose(3NSL) call has been issued. No other transport end-
points 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 TIDLE state). This will
prevent more than one transport endpoint bound to the same
protocol address from accepting connection indications.
If fd refers to connectionless mode service, this function
allows for more than one transport endpoint to be associated
with a protocol address, where the underlying transport pro-
vider supports this capability (often in conjunction with
value of a protocol-specific option). If a user attempts to
bind a second transport endpoint to an already bound proto-
col address when such capability is not supported for a
transport provider, tbind() will return -1 and set terrno
to TADRBUSY.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Oth-
erwise, a value of -1 is returned and terrno is set to
indicate an error.
VALID STATES
TUNBND
ERORS
On failure, terrno is set to one of the following:
TACES The user does not have permission to use the
specified address.
TADRBUSY The requested address is in use.
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions tbind(3NSL)
TBADADR The specified protocol address was in an
incorrect format or contained illegal informa-
tion.
TBADF The specified file descriptor does not refer to
a transport endpoint.
TBUFOVFLW The number of bytes allowed for an incoming
argument (maxlen) is greater than 0 but not
sufficient to store the value of that argument.
The provider's state will change to TIDLE and
the information to be returned in ret will be
discarded.
TOUTSTATE The communications endpoint referenced by fd
is not in one of the states in which a call to
this function is valid.
TNOADR The transport provider could not allocate an
address.
TPROTO This error indicates that a communication prob-
lem has been detected between XTI and the tran-
sport provider for which there is no other
suitable XTI error (terrno).
TSYSER A system error has occurred during execution of
this function.
TLI COMPATIBILITY
The XTI and TLI interface definitions have common names but
use different header files. This, and other semantic differ-
ences between the two interfaces are described in the sub-
sections below.
Interface Header
The XTI interfaces use the header file, xti.h. TLI inter-
faces should not use this header. They should use the
header:
#include
Address Bound
SunOS 5.11 Last change: 7 May 1998 4
Networking Services Library Functions tbind(3NSL)
The user can compare the addresses in req and ret to deter-
mine whether the transport provider bound the transport end-
point to a different address than that requested.
Error Description Values
The terrno values TPROTO and TADRBUSY can be set by the
XTI interface but cannot be set by the TLI interface.
A terrno value that this routine can return under different
circumstances than its XTI counterpart is TBUFOVFLW. It can
be returned even when the maxlen field of the corresponding
buffer has been set to zero.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
taccept(3NSL), talloc(3NSL), tclose(3NSL),
tconnect(3NSL), tunbind(3NSL), attributes(5)
WARNINGS
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.
An implementation need not allow an application explicitly
to bind more than one communications endpoint to a single
protocol address, while permitting more than one connection
to be accepted to the same protocol address. That means that
although an attempt to bind a communications endpoint to
some address with qlen=0 might be rejected with TADRBUSY,
the user may nevertheless use this (unbound) endpoint as a
responding endpoint in a call to taccept(3NSL). To become
independent of such implementation differences, the user
should supply unbound responding endpoints to
taccept(3NSL).
SunOS 5.11 Last change: 7 May 1998 5
Networking Services Library Functions tbind(3NSL)
The local address bound to an endpoint may change as result
of a taccept(3NSL) or tconnect(3NSL) call. Such changes
are not necessarily reversed when the connection is
released.
SunOS 5.11 Last change: 7 May 1998 6
|
