| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
| XPG4.2 | both |
#define _XOPEN_SOURCE_EXTENDED 1
#include <xti.h>
int t_optmgmt(int fd, struct t_optmgmt *req, struct t_optmgmt *ret);struct netbuf opt;
long flags;unsigned int maxlen maximum buffer value length
unsigned int len actual buffer value length
char * buf pointer to bufferEach option in the options buffer is of the form struct t_opthdr possibly followed by an option value. The t_opthdr structure contains the following members:
unsigned long len sizeof(t_opthdr)+optval len
unsigned long level protocol affected
unsigned long name option value
unsigned long status status valueunsigned int len sizeof(t_opthdr)+optval len
unsigned int level protocol affected
unsigned int name option value
unsigned int status status valueThe 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. The total length 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.
Each option in the input or output option buffer must start at a long-word boundary. The macro OPT_NEXTHDR(pbuf, buflen, poption) 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 poption points to the 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 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.
Before using this function, you should read topic, “Use of Options in XTI”, in X/Open CAE Specification, Networking Services, Issue 4
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.)
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.
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(), t_open() ) before the call.
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.
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. For example, 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 behavior of the function is not changed if O_NONBLOCK is set.
Valid states: All - except for T_UNINIT
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 are not association-related They may be negotiated in all XTI states except T_UNINIT. See topic, “Use of Options in XTI”, in X/Open CAE Specification, Networking Services, Issue 4 for more information.
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.
struct t_linger {
long l_onoff; /* switch option on/off */
long l_linger; /* linger period in seconds */
}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 nonnegative 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().
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.
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.
struct t_kpalive {
long kp_onoff; /* switch option on/off */
long kp_timeout; /* keep-alive timeout in minutes */
}The timeout value is not an absolute requirement. However, no limits are currently specified by the TCP transport provider.
If successful, t_optmgmt() returns 0.