Product SiteDocumentation Site

Red Hat Enterprise Linux 5

SystemTap Tapset Reference

For SystemTap in Red Hat Enterprise Linux 5

Edition 1

Logo

Red Hat Enterprise Linux Documentation

William Cohen

Engineering Services and Operations Performance Tools

Don Domingo

Engineering Services and Operations Content Services

Legal Notice

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.
Abstract
The Tapset Reference Guide describes the most common tapset definitions users can apply to SystemTap scripts. All included tapsets documented in this guide are current as of the latest upstream version of SystemTap.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. We Need Feedback!
1. Introduction
1.1. Documentation Goals
2. Tapset Development Guidelines
2.1. Writing Good Tapsets
2.2. Elements of a Tapset
2.2.1. Tapset Files
2.2.2. Namespace
2.2.3. Comments and Documentation
3. 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.
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 — Determines if probe point is a return probe.
target — Return the process ID of the target 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
caller — Return name and address of calling function
caller_addr — Return caller address
print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL!
ubacktrace — Hex backtrace of current task stack. EXPERIMENTAL!
4. Timestamp Functions
get_cycles — Processor cycle count.
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.
6. IO Scheduler 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 — A request was added to the request queue
ioscheduler.elv_completed_request — Fires when a request is completed
7. 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
8. Networking Tapset
netdev.receive — Data recieved from network device.
netdev.transmit — Network device transmitting buffer
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
9. 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.
10. 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
11. 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 — Flusing all pending signals for a task
A. Revision History