Networking Services Library Functions trcv(3NSL)
NAME
trcv - receive data or expedited data sent over a connec-
tion
SYNOPSIS
#include
int trcv(int fd, void *buf, unsigned int nbytes, int *flags);
DESCRIPTION
This function is part of the XTI interfaces which evolved
from the TLI interfaces. XTI represents the future evolution
of these interfaces. However, TLI interfaces are supported
for compatibility. When using a TLI function that has the
same name as an XTI function, the tiuser.h header file must
be used. Refer to the TLI COMPATIBILITY section for a
description of differences between the two interfaces.
This function receives either normal or expedited data. The
argument fd identifies the local transport endpoint through
which data will arrive, buf points to a receive buffer where
user data will be placed, and nbytes specifies the size of
the receive buffer. The argument flags may be set on return
from trcv() and specifies optional flags as described
below.
By default, trcv() 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
fcntl(2), trcv() 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 trcv() 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 trcv() call even
when the number of bytes received is less than the size of
the receive buffer specified. Each trcv() with the TMORE
flag set indicates that another trcv() must follow to get
more data for the current TSDU. The end of the TSDU is iden-
tified by the return of a trcv() call with the TMORE flag
not set. If the transport provider does not support the con-
cept 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 nbytes is greater
SunOS 5.11 Last change: 24 Aug 2007 1
Networking Services Library Functions trcv(3NSL)
than zero on the call to trcv(), trcv() 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 trcv() which will return with TEXPEDITED
set in flags. The end of the ETSDU is identified by the
return of a trcv() 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, trcv() returns, giving the user any
data currently available. If no data is available, trcv()
returns -1, sets terrno to TSYSER and errno to EINTR.
If some data is available, trcv() 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 by means of the EM interface.
RETURN VALUES
On successful completion, trcv() 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:
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.
SunOS 5.11 Last change: 24 Aug 2007 2
Networking Services Library Functions trcv(3NSL)
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
The XTI and TLI interface definitions have common names but
use different header files. This, and other semantic differ-
ences between the two interfaces are described in the sub-
sections below.
Interface Header
The XTI interfaces use the header file, xti.h. TLI inter-
faces should not use this header. They should use the
header:
#include
Error Description Values
The terrno value that can be set by the XTI interface and
cannot be set by the TLI interface is:
TPROTO
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 24 Aug 2007 3
Networking Services Library Functions trcv(3NSL)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
Standard See standards(5).
SEE ALSO
fcntl(2), tgetinfo(3NSL), tlook(3NSL), topen(3NSL),
tsnd(3NSL), attributes(5), standards(5)
SunOS 5.11 Last change: 24 Aug 2007 4
|
