Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

dtrace_vopen (3DTRACE)

Name

dtrace_open, dtrace_vopen, dtrace_close - Open and close DTrace handles

Synopsis

     cc [ flag... ] file... -ldtrace [ library... ]
     #include <dtrace.h>

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

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

     void dtrace_close(dtrace_hdl_t *dtp)

Description

The dtrace_open() function creates a DTrace handle, an opaque object containing information about the current invocation of DTrace. The DTrace handle is passed to other libdtrace(3LIB) library functions. The version argument contains the DTrace version to be used. The flags argument specifies the options to be associated with the DTrace handle. See the Usage section for more information on the version and flags arguments. If an error occurs, the errp argument contains the error number.

The dtrace_vopen() is a vectored DTrace open function. The DTrace library normally communicates directly with the dtrace(4D) device. However, this communication can be vectored elsewhere using the dtrace_vopen() function. The vector argument contains pointers to the vector functions replacing the dtrace(4D) device for such communication purposes. The user-defined argument, arg is passed to the vector functions.

The dtrace_close() function closes a DTrace handle, freeing all resources associated with the DTrace handle.

Return Values

Upon successful completion, the dtrace_open() and dtrace_vopen() functions return a pointer to a DTrace handle, an opaque data structure. Otherwise, the functions return NULL and the errp argument indicates the error number.

The dtrace_close() function has no return value, although it sets the DTrace error number to indicate a failure. See the dtrace_errno(3DTRACE) man page for more information.

Errors

The dtrace_open() and dtrace_vopen() functions will fail if:

EINVAL
  • The version argument passed to the function is invalid.

  • The flags argument contains invalid bit.

  • The flags argument contains both DTRACE_O_LP64 and DTRACE_O_ILP32 values.

  • Only for the dtrace_vopen() function, the vector argument is NULL and arg argument is non-NULL.

EDT_VERSION

The value of the version argument is greater than the current DTrace version number.

EDT_OVERSION

The value of the version argument is less than the minimum committed DTrace version number.

EDT_ELFVERSION

The libelf library is out of date with respect to the libdtrace library.

EDT_NOENT

The DTrace device, /dev/dtrace is not available.

EDT_BUSY

The DTrace device is busy because, for example, the kernel debugger is active.

EDT_ACCESS

The user has insufficient privileges to use DTrace.

EDT_NOMEM

The system was unable to allocate memory while processing this function.

EDT_DIFVERS

The libdtrace library uses a newer DIF version than the DTrace driver.

EDT_TYPE

A call into the backend type system failed.

The dtrace_close() function will fail if:

EINVAL

The DTrace handle is NULL.

Usage

The current DTrace version number is defined by the macro, DTRACE_VERSION.

The set of flags which can be passed to the dtrace_open() and dtrace_vopen() functions are listed below:

DTRACE_O_NODEV

Do not open the dtrace(4D) device

DTRACE_O_NOSYS

Do not load /system/object modules

DTRACE_O_LP64

Force the D compiler to be LP64

DTRACE_O_ILP32

Force the D compiler to be ILP32

Examples

See the libdtrace(3LIB) man page for an example of using the dtrace_open() and dtrace_close() functions.

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)