TIMOD

Section: OpenSS7 XTI/TLI Networking Devices (4)
Updated: 2008-10-31
Index Return to Main Contents

NAME

timod - a STREAMS XTI/TLI compatability interface

SYNOPSIS

#include <sys/stropts.h>
#include <sys/tihdr.h>
#include <sys/timod.h>

t = open(/dev/tcp,0);
ioctl(t, I_PUSH, ``timod'');
ioctl(t, I_STR, &ic);

DESCRIPTION

timod
is a XTI/TLI library compatability module for the STREAMS Transport Provider Interface tpi(7). It translates a set of timod ioctl(2) commands into TLI primitives. These timod ioctl(2) commands are intended to be used by the XTI/TLI library.

The purpose of the timod module is provide thread-safe atomic operations in support fot he XTI/TLI library. timod does not alter any messages passed with putmsg(2) or putpmsg(2s), or received with getmsg(2) or getpmsg(2s). timod simply intercepts responses to its own primitives sent downstream as a result of an ioctl(2) command.

Unlike the sockmod(4) module, timod makes no adjustments to the stream head for read(2) options (see I_SRDOPT under streamio(7)).

IOCTLS

The following subsections detail the ioctl(2) commands that are made available by pushing the timod module. For additional information on the T_primitive structures, see tpi(7).

timod only supports the I_STR version of the IO controls and does not support transparent IO controls. For more information, see the I_STR subsection of streamio(7).

TI_GETINFO (('T' << 8) + 140)

arg is a pointer to a strioctl structure passing in a T_info_req structure, formatted as follows:

struct T_info_req {
    t_scalar_t PRIM_type;       /* always T_INFO_REQ */
};

and returning a T_info_ack structure, formatted as follows:

