t_rcvvudata(3) Library Functions Manual t_rcvvudata(3)
NAME
t_rcvvudata - Receives data or expedited data sent over a connection and puts the data into one or more non-contiguous buffers
LIBRARY
XTI Library (libxti.a)
SYNOPSIS
#include <xti.h>
int t_rcvvudata(
int fd,
struct t_unitdata *unitdata,
struct t_iovec *iov,
unsigned int iovcount,
int *flags);
STANDARDS
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.
PARAMETERS
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[iovcount-1].iov_base y(n) e(y)
iov[iovcount-1].iov_len y e
iovcount y n
flags n n
Notes to Table:
y This is a meaningful parameter.
(y)The content of the object pointed to by y is meaningful.
o This is a meaningful but optional parameter.
(o)The content of the object pointed to by o is meaningful.
e The parameter value after the call is the same as before the call.
n 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: Refer-
ences 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.
Contains the number of non-contiguous udata buffers, which is limited to T_IOV_MAX (an implementation-defined value of at least 16). Indi-
cates (on return) that the complete data unit was not received.
VALID STATES
The t_rcvvudata() function can be called only in the T_IDLE transport provider state.
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 [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_rcvvu-
data() 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_rcvvu-
data() is the number of bytes of user data given to the user. 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 flags 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.
RETURN VALUE
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.
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 dis-
carded. 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 communica-
tions 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.
RELATED INFORMATION
Functions: fcntl(2), t_alloc(3), t_open(3), t_rcvudata(3), t_rcvuderr(3), t_sndudata(3), t_sndvudata(3). delim off
t_rcvvudata(3)