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.

function::print_regs - Print a register dump.
function::execname - Returns the execname of a target process (or group of processes).
function::pid - Returns the ID of a target process.
function::tid - Returns the thread ID of a target process.
function::ppid - Returns the process ID of a target process's parent process.
function::pgrp - Returns the process group ID of the current process.
function::sid - Returns the session ID of the current process.
function::pexecname - Returns the execname of a target process's parent process.
function::gid - Returns the group ID of a target process.
function::egid - Returns the effective gid of a target process.
function::uid - Returns the user ID of a target process.
function::euid - Return the effective uid of a target process.
function::is_myproc - Determines if the current probe point has occurred in the user's own process.
function::cpu - Returns the current cpu number.
function::pp - Returns the active probe point.
function::registers_valid - Determines validity of register and u_register in current context.
function::user_mode - Determines if probe point occurs in user-mode.
function::is_return - Whether the current probe context is a return probe.
function::target - Return the process ID of the target process.
function::module_name - The module name of the current script.
function::stp_pid - The process id of the stapio process.
function::stack_size - Return the size of the kernel stack.
function::stack_used - Returns the amount of kernel stack used.
function::stack_unused - Returns the amount of kernel stack currently available.
function::uaddr - User space address of current running task. EXPERIMENTAL.
function::cmdline_args - Fetch command line arguments from current process
function::cmdline_arg - Fetch a command line argument.
function::cmdline_str - Fetch all command line arguments from current process
function::env_var - Fetch environment variable from current process
function::print_stack - Print out kernel stack from string.
function::sprint_stack - Return stack for kernel addresses from string. EXPERIMENTAL!
function::probefunc - Return the probe point's function name, if known.
function::probemod - Return the probe point's kernel module name.
function::modname - Return the kernel module name loaded at the address.
function::symname - Return the kernel symbol associated with the given address.
function::symdata - Return the kernel symbol and module offset for the address.
function::usymname - Return the symbol of an address in the current task. EXPERIMENTAL!
function::usymdata - Return the symbol and module offset of an address. EXPERIMENTAL!
function::print_ustack - Print out stack for the current task from string. EXPERIMENTAL!
function::sprint_ustack - Return stack for the current task from string. EXPERIMENTAL!
function::print_backtrace - Print stack back trace
function::sprint_backtrace - Return stack back trace as string. EXPERIMENTAL!
function::backtrace - Hex backtrace of current stack
function::task_backtrace - Hex backtrace of an arbitrary task
function::caller - Return name and address of calling function
function::caller_addr - Return caller address
function::print_ubacktrace - Print stack back trace for current task. EXPERIMENTAL!
function::sprint_ubacktrace - Return stack back trace for current task as string. EXPERIMENTAL!
function::print_ubacktrace_brief - Print stack back trace for current task. EXPERIMENTAL!
function::ubacktrace - Hex backtrace of current task stack. EXPERIMENTAL!
function::task_current - The current task_struct of the current task.
function::task_parent - The task_struct of the parent task.
function::task_state - The state of the task.
function::task_execname - The name of the task.
function::task_pid - The process identifier of the task.
function::pid2task - The task_struct of the given process identifier.
function::pid2execname - The name of the given process identifier.
function::task_tid - The thread identifier of the task.
function::task_gid - The group identifier of the task.
function::task_egid - The effective group identifier of the task.
function::task_uid - The user identifier of the task.
function::task_euid - The effective user identifier of the task.
function::task_prio - The priority value of the task.
function::task_nice - The nice value of the task.
function::task_cpu - The scheduled cpu of the task.
function::task_open_file_handles - The number of open files of the task.
function::task_max_file_handles - The max number of open files for the task.
function::pn - Returns the active probe name.

function::get_cycles - Processor cycle count.
function::gettimeofday_ns - Number of nanoseconds since UNIX epoch.
function::gettimeofday_us - Number of microseconds since UNIX epoch.
function::gettimeofday_ms - Number of milliseconds since UNIX epoch.
function::gettimeofday_s - Number of seconds since UNIX epoch.

5. Time string utility function

function::ctime - Convert seconds since epoch into human readable date/time string.

6. Memory Tapset

