X/Open Transport Interface (XTI)

XNET

Section: The OpenSS7 Project Library Calls (3)
Updated: Tue, 02 Dec 2008 10:19:03 GMT
Index Return to Main Contents

NAME

xti, xnet - XNS 5.2 XTI/TLI Library (libxnet)

SYNOPSIS

#include <sys/xti.h>

int t_accept(int fd, int connfd, struct t_call *call);
void *t_alloc(int fd, int type, int fields);
int t_bind(int fd, struct t_bind *req, struct t_bind *ret);
int t_close(int fd);
int t_connect(int fd, struct t_call *sndcall, struct t_call *rcvcall);
extern int t_errno;
void t_error(char *errmsg);
int t_free(void *ptr, int type);
int t_getinfo(int fd, struct t_info *info);
int t_getstate(int fd);
int t_listen(int fd, struct t_call *call);
int t_look(int fd);
int t_open(char *path, int oflag, struct t_info *info);
int t_optmgmt(int fd, const struct t_optmgmt *req, struct t_optmgmt *ret);
int t_rcvconnect(int fd, struct t_call *call);
int t_rcvdis(int fd, struct t_discon *dis);
int t_rcv(int fd, char *buf, unsigned int nbytes, int *flags);
int t_rcvreldata(int fd, struct t_discon *discon);
int t_rcvrel(int fd);
int t_rcvudata(int fd, struct t_unitdata *data, int *flags);
int t_rcvuderr(int fd, struct t_uderr *err);
int t_rcvv(int fd, struct t_iovec *iov, unsigned int iovcnt, int *flags);
int t_rcvvudata(int fd, struct t_unitdata *data, struct t_iovec *iov, unsigned int iovcnt, int *flags);
int t_snddis(int fd, const struct t_call *call);
int t_snd(int fd, char *buf, unsigned int nbytes, int flags);
int t_sndreldata(int fd, struct t_discon *discon);
int t_sndrel(int fd);
int t_sndudata(int fd, struct t_unitdata *data);
int t_sndv(int fd, struct t_iovec *iov, unsigned int iovcnt, int flags);
int t_sndvudata(int fd, struct t_unitdata *data, struct t_iovec *iov, unsigned int iovcnt, int flags);
int t_sync(int fd);
int t_unbind(int fd);

OVERVIEW

libxnet
is an OpenSS7 implementation of the XNS 5.2 XTI/TLI Library for LFS (Linux Fast-STREAMS).

DESCRIPTION

libxnet implements the following XTI/TLI API library functions:

t_accept(3): accept a connection request.
t_alloc(3): allocate a library structure.
t_bind(3): bind to a transport endpoint.
t_close(3): close a transport endpoint.
t_connect(3): establish a transport connection.
t_errno(3): TLI error number.
t_error(3): print an error message.
t_free(3): free an XTI/TLI library structure.
t_getinfo(3): get protocol information.
t_getstate(3): get interface state.
t_listen(3): listen for a transport connection request.
t_look(3): look for a transport event.
t_open(3): open a transport endpoint.
t_optmgmt(3): manage transport options.
t_rcvconnect(3): receive connection request confirmation.
t_rcvdis(3): receive abortive disconnect.
t_rcv(3): receive transport data.
t_rcvreldata(3): acknowledge orderly release request with data.
t_rcvrel(3): acknowledge orderly release request.
t_rcvudata(3): receive unitdata.
t_rcvuderr(3): receive unitdata error.
t_rcvv(3): receive data and scatter.
t_rcvvudata(3): receive unitdata and scatter.
t_snddis(3): send abortive disconnect.
t_snd(3): send transport data.
t_sndreldata(3): send orderly release with data.
t_sndrel(3): send orderly release.
t_sndudata(3): send unitdata.
t_sndv(3): gather and send data.
t_sndvudata(3): gather and send unitdata.
t_sync(3): synchronize XTI/TLI library with TLI provider.
t_unbind(3): unbind.

OPTIONS

XTI/TLI Generic Options

Several options are independent of transport service provider. These options are specified at the option level XTI_GENERIC, and are defined as follows:

XTI_DEBUG

This option enables debugging. The values of this option are implementation defined. Debugging is disabled if the option is specified with ``no value''; that is, with an option header only. The system supplies utilities to process the traces. Note that an implementation may also provide other means for debugging.

