Print this page
OS-6101 t_bind(3NSL) could mention data types for transports
*** 1,233 ****
T_BIND(3NSL) Networking Services Library Functions T_BIND(3NSL)
-
-
NAME
! t_bind - bind an address to a transport endpoint
SYNOPSIS
#include <xti.h>
-
-
- int t_bind(int fd, const struct t_bind *req, struct t_bind *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.h
! header 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 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 addr field of the t_bind 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, 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, t_bind() fails with
- t_errno set to TBUFOVFLW.
-
-
- If the requested 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.
-
-
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 connection indications
that the transport provider should support for the given transport
endpoint. An outstanding 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 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 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 same protocol address.
- It is not possible to bind more than one protocol address to the same
- transport endpoint. However, the transport provider must also support
- this capability. 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 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
- connection 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 TADDRBUSY. 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(3NSL) or
- t_close(3NSL) call has been issued. No other transport endpoints 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
- T_IDLE 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 provider 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 protocol address when such capability is not supported
! for a transport provider, t_bind() will return -1 and set t_errno to
! TADDRBUSY.
RETURN VALUES
! Upon successful completion, a value of 0 is returned. Otherwise, a
! value of -1 is returned and t_errno is set to indicate an error.
VALID STATES
T_UNBND
ERRORS
On failure, t_errno is set to one of the following:
! TACCES
! The user does not have permission to use the specified
address.
! TADDRBUSY
! The requested address is in use.
!
! TBADADDR
! The specified protocol address was in an incorrect format
! or contained illegal information.
!
!
! 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 T_IDLE 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.
! TNOADDR
! The transport provider could not allocate an address.
!
! TPROTO
! This error indicates that a communication problem has been
! detected between XTI and the transport provider for which
! there is no other suitable XTI error (t_errno).
!
!
! TSYSERR
! 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 differences between
! the two interfaces are described in the subsections below.
Interface Header
! The XTI interfaces use the header file, xti.h. TLI interfaces should
! not use this header. They should use the header:
-
- #include <tiuser.h>
-
Address Bound
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.
Error Description Values
The t_errno values TPROTO and TADDRBUSY can be set by the XTI interface
but cannot be set by the TLI interface.
-
A t_errno 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.
! ATTRIBUTES
! See attributes(5) for descriptions of the following attributes:
-
-
-
- +---------------+-----------------+
- |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
- +---------------+-----------------+
- |MT Level | Safe |
- +---------------+-----------------+
-
SEE ALSO
t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL),
t_unbind(3NSL), attributes(5)
WARNINGS
--- 1,189 ----
T_BIND(3NSL) Networking Services Library Functions T_BIND(3NSL)
NAME
! t_bind - bind an address to a tansport endpoint
SYNOPSIS
+ Network Services Library (libnsl, -lnsl)
#include <xti.h>
+ int
+ t_bind(int fd, const struct t_bind *req, stuct t_bind *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.h> header
! 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 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 addr field of the t_bind 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. For tcp(7P) and udp(7P) transports, buf points to either
+ a struct sockaddr_in or struct sockaddr_in6 buffer (depending on if IPv4
+ or IPv6 is being used). 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, 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, t_bind() fails with t_errno set to TBUFOVFLW.
+ If the requested 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.
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 connection indications
that the transport provider should support for the given transport
endpoint. An outstanding 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 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 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 same protocol address. It is
+ not possible to bind more than one protocol address to the same transport
+ endpoint. However, the transport provider must also support this
+ capability. 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 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 connection
+ 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 TADDRBUSY. 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(3NSL) or t_close(3NSL) call
+ has been issued. No other transport endpoints 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 T_IDLE 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 provider 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
! protocol address when such capability is not supported for a transport
! provider, t_bind() will return -1 and set t_errno to TADDRBUSY.
RETURN VALUES
! Upon successful completion, a value of 0 is returned. Otherwise, a value
! of -1 is returned and t_errno is set to indicate an error.
VALID STATES
T_UNBND
ERRORS
On failure, t_errno is set to one of the following:
! TACCES The user does not have permission to use the specified
address.
+ TADDRBUSY The requested address is in use.
! TBADADDR The specified protocol address was in an incorrect
! format or contained illegal information.
! 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 T_IDLE 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.
+ TNOADDR The transport provider could not allocate an address.
! TPROTO This error indicates that a communication problem has
! been detected between XTI and the transport provider
! for which there is no other suitable XTI error
! (t_errno).
! TSYSERR 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 differences between the two
! interfaces are described in the subsections below.
Interface Header
! The XTI interfaces use the header file, <xti.h>. TLI interfaces should
! not use this header. They should use the header: <tiuser.h>
Address Bound
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.
Error Description Values
The t_errno values TPROTO and TADDRBUSY can be set by the XTI interface
but cannot be set by the TLI interface.
A t_errno 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.
! MT-LEVEL
! Safe
SEE ALSO
t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL),
t_unbind(3NSL), attributes(5)
WARNINGS
*** 234,244 ****
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 TADDRBUSY,
--- 190,199 ----
*** 245,257 ****
the user may nevertheless use this (unbound) endpoint as a responding
endpoint in a call to t_accept(3NSL). To become independent of such
implementation differences, the user should supply unbound responding
endpoints to t_accept(3NSL).
-
The local address bound to an endpoint may change as result of a
! t_accept(3NSL) or t_connect(3NSL) call. Such changes are not
! necessarily reversed when the connection is released.
!
!
! December 27, 2013 T_BIND(3NSL)
--- 200,209 ----
the user may nevertheless use this (unbound) endpoint as a responding
endpoint in a call to t_accept(3NSL). To become independent of such
implementation differences, the user should supply unbound responding
endpoints to t_accept(3NSL).
The local address bound to an endpoint may change as result of a
! t_accept(3NSL) or t_connect(3NSL) call. Such changes are not necessarily
! reversed when the connection is released.
! illumos May 1, 2017 illumos