DTrace Functions

By Ifeyinwa Okoye and John Stearns, August 2006

DTrace Functions

Name	Prototype	Description

`trace`	`void trace (expression)`	Takes a D expression as argument and traces the result to the directed buffer.
`tracemem`	`void tracemem (address, size_t nbytes)`	Takes the memory address specified by `address` into the directed buffer for the length specified by `nbytes`. Address is a D expression.
`printf`	`void printf (string format,...)`	The arguments are a format string followed by a variable number of arguments. The arguments are formatted for output according to the specified format string.
`printa`	`void printa (aggregation) void printa (string format, aggregation)`	Enables displaying and formatting of aggregations. If a format is not specified, the default format is used.
`stack`	`void stack (int nframes)`, `void stack (void)`	Records a kernel stack trace, `nframes` in depth. The number specified by the `stackframes` option is used if `nframes` is not specified. May also be used as a key to an aggregation.
`ustack`	`void ustack (int nframes, int strsize)` `void ustack (int nframes)` `void ustack (void)`	Records a user stack trace, `nframes` in depth. The number specified by the `ustackframes` option is used if `nframes` is unspecified. If `strsize` is specified and non-zero, `ustack`() will allocate the specified amount of string space and use it to perform address-to-symbol translation directly from the kernel.
`jstack`	`void jstack (int nframes, int strsize)` `void jstack (int nframes)` `void jstack (void)`	Alias for `ustack`() that uses the `jstackframes` option for the stack frame value and `jstackstrsize` for the string space size.
`stop`	`void stop (void)`	Forces the process that fires the enabled probe to stop when it next leaves the kernel.
`raise`	`void raise (int signal)`	Sends the specified signal to the currently running process.
`copyout`	`void copyout (void *buf, uintptr_t addr, size_t nbytes)`	Copies `nbytes` from the buffer `buf` to the address `addr` in the address space of the process associated with the current thread.
`copyoutstr`	`void copyoutstr (string str, uintptr_t addr, size_t maxlen)`	Copies the string `str` to the address `addr` in the address space of the process associated with the current thread. The string length is limited to the value set by the `strsize` option.
`system`	`void system (string program, ...)`	Causes program to be executed as if it were given to the shell as input. Program may contain any of the `printf`/`printa` formats. Other arguments must match the specified format in program.
`breakpoint`	`void breakpoint (void)`	Induces a kernel breakpoint, causing the system to stop and transfer control to the kernel debugger.
`panic`	`void panic (void)`	Causes a kernel panic. Should be used to force a system crash dump at a time of interest.
`chill`	`void chill (int nanoseconds)`	Causes DTrace to spin for the given nanoseconds. For system safety, DTrace will refuse to execute the chill action for more than 500 milliseconds in each 1-second on any CPU.
`exit`	`void exit (int status)`	Immediately stops tracing, notifies DTrace consumer to cease tracing, performs any final processing, and calls exit with the specified status.
`alloca`	`void *alloca (size_t size)`	Allocates size bytes out of scratch space and returns a pointer to the allocated memory.
`basename`	`string basename (char *str)`	Creates a string that consists of a copy of the specified string, but without any prefix that ends in `/`.
`bcopy`	`void bcopy (void src, void dest, size_t size)`	Copies size bytes from the memory pointed to by `src`, to the memory pointed to by `dest`. All source memory must lie outside of scratch memory, and all destination memory must lie within it.
`cleanpath`	`string cleanpath (char *str)`	Creates a string that consists of a copy of the path indicated by `str`, but with redundant elements eliminated. This might result in shorter invalid paths being returned.
`copyin`	`void *copyin (uintptr_t addr, size_t size)`	Copies the specified size in bytes from the specified user address into a DTrace scratch buffer and returns the address of this buffer. The resulting buffer pointer is 8-byte aligned.
`copyinstr`	`string copyinstr (uintptr_t addr)`	Copies a null-terminated C string from the specified user address into a DTrace scratch buffer, and returns the address of this buffer. The `strsize` option limits the string length.
`copyinto`	`void copyinto (uintptr_t addr, size_t size, void *dest)`	Copies the specified size in bytes from the specified user address into the DTrace scratch buffer specified by `dest`.
`dirname`	`string dirname (char *str)`	Creates a string that consists of all but the last level of the path name specified by `str`.
`msgdsize`	`size_t msgdsize (mblk_t *mp)`	Returns the number of bytes in the data message pointed to by `mp`.
`msgsize`	`size_t msgsize (mblk_t *mp)`	Returns the number of bytes in the message pointed to by `mp`.
`mutex_owned`	`int mutex_owned (kmutex_t *mutex)`	Returns non-zero if the calling thread currently holds the specified kernel mutex, or zero if the specified adaptive mutex is currently unowned.
`mutex_owner`	`kthread_t mutex_owner (kmutex_t mutex)`	Returns the thread pointer of the current owner of the specified adaptive kernel mutex. Returns NULL if the specified adaptive mutex is currently unowned, or if the specified mutex is a spin mutex.
`mutex_type_adaptive`	`int mutex_type_adaptive (kmutex_t *mutex)`	Returns non-zero if the specified kernel mutex is of type `MUTEX_ADAPTIVE`, or zero if it is not.
`progenyof`	`int progenyof (pid_t pid)`	Returns non-zero if the calling process is among the progeny of the specified process ID.
`rand`	`int rand (void)`	Returns a pseudo-random integer.
`rw_iswriter`	`int rw_iswriter(krwlock_t *rwlock)`	Returns non-zero if the specified reader-writer lock is either held or desired by a writer. Returns zero if the lock is held only by readers, no writer is blocked, or the lock is not held at all.
`rw_write_held`	`int rw_write_held (krwlock_t *rwlock)`	Returns non-zero if the specified reader-writer lock is currently held by a writer. Returns zero if the lock is held only by readers or not held at all.
`speculation`	`int speculation (void)`	Reserves a speculative trace buffer for use with `speculate`() and returns an identifier for this buffer.
`strjoin`	`string strjoin(char str1 char str2)`	Creates a string that consists of `str1` concatenated with `str2`.
`strlen`	`size_t strlen(string str)`	Returns the length of the specified string in bytes, excluding the terminating null byte.