Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

dtrace_handle_setopt (3DTRACE)

Name

dtrace_handle_buffered, dtrace_handle_drop, dtrace_handle_err, dtrace_handle_proc, dtrace_handle_setopt - DTrace handler interface

Synopsis

     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)

Description

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;

Return Values

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.

Errors

The functions will fail if:

EINVAL

dtp is NULL.

EALREADY

A handler of this type already exists for this DTrace handle.

Usage

Handlers are expected to return one of the following values:

DTRACE_HANDLE_ABORT

Abort the current D program.

DTRACE_HANDLE_OK

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:

DTRACE_BUFDATA_AGGKEY

Aggregation key

DTRACE_BUFDATA_AGGVAL

Aggregation value

DTRACE_BUFDATA_AGGFORMAT

Aggregation format data

DTRACE_BUFDATA_AGGLAST

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:

DTRACEDROP_PRINCIPAL

Drop to the principal buffer

DTRACEDROP_AGGREGATION

Drop to the aggregation buffer

DTRACEDROP_DYNAMIC

Dynamic drop

DTRACEDROP_DYNRINSE

Dynamic drop due to rinsing

DTRACEDROP_DYNDIRTY

Dynamic drop due to dirty

DTRACEDROP_SPEC

Speculative drop

DTRACEDROP_SPECBUSY

Speculative drop due to busy

DTRACEDROP_SPECUNAVAIL

Speculative drop due to unavail

DTRACEDROP_STKSTROVERFLOW

Stack string tab overflow

DTRACEDROP_DBLERROR

Error in the ERROR probe

Examples

Example 1 Using a DTrace Error Handler

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);
	}

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Architecture
All
Availability
system/dtrace
Interface Stability
Committed
MT-Level
Safe

See Also

libdtrace(3LIB), dtrace_errno(3DTRACE)