t_rcvv(3)t_rcvv(3)NAMEt_rcvv - 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_rcvv(
int fd,
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_rcvv(): 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_rcvv() is called:
───────────────────────────────────────────────────
Parameters Before Call After Call
───────────────────────────────────────────────────
fd y n
iov y n
iovcount y n
iov[0].iov_base y(n)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
───────────────────────────────────────────────────
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 an array of
buffer address/buffer size pairs (iov_base, iov_len). Specifies the
number of buffers, which is limited to T_IOV_MAX (an implementation-
defined value of at least 16). If the limit is exceeded, the function
will fail with [TBADDATA]. See the DESCRIPTION section.
DESCRIPTION
The t_rcvv() function receives data into the buffers specified by
iov[0].iov_base, iov[1].iov_base, through iov[iovcount-1].iov_base,
always filling one buffer before proceding to the next.
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_rcvv() operates in synchronous mode and will wait for
data to arrive if none is currently available. However, if O_NONBLOCK
is set (via t_open() or fcntl()), t_rcvv() will execute in asynchronous
mode and will fail if no data is available (see [TNODATA]).
The flags argument may be set on return from t_rcvv(), and specifies
optional flags as follows.
On return from the call, if T_MORE is set in flags, this indicates that
there is more data, and the current transport service data unit (TSDU)
or expedited transport service data unit (ETSDU) must be received in
multiple t_rcvv() or t_rcv() calls. In the asynchronous mode, or under
unusual conditions (for example, the arrival of a signal or T_EXDATA
event), the T_MORE flag may be set on return from the t_rcvv() call
even when the number of bytes received is less than the total size of
all the receive buffers. Each t_rcvv() with the T_MORE flag set indi‐
cates that another t_rcvv() call must follow to get more data for the
current TSDU. The end of the TSDU is identified by the return of a
t_rcvv() call with the T_MORE flag not set.
If the transport provider does not support the concept of a TSDU as
indicated in the info argument on return from t_open() or t_getinfo(),
the T_MORE flag is not meaningful and should be ignored. If the amount
of buffer space passed in iov is greater than zero on the call to
t_rcvv(), t_rcvv() will return 0 only if the end of a TSDU is being
returned to the user.
On return, the data is expedited if T_EXPEDITED is set in flags. If
T_MORE is also set, it indicates that the number of expedited bytes
exceeded nbytes, a signal has interrupted the call, or that an entire
ETSDU was not available (only for transport protocols that support
fragmentation of ETSDUs). The rest of the ETSDU will be returned by
subsequent calls to t_rcvv(), which will return with T_EXPEDITED set in
flags. The end of the ETSDU is identified by the return of a t_rcvv()
call with T_EXPEDITED set and T_MORE cleared. If the entire ETSDU is
not available it is possible for normal data fragments to be returned
between the initial and final fragments of an ETSDU.
If a signal arrives, t_rcvv() returns, giving the user any data cur‐
rently available. If no data is available, t_rcvv() returns -1, sets
t_errno to [TSYSERR] and errno to [EINTR]. If some data is available,
t_rcvv() returns the number of bytes received and T_MORE is set in
flags.
In synchronous mode, the only way for the user to be notified of the
arrival of normal or expedited data is to issue this function or check
for the T_DATA or T_EXDATA events using the t_look() function. Addi‐
tionally, the process can arrange to be notified via the EM interface.
ERRORS
If the t_rcvreldata() 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. An asynchro‐
nous 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. Orderly release 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 com‐
munication 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_rcvv() function can be called in either the T_DATAXFER or T_OUT‐
REL transport provider states.
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_getinfo(3), t_look(3), t_open(3), t_rcv(3),
t_snd(3), t_sndv(3).
Standards: standards(5)
Network Programmer's Guide
t_rcvv(3)
