*** UNIX MANUAL PAGE BROWSER ***

t_optmgmt(3) Library Functions Manual t_optmgmt(3) NAME t_optmgmt - Manages protocol options for a transport endpoint LIBRARY XTI Library (libxti.a) SYNOPSIS #include <xti.h> int t_optmgmt( int fd, struct t_optmgmt *req, struct t_optmgmt *ret) ; STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: t_optmgmt: XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS The following table summarizes the relevance of input and output para- meters before and after t_optmgmt() is called: center,tab(@); lfHB lfHB lfHB l c c. 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->flags@y@n ret->opt.maxlen@y@n ret->opt.len@n@y ret->opt.buf@o@(o) ret->flags@n@y _ Table Notes: This a meaningful parameter. The content of the object pointed to by y is meaningful. This is not a meaningful parameter. This is an optional parameter. The content of the object pointed to by o is optional. Specifies a file descriptor returned by t_open() func- tion that identifies the local transport endpoint. 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 flag values to the user. Both arguments point to a type t_optmgmt structure. This struc- ture is used to reserve space for a transport-user options data buffer that stores negotiable protocol options. The type t_opt- mgmt structure has the following members: Specifies a buffer for protocol options associated with the referenced transport end- point. 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: For the req argument, this has no meaning. For the ret argument, it specifies the maximum byte length of the options buffer. 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. 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: Contains its total length (the length of the option header t_opthdr plus the length of the option value). Identi- fies the XTI level or a protocol of the transport provider. Identifies the option within the level. If t_optmgmt() is called with the action T_NEGOTIATE set, the status field of the returned options contains information about the success or fail- ure 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 op- tion, or the level specified is unsupported, the t_optmgmt() re- quest 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_opt- mgmt() with the T_CURRENT flag set. A longword (least signifi- cant 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. center, tab (@); lb lb l lw(3i) . Symbolic Name@Mean- ing _ T_NEGOTIATE@T{ 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 accept- able (negotiated) values to the data buffer pointed to by ret->opt.buf. T} T_CHECK@T{ The transport user wants to verify that the options specified in the data buffer pointed to by req->opt.buf are sup- ported by the transport provider. On return, the transport provider writes a ret->flags> value, which is either T_SUCCESS or T_FAILURE. T} T_DEFAULT@T{ 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.len parameter must be set to 0 (zero). The req->opt.buf member may be set to its null value. T} T_CURRENT@T{ 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. T} _ 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. XTI-LEVEL OPTIONS XTI-level options are not specific for a particular transport provider. Digital'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. tab(@); lfHB lfHB lfHB lfHB l l l l. T{ Option Name T}@T{ Type of Option Value T}@T{ Legal Option Value T}@T{ Meaning T} _ XTI_DEBUG@T{ array of unsigned longs T}@See text@en- able debugging XTI_LINGER@struct linger@See text@T{ linger on close if data is present T} 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 acti- vate XTI_LINGER is also an absolute requirement; the timeout value for this option is not. XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF, and XTI_SND- LOWAT are not absolute requirements. This option controls debugging. Debugging is disabled if the option is specified with "no value", that is, with only an option header. DIGITAL 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 op- tion 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 sys- tem supplies utilities to process the traces. Lingers the exe- cution 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 de- clared 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: switch option off 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 un- derlying transport provider; the value is often T_INFINITE. Le- gal 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 implemen- tation 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_snd- dis(). Adjusts the internal buffer size allocated for the re- ceive buffer. The buffer size may be increased for high volume connections or decreased to limit the possible backlog of incom- ing 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. Sets a low-water mark in the receive buffer. The option value gives the minimal number of bytes that must have accumu- lated 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. 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. Sets a low-water mark in the send buffer. The option value gives the minimal number of bytes that must have accumu- lated 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. DESCRIPTION The t_optmgmt() XTI function is used in connectionless and connection- oriented transport service. The t_optmgmt() function associates spe- cific 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. RETURN VALUE Upon successful completion, a value of 0 (zero) is returned. Other- wise, a value of -1 is returned and t_errno is set to indicate the er- ror. ERRORS If the t_optmgmt() function fails, t_errno may be set to one of the following values: File descriptor fd does not refer to a valid trans- port endpoint. This function was called in the wrong sequence. The specified protocol options are either of an incorrect format or contain illegal information. The specified flag is invalid. The transport user does not have permission to negotiate the specified options. 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. A system er- ror occurred during execution of the t_optmgmt() function. This func- tion is not supported by the underlying transport provider. 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). RELATED INFORMATION Functions: t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_lis- ten(3), t_open(3), t_rcvconnect(3) delim off delim off t_optmgmt(3)