struct T_info_ack {
    t_scalar_t PRIM_type;       /* always T_INFO_ACK */
    t_scalar_t TSDU_size;       /* max TSDU size */
    t_scalar_t ETSDU_size;      /* max ETSDU size */
    t_scalar_t CDATA_size;      /* Connect data size */
    t_scalar_t DDATA_size;      /* Discon data size */
    t_scalar_t ADDR_size;       /* TSAP size */
    t_scalar_t OPT_size;        /* options size */
    t_scalar_t TIDU_size;       /* TIDU size */
    t_scalar_t SERV_type;       /* service type */
    t_scalar_t CURRENT_state;   /* current state */
    t_scalar_t PROVIDER_flag;   /* provider flags */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_info_ack structure.

TI_OPTMGMT (('T' << 8) + 141)

arg is a pointer to a buffer passing in a T_optmgmt_req structure, formatted as follows:

struct T_optmgmt_req {
    t_scalar_t PRIM_type;       /* always T_OPTMGMT_REQ */
    t_scalar_t OPT_length;      /* options length */
    t_scalar_t OPT_offset;      /* options offset */
    t_scalar_t MGMT_flags;      /* flags */
};

and returning a T_optmgmt_ack structure, formatted as follows:

struct T_optmgmt_ack {
    t_scalar_t PRIM_type;       /* always T_OPTMGMT_ACK */
    t_scalar_t OPT_length;      /* options length */
    t_scalar_t OPT_offset;      /* options offset */
    t_scalar_t MGMT_flags;      /* flags */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_optmgmt_ack structure.

TI_BIND (('T' << 8) + 142)

arg is a pointer to a buffer passing in a T_bind_req structure, formatted as follows:

struct T_bind_req {
    t_scalar_t PRIM_type;       /* always T_BIND_REQ */
    t_scalar_t ADDR_length;     /* length of address */
    t_scalar_t ADDR_offset;     /* offset of address */
    t_uscalar_t CONIND_number;  /* requested number of connect
                                   indications to be queued */
};

and returning a T_bind_ack structure, formatted as follows:

struct T_bind_ack {
    t_scalar_t PRIM_type;       /* always T_BIND_ACK */
    t_scalar_t ADDR_length;     /* length of address */
    t_scalar_t ADDR_offset;     /* offset of address */
    t_uscalar_t CONIND_number;  /* connect indications to be queued */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_bind_ack structure.

TI_UNBIND (('T' << 8) + 143)

arg is a pointer to a buffer passing in a T_unbind_req structure, formatted as follows:

struct T_unbind_req {
    t_scalar_t PRIM_type;       /* always T_UNBIND_REQ */
};

and returning a T_ok_ack structure, formatted as follows:

struct T_ok_ack {
    t_scalar_t PRIM_type;       /* always T_OK_ACK */
    t_scalar_t CORRECT_prim;    /* primitive */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_ok_ack structure.

TI_GETMYNAME (('T' << 8) + 144)

arg is a pointer to a buffer passing in a T_addr_req structure, formatted as follows:

struct T_addr_req {
    t_scalar_t PRIM_type;       /* always T_ADDR_REQ */
};

and returning a T_addr_ack structure, formatted as follows:

struct T_addr_ack {
    t_scalar_t PRIM_type;       /* always T_ADDR_ACK */
    t_scalar_t LOCADDR_length;  /* length of local address */
    t_scalar_t LOCADDR_offset;  /* offset of local address */
    t_scalar_t REMADDR_length;  /* length of remote address */
    t_scalar_t REMADDR_offset;  /* offset of remote address */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_addr_ack structure.

TI_GETPEERNAME (('T' << 8) + 145)

arg is a pointer to a buffer passing in a T_addr_req structure, formatted as follows:

struct T_addr_req {
    t_scalar_t PRIM_type;       /* always T_ADDR_REQ */
};

and returning a T_addr_ack structure, formatted as follows:

struct T_addr_ack {
    t_scalar_t PRIM_type;       /* always T_ADDR_ACK */
    t_scalar_t LOCADDR_length;  /* length of local address */
    t_scalar_t LOCADDR_offset;  /* offset of local address */
    t_scalar_t REMADDR_length;  /* length of remote address */
    t_scalar_t REMADDR_offset;  /* offset of remote address */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_addr_ack structure.

TI_SETMYNAME (('T' << 8) + 146)

arg is a pointer to a buffer passing in a T_conn_res structure, formatted as follows:

struct T_conn_res {
    t_scalar_t PRIM_type;       /* always T_CONN_RES */
    t_scalar_t ACCEPTOR_id;     /* reponse queue ptr */
    t_scalar_t OPT_length;      /* options length */
    t_scalar_t OPT_offset;      /* options offset */
    t_scalar_t SEQ_number;      /* sequence number */
};

following by any connection response data.

and returning a T_ok_ack structure, formatted as follows:

struct T_ok_ack {
    t_scalar_t PRIM_type;       /* always T_OK_ACK */
    t_scalar_t CORRECT_prim;    /* primitive */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_ok_ack structure.

TI_SETPEERNAME (('T' << 8) + 147)

arg is a pointer to a buffer passing in a T_conn_req structure, formatted as follows:

struct T_conn_req {
    t_scalar_t PRIM_type;       /* always T_CONN_REQ */
    t_scalar_t DEST_length;     /* dest addr length */
    t_scalar_t DEST_offset;     /* dest addr offset */
    t_scalar_t OPT_length;      /* options length */
    t_scalar_t OPT_offset;      /* options offset */
};

followed by any connection request data.

and returning a T_ok_ack structure, formatted as follows:

struct T_ok_ack {
    t_scalar_t PRIM_type;       /* always T_OK_ACK */
    t_scalar_t CORRECT_prim;    /* primitive */
};

or an error return value. See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_ok_ack structure.

TI_SYNC (('T' << 8) + 148)

arg is a pointer to a buffer passing in a ti_sync_req structure, formatted as follows:

struct ti_sync_req {
    u_int32_t tsr_flags;
};

and returning a ti_sync_ack structure, formatted as follows:

struct ti_sync_ack {
    t_scalar_t PRIM_type;
    t_scalar_t TSDU_size;
    t_scalar_t ETSDU_size;
    t_scalar_t CDATA_size;
    t_scalar_t DDATA_size;
    t_scalar_t ADDR_size;
    t_scalar_t OPT_size;
    t_scalar_t TIDU_size;
    t_scalar_t SERV_type;
    t_scalar_t CURRENT_state;
    t_scalar_t PROVIDER_flag;
    t_uscalar_t tsa_qlen;
    u_int32_t tsa_flags;
};

or an error return value. See ``RETURN VALUES,'' below.

Field tsr_flags can contain zero or more of the following flags bitwise OR'ed together:

TSRF_INFO_REQ: Requests that the response contain a completed information request.
TSRF_IS_EXP_IN_RCVBUF: Requests that the response contain a flag indicating whether there is expedited data in the receive buffer.
TSRF_QLEN_REQ: Requests that the response contain the queue length of the transport service provider. Note that this information is not contained in a T_capability_ack but is necessary when a file descriptor is being synced on an open transport endpoint.

Field tsa_flags can contain zero or more of the following flags bitwise OR'ed together:

TSAF_EXP_QUEUED: Indicates that there is expedited data queued in the transport endpoint receive buffer.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned ti_sync_ack structure.

TI_GETADDRS (('T' << 8) + 149)

arg is a pointer to a buffer passing in a T_addr_req structure, formatted as follows:

struct T_addr_req {
    t_scalar_t PRIM_type;       /* always T_ADDR_REQ */
};

and returning a T_addr_ack structure, formatted as follows:

struct T_addr_ack {
    t_scalar_t PRIM_type;       /* always T_ADDR_ACK */
    t_scalar_t LOCADDR_length;  /* length of local address */
    t_scalar_t LOCADDR_offset;  /* offset of local address */
    t_scalar_t REMADDR_length;  /* length of remote address */
    t_scalar_t REMADDR_offset;  /* offset of remote address */
};

or an error return value, See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_addr_ack structure.

TI_CAPABILITY (('T' << 8) + 150)

arg is a pointer to a buffer passing in a T_capability_req structure, formatted as follows:

struct T_capability_req {
    t_scalar_t PRIM_type;       /* T_CAPABILITY_REQ */
    t_uscalar_t CAP_bits1;      /* capability bits 1 */
};

and returning a T_capability_ack structure, formatted as follows:

struct T_capability_ack {
    t_scalar_t PRIM_type;       /* T_CAPABILITY_ACK */
    t_uscalar_t CAP_bits1;      /* capability bits #1 */
    struct T_info_ack INFO_ack; /* info acknowledgement */
    t_uscalar_t ACCEPTOR_id;    /* accepting endpoint id */
};

or an error return value, See ``RETURN VALUES,'' below.

The buffer passed in the strioctl structure (ic_dp) must be of sufficient size (ic_len) to hold the returned T_capability_ack structure.

RETURN VALUES

When timod ioctls succeed, they return zero and the returned TLI message in the area pointed to by the ic_dp member of the strioctl structure pointed to by arg. When timod ioctls fail due to a T_ERROR_ACK being returned from the underlying TLI driver, timod returns a concatentation of the UNIX_error and the TLI_error as follows: ((p->UNIX_error << 8) + p->TLI_error). When the ioctl fails, timod returns -1 and sets errno(3) to an appropriate error number. See streamio(7) for a list of error numbers returned by the I_STR command.

ERRORS

When timod ioctl calls fail, timod returns -1 and sets the errno(3) to an appropriate error number. See streamio(7) for a list of error numbers returned by the I_STR command.

MODULES

``timod'' STREAMS module.

BUGS

timod has been tested with the test-timod(8) conformance test suite.

timod has no known bugs.

COMPATIBILITY

This Linux Fast-STREAMS[1] implementation of timod was backported to LiS[2] to repair deficiencies in the previous LiS implementation.

timod is compatible with XNS 5.2[3] and SVR 4.2[4], and descriptions for UnixWare7®[5], AIX®[6], DigitalUNIX®[7], HP-UX®[8], Solaris®[9], SUPER-UX®[10], with the following portability considerations:

---: Most other implementations only document the TI_GETINFO, TI_OPTMGMT, TI_BIND and T_UNBIND IO controls. timod is consistent with this documentation.
---: Most other implementations do not document TI_GETMYNAME, TI_GETPEERNAME, TI_SETMYNAME and TI_SETPEERNAME IO controls. Some of these are archaic and deprecated. timod provides the non-portable mechanisms described here. Portable application programs should not use these IO controls directly. timod uses special versions of these IO controls to ease work involved in the XTI/TLI library and to increase efficiency of that library.
---: TI_SYNC, TI_GETADDR and TI_CAPABILITY IO controls are consistent with internal documentation of other implementations. timod uses these IO controls to ease work involved in the XTI/TLI library and to increase efficiency of that library. timod provides the non-portable mechanisms described here. Portable application programs should not use these IO controls directly.

Compatibility is tested using the test-timod(8) test case executable and the OpenSS7 XTI/TLI Networking autotest test suite.

CONFORMANCE

SVID[11], XID[12], XNS 5.2[3], SUSv2[13], SUSv3/POSIX[14],

Conformance is tested using the test-timod(8) test case executable and the OpenSS7 XTI/TLI Networking autotest test suite.

HISTORY

timod first appeared in SVR 3[15]

REFERENCES

[1]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[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]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[5]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[6]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[7]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[8]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[9]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[10]: SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[11]: SVID, System V, Interface Definition, Fourth Edition.
[12]: XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[13]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[14]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[15]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.