Networking Services Library Functions trcvv(3NSL)
NAME
trcvv - receive data or expedited data sent over a connec-
tion and put the data into one or more non-contiguous
buffers
SYNOPSIS
#include
int trcvv(int fd, struct tiovec *iov, unsigned int iovcount, int *flags);
DESCRIPTION
This function receives either normal or expedited data. The
argument fd identifies the local transport endpoint through
which data will arrive, iov points to an array of buffer
address/buffer size pairs (iovbase, iovlen). The trcvv()
function receives data into the buffers specified by
iov0.iovbase, iov1.iovbase, through iov [iovcount-
1].iovbase, always filling one buffer before proceeding to
the next.
Note that the limit on the total number of bytes available
in all buffers passed:
iov(0).iovlen ] . . ] iov(iovcount-1).iovlen)
may be constrained by implementation limits. If no other
constraint applies, it will be limited by INTMAX. In prac-
tice, 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.
The argument iovcount contains the number of buffers which
is limited to TIOVMAX, which is an implementation-defined
value of at least 16. If the limit is exceeded, the func-
tion will fail with TBADATA.
The argument flags may be set on return from trcvv() and
specifies optional flags as described below.
By default, trcvv() operates in synchronous mode and will
wait for data to arrive if none is currently available. How-
ever, if ONONBLOCK is set by means of topen(3NSL) or
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions trcvv(3NSL)
fcntl(2), trcvv() will execute in asynchronous mode and
will fail if no data is available. See TNODATA below.
On return from the call, if TMORE 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 trcvv() or
trcv(3NSL) calls. In the asynchronous mode, or under
unusual conditions (for example, the arrival of a signal or
TEXDATA event), the TMORE flag may be set on return from
the trcvv() call even when the number of bytes received is
less than the total size of all the receive buffers. Each
trcvv() with the TMORE flag set indicates that another
trcvv() must follow to get more data for the current TSDU.
The end of the TSDU is identified by the return of a
trcvv() call with the TMORE flag not set. If the tran-
sport provider does not support the concept of a TSDU as
indicated in the info argument on return from topen(3NSL)
or tgetinfo(3NSL), the TMORE 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 trcvv(), then
trcvv() will return 0 only if the end of a TSDU is being
returned to the user.
On return, the data is expedited if TEXPEDITED is set in
flags. If TMORE 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 subse-
quent calls to trcvv() which will return with TEXPEDITED
set in flags. The end of the ETSDU is identified by the
return of a trcvv() call with TEXPEDITED set and TMORE
cleared. If the entire ETSDU is not available it is possi-
ble for normal data fragments to be returned between the
initial and final fragments of an ETSDU.
If a signal arrives, trcvv() returns, giving the user any
data currently available. If no data is available,
trcvv() returns -1, sets terrno to TSYSER and errno to
EINTR. If some data is available, trcvv() returns the
number of bytes received and TMORE is set in flags.
In synchronous mode, the only way for the user to be noti-
fied of the arrival of normal or expedited data is to issue
this function or check for the TDATA or TEXDATA events
using the tlook(3NSL) function. Additionally, the process
can arrange to be notified via the EM interface.
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions trcvv(3NSL)
RETURN VALUES
On successful completion, trcvv() returns the number of
bytes received. Otherwise, it returns -1 on failure and
terrno is set to indicate the error.
VALID STATES
TDATAXFER, TOUTREL.
ERORS
On failure, terrno is set to one of the following:
TBADATA iovcount is greater than TIOVMAX.
TBADF The specified file descriptor does not refer
to a transport endpoint.
TLOK An asynchronous event has occurred on this
transport endpoint and requires immediate
attention.
TNODATA ONONBLOCK was set, but no data is currently
available from the transport provider.
TNOTSUPORT This function is not supported by the under-
lying transport provider.
TOUTSTATE The communications endpoint referenced by fd
is not in one of the states in which a call
to this function is valid.
TPROTO This error indicates that a communication
problem has been detected between XTI and the
transport provider for which there is no
other suitable XTI error (terrno).
TSYSER A system error has occurred during execution
of this function.
TLI COMPATIBILITY
In the TLI interface definition, no counterpart of this rou-
tine was defined.
ATRIBUTES
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions trcvv(3NSL)
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
fcntl(2), tgetinfo(3NSL), tlook(3NSL), topen(3NSL),
trcv(3NSL), tsnd(3NSL), tsndv(3NSL), attributes(5)
SunOS 5.11 Last change: 7 May 1998 4
|
