void freopen(string format, ...)

The freopen action changes the file that is associated with stdout to the file that is specified by the arguments in printf fashion.

If the "" string is used, the output is again restored to stdout.

void ftruncate(void)

The ftruncate action truncates the output stream on stdout.

_symaddr func(uintptr_t address)

The func action prints the symbol that corresponds to a specified kernel-space address. For example, func((uintptr_t) (&vmlinux`max_pfn)) causes vmlinux`max_pfn to be printed. The func action is an alias for sym.

_symaddr mod(uintptr_t address)

The mod action prints the name of the module that corresponds to a specified kernel-space address. For example, mod((uintptr_t) (&vmlinux`max_pfn)) prints vmlinux.

void printa(aggregation)
void printa(string format, aggregation)

The printa action enables you to display and format aggregations. See Aggregations for more details. If format is not specified, printa traces only a directive to the DTrace consumer for which the specified aggregation should be processed and is displayed using the default format. If format is specified, the aggregation is formatted. See printa Action for a detailed description of the printa format string.

When printa traces only a directive that the aggregation should be processed by the DTrace consumer, it does not process the aggregation in the kernel. Therefore, the time between the tracing of the printa directive and the actual processing of the directive depends on factors that affect buffer processing, which include the following: the aggregation rate, the buffering policy (and if the buffering policy is switching), and the rate at which buffers are switched. See Aggregations and Buffers and Buffering for detailed descriptions.

void printf(string format, ...)

Like trace, the printf action traces D expressions, but printf enables elaborate printf-style formatting. The parameters consist of a format string, followed by a variable number of arguments. By default, the arguments are traced to the directed buffer. The arguments are later formatted for output by the dtrace command, according to the specified format string, for example:

printf("execname is %s; priority is %d", execname, curlwpsinfo->pr_pri);

For more information, see printf Action.

stack stack(int nframes)
stack stack(void)

The stack action records a kernel stack trace to the directed buffer. The kernel stack is nframes in depth. If nframes is not specified, the number of stack frames recorded is the number that is specified by the stackframes option. The dtrace command reports frames, either up to the root frame or until the nframes limit has been reached, whichever comes first:

# dtrace -n gettimeofday:entry'{stack()}'
dtrace: description 'gettimeofday:entry' matched 1 probe
CPU     ID                    FUNCTION:NAME
  0    196               gettimeofday:entry 
              vmlinux`pollwake
              vmlinux`dtrace_stacktrace+0x30
              vmlinux`__brk_limit+0x1e1832d7
              vmlinux`__brk_limit+0x1e1913a1
              vmlinux`pollwake
              vmlinux`do_gettimeofday+0x1a
              vmlinux`ktime_get_ts+0xad
              vmlinux`systrace_syscall+0xde
              vmlinux`audit_syscall_entry+0x1d7
              vmlinux`system_call_fastpath+0x16

  0    196               gettimeofday:entry 
              vmlinux`dtrace_stacktrace+0x30
              vmlinux`__brk_limit+0x1e1832d7
              vmlinux`__brk_limit+0x1e1913a1
              vmlinux`security_file_permission+0x8b
              vmlinux`systrace_syscall+0xde
              vmlinux`audit_syscall_entry+0x1d7
              vmlinux`system_call_fastpath+0x16

...

The stack action, having a non-void return value, can also be used as the key to an aggregation, for example:

# dtrace -n execve:entry'{@[stack()] = count()}'
dtrace: description 'execve:entry' matched 1 probe
^C


              vmlinux`dtrace_stacktrace+0x30
              vmlinux`__brk_limit+0x1e1832d7
              vmlinux`__brk_limit+0x1e1913a1
              vmlinux`dtrace_execve+0xcd
              vmlinux`audit_syscall_entry+0x1d7
              vmlinux`dtrace_stub_execve+0x6c
                2

              vmlinux`dtrace_stacktrace+0x30
              vmlinux`__brk_limit+0x1e1832d7
              vmlinux`__brk_limit+0x1e1913a1
              vmlinux`do_sigaction+0x13a
              vmlinux`dtrace_execve+0xcd
              vmlinux`audit_syscall_entry+0x1d7
              vmlinux`dtrace_stub_execve+0x6c
               13

...

_symaddr sym(uintptr_t address)

The sym action prints the symbol that corresponds to a specified kernel-space address. For example, sym((uintptr_t) (&vmlinux`max_pfn)) causes vmlinux`max_pfn to be printed. The sym action is an alias for func.

void trace(expression)

The trace action is the most basic action. This action takes a D expression as its argument and then traces the result to the directed buffer. The following statements are examples of trace actions:

trace(execname);
trace(curlwpsinfo->pr_pri);
trace(timestamp / 1000);
trace(‘lbolt);
trace("somehow managed to get here");

If the trace action is used on a buffer, the output format depends on the data type. If the dtrace command determines that the data is like an ASCII string, it prints it as text and terminates the output with a null character (0). When dtrace decides that the data is most likely binary, it prints it in hexadecimal format, for example:

0      342                      write:entry
             0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f  0123456789abcdef
         0: c0 de 09 c2 4a e8 27 54 dc f8 9f f1 9a 20 4b d1  ....J.’T..... K.
        10: 9c 7a 7a 85 1b 03 0a fb 3a 81 8a 1b 25 35 b3 9a  .zz.....:...%5..
        20: f1 7d e6 2b 66 6d 1c 11 f8 eb 40 7f 65 9a 25 f8  .}.+fm....@.e.%.
        30: c8 68 87 b2 6f 48 a2 a5 f3 a2 1f 46 ab 3d f9 d2  .h..oH.....F.=..
        40: 3d b8 4c c0 41 3c f7 3c cd 18 ad 0d 0d d3 1a 90  =.L.A<.<........

You can force the trace action to always use the binary format by specifying the rawbytes option.

void tracemem(address, size_t nbytes)
void tracemem(address, size_t nbytes, size_t dbytes)

The tracemem action takes a D expression as its first argument, address, and a constant as its second argument, nbytes. The tracemem action copies the memory from the address specified by address into the directed buffer for the length specified by nbytes. If only two arguments are provided, dtrace dumps the entire contents of the buffer.

In the second format, the tracemem action takes an additional, third argument, dbytes, which is a D expression that is computed dynamically. The result is used to limit the number of bytes that are displayed. If the result is less than zero or greater than nbytes, the result is ignored and tracemem behaves as though it is called by using the two-argument form. Otherwise, dtrace dumps only the dbytes bytes of the directed buffer.

DTrace supports the use of the ustack action with both 32-bit and 64-bit binaries, for example:

stack ustack(int nframes, int strsize) 
stack ustack(int nframes)
stack ustack(void)

The ustack action records a user stack trace to the directed buffer. The user stack is nframes in depth. If nframes is not specified, the number of stack frames that is recorded is the number specified by the ustackframes option. While ustack is able to determine the address of the calling frames when the probe fires, the stack frames are not translated into symbols until the ustack action is processed at user level by the DTrace consumer. If strsize is specified and is non-zero, ustack allocates the specified amount of string space and then uses it to perform address-to-symbol translation directly from the kernel. Such direct user symbol translation is used only with stacktrace helpers that support this usage with DTrace. If such frames cannot be translated, the frames appear only as hexadecimal addresses.

The following example traces a stack with no address-to-symbol translation:

# dtrace -n syscall::write:entry'/pid == $target/{ustack(); exit(0)}' -c "./mytestprog -v"
dtrace: description 'syscall::write:entry' matched 1 probe
mytestprog (Version 1.0)
CPU     ID                    FUNCTION:NAME
  2      6                      write:entry 
              mytestprog`printver+0x2f
              mytestprog`0x401338
              mytestprog`main+0xc7
              mytestprog`0x401338
              libc.so.6`__libc_start_main+0xfd
              mytestprog`main
              mytestprog`0x400ad0
              mytestprog`__libc_csu_init
              mytestprog`0x400ad0
              mytestprog`0x400af9

The ustack symbol translation occurs after the stack data is recorded. Therefore, the corresponding user process might exit before symbol translation can be performed, making stack frame translation impossible. If the user process exits before symbol translation is performed, dtrace outputs a warning message, followed by the hexadecimal stack frames.

DTrace supports the use of the uaddr action with both 32-bit and 64-bit binaries.

_usymaddr uaddr(uintptr_t address)

The uaddr action prints the symbol for a specified address, including hexadecimal offset, which enables the same symbol resolution that ustack provides.

DTrace supports the use of the usym action with both 32-bit and 64-bit binaries.

_usymaddr usym(uintptr_t address)

The usym action prints the symbol for a specified address, which is analogous to how uaddr works, but without the hexadecimal offsets.

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

The copyout action copies nbytes from the buffer that is specified by buf to the address that is specified by addr, in the address space of the process that associated with the current thread. If the user-space address does not correspond to a valid, faulted-in page in the current address space, an error is generated.

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

The copyoutstr action copies the string tha tis specified by str to the address that is specified by addr in the address space of the process associated with the current thread. If the user-space address does not correspond to a valid, faulted-in page in the current address space, an error is generated. Note that the string length is limited to the value that is set by the strsize option. See Options and Tunables.

void raise(int signal)

The raise action sends the specified signal to the currently running process. This action is similar to using the kill command to send a signal to a process. The raise action can be used to send a signal at a precise point in the execution of a process.

void stop(void)

The stop action forces the process that is firing the enabled probe to stop when it next leaves the kernel, as if stopped by a proc action. The stop action can be used to stop a process at any DTrace probe point. This action can be used to capture a program in a particular state that would be difficult to achieve with a simple breakpoint and then attach a traditional debugger such as gdb to the process. You can also use the gcore utility to save the state of a stopped process in a core file for later analysis.

void system(string program, ...)

The system action causes the specified program to be executed as though given to the shell as input. The program string can contain any of the printf or printa format conversions. Arguments that match the format conversions must be specified. See Output Formatting for details on valid format conversions.

The following example runs the date command once per second:

# dtrace -wqn tick-1sec'{system("date")}'
Tue Oct 16 10:21:34 BST 2012
Tue Oct 16 10:21:35 BST 2012
Tue Oct 16 10:21:36 BST 2012
^C
#

The following example shows a more elaborate use of the action by using printf conversions in the program string, along with traditional filtering tools such as pipes. Type the following source code and save it in a file named whosend.d:

#pragma D option destructive
#pragma D option quiet

proc:::signal-send
/args[2] == SIGINT/
{
  printf("SIGINT sent to %s by ", args[1]->pr_fname);
  system("getent passwd %d | cut -d: -f5", uid);
}

Running the previous script results in output similar to the following:

# dtrace -s whosend.d
SIGINT sent to top by root
SIGINT sent to bash by root
SIGINT sent to bash by A Nother
^C
SIGINT sent to dtrace by root

The execution of the specified command does not occur in the context of the firing probe. Rather, it occurs when the buffer containing the details of the system action are processed at user level. How and when this processing occurs depends on the buffering policy, as described in Buffers and Buffering. With the default buffering policy, the buffer processing rate is specified by the switchrate option.

You can see the delay that is inherent in system if you explicitly tune the switchrate higher than its one-second default, as shown in the following example. Save it in a file named time.d:

#pragma D option quiet
#pragma D option destructive
#pragma D option switchrate=5sec

tick-1sec
/n++ < 5/
{
  printf("walltime : %Y\n", walltimestamp);
  printf("date : ");
  system("date");
  printf("\n");
}

tick-1sec
/n == 5/
{
  exit(0);
}

Running the previous script results in output similar to the following:

# dtrace -s time.d
walltime : 2012 Oct 16 10:26:07
date : Tue Oct 16 10:26:11 BST 2012

walltime : 2012 Oct 16 10:26:08
date : Tue Oct 16 10:26:11 BST 2012

walltime : 2012 Oct 16 10:26:09
date : Tue Oct 16 10:26:11 BST 2012

walltime : 2012 Oct 16 10:26:10
date : Tue Oct 16 10:26:11 BST 2012

walltime : 2012 Oct 16 10:26:11
date : Tue Oct 16 10:26:11 BST 2012

In the previous output, notice that the walltime values differ, but the date values are identical. This result reflects the fact that the execution of the date command occurred when the buffer was processed, not when the system action was recorded.

void chill(int nanoseconds)

The chill action causes DTrace to spin for the specified number of nanoseconds. This action is primarily useful for exploring problems that might be timing related. For example, you can use this action to open race condition windows or bring periodic events into or out of phase with one another. Because interrupts are disabled while in DTrace probe context, any use of the chill action results in an interrupt, scheduling, or dispatch latency. Therefore, chill can cause unexpected systemic effects and therefore should not be used indiscriminately. Because system activity relies on periodic interrupt handling, DTrace refuses to execute the chill action for more than 500 milliseconds out of each one-second interval on any given CPU. If the maximum chill interval is exceeded, DTrace reports an illegal operation error:

# dtrace -w -n syscall::openat:entry'{chill(500000001)}'
dtrace: allowing destructive actions
dtrace: description 'syscall::openat:entry' matched 1 probe 
dtrace: 57 errors
CPU     ID                    FUNCTION:NAME 
dtrace: error on enabled probe ID 1 (ID 14: syscall::openat:entry): \
illegal operation in action #1

This limit is enforced even if the time is spread across multiple calls to chill or multiple DTrace consumers of a single probe. For example, the same error would be generated by running the following command:

# dtrace -w -n syscall::openat:entry'{chill(250000000); chill(250000001);}'

void panic(void)

When triggered, the panic action causes a kernel panic. This action should be used to force a system crash dump at a time of interest. You can use this action along with ring buffering to understand a problem. For more information, see Buffers and Buffering . When the panic action is used, a panic message appears denoting the probe that is causing the panic. rsyslogd also emits a message upon reboot. The message buffer of the crash dump contains the probe and event control block (ECB) that is responsible for the panic action.

The actions associated with speculative tracing are speculate, commit, and discard. These actions are described in more detail in Speculative Tracing.

void exit(int status)

The exit action is used to immediately stop tracing and inform the DTrace consumer that it should do the following: cease tracing, perform any final processing, and call exit() with the specified status value. Because exit returns a status to user level, it is considered a data recording action, However, unlike other data storing actions, exit cannot be speculatively traced. The exit action causes the DTrace consumer to exit regardless of buffer policy. Note that because exit is a data recording action, it can be dropped.

When exit is called, only those DTrace actions that are already in progress on other CPUs are completed. No new actions occur on any CPU. The only exception to this rule is the processing of the END probe, which is called after the DTrace consumer has processed the exit action, and indicates that tracing should stop.

void setopt(const char *opt_name)
void setopt(const char *opt_name, const char *opt_value)

setopt("quiet");
setopt("bufsize", "50m");
setopt("aggrate", "2hz");