t_rcvv - 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_rcvv(
int fd,
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_rcvv(): 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_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 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
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.
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 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_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
indicates 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 currently 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. Additionally, the
process can arrange to be notified via the EM interface.
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 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. 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 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_rcvv() function can be called in either the
T_DATAXFER or T_OUTREL transport provider states.
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_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)
[ Back ] |
