Internet Protocol-specific Information

General

This Appendix also defines data structures and constants required for TCP and UDP transport providers which are exposed through the <xti_inet.h> header file.

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, will have these data structures and constants exposed through the inclusion of <xti.h>.

Notes

• T_MORE flag and TSDUs

  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

/* INTERNET-SPECIFIC ENVIRONMENT */

/*
 *  TCP level
 *
 *  The values defined for the TCP Level are recommended-only,
 *  not mandatory.
 */

/*
 *  TCP-level Options
 *
 *  The values defined for the TCP-level Options are recommended-only,
 *  not mandatory.
 */


#define T_TCP_NODELAY   0x1 /* don't delay packets to coalesce */
#define TCP_NODELAY     0x1 /* (LEGACY)                  */

#define T_TCP_MAXSEG    0x2 /* get maximum segment size        */
#define TCP_MAXSEG      0x2 /* (LEGACY)                  */

#define T_TCP_KEEPALIVE 0x8 /* check, if connections are alive */
#define TCP_KEEPALIVE   0x8 /* (LEGACY)                  */

/*
 * Structure used with TCP_KEEPALIVE option.
 */


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

#define T_GARBAGE       0x02

/*
 *  UDP level
 *
 *  The values defined for the UDP Level are recommended-only,
 *  not mandatory.
 */
#define T_INET_UDP      0x11
#define INET_UDP        0x11       /* LEGACY            */

/*
 *  UDP-level Options
 *
 *  The values defined for the UDP-level Options are recommended-only,
 *  not mandatory.
 */

#define T_UDP_CHECKSUM  T_TCO_CHECKSUM  /* checksum computation */
#define UDP_CHECKSUM    T_TCO_CHECKSUM  /* LEGACY              */

/*
 *  IP level
 *
 *  The values defined for the IP Level are recommended-only,
 *  not mandatory.
 */
#define T_INET_IP      0x0
#define INET_IP        0x0   [??]LEGACY                 */

/*
 *  IP-level Options
 *
 *  The values defined for the IP-level Options are recommended-only,
 *  not mandatory.
 */

#define T_IP_OPTIONS   0x1   /* IP per-packet options            */
#define IP_OPTIONS     0x1   /* LEGACY                           */

#define T_IP_TOS       0x2   /* IP per-packet type of service    */
#define IP_TOS         0x2   /* LEGACY                           */

#define T_IP_TTL       0x3   /* IP per-packet time to live       */
#define IP_TTL         0x3   /* LEGACY                           */

#define T_IP_REUSEADDR 0x4   /* allow local address reuse        */
#define IP_REUSEADDR   0x4   /* LEGACY                           */

#define T_IP_DONTROUTE 0x10  /* just use interface addresses     */
#define IP_DONTROUTE   0x10  /* LEGACY                           */

#define T_IP_BROADCAST 0x20  /* permit sending of broadcast msgs */
#define IP_BROADCAST   0x20  /* LEGACY                           */

/*
 * IP_TOS precedence levels
 */

/*
 * IP_TOS type of service
 */

Footnotes

1.

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

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.