function::vm_fault_contains - Test return value for page fault reason
probe::vm.pagefault - Records that a page fault occurred.
probe::vm.pagefault.return - Indicates what type of fault occurred.
function::addr_to_node - Returns which node a given address belongs to within a NUMA system.
probe::vm.write_shared - Attempts at writing to a shared page.
probe::vm.write_shared_copy - Page copy for shared page write.
probe::vm.mmap - Fires when an mmap is requested.
probe::vm.munmap - Fires when an munmap is requested.
probe::vm.brk - Fires when a brk is requested (i.e. the heap will be resized).
probe::vm.oom_kill - Fires when a thread is selected for termination by the OOM killer.
probe::vm.kmalloc - Fires when kmalloc is requested.
probe::vm.kmem_cache_alloc - Fires when \
probe::vm.kmalloc_node - Fires when kmalloc_node is requested.
probe::vm.kmem_cache_alloc_node - Fires when \
probe::vm.kfree - Fires when kfree is requested.
probe::vm.kmem_cache_free - Fires when \
function::proc_mem_size - Total program virtual memory size in pages
function::proc_mem_size_pid - Total program virtual memory size in pages
function::proc_mem_rss - Program resident set size in pages
function::proc_mem_rss_pid - Program resident set size in pages
function::proc_mem_shr - Program shared pages (from shared mappings)
function::proc_mem_shr_pid - Program shared pages (from shared mappings)
function::proc_mem_txt - Program text (code) size in pages
function::proc_mem_txt_pid - Program text (code) size in pages
function::proc_mem_data - Program data size (data + stack) in pages
function::proc_mem_data_pid - Program data size (data + stack) in pages
function::mem_page_size - Number of bytes in a page for this architecture
function::bytes_to_string - Human readable string for given bytes
function::pages_to_string - Turns pages into a human readable string
function::proc_mem_string - Human readable string of current proc memory usage
function::proc_mem_string_pid - Human readable string of process memory usage

7. Task Time Tapset

function::task_utime - User time of the current task
function::task_utime_tid - User time of the given task
function::task_stime - System time of the current task
function::task_stime_tid - System time of the given task
function::cputime_to_msecs - Translates the given cputime into milliseconds
function::msecs_to_string - Human readable string for given milliseconds
function::cputime_to_string - Human readable string for given cputime
function::task_time_string - Human readable string of task time usage
function::task_time_string_tid - Human readable string of task time usage

8. IO Scheduler and block IO Tapset

probe::ioscheduler.elv_next_request - Fires when a request is retrieved from the request queue
probe::ioscheduler.elv_next_request.return - Fires when a request retrieval issues a return signal
probe::ioscheduler.elv_completed_request - Fires when a request is completed
probe::ioscheduler.elv_add_request.kp - kprobe based probe to indicate that a request was added to the request queue
probe::ioscheduler.elv_add_request.tp - tracepoint based probe to indicate a request is added to the request queue.
probe::ioscheduler.elv_add_request - probe to indicate request is added to the request queue.
probe::ioscheduler_trace.elv_completed_request - Fires when a request is
probe::ioscheduler_trace.elv_issue_request - Fires when a request is
probe::ioscheduler_trace.elv_requeue_request - Fires when a request is
probe::ioscheduler_trace.elv_abort_request - Fires when a request is aborted.
probe::ioscheduler_trace.plug - Fires when a request queue is plugged;
probe::ioscheduler_trace.unplug_io - Fires when a request queue is unplugged;
probe::ioscheduler_trace.unplug_timer - Fires when unplug timer associated
probe::ioblock.request - Fires whenever making a generic block I/O request.
probe::ioblock.end - Fires whenever a block I/O transfer is complete.
probe::ioblock_trace.bounce - Fires whenever a buffer bounce is needed for at least one page of a block IO request.
probe::ioblock_trace.request - Fires just as a generic block I/O request is created for a bio.
probe::ioblock_trace.end - Fires whenever a block I/O transfer is complete.

9. SCSI Tapset

