 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
t_optmgmt(3)
NAME
t_optmgmt - Manage protocol options for a transport endpoint
SYNOPSIS
#include <xti.h>
int t_optmgmt(
int fd,
struct t_optmgmt *req,
struct t_optmgmt *ret );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
t_optmgmt(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
The following table summarizes the relevance of input and output parameters
before and after t_optmgmt() is called:
__________________________________________
Parameter Before Call After Call
__________________________________________
fd y n
req->opt.maxlen n n
req->opt.len y n
req->opt.buf y(y) n
req->options y n
ret->opt.maxlen y n
ret->opt.len n y
ret->opt.buf o (o)
ret->options n y
__________________________________________
Notes to Table:
y This a meaningful parameter.
(y) The content of the object pointed to by y is meaningful.
n This is not a meaningful parameter.
o This is an optional parameter.
(o) The content of the object pointed to by o is optional.
fd Specifies a file descriptor returned by t_open() function that
identifies the local transport endpoint.
req and ret
The argument req is used to request a specific action of the provider
and to send options to the provider. The argument ret is used by the
transport provider to return options and option values to the user.
Both arguments point to a type t_optmgmt structure. This structure is
used to reserve space for a transport-user options data buffer that
stores negotiable protocol options. The type t_optmgmt structure has
the following members:
struct netbuf opt
Specifies a buffer for protocol options associated with the
referenced transport endpoint. The type netbuf structure pointed to
by this member is defined in the xti.h include file. This
structure, which is used to define buffer parameters, has the
following members:
unsigned int maxlen
For the req argument, this has no meaning. For the ret
argument, it specifies the maximum byte length of the options
buffer.
unsigned int len
For the req argument, this specifies the number of bytes in the
options. For the ret argument, it specifies the number of bytes
of options returned.
char *buf
For the req argument, this points to the options buffer. For
the ret argument, it points to the buffer where the options are
placed.
Each option in the options buffer is of the form struct
t_opthdr, possibly followed by an option value. The t_opthdr
structure, which is defined in the xti.h file, has the
following members:
unsigned long len
Contains its total length (the length of the option header
t_opthdr plus the length of the option value).
unsigned long level
Identifies the XTI level or a protocol of the transport
provider.
unsigned long name
Identifies the option within the level.
unsigned long status
If t_optmgmt() is called with the action T_NEGOTIATE set,
the status field of the returned options contains
information about the success or failure of the
negotiation.
Each option in the input or output option buffer must start at
a longword boundary. The macro OPT_NEXTHDR(pbuf, buflen,
poption) can be used for that purpose. This macro is defined in
the xti.h file.
If the transport user specifies several options on input, all
the options must address the same level. If any option in the
options buffer does not indicate the same level as the first
option, or the level specified is unsupported, the t_optmgmt()
request will fail with the error [TBADOPT]. Some options may
have been successfully negotiated when this error is detected.
The transport user can check the current status by calling
t_optmgmt() with the T_CURRENT option set.
flags
A longword (least significant bit rightmost) that specifies the
response action that must be taken by a transport provider when the
t_optmgmt() function is processed. The symbolic names for
indicating various actions are defined in the xti.h include file.
The flags field of req must specify one of the symbolic names shown
in the following table.
_________________________________________________________
Symbolic Name Meaning
_________________________________________________________
T_NEGOTIATE
The transport user wants to negotiate the
values of the options stored in the
options buffer. In response, the
transport provider evaluates the options
and writes acceptable (negotiated) values
to the data buffer pointed to by
ret->opt.buf.
T_CHECK
The transport user wants to verify that
the options specified in the data buffer
pointed to by req->opt.buf are supported
by the transport provider. On return, the
transport provider writes a ret->flags
value, which is either T_SUCCESS or
T_FAILURE.
T_DEFAULT
The transport user wants to know what the
default options supported by the
transport provider are. The transport
provider writes default data into the
options data buffer pointed to by
ret->opt.buf. The req->opt.lenparameter
must be set to 0 (zero). The req->opt.buf
member may be set to its null value.
T_CURRENT
The transport user wants to retrieve the
currently effective option values, for
options specified in req->opt.buf. It is
sufficient to specify only the t_opthdr
part of an option. The currently
effective values are then returned in
ret->opt.buf.
_________________________________________________________
The option T_ALLOPT can only be used with t_optmgmt() and the
actions T_NEGOTIATE, T_DEFAULT, and T_CURRENT. It can be used with
any supported level, and it addresses all supported options of this
level. The option has no value; it consists only of a t_opthdr.
In a t_optmgmt() call, only options of one level may be addressed,
so this option should not be requested together with other options.
The function returns as soon as this option has been processed.
Options are processed independently in the order they appear in the
input option buffer. If an option is input multiple times, it may
be output multiple times or only once, depending on the
implementation.
If the transport provider is not able to provide an interface that
can support the T_NEGOTIATE or T_CHECK functions, the error
[TNOTSUPPORT] is returned.
DESCRIPTION
The t_optmgmt() XTI function is used in connectionless and connection-
oriented transport service. The t_optmgmt() function associates specific
optional parameters with a bound transport endpoint previously defined by a
file descriptor returned by the t_open() function. The t_optmgmt()
function permits a transport user to retrieve, verify, or negotiate desired
options with a transport provider.
A type t_optmgmt structure defined in the xti.h include file is used to
specify options.
ERRORS
If the t_optmgmt() function fails, t_errno may be set to one of the
following values:
[TBADF]
File descriptor fd does not refer to a valid transport endpoint.
[TOUTSTATE]
This function was called in the wrong sequence.
[TBADOPT]
The specified protocol options are either of an incorrect format or
contain illegal information.
[TBADFLAG]
The specified option is invalid.
[TACCES]
The transport user does not have permission to negotiate the specified
options.
[TBUFOVFLW]
The number of bytes allowed for an incoming argument is not sufficient
to store the value of that argument. The information intended for the
data buffer pointed to by the ret parameter is discarded.
[TSYSERR]
A system error occurred during execution of the t_optmgmt() function.
[TNOTSUPPORT]
This function is not supported by the underlying transport provider.
[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 (t_errno).
XTI-LEVEL OPTIONS
XTI-level options are not specific for a particular transport provider.
This operating system's XTI implementation supports all of the options
defined in this section.
The options described in this section are association-related. They may be
negotiated in all XTI states except T_UNINIT.
The protocol level is XTI_GENERIC. The options defined for this level are
listed in the following table.
______________________________________________________________________
Option Name Meaning
Type of Option
Value
Legal Option
Value
______________________________________________________________________
XTI_DEBUG See text
array of unsigned
longs
enable
debugging
XTI_LINGER struct linger See text
linger on close
if data is
present
XTI_RCVBUF unsigned long size in octets
receive buffer
size
XTI_RCVLOWAT unsigned long size in octets
receive low-
water mark
XTI_SNDBUF unsigned long size in octets
send buffer
size
XTI_SNDLOWAT unsigned long size in octets
send low-water
mark
______________________________________________________________________
A request for XTI_DEBUG is an absolute requirement. A request to activate
XTI_LINGER is also an absolute requirement; the timeout value for this
option is not. XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF, and XTI_SNDLOWAT are
not absolute requirements.
XTI_DEBUG
This option controls debugging. Debugging is disabled if the option is
specified with "no value", that is, with only an option header. Tru64
UNIX accepts a single value for this option. A non-zero value enables
socket level debugging and a zero value disables it.
The actual effects of the debugging depend upon the underlying
transport provider. For example, you can set the XTI_DEBUG option for
any transport endpoint in the TCP/IP family. However, TCP is the only
protocol that looks at the option. trpt can be used to report the
trace records for TCP. Other transport providers may supply utilities
to process the traces. The system supplies utilities to process the
traces.
XTI_LINGER
Lingers the execution of a t_close() or close() if send data is still
queued in the send buffer. The option value specifies the linger
period. If a close() or a t_close() 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 transport, t_close() or close() either block for, at
maximum, the linger period, or immediately return, whereupon the system
holds the connection in existence for, at most, the linger period.
The option value consists of a structure t_linger, which is declared as
shown here:
struct
t_linger {
long l_onoff; /* switch option on/off */
long l_linger; /* linger period in seconds */
}
The value for l_onoff is an absolute requirement. The legal values for
this field are as follows:
T_NO switch option off
T_YES activate option
The field l_linger determines the linger period in seconds. The
transport user can request the default value by setting the field to
T_UNSPEC. The default timeout value depends on the underlying transport
provider; the value is often T_INFINITE. Legal values for this field
are as follows: T_UNSPEC, T_INFINITE, and all non-negative numbers.
The l_linger value is not an absolute requirement. The implementation
may place upper and lower limits on this value. Requests that fall
short of the lower limit are negotiated to the lower limit.
Note that this option does not linger the execution of t_snddis().
XTI_RCVBUF
Adjusts 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 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.
XTI_RCVLOWAT
Sets 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 mechanism, for example poll() or
select(), indicates the data, and the data can be read by t_rcv() or
t_rcvdata().
Legal values for this field are all positive numbers.
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.
XTI_SNDBUF
Adjusts the internal buffer size allocated for the send buffer.
Legal values for this field are all positive numbers.
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.
XTI_SNDLOWWAT
Sets 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.
Legal values for this field are all positive numbers.
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.
VALID STATES
The t_optmgmt() function can be called in all the transport provider
states, except T_UNINIT.
RETURN VALUE
Upon successful completion, a value of 0 (zero) is returned. Otherwise, a
value of -1 is returned and t_errno is set to indicate the error.
SEE ALSO
Functions: t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3),
t_listen(3), t_open(3), t_rcvconnect(3)
Standards: standards(5)
Network Programmer's Guide
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|