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.