probe::scsi.ioentry - Prepares a SCSI mid-layer request
probe::scsi.iodispatching - SCSI mid-layer dispatched low-level SCSI command
probe::scsi.iodone - SCSI command completed by low level driver and enqueued into the done queue.
probe::scsi.iocompleted - SCSI mid-layer running the completion processing for block device I/O requests
probe::scsi.ioexecute - Create mid-layer SCSI request and wait for the result
probe::scsi.set_state - Order SCSI device state change

10. TTY Tapset

probe::tty.open - Called when a tty is opened
probe::tty.release - Called when the tty is closed
probe::tty.resize - Called when a terminal resize happens
probe::tty.ioctl - called when a ioctl is request to the tty
probe::tty.init - Called when a tty is being initalized
probe::tty.register - Called when a tty device is registred
probe::tty.unregister - Called when a tty device is being unregistered
probe::tty.poll - Called when a tty device is being polled
probe::tty.receive - called when a tty receives a message
probe::tty.write - write to the tty line
probe::tty.read - called when a tty line will be read

11. Networking Tapset

probe::netdev.receive - Data received from network device.
probe::netdev.transmit - Network device transmitting buffer
probe::netdev.change_mtu - Called when the netdev MTU is changed
probe::netdev.open - Called when the device is opened
probe::netdev.close - Called when the device is closed
probe::netdev.hard_transmit - Called when the devices is going to TX (hard)
probe::netdev.rx - Called when the device is going to receive a packet
probe::netdev.change_rx_flag - Called when the device RX flag will be changed
probe::netdev.set_promiscuity - Called when the device enters/leaves promiscuity
probe::netdev.ioctl - Called when the device suffers an IOCTL
probe::netdev.register - Called when the device is registered
probe::netdev.unregister - Called when the device is being unregistered
probe::netdev.get_stats - Called when someone asks the device statistics
probe::netdev.change_mac - Called when the netdev_name has the MAC changed
probe::tcp.sendmsg - Sending a tcp message
probe::tcp.sendmsg.return - Sending TCP message is done
probe::tcp.recvmsg - Receiving TCP message
probe::tcp.recvmsg.return - Receiving TCP message complete
probe::tcp.disconnect - TCP socket disconnection
probe::tcp.disconnect.return - TCP socket disconnection complete
probe::tcp.setsockopt - Call to setsockopt
probe::tcp.setsockopt.return - Return from setsockopt
probe::tcp.receive - Called when a TCP packet is received
probe::udp.sendmsg - Fires whenever a process sends a UDP message
probe::udp.sendmsg.return - Fires whenever an attempt to send a UDP message is completed
probe::udp.recvmsg - Fires whenever a UDP message is received
probe::udp.recvmsg.return - Fires whenever an attempt to receive a UDP message received is completed
probe::udp.disconnect - Fires when a process requests for a UDP disconnection
probe::udp.disconnect.return - UDP has been disconnected successfully
function::ip_ntop - returns a string representation from an integer IP number

12. Socket Tapset

probe::socket.send - Message sent on a socket.
probe::socket.receive - Message received on a socket.
probe::socket.sendmsg - Message is currently being sent on a socket.
probe::socket.sendmsg.return - Return from socket.sendmsg.
probe::socket.recvmsg - Message being received on socket
probe::socket.recvmsg.return - Return from Message being received on socket
probe::socket.aio_write - Message send via sock_aio_write
probe::socket.aio_write.return - Conclusion of message send via sock_aio_write
probe::socket.aio_read - Receiving message via sock_aio_read
probe::socket.aio_read.return - Conclusion of message received via sock_aio_read
probe::socket.writev - Message sent via socket_writev
probe::socket.writev.return - Conclusion of message sent via socket_writev
probe::socket.readv - Receiving a message via sock_readv
probe::socket.readv.return - Conclusion of receiving a message via sock_readv
probe::socket.create - Creation of a socket
probe::socket.create.return - Return from Creation of a socket
probe::socket.close - Close a socket
probe::socket.close.return - Return from closing a socket
function::sock_prot_num2str - Given a protocol number, return a string representation.
function::sock_prot_str2num - Given a protocol name (string), return the corresponding protocol number.
function::sock_fam_num2str - Given a protocol family number, return a string representation.
function::sock_fam_str2num - Given a protocol family name (string), return the corresponding
function::sock_state_num2str - Given a socket state number, return a string representation.
function::sock_state_str2num - Given a socket state string, return the corresponding state number.

