man pages section 3: Extended Library Functions, Volume 2

dtrace_proc_continue (3DTRACE)

Name

dtrace_proc_grab, dtrace_proc_create, dtrace_proc_continue, dtrace_proc_release - DTrace process control interfaces

Synopsis

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

     struct ps_prochandle *dtrace_proc_create(dtrace_hdl_t *dtp,
	const char *file, char *const *argv)

     struct ps_prochandle *dtrace_proc_grab(dtrace_hdl_t *dtp, pid_t pid,
	int flags)

     void dtrace_proc_release(dtrace_hdl_t *dtp, struct ps_prochandle *P)

     void dtrace_proc_continue(dtrace_hdl_t *dtp, struct ps_prochandle *P)

Description

The dtrace_proc_create() function is used to create a process under the control of DTrace. The process is left in a stopped state and needs to be set running by calling the dtrace_proc_continue() function. The dtrace_proc_create() function takes the following arguments:

file

Program to be executed.

argv

argv for the executed process.

The dtrace_proc_grab() function is used to place an existing process under the control of DTrace. The function takes the following arguments:

pid

pid of the process.

flags

Has possible values, 0 or DTRACE_PGRAB_RDONLY.

---

Note -  The data type of the return value is defined by the libproc library, which is not a public API. The value can be treated as opaque by casting it as a void *. The value can be passed to dtrace_proc_release() and dtrace_proc_continue() functions, described next in this section.

---

The dtrace_proc_release() function is used to release a process under DTrace control. The second argument, P, is the value returned by a previous call to the dtrace_proc_create() or dtrace_proc_grab() functions.

The dtrace_proc_continue() function is used to set running a process that is stopped. (Note that dtrace_proc_create() and dtrace_proc_grab() functions leave the process in question in a stopped state.)

Return Values

On successful completion, the dtrace_proc_create() and dtrace_proc_grab() functions return a pointer to an opaque object. Otherwise the 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.

The dtrace_proc_release() and dtrace_proc_continue() functions have no return value, although the functions set the DTrace error number in the event of a failure. See the dtrace_errno(3DTRACE) man page for more information.

Errors

The dtrace_proc_create() function will fail if:

EINVAL

The dtp, file, or argv argument is NULL.

EDT_NOMEM

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

EDT_COMPILER

The libproc library encountered some error while attempting to create this process.

The dtrace_proc_grab() function will fail if:

EINVAL

The dtp argument is NULL.

EDT_COMPILER

The libproc library failed to grab this process or failed to create a control thread within this process.

The dtrace_proc_release() and dtrace_proc_continue() functions will fail if:

EINVAL

The dtp or P argument is NULL.

Attributes

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

See Also

libdtrace(3LIB), dtrace_errno(3DTRACE)