t_optmgmt(3) t_optmgmt(3)
NAME [Toc] [Back]
t_optmgmt() - manage options for a transport endpoint
SYNOPSIS [Toc] [Back]
#include <xti.h> /* for X/OPEN Transport Interface - XTI */
/* or */
#include <tiuser.h> /* for Transport Layer Interface - TLI */
int t_optmgmt (fd, req, ret);
int fd;
struct t_optmgmt *req;
struct t_optmgmt *ret;
DESCRIPTION [Toc] [Back]
The t_optmgmt() function enables a transport user to retrieve, verify
or negotiate protocol options with the transport provider. The
argument fd identifies a bound transport endpoint.
The req and ret arguments point to a t_optmgmt structure containing
the following members:
struct netbuf opt;
t_scalar_t flags;
The opt field identifies protocol options. The flags field is used to
specify the action to take with those options.
The options are represented by a netbuf structure in a manner similar
to the address in t_bind(). The argument req is used to request a
specific action of the provider and to send options to the provider.
The argument len specifies the number of bytes in the options. buf
points to the options buffer. maxlen has no meaning for the req
argument. For XTI over the OSI transport provider, the options buffer
should be of struct isoco_options for connection-oriented service, or
struct isocl_options for connectionless service. For TLI, see the
documentation of the transport provider being used.
The transport provider may return options and flag values to the user
through ret. For ret, maxlen specifies the maximum size of the
options buffer, and buf points to the buffer where the options are to
be placed. For XTI over the OSI transport provider, the options
buffer should be of struct isoco_options for connection-oriented
service, or struct isocl_options for connectionless service. For TLI,
see the documentation of the transport provider being used. On
return, len specifies the number of bytes of options returned. The
value in maxlen has no meaning for the req argument, but must be set
in the ret argument to specify the maximum number of bytes the options
buffer can hold. The actual content of the options is imposed by the
transport provider.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
Each option in the options buffer is of the form struct t_opthdr
possibly followed by an option value.
The level field of struct t_opthdr identifies the XTI level or a
protocol of the transport provider. The name field identifies the
option within the level. len contains its total length; i.e. the
length of the option header t_opthdr plus the length of the option
value. 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 a negotiation.
Each option in the input or output option buffer must start at a
t_uscalar_t boundary. The macro OPT_NEXTHDR(pbuf, buflen, option) can
be used for that purpose. The parameter pbuf denotes a pointer to an
option buffer opt.buf, and buflen is its length. The parameter option
points to a current option in the option buffer. OPT_NEXTHDR returns
a pointer to the position of the next option or returns a null pointer
if the option buffer is exhausted. The macro is helpful for writing
and reading. See <xti.h> in the CAE Specification X/Open Transport
Interface (XTI) manual from X/Open Company Limited for the exact
definition.
If the transport user specifies several options on input, all 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, then the
t_optmgmt() request will fail with [TBADOPT]. If the error is
detected, some options have possibly been successfully negotiated.
The transport user can check the current status by calling t_optmgmt()
with the T_CURRENT flag set.
The flags field of req must specify one of the following actions:
T_NEGOTIATE This action enables the transport user to
negotiate option values.
The user specifies the options of interest and
their values in the buffer specified by req-
>opt.buf and req->opt.len. The negotiated option
values are returned in the buffer pointed to by
ret->opt.buf. The status field of each returned
option is set to indicate the result of the
negotiation. The status is one of the following:
T_SUCCESS if the proposed value was
negotiated.
T_PARTSUCCESS if a degraded value was
negotiated.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
T_FAILURE if the negotiation failed
according to the negotiation
rules.
T_NOTSUPPORT if the transport provider
does not support this option
or illegally requests
negotiation of a privileged
option.
T_READONLY if modification of a readonly
option was requested.
If the status is T_SUCCESS, T_FAILURE,
T_NOTSUPPORT or T_READONLY, the returned option
value is the same as the one requested on input.
The overall result of the negotiation is returned
in ret->flags.
This field contains the worst single result,
whereby the rating is done according to the order
of T_NOTSUPPORT, T_READONLY, T_FAILURE,
T_PARTSUCCESS, T_SUCCESS. The value T_NOTSUPPORT
is the worst result and T_SUCCESS is the best.
For each level, the option T_ALLOPT can be
requested on input. No value is given with this
option; only the t_opthdr part is specified. This
input requests to negotiate all supported options
of this level to their default values. The result
is returned option by option in ret->opt.buf.
(Note that depending on the state of the transport
endpoint, not all requests to negotiate the
default may be successful.)
T_CHECK This action enables the user to verify whether the
options specified in req are supported by the
transport provider.
If an option is specified with no option value (it
consists only of a t_opthdr structure), the option
is returned with its status field set to T_SUCCESS
if it is supported, T_NOTSUPPORT if it is not or
needs additional user privileges, and T_READONLY
if it is read-only (in the current state). No
option value is returned.
If an option is specified with an option value,
the status field of the returned option has the
same value, as if the user had tried to negotiate
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
this value with T_NEGOTIATE. If the status is
T_SUCCESS, T_FAILURE, T_NOTSUPPORT, or T_READONLY,
the returned option value is the same as the one
requested on input.
The overall result of the option checks is
returned in ret->flags. This field contains the
worst single result of the option checks, whereby
the rating is the same as for T_NEGOTIATE.
Note that no negotiation takes place. All
currently effective option values remain
unchanged.
T_DEFAULT This action enables the transport user to retrieve
the default option values. The user specifies the
option of interest in req->opt.buf. The option
values are irrelevant and will be ignored; it is
sufficient to specify the t_opthdr part of an
option only. The default values are then returned
in ret->opt.buf.
The status field returned is one of the following:
T_NOTSUPPORT if the protocol level does
not support this option or
if the transport user
illegally requested a
privileged option.
T_READONLY if the option is read-only.
T_SUCCESS in all other cases.
The overall result of the request is returned in
ret->flags. This field contains the worst single
result, whereby the rating is the same as for
T_NEGOTIATE.
For each level, the option T_ALLOPT can be
requested on input. All supported options of this
level with their default values are then returned.
In this case, ret->opt.maxlen must be given at
least the value info->options (see t_getinfo(3),
t_open(3)) before the call.
T_CURRENT This action enables the transport user to retrieve
the currently effective option values. The user
specifies the options of interest in req->opt.buf.
The option values are irrelevant and will be
ignored; it is sufficient to specify the t_opthdr
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
part of an option only. The default values are
then returned in ret->opt.buf.
The status field returned is one of the following:
T_NOTSUPPORT if the protocol level does
not support this option or
if the transport user
illegally requested a
privileged option.
T_READONLY if the option is read-only.
T_SUCCESS in all other cases.
The overall result of the request is returned in
ret->flags. This field contains the worst single
result, whereby the rating is the same as for
T_NEGOTIATE.
For each level, the option T_ALLOPT can be
requested on input. All supported options of this
level with their currently effective values are
then returned.
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 addresses all supported
options of this level. The option has no value;
it consists of a t_opthdr only. Since in a
t_optmgmt() call only options of one level may be
addressed, this option should not be requested
together with other options. The function returns
as soon as this option has been processed.
Options are independently processed in the order
they appear in the input option buffer. If an
option is multiply input, it depends on the
implementation whether it is multiply output or
whether it is returned only once.
Transport providers may not be able to provide an
interface capable of supporting T_NEGOTIATE and/or
T_CHECK functionalities. When this is the case,
the error [T_NOTSUPPORT] is returned.
The function t_optmgmt() may block under various circumstances and
depending on the implementation. The function will block, for
instance, if the protocol addressed by the call resides on a separate
controller. It may also block due to flow control constraints, i.e.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
if data set previously across this transport endpoint has not yet been
fully processed. If the function is interrupted by a signal, the
option negotiations that have been done so far may remain valid. The
behavior of the function is not changed if O_NONBLOCK is set.
XTI-Level Options [Toc] [Back]
XTI level options are not specific for a particular transport
provider. An XTI implementation supports none, all or any subset of
the options defined below. An implementation may restrict the use of
any of these options by offering them only in the privileged or
read-only mode, or if fd relates to specific transport providers.
The subsequent options are not association-related. They may be
negotiated in all XTI states except T_UNINIT.
The protocol level is XTI_GENERIC. For this level, the following
options are defined. A request for XTI_DEBUG is an absolute
requirement. A request to activate XTI_LINGER is an absolute
requirement; the timeout value to this option is not. XTI_RCVBUF,
XTI_RECVLOWAT, XTI_SNDBUF, and XTI_SNDLOWAT are not absolute
requirements.
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", i.e. with an option header only.
The system supplies utilities to process the
traces. Note that an implementation may also
provide other means for debugging.
XTI_LINGER This option is used to linger 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 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 implementation, 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 constists of a structure t_linger
declared as:
struct t_linger{
t_uscalar_t l_onoff; /* switch option on/off */
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
t_uscalar_t l_linger; /* linger period in seconds */
}
Legal values for the l_onoff are:
T_NO switch option off
T_YES activate option
The value of l_onoff is an absolute requirement.
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 (it is often
T_INFINITE). Legal values for this field are
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 to 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 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. Default and maximum buffer sizes
are protocol-dependent; see individual protocol
manual entries, such as tc
.
Maximum buffer size is controlled by the ndd
variables tcp_recv_hiwater_max and
udp_recv_hiwater_max depending upon the underlying
protocol in use.
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.
XTI_RCVLOWAT This option is used to set a low-water mark in the
receive buffer. The option values gives the
minimal number of bytes that must have accumulated
in the receive buffer before they become visible
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
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 (e.g. poll() or select()) indicates the
data, and the data can be read by t_rcv() or
t_rcvudata().
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.
XTI_SNDBUF This option is used to adjust the internal buffer
size allocated for the send buffer. The default
maximum size of this buffer is controlled by the
ndd variable tcp_xmit_hiwater_max.
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.
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.
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.
Thread-Safeness [Toc] [Back]
The t_optmgmt() function is safe to be called by multithreaded
applications, and it is thread-safe for both POSIX Threads and DCE
User Threads. It has a cancellation point. It is neither asynccancel
safe nor async-signal safe. Finally, it is not fork-safe.
Valid States [Toc] [Back]
All - apart from T_UNINIT.
RETURN VALUE [Toc] [Back]
Upon successful completion, a value of 0 is returned. Otherwise, a
value of -1 is returned, and t_errno is set to indicate the error.
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
t_optmgmt(3) t_optmgmt(3)
TLI supports any transport provider which is compliant with TPI
(Transport Provider Interface). Users can access TLI versions of the
t_* routines by linking with /usr/lib/libnsl_s.a. For more
information on TLI, see the TLI section of STREAMS/UX for HP 9000
Reference Manual.
ERRORS [Toc] [Back]
On failure, t_errno is set to the following:
[TBADF] The specified identifier does not refer to a
transport endpoint.
[TOUTSTATE] The function was issued in the wrong sequence.
[TACCES] The user does not have the permission to negotiate
the specified options.
[TBADOPT] The specified protocol options were in an
incorrect format or contained illegal information.
[TBADFLAG] An invalid flag was specified.
[TBUFOVFLW] The number of bytes allowed for an incoming
argument (maxlen) is greater than 0 and not
sufficient to store the value of that argument.
The information to be returned in ret will be
discarded.
[TSYSERR] A system error has occurred during execution of
this function.
[TPROTO] (XTI only) This error indicates that a
communication problem has been detected between
XTI and the transport provider for which there is
no existing XTI t_errno.
[TNOTSUPPORT] (XTI only) This action is not supported by the
underlying transport provider.
SEE ALSO [Toc] [Back]
t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3),
t_open(3), t_rcvconnect(3).
STANDARDS CONFORMANCE [Toc] [Back]
t_optmgmt(): SVID2, XPG3, XPG4
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003 [ Back ] |