t_rcvvudata - Receive data or expedited data sent over a
connection and put the data into one or more non-contiguous
buffers
#include <xti.h>
int t_rcvvudata(
int fd,
struct t_unitdata *unitdata,
struct t_iovec *iov,
unsigned int iovcount,
int *flags );
XTI Library (libxti.a)
Interfaces documented on this reference page conform to
industry standards as follows:
t_rcvvudata(): XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
The following table summarizes the relevance of input and
output parameters before and after t_rcvvudata() is
called:
---------------------------------------------------
Parameters Before Call After Call
---------------------------------------------------
fd y n
unitdata->addr.maxlen y e
unitdata->addr.len n y
unitdata->addr.buf o(n) e(n)
unitdata->opt.maxlen y e
unitdata->opt.len n y
unitdata->opt.buf o(n) e(o)
unitdata->udata.maxlen n e
unitdata->udata.len n e
unitdata->udata.buf n e
iov[0].iov_base y e(y)
iov[0].iov_len y e
...
iov[iov- y(n) e(y)
count-1].iov_base
iov[iovcount-1].iov_len y e
iovcount y n
flags n n
---------------------------------------------------
Notes to Table: This is a meaningful parameter. The content
of the object pointed to by y is meaningful. This is
a meaningful but optional parameter. The content of the
object pointed to by o is meaningful. The parameter value
after the call is the same as before the call. This is
not a meaningful parameter. Identifies the local transport
endpoint through which data is to arrive. Points to
a type t_unitdata structure used to specify a data unit
being received through the transport endpoint specified by
the fd parameter. The t_unitdata structure has the following
members: References a buffer for protocol address
information of the remote transport user. The type netbuf
structure referenced by this member is defined in the
xti.h include file and has the following members: Specifies
a maximum byte length of the data buffer. Specifies
the actual byte length of the data written to the buffer.
Points to the buffer location. Identifies options that
the user wants associated with this request. The user may
choose not to specify what protocol options are associated
with the transfer by setting the len field of opt to zero.
In this case, the provider may use default options. Specifies
the user data unit that is being sent to the remote
transport user. Points to a buffer where the user data
will be placed. Contains the number of non-contiguous
udata buffers, which is limited to T_IOV_MAX (an implementation-defined
value of at least 16). Indicates (on
return) that the complete data unit was not received.
The t_rcvvudata() function is an XTI connectionless service
function that is used to receive a data unit from
another transport user.
If the limit on iovcount is exceeded, the function fails
with [TBADDATA].
The maxlen field of addr and opt must be set before calling
this function to indicate the maximum size of the
buffer for each. The udata field of t_unitdata is not
used. The iov_len and iov_base fields of iov[0] through
iov[iovcount-1] must be set before calling t_rcvvudata()
to define the buffer where the user data will be placed.
If the maxlen field of addr or opt is set to zero, no
information is returned in the buf field for this parameter.
On return from this call, addr specifies the protocol
address of the sending user, opt identifies options that
were associated with this data unit, and iov[0].iov_base
through iov[iovcount-1].iov_base contains the user data
that was received. The return value of t_rcvvudata() is
the number of bytes of user data given to the user.
Note
The limit on the total number of bytes available in all
buffers passed (that is, iov(0).iov_len + ... + iov(iovcount-1).iov_len)
may be constrained by implementation
limits. If no other constraint applies, it will be limited
by [INT_MAX]. In practice, the availability of memory
to an application is likely to impose a lower limit on
the amount of data that can be sent or received using
scatter/gather functions.
By default, t_rcvvudata() operates in synchronous mode and
waits for a data unit to arrive if none is currently
available. However, if O_NONBLOCK is set (via t_open() or
fcntl()), t_rcvvudata() executes in asynchronous mode and
fails if no data units are available.
If the buffers defined in the iov[] array are not large
enough to hold the current data unit, the buffers will be
filled and T_MORE will be set in options on return to
indicate that another t_rcvvudata() should be called to
retrieve the rest of the data unit. Subsequent calls to
t_rcvvudata() will return zero for the length of the
address and options, until the full data unit has been
received.
If the t_rcvvudata() function fails, t_errno may be set to
one of the following values: The iovcount parameter is
greater than T_IOV_MAX. File descriptor (fd) is not a
valid transport endpoint. The number of bytes allocated
for the incoming protocol address or options (maxlen) is
greater than 0, but not sufficient to store the information.
The unit data information to be returned in unitdata
will be discarded. An asynchronous event occurred on this
transport endpoint and requires immediate attention.
O_NONBLOCK mode was set, but no data is currently available
from the transport provider. This function is not
supported by the underlying transport provider. The communications
endpoint referenced by fd is not in a valid
state in which a call to this function. A communication
problem has been detected between XTI and the transport
provider for which there is no other suitable XTI error
(t_errno). A system error occurred during execution of
this function.
The t_rcvvudata() function can be called only in the
T_IDLE transport provider state.
Upon successful completion, t_rcvv() returns a value of 0
(zero). Otherwise, it returns a value of -1 and sets
t_errno to indicate the error.
Functions: fcntl(2), t_alloc(3), t_open(3), t_rcvudata(3),
t_rcvuderr(3), t_sndudata(3), t_sndvudata(3).
Standards: standards(5)
Network Programmer's Guide
t_rcvvudata(3)
[ Back ] | 