[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 2
Manage options for a transport
endpoint.
X/Open Transport Interface
Library (libxti.a)
#include <xti.h>
int t_optmgmt(
int fd,
const struct t_optmgmt *req,
struct t_optmgmt *ret)
The t_optmgmt
subroutine enables a transport user to retrieve, verify, or negotiate protocol
options with the transport provider.
The req and
ret parameters both point to a t_optmgmt structure
containing the following members:
struct netbuf opt;
long flags;
Within this structure, the fields
have the following meaning:
opt
| Identifies protocol options. The options are represented by a
netbuf structure in a manner similar to the address in the
t_bind subroutine:
- len
- Specifies the number of bytes in the options and on return, specifies the
number of bytes of options returned.
- buf
- Points to the options buffer. For the ret parameter,
buf points to the buffer where the options are to be placed.
Each option in the options buffer is of the form struct t_opthdr
possibly followed by an option value. The fields of this structure and
the values are:
- level
- Identifies the X/Open Transport Interface level or a protocol of the
transport provider.
- name
- Identifies the option within the level.
- len
- Contains its total length, for example, 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.
- status
- 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 macro
parameters are as follows:
- pbuf
- Specifies a pointer to an option buffer opt.buf.
- buflen
- The length of the option buffer pointed to by pbuf.
- 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 the xti.h header
file for the exact definition of this structure.
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 fails with
TBADOPT. If the error is detected, some options may have
successfully negotiated. The transport user can check the current
status by calling the t_optmgmt subroutine with the
T_CURRENT flag set.
Note: "The Use of Options" contains a detailed description
about the use of options and should be read before using this
subroutine.
- maxlen
- Has no meaning for the req parameter, but must be set in the
ret parameter to specify the maximum size of the options
buffer. On return, len specifies the number of bytes of
options returned. The value in maxlen has no meaning for the
req argument,
|
flags
| Specifies the action to take with those options. The
flags field of req must specify one of the following
actions:
- T_CHECK
- This action enables the user to verify whether the options specified in
the req parameter are supported by the transport provider.
If an option is specified with no option value, (that is, it consists only of
a t_opthdr structure), the option is returned with its
status field set to one of the following:
- T_SUCCESS - if it is supported.
- T_NOTSUPPORT - if it is not or needs
additional user privileges.
- T_READONLY - if it is read-only (in the
current X/Open Transport Interface 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 the flags field of the netbuf
structure pointed to by the ret parameter. This field
contains the worst single result of the option checks, where the rating is the
same as for T_NEGOTIATE.
Note, that no negotiation takes
place. All currently effective option values remain unchanged.
- T_CURRENT
- This action enables the transport user to retrieve the currently effective
option values. The user specifies the options of interest in the
opt fields in the netbuf structure pointed to by the
req parameter. 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
opt fields in the netbuf structure pointed to by the
ret parameter.
The status field
returned is on of the following:
- 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.
- T_SUCCESS in all other cases.
The overall result of the option
checks is returned in the flags field of the netbuf
structure pointed to by the ret parameter. This field
contains the worst single result of the option checks, where the rating is the
same as for T_NEGOTIATE.
For each level, the
T_ALLOPT option (see below) can be requested on input. All
supported options of this level with their default values are then
returned.
|
|
- T_DEFAULT
- This action enables the transport user to retrieve the default option
values. The user specifies the options of interest in the
opt fields in the netbuf structure pointed to by the
req parameter. 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 the opt
field of the netbuf structure pointed to by the ret
parameter.
The status field
returned is one of the following:
- 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.
- T_SUCCESS in all other cases.
The overall result of the option
checks is returned in the flags field of the ret
parameter netbuf structure. This field contains the worst
single result of the option checks, where the rating is the same as for
T_NEGOTIATE.
For each level, the
T_ALLOPT option (see below) can be requested on input. All
supported options of this level with their default values are then
returned. In this case, the maxlen value of the
opt field in the ret parameter netbuf
structure must be given at least the value of the options field of
the info parameter (see the t_getinfo or t_open
subroutines) before the call.
|
|
- 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 in the req parameter netbuf structure.
The negotiated option values are returned in the buffer pointed to by the
opt field of the ret parameter netbuf
structure. The status field of each returned option is set
to indicate the result of the negotiation. The value is one of the
following:
- T_SUCCESS if the proposed value was
negotiated.
- T_PARTSUCCESS if a degraded value was
negotiated.
- T_FAILURE is 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 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 the flags field of the ret
parameter netbuf structure. This field contains the worst
single result, whereby the rating is done according to the following order,
where T_NOTSUPPORT is the worst result and T_SUCCESS is
the best:
- T_NOTSUPPORT
- T_READONLY
- T_FAILURE
- T_PARTSUCCESS
- T_SUCCESS.
For each level, the
T_ALLOPT option (see below) can be requested on input. This
option has no value and consists of a t_opthdr only. This
input requests negotiation of all supported options of this level to their
default values. The result is returned option by option in the
opt field of the structure pointed to in the ret
parameter. Depending on the state of the transport endpoint, not all
requests to negotiate the default value may be successful.
|
|
The T_ALLOPT option
can only be used with the t_optmgmt structure and the actions
T_NEGOTIATE, T_DEFAULT and T_CURRENT.
This option can be used with any supported level and addresses all supported
options of this level. The option has no value and consists of a
t_opthdr only. Since only options of one level may be
addressed in a t_optmgmt call, this option should not be requested
together with other options. The subroutine 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 subroutine
t_optmgmt may block under various circumstances and depending on
the implementation. For example, the subroutine will block if the
protocol addressed by the call resides on a separate controller. It may
also block due to flow control constraints, if data previously sent across
this transport endpoint has not yet been fully processed. If the
subroutine is interrupted by a signal, the option negotiations that have been
done so far may remain valid. The behavior of the subroutine is not
changed if O_NONBLOCK is set.
|
fd
| Identifies a transport endpoint.
|
req
| Requests a specific action of the provider.
|
ret
| Returns options and flag values to the user.
|
X/Open Transport Interface (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 the bound
transport endpoint identified by the fd parameter relates to
specific transport providers.
The subsequent options are not
association-related (see Chapter 5, The Use of Options)
. 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:
XTI-Level Options
|
Option Name
| Type of Option Value
| Legal Option Value
| Meaning
|
XTI_DEBUG
| array of unsigned longs
| see text
| 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_SNDBUF0
| 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 an absolute requirement; the timeout value to
this option is not. XTI_RCVBUF, XTI_RCVLOWAT,
XTI_SNDBUF and XTI_SNDLOWAT are not absolute
requirements.
XTI_DEBUG
| Enables debugging. The values of this option are
implementation-defined. Debugging is disabled if the option is
specified with no value (for example, with an option header only).
The system supplies utilities to
process the traces. An implementation may also provide other means for
debugging.
|
XTI_LINGER
| Lingers the execution of a t_close subroutine or the
close exec if send data is still queued in the send buffer.
The option value specifies the linger period. If a close
exec or t_close subroutine 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,
the t_close subroutine or close exec either, at a
maximum, block the linger period, or immediately return, whereupon, at most,
the system holds the connection in existence for the linger period.
The option value consists of a
structure t_linger declared as:
struct t_linger {
long l_onoff;
long l_linger;
}
The fields of the structure and
the legal values are:
- l_onoff
- Switches the option on or off. The value l_onoff is an
absolute requirement. The possible values are:
- T_NO
- switch option off
- T_YES
- activate option
- 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: Note that this option does not linger the execution of
the t_snddis subroutine.
|
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.
Legal values are all positive
numbers.
|
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, the
poll or select subroutines) indicates the data, and the
data can be read by the t_rcv or t_rcvudata
subroutines.
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
| Adjusts 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
| 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.
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.
|
ALL - except from
T_UNINIT.
0
| Successful completion.
|
-1
| t_errno is set to indicate an error.
|
On failure, t_errno is
set to one of the following:
TACCES
| The user does not have permission to negotiate the specified
options.
|
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.
|
TOUTSTATE
| The subroutine was issued in the wrong sequence.
|
TPROTO
| This error indicates that a communication problem has been detected
between the X/Open Transport Interface and the transport provider for which
there is no other suitable X/Open Transport Interface
(t_errno).
|
TSYSERR
| A system error has occurred during execution of this subroutine.
|
The t_accept subroutine, t_alloc subroutine, t_connect subroutine, t_getinfo subroutine, t_listen subroutine, t_open subroutine, t_rcvconnect subroutine.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]