13. Kernel Process Tapset

probe::kprocess.create - Fires whenever a new process is successfully created
probe::kprocess.start - Starting new process
probe::kprocess.exec - Attempt to exec to a new program
probe::kprocess.exec_complete - Return from exec to a new program
probe::kprocess.exit - Exit from process
probe::kprocess.release - Process released

14. Signal Tapset

probe::signal.send - Signal being sent to a process
probe::signal.send.return - Signal being sent to a process completed
probe::signal.checkperm - Check being performed on a sent signal
probe::signal.checkperm.return - Check performed on a sent signal completed
probe::signal.wakeup - Sleeping process being wakened for signal
probe::signal.check_ignored - Checking to see signal is ignored
probe::signal.check_ignored.return - Check to see signal is ignored completed
probe::signal.force_segv - Forcing send of SIGSEGV
probe::signal.force_segv.return - Forcing send of SIGSEGV complete
probe::signal.syskill - Sending kill signal to a process
probe::signal.syskill.return - Sending kill signal completed
probe::signal.sys_tkill - Sending a kill signal to a thread
probe::signal.systkill.return - Sending kill signal to a thread completed
probe::signal.sys_tgkill - Sending kill signal to a thread group
probe::signal.sys_tgkill.return - Sending kill signal to a thread group completed
probe::signal.send_sig_queue - Queuing a signal to a process
probe::signal.send_sig_queue.return - Queuing a signal to a process completed
probe::signal.pending - Examining pending signal
probe::signal.pending.return - Examination of pending signal completed
probe::signal.handle - Signal handler being invoked
probe::signal.handle.return - Signal handler invocation completed
probe::signal.do_action - Examining or changing a signal action
probe::signal.do_action.return - Examining or changing a signal action completed
probe::signal.procmask - Examining or changing blocked signals
probe::signal.procmask.return - Examining or changing blocked signals completed
probe::signal.flush - Flushing all pending signals for a task

15. Directory-entry (dentry) Tapset

function::d_name - get the dirent name
function::reverse_path_walk - get the full dirent path
function::task_dentry_path - get the full dentry path
function::d_path - get the full nameidata path

16. Logging Tapset

function::log - Send a line to the common trace buffer.
function::warn - Send a line to the warning stream.
function::exit - Start shutting down probing script.
function::error - Send an error message.
function::ftrace - Send a message to the ftrace ring-buffer.

17. Random functions Tapset

function::randint - Return a random number between [0,n)

18. String and data retrieving functions Tapset

function::kernel_string - Retrieves string from kernel memory.
function::kernel_string2 - Retrieves string from kernel memory with alternative error string.
function::kernel_string_n - Retrieves string of given length from kernel memory.
function::kernel_long - Retrieves a long value stored in kernel memory.
function::kernel_int - Retrieves an int value stored in kernel memory.
function::kernel_short - Retrieves a short value stored in kernel memory.
function::kernel_char - Retrieves a char value stored in kernel memory.
function::kernel_pointer - Retrieves a pointer value stored in kernel memory.
function::user_string - Retrieves string from user space.
function::user_string2 - Retrieves string from user space with alternative error string.
function::user_string_warn - Retrieves string from user space.
function::user_string_quoted - Retrieves and quotes string from user space.
function::user_string_n - Retrieves string of given length from user space.
function::user_string_n2 - Retrieves string of given length from user space.
function::user_string_n_warn - Retrieves string from user space.
function::user_string_n_quoted - Retrieves and quotes string from user space.
function::user_short - Retrieves a short value stored in user space.
function::user_short_warn - Retrieves a short value stored in user space.
function::user_int - Retrieves an int value stored in user space.
function::user_int_warn - Retrieves an int value stored in user space.
function::user_long - Retrieves a long value stored in user space.
function::user_long_warn - Retrieves a long value stored in user space.
function::user_char - Retrieves a char value stored in user space.
function::user_char_warn - Retrieves a char value stored in user space.

19. A collection of standard string functions

