Index of Section 3 Manual Pages
| Interix / SUA | t_optmgmt.3 | Interix / SUA |
t_optmgmt(3) t_optmgmt(3)
t_optmgmt()
NAME
t_optmgmt - manage options for a transport endpoint
SYNOPSIS
#include
int t_optmgmt(
int fd,
const struct t_optmgmt *req,
struct t_optmgmt *ret)
DESCRIPTION
The t_optmgmt() function enables a transport user to retrieve, verify or
negotiate protocol options with the transport provider.
Parameters Before call After call
fd x /
req->opt.maxlen = =
req->opt.len x =
req->opt.buf x (x) =
req->flags x =
ret->opt.maxlen x =
ret->opt.len / x
ret->opt.buf ? (?)
ret->flags / x
The argument fd identifies a 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 and 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, and maxlen has no meaning for the req argument. 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. If maxlen in
ret is set to zero, no options values are returned. 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.
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, and len contains its total length; that is, 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.
Several options can be concatenated. The option user has, however to
ensure that each options header and value part starts at a boundary
appropriate for the architecture-specific alignment rules. The macros
T_OPT_FIRSTHDR(nbp), T_OPT_NXTHDR(nbp, tohp), T_OPT_DATA(tohp) are
provided for that purpose.
T_OPT_DATA
If argument is a pointer to a t_opthdr structure, this macro returns
an unsigned character pointer to the data associated with the
t_opthdr.
T_OPT_NXTHDR
If the first argument is a pointer to a netbuf structure associated
with an option buffer and second argument is a pointer to a t_opthdr
structure within that option buffer, this macro returns a pointer to
the next t_opthdr structure or a null pointer if this t_opthdr is the
last t_opthdr in the option buffer.
T_OPT_FIRSTHDR
If the argument is a pointer to a netbuf structure associated with an
option buffer, this macro returns the pointer to the first t_opthdr
structure in the associated option buffer, or a null pointer if there
is no option buffer associated with this netbuf or if it is not
possible or the associated option buffer is too small to accommodate
even the first aligned option header.
T_OPT_FIRSTHDR is useful for finding an appropriately aligned start of the
option buffer. T_OPT_NEXTHDR is useful for moving to the start of the next
appropriately aligned option in the option buffer. Note that OPT_NEXTHDR
is also available for backward compatibility requirements. T_OPT_DATA is
useful for finding the start of the data part in the option buffer where
the contents of its values start on an appropriately aligned boundary.
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 value is T_SUCCESS if the proposed value was
negotiated, T_PARTSUCCESS if a degraded value was negotiated,
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, and
T_READONLY if modification of a read-only 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 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 (see
below) 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 value 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 XTI 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 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 options 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
T_NOTSUPPORT if the protocol level does not support this option or the
transport user illegally requested a privileged option, T_READONLY if
the option is read-only, and set to 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 (see below) 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 part of an option only. The
currently effective values are then returned in ret->opt.buf. The
status field returned is T_NOTSUPPORT if the protocol level does not
support this option or the transport user illegally requested a
privileged option, T_READONLY if the option is read-only, and set to
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 (see below) 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 [TNOTSUPPORT] 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; that is, if data sent
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 behaviour of
the function is not changed if O_NONBLOCK is set.
XTI-LEVEL OPTIONS
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 do not have end-to-end significance. 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:
option name type of option legal option va meaning
value
XTI_DEBUG array of see text enable
t_uscalar_t debugging
XTI_LINGER struct t_linger see text linger on
close if data
is present
XTI_RCVBUF t_uscalar_t size in octets receive buffer
size
XTI_RCVLOWAT t_uscalar_t size in octets receive low-
water mark
XTI_SNDBUF t_uscalar_t size in octets send buffer
size
XTI_SNDLOWAT t_uscalar_t size in octets send low-water
mark
A request for XTI_DEBUG is an absolute requirement. A request to activate
XTI_LINGER is an absolute requirement; the time-out value to this option
is not. XTI_RCVBUF, XTI_RCVLOWAT, 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"; that is, 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 close(2) or
t_close(3) if send data is still queued in the send buffer. The option
value specifies the linger period. If a close(2) or t_close(3) 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, close(2) or t_close(3) 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 declared as:
struct t_linger {
t_scalar_t l_onoff; /* switch option on/off */
t_scalar_t l_linger; /* linger period in seconds */
}
Legal values for the field l_onoff are:
T_NO switch option off
T_YES activate option
The value 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 time-out 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(3).
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.
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 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(2)) indicates the data, and
the data can be read by t_rcv(3) or t_rcvudata(3). 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. 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.
VALID STATES
ALL - apart from T_UNINIT
ERRORS
On failure, t_errno is set to one of the following:
[TBADF]
The specified file descriptor does not refer to a transport endpoint.
[TBADFLAG]
An invalid flag was specified.
[TBADOPT]
The specified options were in an incorrect format or contained illegal
information.
[TBUFOVFLW]
The number of bytes allowed for an incoming argument (maxlen) is
greater than 0 but not sufficient to store the value of that argument.
The information to be returned in ret will be discarded.
[TNOTSUPPORT]
This action is not supported by the transport provider.
[TOUTSTATE]
The communications endpoint referenced by fd is not in one of the
states in which a call to this function is valid.
[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 (t_errno).
[TSYSERR]
A system error has occurred during execution of this function.
RETURN VALUE
Upon successful completion, a value of 0 is returned. Otherwise, a value
of -1 is returned and t_errno is set to indicate an error.
SEE ALSO
t_accept(3)
t_alloc(3)
t_connect(3)
t_getinfo(3)
t_listen(3)
t_open(3)
t_rcvconnect(3)
USAGE NOTES
The t_optmgmt function is not thread safe.
The t_optmgmt function is not async-signal safe.