Previous section.

Networking Services (XNS) Issue 5
Copyright © 1997 The Open Group

Internet Protocol-specific Information

General

This appendix describes the protocol-specific information that is relevant for TCP and UDP transport providers.

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

Options

Options are formatted according to the structure t_opthdr as described in The Use of Options in XTI . A transport provider compliant to this specification supports none, all or any subset of the options defined in TCP-level Options , T_UDP-level Options and T_IP-level Options . An implementation may 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 T_INET_TCP. For this level, TCP-level Options shows the options that are defined.

Option Name Type of Option Legal Meaning
  Value Option Value  
T_TCP_KEEPALIVE struct t_kpalive see text check if connections are alive
T_TCP_MAXSEG t_uscalar_t length in octets get TCP maximum segment size
T_TCP_NODELAY t_uscalar_t T_YES/T_NO don't delay send to coalesce packets


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

The protocol level is T_INET_UDP. The option defined for this level is shown in T_UDP-level Option .

Option Name Type of Option Legal Meaning
  Value Option Value  
T_UDP_CHECKSUM t_uscalar_t T_YES/T_NO checksum computation


Table: T_UDP-level Option

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

The protocol level is T_INET_IP. The options defined for this level are listed in T_IP-level Options .

Option Name Type of Option Legal Meaning
  Value Option Value  
T_IP_BROADCAST unsigned int T_YES/T_NO permit sending of broadcast messages
T_IP_DONTROUTE unsigned int T_YES/T_NO just use interface addresses
T_IP_OPTIONS array of unsigned characters see text T_IP per-packet options
T_IP_REUSEADDR unsigned int T_YES/T_NO allow local address reuse
T_IP_TOS unsigned char see text T_IP per-packet type of service
T_IP_TTL unsigned char time in seconds T_IP per packet time-to-live


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

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 option1 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

This section presents definitions for the <xti_inet.h> header. The values defined for some of the symbolic constants are designated as not mandatory for conformance purposes. These are identified by a comment in the definitions.


/* INTERNET-SPECIFIC ENVIRONMENT */

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

#define T_INET_TCP 0x6  
#define INET_TCP 0x6 (LEGACY)





/*
 *  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
 */


#define T_ROUTINE 0
#define T_PRIORITY 1
#define T_IMMEDIATE 2
#define T_FLASH 3
#define T_OVERRIDEFLASH 4
#define T_CRITIC_ECP 5
#define T_INETCONTROL 6
#define T_NETCONTROL 7





/*
 * IP_TOS type of service
 */

#define T_NOTOS 0
#define T_LDELAY (1 << 4)
#define T_HITHRPT (1 << 3)
#define T_HIREL (1 << 2)
#define T_LOCOST (1 << 1)
     
#define SET_TOS(prec, tos) ((0x7 & (prec)) << 5 | (0x1c & (tos)))




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.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index