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.