dtrace_handle_buffered, dtrace_handle_drop, dtrace_handle_err, dtrace_handle_proc, dtrace_handle_setopt - DTrace handler interface
cc [ flag... ] file... -ldtrace [ library... ]
#include <dtrace.h>
typedef int dtrace_handle_buffered_f(const dtrace_bufdata_t *, void *);
int dtrace_handle_buffered(dtrace_hdl_t *dtp,
dtrace_handle_buffered_f *hdlr, void *arg)
typedef int dtrace_handle_drop_f(const dtrace_dropdata_t *, void *);
int dtrace_handle_drop(dtrace_hdl_t *dtp, dtrace_handle_drop_f *hdlr,
void *arg)
typedef int dtrace_handle_err_f(const dtrace_errdata_t *, void *);
int dtrace_handle_err(dtrace_hdl_t *dtp, dtrace_handle_err_f *hdlr,
void *arg)
typedef void dtrace_handle_proc_f(struct ps_prochandle *, const char *,
void *);
int dtrace_handle_proc(dtrace_hdl_t *dtp, dtrace_handle_proc_f *hdlr,
void *arg)
typedef int dtrace_handle_setopt_f(const dtrace_setoptdata_t *, void *);
int dtrace_handle_setopt(dtrace_hdl_t *dtp, dtrace_handle_setopt_f *hdlr,
void *arg)
The dtrace_handle_buffered() function is used to register a buffered I/O handler for a DTrace consumer, thus allowing the consumer to perform its own buffered I/O.
If a NULL pointer is passed to the dtrace_work(3DTRACE), dtrace_consume(3DTRACE), or dtrace_aggregate_print(3DTRACE) function, then the libdtrace(3LIB) library makes use of the buffered I/O handler. The output then goes into the dtbda_buffered member of the dtrace_bufdata_t data structure, described as follows:
typedef struct dtrace_bufdata {
dtrace_hdl_t *dtbda_handle; /* handle to DTrace library */
const char *dtbda_buffered; /* buffered output */
dtrace_probedata_t *dtbda_probe; /* probe data */
const dtrace_recdesc_t *dtbda_recdesc; /* record description */
const dtrace_aggdata_t *dtbda_aggdata; /* aggregation data, if agg. */
uint32_t dtbda_flags; /* flags (see USAGE) */
} dtrace_bufdata_t;
The dtrace_handle_drop() function is used to register a drop handler for a DTrace consumer. The drop handler is called whenever data is dropped by the running D program. Information about the drop is stored in the dtrace_dropdata_t argument that has the following structure:
typedef struct dtrace_dropdata {
dtrace_hdl_t *dtdda_handle; /* handle to DTrace library */
processorid_t dtdda_cpu; /* CPU, if any */
dtrace_dropkind_t dtdda_kind; /* kind of drop (see USAGE) */
uint64_t dtdda_drops; /* number of drops */
uint64_t dtdda_total; /* total drops */
const char *dtdda_msg; /* preconstructed message */
} dtrace_dropdata_t;
The dtrace_handle_err() function is used to register an error handler for a DTrace consumer. The error handler is called whenever an error, such as accessing an invalid address or dividing by zero, occurs in a running D program. Information about the error is stored in the dtrace_errdata_t argument that has the following structure:
typedef struct dtrace_errdata {
dtrace_hdl_t *dteda_handle; /* handle to DTrace library */
dtrace_eprobedesc_t *dteda_edesc; /* enabled probe inducing err */
dtrace_probedesc_t *dteda_pdesc; /* probe inducing error */
processorid_t dteda_cpu; /* CPU of error */
int dteda_action; /* action inducing error */
int dteda_offset; /* offset in DIFO of error */
int dteda_fault; /* specific fault */
uint64_t dteda_addr; /* address of fault, if any */
const char *dteda_msg; /* preconstructed message */
} dtrace_errdata_t;
The dtrace_handle_proc() function is used to register a process handler for a DTrace consumer. The process handler is called whenever certain events, such as dynamic linker activity or exiting by a process, occur in a process under DTrace control. A libproc handle to the process is passed as the first argument, and a preformatted message is passed as the second argument to the handler.
The dtrace_handle_setopt() function is used to register a setopt handler for a DTrace consumer. The setopt handler is called whenever a DTrace option is set from inside a D program using the setopt() function. Information about the option being set, and the old and new values of the option are passed in the dtrace_setoptdata_t argument that has the following structure:
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;
On successful completion, these functions return 0. On failure, these functions return -1 and set the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.
The functions will fail if:
dtp is NULL.
A handler of this type already exists for this DTrace handle.
Handlers are expected to return one of the following values:
Abort the current D program.
The event has been handled appropriately, and the operation can continue.
The flags that may be set in the dtbda_flags member of the dtrace_bufdata_t structure are as follows:
Aggregation key
Aggregation value
Aggregation format data
Last for this key/val
The types of data drops, exposed using the dtdda_kind member of the dtrace_dropdata_t structure are as follows:
Drop to the principal buffer
Drop to the aggregation buffer
Dynamic drop
Dynamic drop due to rinsing
Dynamic drop due to dirty
Speculative drop
Speculative drop due to busy
Speculative drop due to unavail
Stack string tab overflow
Error in the ERROR probe
The following is example shows how a DTrace error handler works:
static int
errhandler(const dtrace_errdata_t *data, void *arg)
{
fprintf(stderr, "Error on enabled probe %d (probe %s:%s:%s:%s)\n",
data->dteda_edesc->dtepd_epid, data->dteda_pdesc->dtpd_provider,
data->dteda_pdesc->dtpd_mod, data->dteda_pdesc->dtpd_func,
data->dteda_pdesc->dtpd_name);
return (DTRACE_HANDLE_OK);
}
[ ... ]
if (dtrace_handle_err(g_dtp, errhandler, NULL) == -1) {
fprintf(stderr, "Failed to install error handler\n");
exit(1);
}
See attributes(7) for descriptions of the following attributes:
|