Destructive Actions

You must explicitly enable destructive actions in order to use them. You can enable destructive actions by using the -w option. If you attempt to use destructive actions in dtrace without explicitly enabling them, dtrace fails with a message similar to the following example:

dtrace: failed to enable 'syscall': destructive actions not allowed

For more information on DTrace actions, including destructive actions, see Chapter 10, Actions and Subroutines, in Solaris Dynamic Tracing Guide.

Process Destructive Actions

Some actions are destructive only to a particular process. These actions are available to users with the dtrace_proc or dtrace_user privileges. See Chapter 35, Security, in Solaris Dynamic Tracing Guide for details on DTrace security privileges.

The stop() function

When a probe fires with the stop() action enabled, the process that fired that probe stops upon leaving the kernel. This process stops in the same way as a process that is stopped by a proc(4) action.

The raise() function

void raise(int signal)

The raise() action sends the specified signal to the currently running process.

The copyout() function

void copyout(void *buf, uintptr_t addr, size_t nbytes)

The copyout() action copies data from a buffer to an address in memory. The number of bytes that this action copies is specified in nbytes. The buffer that the data is copied from is specified in buf. The address that the data is copied to is specified in addr. That address is in the address space of the process that is associated with the current thread.

The copyoutstr() function

void copyoutstr(string str, uintptr_t addr, size_t maxlen)

The copyoutstr() action copies a string to an address in memory. The string to copy is specified in str. The address that the string is copied to is specified in addr. That address is in the address space of the process that is associated with the current thread.

The system() function

void system(string program, ...) 

The system() action causes the program specified by program to be executed by the system as if it were given to the shell as input.

Kernel Destructive Actions

Some destructive actions are destructive to the entire system. Use these actions with caution. These actions affect every process on the system and may affect other systems, depending upon the affected system's network services.

The breakpoint() function

void breakpoint(void)

The breakpoint() action induces a kernel breakpoint, causing the system to stop and transfer control to the kernel debugger. The kernel debugger will emit a string that denotes the DTrace probe that triggered the action.

The panic() function

void panic(void)

When a probe with the panic() action triggers, the kernel panics. This action can force a system crash dump at a time of interest. You can use this action in conjunction with ring buffering and postmortem analysis to diagnose a system problem. For more information, see Chapter 11, Buffers and Buffering, in Solaris Dynamic Tracing Guide and Chapter 37, Postmortem Tracing, in Solaris Dynamic Tracing Guide respectively.

The chill() function

void chill(int nanoseconds)

When a probe with the chill() action triggers, DTrace spins for the specified number of nanoseconds. The chill() action is useful for exploring problems related to timing. Because interrupts are disabled while in DTrace probe context, any use of chill() will induce interrupt latency, scheduling latency, dispatch latency.