Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

dtrace_program_fcompile (3DTRACE)

Name

dtrace_program_strcompile, dtrace_program_fcompile, dtrace_program_exec, dtrace_program_info - DTrace program interface

Synopsis

     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)

Description

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.

Return Values

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.

Errors

The dtrace_program_strcompile() and dtrace_program_fcompile() functions will fail if:

EINVAL

dtp is NULL, s or fp is NULL, or an invalid bit is set in cflags.

EDT_NOMEM

The system failed to allocate memory while processing the function.

EDT_CPPFORK

The system failed to fork the preprocessor (if DTRACE_C_CPP was specified).

EDT_CPPEXEC

The system failed to execute the preprocessor (if DTRACE_C_CPP was specified).

EDT_CPPENT

The system failed to find the preprocessor (if DTRACE_C_CPP was specified).

EDT_CPPERR

The preprocessor encountered an error and failed (if DTRACE_C_CPP was specified).

EDT_COMPILER

There was an error in compiling the D program.

The dtrace_program_exec() function will fail if:

EINVAL

dtp or pgp is NULL.

EDT_DIFINVAL

The downloaded DIF is invalid.

EDT_DIFFAULT

There was a failure when attempting to download the DIF into the kernel.

EDT_DIFSIZE

The DIF for this program exceeds the maximum allowable size.

EDT_ENABLING_ERR

The system failed to enable some probe specified in the program.

The dtrace_program_info() function will fail if:

EINVAL

dtp is NULL, or pgp is NULL and pip is non-NULL.

Usage

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:

DTRACE_C_DIFV

DIF verbose mode: show each compiled DIF object

DTRACE_C_EMPTY

Permit compilation of empty D source files

DTRACE_C_ZDEFS

Permit probe definitions that match zero probes

DTRACE_C_EATTR

Error if program attributes are less than the minimum

DTRACE_C_CPP

Preprocess input file with cpp(1)

DTRACE_C_KNODEF

Permit unresolved kernel symbols in DIF objects

DTRACE_C_UNODEF

Permit unresolved user symbols in DIF objects

DTRACE_C_PSPEC

Interpret ambiguous specifiers as probes

DTRACE_C_ETAGS

Prefix error messages with error tags

DTRACE_C_ARGREF

Do not require all macro arguments to be used

DTRACE_C_DEFARG

Use 0/"" as value for unspecified arguments

DTRACE_C_NOLIBS

Do not process D system libraries

DTRACE_C_CTL

Only process control directives

Examples

See the libdtrace(3LIB) for an example of using the dtrace_program_strcompile() function and dtrace_program_exec() function.

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), dtrace_go(3DTRACE), dtrace_open(3DTRACE), dtrace_dof_create(3DTRACE)