t_bind(3N) SDK R4.11 t_bind(3N)
NAME
tbind - 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 transport
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 containing 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] 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 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.
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 provider 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 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 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
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 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.
On failure, terrno 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 allowed for an incoming
argument is 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.
[TSYSERR] A system error has occurred during execution of
this function.
DIAGNOSTICS
tbind returns 0 on success and -1 on failure and terrno is set to
indicate the error.
SEE ALSO
intro(3), topen(3N), toptmgmt(3N), tunbind(3N).
UNIX System V Network Programmer's Guide.
Licensed material--property of copyright holder(s)