SystemTap Tapset Reference Manual

SystemTap

Hackers

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of Linux.


Table of Contents

1. Introduction
Tapset Name Format
2. Context Functions
print_regs - Print a register dump.
execname - Returns the execname of a target process (or group of processes).
pid - Returns the ID of a target process.
tid - Returns the thread ID of a target process.
ppid - Returns the process ID of a target process's parent process.
pgrp - Returns the process group ID of the current process.
sid - Returns the session ID of the current process.
pexecname - Returns the execname of a target process's parent process.
gid - Returns the group ID of a target process.
egid - Returns the effective gid of a target process.
uid - Returns the user ID of a target process.
euid - Return the effective uid of a target process.
is_myproc - Determines if the current probe point has occurred in the user's own process.
cpu - Returns the current cpu number.
pp - Return the probe point associated with the currently running probe handler,
registers_valid - Determines validity of register and u_register in current context.
user_mode - Determines if probe point occurs in user-mode.
is_return - Whether the current probe context is a return probe.
target - Return the process ID of the target process.
module_name - The module name of the current script.
stp_pid - The process id of the stapio process.
stack_size - Return the size of the kernel stack.
stack_used - Returns the amount of kernel stack used.
stack_unused - Returns the amount of kernel stack currently available.
uaddr - User space address of current running task. EXPERIMENTAL.
print_stack - Print out stack from string.
probefunc - Return the probe point's function name, if known.
probemod - Return the probe point's module name, if known.
modname - Return the kernel module name loaded at the address.
symname - Return the symbol associated with the given address.
symdata - Return the symbol and module offset for the address.
usymname - Return the symbol of an address in the current task. EXPERIMENTAL!
usymdata - Return the symbol and module offset of an address. EXPERIMENTAL!
print_ustack - Print out stack for the current task from string. EXPERIMENTAL!
print_backtrace - Print stack back trace
backtrace - Hex backtrace of current stack
task_backtrace - Hex backtrace of an arbitrary task
caller - Return name and address of calling function
caller_addr - Return caller address
print_ubacktrace - Print stack back trace for current task. EXPERIMENTAL!
print_ubacktrace_brief - Print stack back trace for current task. EXPERIMENTAL!
ubacktrace - Hex backtrace of current task stack. EXPERIMENTAL!
3. Timestamp Functions
get_cycles - Processor cycle count.
4. Time string utility function
ctime - Convert seconds since epoch into human readable date/time string.
5. Memory Tapset
vm_fault_contains - Test return value for page fault reason
vm.pagefault - Records that a page fault occurred.
vm.pagefault.return - Indicates what type of fault occurred.
addr_to_node - Returns which node a given address belongs to within a NUMA system.
vm.write_shared - Attempts at writing to a shared page.
vm.write_shared_copy - Page copy for shared page write.
vm.mmap - Fires when an mmap is requested.
vm.munmap - Fires when an munmap is requested.
vm.brk - Fires when a brk is requested (i.e. the heap will be resized).
vm.oom_kill - Fires when a thread is selected for termination by the OOM killer.
vm.kmalloc - Fires when kmalloc is requested.
vm.kmem_cache_alloc - Fires when \
vm.kmalloc_node - Fires when kmalloc_node is requested.
vm.kmem_cache_alloc_node - Fires when \
vm.kfree - Fires when kfree is requested.
vm.kmem_cache_free - Fires when \
proc_mem_size - Total program virtual memory size in pages.
proc_mem_rss - Program resident set size in pages.
proc_mem_shr - Program shared pages (from shared mappings).
proc_mem_txt - Program text (code) size in pages.
proc_mem_data - Program data size (data + stack) in pages.
mem_page_size - Number of bytes in a page for this architecture.
bytes_to_string - Human readable string for given bytes.
pages_to_string - Turns pages into a human readable string.
proc_mem_string - Human readable string of current proc memory usage.
6. Task Time Tapset
task_utime - User time of the current task.
task_stime - System time of the current task.
cputime_to_msecs - Translates the given cputime into milliseconds.
msecs_to_string - Human readable string for given milliseconds.
cputime_to_string - Human readable string for given cputime.
task_time_string - Human readable string of task time usage.
7. IO Scheduler and block IO Tapset
ioscheduler.elv_next_request - Fires when a request is retrieved from the request queue
ioscheduler.elv_next_request.return - Fires when a request retrieval issues a return signal
ioscheduler.elv_add_request.kp - kprobe based probe to indicate that a request was added to the request queue
ioscheduler.elv_completed_request - Fires when a request is completed
ioscheduler.elv_add_request.tp - tracepoint based probe to indicate a request is added to the request queue.
ioscheduler.elv_add_request - probe to indicate request is added to the request queue.
ioscheduler_trace.elv_completed_request - Fires when a request is
ioscheduler_trace.elv_issue_request - Fires when a request is
ioscheduler_trace.elv_requeue_request - Fires when a request is
ioscheduler_trace.elv_abort_request - Fires when a request is aborted.
ioscheduler_trace.plug - Fires when a request queue is plugged;
ioscheduler_trace.unplug_io - Fires when a request queue is unplugged;
ioscheduler_trace.unplug_timer - Fires when unplug timer associated
ioblock.request - Fires whenever making a generic block I/O request.
ioblock.end - Fires whenever a block I/O transfer is complete.
ioblock_trace.bounce - Fires whenever a buffer bounce is needed for at least one page of a block IO request.
ioblock_trace.request - Fires just as a generic block I/O request is created for a bio.
ioblock_trace.end - Fires whenever a block I/O transfer is complete.
8. SCSI Tapset
scsi.ioentry - Prepares a SCSI mid-layer request
scsi.iodispatching - SCSI mid-layer dispatched low-level SCSI command
scsi.iodone - SCSI command completed by low level driver and enqueued into the done queue.
scsi.iocompleted - SCSI mid-layer running the completion processing for block device I/O requests
scsi.ioexecute - Create mid-layer SCSI request and wait for the result
scsi.set_state - Order SCSI device state change
9. TTY Tapset
tty.open - Called when a tty is opened
tty.release - Called when the tty is closed
tty.resize - Called when a terminal resize happens
tty.ioctl - called when a ioctl is request to the tty
tty.init - Called when a tty is being initalized
tty.register - Called when a tty device is registred
tty.unregister - Called when a tty device is being unregistered
tty.poll - Called when a tty device is being polled
tty.receive - called when a tty receives a message
tty.write - write to the tty line
tty.read - called when a tty line will be read
10. Networking Tapset
netdev.receive - Data received from network device.
netdev.transmit - Network device transmitting buffer
netdev.change_mtu - Called when the netdev MTU is changed
netdev.open - Called when the device is opened
netdev.close - Called when the device is closed
netdev.hard_transmit - Called when the devices is going to TX (hard)
netdev.rx - Called when the device is going to receive a packet
netdev.change_rx_flag - Called when the device RX flag will be changed
netdev.set_promiscuity - Called when the device enters/leaves promiscuity
netdev.ioctl - Called when the device suffers an IOCTL
netdev.register - Called when the device is registered
netdev.unregister - Called when the device is being unregistered
netdev.get_stats - Called when someone asks the device statistics
netdev.change_mac - Called when the netdev_name has the MAC changed
tcp.sendmsg - Sending a tcp message
tcp.sendmsg.return - Sending TCP message is done
tcp.recvmsg - Receiving TCP message
tcp.recvmsg.return - Receiving TCP message complete
tcp.disconnect - TCP socket disconnection
tcp.disconnect.return - TCP socket disconnection complete
tcp.setsockopt - Call to setsockopt
tcp.setsockopt.return - Return from setsockopt
tcp.receive - Called when a TCP packet is received
udp.sendmsg - Fires whenever a process sends a UDP message
udp.sendmsg.return - Fires whenever an attempt to send a UDP message is completed
udp.recvmsg - Fires whenever a UDP message is received
udp.recvmsg.return - Fires whenever an attempt to receive a UDP message received is completed
udp.disconnect - Fires when a process requests for a UDP disconnection
udp.disconnect.return - UDP has been disconnected successfully
ip_ntop - returns a string representation from an integer IP number
11. Socket Tapset
socket.send - Message sent on a socket.
socket.receive - Message received on a socket.
socket.sendmsg - Message is currently being sent on a socket.
socket.sendmsg.return - Return from socket.sendmsg.
socket.recvmsg - Message being received on socket
socket.recvmsg.return - Return from Message being received on socket
socket.aio_write - Message send via sock_aio_write
socket.aio_write.return - Conclusion of message send via sock_aio_write
socket.aio_read - Receiving message via sock_aio_read
socket.aio_read.return - Conclusion of message received via sock_aio_read
socket.writev - Message sent via socket_writev
socket.writev.return - Conclusion of message sent via socket_writev
socket.readv - Receiving a message via sock_readv
socket.readv.return - Conclusion of receiving a message via sock_readv
socket.create - Creation of a socket
socket.create.return - Return from Creation of a socket
socket.close - Close a socket
socket.close.return - Return from closing a socket
sock_prot_num2str - Given a protocol number, return a string representation.
sock_prot_str2num - Given a protocol name (string), return the corresponding protocol number.
sock_fam_num2str - Given a protocol family number, return a string representation.
sock_fam_str2num - Given a protocol family name (string), return the corresponding
sock_state_num2str - Given a socket state number, return a string representation.
sock_state_str2num - Given a socket state string, return the corresponding state number.
12. Kernel Process Tapset
kprocess.create - Fires whenever a new process is successfully created
kprocess.start - Starting new process
kprocess.exec - Attempt to exec to a new program
kprocess.exec_complete - Return from exec to a new program
kprocess.exit - Exit from process
kprocess.release - Process released
13. Signal Tapset
signal.send - Signal being sent to a process
signal.send.return - Signal being sent to a process completed
signal.checkperm - Check being performed on a sent signal
signal.checkperm.return - Check performed on a sent signal completed
signal.wakeup - Sleeping process being wakened for signal
signal.check_ignored - Checking to see signal is ignored
signal.check_ignored.return - Check to see signal is ignored completed
signal.force_segv - Forcing send of SIGSEGV
signal.force_segv.return - Forcing send of SIGSEGV complete
signal.syskill - Sending kill signal to a process
signal.syskill.return - Sending kill signal completed
signal.sys_tkill - Sending a kill signal to a thread
signal.systkill.return - Sending kill signal to a thread completed
signal.sys_tgkill - Sending kill signal to a thread group
signal.sys_tgkill.return - Sending kill signal to a thread group completed
signal.send_sig_queue - Queuing a signal to a process
signal.send_sig_queue.return - Queuing a signal to a process completed
signal.pending - Examining pending signal
signal.pending.return - Examination of pending signal completed
signal.handle - Signal handler being invoked
signal.handle.return - Signal handler invocation completed
signal.do_action - Examining or changing a signal action
signal.do_action.return - Examining or changing a signal action completed
signal.procmask - Examining or changing blocked signals
signal.flush - Flushing all pending signals for a task
14. Directory-entry (dentry) Tapset
d_name - get the dirent name
reverse_path_walk - get the full dirent path
d_path - get the full nameidata path
15. Logging Tapset
log - Send a line to the common trace buffer.
warn - Send a line to the warning stream.
exit - Start shutting down probing script.
error - Send an error message.
ftrace - Send a message to the ftrace ring-buffer (or else printk).
16. Random functions Tapset
randint - Return a random number between [0,n)
17. String and data retrieving functions Tapset
kernel_string - Retrieves string from kernel memory.
kernel_string_n - Retrieves string of given length from kernel memory.
kernel_long - Retrieves a long value stored in kernel memory.
kernel_int - Retrieves an int value stored in kernel memory.
kernel_short - Retrieves a short value stored in kernel memory.
kernel_char - Retrieves a char value stored in kernel memory.
user_string - Retrieves string from user space.
user_string2 - Retrieves string from user space with alternative error string..
user_string_warn - Retrieves string from user space.
user_string_quoted - Retrieves and quotes string from user space.
user_string_n - Retrieves string of given length from user space.
user_string_n2 - Retrieves string of given length from user space.
user_string_n_warn - Retrieves string from user space.
user_string_n_quoted - Retrieves and quotes string from user space.
user_short - Retrieves a short value stored in user space.
user_short_warn - Retrieves a short value stored in user space.
user_int - Retrieves an int value stored in user space.
user_int_warn - Retrieves an int value stored in user space.
user_long - Retrieves a long value stored in user space.
user_long_warn - Retrieves a long value stored in user space.
user_char - Retrieves a char value stored in user space.
user_char_warn - Retrieves a char value stored in user space.
18. A collection of standard string functions
strlen - Returns the length of a string.
substr - Returns a substring.
stringat - Returns the char at a given position in the string.
isinstr - Returns whether a string is a substring of another string.
text_str - Escape any non-printable chars in a string.
text_strn - Escape any non-printable chars in a string.
tokenize - Return the next non-empty token in a string.
str_replace - str_replace Replaces all instances of a substring with another.
strtol - strtol - Convert a string to a long.
19. Utility functions for using ansi control chars in logs
ansi_clear_screen - Move cursor to top left and clear screen.
ansi_set_color - Set the ansi Select Graphic Rendition mode.
ansi_set_color2 - Set the ansi Select Graphic Rendition mode.
ansi_set_color3 - Set the ansi Select Graphic Rendition mode.
ansi_reset_color - Resets Select Graphic Rendition mode.
ansi_new_line - Move cursor to new line.
ansi_cursor_move - Move cursor to new coordinates.
ansi_cursor_hide - Hides the cursor.
ansi_cursor_save - Saves the cursor position.
ansi_cursor_restore - Restores a previously saved cursor position.
ansi_cursor_show - Shows the cursor.