Networking Services Library Functions tsnd(3NSL)
NAME
tsnd - send data or expedited data over a connection
SYNOPSIS
#include
int tsnd(int fd, void *buf, unsigned int nbytes, int flags);
DESCRIPTION
This routine 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 routine that has the
same name as an XTI routine, 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 is used to send either normal or expedited
data. The argument fd identifies the local transport end-
point over which data should be sent, buf points to the user
data, nbytes specifies the number of bytes of user data to
be sent, and 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 tran-
sport provider that the transport service
data unit (TSDU) (or expedited transport
service data unit - ETSDU) is being sent
through multiple tsnd() calls. Each
tsnd() with the TMORE flag set indicates
that another tsnd() will follow with more
data for the current TSDU (or ETSDU).
The end of the TSDU (or ETSDU) is identified
by a tsnd() 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 connection. 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
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions tsnd(3NSL)
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.
TPUSH 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
similarly 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.
Note that the communications provider is free to collect
data in a send buffer until it accumulates a sufficient
amount for transmission.
By default, tsnd() 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), tsnd() will execute in asyn-
chronous mode, and will fail immediately if there are flow
control restrictions. The process can arrange to be informed
when the flow control restrictions are cleared by means of
either tlook(3NSL) or the EM interface.
On successful completion, tsnd() returns the number of
bytes (octets) accepted by the communications provider.
Normally this will equal the number of octets specified in
nbytes. 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 communications
provider. In this case, tsnd() returns a value that is
less than the value of nbytes. If tsnd() 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.
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions tsnd(3NSL)
If nbytes is zero and sending of zero bytes is not supported
by the underlying communications service, tsnd() 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, tsnd() 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 if the number of bytes accepted by the communica-
tions provider is less than the number of bytes requested,
this may either indicate that ONONBLOCK is set and the
communications provider is blocked due to flow control, or
that ONONBLOCK is clear and the function was interrupted
by a signal.
ERORS
On failure, terrno is set to one of the following:
TBADATA Illegal amount of data:
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-
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions tsnd(3NSL)
dependent. See WARNINGS, below.
TBADF The specified file descriptor does not refer
to a transport endpoint.
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.
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
SunOS 5.11 Last change: 7 May 1998 4
Networking Services Library Functions tsnd(3NSL)
The terrno values that can be set by the XTI interface and
cannot be set by the TLI interface are:
TPROTO
TLOK
TBADFLAG
TOUTSTATE
The terrno values that this routine can return under dif-
ferent circumstances than its XTI counterpart are:
TBADATA
In the TBADATA error cases described above, TBADATA is
returned, only for illegal zero byte TSDU ( ETSDU) send
attempts.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
fcntl(2), tgetinfo(3NSL), tlook(3NSL), topen(3NSL),
trcv(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 tsnd()
calls then the different data may be intermixed.
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.
If multiple sends which exceed the maximum TSDU or ETSDU
size are detected by XTI, tsnd() fails with TBADATA.
SunOS 5.11 Last change: 7 May 1998 5
|
