Manpage of XTI-IP

XTI-IP

Section: X/Open Transport Interface (XTI) (3)
Updated: 2008-10-31
Index Return to Main Contents

NAME

xti_ip - X/Open Transport Interface - Corrigendum for Internet Protocol (IP) Conformance

SYNOPSIS

#include <xti.h>
#include <xti_ip.h>
#include <xti_inet.h>

int ip_stream = t_open(``/dev/rawip'', flags);
int ip_stream = t_open(``/dev/rawip2'', flags);

OVERVIEW

This manual page describes the XTI interface for IP in accordance with XNS 5.2[1].

The X/Open Transport Interface[1] specifies addressing and options for Internet Protocol (IP). Although this interface is always exposed by including the <xti.h> header file, it is provided by the <xti_ip.h> header file included by the former.

DESCRIPTION

This manual section describes the protocol-specific information that is relevant for IP transport providers. This section also describes the protocol-specific information that is relevant when IP services are provided over an IP network using IP.

This section also defines the data structures and constants required for IP transport providers that are exposed through the <xti.h> header file.

ADDRESS FORMAT

For convenience and traditionally, the transport interface address used by XTI for protocols in the TCP/IP protocol family use BSD-style socket addresses (also described in XNS 5.2[1]) for addresses.

The socket address, defined in <sys/socket.h>, is structured as follows:

struct sockaddr {
    uint16_t sa_family;
    char sa_data[14];
};

The Internet Protocol family socket address, defined in <netinet/in.h>, is structured as follows:

typedef unsigned int in_addr_t;
struct in_addr {
    in_addr_t  s_addr;
};
struct sockaddr_in {
    sa_family_t         sin_family;  /* Address family */
    unsigned short int  sin_port;    /* Port number */
    struct in_addr      sin_addr;    /* Internet address */
    /* padding */
};

The sockaddr_in structure contains the following members:

sin_family: The address family. Always set to AF_INET or AF_UNSPEC.
sin_port: The port number of the transport endpoint.
sin_addr: The IP address of the transport endpoint.
(padding): Padding to pad the size of the sockaddr_in structure to the size of a sockaddr structure.

The structure is padded to the size of a sockaddr structure (16 bytes).

OPTIONS

Options are formatted according to the t_opthdr structure as described in xti(3). An IP transport provider compliant to this specification supports none, all or any subset of the options defined here. An implementation may restrict the use of any of these options by offering them only in a priviledged read-only mode.

Options can be absolute requirements and can also be of end-to-end significance, as follows:

Absolute Requirements: Options that are absolute requirements, mean the when the option is negotiated with the transport service provider, the transport service provider is not permitted to negotiate the option to a value with differing quality of service. Either the proposed value is accepted or it is rejected. Options that are not absolute requirements, can be negotiated by the transport provider to a different quality of service level and it is the responsibility of the transport service user to determine whether the negotitated value is sufficient.
End-to-End Significance: Options that are of end-to-end significance are options that require negotiation with, or are communicated to, the peer transport provider or user. For example, options that are requested in a connection request, T_CONN_REQ(7), primitive will be indicated at the peer in a connection indication, T_CONN_IND(7), primitive. Options that are not of end-to-end significance are of local significance only and can be negotiated directly between the local transport service user and the local transport service provider.

An IP transport provider supports two levels of options. These two levels are described below.

XTI_GENERIC

Options with this level are specific to the X/Open Transport Interface (XTI/TLI)[2] and are common to all transport providers. For more information see xti(3).

The options defined with the option level XTI_GENERIC are as follows:

XTI_DEBUG

Sets debugging flags for the stream. This option is formatted as an array of t_uscalar_t. Legal values are implementation defined. For more information, see xti(3).

XTI_LINGER

Sets whether, and the amount of time if, the stream will linger waiting for unsent data to be delivered. This option is formatted as a t_linger structure as follows:

struct t_linger {
    t_scalar_t l_onoff;   /* option on/off */
    t_scalar_t l_linger;  /* linger time */
};

l_onoff: Specifies whether to linger (T_YES) or not (T_NO). Legal values are T_YES and T_NO.
l_linger: Specifies the amount of time (in seconds) to linger. Legal values are T_INFINITE, T_UNSPEC and all positive numbers including zero.

For more information, see xti(3).

XTI_RCVBUF

Specifies the size, in bytes, of the receive buffer. This option is formatted as a t_uscalar_t. Legal values are all positive, non-zero numbers. For more information, see xti(3).

XTI_RCVLOWAT

Specifies the low water mark above which received data will be indicated and delivered to the user. This option is formatted as a t_uscalar_t. Legal values are all positive, non-zero numbers. For more information, see xti(3).

XTI_SNDBUF

Specifies the size, in bytes, of the transmit buffer. This option is formatted as a t_uscalar_t. Legal values are all positive, non-zero numbers. For more information, see xti(3).

XTI_SNDLOWAT

Specifies the low water mark above which queued data will be transmitted to the peer. This option is formatted as a t_uscalar_t. Legal values are all positive, non-zero numbers. For more information, see xti(3).

T_INET_IP

Options within this level are specific to the Internet Protocol (IP) and are common to all the protocol levels in the TCP/IP suite. All options controlling the basic IP networking occur at this level.

The options defined with the option level T_INET_IP are as follows:

T_IP_OPTIONS

This option is used to set (retreive) the OPTIONS field of each outgoing (incoming) IP datagram. It 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 linst of addresses for the souce routing option 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(3) (in synchronous mode), t_listen(3), t_rcvconnect(3) and t_rcvudata(3) return the OPTIONS field, if any, of the received IP datagram associated with this call. The function t_rcvuderr(3) 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 application never need this option. It is mainly used for network debugging and control purposes.

