 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
t_rcvv(3)
NAME
t_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 standards
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 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
...
y(n) e(y)
iov[iovcount-
1].iov_base
iov[iovcount-1].iov_len y e
__________________________________________________
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.
fd Identifies the local transport endpoint through which data is to
arrive.
iov Points to an array of buffer address/buffer size pairs (iov_base,
iov_len).
iovcount
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].
flags
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
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.
ERRORS
If the t_rcvreldata() function fails, t_errno may be set to one of the
following values:
[TBADDATA]
The iovcount parameter is greater than T_IOV_MAX.
[TBADF]
File descriptor (fd) is not a valid transport endpoint.
[TLOOK]
An asynchronous event occurred on this transport endpoint and requires
immediate attention.
[TNODATA]
O_NONBLOCK mode was set, but no data is currently available from the
transport provider.
[TNOTSUPPORT]
Orderly release is not supported by the underlying transport provider.
[TOUTSTATE]
The communications endpoint referenced by fd is not in a valid state in
which a call to this function.
[TPROTO]
A communication problem has been detected between XTI and the transport
provider for which there is no other suitable XTI error (t_errno).
[TSYSERR]
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_OUTREL
transport provider states.
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.
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|