 |
Click this button to go to the index for this section. |
t_snd(3)
NAME
t_snd - Sends normal data or expedited data over a connection
LIBRARY
XTI Library (libxti.a)
SYNOPSIS
#include <xti.h>
int t_snd(
int fd,
char *buf,
unsigned nbytes,
int flags) ;
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
t_snd: XPG4-UNIX
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_snd() is called:
Parameters Before Call After Call
_____________________________________
fd y n
buf y(y) n
nbytes y n
flags y n
Notes to Table:
y This is a meaningful parameter.
n This is not a meaningful parameter.
(y) The content of the object pointed to by y is meaningful.
fd Specifies a file descriptor returned by the t_open() function that
identifies the local transport endpoint where an active connection
exists.
buf Points to the data buffer from which data is to be sent.
nbytes
Specifies the length in bytes of the send data buffer contents pointed
to by the buf parameter.
flags
Points to an integer whose bits specify certain optional information.
Corresponding values and symbolic names for these flag bits are
defined in the xti.h include file. Flags specified by this function
are:
Symbolic Name Meaning
T_MORE When set, this bit notifies the transport provider that sent
data is a fragment of a Transport Service Data Unit (TSDU)
or Expedited Transport Service Data Unit (ETSDU), and that
more data will be sent on the same TSDU or ETSDU via the
t_snd() function. The rest of the TSDU or ETSDU can be sent
through further t_snd() function calls.
Each time the T_MORE flag is set, another t_snd() call
follows so that additional parts of the TSDUs or ETSDUs can
be sent. When the final piece is sent, this flag bit is set
to a value of 0 (zero). When the transport provider does not
support TSDU or ETSDU data exchanges (refer to the t_open()
and t_getinfo() functions) the state of this flag bit is
meaningless.
Sending 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 T_MORE flag is not set. Some
transport providers also forbid zero-length TSDUs and
ETSDUs.
T_EXPEDITED When set, this bit notifies the transport provider that
expedited data is sent. When the value of ETSDU data exceeds
the value specified by nbytes parameter, this flag bit and
the T_MORE flag bit should be set prior to the initial
t_snd() call. Subsequent t_snd() calls used to send pieces
of ETSDU must have both these flag bits set. When the final
ETSDU is sent, the T_MORE flag bit is set to a value of 0
(zero).
VALID STATES
The t_snd() function can be called only in the T_DATAXFER and T_INREL
transport provider states.
DESCRIPTION
The t_snd() function is an XTI connection-oriented service function that is
used to send normal or expedited data. The transport endpoint through which
normal Transport Service Data Unit (TSDU) data or special Expedited TSDU
(ETSDU) data is sent is specified by a file descriptor previously returned
by the t_open() function.
The size of each TSDU or ETSDU must not exceed the size limits specified by
info->tsdu or info->etsdu, respectively, returned by the t_open() or
t_getinfo() functions. Failure to comply with specified size constraints
results in return of a [TSYSERR] protocol error. By default, the t_snd()
function executes in the synchronous operating mode. In the synchronous
operating mode t_snd() waits for data to be accepted by the transport
provider, before returning control to the calling transport user.
When the transport endpoint specified by the file descriptor has been
opened with the O_NONBLOCK flag set in the t_open() or fcntl() function,
the t_snd() function executes in asynchronous mode. When data cannot be
immediately accepted because flow control restrictions apply, control is
immediately returned to the caller.
When the t_snd() function executes successfully, the number of bytes
accepted by the transport provider is returned. It is possible that only
part of the data may be accepted by a transport provider. When only partial
data is accepted, the returned value is less than the number of bytes sent.
If the nbytes parameter is specified as 0 (zero), and the underlying
transport service does not support the sending of 0 octets, t_errno is set
to [TBADDATA] and -1 is returned.
NOTES
In asynchronous mode, when the number of bytes accepted by the transport
provider is less than the number of bytes sent, the transport provider may
be blocked because of flow-control restrictions.
The transport provider treats all users of a transport endpoint as a single
user. Therefore, if several processes issue concurrent t_snd() calls, then
the different data may be intermixed.
Multiple sends which exceed the maximum TSDU or ERSDU size may not be
discovered by XTI. In this case, an implementation-dependent error will
result, which may take the form of a connection abort, or a [TSYSERR],
[TBADDATA], or a [TPROTO] error.
If XTI detects multiple sends that exceed the maximum TSDU or ETSDU size,
t_snd() fails with the error [TBADDATA].
RETURN VALUES
Upon successful completion, the t_snd() function returns the number of
bytes of data accepted by the transport provider. Otherwise, -1 is returned
and t_errno is set to indicate the error.
ERRORS
If the t_snd(|) function fails, t_errno may be set to one of the following
values:
[TBADF] File descriptor fd does not refer to a valid transport endpoint.
[TBADDATA]
Illegal amount of data:
·
A single send was attempted specifying a TSDU or ETSDU, or a
fragment TSDU or ETSDU, greater than that specified by the
current values of the TSDU or ETSDU fields in the info
argument.
·
A send of a zero-byte TSDU or ETSDU, or a zero-byte fragment of
a TSDU or ETSDU, is not supported by the provider.
·
Multiple sends were attempted, which resulted in a TSDU or
ETSDU larger than that specified by the current values of the
TSDU or ETSDU fields in the info argument. The ability to
detect this error is implementation dependent.
[TBADFLAG]
An invalid flags value was specified.
[TFLOW]
Asynchronous mode is indicated because O_NONBLOCK was set, but no data can
currently be accepted by the transport provider because of flow-control
restrictions.
[TLOOK]
An asynchronous event occurred on this transport endpoint.
[TOUTSTATE]
The t_snd() function was issued in the wrong sequence on the transport
endpoint referenced by the fd parameter.
[TSYSERR]
A system error occurred during execution of the t_snd() function. A
protocol error may not cause t_snd() to fail until a subsequent access of
the transport endpoint is made.
[TNOTSUPPORT]
This function is not supported by the underlying transport provider.
[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(t_errno).
RELATED INFORMATION
Functions: fcntl(2), t_getinfo(3), t_look(3), t_open(3), t_optmgmt(3),
t_rcv(3)