Go to main content

Oracle® Solaris 11.4 DTrace (Dynamic Tracing) Guide

Exit Print View

Updated: September 2020

libdtrace API Reference

For more information about the libdtrace library, see the libdtrace(3LIB) man page.

General Purpose APIs

dtrace_hdl_t *dtrace_open(int version, int flags, int *errp)

Creates a DTrace handle, which is passed to other libdtrace functions. See dtrace_open(3DTRACE).

dtrace_hdl_t *dtrace_vopen(int version, int flags, int *errp,const dtrace_vector_t *vector, void *arg)

Creates a vectored DTrace open. This API contains pointers to functions to be used instead of the communication with DTrace. See dtrace_vopen(3DTRACE).

int dtrace_go(dtrace_hdl_t *dtp)

Causes tracing to begin for a D program that has been compiled by using dtrace_program_strcompile() or dtrace_program_fcompile() and downloaded into the kernel by using dtrace_program_exec(). See dtrace_go(3DTRACE).

int dtrace_stop(dtrace_hdl_t *dtp)

Disables all the probes associated with the DTrace handle. dtrace_stop also stops collecting data. See dtrace_stop(3DTRACE).

void dtrace_sleep(dtrace_hdl_t *dtp)

Suspends the execution for an interval time. The duration of the suspension is determined by certain rates specified in DTrace handle. See dtrace_sleep(3DTRACE).

void dtrace_close(dtrace_hdl_t *dtp)

Closes the DTrace handle and frees any resources associated with it. See dtrace_close(3DTRACE).

int dtrace_errno(dtrace_hdl_t *dtp)

Returns the error number associated with this DTrace handle. The error number will be set on failure of a libdtrace function call. See dtrace_errno(3DTRACE).

const char *dtrace_errmsg(dtrace_hdl_t *dtp, int error)

Returns a string associated with a particular DTrace error number. For example:

if (dtrace_foo(dtp) == -1) {
		fprintf(stderr, "%s\n",
		    dtrace_errmsg(dtp, dtrace_errno(dtp)));

See dtrace_errmsg(3DTRACE).

const char *dtrace_faultstr(dtrace_hdl_t *dtp, int fault)

Returns a string associated with a particular DTrace fault number. See dtrace_faultstr(3DTRACE).

const char *dtrace_subrstr(dtrace_hdl_t *dtp, int subr)

Returns the name of a DTrace subroutine given the constant associated with that subroutine. See dtrace_subrstr(3DTRACE).

int dtrace_setopt(dtrace_hdl_t *dtp, const char *opt, const char *val)

Sets certain options for the DTrace handle for data collection. The full list of options is provided in DTrace Options and Tunables. Certain options must be set for data collection. Specifically, if any regular data is collected by using trace(), tracemem(), or printf(), the bufsize option must be set so that principal buffers are allocated. If any aggregations are used, the aggsize option must be set so that aggregation buffers are allocated. The option is specified in the second argument, and the value is specified as a string in the third argument. See dtrace_setopt(3DTRACE).

int dtrace_getopt(dtrace_hdl_t *dtp, const char *opt, dtrace_optval_t *val)

Gets the current value of an option, returning the value in the third argument. See dtrace_getopt(3DTRACE).

void dtrace_update(dtrace_hdl_t *dtp)

Clears the DTrace cache of CTF and other information about the system, and repopulates the data. See dtrace_update(3DTRACE).

int dtrace_ctlfd(dtrace_hdl_t *dtp)

Returns the file descriptor that is being used to communicate with /dev/dtrace. See dtrace_ctlfd(3DTRACE).

int dtrace_fire_extern(dtrace_hdl_t *dtp, uint64_t arg1, unit64_t arg2, uint64_t arg3)

Fires when dtrace_fire_extern is called in the consumer. The EXTERN probe allows a consumer to pass information to a running DTrace script. The arguments to dtrace_fire_extern are passed as arguments to the EXTERN probe. See dtrace_fire_extern(3DTRACE).