t_open(3xti)

t_open -- establish a transport endpoint

Synopsis

cc [options] file -lnsl

#include <xti.h>

#include <fcntl.h>

int t_open(const char *path, int oflag, struct t_info info)

Description

The t_open function is a TLI/XTI local management routine that must be called as the first step in the initialization of a transport endpoint. This function opens a UNIX^® file that identifies a transport endpoint connected to a chosen transport provider (that is, transport protocol). The file descriptor (fd) for the opened file identifies the provider and establishes the endpoint. For example, a call to t_open may be used to open the file /dev/iso_cots to specify an OSI connection-oriented transport layer protocol as the transport provider.

The file descriptor returned by t_open is used by all subsequent functions to identify the particular transport endpoint.

t_open also returns various default characteristics of the underlying transport protocol by setting fields in the t_info structure.

Parameters

path: points to the path name of the file to open.
oflag: identifies any open (as in open(2)) flags. oflag may be constructed from O_NONBLOCK OR-ed with O_RDWR. These flags are defined in the header file <fcntl.h>.
info: points to the t_info structure used to identify a transport provider.

State transitions

On entry, T_UNINIT; T_UNBND (successful) or T_UNINIT (failed) on exit.

Structure definitions

This argument points to a struct t_info which contains the following members:

long addr;     /* max size of the transport protocol address         */
long options;  /* max num of bytes of protocol-specific options      */
long tsdu;     /* max size of a transport service data unit (TSDU)   */
long etsdu;    /* max size of an expedited TSDU (ETSDU)              */
long connect;  /* max amt of data allowed on connect establishment   */
long discon;   /* max amt of data allowed on t_snddis, t_rcvdis      */
long servtype; /* service type supported by transport provider       */
long flags;    /* provides more info about transport provider        */

The values of the fields have the following meanings:

addr

A value greater than or equal to 0 indicates the maximum size of a transport protocol address, and a value of -2 specifies that the transport provider does not provide user access to transport protocol addresses.

options

A value greater than or equal to 0 indicates the maximum number of bytes of protocol-specific options supported by the provider, and a value of -2 specifies that the transport provider does not support user-settable options.

tsdu

A value greater than 0 specifies the maximum size of a transport service data unit (TSDU); a value of 0 specifies that the transport provider does not support the concept of TSDU, although it does support the sending of a data stream with no logical boundaries preserved across a connection; a value of -1 specifies that there is no limit to the size of TSDU; and a value of -2 specifies that the transfer of normal data is not supported by the transport provider.

etsdu

A value greater than 0 specifies the maximum size of an expedited transport service data unit (ETSDU); a value of 0 specifies that the transport provider does not support the concept of ETSDU, although it does support the sending of an expedited data stream with no logical boundaries preserved across a connection; a value of -1 specifies that there is no limit to the size of ETSDU; and a value of -2 specifies that the transfer of expedited data is not supported by the transport provider.

connect

A value greater than or equal to 0 specifies the maximum amount of data that may be associated with connection establishment functions, and a value of -2 specifies that the transport provider does not allow data to be sent with connection establishment functions.

discon

A value greater than or equal to 0 specifies the maximum amount of data that may be associated with the t_snddis and t_rcvdis functions, and a value of -2 specifies that the transport provider does not allow data to be sent with the abortive release functions.

servtype

This field specifies the service type supported by the transport provider. A single transport endpoint may support only one of the following services at one time.

T_COTS: The transport provider supports a connection-mode service but does not support the optional orderly release facility.
T_COTS_ORD: The transport provider supports a connection-mode service with the optional orderly release facility.
T_CLTS: The transport provider supports a connectionless service. For this service type, t_open will return -2 for etsdu, connect, and discon.

flags

This bit field is used to specify other information about the transport provider. If the T_SENDZERO bit is set in flags, this indicates the underlying transport provider supports the sending of zero-length TSDUs.

A single transport endpoint may support only one of the above services at one time.

If info is set to NULL by the transport user, no protocol information is returned by t_open.

Files

/usr/lib/libxti.so: X/Open^® Transport Interface Library (shared object)
/usr/lib/libnsl.so: Network Services Library (shared object)

Examine your system's /etc/netconfig file for device files associated with a transport protocol provider.

Usage

If a transport user is concerned with protocol independence, the sizes specified in t_info may be accessed to determine how large the buffers must be to hold each piece of information. Alternatively, the t_alloc function may be used to allocate these buffers. An error will result if a transport user exceeds the allowed data size on any function.

If info is set to NULL by the transport user, no protocol information is returned by t_open.

Return values

t_open returns a valid file descriptor on success and -1 on failure and t_errno is set to indicate the error.

Errors

On failure, t_errno may be set to the following:

TSYSERR: A system error has occurred during execution of this function.
TBADFLAG: An invalid flag is specified.
TBADNAME: An invalid path is specified for the transport provider name.
TPROTO: A communication problem has been detected with the transport provider and there is no other value of t_errno to describe the error condition.

Warnings

If t_open is used on a non-TLI/XTI-conforming STREAMS device, unpredictable events may occur.

The close(2) system call should not be used directly on the file descriptor returned by t_open(3xti). The t_close(3xti) routine should be used to close a file descriptor opened by t_open(3xti).

References

close(2), open(2), t_alloc(3xti), t_close(3xti), t_getinfo(3xti), netconfig(4bnu)