t_rcvvudata(3)t_rcvvudata(3)NAMEt_rcvvudata - Receive data or expedited data sent over a connection and
put the data into one or more non-contiguous buffers
SYNOPSIS
#include <xti.h>
int t_rcvvudata(
int fd,
struct t_unitdata *unitdata,
struct t_iovec *iov,
unsigned int iovcount,
int *flags );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
t_rcvvudata(): XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
The following table summarizes the relevance of input and output param‐
eters 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 mean‐
ingful. The parameter value after the call is the same as before the
call. This is not a meaningful parameter. Identifies the local trans‐
port 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.
DESCRIPTION
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 [TBAD‐
DATA].
The maxlen field of addr and opt must be set before calling this func‐
tion 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 con‐
tains the user data that was received. The return value of t_rcvvu‐
data() 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 con‐
strained 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_NON‐
BLOCK is set (via t_open() or fcntl()), t_rcvvudata() executes in asyn‐
chronous 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.
ERRORS
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 ref‐
erenced 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.
VALID STATES
The t_rcvvudata() function can be called only in the T_IDLE transport
provider state.
RETURN VALUE
Upon successful completion, t_rcvv() returns a value of 0 (zero). Oth‐
erwise, it returns a value of -1 and sets t_errno to indicate the
error.
SEE ALSO
Functions: fcntl(2), t_alloc(3), t_open(3), t_rcvudata(3), t_rcvud‐
err(3), t_sndudata(3), t_sndvudata(3).
Standards: standards(5)
Network Programmer's Guide
t_rcvvudata(3)
