1. Using DTrace for System Tracing
  2. DTrace Function Reference

7 DTrace Function Reference

You use D function calls to invoke different kinds of services that DTrace provides.

Functions can be grouped according to their general use case and might appear in more than one grouping:

Data Recording Functions

Data recording functions record data to a DTrace buffer. These are the most common functions and the default DTrace function belongs to this category. By default, data recording functions record data to the principal buffer, but can also be directed to record data into a speculative buffer.

Data recording functions include:

  • Default Action: The default action applies when DTrace encounters an empty clause for a probe. The default action is to trace the enabled probe identifier (EPID).

  • printa: Displays and controls the formatting of an aggregation

  • printf: Displays and controls the formatting of a string.

  • trace: Traces the result of an expression to the directed buffer.

  • tracemem: Copies the specified number of bytes of data from an address in memory to the current buffer.

Aggregation Functions

Aggregation functions provide calculated information about sets of DTrace data stored in aggregations.

The following functions are aggregation functions:

  • avg: Stores the arithmetic average of the specified expressions in an aggregation.

  • count: Stores an incremented count value in an aggregation.

  • max: Stores the largest value among the specified expressions in an aggregation.

  • min: Stores the smallest value among the specified expressions in an aggregation.

  • sum: Stores the total value of the specified expression in an aggregation.

  • stddev: Stores the standard deviation of the specified expressions in an aggregation.

  • quantize: Stores a power-of-two frequency distribution of the values of the specified expressions in an aggregation. An optional increment can be specified.

  • lquantize: Stores the linear frequency distribution of the values of the specified expressions, sized by the specified range, in an aggregation.

  • llquantize: Stores the log-linear frequency distribution in an aggregation.

The following functions aren't aggregating functions but work on aggregations:

  • clear: Clears the values from an aggregation while retaining aggregation keys.

  • denormalize: Removes the normalization that's applied to a specified aggregation.

  • normalize: Divides an aggregation value by a specified normalization factor.

  • printa: Displays and controls the formatting of an aggregation

Speculation Functions

Speculation functions create or operate on speculative buffers. Speculation is used to trace quantities into speculation buffers that can either be committed to the primary buffer or discarded at a later point, when other important information is known.

The following functions are speculation functions:

  • speculation: Creates a speculative trace buffer and returns its ID.

  • speculate: A special function that causes DTrace to switch to using a speculation buffer identified by the specified ID for the remainder of a clause.

  • commit: Commits the speculative buffer, specified by ID, to the principal buffer.

  • discard: Discards a speculative buffer specified by the provided speculation ID.

String Manipulation Functions

String manipulation functions are typical in most programming languages and are used to perform common functional operations on strings. Many functions have analogs in the system library calls described in section 3 of the Oracle Linux manual pages. You can often find out more about these functions by examining the corresponding manual page. For example:

man 3 strchr

Several of these functions require temporary buffers, which persist only for duration of the clause. Preallocated scratch memory is used for such buffers.

The following string manipulation functions are available:

  • index: Finds the first occurrence of a substring within a string.

  • rindex: Finds the last occurrence of a specific substring within a string.

  • lltostr: Converts an unsigned 64-bit integer to a string.

  • strchr: Returns a substring that begins at the first matching occurrence of a specified character in a string.

  • strjoin: Concatenates two specified strings and returns the resulting string.

  • strlen: Returns the length of a string in bytes.

  • strrchr: Returns a substring that begins at the last matching occurrence of a specified character in a string.

  • strstr: Returns a substring starting at first occurrence of a specified substring within a string.

  • strtok: Parse a string into a sequence of tokens using a specified delimiter.

  • substr: Returns the substring from a string at a specified index position.

File Path Manipulation Functions

Similar to string manipulation functions, file path manipulation functions act on file paths or can provide the path name for a specified pointer. Some of these functions have analogs in the system library calls described in section 3 of the Oracle Linux manual pages.

  • basename: Returns a string excluding any prefix ending in /.

  • dirname: Returns the path up to the last level of a specified string.

Integer Conversion Functions

Similar to string manipulation functions, DTrace includes several integer conversion functions that can convert integers between host byte order and network byte order. These functions have analogs in the system library calls described in section 3 of the Oracle Linux manual pages.

