Networking Services Library Functions tsndv(3NSL)
NAME
tsndv - send data or expedited data, from one or more non-
contiguous buffers, on a connection
SYNOPSIS
#include
int tsndv(int fd, const struct tiovec *iov, unsigned int iovcount, int flags);
DESCRIPTION
This function is used to send either normal or expedited
data. The argument fd identifies the local transport end-
point over which data should be sent, iov points to an
array of buffer address/buffer length pairs. tsndv()
sends data contained in buffers iov0 , iov1 , through iov
[iovcount-1]. iovcount contains the number of non-contiguous
data buffers which is limited to TIOVMAX, an
implementation-defined value of at least 16. If the limit
is exceeded, the function fails with TBADATA.
iov(0).iovlen ] . . ] iov(iovcount-1).iovlen)
Note that the limit on the total number of bytes available
in all buffers passed:
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 flags specifies any optional flags described
below:
TEXPEDITED If set in flags, the data will be sent as
expedited data and will be subject to the
interpretations of the transport provider.
TMORE If set in flags, this indicates to the
transport provider that the transport ser-
vice data unit (TSDU) (or expedited tran-
sport service data unit - ETSDU) is being
sent through multiple tsndv() calls. Each
tsndv() with the TMORE flag set indicates
SunOS 5.11 Last change: 23 Aug 2001 1
Networking Services Library Functions tsndv(3NSL)
that another tsndv() or tsnd(3NSL) will
follow with more data for the current TSDU
(or ETSDU).
The end of the TSDU (or ETSDU) is identified by a tsndv()
call with the TMORE flag not set. Use of TMORE enables
a user to break up large logical data units without losing
the boundaries of those units at the other end of the con-
nection. The flag implies nothing about how the data is
packaged for transfer below the transport interface. If the
transport 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
will be ignored if set.
The sending of a zero-length fragment of a TSDU or ETSDU is
only permitted where this is used to indicate the end of a
TSDU or ETSDU, that is, when the TMORE flag is not set.
Some transport providers also forbid zero-length TSDUs and
ETSDUs.
If set in flags, requests that the provider transmit all
data that it has accumulated but not sent. The request is a
local action on the provider and does not affect any simi-
larly named protocol flag (for example, the TCP PUSH flag).
This effect of setting this flag is protocol-dependent, and
it may be ignored entirely by transport providers which do
not support the use of this feature.
The communications provider is free to collect data in a
send buffer until it accumulates a sufficient amount for
transmission.
By default, tsndv() operates in synchronous mode and may
wait if flow control restrictions prevent the data from
being accepted by the local transport provider at the time
the call is made. However, if ONONBLOCK is set by means
of topen(3NSL) or fcntl(2), tsndv() executes in asynchro-
nous mode, and will fail immediately if there are flow con-
trol restrictions. The process can arrange to be informed
when the flow control restrictions are cleared via either
tlook(3NSL) or the EM interface.
On successful completion, tsndv() returns the number of
bytes accepted by the transport provider. Normally this
SunOS 5.11 Last change: 23 Aug 2001 2
Networking Services Library Functions tsndv(3NSL)
will equal the total number of bytes to be sent, that is,
(iov0.iovlen ] .. ] iov[iovcount-1].iovlen)
However, the interface is constrained to send at most
INTMAX bytes in a single send. When tsndv() has submit-
ted INTMAX (or lower constrained value, see the note
above) bytes to the provider for a single call, this value
is returned to the user. However, if ONONBLOCK is set or
the function is interrupted by a signal, it is possible that
only part of the data has actually been accepted by the com-
munications provider. In this case, tsndv() returns a
value that is less than the value of nbytes. If tsndv() is
interrupted by a signal before it could transfer data to the
communications provider, it returns -1 with terrno set to
TSYSER and errno set to EINTR.
If the number of bytes of data in the iov array is zero and
sending of zero octets is not supported by the underlying
transport service, tsndv() returns -1 with terrno set to
TBADATA.
The size of each TSDU or ETSDU must not exceed the limits of
the transport provider as specified by the current values in
the TSDU or ETSDU fields in the info argument returned by
tgetinfo(3NSL).
The error TLOK is returned for asynchronous events. It is
required only for an incoming disconnect event but may be
returned for other events.
RETURN VALUES
On successful completion, tsndv() returns the number of
bytes accepted by the transport provider. Otherwise, -1 is
returned on failure and terrno is set to indicate the
error.
Note that in synchronous mode, if more than INTMAX bytes
of data are passed in the iov array, only the first
INTMAX bytes will be passed to the provider.
If the number of bytes accepted by the communications pro-
vider is less than the number of bytes requested, this may
either indicate that ONONBLOCK is set and the communica-
tions provider is blocked due to flow control, or that
SunOS 5.11 Last change: 23 Aug 2001 3
Networking Services Library Functions tsndv(3NSL)
ONONBLOCK is clear and the function was interrupted by a
signal.
VALID STATES
TDATAXFER, TINREL.
ERORS
On failure, terrno is set to one of the following:
TBADATA Illegal amount of data:
TBADF The specified file descriptor does not refer
to a transport endpoint.
o A single send was attempted specify-
ing a TSDU (ETSDU) or fragment TSDU
(ETSDU) greater than that specified
by the current values of the TSDU or
ETSDU fields in the info argument.
o A send of a zero byte TSDU (ETSDU)
or zero byte fragment of a TSDU
(ETSDU) is not supported by the pro-
vider.
o Multiple sends were attempted
resulting in a TSDU (ETSDU) larger
than that specified by the current
value of the TSDU or ETSDU fields in
the info argument - the ability of
an XTI implementation to detect such
an error case is implementation-
dependent. See WARNINGS, below.
o iovcount is greater than TIOVMAX.
TBADFLAG An invalid flag was specified.
TFLOW ONONBLOCK was set, but the flow control
mechanism prevented the transport provider
from accepting any data at this time.
TLOK An asynchronous event has occurred on this
transport endpoint.
TNOTSUPORT This function is not supported by the under-
lying transport provider.
SunOS 5.11 Last change: 23 Aug 2001 4
Networking Services Library Functions tsndv(3NSL)
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
tgetinfo(3NSL), topen(3NSL), trcvv(3NSL) trcv(3NSL),
tsnd(3NSL), attributes(5)
WARNINGS
It is important to remember that the transport provider
treats all users of a transport endpoint as a single user.
Therefore if several processes issue concurrent tsndv() or
tsnd(3NSL) calls, then the different data may be inter-
mixed.
Multiple sends which exceed the maximum TSDU or ETSDU size
may not be discovered by XTI. In this case an
implementation-dependent error will result (generated by the
transport provider), perhaps on a subsequent XTI call. This
error may take the form of a connection abort, a TSYSER, a
TBADATA or a TPROTO error.
SunOS 5.11 Last change: 23 Aug 2001 5
Networking Services Library Functions tsndv(3NSL)
If multiple sends which exceed the maximum TSDU or ETSDU
size are detected by XTI, tsndv() fails with TBADATA.
SunOS 5.11 Last change: 23 Aug 2001 6
|
