Networking Services Library Functions tgetinfo(3NSL)
NAME
tgetinfo - get protocol-specific service information
SYNOPSIS
#include
int tgetinfo(int fd, struct tinfo *info);
DESCRIPTION
This routine is part of the XTI interfaces which evolved
from the TLI interfaces. XTI represents the future evolution
of these interfaces. However, TLI interfaces are supported
for compatibility. When using a TLI routine that has the
same name as an XTI routine, the tiuser.h header file must
be used. Refer to the TLI COMPATIBILITY section for a
description of differences between the two interfaces.
This function returns the current characteristics of the
underlying transport protocol and/or transport connection
associated with file descriptor fd. The info pointer is used
to return the same information returned by topen(3NSL),
although not necessarily precisely the same values. This
function enables a transport user to access this information
during any phase of communication.
This argument points to a tinfo structure which contains
the following members:
tscalart addr; /*max size in octets of the transport protocol address*/
tscalart options; /*max number of bytes of protocol-specific options */
tscalart tsdu; /*max size in octets of a transport service data unit */
tscalart etsdu; /*max size in octets of an expedited transport service*/
/*data unit (ETSDU) */
tscalart connect; /*max number of octets allowed on connection */
/*establishment functions */
tscalart discon; /*max number of octets of data allowed on tsnddis() */
/*and trcvdis() functions */
tscalart servtype; /*service type supported by the transport provider */
tscalart flags; /*other info about the transport provider */
The values of the fields have the following meanings:
addr A value greater than zero indicates the maximum
size of a transport protocol address and a value
of TINVALID (-2) specifies that the transport
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions tgetinfo(3NSL)
provider does not provide user access to tran-
sport protocol addresses.
options A value greater than zero indicates the maximum
number of bytes of protocol-specific options
supported by the provider, and a value of
TINVALID (-2) specifies that the transport pro-
vider does not support user-settable options.
tsdu A value greater than zero specifies the maximum
size in octets of a transport service data unit
(TSDU); a value of TNUL (zero) specifies that
the transport provider does not support the con-
cept of TSDU, although it does support the send-
ing of a datastream with no logical boundaries
preserved across a connection; a value of
TINFINITE (-1) specifies that there is no limit
on the size in octets of a TSDU; and a value of
TINVALID (-2) specifies that the transfer of
normal data is not supported by the transport
provider.
etsdu A value greater than zero specifies the maximum
size in octets of an expedited transport service
data unit (ETSDU); a value of TNUL (zero)
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 TINFINITE (-1) speci-
fies that there is no limit on the size (in
octets) of an ETSDU; and a value of TINVALID
(-2) specifies that the transfer of expedited
data is not supported by the transport provider.
Note that the semantics of expedited data may be
quite different for different transport provid-
ers.
connect A value greater than zero specifies the maximum
number of octets that may be associated with
connection establishment functions and a value
of TINVALID (-2) specifies that the transport
provider does not allow data to be sent with
connection establishment functions.
discon If the TORDRELDATA bit in flags is clear, a
value greater than zero specifies the maximum
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions tgetinfo(3NSL)
number of octets that may be associated with the
tsnddis(3NSL) and trcvdis(3NSL) functions, and
a value of TINVALID (-2) specifies that the
transport provider does not allow data to be
sent with the abortive release functions. If the
TORDRELDATA bit is set in flags, a value
greater than zero specifies the maximum number
of octets that may be associated with the
tsndreldata(), trcvreldata(), tsnddis(3NSL)
and trcvdis(3NSL) functions.
servtype This field specifies the service type supported
by the transport provider, as described below.
flags This is a bit field used to specify other infor-
mation about the communications provider. If
the TORDRELDATA bit is set, the communications
provider supports sending user data with an ord-
erly release. If the TSENDZERO bit is set in
flags, this indicates that the underlying tran-
sport provider supports the sending of zero-
length TSDUs.
If a transport user is concerned with protocol independence,
the above sizes may be accessed to determine how large the
buffers must be to hold each piece of information. Alterna-
tively, the talloc(3NSL) function may be used to allocate
these buffers. An error will result if a transport user
exceeds the allowed data size on any function. The value of
each field may change as a result of protocol option nego-
tiation during connection establishment (the toptmgmt(3NSL)
call has no effect on the values returned by tgetinfo()).
These values will only change from the values presented to
topen(3NSL) after the endpoint enters the TDATAXFER
state.
The servtype field of info specifies one of the following
values on return:
TCOTS The transport provider supports a
connection-mode service but does not support
the optional orderly release facility.
TCOTSORD The transport provider supports a
connection-mode service with the optional
orderly release facility.
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions tgetinfo(3NSL)
TCLTS The transport provider supports a
connectionless-mode service. For this service
type, topen(3NSL) will return TINVALID (-
1) for etsdu, connect and discon.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Oth-
erwise, a value of -1 is returned and terrno is set to
indicate an error.
VALID STATES
AL - apart from TUNINIT.
ERORS
On failure, terrno is set to one of the following:
TBADF The specified file descriptor does not refer to a
transport endpoint.
TPROTO This error indicates that a communication problem
has been detected between XTI and the transport
provider for which there is no other suitable XTI
error (terrno).
TSYSER A system error has occurred during execution of
this function.
TLI COMPATIBILITY
The XTI and TLI interface definitions have common names but
use different header files. This, and other semantic differ-
ences between the two interfaces are described in the sub-
sections below.
Interface Header
The XTI interfaces use the header file, xti.h. TLI inter-
faces should not use this header. They should use the
header:
#include
Error Description Values
The terrno value TPROTO can be set by the XTI interface but
not by the TLI interface.
The tinfo Structure
For TLI , the tinfo structure referenced by info lacks the
following structure member:
SunOS 5.11 Last change: 7 May 1998 4
Networking Services Library Functions tgetinfo(3NSL)
tscalart flags; /* other info about the transport provider */
This member was added to struct tinfo in the XTI inter-
faces.
When a value of -1 is observed as the return value in vari-
ous tinfo structure members, it signifies that the tran-
sport provider can handle an infinite length buffer for a
corresponding attribute, such as address data, option data,
TSDU (octet size), ETSDU (octet size), connection data, and
disconnection data. The corresponding structure members are
addr, options, tsdu, estdu, connect, and discon, respec-
tively.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
talloc(3NSL), topen(3NSL), toptmgmt(3NSL),
trcvdis(3NSL), tsnddis(3NSL), attributes(5)
SunOS 5.11 Last change: 7 May 1998 5
|
