 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
t_rcvvudata(3)
NAME
t_rcvvudata - 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_rcvvudata(
int fd,
struct t_unitdata *unitdata,
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_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
...
y(n) e(y)
iov[iovcount-
1].iov_base
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.
fd Identifies the local transport endpoint through which data is to
arrive.
unitdata
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:
struct netbuf addr
References 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:
unsigned int maxlen
Specifies a maximum byte length of the data buffer.
unsigned int len
Specifies the actual byte length of the data written to the
buffer.
char *buf
Points to the buffer location.
struct netbuf opt
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.
struct netbuf udata
Specifies the user data unit that is being sent to the remote
transport user.
iov Points to a buffer where the user data will be placed.
iovcount
Contains the number of non-contiguous udata buffers, which is limited
to T_IOV_MAX (an implementation-defined value of at least 16).
flags
Indicates (on return) that the complete data unit was not received.
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_rcvvudata() 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_rcvvudata() is the
number of bytes of user data given to the user.
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_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
options 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.
ERRORS
If the t_rcvvudata() 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.
[TBUFOVFLW]
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 discarded.
[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]
This function 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_rcvvudata() function can be called only in the T_IDLE transport
provider state.
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_alloc(3), t_open(3), t_rcvudata(3), t_rcvuderr(3),
t_sndudata(3), t_sndvudata(3).
Standards: standards(5)
Network Programmer's Guide
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|