9.1 Interpreter Files

Similar to your shell and utilities such as awk and perl, you can use the dtrace command to create executable interpreter files.

An interpreter file begins with a line of the following form:

#!pathname [arg]

where pathname is the path of the interpreter and arg is a single, optional argument. When an interpreter file is executed, the system invokes the specified interpreter. If arg was specified in the interpreter file, it is passed as an argument to the interpreter. The path to the interpreter file and any additional arguments that were specified when it was executed are then appended to the interpreter argument list. Therefore, you always need to create DTrace interpreter files with at least the following arguments:

#!/usr/sbin/dtrace -s

When your interpreter file is executed, the argument to the -s option is the pathname of the interpreter file. The dtrace command then reads, compiles, and executes this file as if you had typed the following command in your shell:

# dtrace -s interpreter-file

The following example shows how you would create and execute a dtrace interpreter file. First, type the following D source code and save it in a file named interp.d:

#!/usr/sbin/dtrace -s
BEGIN
{
  trace("hello");
  exit(0);
}

Then, make the interp.d file executable and execute it as follows:

# chmod a+rx interp.d
# ./interp.d
dtrace: script './interp.d' matched 1 probe
CPU     ID                    FUNCTION:NAME
  0      1                           :BEGIN   hello                            
#

Remember that the #! directive must comprise the first two characters of your file with no intervening or preceding white space. The D compiler automatically ignores this line when it processes the interpreter file.

The dtrace command uses getopt() to process command-line options so that you can combine multiple options in your single interpreter argument. For example, to add the -q option to the previous example you could change the interpreter directive to the following:

#!/usr/sbin/dtrace -qs
Note

If you specify multiple options, the -s option must always end the list of options so that the next argument, the interpreter file name, is correctly processed as the argument to the -s option.

If you need to specify more than one option that requires an argument in your interpreter file, use the #pragma D option directive to set your options. Several dtrace command-line options have #pragma equivalents that you can use. See Chapter 10, Options and Tunables.