Networking Services Library Functions trcvvudata(3NSL)
NAME
trcvvudata - receive a data unit into one or more noncon-
tiguous buffers
SYNOPSIS
#include
int trcvvudata(int fd, struct tunitdata *unitdata, struct tiovec *iov,
unsigned int iovcount, int *flags);
DESCRIPTION
This function is used in connectionless mode to receive a
data unit from another transport user. The argument fd
identifies the local transport endpoint through which data
will be received, unitdata holds information associated
with the received data unit, iovcount contains the number
of non-contiguous udata buffers which is limited to
TIOVMAX, which is an implementation-defined value of at
least 16, and flags is set on return to indicate that the
complete data unit was not received. If the limit on
iovcount is exceeded, the function fails with TBADATA. The
argument unitdata points to a tunitdata structure con-
taining the following members:
struct netbuf addr;
struct netbuf opt;
struct netbuf udata;
The maxlen field of addr and opt must be set before cal-
ling this function to indicate the maximum size of the
buffer for each. The udata field of tunitdata is not
used. The iovlen and iovbase fields of "iov0" through
iov [iovcount-1] must be set before calling trcvvudata()
to define the buffer where the userdata will be placed. If
the maxlen field of addr or opt is set to zero then no
information is returned in the buf field for this parame-
ter.
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].iovbase
through iov [iovcount-1].iovbase contains the user data
that was received. The return value of trcvvudata() is the
number of bytes of user data given to the user.
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions trcvvudata(3NSL)
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.
By default, trcvvudata() operates in synchronous mode and
waits for a data unit to arrive if none is currently avail-
able. However, if ONONBLOCK is set by means of
topen(3NSL) or fcntl(2), trcvvudata() executes in asyn-
chronous 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 TMORE will be set in flags on return to indi-
cate that another trcvvudata() should be called to
retrieve the rest of the data unit. Subsequent calls to
trcvvudata() will return zero for the length of the address
and options, until the full data unit has been received.
RETURN VALUES
On successful completion, trcvvudata() returns the number
of bytes received. Otherwise, it returns -1 on failure and
terrno is set to indicate the error.
VALID STATES
TIDLE.
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.
TBUFOVFLW The number of bytes allocated for the incom-
ing 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.
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions trcvvudata(3NSL)
TLOK An asynchronous event has occurred on this
transport endpoint and requires immediate
attention.
TNODATA ONONBLOCK was set, but no data units are
currently available from the transport pro-
vider.
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
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
fcntl(2), talloc(3NSL), topen(3NSL), trcvudata(3NSL),
trcvuderr(3NSL), tsndudata(3NSL), tsndvudata(3NSL),
attributes(5)
SunOS 5.11 Last change: 7 May 1998 3
|
