dtrace_program_strcompile, dtrace_program_fcompile, dtrace_program_exec, dtrace_program_info - DTrace program interface
cc [ flag... ] file... -ldtrace [ library... ]
#include <dtrace.h>
dtrace_prog_t *dtrace_program_strcompile(dtrace_hdl_t *dtp,
const char *s, dtrace_probespec_t spec, uint_t cflags, int argc,
char *const argv[])
dtrace_prog_t *dtrace_program_fcompile(dtrace_hdl_t *dtp, FILE *fp,
uint_t cflags, int argc, char *const argv[])
int dtrace_program_exec(dtrace_hdl_t *dtp, dtrace_prog_t *pgp,
dtrace_proginfo_t *pip)
void dtrace_program_info(dtrace_hdl_t *dtp, dtrace_prog_t *pgp,
dtrace_proginfo_t *pip)
The dtrace_program_strcompile() function compiles a D program contained in a string, s. The dtrace_program_fcompile() function compiles a D program contained in a file pointed to by fp. dtp is a DTrace handle as returned by dtrace_open(3DTRACE). spec is the probe description evaluation context. cflags are the compilation flags. See the Usage section for more information on the spec and cflags arguments. argc is the count of arguments being passed to this program, and argv contains those arguments.
The dtrace_program_exec() function creates a DTrace Object Format (DOF) object from the compiled program pgp and downloads it into the kernel in preparation for running the D program via dtrace_go(3DTRACE). Information about the program being executed is returned in the pip argument.
The dtrace_program_info() function returns information about the compiled program pgp in pip. See the Usage section for a description of the dtrace_proginfo_t data structure.
Upon successful completion, the dtrace_program_fcompile() function and dtrace_program_strcompile() function return a pointer to a dtrace_prog_t structure representing the compiled D program. Otherwise these functions return NULL and set the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.
Upon successful completion, the dtrace_program_exec() function returns 0. Otherwise the function returns -1 and sets the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.
The dtrace_program_info() function has no return value, although the function sets the DTrace error number in the case of an error. See the dtrace_errno(3DTRACE) man page for more information.
The dtrace_program_strcompile() and dtrace_program_fcompile() functions will fail if:
dtp is NULL, s or fp is NULL, or an invalid bit is set in cflags.
The system failed to allocate memory while processing the function.
The system failed to fork the preprocessor (if DTRACE_C_CPP was specified).
The system failed to execute the preprocessor (if DTRACE_C_CPP was specified).
The system failed to find the preprocessor (if DTRACE_C_CPP was specified).
The preprocessor encountered an error and failed (if DTRACE_C_CPP was specified).
There was an error in compiling the D program.
The dtrace_program_exec() function will fail if:
dtp or pgp is NULL.
The downloaded DIF is invalid.
There was a failure when attempting to download the DIF into the kernel.
The DIF for this program exceeds the maximum allowable size.
The system failed to enable some probe specified in the program.
The dtrace_program_info() function will fail if:
dtp is NULL, or pgp is NULL and pip is non-NULL.
The values for the probe description evaluation context are as follows:
DTRACE_PROBESPEC_NONE
DTRACE_PROBESPEC_PROVIDER
DTRACE_PROBESPEC_MOD
DTRACE_PROBESPEC_FUNC
DTRACE_PROBESPEC_NAME
The values for the compilation flags are as follows:
DIF verbose mode: show each compiled DIF object
Permit compilation of empty D source files
Permit probe definitions that match zero probes
Error if program attributes are less than the minimum
Preprocess input file with cpp(1)
Permit unresolved kernel symbols in DIF objects
Permit unresolved user symbols in DIF objects
Interpret ambiguous specifiers as probes
Prefix error messages with error tags
Do not require all macro arguments to be used
Use 0/"" as value for unspecified arguments
Do not process D system libraries
Only process control directives
See the libdtrace(3LIB) for an example of using the dtrace_program_strcompile() function and dtrace_program_exec() function.
See attributes(7) for descriptions of the following attributes:
|
libdtrace(3LIB), dtrace_errno(3DTRACE), dtrace_go(3DTRACE), dtrace_open(3DTRACE), dtrace_dof_create(3DTRACE)