The following integer conversion functions are available:

  • htonl: Converts an unsigned 32-bit long integer from host byte order to network byte order.

  • htonll: Converts an unsigned 64-bit long integer from host byte order to network byte order.

  • htons: Converts a short 16-bit unsigned integer from host byte order to network byte order.

  • ntohl: Converts a 32-bit long integer from network byte order to host byte order.

  • ntohll: Converts a 64-bit long integer from network byte order to host byte order.

  • ntohs: Converts a short 16-bit integer from network byte order to host byte order.

Copying Functions

Copying functions are functions that relate to copying information between memory addresses and DTrace buffers. Some of these functions are also considered process destructive functions because they change data in memory for a running process. Destructive functions must be explicitly enabled in DTrace.

  • alloca: Allocates memory and returns a pointer.

  • bcopy: Copies a specified size in bytes from a specified source address outside of scratch memory to a destination address inside scratch memory.

  • copyin: Copies the specified size from the user address to a DTrace buffer and returns the address of the buffer.

  • copyinstr: Copies a null-terminated C string from the specified user address to a DTrace buffer and returns the address of the buffer.

  • copyinto: Copies the specified size in bytes from the specified user address into the DTrace scratch buffer and returns the buffer address.

  • copyout: Copies the specified size from the specified DTrace buffer to the specified user space address.

  • copyoutstr: Copies a specified string to a specified user space address.

Lock Analysis Functions

Lock analysis functions are used to check mutexes and file locks.

The following lock analysis functions are available:

  • mutex_owned: Checks whether a thread holds the specified kernel mutex.

  • mutex_owner: Returns the thread pointer to the current owner of the specified kernel mutex.

  • mutex_type_adaptive: Returns a non-zero value if a specified kernel mutex is adaptive.

  • mutex_type_spin: Returns a non-zero value if a specified kernel mutex is a spin mutex.

  • rw_iswriter: Checks whether a writer is holding or waiting for the specified reader-writer lock.

  • rw_read_held: Checks whether the specified reader-writer lock is held by a reader.

  • rw_write_held: Checks whether the specified reader-writer lock is held by a writer.

Symbolic Names and Stack Analysis Functions

DTrace includes functions that either record stack traces to the buffer or which can print symbols and module names for pointers to addresses in user space or kernel space can be helpful for debugging processes.

The following functions return information about stack and addresses:

  • stack: Records a stack trace to the buffer.

  • func: Prints the symbol for a specified kernel space address. An alias for sym.

  • mod: Prints the module name that corresponds to a specified kernel space address.

  • sym: Prints the symbol for a specified kernel space address. An alias for func.

  • ustack: Records a user stack trace to the directed buffer.

  • uaddr: Prints the symbol for a specified address.

  • ufunc: Prints the symbol for a specified user space address. An alias for usym.

  • umod: Prints the module name that corresponds to a specified user space address.

  • usym: Prints the symbol for a specified address. An alias for ufunc.

General System Functions

DTrace includes several functions to obtain information from the system or which are generalized for different use cases. Functions in this category include:

  • getmajor: Returns the major device number for a specified device.

  • getminor: Returns the minor device number for a specified device

  • inet_ntoa: Returns a dotted, quad decimal string for a pointer to an IPv4 address.

  • progenyof: Checks whether a calling process is in the progeny of a specified process ID.

  • rand: Returns a pseudo random integer.

Destructive Functions

DTrace is designed to run code safely. By using destructive functions, you must explicitly enable them to relax the constraints that protect a system from actions that are run from DTrace.

Destructive functions can change a process or the entire system in some defined manner. These include functions such as stopping the current process, raising a specific signal on the current process or even spawning another system process. You can only use these functions if the facility to use destructive functions is explicitly enabled. When using the dtrace utility, you can enable destructive functions by using the -w command line option.

If you try to use destructive functions without explicitly enabling them, dtrace fails with a message similar to the following: 

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

These functions must be used with caution, as such functions can affect every process on the system and any other system, implicitly or explicitly, depending upon the affected system's network services.

  • copyout: Copies the specified size from the specified DTrace buffer to the specified user space address.

  • copyoutstr: Copies a specified string to a specified user space address.

  • freopen: Changes the file associated with stdout to a specified file.

  • ftruncate: Truncates the output stream on stdout.

  • raise: Sends a specified signal to the running process.

  • system: Causes a specified program to be run on the system as if within a shell.

Special Functions

DTrace also includes functions that change DTrace behavior such as exiting tracing altogether or changing DTrace runtime options.

  • exit: Stops all tracing and exits to return an exit value.

  • setopt: Dynamically sets DTrace compiler or runtime options.