function::strlen - Returns the length of a string.
function::substr - Returns a substring.
function::stringat - Returns the char at a given position in the string.
function::isinstr - Returns whether a string is a substring of another string.
function::text_str - Escape any non-printable chars in a string.
function::text_strn - Escape any non-printable chars in a string.
function::tokenize - Return the next non-empty token in a string.
function::str_replace - str_replace Replaces all instances of a substring with another.
function::strtol - strtol - Convert a string to a long.
function::isdigit - Checks for a digit.

20. Utility functions for using ansi control chars in logs

function::ansi_clear_screen - Move cursor to top left and clear screen.
function::ansi_set_color - Set the ansi Select Graphic Rendition mode.
function::ansi_set_color2 - Set the ansi Select Graphic Rendition mode.
function::ansi_set_color3 - Set the ansi Select Graphic Rendition mode.
function::ansi_reset_color - Resets Select Graphic Rendition mode.
function::ansi_new_line - Move cursor to new line.
function::ansi_cursor_move - Move cursor to new coordinates.
function::ansi_cursor_hide - Hides the cursor.
function::ansi_cursor_save - Saves the cursor position.
function::ansi_cursor_restore - Restores a previously saved cursor position.
function::ansi_cursor_show - Shows the cursor.

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:

To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.

The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the plus sign that connects each part of a key combination. For example:

Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.

The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:

File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

Choose System ⤍ Preferences ⤍ Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications ⤍ Accessories ⤍ Character Map from the main menu bar. Next, choose Search ⤍ Find . . . . . . from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit ⤍ Paste from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh [email protected].
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.

Note the words in bold italics above - username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.

Output sent to a terminal is set in mono-spaced roman and presented thus:

books Desktop   documentation  drafts  mss photos   stuff  svnbooks_tests  Desktop1  downloads  images  notes  scripts  svgs

Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:

package org.jboss.book.jca.ex1;import javax.naming.InitialContext;public class ExClient{   public static void main(String args[]) throws Exception   {  InitialContext iniCtx = new InitialContext();  Object ref = iniCtx.lookup("EchoBean");  EchoHome   home   = (EchoHome) ref;  Echo   echo   = home.create();  System.out.println("Created Echo");  System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));   }}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Getting Help and Giving Feedback

2.1. Do You Need Help?

If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:

search or browse through a knowledgebase of technical support articles about Red Hat products.
submit a support case to Red Hat Global Support Services (GSS).
access other product documentation.

Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.

2.2. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/ against the product Red_Hat_Enterprise_Linux.

When submitting a bug report, be sure to mention the manual's identifier: doc-SystemTap_Tapset_Reference

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Chapter 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

This chapter describes the upstream guidelines on proper tapset documentation. It also contains information on how to properly document your tapsets, to ensure that they are properly defined in this guide.

2.1. Writing Good Tapsets

The first step to writing good tapsets is to create a simple model of your subject area. For example, a model of the process subsystem might include the following:

Key Data

process ID
parent process ID
process group ID

State Transitions

forked
exec'd
running
stopped
terminated

Note

Both lists are examples, and are not meant to represent a complete list.

Use your subsystem expertise to find probe points (function entries and exits) that expose the elements of the model, then define probe aliases for those points. Be aware that some state transitions can occur in more than one place. In those cases, an alias can place a probe in multiple locations.

For example, process execs can occur in either the do_execve() or the compat_do_execve() functions. The following alias inserts probes at the beginning of those functions:

probe kprocess.exec = kernel.function("do_execve"),kernel.function("compat_do_execve") {probe body}

Try to place probes on stable interfaces (i.e., functions that are unlikely to change at the interface level) whenever possible. This will make the tapset less likely to break due to kernel changes. Where kernel version or architecture dependencies are unavoidable, use preprocessor conditionals (see the stap(1) man page for details).

Fill in the probe bodies with the key data available at the probe points. Function entry probes can access the entry parameters specified to the function, while exit probes can access the entry parameters and the return value. Convert the data into meaningful forms where appropriate (e.g., bytes to kilobytes, state values to strings, etc).

You may need to use auxiliary functions to access or convert some of the data. Auxiliary functions often use embedded C to do things that cannot be done in the SystemTap language, like access structure fields in some contexts, follow linked lists, etc. You can use auxiliary functions defined in other tapsets or write your own.