This option is formated as an array (maximum 40 elements) of unsigned char. This option is an absolute requirement. This option has end-to-end significance.

T_IP_TOS

This option is used to set (retrieve) the type-of-service filed 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.

SET_TOS(prec, tos)

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.

prec

The precedence flags specify datagram precedence, allowing senders to indicate the importance of each datagram. They are intended for Department of Defence applications. Applications using T_IP_TOS but not the precedence level should use the value of T_ROUTINE for precedence. prec can be one of the following values:

T_ROUTINE: routine.
T_PRIORITY: priority precedence.
T_IMMEDIATE: immediate precedence.
T_FLASH: flash precedence.
T_OVERRIDEFLASH: flash override precedence.
T_CRITIC_ECP: flash override override precedence.
T_INETCONTROL: internetwork control.
T_NETCONTROL: network control.

tos

The type-of-service flags specify the type of service the IP datagram desires. tos can be one of the following values:

T_NOTOS: no type of service.
T_LDELAY: low delay.
T_HITHRPT: high throughput.
T_HIREL: high reliability.
T_LOCOST: low cost.

The functions t_connect(3), t_listen(3), t_rcvconnect(3) and t_rcvudata(3) return the type-of-service

This option is formatted as an unsigned char. This option is an absolute requirement. This option has end-to-end significance.

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

This option is formatted as an unsigned char. It can take on values between 0 and 255. This option is an absolute requirement. This option has local significance.

T_IP_REUSEADDR

Many TCP implementations do not allow the user to bind more than one transport endpoint address 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.

This option is formatted as an unsigned int. It can take on values T_YES or T_NO. This option is an absolute requirement. This option has local significance.

T_IP_DONTROUTE

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

This option is formatted as an unsigned int. It can take on values T_YES or T_NO. This option is an absolute requirement. This option has local significance.

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.

This option is formated as an unsigned int. It can take on values T_YES or T_NO. This option is an absolute requirement. This option has local significance.

BUGS

XTI-IP has no known bugs. The INET(4) implementation of XTI-IP has been conformance tested and validated using the test-inet_rawip(8) test case executable and the strinet autotest conformance and validation test suite.

NOTICES

In support of the sockets(3) library for tpi(7) transport providers, the options described here have been made compatible with the socket options described in raw(7). As a result, depending on the release of INET(4), the XTI/TLI options described might not be compatible with the options described here.

The Linux socket version of IP described in raw(7), accessed using the TPI interface of the strinet package described in INET(4), supports all of the options described here.

Earlier version of the INET(4) driver did not support wildcard binds. If an attempt was made to bind to a wildcard address or port number, the bind would fail with [TNOADDR]. While this is correct behavior, it was not consistent with other XTI-IP implemetnations. Recent versions of the INET(4) driver include the ability to bind to wildcards or to request that the transport service provider asign a suitable address.

UDPIncluding the <xti.h> header file may include the <xti_inet.h> header file. Including the <xti_inet.h> header file may include the <xti_ip.h> header file.

DEVICES

There are a number of IP devices providing the Transport Provider Interface that provide IP conforming TPI devices as follows:

/dev/ip, /dev/inet/ip
/dev/icmp, /dev/inet/icmp
/dev/ggp, /dev/inet/ggp
/dev/ipip, /dev/inet/ipip
/dev/egp, /dev/inet/egp
/dev/pup, /dev/inet/pup
/dev/idp, /dev/inet/idp
/dev/rawip, /dev/inet/rawip

These devices are provided by the OpenSS7INETNetworking(strinet-0.9.2.7) package. For more information on the TPI IP device, see rawip(4).

COMPATIBILITY

This interface is compatible with XNS 5.2[1], and implementations based on XNS 5.2, with the following portability considerations:

---: Internet Protocol (IP) options were not standardized until XPG4[2].
---: The format of options for the Transport Provider Interface (TPI) differ from those for the AT&T Transport Layer Interface (TLI). This interface follows the TPI.
---: The precise values of some options and formats of primitives may differ from implementation to implementation. Binary compatibility is not guaranteed.

See xti(3), for additional compatibility information.

CONFORMING TO

The OpenGroup XNS Issue 5.2[1]. Conformance is validated using the test-inet_rawip(8) test case executable and the strinet autotest validation test suite.

HISTORY

The Transport Provider Interface (TPI)[3] was first created by AT&T as the Transport Layer Interface (TLI) and was subsequently standardized by UNIX International and later by The OpenGroup in XPG4[2] and XNS 5.2[1].

The IP-TPI driver is specific to the OpenSS7 stack. This is an unofficial Corrigendum to XNS 5.2 Revision 2[1].

REFERENCES

[1]: XNS, Open Group CAE Specification: Technical Standard: Network Services (XNS), Issue 5.2, Draft 2, 1999, (Berkshire, UK), OpenGroup, Open Group Publication. [ISBN 1-85912-241-8] <http://www.opengroup.org/onlinepubs/>
[2]: XTI/TLI Revision 1.0, Open Group CAE Specification: XOpen Transport Interface, Revision 1, n.d., (Berkshire, UK), XPG, X Programmer's Group. <http://www.opengroup.org/onlinepubs/>
[3]: TPI Revision 2.0.0, Open Group CAE Specification: Transport Provider Interface (TPI) Specification, Revision 2.0.0, Draft 2, 1999, (Berkshire, UK), OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>