t_bind(3) t_bind(3)
NAME [Toc] [Back]
t_bind() - bind an address to a transport endpoint
SYNOPSIS [Toc] [Back]
#include <xti.h> /* for X/OPEN Transport Interface - XTI */
/* or */
#include <tiuser.h> /* for Transport Layer Interface - TLI */
int t_bind (fd, req, ret);
int fd;
struct t_bind *req;
struct t_bind *ret;
DESCRIPTION [Toc] [Back]
The t_bind() 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 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 t_bind structure containing the
following members:
struct netbuf addr;
unsigned qlen;
The type netbuf structure is defined in the <xti.h> or <tiuser.h>
header file. This structure, which is used to define buffer
parameters, has the following members:
unsigned int maxlen maximum byte length of the data buffer
unsigned int len actual byte length of data written to
buffer
char *buf points to buffer location
The addr field of the t_bind structure specifies a protocol address.
The qlen field is used to indicate the maximum number of outstanding
connect 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 the address of that the
transport provider actually bound to the transport endpoint. This is
the same as the address specified 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,
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
t_bind(3) t_bind(3)
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 request address is not available, t_bind() will return -1 with
t_errno set as appropriate. If no address is specified in req (the
len field of addr in req is zero or req is NULL), 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, t_bind() will fail with
t_errno set to [TNOADDR]. HP OSI does not support the automatic
generation of an address.
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 negotiated 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 outstanding connect indications
that 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 but which has
not been accepted or rejected. A value of qlen greater than zero is
only meaningful when issued by a passive transport user that expects
others 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.
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 Caveats 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 same protocol address
(however, the transport provider must also support this capability),
but it is not possible 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 the 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 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, t_bind() will return -1 and set t_errno to
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
t_bind(3) t_bind(3)
[TADDRBUSY] (XTI) or [TBADADDR] (TLI). When 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 the connection, until a t_unbind() or
t_close() call has been issued. No other transport endpoints may be
bound for listening on the same protocol address while that initial
listening endpoint is active (in the data transfer phase or in the
T_IDLE state). This will prevent more than one transport endpoint
bound to the same protocol address from accepting connect indications.
If fd refers to a connectionless-mode service, only one endpoint may
be associated with a protocol address. If a user attempts to bind a
second transport endpoint to an already bound address, t_bind() will
return -1 and set t_errno to [TADDRBUSY].
Thread-Safeness [Toc] [Back]
The t_bind() function is safe to be called by multi-threaded
applications, and it is thread-safe for both POSIX Threads and DCE
User Threads. It has a cancellation point. It is neither asynccancel
safe nor async-signal safe. Finally, it is not fork-safe.
Valid States [Toc] [Back]
T_UNBND
Note [Toc] [Back]
HP XTI does not support automatic generation of addresses. Therefore a
valid local transport address must be specified in req.
Caveats [Toc] [Back]
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.
A transport provider may not allow an explicit binding of more than
one transport endpoint to the same protocol address although it allows
more than one connection to be accepted for the same protocol address.
To ensure portability, it is, therefore, 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.
RETURN VALUE [Toc] [Back]
Upon successful completion, a value of 0 is returned. Otherwise, a
value of -1 is returned and t_errno is set to indicate the error.
ERRORS [Toc] [Back]
On failure, t_errno is set to one of the following:
[TBADF] The specified file descriptor does not refer to a
transport endpoint.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
t_bind(3) t_bind(3)
[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 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] The address requested is in use and the transport
provider could not allocate a new address.
[TPROTO] (XTI only) This error indicates that a
communication problem has been detected between
XTI and the transport provider for which there is
no suitable XTI (t_errno).
FILES [Toc] [Back]
/usr/include/xti.h XTI data structures
/usr/include/xti_iso.h XTI data structures
/usr/include/tiuser.h TLI data structures
SEE ALSO [Toc] [Back]
t_alloc(3), t_close(3), t_open(3), t_unbind(3).
STANDARDS CONFORMANCE [Toc] [Back]
t_bind(): SVID2, XPG3, XPG4
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003 [ Back ] |
