*** UNIX MANUAL PAGE BROWSER ***

xti_internet(7) Miscellaneous Information Manual xti_internet(7) NAME xti_internet - Internet Protocol-specific information on XTI DESCRIPTION This reference page provides protocol-specific information that is rel- evant for TCP and UDP transport providers. It includes information on the following: General notes Options Functions GENERAL NOTES 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 follow- ing: 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 re- ceiving Upper Level Protocol and are not intended to serve as a record boundary marker. 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. The orderly release functions t_sndrel and t_rcvrel were defined to support the or- derly release facility of TCP. The specification of TCP states that only established connections may be closed with orderly re- lease; that is, on an endpoint in T_DATAXFER or T_INREL state. TCP does not allow the possibility of refusing a connection in- dication. 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: tab (@); lfHB lfHB lfHB lfHB l l l l. _ T{ Option Name T}@T{ Type of Option Value T}@T{ Legal Option Value T}@Meaning _ TCP_KEEPALIVE@struct t_kpalive@See text@T{ Check if connections are alive. T} TCP_MAXSEG@Unsigned long@T{ Length in octets T}@T{ Get TCP maximum seg- ment size. T} TCP_NODELAY@Unsigned long@T_YES/T_NO@T{ Do not delay send to coalesce packets. T} 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 be- tween 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. If this op- tion is set, a keep-alive timer is activated to monitor idle connec- tions 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 fol- lowing: ... a keep-alive mechanism should only be invoked in server ap- plications that might otherwise hang indefinitely and consume resources unnecessarily if a client crashes or aborts a connec- tion 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 implemen- tation 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. This option is read-only. It is used to retrieve the maximum TCP segment size. 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 val- ues are T_YES, which indicates do not delay, and T_NO, which in- dicates delay. UDP-level Options The protocol level is INET_UDP. The following table shows the option defined for this level: tab (@); lfHB lfHB lfHB lfHB l l l l. _ T{ Option Name T}@T{ Type of Option Value T}@T{ Legal Option Value T}@Meaning _ 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 op- tions that are association-related and those that are not. A request for UDP_CHECKSUM is an absolute requirement. The option al- lows 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 ap- plications chose to turn off checksums for efficiency. The ad- visability of ever turning off the checksum check is controver- sial. IP-level Options The protocol level is INET_IP. The following table shows the options defined for this level: tab (@); lfHB lfHB lfHB lfHB l l l l. _ T{ Option Name T}@T{ Type of Option Value T}@T{ Legal Option Value T}@Meaning _ IP_BROADCAST@Unsigned int@T_YES/T_NO@T{ Permit sending of broadcast messages. T} IP_DONTROUTE@Unsigned int@T_YES/T_NO@T{ Just use interface addresses. T} IP_OPTIONS@T{ Array of unsigned characters T}@See text@T{ IP per-packet options. T} IP_REUSEADDR@Unsigned int@T_YES/T_NO@T{ 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. T} IP_OPTIONS and IP_TOS are association-related options. All other op- tions 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. 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. This option indi- cates that outgoing messages should bypass the standard routing facili- ties. It is mainly used for testing and development. 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 op- tions must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address is extracted from the op- tion 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. Many TCP implemen- tations do not allow the user to bind more than one transport endpoint to addresses with identical port numbers. If IP_REUSE- ADDR is set to T_YES this restriction is relaxed in the sense that it is now allowed to bind a transport endpoint to an ad- dress 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 Inter- net addresses. 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 in- dicate 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 re- quests. 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 re- liability. 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 as- sociated with this call. The t_rcvuderr function returns the type-of-service field of the data unit previously sent that pro- duced the error. The t_optmgmt function with T_CURRENT set retrieves the cur- rently effective IP_TOS value that is sent with outgoing data- grams. 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. 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 Issuing t_accept assigns an already established connection to resfd. Since user data cannot be exchanged during the connection estab- lishment phase, call->udata.len must be set to zero (0). Also, resfd must be bound to the same address as fd. A potential re- striction on binding of endpoints to protocol addresses is de- scribed 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 op- tions 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. 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 func- tion can only bind one transport endpoint to any particular pro- tocol address. If that endpoint was bound in passive mode; that is qlen > 0, other endpoints will be bound to the passive end- point'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. The snd- call->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, con- firms the connection. Upon successful return, t_listen indi- cates an existing connection and not a connection indication. Since user data cannot be exchanged during the connection estab- lishment phase, call->udata.maxlen must be set to zero (0) be- fore the call to t_listen. The call->addr structure contains the remote calling socket. 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 re- ceived. 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. The t_open func- tion is called as the first step in the initialization of a transport endpoint. This function returns various default char- acteristics 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: tab (@); lfHB lfHB lfHB lfHB l l l l. _ T{ Parameters T}@T{ Before Call T}@T{ After Call TCP/IP T}@T{ After Call UDP/IP T} _ 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{ T_COTS/T_COTS_ORD T}@T_CLTS info->flags@/@T_SNDZERO@T_SNDZERO Table Notes: x equals -2 or an integral number greater than zero (0). 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, indicat- ing 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. Since user data cannot be ex- changed 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. Since data cannot be sent with a discon- nect, the discon->udata structure will not be meaningful. 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. Data for a t_snd call with the T_EXPE- DITED flag set may not pass data sent previously. Since data cannot be sent with a disconnect, the call->udata.len must be set to zero (0). Be aware that the maximum size of a connec- tionless TSDU varies among implementations. RELATED INFORMATION t_optmgmt(3), xti(7) Network Programmer's Guide, X/Open CAE Specification: Networking Ser- vices, Issue 4 delim off xti_internet(7)