Use of XTI with Internet Protocols

Introduction

Note:

Applications written to compilation environments earlier than those required by this issue of the specification (see The Compilation Environment) and defining _XOPEN_SOURCE to be less than 500, may have these data structures and constants exposed through the inclusion of <xti.h>.

Protocol Features

The notion of TSDU is not supported by TCP transport provider, so the T_MORE flag will be ignored when TCP is used.

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. T_UDP has no urgent mechanism. See the TCP 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. They are the recommended means of releasing a TCP connection. 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.

Abortive Release

Functions t_snddis() and t_rcvdis() may be used to perform abortive release over TCP transport. However their use is not recommended as the abortive release primitive (RST segment) is not transmitted reliably by the TCP protocol.

Connection Establishment

TCP does not allow the possibility of refusing a connection indication. Each connection indication causes the TCP transport provider to establish the connection. Therefore, t_listen() and t_accept() have a semantic which is slightly different from that for ISO providers.

Connection Release

After a connection has been released, the local address bound to the endpoint may be qualified with the local IP address (rather than having a wildcard IP address). Also, the port number itself may have been changed during the t_accept() processing. If the endpoint is not being reused immediately then it is recommended that it should be unbound or closed so that other users can successfully bind to the address.

Options

TCP-level Options

These options do not have end-to-end significance. They may be negotiated in all XTI states except T_UNBND and T_UNINIT. They are read-only in state T_UNBND. See The Use of Options in XTI for the difference between options that have end-to-end significance and those that do not.

Absolute Requirements

A request for T_TCP_NODELAY and a request to activate T_TCP_KEEPALIVE is an absolute requirement. T_TCP_MAXSEG is a read-only option.

Further Remarks

T_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. According to RFC 1122 (see Referenced Documents):

"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:

 

struct t_kpalive {
    t_scalar_t kp_onoff;    /* switch option on/off */
    t_scalar_t kp_timeout;  /* keep-alive timeout   */
                            /* in minutes           */
}

Legal values for the field kp_onoff are:

T_NO

switch keep-alive timer off

T_YES

activate keep-alive timer

The field kp_timeout determines the frequency of keep-alive packets being sent, in minutes. 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 (see the referenced RFC 1122). Legal values for this field are T_UNSPEC and all positive numbers.

The timeout value is not an absolute requirement. The implementation may pose upper and lower limits to this value. Requests that fall short of the lower limit may be negotiated to the lower limit.

The use of this option might be restricted to privileged users.

T_TCP_MAXSEG

This option is read-only. It is used to retrieve the maximum TCP segment size.

T_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 which receive no replies, this packetisation may cause significant delays. T_TCP_NODELAY is used to defeat this algorithm. Legal option values are T_YES ("don't delay") and T_NO ("delay").

T_UDP-level Options

This option has end-to-end significance. It may be negotiated in all XTI states except T_UNBND and T_UNINIT. It is read-only in state T_UNBND. See The Use of Options in XTI for the difference between options that have end-to-end significance and those that do not.

Absolute Requirements

A request for this option is an absolute requirement.

Further Remarks

T_UDP_CHECKSUM

The option allows disabling/enabling of the T_UDP checksum computation. The legal values are T_YES (checksum enabled) and T_NO (checksum disabled).

If this option is returned with t_rcvudata(), its value indicates whether a checksum was present in the received datagram or not.

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 very controversial.

T_IP-level Options

T_IP_OPTIONS and T_IP_TOS are both options with end-to-end significance. All other options do not have end-to-end significance. See The Use of Options in XTI for the difference between options with end-to-end significance and options without.

T_IP_REUSEADDR may be negotiated in all XTI states except T_UNINIT. All other options may be negotiated in all other XTI states except T_UNBND and T_UNINIT; they are read-only in the state T_UNBND.

Absolute Requirements

A request for any of these options is an absolute requirement.

Further Remarks

T_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.

T_IP_DONTROUTE

This option indicates that outgoing messages should bypass the standard routing facilities. It is mainly used for testing and development.

T_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 T_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 will be 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 functions t_connect() (in synchronous mode), t_listen(), t_rcvconnect() and t_rcvudata() return the OPTIONS field, if any, of the received IP datagram associated with this call. The function t_rcvuderr() returns the OPTIONS field of the data unit previously sent that produced the error. The function t_optmgmt() with T_CURRENT set retrieves the currently effective T_IP_OPTIONS that is sent with outgoing datagrams.

Common applications never need this option. It is mainly used for network debugging and control purposes.

T_IP_REUSEADDR

Many TCP implementations do not allow the user to bind more than one transport endpoint to addresses with identical port numbers. If T_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.

T_IP_TOS

This option is used to set (retrieve) the type-of-service field of an outgoing (incoming) T_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:

• Precedence:

  These flags specify datagram precedence, allowing senders to indicate the importance of each datagram. They are intended for Department of Defense applications. Legal flags are:

  
  T_ROUTINE
  T_PRIORITY
  T_IMMEDIATE
  T_FLASH
  T_OVERRIDEFLASH
  T_CRITIC_ECP
  T_INETCONTROL
  T_NETCONTROL.
  

  Applications using T_IP_TOS but not the precedence level should use the value T_ROUTINE for precedence.

• Type of service:

  These flags specify the type of service the IP datagram desires. Legal flags are:

  
  
  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 functions t_connect(), t_listen(), t_rcvconnect() and t_rcvudata() return the type-of-service field of the received IP datagram associated with this call. The function t_rcvuderr() returns the type-of-service field of the data unit previously sent that produced the error.

The function t_optmgmt() with T_CURRENT set retrieves the currently effective T_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.

T_IP_TTL

This option¹ is used to set the time-to-live field in an outgoing IP datagram. It specifies how long, in seconds, 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 option with end-to-end significance).

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 0.

When (resfd != fd), the function t_accept() is recommended to be called with resfd in T_UNBND state, though an endpoint which is bound to any local address (in T_IDLE state) can also be used.

After t_accept() completes, the endpoint resfd will represent a connected TCP endpoint whose complete binding essentially has both local and remote address components.

If file descriptor resfd was unbound before calling t_accept(), after the call completes its local address binding would be to the same protocol address bound to fd. If file descriptor resfd was bound to a local address before calling t_accept(), that local address binding is dissolved and the local address part of the binding after t_accept() completes would become same as the address bound to fd.

If options with end-to-end significance (T_IP_OPTIONS, T_IP_TOS) are to be sent with the connection confirmation, the values of these options must be set with t_optmgmt() 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 which specifically includes a port identifier.

Some implementations treat port number 0 as a request to bind to any unused port. Other than that value, a port number part of the binding is specific. The IP address part of the binding can represent a single IP address or a wildcard binding to an address that could represent multiple IP addresses that are legal for the host.

t_close()

The t_close() call will result in a close call on the descriptor of this XTI communication endpoint. If there are no other descriptors in this process or any other process which reference this communication endpoint, the close() call will perform an orderly connection termination according to the rules of a TCP CLOSE call on this connection endpoint as specified in standards RFC 793 and RFC 1122. If the XTI_LINGER option is supported and is used to enable the linger option, the linger time will affect the time an implementation lingers in the execution of t_close() or close() A linger time of 0 specified with the XTI_LINGER option may cause an abortive release of a TCP connection, resulting in lost data.

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 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 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()

t_open() is called as the first step in the initialisation 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
		_	_
		T_TCP/T_IP	T_UDP/T_IP
name	x	/	/
oflag	x	/	/
info->addr	/	x	x
info->options	/	x	x
info->tsdu	/	0	x
info->etsdu	/	T_INFINITE	T_INVALID
info->connect	/	T_INVALID	T_INVALID
info->discon	/	T_INVALID	T_INVALID
info->servtype	/	T_COTS_ORD	T_CLTS
info->flags	/	0	T_SNDZERO

`x' equals T_INVALID (-2) or an integral number greater than zero.

t_rcv()

The T_MORE flag should be ignored if normal data is delivered. If a byte in the data stream is pointed to by the TCP urgent pointer, 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 will be 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 0 before the call to t_rcvconnect(). On return, the call->addr structure contains the address of the remote calling endpoint.

t_rcvdis()

Since data may not be sent with a disconnect, the discon->udata structure will not be meaningful.

t_snd()

The T_MORE flag should be ignored. If t_snd() is called with more than one byte specified and with the T_EXPEDITED flag set, then the last byte of the buffer will be the byte pointed to by the TCP urgent pointer. 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 may not be sent with a disconnect, call->udata.len must be set to zero.

t_sndudata()

Be aware that the maximum size of a connectionless-mode TSDU varies among implementations.

The <xti_inet.h> Header File

The data definitions and macros specified in this section need not be contained in <xti_inet.h> itself, but must be available to the application when <xti.h> is included and <xti_inet.h> is included after <xti.h>.

Note:

Applications written to compilation environments earlier than those required by this issue of the specification (see The Compilation Environment) and defining _XOPEN_SOURCE to be less than 500 may have the data structures and constants of this header automatically exposed by the inclusion of <xti.h> for compatibility.

Certain symbols may be exposed to applications including <xti_inet.h> for compatibility with applications transitioning from older issues of this specification where their semantics are specified. Exposing these symbols is allowed but not required. Symbols that may be exposed in this implementation-dependent manner are:

INET_TCP
TCP_NODELAY
TCP_MAXSEG
TCP_KEEPALIVE
T_GARBAGE
INET_UDP
INET_IP
IP_OPTIONS
IP_TOS
IP_TTL
IP_REUSEADDR
IP_DONTROUTE
IP_BROADCAST

There is an example <xti_inet.h> header file in Example XTI Header Files.

---

Footnotes

1.

This is a simplified description. Refer to RFC 1122 (see Referenced Documents) for precise details.

Contents

Next section

Index