In the following example, copy_process() returns a pointer to the task_struct for the new process. Note that the process ID of the new process is retrieved by calling task_pid() and passing it the task_struct pointer. In this case, the auxiliary function is an embedded C function defined in task.stp.

probe kprocess.create = kernel.function("copy_process").return {   task = $return   new_pid = task_pid(task)}

It is not advisable to write probes for every function. Most SystemTap users will not need or understand them. Keep your tapsets simple and high-level.

2.2. Elements of a Tapset

The following sections describe the most important aspects of writing a tapset. Most of the content herein is suitable for developers who wish to contribute to SystemTap's upstream library of tapsets.

2.2.1. Tapset Files

Tapset files are stored in src/tapset/ of the SystemTap GIT directory. Most tapset files are kept at that level. If you have code that only works with a specific architecture or kernel version, you may choose to put your tapset in the appropriate subdirectory.

Installed tapsets are located in /usr/share/systemtap/tapset/ or /usr/local/share/systemtap/tapset.

Personal tapsets can be stored anywhere. However, to ensure that SystemTap can use them, use -I tapset_directory to specify their location when invoking stap.

2.2.2. Namespace

Probe alias names should take the form tapset_name.probe_name. For example, the probe for sending a signal could be named signal.send.

Global symbol names (probes, functions, and variables) should be unique accross all tapsets. This helps avoid namespace collisions in scripts that use multiple tapsets. To ensure this, use tapset-specific prefixes in your global symbols.

Internal symbol names should be prefixed with an underscore (_).

2.2.3. Comments and Documentation

All probes and functions should include comment blocks that describe their purpose, the data they provide, and the context in which they run (e.g. interrupt, process, etc). Use comments in areas where your intent may not be clear from reading the code.

Note that specially-formatted comments are automatically extracted from most tapsets and included in this guide. This helps ensure that tapset contributors can write their tapset and document it in the same place. The specified format for documenting tapsets is as follows:

/** * probe tapset.name - Short summary of what the tapset does. * @argument: Explanation of argument. * @argument2: Explanation of argument2. Probes can have multiple arguments. * * Context: * A brief explanation of the tapset context.  * Note that the context should only be 1 paragraph short. * * Text that will appear under "Description." * * A new paragraph that will also appear under the heading "Description". * * Header: * A paragraph that will appear under the heading "Header". **/

For example:

/** * probe vm.write_shared_copy- Page copy for shared page write. * @address: The address of the shared write. * @zero: Boolean indicating whether it is a zero page * (can do a clear instead of a copy). * * Context: *  The process attempting the write. * *  Fires when a write to a shared page requires a page copy.  This is *  always preceded by a vm.shared_write. **/

To override the automatically-generated Synopsis content, use:

 * Synopsis: * New Synopsis string *

For example:

/** * probe signal.handle - Fires when the signal handler is invoked * @sig: The signal number that invoked the signal handler * * Synopsis: * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka, * sigset_t *oldset, struct pt_regs * regs)</programlisting> */

It is recommended that you use the <programlisting> tag in this instance, since overriding the Synopsis content of an entry does not automatically form the necessary tags.

For the purposes of improving the DocBook XML output of your comments, you can also use the following XML tags in your comments:

command
emphasis
programlisting
remark (tagged strings will appear in Publican beta builds of the document)

SystemTap Tapset Reference

For SystemTap in Red Hat Enterprise Linux 6

Red Hat Enterprise Linux Documentation

William Cohen

Don Domingo

Legal Notice

Daftar Isi

Preface

1. Document Conventions

1.1. Typographic Conventions

1.2. Pull-quote Conventions

1.3. Notes and Warnings

Note

Important

Warning

2. Getting Help and Giving Feedback

2.1. Do You Need Help?

2.2. We Need Feedback!

Chapter 1. Introduction

1.1. Documentation Goals

Chapter 2. Tapset Development Guidelines

2.1. Writing Good Tapsets

Key Data

State Transitions

Note

2.2. Elements of a Tapset

2.2.1. Tapset Files

2.2.2. Namespace

2.2.3. Comments and Documentation