This option is formatted as an array of t_uscalar_t. This option is an absolute requirement. Legal values are implementation defined.

This option can be negotiated in any XTI/TLI transport endpoint state. This option can be negotiated using the t_optmgmt(3), t_connect(3) or t_accept(3) XTI/TLI library calls.

XTI_LINGER

This option is used to linger the execution of a t_close(3) or close(2) if send data is still queue in the send buffer. The option value specifies the linger period. If a close(2) or t_close(3) is issued and the send buffer is not empty, the system attempts to send the pending data within the linger period before closing the endpoint. Data still pending after the linger period has elapsed is discarded.

Depending on the implementation, t_close(3) or close(2) either blocks for, at maximum, the linger period, or immediately returns, whereupon the system holds the connection in existence for at most the linger period.

This option is formatted as a t_linger structure, with the following members:

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

The value of l_onoff is T_YES (on) or T_NO (off). l_onoff is an absolute requirement.

The value of l_linger determines the linger period in seconds. The transport user can request the default value by setting the to T_UNSPEC. The default timeout value depends on the underlying transport provider (it is often T_INFINITE). Legal values for this field are T_UNSPEC, T_INFINITE and all non-negative numbers. l_linger is not an absolute requirement. The implementation may place upper and lower limits on the l_linger option value. Requests that fall short of the lower limit are negotiated to the lower limit. Legal values are all positive numbers.

This option can be negotiated in any XTI/TLI transport endpoint state; however, the negotiated value is not effective until t_close(3) or close(2) is called. This option can be negotiated using the t_optmgmt(3), t_connect(3) or t_accept(3) XTI/TLI library calls.

There are notes in Linux 2.4 TCP code that say that if l_onoff is set to T_YES and l_linger is set to zero (0), that, per RFC 793[1], an abort will be sent. This might be a way to resolve the problem sending aborts.

XTI_RCVBUF

This option is used to adjust the internal buffer size allocated for the receive buffer. The buffer size may be increased for high-volume connections, or decreased to limit the possible backlog of incoming data.

This option is formatted as a t_uscalar_t. This request is not an absolute requirement. The implementation may place upper and lower limits on the option value. Requests that fall short of the lower limit are negotiated to the lower limit. Legal values are all positive numbers.

This option can be negotiated in any XTI/TLI state; however, the negotiated value will not be effective until the T_DATAXFER state is acheived. This option can be negotiated using the t_optmgmt(3), t_connect(3) or t_accept(3) XTI/TLI library calls.

XTI_RCVLOWAT

This option is used to set a low-water mark in the receive buffer. The option value gives the minimal number of bytes that must have accumulated in the receive buffer before they become visible to the transport user. If and when the amount of accumulated receive data exceeds the low-water mark, a T_DATA event is created, an event mechansm (for example, poll(2) or select(2)) indicates the data, and the data can be read by t_rcv(3) or t_rcvudata(3).

XTI_SNDBUF

This option is used to adjust the internal buffer size allocated for the send buffer.

XTI_SNDLOWAT

This option is used to set a low-water mark in the send buffer. The option value gives the minimal number of bytes that must have accumulated in the send buffer before they are sent.

FUNCTIONS

Local Transport Endpoint Management

Local Endpoint Management
functions are applicable to all transport service provider service types and include functions to open and close a file descriptor associated, bind and unbind a file descriptor from a local transport endpoint, manage options and get information about the state, bound and connecting addresses, protocol parameter limits of a local transport endpoint.

t_open(3) - open an endpoint
t_close(3) - close an endpoint
t_bind(3) - bind to an address
t_unbind(3) - unbind from an address
t_optmgmt(3) - manage options
t_getinfo(3) - return protocol information
t_getprotaddr(3) - get protocol addresses
t_getstate(3) - return the current state
Local Event Management
functions are responsible for handling asynchronous events of the underlying transport service provider and resynchronizing the XTI/TLI library with the underlying transport service provider.

t_sync(3) - synchronize library with provider
t_look(3) - look at the current event

Connection Oriented Endpoints

A set of XTI/TLI Library calls are provided for performing protocol functions on local transport endpoints for which the transport service provider is of a connection oriented service type. Connection oriented services have three phases as follows:

Connection Establishement Phase
consists of either invoking outgoing connections or listening for and accepting incoming connections. Valid states for this phase are: T_IDLE, T_INCON, and T_OUTCON. XTI/TLI Library calls used in the Connection Establishment Phare are as follows:

t_listen(3) - get a connection request
t_accept(3) - accept a connection request
t_connect(3) - establish a connection
t_rcvconnect(3) - receive connect request confirmation
t_addleaf(3) - add a point to a point to multipoint connection
t_removeleaf(3) - remove point from point to multipoint connection
t_rcvleafchange(3) - receive point added to point to multipoint connection
Data Transfer Phase
consist of transfering data between connected transport endpoints. Valid states for this phase are: T_DATAXFER, T_OUTREL (for incoming data) and T_INREL (for outgoing data). XTI/TLI Library calls used in the Data Transfer Phare are as follows:

t_snd(3) - send data
t_sndv(3) - gather and send data
t_rcv(3) - receive data
t_rcvv(3) - receive data and scatter
Connection Release Phase
consists of either abortive or orderly release of the transport connection, with or without user data. Valid states for this phase are: T_DATAXFER, T_OUTREL, and T_INREL. XTI/TLI Library calls used in the Connection Release Phare are as follows:

t_rcvdis(3) - receive abortive disconnect
t_snddis(3) - send abortive disconnect request
t_rcvrel(3) - acknowledge orderly release request
t_sndrel(3) - send orderly release request
t_rcvreldata(3) - acknowledge orderly release request with data
t_sndreldata(3) - send orderly release request with data

Connectionless Endpoints

A set of XTI/TLI Library calls are provided for performing protocol functions on local transport endpoints for which the transport service provider is of a connectionless service type. Connectionless service has one phase as follows:

Data Transfer Phase
consists of transferring data between disconnected transport endpoints. Valid states for this phase are: T_IDLE. XTI/TLI Library calls used in the Data Transfer Phase are as follows:

t_rcvudata(3) - receive unitdata
t_rcvvudata(3) - receive unitdata and scatter
t_sndudata(3) - send unitdata
t_sndvudata(3) - gather and send unitdata

XTI/TLI Library functions

A set of XTI/TLI Library calls are provided for error handling and utility. These functions do not operate directly on a transport endpoint.

Error Handling
consists of the global external variable t_errno which holds all XTI/TLI Library call error numbers in a similar fashion to errno(3). The following Error Handling functions are provided:

t_errno(3) - error number
t_error(3) - print an error message
t_strerror(3) - describe an XTI/TLI library error
Utility Functions
provide for the allocation and deallocation of XTI/TLI library datastructures, and equiry concerning XTI/TLI system confiruation parameters. The following Utility Functions are provided:

t_alloc(3) - allocate a library structure
t_free(3) - free a library structure
t_sysconf(3) - configure XTI/TLI system parameters

RETURN VALUES

Upon success, most XTI/TLI library functions return zero (0) or a positive integer reflecting a returned parameter value. Upon failure, XTI/TLI library functions return -1 and set t_errno(3) to an applicable error number.

ERRORS

The errors that can be returned by XTI/TLI Library calls are detailed in t_errno(3).

BUGS

The XTI/TLI library has been tested with the test-xnet(8) and test-xnet_thr(8) conformance test suites.

The XTI/TLI library has no known bugs.

COMPATIBILITY

The XTI/TLI library functions are compatible with SVR 4.2[2], XNS 5.2[3], SUSv2[4].

Compatibility is tested using the test-xnet(8) and test-xnet_thr(8) test case executables and the The OpenSS7 Project autotest test suite.

CONFORMANCE

The Open Group XNS Issue 5.2[3], Single UNIX® Specification Version 2[4].

Conformance is tested using the test-xnet(8) and test-xnet_thr(8) test case executables and the The OpenSS7 Project autotest test suite.

HISTORY

The XTI/TLI interface first appeared in SVR4.2[2].

VERSIONS

This manpage was written for the OpenSS7 XTI/TLI Library.

REFERENCES

[1]: RFC 793/STD 7, Transmission Control Protocol, DARPA Internet Program, Protocol Specification, September 1981, J. Postel, ed., The Internet Society. (Also STD0007) (Updated by RFC 3168) (Status: STANDARD) <http://www.ietf.org/rfc/rfc0793.txt>
[2]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: 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/>
[4]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>