 |
Click this button to go to the index for this section. |
xti_internet(7)
NAME
xti_internet - Internet Protocol-specific information on XTI
DESCRIPTION
This reference page provides protocol-specific information that is relevant
for TCP and UDP transport providers. It includes information on the
following:
· General notes
· Options
· Functions
GENERAL NOTES
T_MORE flag and transport service data units (TSDUs)
TSDU is not supported by a TCP transport provider, so the T_MORE flag
is ignored when TCP is used. The TCP PUSH flag cannot be used through
the XTI interface because the TCP Military Standard states the
following:
Successive pushes may not be preserved because two or more units
of pushed data may be joined into a single pushed unit by either
the sending or receiving TCP. Pushes are not visible to the
receiving Upper Level Protocol and are not intended to serve as a
record boundary marker.
Expedited data
TCP does not have a notion of expedited data in a sense comparable to
ISO expedited data. TCP defines an urgent mechanism, by which in-line
data is marked for urgent delivery. UDP has no urgent mechanism. See
the TCP Military Standard for more detailed information.
Orderly release
The orderly release functions t_sndrel and t_rcvrel were defined to
support the orderly release facility of TCP. The specification of TCP
states that only established connections may be closed with orderly
release; that is, on an endpoint in T_DATAXFER or T_INREL state.
Connection establishment
TCP does not allow the possibility of refusing a connection indication.
Each connect indication causes the TCP transport provider to establish
the connection. Therefore, t_listen and t_accept have a semantic that
is slightly different from that for ISO providers.
OPTIONS
Options are formatted according to the structure t_opthdr as described in
the xti(7) reference page. A transport provider compliant to this
specification supports none, all, or any subset of the options defined in
this section. An implementation can restrict the use of any of these
options by offering them only in the privileged or read-only mode.
TCP-level Options
The protocol level is INET_TCP. The following table shows the options that
are defined for this level:
_________________________________________________________________
Meaning
Option Name
Type of Option
Value
Legal Option
Value
_________________________________________________________________
TCP_KEEPALIVE struct t_kpalive See text
Check if
connections are
alive.
TCP_MAXSEG Unsigned long
Length in
octets
Get TCP maximum
segment size.
TCP_NODELAY Unsigned long T_YES/T_NO
Do not delay
send to
coalesce
packets.
These options are not association-related. They can be negotiated in all
XTI states except T_UNBND and T_UNINIT. They are read-only in the T_UNBND
state. See the xti(7) reference page for the difference between options
that are association-related and those that are not.
A request for TCP_NODELAY and a request to activate TCP_KEEPALIVE is an
absolute requirement. TCP_MAXSEG is a read-only option.
TCP_KEEPALIVE
If this option is set, a keep-alive timer is activated to monitor idle
connections that might no longer exist. If a connection has been idle
since the last keep-alive timeout, a keep-alive packet is sent to check
if the connection is still alive or broken.
Keep-alive packets are not an explicit feature of TCP, and this
practice is not universally accepted. RFC1122 states the following:
... a keep-alive mechanism should only be invoked in server
applications that might otherwise hang indefinitely and consume
resources unnecessarily if a client crashes or aborts a
connection during a network failure.
The option value consists of a structure t_kpalive declared as follows:
struct t_kpalive {
long kp_onoff; /* switch option on or off */
long kp_timeout; /* keepalive timeout in minute */
}
Legal values for the kponoff field are:
·
T_NO - Switch keep-alive time off
·
T_YES - Activate keep-alive timer
·
T_YES | T_GARBAGE - Activate keep-alive timer and send garbage octet
Usually, an implementation should send a keep-alive packet with no data
(T_GARBAGE not set). If T_GARBAGE is set, the keep-alive packet
contains one garbage octet for compatibility with erroneous TCP
implementations.
An implementation is not obliged to support T_GARBAGE. Since the
kp_onoff value is an absolute requirement, the request T_YES |
T_GARBAGE can therefore be rejected.
The kp_timeout field determines the frequency in minutes of keep-alive
packets being sent. The transport user can request the default value
by setting the field to T_UNSPEC. The default is implementation-
dependent, but at least 120 minutes. Legal values for this field are
T_UNSPEC and all positive numbers.
The timeout value is not an absolute requirement. The implementation
can pose upper and lower limits to this value. Requests that fall
short of the lower limit can be negotiated to the lower limit.
The use of this option might be restricted to privileged users.
TCP_MAXSEG
This option is read-only. It is used to retrieve the maximum TCP
segment size.
TCP_NODELAY
Under most circumstances, TCP sends data as soon as it is presented.
When outstanding data has not yet been acknowledged, it gathers small
amounts of output to be sent in a single packet once an acknowledgement
is received. For a small number of clients, such as window systems
(for example, MIT X Window System) that send a stream of mouse events
that receive no replies, this packetisation can cause significant
delays. TCP_NODELAY is used to defeat this algorithm. Legal option
values are T_YES, which indicates do not delay, and T_NO, which
indicates delay.
UDP-level Options
The protocol level is INET_UDP. The following table shows the option
defined for this level:
____________________________________________________________________
Meaning
Option Name
Type of Option
Value
Legal Option
Value
____________________________________________________________________
UDP_CHECKSUM Unsigned long T_YES/T_NO Checksum computation.
This option is association-related. It can be negotiated in all XTI states
except T_UNBND and T_UNINIT. It is read-only in the T_UNBND state. See
the xti(7) reference page for the difference between options that are
association-related and those that are not.
A request for UDP_CHECKSUM is an absolute requirement.
UDP_CHECKSUM
The option allows enabling and disabling of the UDP checksum
computation. The legal values are T_YES, checksum enabled, and T_NO,
checksum disabled.
If this option is returned with the t_rcvudata function, its value
indicates whether a checksum was present in the received datagram.
Numerous cases of undetected errors have been reported when
applications chose to turn off checksums for efficiency. The
advisability of ever turning off the checksum check is controversial.
IP-level Options
The protocol level is INET_IP. The following table shows the options
defined for this level:
________________________________________________________________
Meaning
Option Name
Type of Option
Value
Legal Option
Value
________________________________________________________________
IP_BROADCAST Unsigned int T_YES/T_NO
Permit sending
of broadcast
messages.
IP_DONTROUTE Unsigned int T_YES/T_NO
Just use
interface
addresses.
IP_OPTIONS See text
Array of
unsigned
characters
IP per-packet
options.
IP_REUSEADDR Unsigned int T_YES/T_NO
Allow local
address reuse.
IP_TOS Unsigned char See text
IP per-packet
type of
service.
IP_TTL Unsigned char Time in seconds
IP per-packet
time-to-live.
IP_OPTIONS and IP_TOS are association-related options. All other options
are not association-related. See the xti(7) reference page for the
difference between options that are association-related and those that are
not.
IP_REUSEADDR can be negotiated in all XTI states except T_UNINIT. All
other options can be negotiated in all other XTI states except T_UNBND and
T_UNINIT; they are read-only in the T_UNBND state.
A request for any of these options is an absolute requirement.
IP_BROADCAST
This option requests permission to send broadcast datagrams. It was
defined to make sure that broadcasts are not generated by mistake. The
use of this option is often restricted to privileged users.
IP_DONTROUTE
This option indicates that outgoing messages should bypass the standard
routing facilities. It is mainly used for testing and development.
IP_OPTIONS
This option is used to set (retrieve) the OPTIONS field of each
outgoing (incoming) IP datagram. Its value is a string of octets
composed of a number of IP options, whose format matches those defined
in the IP specification with one exception: the list of addresses for
the source routing options must include the first-hop gateway at the
beginning of the list of gateways. The first-hop gateway address is
extracted from the option list and the size adjusted accordingly before
use.
The option is disabled if it is specified with no value; that is, with
an option header only.
The t_connect (in synchronous mode), t_listen, t_rcvconnect, and
t_rcvudata functions return the OPTIONS field, if any, of the received
IP datagram associated with this call. The t_rcvuderr function returns
the OPTIONS field of the data unit previously sent that produced the
error. The t_optmgmt function with T_CURRENT set retrieves the
currently effective IP_OPTIONS that is sent with out going datagrams.
Common applications never need this option. It is mainly used for
network debugging and control purposes.
IP_REUSEADDR
Many TCP implementations do not allow the user to bind more than one
transport endpoint to addresses with identical port numbers. If
IP_REUSEADDR is set to T_YES this restriction is relaxed in the sense
that it is now allowed to bind a transport endpoint to an address with
a port number and an underspecified Internet address (wild card
address) and further endpoints to addresses with the same port number
and (mutually exclusive) fully specified Internet addresses.
IP_TOS
This option is used to set (retrieve) the type-of-service field of an
outgoing (incoming) IP datagram. This field can be constructed by any
OR'ed combination of one of the precedence flags and the type-of-
service flags T_LDELAY, T_HITHRPT, and T_HIREL, as follows:
·
Precedence
These flags specify datagram precedence, allowing senders to indicate
the importance of each datagram. They are intended for Department of
Defense applications. The following are legal flags:
--
T_ROUTINE
--
T_PRIORITY
--
T_IMMEDIATE
--
T_FLASH
--
T_OVERRIDEFLASH
--
T_CRITIC_ECP
--
T_INETCONTROL
--
T_NETCONTROL
Applications using IP_TOS but not the precedence level should use the
T_ROUTINE value for precedence.
·
Type of service
These flags specify the type of service the IP datagram requests.
The following are legal flags:
--
T_NOTOS - Requests no distinguished type of service.
--
T_LDELAY - Requests low delay.
--
T_HITHRPT - Requests high throughput
--
T_HIREL - Requests high reliability.
The option value is set using the macro SET_TOS (prec, tos), where prec
is set to one of the precedence flags and tos to one or an OR'ed
combination of the type-of-service flags. SET_TOS returns the option
value.
The t_connect, t_listen, t_rcvconnect, and t_rcvudata functions return
the type-of-service field of the received IP datagram associated with
this call. The t_rcvuderr function returns the type-of-service field
of the data unit previously sent that produced the error.
The t_optmgmt function with T_CURRENT set retrieves the currently
effective IP_TOS value that is sent with outgoing datagrams.
The requested type-of-service cannot be guaranteed. It is a hint to
the routing algorithm that helps it choose among various paths to a
destination. Note also, that most hosts and gateways in the Internet
these days ignore the type-of-service field.
IP_TTL
This option is used to set the time-to-live field in an outgoing IP
datagram. It specifies in seconds how long the datagram is allowed to
remain in the Internet. The time-to-live field of an incoming datagram
is not returned by any function (since it is not an association-related
option).
FUNCTIONS
t_accept
Issuing t_accept assigns an already established connection to resfd.
Since user data cannot be exchanged during the connection establishment
phase, call->udata.len must be set to zero (0). Also, resfd must be
bound to the same address as fd. A potential restriction on binding of
endpoints to protocol addresses is described under the t_bind function.
If association-related options (IP_OPTIONS and IP_TOS) are to be sent
with the connect confirmation, the values of these options must be set
with the t_optmgmt function before the T_LISTEN event occurs. When the
transport user detects a T_LISTEN, TCP has already established the
connection. Association-related options passed with t_accept become
effective at once, but since the connection is already established,
they are transmitted with subsequent IP datagrams sent out in the
T_DATAXFER state.
t_bind
The addr field of the t_bind structure represents the local socket;
that is an address that specifically includes a port identifier.
In the connection-oriented mode (that is, TCP), the t_bind function can
only bind one transport endpoint to any particular protocol address.
If that endpoint was bound in passive mode; that is qlen > 0, other
endpoints will be bound to the passive endpoint's protocol address
through the t_accept function only. That is, if fd refers to the
passive endpoint and resfd refers to the new endpoint on which the
connection is to be accepted, resfd will be bound to the same protocol
address as fd after the successful completion of the t_accept function.
t_connect
The sndcall->addr structure specifies the remote socket. In the
present version, the returned address set in rcvcall->addr will have
the same value. Since user data cannot be exchanged during the
connection establishment phase, sndcall->udata.len must be set to zero
(0).
Note that the peer TCP, and not the peer transport user, confirms the
connection.
t_listen
Upon successful return, t_listen indicates an existing connection and
not a connection indication.
Since user data cannot be exchanged during the connection establishment
phase, call->udata.maxlen must be set to zero (0) before the call to
t_listen. The call->addr structure contains the remote calling socket.
t_look
As soon as a segment with the TCP urgent pointer set enters the TCP
receive buffer, the event T_EXDATA is indicated. T_EXDATA remains set
until all data up to the byte pointed to by the TCP urgent pointer has
been received. If the urgent pointer is updated, and the user has not
yet received the byte previously pointed to by the urgent pointer, the
update is invisible to the user.
t_open
The t_open function is called as the first step in the initialization
of a transport endpoint. This function returns various default
characteristics of the underlying transport protocol by setting fields
in the t_info structure.
The following should be the values returned by the call to t_open and
t_getinfo with the indicated transport providers:
_____________________________________________________________
Parameters
Before Call
After Call
TCP/IP
After Call
UDP/IP
_____________________________________________________________
name x / /
oflag x / /
info->addr / x x
info->options / x x
info->tsdu / 0 x
info->etsdu / -1 -2
info->connect / -2 -2
info->discon / -2 -2
info->servtype / T_CLTS
T_COTS/T_COTS_ORD
info->flags / T_SNDZERO T_SNDZERO
Table Notes:
x equals -2 or an integral number greater than zero (0).
t_rcv
The T_MORE flag should be ignored if normal data is delivered. If the
TCP urgent pointer points to a byte in the data stream, as many bytes
as possible preceding this marked byte and the marked byte itself are
denoted as urgent data and are received with the T_EXPEDITED flag set.
If the buffer supplied by the user is too small to hold all urgent
data, the T_MORE flag is set, indicating that urgent data still remains
to be read. Note that the number of bytes received with the
T_EXPEDITED flag set is not necessarily equal to the number of bytes
sent by the peer user with the T_EXPEDITED flag set.
t_rcvconnect
Since user data cannot be exchanged during the connection establishment
phase, call->udata.maxlen must be set to zero (0) before the call to
t_rcvconnect. On return, the call->addr structure contains the remote
calling socket.
t_rcvdis
Since data cannot be sent with a disconnect, the
discon->udata structure will not be meaningful.
t_snd
If t_snd is called with more than one byte specified and with the
T_EXPEDITED flag set, the TCP urgent pointer points to the last byte of
the buffer. If the T_EXPEDITED flag is set, at least one byte must be
sent.
Implementor's Note
Data for a t_snd call with the T_EXPEDITED flag set may not
pass data sent previously.
t_snddis
Since data cannot be sent with a disconnect, the
call->udata.len must be set to zero (0).
t_sndudata
Be aware that the maximum size of a connectionless TSDU varies among
implementations.
RELATED INFORMATION
t_optmgmt(3), xti(7)
Network Programmer's Guide, X/Open CAE Specification: Networking Services,
Issue 4