setopt
Handler
Options affecting the behavior of DTrace can be set in one of the following ways:
-
Directly by the consumer
-
Indirectly by using a
pragma
in the D program -
From within a D program with the
setopt
() action.
In the first two cases, the option is set prior to running the D program. In the third case, the option is set at runtime.
Note:
Certain options, such as buffer sizes, might only be set prior to executing a D program.The consumer must be informed when the values of certain options change during the execution of a D program. The setopt
handler informs the consumer about any change in the options during runtime. In the absence of the setopt
handler, the processing continues when options are changed. This behavior differs from the behavior for errors and drops, but setting options is not considered to be an abnormal occurrence.
The dtrace_handle_setopt
() interface provided by the libdtrace
library specifies a setopt
handler. The arguments to the dtrace_handle_setopt
() function are:
-
DTrace handle
-
Pointer to a function to handle the
setopt
-
Pointer to a private argument to be passed to the
setopt
handler
The setopt
handler is a function that takes two arguments: a pointer to the dtrace_setoptdata
data structure and a pointer to the private argument originally passed to the dtrace_handle_setopt
() function. It returns one of two values: DTRACE_HANDLE_ABORT
or DTRACE_HANDLE_OK
.
The dtrace_setoptdata
data structure contains information about the option that was set, including which option was set and the old and new values for that option.
typedef struct dtrace_setoptdata { dtrace_hdl_t *dtsda_handle; /* handle to DTrace library */ const dtrace_probedata_t *dtsda_probe; /* probe data */ const char *dtsda_option; /* option that was set */ dtrace_optval_t dtsda_oldval; /* old value */ dtrace_optval_t dtsda_newval; /* new value */ } dtrace_setoptdata_t;
Because the changing of values is not an abnormal occurrence, there is no predefined message is included in this data structure. So there is no setopt
handler to parallel the drop and error handlers where the prepared message is displayed to the user. You can ignore a setopt
either by installing a handler that only returns DTRACE_HANDLE_OK
or by relying on the default behavior.
There might be cases in which the consumer might alter its behavior based on the value of certain options. In the following example, the setopt
handler for dtrace
checks whether the value for the quiet
or flowindent
option has been set.
static int setopthandler(const dtrace_setoptdata_t *data, void *arg) { if (strcmp(data->dtsda_option, "quiet") == 0) g_quiet = data->dtsda_newval != DTRACEOPT_UNSET; if (strcmp(data->dtsda_option, "flowindent") == 0) g_flowindent = data->dtsda_newval != DTRACEOPT_UNSET; return (DTRACE_HANDLE_OK); }
The dtrace
utility predicates certain behavior on those options. The chew
() function for DTrace prints extra information, such as the probe ID and the CPU on which a probe fired, when the quiet
option is not set. The chew
() function also implements the formatting for the flowindent
processing.