SystemTap Tapset Reference - linux. · PDF fileSystemTap Tapset Reference Red Hat Enterprise Linux 6 SystemTap Tapset Reference For SystemTap in Red Hat Enterprise Linux 6 Edition

Red Hat Enterprise Linux 6

SystemTapTapset Reference

For SystemTap in Red Hat Enterprise Linux 6

William Cohen

Don Domingo

SystemTap Tapset Reference

Red Hat Enterprise Linux 6 SystemTap Tapset ReferenceFor SystemTap in Red Hat Enterprise Linux 6Edition 0

Author William Cohen [email protected] Don Domingo [email protected]

This documentation is free software; you can redistribute it and/or modify it under the terms of theGNU 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; withouteven the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Seethe 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.

The Tapset Reference Guide describes the most common tapset definitions users can apply toSystemTap scripts. All included tapsets documented in this guide are current as of the latest upstreamversion of SystemTap.

mailto:[email protected]

mailto:[email protected]

iii

Preface xi1. Document Conventions ................................................................................................... xi

1.1. Typographic Conventions ..................................................................................... xi1.2. Pull-quote Conventions ........................................................................................ xii1.3. Notes and Warnings ........................................................................................... xiii

2. Getting Help and Giving Feedback ................................................................................ xiii2.1. Do You Need Help? ........................................................................................... xiii2.2. We Need Feedback! .......................................................................................... xiv

1. Introduction 11.1. Documentation Goals ................................................................................................... 1

2. Tapset Development Guidelines 32.1. Writing Good Tapsets ................................................................................................... 32.2. Elements of a Tapset ................................................................................................... 4

2.2.1. Tapset Files ...................................................................................................... 42.2.2. Namespace ....................................................................................................... 42.2.3. Comments and Documentation .......................................................................... 4

3. Context Functions 7function::print_regs .............................................................................................................. 7function::execname ............................................................................................................. 7function::pid ........................................................................................................................ 7function::tid ......................................................................................................................... 8function::ppid ...................................................................................................................... 8function::pgrp ...................................................................................................................... 9function::sid ........................................................................................................................ 9function::pexecname ............................................................................................................ 9function::gid ...................................................................................................................... 10function::egid ..................................................................................................................... 10function::uid ...................................................................................................................... 11function::euid ..................................................................................................................... 11function::is_myproc ............................................................................................................ 11function::cpu ..................................................................................................................... 12function::pp ....................................................................................................................... 12function::registers_valid ..................................................................................................... 13function::user_mode .......................................................................................................... 13function::is_return .............................................................................................................. 13function::target .................................................................................................................. 14function::module_name ...................................................................................................... 14function::stp_pid ................................................................................................................ 15function::stack_size ........................................................................................................... 15function::stack_used .......................................................................................................... 16function::stack_unused ...................................................................................................... 16function::uaddr .................................................................................................................. 16function::cmdline_args ....................................................................................................... 17function::cmdline_arg ......................................................................................................... 17function::cmdline_str .......................................................................................................... 18function::env_var ............................................................................................................... 18function::print_stack ........................................................................................................... 19function::sprint_stack ......................................................................................................... 19function::probefunc ............................................................................................................ 20function::probemod ............................................................................................................ 20function::modname ............................................................................................................ 21function::symname ............................................................................................................ 21


iv

function::symdata .............................................................................................................. 21function::usymname ........................................................................................................... 22function::usymdata ............................................................................................................ 22function::print_ustack ......................................................................................................... 23function::sprint_ustack ....................................................................................................... 23function::print_backtrace .................................................................................................... 24function::sprint_backtrace .................................................................................................. 24function::backtrace ............................................................................................................ 24function::task_backtrace ..................................................................................................... 25function::caller ................................................................................................................... 25function::caller_addr .......................................................................................................... 26function::print_ubacktrace .................................................................................................. 26function::sprint_ubacktrace ................................................................................................. 27function::print_ubacktrace_brief .......................................................................................... 27function::ubacktrace ........................................................................................................... 28function::task_current ......................................................................................................... 28function::task_parent ......................................................................................................... 29function::task_state ............................................................................................................ 29function::task_execname .................................................................................................... 29function::task_pid .............................................................................................................. 30function::pid2task .............................................................................................................. 30function::pid2execname ..................................................................................................... 31function::task_tid ............................................................................................................... 31function::task_gid .............................................................................................................. 31function::task_egid ............................................................................................................. 32function::task_uid .............................................................................................................. 32function::task_euid ............................................................................................................. 33function::task_prio ............................................................................................................. 33function::task_nice ............................................................................................................. 34function::task_cpu .............................................................................................................. 34function::task_open_file_handles ........................................................................................ 34function::task_max_file_handles ......................................................................................... 35function::pn ....................................................................................................................... 35

4. Timestamp Functions 37function::get_cycles ........................................................................................................... 37function::gettimeofday_ns .................................................................................................. 37function::gettimeofday_us .................................................................................................. 38function::gettimeofday_ms .................................................................................................. 38function::gettimeofday_s .................................................................................................... 38

5. Time string utility function 41function::ctime ................................................................................................................... 41

6. Memory Tapset 43function::vm_fault_contains ................................................................................................ 43probe::vm.pagefault ........................................................................................................... 43probe::vm.pagefault.return ................................................................................................. 43function::addr_to_node ...................................................................................................... 44probe::vm.write_shared ...................................................................................................... 44probe::vm.write_shared_copy ............................................................................................. 45probe::vm.mmap ............................................................................................................... 45probe::vm.munmap ............................................................................................................ 46probe::vm.brk .................................................................................................................... 46probe::vm.oom_kill ............................................................................................................ 47

v

probe::vm.kmalloc ............................................................................................................. 47probe::vm.kmem_cache_alloc ............................................................................................ 48probe::vm.kmalloc_node .................................................................................................... 48probe::vm.kmem_cache_alloc_node ................................................................................... 49probe::vm.kfree ................................................................................................................. 50probe::vm.kmem_cache_free ............................................................................................. 50function::proc_mem_size ................................................................................................... 51function::proc_mem_size_pid ............................................................................................. 51function::proc_mem_rss ..................................................................................................... 51function::proc_mem_rss_pid ............................................................................................... 52function::proc_mem_shr ..................................................................................................... 52function::proc_mem_shr_pid .............................................................................................. 53function::proc_mem_txt ...................................................................................................... 53function::proc_mem_txt_pid ................................................................................................ 53function::proc_mem_data ................................................................................................... 54function::proc_mem_data_pid ............................................................................................. 54function::mem_page_size .................................................................................................. 54function::bytes_to_string .................................................................................................... 55function::pages_to_string ................................................................................................... 55function::proc_mem_string ................................................................................................. 55function::proc_mem_string_pid ........................................................................................... 56

7. Task Time Tapset 57function::task_utime ........................................................................................................... 57function::task_utime_tid ..................................................................................................... 57function::task_stime ........................................................................................................... 57function::task_stime_tid ...................................................................................................... 58function::cputime_to_msecs ............................................................................................... 58function::msecs_to_string ................................................................................................... 58function::cputime_to_string ................................................................................................. 59function::task_time_string ................................................................................................... 59function::task_time_string_tid ............................................................................................. 59

8. IO Scheduler and block IO Tapset 61probe::ioscheduler.elv_next_request ................................................................................... 61probe::ioscheduler.elv_next_request.return ......................................................................... 61probe::ioscheduler.elv_completed_request .......................................................................... 61probe::ioscheduler.elv_add_request.kp ............................................................................... 62probe::ioscheduler.elv_add_request.tp ................................................................................ 63probe::ioscheduler.elv_add_request .................................................................................... 63probe::ioscheduler_trace.elv_completed_request ................................................................. 64probe::ioscheduler_trace.elv_issue_request ........................................................................ 64probe::ioscheduler_trace.elv_requeue_request .................................................................... 65probe::ioscheduler_trace.elv_abort_request ........................................................................ 66probe::ioscheduler_trace.plug ............................................................................................. 66probe::ioscheduler_trace.unplug_io ..................................................................................... 67probe::ioscheduler_trace.unplug_timer ................................................................................ 67probe::ioblock.request ........................................................................................................ 67probe::ioblock.end ............................................................................................................. 68probe::ioblock_trace.bounce ............................................................................................... 69probe::ioblock_trace.request .............................................................................................. 69probe::ioblock_trace.end .................................................................................................... 70

9. SCSI Tapset 71probe::scsi.ioentry ............................................................................................................. 71


vi

probe::scsi.iodispatching .................................................................................................... 71probe::scsi.iodone ............................................................................................................. 72probe::scsi.iocompleted ..................................................................................................... 73probe::scsi.ioexecute ......................................................................................................... 73probe::scsi.set_state .......................................................................................................... 74

10. TTY Tapset 77probe::tty.open .................................................................................................................. 77probe::tty.release ............................................................................................................... 77probe::tty.resize ................................................................................................................. 78probe::tty.ioctl .................................................................................................................... 78probe::tty.init ...................................................................................................................... 79probe::tty.register ............................................................................................................... 79probe::tty.unregister ........................................................................................................... 80probe::tty.poll ..................................................................................................................... 80probe::tty.receive ............................................................................................................... 80probe::tty.write ................................................................................................................... 81probe::tty.read ................................................................................................................... 81

11. Networking Tapset 83probe::netdev.receive ......................................................................................................... 83probe::netdev.transmit ........................................................................................................ 83probe::netdev.change_mtu ................................................................................................. 83probe::netdev.open ............................................................................................................ 84probe::netdev.close ............................................................................................................ 84probe::netdev.hard_transmit ............................................................................................... 84probe::netdev.rx ................................................................................................................. 85probe::netdev.change_rx_flag ............................................................................................. 85probe::netdev.set_promiscuity ............................................................................................ 85probe::netdev.ioctl ............................................................................................................. 86probe::netdev.register ........................................................................................................ 86probe::netdev.unregister ..................................................................................................... 87probe::netdev.get_stats ...................................................................................................... 87probe::netdev.change_mac ................................................................................................ 87probe::tcp.sendmsg ........................................................................................................... 88probe::tcp.sendmsg.return .................................................................................................. 88probe::tcp.recvmsg ............................................................................................................ 88probe::tcp.recvmsg.return ................................................................................................... 89probe::tcp.disconnect ......................................................................................................... 90probe::tcp.disconnect.return ............................................................................................... 90probe::tcp.setsockopt ......................................................................................................... 91probe::tcp.setsockopt.return ............................................................................................... 91probe::tcp.receive .............................................................................................................. 92probe::udp.sendmsg .......................................................................................................... 93probe::udp.sendmsg.return ................................................................................................ 93probe::udp.recvmsg ........................................................................................................... 94probe::udp.recvmsg.return ................................................................................................. 94probe::udp.disconnect ........................................................................................................ 94probe::udp.disconnect.return .............................................................................................. 95function::ip_ntop ................................................................................................................ 95

12. Socket Tapset 97probe::socket.send ............................................................................................................ 97probe::socket.receive ......................................................................................................... 97probe::socket.sendmsg ...................................................................................................... 98

vii

probe::socket.sendmsg.return ............................................................................................ 99probe::socket.recvmsg ..................................................................................................... 100probe::socket.recvmsg.return ............................................................................................ 100probe::socket.aio_write .................................................................................................... 101probe::socket.aio_write.return ........................................................................................... 102probe::socket.aio_read ..................................................................................................... 103probe::socket.aio_read.return ........................................................................................... 103probe::socket.writev ......................................................................................................... 104probe::socket.writev.return ................................................................................................ 105probe::socket.readv ......................................................................................................... 106probe::socket.readv.return ................................................................................................ 107probe::socket.create ........................................................................................................ 107probe::socket.create.return ............................................................................................... 108probe::socket.close .......................................................................................................... 109probe::socket.close.return ................................................................................................ 109function::sock_prot_num2str ............................................................................................. 110function::sock_prot_str2num ............................................................................................. 110function::sock_fam_num2str ............................................................................................. 110function::sock_fam_str2num ............................................................................................. 111function::sock_state_num2str ........................................................................................... 111function::sock_state_str2num ........................................................................................... 111

13. Kernel Process Tapset 113probe::kprocess.create ..................................................................................................... 113probe::kprocess.start ....................................................................................................... 113probe::kprocess.exec ....................................................................................................... 113probe::kprocess.exec_complete ........................................................................................ 114probe::kprocess.exit ......................................................................................................... 114probe::kprocess.release ................................................................................................... 115

14. Signal Tapset 117probe::signal.send ........................................................................................................... 117probe::signal.send.return .................................................................................................. 117probe::signal.checkperm .................................................................................................. 118probe::signal.checkperm.return ......................................................................................... 119probe::signal.wakeup ....................................................................................................... 119probe::signal.check_ignored ............................................................................................. 120probe::signal.check_ignored.return ................................................................................... 120probe::signal.force_segv .................................................................................................. 121probe::signal.force_segv.return ......................................................................................... 121probe::signal.syskill .......................................................................................................... 121probe::signal.syskill.return ................................................................................................ 122probe::signal.sys_tkill ....................................................................................................... 122probe::signal.systkill.return ............................................................................................... 123probe::signal.sys_tgkill ..................................................................................................... 123probe::signal.sys_tgkill.return ............................................................................................ 124probe::signal.send_sig_queue .......................................................................................... 124probe::signal.send_sig_queue.return ................................................................................. 124probe::signal.pending ....................................................................................................... 125probe::signal.pending.return ............................................................................................. 125probe::signal.handle ......................................................................................................... 126probe::signal.handle.return ............................................................................................... 126probe::signal.do_action .................................................................................................... 127probe::signal.do_action.return ........................................................................................... 127probe::signal.procmask .................................................................................................... 128


viii

probe::signal.procmask.return ........................................................................................... 128probe::signal.flush ............................................................................................................ 128

15. Directory-entry (dentry) Tapset 131function::d_name ............................................................................................................. 131function::reverse_path_walk ............................................................................................. 131function::task_dentry_path ................................................................................................ 131function::d_path ............................................................................................................... 132

16. Logging Tapset 133function::log ..................................................................................................................... 133function::warn .................................................................................................................. 133function::exit .................................................................................................................... 134function::error .................................................................................................................. 134function::ftrace ................................................................................................................. 134

17. Random functions Tapset 137function::randint ............................................................................................................... 137

18. String and data retrieving functions Tapset 139function::kernel_string ...................................................................................................... 139function::kernel_string2 .................................................................................................... 139function::kernel_string_n .................................................................................................. 140function::kernel_long ........................................................................................................ 140function::kernel_int ........................................................................................................... 141function::kernel_short ....................................................................................................... 141function::kernel_char ........................................................................................................ 141function::kernel_pointer .................................................................................................... 142function::user_string ......................................................................................................... 142function::user_string2 ....................................................................................................... 143function::user_string_warn ................................................................................................ 143function::user_string_quoted ............................................................................................. 144function::user_string_n ..................................................................................................... 144function::user_string_n2 ................................................................................................... 145function::user_string_n_warn ............................................................................................ 145function::user_string_n_quoted ......................................................................................... 146function::user_short ......................................................................................................... 146function::user_short_warn ................................................................................................ 147function::user_int ............................................................................................................. 147function::user_int_warn .................................................................................................... 148function::user_long .......................................................................................................... 148function::user_long_warn ................................................................................................. 149function::user_char .......................................................................................................... 149function::user_char_warn ................................................................................................. 149

19. A collection of standard string functions 151function::strlen ................................................................................................................. 151function::substr ................................................................................................................ 151function::stringat .............................................................................................................. 152function::isinstr ................................................................................................................ 152function::text_str .............................................................................................................. 153function::text_strn ............................................................................................................ 153function::tokenize ............................................................................................................. 154function::str_replace ......................................................................................................... 154function::strtol .................................................................................................................. 155function::isdigit ................................................................................................................ 155

ix

20. Utility functions for using ansi control chars in logs 157function::ansi_clear_screen .............................................................................................. 157function::ansi_set_color .................................................................................................... 157function::ansi_set_color2 .................................................................................................. 158function::ansi_set_color3 .................................................................................................. 158function::ansi_reset_color ................................................................................................. 159function::ansi_new_line .................................................................................................... 159function::ansi_cursor_move .............................................................................................. 159function::ansi_cursor_hide ................................................................................................ 160function::ansi_cursor_save ............................................................................................... 160function::ansi_cursor_restore ............................................................................................ 161function::ansi_cursor_show .............................................................................................. 161

x

xi

Preface

1. Document ConventionsThis manual uses several conventions to highlight certain words and phrases and draw attention tospecific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts1 set. TheLiberation 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 includesthe Liberation Fonts set by default.

1.1. Typographic ConventionsFour typographic conventions are used to call attention to specific words and phrases. Theseconventions, 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 highlightkeycaps and key combinations. For example:

To see the contents of the file my_next_bestselling_novel in your currentworking directory, enter the cat my_next_bestselling_novel command at theshell 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 boldand all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the hyphen connecting each part of a keycombination. For example:

Press Enter to execute the command.

Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 toreturn to your X-Windows session.

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

If source code is discussed, class names, methods, functions, variable names and returned valuesmentioned 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 fordirectories. 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 MousePreferences. In the Buttons tab, click the Left-handed mouse check box and click

1 https://fedorahosted.org/liberation-fonts/

https://fedorahosted.org/liberation-fonts/

https://fedorahosted.org/liberation-fonts/

Preface

xii

Close to switch the primary mouse button from the left to the right (making the mousesuitable 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 theCharacter Map menu bar, type the name of the character in the Search field and clickNext. 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 thegedit menu bar.

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

Mono-spaced Bold Italic or Proportional Bold Italic

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

To connect to a remote machine using ssh, type ssh [email protected] ata shell prompt. If the remote machine is example.com and your username on thatmachine is john, type ssh [email protected].

The mount -o remount file-system command remounts the named filesystem. For example, to remount the /home file system, the command is mount -oremount /home.

To see the version of a currently installed package, use the rpm -q packagecommand. It will return a result as follows: package-version-release.

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

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

Publican is a DocBook publishing system.

1.2. Pull-quote ConventionsTerminal 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;

Notes and Warnings

xiii

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 WarningsFinally, 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 shouldhave 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 tothe current session, or services that need restarting before an update will apply. Ignoring a boxlabeled '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 HatCustomer 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 andtechnology. 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.

http://access.redhat.com

https://www.redhat.com/mailman/listinfo

https://www.redhat.com/mailman/listinfo

Preface

xiv

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 manualbetter, 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 whendescribing it. If you have found an error, please include the section number and some of thesurrounding text so we can find it easily.

http://bugzilla.redhat.com/

Chapter 1.

1

IntroductionSystemTap provides free software (GPL) infrastructure to simplify the gathering of information aboutthe running Linux system. This assists diagnosis of a performance or functional problem. SystemTapeliminates the need for the developer to go through the tedious and disruptive instrument, recompile,install, and reboot sequence that may be otherwise required to collect data.

SystemTap provides a simple command line interface and scripting language for writinginstrumentation for a live, running kernel. This instrumentation uses probe points and functionsprovided in the tapset library.

Simply put, tapsets are scripts that encapsulate knowledge about a kernel subsystem into pre-writtenprobes and functions that can be used by other scripts. Tapsets are analogous to libraries for Cprograms. They hide the underlying details of a kernel area while exposing the key information neededto manage and monitor that aspect of the kernel. They are typically developed by kernel subject-matter experts.

A tapset exposes the high-level data and state transitions of a subsystem. For the most part, goodtapset developers assume that SystemTap users know little to nothing about the kernel subsystem'slow-level details. As such, tapset developers write tapsets that help ordinary SystemTap users writemeaningful and useful SystemTap scripts.

1.1. Documentation GoalsThis guide aims to document SystemTap's most useful and common tapset entries; it also containsguidelines on proper tapset development and documentation. The tapset definitions contained in thisguide are extracted automatically from properly-formatted comments in the code of each tapset file. Assuch, any revisions to the definitions in this guide should be applied directly to their respective tapsetfile.

2

Chapter 2.

3

Tapset Development GuidelinesThis chapter describes the upstream guidelines on proper tapset documentation. It also containsinformation on how to properly document your tapsets, to ensure that they are properly defined in thisguide.

2.1. Writing Good TapsetsThe first step to writing good tapsets is to create a simple model of your subject area. For example, amodel 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 theelements of the model, then define probe aliases for those points. Be aware that some statetransitions can occur in more than one place. In those cases, an alias can place a probe in multiplelocations.

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 interfacelevel) whenever possible. This will make the tapset less likely to break due to kernel changes. Wherekernel version or architecture dependencies are unavoidable, use preprocessor conditionals (see thestap(1) man page for details).

Fill in the probe bodies with the key data available at the probe points. Function entry probescan access the entry parameters specified to the function, while exit probes can access the entry

Chapter 2. Tapset Development Guidelines

4

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 functionsoften use embedded C to do things that cannot be done in the SystemTap language, like accessstructure fields in some contexts, follow linked lists, etc. You can use auxiliary functions defined inother tapsets or write your own.

In the following example, copy_process() returns a pointer to the task_struct for the newprocess. Note that the process ID of the new process is retrieved by calling task_pid() and passingit the task_struct pointer. In this case, the auxiliary function is an embedded C function defined intask.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 orunderstand them. Keep your tapsets simple and high-level.

2.2. Elements of a TapsetThe following sections describe the most important aspects of writing a tapset. Most of the contentherein is suitable for developers who wish to contribute to SystemTap's upstream library of tapsets.

2.2.1. Tapset FilesTapset files are stored in src/tapset/ of the SystemTap GIT directory. Most tapset files are keptat that level. If you have code that only works with a specific architecture or kernel version, you maychoose 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 -Itapset_directory to specify their location when invoking stap.

2.2.2. NamespaceProbe alias names should take the form tapset_name.probe_name. For example, the probe forsending a signal could be named signal.send.

Global symbol names (probes, functions, and variables) should be unique accross all tapsets. Thishelps 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 DocumentationAll probes and functions should include comment blocks that describe their purpose, the data theyprovide, and the context in which they run (e.g. interrupt, process, etc). Use comments in areas whereyour intent may not be clear from reading the code.

Comments and Documentation

5

Note that specially-formatted comments are automatically extracted from most tapsets and includedin this guide. This helps ensure that tapset contributors can write their tapset and document it in thesame 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 theSynopsis content of an entry does not automatically form the necessary tags.

Chapter 2. Tapset Development Guidelines

6

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

• command

• emphasis

• programlisting

• remark (tagged strings will appear in Publican beta builds of the document)

Chapter 3.

7

Context FunctionsThe context functions provide additional information about where an event occurred. These functionscan provide information such as a backtrace to where the event occurred and the current registervalues for the processor.

Namefunction::print_regs — Print a register dump.

Synopsis

function print_regs()

ArgumentsNone

General Syntaxprint_regs

DescriptionThis function prints a register dump.

Namefunction::execname — Returns the execname of a target process (or group of processes).

Synopsis

function execname:string()

ArgumentsNone

General Syntaxexecname:string

DescriptionReturns the execname of a target process (or group of processes).

Namefunction::pid — Returns the ID of a target process.

Chapter 3. Context Functions

8

Synopsis

function pid:long()

ArgumentsNone

General Syntaxpid:long

DescriptionThis function returns the ID of a targer process.

Namefunction::tid — Returns the thread ID of a target process.

Synopsis

function tid:long()

ArgumentsNone

General Syntaxtid:long

DescriptionThis function returns the thread ID of the target process.

Namefunction::ppid — Returns the process ID of a target process's parent process.

Synopsis

function ppid:long()

ArgumentsNone

9

General Syntaxppid:long

DescriptionThis function return the process ID of the target proccess's parent process.

Namefunction::pgrp — Returns the process group ID of the current process.

Synopsis

function pgrp:long()

ArgumentsNone

General Syntaxpgrp:long

DescriptionThis function returns the process group ID of the current process.

Namefunction::sid — Returns the session ID of the current process.

Synopsis

function sid:long()

ArgumentsNone

General Syntaxsid:long

DescriptionThe session ID of a process is the process group ID of the session leader. Session ID is stored in thesignal_struct since Kernel 2.6.0.

Namefunction::pexecname — Returns the execname of a target process's parent process.


10

Synopsis

function pexecname:string()

ArgumentsNone

General Syntaxpexecname:string

DescriptionThis function returns the execname of a target process's parent procces.

Namefunction::gid — Returns the group ID of a target process.

Synopsis

function gid:long()

ArgumentsNone

General Syntaxgid:long

DescriptionThis function returns the group ID of a target process.

Namefunction::egid — Returns the effective gid of a target process.

Synopsis

function egid:long()

ArgumentsNone

11

General Syntaxegid:long

DescriptionThis function returns the effective gid of a target process

Namefunction::uid — Returns the user ID of a target process.

Synopsis

function uid:long()

ArgumentsNone

General Syntaxuid:long

DescriptionThis function returns the user ID of the target process.

Namefunction::euid — Return the effective uid of a target process.

Synopsis

function euid:long()

ArgumentsNone

General Syntaxeuid:long

DescriptionReturns the effective user ID of the target process.

Namefunction::is_myproc — Determines if the current probe point has occurred in the user's own process.


12

Synopsis

function is_myproc:long()

ArgumentsNone

General Syntaxis_myproc:long

DescriptionThis function returns 1 if the current probe point has occurred in the user's own process.

Namefunction::cpu — Returns the current cpu number.

Synopsis

function cpu:long()

ArgumentsNone

General Syntaxcpu:long

DescriptionThis function returns the current cpu number.

Namefunction::pp — Returns the active probe point.

Synopsis

function pp:string()

ArgumentsNone

13

General Syntaxpp:string

DescriptionThis function returns the fully-resolved probe point associated with a currently running probe handler,including alias and wild-card expansion effects. Context: The current probe point.

Namefunction::registers_valid — Determines validity of register and u_register in current context.

Synopsis

function registers_valid:long()

ArgumentsNone

General Syntaxregisters_valid:long

DescriptionThis function returns 1 if register and u_register can be used in the current context, or 0otherwise. For example, registers_valid returns 0 when called from a begin or end probe.

Namefunction::user_mode — Determines if probe point occurs in user-mode.

Synopsis

function user_mode:long()

ArgumentsNone

General Syntaxuser_mode:long

Return 1 if the probe point occurred in user-mode.

Namefunction::is_return — Whether the current probe context is a return probe.


14

Synopsis

function is_return:long()

ArgumentsNone

General Syntaxis_return:long

DescriptionReturns 1 if the current probe context is a return probe, returns 0 otherwise.

Namefunction::target — Return the process ID of the target process.

Synopsis

function target:long()

ArgumentsNone

General Syntaxtarget:long

DescriptionThis function returns the process ID of the target process. This is useful in conjunction with the -xPID or -c CMD command-line options to stap. An example of its use is to create scripts that filter on aspecific process.

Namefunction::module_name — The module name of the current script.

Synopsis

function module_name:string()

ArgumentsNone

15

General Syntaxmodule_name:string

DescriptionThis function returns the name of the stap module. Either generated randomly (stap_[0-9a-f]+_[0-9a-f]+) or set by stap -m <module_name>.

Namefunction::stp_pid — The process id of the stapio process.

Synopsis

function stp_pid:long()

ArgumentsNone

General Syntaxstp_pid:long

DescriptionThis function returns the process id of the stapio process that launched this script. There could beother SystemTap scripts and stapio processes running on the system.

Namefunction::stack_size — Return the size of the kernel stack.

Synopsis

function stack_size:long()

ArgumentsNone

General Syntaxstack_size:long

DescriptionThis function returns the size of the kernel stack.


16

Namefunction::stack_used — Returns the amount of kernel stack used.

Synopsis

function stack_used:long()

ArgumentsNone

General Syntaxstack_used:long

DescriptionThis function determines how many bytes are currently used in the kernel stack.

Namefunction::stack_unused — Returns the amount of kernel stack currently available.

Synopsis

function stack_unused:long()

ArgumentsNone

General Syntaxstack_unused:long

DescriptionThis function determines how many bytes are currently available in the kernel stack.

Namefunction::uaddr — User space address of current running task. EXPERIMENTAL.

Synopsis

function uaddr:long()

17

ArgumentsNone

General Syntaxuaddr:long

DescriptionReturns the address in userspace that the current task was at when the probe occurred. When thecurrent running task isn't a user space thread, or the address cannot be found, zero is returned. Canbe used to see where the current task is combined with usymname or symdata. Often the task will bein the VDSO where it entered the kernel. FIXME - need VDSO tracking support #10080.

Namefunction::cmdline_args — Fetch command line arguments from current process

Synopsis

function cmdline_args:string(n:long,m:long,delim:string)

Argumentsn

First argument to get (zero is the command itself)

mLast argument to get (or minus one for all arguments after n)

delimString to use to delimit arguments when more than one.

General Syntaxcmdline_args:string(n:long, m:long, delim:string)

DescriptionReturns arguments from the current process starting with argument number n, up to argument m.If there are less than n arguments, or the arguments cannot be retrieved from the current process,the empty string is returned. If m is smaller than n then all arguments starting from argument n arereturned. Argument zero is traditionally the command itself.

Namefunction::cmdline_arg — Fetch a command line argument.

Synopsis


18

function cmdline_arg:string(n:long)

Argumentsn

Argument to get (zero is the command itself)

General Syntaxcmdline_arg:string(n:long)

DescriptionReturns argument the requested argument from the current process or the empty string whenthere are not that many arguments or there is a problem retrieving the argument. Argument zero istraditionally the command itself.

Namefunction::cmdline_str — Fetch all command line arguments from current process

Synopsis

function cmdline_str:string()

ArgumentsNone

General Syntaxcmdline_str:string

DescriptionReturns all arguments from the current process delimited by spaces. Returns the empty string whenthe arguments cannot be retrieved.

Namefunction::env_var — Fetch environment variable from current process

Synopsis

function env_var:string(name:string)

Argumentsname

Name of the environment variable to fetch

19

General Syntaxevn_var:string(name:string)

DescriptionReturns the contents of the specified environment value for the current process. If the variable isn't setan empty string is returned.

Namefunction::print_stack — Print out kernel stack from string.

Synopsis

function print_stack(stk:string)

Argumentsstk

String with list of hexadecimal addresses.

General Syntaxprint_stack(stk:string)

DescriptionThis function performs a symbolic lookup of the addresses in the given string, which is assumed to bethe result of a prior call to backtrace.

Print one line per address, including the address, the name of the function containing the address, andan estimate of its position within that function. Return nothing.

Namefunction::sprint_stack — Return stack for kernel addresses from string. EXPERIMENTAL!

Synopsis

function sprint_stack:string(stk:string)

Argumentsstk

String with list of hexadecimal (kernel) addresses.

DescriptionPerform a symbolic lookup of the addresses in the given string, which is assumed to be the result of aprior call to backtrace.


20

Returns a simple backtrace from the given hex string. One line per address. Includes the symbol name(or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset fromthe start of the function if found, otherwise the offset will be added to the module (if found, betweenbrackets). Returns the backtrace as string (each line terminated by a newline character). Note that thereturned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_stack.

Namefunction::probefunc — Return the probe point's function name, if known.

Synopsis

function probefunc:string()

ArgumentsNone

General Syntaxprobefunc:string

DescriptionThis function returns the name of the function being probed. It will do this based on the probe pointstring as returned by pp.

Please notethis function is deprecated, please use symname and/or usymname. This function might return afunction name based on the current address if the probe point context couldn't be parsed.

Namefunction::probemod — Return the probe point's kernel module name.

Synopsis

function probemod:string()

ArgumentsNone

General Syntaxprobemod:string

DescriptionThis funciton returns the name of the kernel module containing the probe point, if known.

21

Namefunction::modname — Return the kernel module name loaded at the address.

Synopsis

function modname:string(addr:long)

Argumentsaddr

The address.

DescriptionReturns the module name associated with the given address if known. If not known it will return thestring “<unknown>”. If the address was not in a kernel module, but in the kernel itself, then the string“kernel” will be returned.

Namefunction::symname — Return the kernel symbol associated with the given address.

Synopsis

function symname:string(addr:long)

Argumentsaddr

The address to translate.

General Syntaxsymname:string(addr:long)

DescriptionReturns the (function) symbol name associated with the given address if known. If not known it willreturn the hex string representation of addr.

Namefunction::symdata — Return the kernel symbol and module offset for the address.

Synopsis


22

function symdata:string(addr:long)

Argumentsaddr


General Syntaxsymdata:string(addr:long)

DescriptionReturns the (function) symbol name associated with the given address if known, the offset from thestart and size of the symbol, plus module name (between brackets). If symbol is unknown, but moduleis known, the offset inside the module, plus the size of the module is added. If any element is notknown it will be omitted and if the symbol name is unknown it will return the hex string for the givenaddress.

Namefunction::usymname — Return the symbol of an address in the current task. EXPERIMENTAL!

Synopsis

function usymname:string(addr:long)

Argumentsaddr


DescriptionReturns the (function) symbol name associated with the given address if known. If not known it willreturn the hex string representation of addr.

Namefunction::usymdata — Return the symbol and module offset of an address. EXPERIMENTAL!

Synopsis

function usymdata:string(addr:long)

Argumentsaddr


23

DescriptionReturns the (function) symbol name associated with the given address in the current task if known, theoffset from the start and the size of the symbol, plus the module name (between brackets). If symbolis unknown, but module is known, the offset inside the module, plus the size of the module is added.If any element is not known it will be omitted and if the symbol name is unknown it will return the hexstring for the given address.

Namefunction::print_ustack — Print out stack for the current task from string. EXPERIMENTAL!

Synopsis

function print_ustack(stk:string)

Argumentsstk

String with list of hexadecimal addresses for the current task.

DescriptionPerform a symbolic lookup of the addresses in the given string, which is assumed to be the result of aprior call to ubacktrace for the current task.

Print one line per address, including the address, the name of the function containing the address, andan estimate of its position within that function. Return nothing.

Namefunction::sprint_ustack — Return stack for the current task from string. EXPERIMENTAL!

Synopsis

function sprint_ustack:string(stk:string)

Argumentsstk

String with list of hexadecimal addresses for the current task.

DescriptionPerform a symbolic lookup of the addresses in the given string, which is assumed to be the result of aprior call to ubacktrace for the current task.

Returns a simple backtrace from the given hex string. One line per address. Includes the symbol name(or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset fromthe start of the function if found, otherwise the offset will be added to the module (if found, between


24

brackets). Returns the backtrace as string (each line terminated by a newline character). Note that thereturned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_ustack.

Namefunction::print_backtrace — Print stack back trace

Synopsis

function print_backtrace()

ArgumentsNone

General Syntaxprint_backtrace

DescriptionThis function isEquivalent to print_stack(backtrace), except that deeper stack nesting may besupported. The function does not return a value.

Namefunction::sprint_backtrace — Return stack back trace as string. EXPERIMENTAL!

Synopsis

function sprint_backtrace:string()

ArgumentsNone

DescriptionReturns a simple (kernel) backtrace. One line per address. Includes the symbol name (or hex addressif symbol couldn't be resolved) and module name (if found). Includes the offset from the start ofthe function if found, otherwise the offset will be added to the module (if found, between brackets).Returns the backtrace as string (each line terminated by a newline character). Note that the returnedstack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_backtrace.Equivalent to sprint_stack(backtrace), but more efficient (no need to translate between hex stringsand final backtrace string).

Namefunction::backtrace — Hex backtrace of current stack

25

Synopsis

function backtrace:string()

ArgumentsNone

General Syntaxbacktrace:string

DescriptionThis function returns a string of hex addresses that are a backtrace of the stack. Output may betruncated as as per maximum string length (MAXSTRINGLEN).

Namefunction::task_backtrace — Hex backtrace of an arbitrary task

Synopsis

function task_backtrace:string(task:long)

Argumentstask

pointer to task_struct

General Syntaxtask_backtrace:string(task:long)

DescriptionThis function returns a string of hex addresses that are a backtrace of the stack of a particular taskOutput may be truncated as per maximum string length.

Namefunction::caller — Return name and address of calling function

Synopsis

function caller:string()


26

ArgumentsNone

General Syntaxcaller:string

DescriptionThis function returns the address and name of the calling function. This is equivalent to calling:sprintf(“s 0xx”, symname(caller_addr, caller_addr)) Works only for return probes at this time.

Namefunction::caller_addr — Return caller address

Synopsis

function caller_addr:long()

ArgumentsNone

General Syntaxcaller_addr:long

DescriptionThis function returns the address of the calling function. Works only for return probes at this time.

Namefunction::print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL!

Synopsis

function print_ubacktrace()

ArgumentsNone

DescriptionEquivalent to print_ustack(ubacktrace), except that deeper stack nesting may be supported.Returns nothing.

27

NoteTo get (full) backtraces for user space applications and shared shared libraries not mentioned in thecurrent script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.

Namefunction::sprint_ubacktrace — Return stack back trace for current task as string. EXPERIMENTAL!

Synopsis

function sprint_ubacktrace:string()

ArgumentsNone

DescriptionReturns a simple backtrace for the current task. One line per address. Includes the symbol name(or hex address if symbol couldn't be resolved) and module name (if found). Includes the offsetfrom the start of the function if found, otherwise the offset will be added to the module (if found,between brackets). Returns the backtrace as string (each line terminated by a newline character).Note that the returned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacksuse print_ubacktrace. Equivalent to sprint_ustack(ubacktrace), but more efficient (no need totranslate between hex strings and final backtrace string).


Namefunction::print_ubacktrace_brief — Print stack back trace for current task. EXPERIMENTAL!

Synopsis

function print_ubacktrace_brief()

ArgumentsNone

DescriptionEquivalent to print_ubacktrace, but output for each symbol is shorter (just name and offset, or justthe hex address of no symbol could be found).


28


Namefunction::ubacktrace — Hex backtrace of current task stack. EXPERIMENTAL!

Synopsis

function ubacktrace:string()

ArgumentsNone

DescriptionReturn a string of hex addresses that are a backtrace of the stack of the current task. Output maybe truncated as per maximum string length. Returns empty string when current probe point cannotdetermine user backtrace.


Namefunction::task_current — The current task_struct of the current task.

Synopsis

function task_current:long()

ArgumentsNone

General Syntaxtask_current:long

DescriptionThis function returns the task_struct representing the current process. This address can be passed tothe various task_*() functions to extract more task-specific data.

29

Namefunction::task_parent — The task_struct of the parent task.

Synopsis

function task_parent:long(task:long)

Argumentstask

task_struct pointer.

General Syntaxtask_parent:long(task:long)

DescriptionThis function returns the parent task_struct of the given task. This address can be passed to thevarious task_*() functions to extract more task-specific data.

Namefunction::task_state — The state of the task.

Synopsis

function task_state:long(task:long)

Argumentstask


General Syntaxtask_state:long(task:long)

DescriptionReturn the state of the given task, one of: TASK_RUNNING (0), TASK_INTERRUPTIBLE (1),TASK_UNINTERRUPTIBLE (2), TASK_STOPPED (4), TASK_TRACED (8), EXIT_ZOMBIE (16),EXIT_DEAD (32).

Namefunction::task_execname — The name of the task.


30

Synopsis

function task_execname:string(task:long)

Argumentstask


General Syntaxtask_execname:string(task:long)

DescriptionReturn the name of the given task.

Namefunction::task_pid — The process identifier of the task.

Synopsis

function task_pid:long(task:long)

Argumentstask


General Syntaxtask_pid:long (task:long)

DescriptionThis fucntion returns the process id of the given task.

Namefunction::pid2task — The task_struct of the given process identifier.

Synopsis

function pid2task:long(pid:long)

31

Argumentspid

Process identifier.

DescriptionReturn the task struct of the given process id.

Namefunction::pid2execname — The name of the given process identifier.

Synopsis

function pid2execname:string(pid:long)

Argumentspid

Process identifier.

DescriptionReturn the name of the given process id.

Namefunction::task_tid — The thread identifier of the task.

Synopsis

function task_tid:long(task:long)

Argumentstask


General Syntaxtask_tid:long(task:long)

DescriptionThis function returns the thread id of the given task.

Namefunction::task_gid — The group identifier of the task.


32

Synopsis

function task_gid:long(task:long)

Argumentstask


General Syntaxtask_gid:long(task:long)

DescriptionThis function returns the group id of the given task.

Namefunction::task_egid — The effective group identifier of the task.

Synopsis

function task_egid:long(task:long)

Argumentstask


General Syntaxtask_egid:long(task:long)

DescriptionThis function returns the effective group id of the given task.

Namefunction::task_uid — The user identifier of the task.

Synopsis

function task_uid:long(task:long)

33

Argumentstask


General Syntaxtask_uid:long(task:long)

DescriptionThis function returns the user id of the given task.

Namefunction::task_euid — The effective user identifier of the task.

Synopsis

function task_euid:long(task:long)

Argumentstask


General Syntaxtask_euid:long(task:long)

DescriptionThis function returns the effective user id of the given task.

Namefunction::task_prio — The priority value of the task.

Synopsis

function task_prio:long(task:long)

Argumentstask


General Syntaxtask_prio:long(task:long)


34

DescriptionThis function returns the priority value of the given task.

Namefunction::task_nice — The nice value of the task.

Synopsis

function task_nice:long(task:long)

Argumentstask


General Syntaxtask_nice:long(task:long)

DescriptionThis function returns the nice value of the given task.

Namefunction::task_cpu — The scheduled cpu of the task.

Synopsis

function task_cpu:long(task:long)

Argumentstask


General Syntaxtask_cpu:long(task:long)

DescriptionThis function returns the scheduled cpu for the given task.

Namefunction::task_open_file_handles — The number of open files of the task.

35

Synopsis

function task_open_file_handles:long(task:long)

Argumentstask


General Syntaxtask_open_file_handles:long(task:long)

DescriptionThis function returns the number of open file handlers for the given task.

Namefunction::task_max_file_handles — The max number of open files for the task.

Synopsis

function task_max_file_handles:long(task:long)

Argumentstask


General Syntaxtask_max_file_handles:long(task:long)

DescriptionThis function returns the maximum number of file handlers for the given task.

Namefunction::pn — Returns the active probe name.

Synopsis

function pn:string()

ArgumentsNone


36

General Syntaxpn:string

DescriptionThis function returns the script-level probe point associated with a currently running probe handler,including wild-card expansion effects. Context: The current probe point.

Chapter 4.

37

Timestamp FunctionsEach timestamp function returns a value to indicate when a function is executed. These returnedvalues can then be used to indicate when an event occurred, provide an ordering for events, orcompute the amount of time elapsed between two time stamps.

Namefunction::get_cycles — Processor cycle count.

Synopsis

function get_cycles:long()

ArgumentsNone

General Syntaxget_cycles:long

DescriptionThis function returns the processor cycle counter value if available, else it returns zero. The cyclecounter is free running and unsynchronized on each processor. Thus, the order of events cannotdetermined by comparing the results of the get_cycles function on different processors.

Namefunction::gettimeofday_ns — Number of nanoseconds since UNIX epoch.

Synopsis

function gettimeofday_ns:long()

ArgumentsNone

General Syntaxgettimeofday_ns:long

DescriptionThis function returns the number of nanoseconds since the UNIX epoch.

Chapter 4. Timestamp Functions

38

Namefunction::gettimeofday_us — Number of microseconds since UNIX epoch.

Synopsis

function gettimeofday_us:long()

ArgumentsNone

General Syntaxgettimeofday_us:long

DescriptionThis function returns the number of microseconds since the UNIX epoch.

Namefunction::gettimeofday_ms — Number of milliseconds since UNIX epoch.

Synopsis

function gettimeofday_ms:long()

ArgumentsNone

General Syntaxgettimeofday_ms:long

DescriptionThis function returns the number of milliseconds since the UNIX epoch.

Namefunction::gettimeofday_s — Number of seconds since UNIX epoch.

Synopsis

function gettimeofday_s:long()

39

ArgumentsNone

General Syntaxgettimeofday_s:long

DescriptionThis function returns the number of seconds since the UNIX epoch.

40

Chapter 5.

41

Time string utility functionUtility function to turn seconds since the epoch (as returned by the timestamp functiongettimeofday_s()) into a human readable date/time string.

Namefunction::ctime — Convert seconds since epoch into human readable date/time string.

Synopsis

function ctime:string(epochsecs:long)

Argumentsepochsecs

Number of seconds since epoch (as returned by gettimeofday_s).

General Syntaxctime:string(epochsecs:long)

DescriptionTakes an argument of seconds since the epoch as returned by gettimeofday_s. Returns a string ofthe form

“Wed Jun 30 21:49:08 1993”

The string will always be exactly 24 characters. If the time would be unreasonable far in the past(before what can be represented with a 32 bit offset in seconds from the epoch) the returned string willbe “a long, long time ago...”. If the time would be unreasonable far in the future the returned string willbe “far far in the future...” (both these strings are also 24 characters wide).

Note that the epoch (zero) corresponds to

“Thu Jan 1 00:00:00 1970”

The earliest full date given by ctime, corresponding to epochsecs -2147483648 is “Fri Dec 13 20:45:521901”. The latest full date given by ctime, corresponding to epochsecs 2147483647 is “Tue Jan 1903:14:07 2038”.

The abbreviations for the days of the week are ‘Sun’, ‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, and ‘Sat’. Theabbreviations for the months are ‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’, ‘May’, ‘Jun’, ‘Jul’, ‘Aug’, ‘Sep’, ‘Oct’, ‘Nov’,and ‘Dec’.

Note that the real C library ctime function puts a newline ('\n') character at the end of the string thatthis function does not. Also note that since the kernel has no concept of timezones, the returned timeis always in GMT.

42

Chapter 6.

43

Memory TapsetThis family of probe points is used to probe memory-related events or query the memory usage of thecurrent process. It contains the following probe points:

Namefunction::vm_fault_contains — Test return value for page fault reason

Synopsis

function vm_fault_contains:long(value:long,test:long)

Argumentsvalue

The fault_type returned by vm.page_fault.return

testThe type of fault to test for (VM_FAULT_OOM or similar)

Nameprobe::vm.pagefault — Records that a page fault occurred.

Synopsis

vm.pagefault

Valueswrite_access

Indicates whether this was a write or read access; 1 indicates a write, while 0 indicates a read.

nameName of the probe point

addressThe address of the faulting memory access; i.e. the address that caused the page fault.

ContextThe process which triggered the fault

Nameprobe::vm.pagefault.return — Indicates what type of fault occurred.

Chapter 6. Memory Tapset

44

Synopsis

vm.pagefault.return

Valuesname

Name of the probe point

fault_typeReturns either 0 (VM_FAULT_OOM) for out of memory faults, 2 (VM_FAULT_MINOR) for minorfaults, 3 (VM_FAULT_MAJOR) for major faults, or 1 (VM_FAULT_SIGBUS) if the fault was neitherOOM, minor fault, nor major fault.

Namefunction::addr_to_node — Returns which node a given address belongs to within a NUMA system.

Synopsis

function addr_to_node:long(addr:long)

Argumentsaddr

The address of the faulting memory access.

General Syntaxaddr_to_node:long(addr:long)

DescriptionThis function accepts an address, and returns the node that the given address belongs to in a NUMAsystem.

Nameprobe::vm.write_shared — Attempts at writing to a shared page.

Synopsis

vm.write_shared

Valuesname


45

addressThe address of the shared write.

ContextThe context is the process attempting the write.

DescriptionFires when a process attempts to write to a shared page. If a copy is necessary, this will be followedby a vm.write_shared_copy.

Nameprobe::vm.write_shared_copy — Page copy for shared page write.

Synopsis

vm.write_shared_copy

Valuesname


zeroBoolean indicating whether it is a zero page (can do a clear instead of a copy).

addressThe address of the shared write.

ContextThe process attempting the write.

DescriptionFires when a write to a shared page requires a page copy. This is always preceded by avm.shared_write.

Nameprobe::vm.mmap — Fires when an mmap is requested.

Synopsis

vm.mmap


46

Valueslength

The length of the memory segment


addressThe requested address

ContextThe process calling mmap.

Nameprobe::vm.munmap — Fires when an munmap is requested.

Synopsis

vm.munmap

Valueslength




ContextThe process calling munmap.

Nameprobe::vm.brk — Fires when a brk is requested (i.e. the heap will be resized).

Synopsis

vm.brk

Valueslength


47



ContextThe process calling brk.

Nameprobe::vm.oom_kill — Fires when a thread is selected for termination by the OOM killer.

Synopsis

vm.oom_kill

Valuesname


taskThe task being killed

ContextThe process that tried to consume excessive memory, and thus triggered the OOM.

Nameprobe::vm.kmalloc — Fires when kmalloc is requested.

Synopsis

vm.kmalloc

Valuesptr

Pointer to the kmemory allocated

caller_functionName of the caller function.

call_siteAddress of the kmemory function.

gfp_flag_nametype of kmemory to allocate (in String format)


48


bytes_reqRequested Bytes

bytes_allocAllocated Bytes

gfp_flagstype of kmemory to allocate

Nameprobe::vm.kmem_cache_alloc — Fires when \

Synopsis

vm.kmem_cache_alloc

Valuesptr



call_siteAddress of the function calling this kmemory function.

gfp_flag_nameType of kmemory to allocate(in string format)





Descriptionkmem_cache_alloc is requested.

Nameprobe::vm.kmalloc_node — Fires when kmalloc_node is requested.

49

Synopsis

vm.kmalloc_node

Valuesptr



call_siteAddress of the function caling this kmemory function.






Nameprobe::vm.kmem_cache_alloc_node — Fires when \

Synopsis

vm.kmem_cache_alloc_node

Valuesptr






50





Descriptionkmem_cache_alloc_node is requested.

Nameprobe::vm.kfree — Fires when kfree is requested.

Synopsis

vm.kfree

Valuesptr

Pointer to the kmemory allocated which is returned by kmalloc




Nameprobe::vm.kmem_cache_free — Fires when \

Synopsis

vm.kmem_cache_free

Valuesptr

Pointer to the kmemory allocated which is returned by kmem_cache

51




Descriptionkmem_cache_free is requested.

Namefunction::proc_mem_size — Total program virtual memory size in pages

Synopsis

function proc_mem_size:long()

ArgumentsNone

DescriptionReturns the total virtual memory size in pages of the current process, or zero when there is no currentprocess or the number of pages couldn't be retrieved.

Namefunction::proc_mem_size_pid — Total program virtual memory size in pages

Synopsis

function proc_mem_size_pid:long(pid:long)

Argumentspid

The pid of process to examine

DescriptionReturns the total virtual memory size in pages of the given process, or zero when that process doesn'texist or the number of pages couldn't be retrieved.

Namefunction::proc_mem_rss — Program resident set size in pages


52

Synopsis

function proc_mem_rss:long()

ArgumentsNone

DescriptionReturns the resident set size in pages of the current process, or zero when there is no current processor the number of pages couldn't be retrieved.

Namefunction::proc_mem_rss_pid — Program resident set size in pages

Synopsis

function proc_mem_rss_pid:long(pid:long)

Argumentspid


DescriptionReturns the resident set size in pages of the given process, or zero when the process doesn't exist orthe number of pages couldn't be retrieved.

Namefunction::proc_mem_shr — Program shared pages (from shared mappings)

Synopsis

function proc_mem_shr:long()

ArgumentsNone

DescriptionReturns the shared pages (from shared mappings) of the current process, or zero when there is nocurrent process or the number of pages couldn't be retrieved.

53

Namefunction::proc_mem_shr_pid — Program shared pages (from shared mappings)

Synopsis

function proc_mem_shr_pid:long(pid:long)

Argumentspid


DescriptionReturns the shared pages (from shared mappings) of the given process, or zero when the processdoesn't exist or the number of pages couldn't be retrieved.

Namefunction::proc_mem_txt — Program text (code) size in pages

Synopsis

function proc_mem_txt:long()

ArgumentsNone

DescriptionReturns the current process text (code) size in pages, or zero when there is no current process or thenumber of pages couldn't be retrieved.

Namefunction::proc_mem_txt_pid — Program text (code) size in pages

Synopsis

function proc_mem_txt_pid:long(pid:long)

Argumentspid



54

DescriptionReturns the given process text (code) size in pages, or zero when the process doesn't exist or thenumber of pages couldn't be retrieved.

Namefunction::proc_mem_data — Program data size (data + stack) in pages

Synopsis

function proc_mem_data:long()

ArgumentsNone

DescriptionReturns the current process data size (data + stack) in pages, or zero when there is no currentprocess or the number of pages couldn't be retrieved.

Namefunction::proc_mem_data_pid — Program data size (data + stack) in pages

Synopsis

function proc_mem_data_pid:long(pid:long)

Argumentspid


DescriptionReturns the given process data size (data + stack) in pages, or zero when the process doesn't exist orthe number of pages couldn't be retrieved.

Namefunction::mem_page_size — Number of bytes in a page for this architecture

Synopsis

function mem_page_size:long()

55

ArgumentsNone

Namefunction::bytes_to_string — Human readable string for given bytes

Synopsis

function bytes_to_string:string(bytes:long)

Argumentsbytes

Number of bytes to translate.

DescriptionReturns a string representing the number of bytes (up to 1024 bytes), the number of kilobytes (whenless than 1024K) postfixed by 'K', the number of megabytes (when less than 1024M) postfixed by 'M'or the number of gigabytes postfixed by 'G'. If representing K, M or G, and the number is amount isless than 100, it includes a '.' plus the remainer. The returned string will be 5 characters wide (paddingwith whitespace at the front) unless negative or representing more than 9999G bytes.

Namefunction::pages_to_string — Turns pages into a human readable string

Synopsis

function pages_to_string:string(pages:long)

Argumentspages

Number of pages to translate.

DescriptionMultiplies pages by page_size to get the number of bytes and returns the result ofbytes_to_string.

Namefunction::proc_mem_string — Human readable string of current proc memory usage

Synopsis


56

function proc_mem_string:string()

ArgumentsNone

DescriptionReturns a human readable string showing the size, rss, shr, txt and data of the memory used by thecurrent process. For example “size: 301m, rss: 11m, shr: 8m, txt: 52k, data: 2248k”.

Namefunction::proc_mem_string_pid — Human readable string of process memory usage

Synopsis

function proc_mem_string_pid:string(pid:long)

Argumentspid


DescriptionReturns a human readable string showing the size, rss, shr, txt and data of the memory used by thegiven process. For example “size: 301m, rss: 11m, shr: 8m, txt: 52k, data: 2248k”.

Chapter 7.

57

Task Time TapsetThis tapset defines utility functions to query time related properties of the current tasks, translate thosein miliseconds and human readable strings.

Namefunction::task_utime — User time of the current task

Synopsis

function task_utime:long()

ArgumentsNone

DescriptionReturns the user time of the current task in cputime. Does not include any time used by other tasks inthis process, nor does it include any time of the children of this task.

Namefunction::task_utime_tid — User time of the given task

Synopsis

function task_utime_tid:long(tid:long)

Argumentstid

Thread id of the given task

DescriptionReturns the user time of the given task in cputime, or zero if the task doesn't exist. Does not includeany time used by other tasks in this process, nor does it include any time of the children of this task.

Namefunction::task_stime — System time of the current task

Synopsis

Chapter 7. Task Time Tapset

58

function task_stime:long()

ArgumentsNone

DescriptionReturns the system time of the current task in cputime. Does not include any time used by other tasksin this process, nor does it include any time of the children of this task.

Namefunction::task_stime_tid — System time of the given task

Synopsis

function task_stime_tid:long(tid:long)

Argumentstid


DescriptionReturns the system time of the given task in cputime, or zero if the task doesn't exist. Does not includeany time used by other tasks in this process, nor does it include any time of the children of this task.

Namefunction::cputime_to_msecs — Translates the given cputime into milliseconds

Synopsis

function cputime_to_msecs:long(cputime:long)

Argumentscputime

Time to convert to milliseconds.

Namefunction::msecs_to_string — Human readable string for given milliseconds

Synopsis

59

function msecs_to_string:string(msecs:long)

Argumentsmsecs

Number of milliseconds to translate.

DescriptionReturns a string representing the number of milliseconds as a human readable string consisting of“XmY.ZZZs”, where X is the number of minutes, Y is the number of seconds and ZZZ is the number ofmilliseconds.

Namefunction::cputime_to_string — Human readable string for given cputime

Synopsis

function cputime_to_string:string(cputime:long)

Argumentscputime

Time to translate.

DescriptionEquivalent to calling: msec_to_string (cputime_to_msecs (cputime).

Namefunction::task_time_string — Human readable string of task time usage

Synopsis

function task_time_string:string()

ArgumentsNone

DescriptionReturns a human readable string showing the user and system time the current task has used up tonow. For example “usr: 0m12.908s, sys: 1m6.851s”.

Namefunction::task_time_string_tid — Human readable string of task time usage

Chapter 7. Task Time Tapset

60

Synopsis

function task_time_string_tid:string(tid:long)

Argumentstid


DescriptionReturns a human readable string showing the user and system time the given task has used up tonow. For example “usr: 0m12.908s, sys: 1m6.851s”.

Chapter 8.

61

IO Scheduler and block IO TapsetThis family of probe points is used to probe block IO layer and IO scheduler activities. It contains thefollowing probe points:

Nameprobe::ioscheduler.elv_next_request — Fires when a request is retrieved from the request queue

Synopsis

ioscheduler.elv_next_request

Valuesname


elevator_nameThe type of I/O elevator currently enabled

Nameprobe::ioscheduler.elv_next_request.return — Fires when a request retrieval issues a return signal

Synopsis

ioscheduler.elv_next_request.return

Valuesdisk_major

Disk major number of the request

rqAddress of the request


disk_minorDisk minor number of the request

rq_flagsRequest flags

Nameprobe::ioscheduler.elv_completed_request — Fires when a request is completed

Chapter 8. IO Scheduler and block IO Tapset

62

Synopsis

ioscheduler.elv_completed_request

Valuesdisk_major







Nameprobe::ioscheduler.elv_add_request.kp — kprobe based probe to indicate that a request was added tothe request queue

Synopsis

ioscheduler.elv_add_request.kp

Valuesdisk_major



qpointer to request queue




63


Nameprobe::ioscheduler.elv_add_request.tp — tracepoint based probe to indicate a request is added to therequest queue.

Synopsis

ioscheduler.elv_add_request.tp

Valuesdisk_major

Disk major no of request.

rqAddress of request.

qPointer to request queue.


elevator_nameThe type of I/O elevator currently enabled.

disk_minorDisk minor number of request.

rq_flagsRequest flags.

Nameprobe::ioscheduler.elv_add_request — probe to indicate request is added to the request queue.

Synopsis

ioscheduler.elv_add_request

Valuesdisk_major




64

qPointer to request queue.




Nameprobe::ioscheduler_trace.elv_completed_request — Fires when a request is

Synopsis

ioscheduler_trace.elv_completed_request

Valuesdisk_major







Descriptioncompleted.

Nameprobe::ioscheduler_trace.elv_issue_request — Fires when a request is

Synopsis

65

ioscheduler_trace.elv_issue_request

Valuesdisk_major







Descriptionscheduled.

Nameprobe::ioscheduler_trace.elv_requeue_request — Fires when a request is

Synopsis

ioscheduler_trace.elv_requeue_request

Valuesdisk_major








66

Descriptionput back on the queue, when the hadware cannot accept more requests.

Nameprobe::ioscheduler_trace.elv_abort_request — Fires when a request is aborted.

Synopsis

ioscheduler_trace.elv_abort_request

Valuesdisk_major







Nameprobe::ioscheduler_trace.plug — Fires when a request queue is plugged;

Synopsis

ioscheduler_trace.plug

Valuesname


rq_queuerequest queue

Descriptionie, requests in the queue cannot be serviced by block driver.

67

Nameprobe::ioscheduler_trace.unplug_io — Fires when a request queue is unplugged;

Synopsis

ioscheduler_trace.unplug_io

Valuesname



DescriptionEither, when number of pending requests in the queue exceeds threshold or, upon expiration of timerthat was activated when queue was plugged.

Nameprobe::ioscheduler_trace.unplug_timer — Fires when unplug timer associated

Synopsis

ioscheduler_trace.unplug_timer

Valuesname



Descriptionwith a request queue expires.

Nameprobe::ioblock.request — Fires whenever making a generic block I/O request.

Synopsis

ioblock.request


68

ValuesNone

Descriptionname - name of the probe point devname - block device name ino - i-node number of the mappedfile sector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0 ok after I/Ocompletion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED5 bio is a bounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 notsupported

rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which make up this I/O request idx - offset into the bio vector arrayphys_segments - number of segments in this bio after physical address coalescing is performedhw_segments - number of segments after physical and DMA remapping hardware coalescing isperformed size - total size in bytes bdev - target block device bdev_contains - points to the deviceobject which contains the partition (when bio structure represents a partition) p_start_sect - pointsto the start sector of the partition structure of the device

ContextThe process makes block I/O request

Nameprobe::ioblock.end — Fires whenever a block I/O transfer is complete.

Synopsis

ioblock.end

ValuesNone

Descriptionname - name of the probe point devname - block device name ino - i-node number of the mapped filebytes_done - number of bytes transferred sector - beginning sector for the entire bio flags - seebelow BIO_UPTODATE 0 ok after I/O completion BIO_RW_BLOCK 1 RW_AHEAD set, and read/writewould block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4doesn't own data BIO_BOUNCED 5 bio is a bounce bio BIO_USER_MAPPED 6 contains user pagesBIO_EOPNOTSUPP 7 not supported error - 0 on success rw - binary trace for read/write requestvcnt - bio vector count which represents number of array element (page, offset, length) which makesup this I/O request idx - offset into the bio vector array phys_segments - number of segments inthis bio after physical address coalescing is performed. hw_segments - number of segments afterphysical and DMA remapping hardware coalescing is performed size - total size in bytes

ContextThe process signals the transfer is done.

69

Nameprobe::ioblock_trace.bounce — Fires whenever a buffer bounce is needed for at least one page of ablock IO request.

Synopsis

ioblock_trace.bounce

ValuesNone

Descriptionname - name of the probe point q - request queue on which this bio was queued. devname - devicefor which a buffer bounce was needed. ino - i-node number of the mapped file bytes_done- number of bytes transferred sector - beginning sector for the entire bio flags - see belowBIO_UPTODATE 0 ok after I/O completion BIO_RW_BLOCK 1 RW_AHEAD set, and read/writewould block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED4 doesn't own data BIO_BOUNCED 5 bio is a bounce bio BIO_USER_MAPPED 6 contains userpages BIO_EOPNOTSUPP 7 not supported rw - binary trace for read/write request vcnt - biovector count which represents number of array element (page, offset, length) which makes up thisI/O request idx - offset into the bio vector array phys_segments - number of segments in thisbio after physical address coalescing is performed. size - total size in bytes bdev - target blockdevice bdev_contains - points to the device object which contains the partition (when bio structurerepresents a partition) p_start_sect - points to the start sector of the partition structure of thedevice

ContextThe process creating a block IO request.

Nameprobe::ioblock_trace.request — Fires just as a generic block I/O request is created for a bio.

Synopsis

ioblock_trace.request

ValuesNone

Descriptionname - name of the probe point q - request queue on which this bio was queued. devname - blockdevice name ino - i-node number of the mapped file bytes_done - number of bytes transferredsector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0 ok after I/O


70

completion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED5 bio is a bounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 notsupported

rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which make up this I/O request idx - offset into the bio vector arrayphys_segments - number of segments in this bio after physical address coalescing is performed.size - total size in bytes bdev - target block device bdev_contains - points to the device objectwhich contains the partition (when bio structure represents a partition) p_start_sect - points to thestart sector of the partition structure of the device

ContextThe process makes block I/O request

Nameprobe::ioblock_trace.end — Fires whenever a block I/O transfer is complete.

Synopsis

ioblock_trace.end

ValuesNone

Descriptionname - name of the probe point q - request queue on which this bio was queued. devname - blockdevice name ino - i-node number of the mapped file bytes_done - number of bytes transferredsector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0 ok after I/Ocompletion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED5 bio is a bounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 notsupported

rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which makes up this I/O request idx - offset into the bio vector arrayphys_segments - number of segments in this bio after physical address coalescing is performed.size - total size in bytes bdev - target block device bdev_contains - points to the device objectwhich contains the partition (when bio structure represents a partition) p_start_sect - points to thestart sector of the partition structure of the device

ContextThe process signals the transfer is done.

Chapter 9.

71

SCSI TapsetThis family of probe points is used to probe SCSI activities. It contains the following probe points:

Nameprobe::scsi.ioentry — Prepares a SCSI mid-layer request

Synopsis

scsi.ioentry

Valuesdisk_major

The major number of the disk (-1 if no information)

device_state_strThe current state of the device, as a string

device_stateThe current state of the device

req_addrThe current struct request pointer, as a number

disk_minorThe minor number of the disk (-1 if no information)

Nameprobe::scsi.iodispatching — SCSI mid-layer dispatched low-level SCSI command

Synopsis

scsi.iodispatching

Valuesdevice_state_str

The current state of the device, as a string

dev_idThe scsi device id

channelThe channel number

data_directionThe data_direction specifies whether this command is from/to the device 0(DMA_BIDIRECTIONAL), 1 (DMA_TO_DEVICE), 2 (DMA_FROM_DEVICE), 3 (DMA_NONE)

Chapter 9. SCSI Tapset

72

lunThe lun number

request_bufflenThe request buffer length

host_noThe host number


data_direction_strData direction, as a string


request_bufferThe request buffer address

Nameprobe::scsi.iodone — SCSI command completed by low level driver and enqueued into the donequeue.

Synopsis

scsi.iodone





data_directionThe data_direction specifies whether this command is from/to the device.

lunThe lun number



73


scsi_timer_pending1 if a timer is pending on this request


Nameprobe::scsi.iocompleted — SCSI mid-layer running the completion processing for block device I/Orequests

Synopsis

scsi.iocompleted





data_directionThe data_direction specifies whether this command is from/to the device

lunThe lun number





goodbytesThe bytes completed

Nameprobe::scsi.ioexecute — Create mid-layer SCSI request and wait for the result

Chapter 9. SCSI Tapset

74

Synopsis

scsi.ioexecute

Valuesretries

Number of times to retry request

device_state_strThe current state of the device, as a string



data_directionThe data_direction specifies whether this command is from/to the device.

lunThe lun number

timeoutRequest timeout in seconds

request_bufflenThe data buffer buffer length




request_bufferThe data buffer address

Nameprobe::scsi.set_state — Order SCSI device state change

Synopsis

scsi.set_state

75

Valuesstate_str

The new state of the device, as a string



stateThe new state of the device

old_state_strThe current state of the device, as a string

lunThe lun number

old_stateThe current state of the device


76

Chapter 10.

77

TTY TapsetThis family of probe points is used to probe TTY (Teletype) activities. It contains the following probepoints:

Nameprobe::tty.open — Called when a tty is opened

Synopsis

tty.open

Valuesinode_state

the inode state

file_namethe file name

file_modethe file mode

file_flagsthe file flags

inode_numberthe inode number

inode_flagsthe inode flags

Nameprobe::tty.release — Called when the tty is closed

Synopsis

tty.release

Valuesinode_state

the inode state

file_namethe file name

file_modethe file mode

Chapter 10. TTY Tapset

78

file_flagsthe file flags

inode_numberthe inode number

inode_flagsthe inode flags

Nameprobe::tty.resize — Called when a terminal resize happens

Synopsis

tty.resize

Valuesnew_ypixel

the new ypixel value

old_colthe old col value

old_xpixelthe old xpixel

old_ypixelthe old ypixel

namethe tty name

old_rowthe old row value

new_rowthe new row value

new_xpixelthe new xpixel value

new_colthe new col value

Nameprobe::tty.ioctl — called when a ioctl is request to the tty

Synopsis

79

tty.ioctl

Valuescmd

the ioctl command

argthe ioctl argument

namethe file name

Nameprobe::tty.init — Called when a tty is being initalized

Synopsis

tty.init

Valuesdriver_name

the driver name

namethe driver .dev_name name

modulethe module name

Nameprobe::tty.register — Called when a tty device is registred

Synopsis

tty.register

Valuesdriver_name

the driver name


indexthe tty index requested


80


Nameprobe::tty.unregister — Called when a tty device is being unregistered

Synopsis

tty.unregister

Valuesdriver_name

the driver name


indexthe tty index requested


Nameprobe::tty.poll — Called when a tty device is being polled

Synopsis

tty.poll

Valuesfile_name

the tty file name

wait_keythe wait queue key

Nameprobe::tty.receive — called when a tty receives a message

Synopsis

tty.receive

81

Valuesdriver_name

the driver name

countThe amount of characters received

namethe name of the module file

fpThe flag buffer

cpthe buffer that was received

indexThe tty Index

idthe tty id

Nameprobe::tty.write — write to the tty line

Synopsis

tty.write

Valuesdriver_name

the driver name

bufferthe buffer that will be written

file_namethe file name lreated to the tty

nrThe amount of characters

Nameprobe::tty.read — called when a tty line will be read

Synopsis


82

tty.read

Valuesdriver_name

the driver name

bufferthe buffer that will receive the characters

file_namethe file name lreated to the tty

nrThe amount of characters to be read

Chapter 11.

83

Networking TapsetThis family of probe points is used to probe the activities of the network device and protocol layers.

Nameprobe::netdev.receive — Data received from network device.

Synopsis

netdev.receive

Valuesprotocol

Protocol of received packet.

dev_nameThe name of the device. e.g: eth0, ath1.

lengthThe length of the receiving buffer.

Nameprobe::netdev.transmit — Network device transmitting buffer

Synopsis

netdev.transmit

Valuesprotocol

The protocol of this packet(defined in include/linux/if_ether.h).

dev_nameThe name of the device. e.g: eth0, ath1.

lengthThe length of the transmit buffer.

truesizeThe size of the data to be transmitted.

Nameprobe::netdev.change_mtu — Called when the netdev MTU is changed

Chapter 11. Networking Tapset

84

Synopsis

netdev.change_mtu

Valuesdev_name

The device that will have the MTU changed

new_mtuThe new MTU

old_mtuThe current MTU

Nameprobe::netdev.open — Called when the device is opened

Synopsis

netdev.open

Valuesdev_name

The device that is going to be opened

Nameprobe::netdev.close — Called when the device is closed

Synopsis

netdev.close

Valuesdev_name

The device that is going to be closed

Nameprobe::netdev.hard_transmit — Called when the devices is going to TX (hard)

Synopsis

85

netdev.hard_transmit

Valuesprotocol

The protocol used in the transmission

dev_nameThe device scheduled to transmit

lengthThe length of the transmit buffer.

truesizeThe size of the data to be transmitted.

Nameprobe::netdev.rx — Called when the device is going to receive a packet

Synopsis

netdev.rx

Valuesprotocol

The packet protocol

dev_nameThe device received the packet

Nameprobe::netdev.change_rx_flag — Called when the device RX flag will be changed

Synopsis

netdev.change_rx_flag

Valuesdev_name

The device that will be changed

flagsThe new flags

Nameprobe::netdev.set_promiscuity — Called when the device enters/leaves promiscuity


86

Synopsis

netdev.set_promiscuity

Valuesdev_name

The device that is entering/leaving promiscuity mode

enableIf the device is entering promiscuity mode

incCount the number of promiscuity openers

disableIf the device is leaving promiscuity mode

Nameprobe::netdev.ioctl — Called when the device suffers an IOCTL

Synopsis

netdev.ioctl

Valuescmd

The IOCTL request

argThe IOCTL argument (usually the netdev interface)

Nameprobe::netdev.register — Called when the device is registered

Synopsis

netdev.register

Valuesdev_name

The device that is going to be registered

87

Nameprobe::netdev.unregister — Called when the device is being unregistered

Synopsis

netdev.unregister

Valuesdev_name

The device that is going to be unregistered

Nameprobe::netdev.get_stats — Called when someone asks the device statistics

Synopsis

netdev.get_stats

Valuesdev_name

The device that is going to provide the statistics

Nameprobe::netdev.change_mac — Called when the netdev_name has the MAC changed

Synopsis

netdev.change_mac

Valuesdev_name

The device that will have the MTU changed

new_macThe new MAC address

mac_lenThe MAC length

old_macThe current MAC address


88

Nameprobe::tcp.sendmsg — Sending a tcp message

Synopsis

tcp.sendmsg

Valuesname

Name of this probe

sizeNumber of bytes to send

sockNetwork socket

ContextThe process which sends a tcp message

Nameprobe::tcp.sendmsg.return — Sending TCP message is done

Synopsis

tcp.sendmsg.return

Valuesname

Name of this probe

sizeNumber of bytes sent or error code if an error occurred.

ContextThe process which sends a tcp message

Nameprobe::tcp.recvmsg — Receiving TCP message

Synopsis

89

tcp.recvmsg

Valuessaddr

A string representing the source IP address

daddrA string representing the destination IP address

nameName of this probe

sportTCP source port

dportTCP destination port

sizeNumber of bytes to be received

sockNetwork socket

ContextThe process which receives a tcp message

Nameprobe::tcp.recvmsg.return — Receiving TCP message complete

Synopsis

tcp.recvmsg.return

Valuessaddr







90

sizeNumber of bytes received or error code if an error occurred.

ContextThe process which receives a tcp message

Nameprobe::tcp.disconnect — TCP socket disconnection

Synopsis

tcp.disconnect

Valuessaddr



flagsTCP flags (e.g. FIN, etc)




sockNetwork socket

ContextThe process which disconnects tcp

Nameprobe::tcp.disconnect.return — TCP socket disconnection complete

Synopsis

tcp.disconnect.return

91

Valuesret

Error code (0: no error)


ContextThe process which disconnects tcp

Nameprobe::tcp.setsockopt — Call to setsockopt

Synopsis

tcp.setsockopt

Valuesoptstr

Resolves optname to a human-readable format

levelThe level at which the socket options will be manipulated

optlenUsed to access values for setsockopt


optnameTCP socket options (e.g. TCP_NODELAY, TCP_MAXSEG, etc)

sockNetwork socket

ContextThe process which calls setsockopt

Nameprobe::tcp.setsockopt.return — Return from setsockopt

Synopsis


92

tcp.setsockopt.return

Valuesret



ContextThe process which calls setsockopt

Nameprobe::tcp.receive — Called when a TCP packet is received

Synopsis

tcp.receive

Valuesurg

TCP URG flag

protocolPacket protocol from driver

pshTCP PSH flag


rstTCP RST flag


saddrA string representing the source IP address


ackTCP ACK flag

finTCP FIN flag

93

synTCP SYN flag


iphdrIP header address

Nameprobe::udp.sendmsg — Fires whenever a process sends a UDP message

Synopsis

udp.sendmsg

Valuesname

The name of this probe

sizeNumber of bytes sent by the process

sockNetwork socket used by the process

ContextThe process which sent a UDP message

Nameprobe::udp.sendmsg.return — Fires whenever an attempt to send a UDP message is completed

Synopsis

udp.sendmsg.return

Valuesname


sizeNumber of bytes sent by the process

ContextThe process which sent a UDP message


94

Nameprobe::udp.recvmsg — Fires whenever a UDP message is received

Synopsis

udp.recvmsg

Valuesname


sizeNumber of bytes received by the process


ContextThe process which received a UDP message

Nameprobe::udp.recvmsg.return — Fires whenever an attempt to receive a UDP message received iscompleted

Synopsis

udp.recvmsg.return

Valuesname


sizeNumber of bytes received by the process

ContextThe process which received a UDP message

Nameprobe::udp.disconnect — Fires when a process requests for a UDP disconnection

Synopsis

95

udp.disconnect

Valuesflags

Flags (e.g. FIN, etc)

nameThe name of this probe


ContextThe process which requests a UDP disconnection

Nameprobe::udp.disconnect.return — UDP has been disconnected successfully

Synopsis

udp.disconnect.return

Valuesret


nameThe name of this probe

ContextThe process which requested a UDP disconnection

Namefunction::ip_ntop — returns a string representation from an integer IP number

Synopsis

function ip_ntop:string(addr:long)

Argumentsaddr

the ip represented as an integer

96

Chapter 12.

97

Socket TapsetThis family of probe points is used to probe socket activities. It contains the following probe points:

Nameprobe::socket.send — Message sent on a socket.

Synopsis

socket.send

Valuessuccess

Was send successful? (1 = yes, 0 = no)

protocolProtocol value

flagsSocket flags value


stateSocket state value

sizeSize of message sent (in bytes) or error code if success = 0

typeSocket type value

familyProtocol family value

ContextThe message sender

Nameprobe::socket.receive — Message received on a socket.

Synopsis

socket.receive

Chapter 12. Socket Tapset

98

Valuessuccess






sizeSize of message received (in bytes) or error code if success = 0



ContextThe message receiver

Nameprobe::socket.sendmsg — Message is currently being sent on a socket.

Synopsis

socket.sendmsg

Valuesprotocol

Protocol value




sizeMessage size in bytes

99




DescriptionFires at the beginning of sending a message on a socket via the sock_sendmsg function

Nameprobe::socket.sendmsg.return — Return from socket.sendmsg.

Synopsis

socket.sendmsg.return

Valuessuccess









ContextThe message sender.


100

DescriptionFires at the conclusion of sending a message on a socket via the sock_sendmsg function

Nameprobe::socket.recvmsg — Message being received on socket

Synopsis

socket.recvmsg

Valuesprotocol

Protocol value







ContextThe message receiver.

DescriptionFires at the beginning of receiving a message on a socket via the sock_recvmsg function

Nameprobe::socket.recvmsg.return — Return from Message being received on socket

Synopsis

socket.recvmsg.return

101

Valuessuccess

Was receive successful? (1 = yes, 0 = no)









DescriptionFires at the conclusion of receiving a message on a socket via the sock_recvmsg function.

Nameprobe::socket.aio_write — Message send via sock_aio_write

Synopsis

socket.aio_write

Valuesprotocol

Protocol value




102






DescriptionFires at the beginning of sending a message on a socket via the sock_aio_write function

Nameprobe::socket.aio_write.return — Conclusion of message send via sock_aio_write

Synopsis

socket.aio_write.return

Valuessuccess









103


DescriptionFires at the conclusion of sending a message on a socket via the sock_aio_write function

Nameprobe::socket.aio_read — Receiving message via sock_aio_read

Synopsis

socket.aio_read

Valuesprotocol

Protocol value








DescriptionFires at the beginning of receiving a message on a socket via the sock_aio_read function

Nameprobe::socket.aio_read.return — Conclusion of message received via sock_aio_read


104

Synopsis

socket.aio_read.return

Valuessuccess










DescriptionFires at the conclusion of receiving a message on a socket via the sock_aio_read function

Nameprobe::socket.writev — Message sent via socket_writev

Synopsis

socket.writev

Valuesprotocol

Protocol value

105








DescriptionFires at the beginning of sending a message on a socket via the sock_writev function

Nameprobe::socket.writev.return — Conclusion of message sent via socket_writev

Synopsis

socket.writev.return

Valuessuccess








106




DescriptionFires at the conclusion of sending a message on a socket via the sock_writev function

Nameprobe::socket.readv — Receiving a message via sock_readv

Synopsis

socket.readv

Valuesprotocol

Protocol value








DescriptionFires at the beginning of receiving a message on a socket via the sock_readv function

107

Nameprobe::socket.readv.return — Conclusion of receiving a message via sock_readv

Synopsis

socket.readv.return

Valuessuccess










DescriptionFires at the conclusion of receiving a message on a socket via the sock_readv function

Nameprobe::socket.create — Creation of a socket

Synopsis

socket.create


108

Valuesprotocol

Protocol value


requesterRequested by user process or the kernel (1 = kernel, 0 = user)



ContextThe requester (see requester variable)

DescriptionFires at the beginning of creating a socket.

Nameprobe::socket.create.return — Return from Creation of a socket

Synopsis

socket.create.return

Valuessuccess

Was socket creation successful? (1 = yes, 0 = no)


errError code if success == 0


requesterRequested by user process or the kernel (1 = kernel, 0 = user)


109


ContextThe requester (user process or kernel)

DescriptionFires at the conclusion of creating a socket.

Nameprobe::socket.close — Close a socket

Synopsis

socket.close

Valuesprotocol

Protocol value







DescriptionFires at the beginning of closing a socket.

Nameprobe::socket.close.return — Return from closing a socket


110

Synopsis

socket.close.return

Valuesname

Name of this probe


DescriptionFires at the conclusion of closing a socket.

Namefunction::sock_prot_num2str — Given a protocol number, return a string representation.

Synopsis

function sock_prot_num2str:string(proto:long)

Argumentsproto

The protocol number.

Namefunction::sock_prot_str2num — Given a protocol name (string), return the corresponding protocolnumber.

Synopsis

function sock_prot_str2num:long(proto:string)

Argumentsproto

The protocol name.

Namefunction::sock_fam_num2str — Given a protocol family number, return a string representation.

111

Synopsis

function sock_fam_num2str:string(family:long)

Argumentsfamily

The family number.

Namefunction::sock_fam_str2num — Given a protocol family name (string), return the corresponding

Synopsis

function sock_fam_str2num:long(family:string)

Argumentsfamily

The family name.

Descriptionprotocol family number.

Namefunction::sock_state_num2str — Given a socket state number, return a string representation.

Synopsis

function sock_state_num2str:string(state:long)

Argumentsstate

The state number.

Namefunction::sock_state_str2num — Given a socket state string, return the corresponding state number.

Synopsis

function sock_state_str2num:long(state:string)


112

Argumentsstate

The state name.

Chapter 13.

113

Kernel Process TapsetThis family of probe points is used to probe process-related activities. It contains the following probepoints:

Nameprobe::kprocess.create — Fires whenever a new process is successfully created

Synopsis

kprocess.create

Valuesnew_pid

The PID of the newly created process

ContextParent of the created process.

DescriptionFires whenever a new process is successfully created, either as a result of fork (or one of its syscallvariants), or a new kernel thread.

Nameprobe::kprocess.start — Starting new process

Synopsis

kprocess.start

ValuesNone

ContextNewly created process.

DescriptionFires immediately before a new process begins execution.

Nameprobe::kprocess.exec — Attempt to exec to a new program

Chapter 13. Kernel Process Tapset

114

Synopsis

kprocess.exec

Valuesfilename

The path to the new executable

ContextThe caller of exec.

DescriptionFires whenever a process attempts to exec to a new program.

Nameprobe::kprocess.exec_complete — Return from exec to a new program

Synopsis

kprocess.exec_complete

Valuessuccess

A boolean indicating whether the exec was successful

errnoThe error number resulting from the exec

ContextOn success, the context of the new executable. On failure, remains in the context of the caller.

DescriptionFires at the completion of an exec call.

Nameprobe::kprocess.exit — Exit from process

Synopsis

kprocess.exit

115

Valuescode

The exit code of the process

ContextThe process which is terminating.

DescriptionFires when a process terminates. This will always be followed by a kprocess.release, though the lattermay be delayed if the process waits in a zombie state.

Nameprobe::kprocess.release — Process released

Synopsis

kprocess.release

Valuespid

PID of the process being released

taskA task handle to the process being released

ContextThe context of the parent, if it wanted notification of this process' termination, else the context of theprocess itself.

DescriptionFires when a process is released from the kernel. This always follows a kprocess.exit, though it maybe delayed somewhat if the process waits in a zombie state.

116

Chapter 14.

117

Signal TapsetThis family of probe points is used to probe signal activities. It contains the following probe points:

Nameprobe::signal.send — Signal being sent to a process

Synopsis

signal.send

Valuessend2queue

Indicates whether the signal is sent to an existing sigqueue

nameThe name of the function used to send out the signal

taskA task handle to the signal recipient

sinfoThe address of siginfo struct

si_codeIndicates the signal type

sig_nameA string representation of the signal

sigThe number of the signal

sharedIndicates whether the signal is shared by the thread group

sig_pidThe PID of the process receiving the signal

pid_nameThe name of the signal recipient

ContextThe signal's sender.

Nameprobe::signal.send.return — Signal being sent to a process completed

Chapter 14. Signal Tapset

118

Synopsis

signal.send.return

Valuesretstr

The return value to either __group_send_sig_info, specific_send_sig_info, or send_sigqueue

send2queueIndicates whether the sent signal was sent to an existing sigqueue

nameThe name of the function used to send out the signal

sharedIndicates whether the sent signal is shared by the thread group.

ContextThe signal's sender. (correct?)

DescriptionPossible __group_send_sig_info and specific_send_sig_info return values are as follows;

0 -- The signal is sucessfully sent to a process,

which means that(1) the signal was ignored by the receiving process, (2) this is a non-RT signal and the system alreadyhas one queued, and (3) the signal was successfully added to the sigqueue of the receiving process.

-EAGAIN -- The sigqueue of the receiving process is overflowing, the signal was RT, and the signalwas sent by a user using something other than kill.

Possible send_group_sigqueue and send_sigqueue return values are as follows;

0 -- The signal was either sucessfully added into the sigqueue of the receiving process, or a SI_TIMERentry is already queued (in which case, the overrun count will be simply incremented).

1 -- The signal was ignored by the receiving process.

-1 -- (send_sigqueue only) The task was marked exiting, allowing * posix_timer_event to redirect it tothe group leader.

Nameprobe::signal.checkperm — Check being performed on a sent signal

Synopsis

119

signal.checkperm

Valuesname


taskA task handle to the signal recipient

sinfoThe address of the siginfo structure

si_codeIndicates the signal type



pid_nameName of the process receiving the signal


Nameprobe::signal.checkperm.return — Check performed on a sent signal completed

Synopsis

signal.checkperm.return

Valuesretstr

Return value as a string


Nameprobe::signal.wakeup — Sleeping process being wakened for signal

Synopsis

signal.wakeup


120

Valuesresume

Indicates whether to wake up a task in a STOPPED or TRACED state

state_maskA string representation indicating the mask of task states to wake. Possible values areTASK_INTERRUPTIBLE, TASK_STOPPED, TASK_TRACED, and TASK_INTERRUPTIBLE.

pid_nameName of the process to wake

sig_pidThe PID of the process to wake

Nameprobe::signal.check_ignored — Checking to see signal is ignored

Synopsis

signal.check_ignored

Valuessig_name

A string representation of the signal




Nameprobe::signal.check_ignored.return — Check to see signal is ignored completed

Synopsis

signal.check_ignored.return

Valuesretstr



121

Nameprobe::signal.force_segv — Forcing send of SIGSEGV

Synopsis

signal.force_segv

Valuesname






Nameprobe::signal.force_segv.return — Forcing send of SIGSEGV complete

Synopsis

signal.force_segv.return

Valuesretstr



Nameprobe::signal.syskill — Sending kill signal to a process

Synopsis

signal.syskill


122

Valuesname



sigThe specific signal sent to the process



Nameprobe::signal.syskill.return — Sending kill signal completed

Synopsis

signal.syskill.return

ValuesNone

Nameprobe::signal.sys_tkill — Sending a kill signal to a thread

Synopsis

signal.sys_tkill

Valuesname



sigThe specific signal sent to the process


123

sig_pidThe PID of the process receiving the kill signal

DescriptionThe tkill call is analogous to kill(2), except that it also allows a process within a specific thread group tobe targeted. Such processes are targeted through their unique thread IDs (TID).

Nameprobe::signal.systkill.return — Sending kill signal to a thread completed

Synopsis

signal.systkill.return

Valuesretstr

The return value to either __group_send_sig_info,


Nameprobe::signal.sys_tgkill — Sending kill signal to a thread group

Synopsis

signal.sys_tgkill

Valuesname



sigThe specific kill signal sent to the process

tgidThe thread group ID of the thread receiving the kill signal


sig_pidThe PID of the thread receiving the kill signal


124

DescriptionThe tgkill call is similar to tkill, except that it also allows the caller to specify the thread group ID of thethread to be signalled. This protects against TID reuse.

Nameprobe::signal.sys_tgkill.return — Sending kill signal to a thread group completed

Synopsis

signal.sys_tgkill.return

Valuesretstr

The return value to either __group_send_sig_info,


Nameprobe::signal.send_sig_queue — Queuing a signal to a process

Synopsis

signal.send_sig_queue

Valuessigqueue_addr

The address of the signal queue



sigThe queued signal

pid_nameName of the process to which the signal is queued

sig_pidThe PID of the process to which the signal is queued

Nameprobe::signal.send_sig_queue.return — Queuing a signal to a process completed

125

Synopsis

signal.send_sig_queue.return

Valuesretstr



Nameprobe::signal.pending — Examining pending signal

Synopsis

signal.pending

Valuesname


sigset_sizeThe size of the user-space signal set

sigset_addThe address of the user-space signal set (sigset_t)

DescriptionThis probe is used to examine a set of signals pending for delivery to a specific thread. This normallyoccurs when the do_sigpending kernel function is executed.

Nameprobe::signal.pending.return — Examination of pending signal completed

Synopsis

signal.pending.return

Valuesretstr



126


Nameprobe::signal.handle — Signal handler being invoked

Synopsis

signal.handle

Valuesregs

The address of the kernel-mode stack area

sig_codeThe si_code value of the siginfo signal


sig_modeIndicates whether the signal was a user-mode or kernel-mode signal

sinfoThe address of the siginfo table


oldset_addrThe address of the bitmask array of blocked signals

sigThe signal number that invoked the signal handler

ka_addrThe address of the k_sigaction table associated with the signal

Nameprobe::signal.handle.return — Signal handler invocation completed

Synopsis

signal.handle.return

127

Valuesretstr



Nameprobe::signal.do_action — Examining or changing a signal action

Synopsis

signal.do_action

Valuessa_mask

The new mask of the signal



oldsigact_addrThe address of the old sigaction struct associated with the signal

sigThe signal to be examined/changed

sa_handlerThe new handler of the signal

sigact_addrThe address of the new sigaction struct associated with the signal

Nameprobe::signal.do_action.return — Examining or changing a signal action completed

Synopsis

signal.do_action.return

Valuesretstr



128


Nameprobe::signal.procmask — Examining or changing blocked signals

Synopsis

signal.procmask

Valueshow

Indicates how to change the blocked signals; possible values are SIG_BLOCK=0 (for blockingsignals), SIG_UNBLOCK=1 (for unblocking signals), and SIG_SETMASK=2 for setting the signalmask.


oldsigset_addrThe old address of the signal set (sigset_t)

sigsetThe actual value to be set for sigset_t (correct?)

sigset_addrThe address of the signal set (sigset_t) to be implemented

Nameprobe::signal.procmask.return — Examining or changing blocked signals completed

Synopsis

signal.procmask.return

Valuesretstr



Nameprobe::signal.flush — Flushing all pending signals for a task

129

Synopsis

signal.flush

Valuesname


taskThe task handler of the process performing the flush

pid_nameThe name of the process associated with the task performing the flush

sig_pidThe PID of the process associated with the task performing the flush

130

Chapter 15.

131

Directory-entry (dentry) TapsetThis family of functions is used to map kernel VFS directory entry pointers to file or full path names.

Namefunction::d_name — get the dirent name

Synopsis

function d_name:string(dentry:long)

Argumentsdentry

Pointer to dentry.

DescriptionReturns the dirent name (path basename).

Namefunction::reverse_path_walk — get the full dirent path

Synopsis

function reverse_path_walk:string(dentry:long)

Argumentsdentry

Pointer to dentry.

DescriptionReturns the path name (partial path to mount point).

Namefunction::task_dentry_path — get the full dentry path

Synopsis

function task_dentry_path:string(task:long,dentry:long,vfsmnt:long)

Chapter 15. Directory-entry (dentry) Tapset

132

Argumentstask


dentrydirentry pointer.

vfsmntvfsmnt pointer.

DescriptionReturns the full dirent name (full path to the root), like the kernel d_path function.

Namefunction::d_path — get the full nameidata path

Synopsis

function d_path:string(nd:long)

Argumentsnd

Pointer to nameidata.

DescriptionReturns the full dirent name (full path to the root), like the kernel d_path function.

Chapter 16.

133

Logging TapsetThis family of functions is used to send simple message strings to various destinations.

Namefunction::log — Send a line to the common trace buffer.

Synopsis

function log(msg:string)

Argumentsmsg

The formatted message string.

General Syntaxlog(msg:string)

DescriptionThis function logs data. log sends the message immediately to staprun and to the bulk transport(relayfs) if it is being used. If the last character given is not a newline, then one is added. This functionis not as effecient as printf and should be used only for urgent messages.

Namefunction::warn — Send a line to the warning stream.

Synopsis

function warn(msg:string)

Argumentsmsg


General Syntaxwarn (msg:string)

DescriptionThis function sends a warning message immediately to staprun. It is also sent over the bulk transport(relayfs) if it is being used. If the last characater is not a newline, the one is added.

Chapter 16. Logging Tapset

134

Namefunction::exit — Start shutting down probing script.

Synopsis

function exit()

ArgumentsNone

General Syntaxexit

DescriptionThis only enqueues a request to start shutting down the script. New probes will not fire (except “end”probes), but all currently running ones may complete their work.

Namefunction::error — Send an error message.

Synopsis

function error(msg:string)

Argumentsmsg


DescriptionAn implicit end-of-line is added. staprun prepends the string “ERROR:”. Sending an error messageaborts the currently running probe. Depending on the MAXERRORS parameter, it may trigger anexit.

Namefunction::ftrace — Send a message to the ftrace ring-buffer.

Synopsis

function ftrace(msg:string)

135

Argumentsmsg


DescriptionIf the ftrace ring-buffer is configured & available, see /debugfs/tracing/trace for the message.Otherwise, the message may be quietly dropped. An implicit end-of-line is added.

136

Chapter 17.

137

Random functions TapsetThese functions deal with random number generation.

Namefunction::randint — Return a random number between [0,n)

Synopsis

function randint:long(n:long)

Argumentsn

Number past upper limit of range, not larger than 2**20.

138

Chapter 18.

139

String and data retrieving functionsTapsetFunctions to retrieve strings and other primitive types from the kernel or a user space programs basedon addresses. All strings are of a maximum length given by MAXSTRINGLEN.

Namefunction::kernel_string — Retrieves string from kernel memory.

Synopsis

function kernel_string:string(addr:long)

Argumentsaddr

The kernel address to retrieve the string from.

General Syntaxkernel_string:string(addr:long)

DescriptionThis function returns the null terminated C string from a given kernel memory address. Reports anerror on string copy fault.

Namefunction::kernel_string2 — Retrieves string from kernel memory with alternative error string.

Synopsis

function kernel_string2:string(addr:long,err_msg:string)

Argumentsaddr


err_msgThe error message to return when data isn't available.

General Syntaxkernel_string2:string(addr:long, err_msg:string)

Chapter 18. String and data retrieving functions Tapset

140

DescriptionThis function returns the null terminated C string from a given kernel memory address. Reports thegiven error message on string copy fault.

Namefunction::kernel_string_n — Retrieves string of given length from kernel memory.

Synopsis

function kernel_string_n:string(addr:long,n:long)

Argumentsaddr


nThe maximum length of the string (if not null terminated).

General Syntaxkernel_string_n:string(addr:long, n:long)

DescriptionReturns the C string of a maximum given length from a given kernel memory address. Reports anerror on string copy fault.

Namefunction::kernel_long — Retrieves a long value stored in kernel memory.

Synopsis

function kernel_long:long(addr:long)

Argumentsaddr

The kernel address to retrieve the long from.

General Syntaxkernel_long:long(addr:long)

DescriptionReturns the long value from a given kernel memory address. Reports an error when reading from thegiven address fails.

141

Namefunction::kernel_int — Retrieves an int value stored in kernel memory.

Synopsis

function kernel_int:long(addr:long)

Argumentsaddr

The kernel address to retrieve the int from.

DescriptionReturns the int value from a given kernel memory address. Reports an error when reading from thegiven address fails.

Namefunction::kernel_short — Retrieves a short value stored in kernel memory.

Synopsis

function kernel_short:long(addr:long)

Argumentsaddr

The kernel address to retrieve the short from.

General Syntaxkernel_short:long(addr:long)

DescriptionReturns the short value from a given kernel memory address. Reports an error when reading from thegiven address fails.

Namefunction::kernel_char — Retrieves a char value stored in kernel memory.

Synopsis

function kernel_char:long(addr:long)


142

Argumentsaddr

The kernel address to retrieve the char from.

General Syntaxkernel_char:long(addr:long)

DescriptionReturns the char value from a given kernel memory address. Reports an error when reading from thegiven address fails.

Namefunction::kernel_pointer — Retrieves a pointer value stored in kernel memory.

Synopsis

function kernel_pointer:long(addr:long)

Argumentsaddr

The kernel address to retrieve the pointer from.

General Syntaxkernel_pointer:long(addr:long)

DescriptionReturns the pointer value from a given kernel memory address. Reports an error when reading fromthe given address fails.

Namefunction::user_string — Retrieves string from user space.

Synopsis

function user_string:string(addr:long)

Argumentsaddr

The user space address to retrieve the string from.

143

General Syntaxuser_string:string(addr:long)

DescriptionReturns the null terminated C string from a given user space memory address. Reports “<unknown>”on the rare cases when userspace data is not accessible.

Namefunction::user_string2 — Retrieves string from user space with alternative error string.

Synopsis

function user_string2:string(addr:long,err_msg:string)

Argumentsaddr



General Syntaxuser_string2:string(addr:long, err_msg:string)

DescriptionReturns the null terminated C string from a given user space memory address. Reports the given errormessage on the rare cases when userspace data is not accessible.

Namefunction::user_string_warn — Retrieves string from user space.

Synopsis

function user_string_warn:string(addr:long)

Argumentsaddr


General Syntaxuser_string_warn:string(addr:long)


144

DescriptionReturns the null terminated C string from a given user space memory address. Reports “<unknown>”on the rare cases when userspace data is not accessible and warns (but does not abort) about thefailure.

Namefunction::user_string_quoted — Retrieves and quotes string from user space.

Synopsis

function user_string_quoted:string(addr:long)

Argumentsaddr


General Syntaxuser_string_quoted:string(addr:long)

DescriptionReturns the null terminated C string from a given user space memory address where any ASCIIcharacters that are not printable are replaced by the corresponding escape sequence in the returnedstring. Reports “NULL” for address zero. Returns “<unknown>” on the rare cases when userspacedata is not accessible at the given address.

Namefunction::user_string_n — Retrieves string of given length from user space.

Synopsis

function user_string_n:string(addr:long,n:long)

Argumentsaddr



General Syntaxuser_string_n:string(addr:long, n:long)

145

DescriptionReturns the C string of a maximum given length from a given user space address. Returns“<unknown>” on the rare cases when userspace data is not accessible at the given address.

Namefunction::user_string_n2 — Retrieves string of given length from user space.

Synopsis

function user_string_n2:string(addr:long,n:long,err_msg:string)

Argumentsaddr




General Syntaxuser_string_n2:string(addr:long, n:long, err_msg:string)

DescriptionReturns the C string of a maximum given length from a given user space address. Returns the givenerror message string on the rare cases when userspace data is not accessible at the given address.

Namefunction::user_string_n_warn — Retrieves string from user space.

Synopsis

function user_string_n_warn:string(addr:long,n:long)

Argumentsaddr




146

General Syntaxuser_string_n_warn:string(addr:long, n:long)

DescriptionReturns up to n characters of a C string from a given user space memory address. Reports“<unknown>” on the rare cases when userspace data is not accessible and warns (but does not abort)about the failure.

Namefunction::user_string_n_quoted — Retrieves and quotes string from user space.

Synopsis

function user_string_n_quoted:string(addr:long,n:long)

Argumentsaddr



General Syntaxuser_string_n_quoted:string(addr:long, n:long)

DescriptionReturns up to n characters of a C string from the given user space memory address where any ASCIIcharacters that are not printable are replaced by the corresponding escape sequence in the returnedstring. Reports “NULL” for address zero. Returns “<unknown>” on the rare cases when userspacedata is not accessible at the given address.

Namefunction::user_short — Retrieves a short value stored in user space.

Synopsis

function user_short:long(addr:long)

Argumentsaddr

The user space address to retrieve the short from.

147

General Syntaxuser_short:long(addr:long)

DescriptionReturns the short value from a given user space address. Returns zero when user space data is notaccessible.

Namefunction::user_short_warn — Retrieves a short value stored in user space.

Synopsis

function user_short_warn:long(addr:long)

Argumentsaddr

The user space address to retrieve the short from.

General Syntaxuser_short_warn:long(addr:long)

DescriptionReturns the short value from a given user space address. Returns zero when user space and warns(but does not abort) about the failure.

Namefunction::user_int — Retrieves an int value stored in user space.

Synopsis

function user_int:long(addr:long)

Argumentsaddr

The user space address to retrieve the int from.

General Syntaxuser_int:long(addr:long)


148

DescriptionReturns the int value from a given user space address. Returns zero when user space data is notaccessible.

Namefunction::user_int_warn — Retrieves an int value stored in user space.

Synopsis

function user_int_warn:long(addr:long)

Argumentsaddr

The user space address to retrieve the int from.

General Syntaxuser_ing_warn:long(addr:long)

DescriptionReturns the int value from a given user space address. Returns zero when user space and warns (butdoes not abort) about the failure.

Namefunction::user_long — Retrieves a long value stored in user space.

Synopsis

function user_long:long(addr:long)

Argumentsaddr

The user space address to retrieve the long from.

General Syntaxuser_long:long(addr:long)

DescriptionReturns the long value from a given user space address. Returns zero when user space data is notaccessible. Note that the size of the long depends on the architecture of the current user space task(for those architectures that support both 64/32 bit compat tasks).

149

Namefunction::user_long_warn — Retrieves a long value stored in user space.

Synopsis

function user_long_warn:long(addr:long)

Argumentsaddr

The user space address to retrieve the long from.

General Syntaxuser_long_warn:long(addr:long)

DescriptionReturns the long value from a given user space address. Returns zero when user space and warns(but does not abort) about the failure. Note that the size of the long depends on the architecture of thecurrent user space task (for those architectures that support both 64/32 bit compat tasks).

Namefunction::user_char — Retrieves a char value stored in user space.

Synopsis

function user_char:long(addr:long)

Argumentsaddr

The user space address to retrieve the char from.

General Syntaxuser_char:long(addr:long)

DescriptionReturns the char value from a given user space address. Returns zero when user space data is notaccessible.

Namefunction::user_char_warn — Retrieves a char value stored in user space.


150

Synopsis

function user_char_warn:long(addr:long)

Argumentsaddr

The user space address to retrieve the char from.

General Syntaxuser_char_warn:long(addr:long)

DescriptionReturns the char value from a given user space address. Returns zero when user space and warns(but does not abort) about the failure.

Chapter 19.

151

A collection of standard stringfunctionsFunctions to get the length, a substring, getting at individual characters, string seaching, escaping,tokenizing, and converting strings to longs.

Namefunction::strlen — Returns the length of a string.

Synopsis

function strlen:long(s:string)

Argumentss

the string

General Syntaxstrlen: long (str:string)

DescriptionThis function returns the length of the string, which can be zero up to MAXSTRINGLEN.

Namefunction::substr — Returns a substring.

Synopsis

function substr:string(str:string,start:long,length:long)

Argumentsstr

The string to take a substring from

startStarting position. 0 = start of the string.

lengthLength of string to return.

General Syntaxsubstr:string (str:string, start:long, stop:long)

Chapter 19. A collection of standard string functions

152

DescriptionReturns the substring of the up to the given length starting at the given start position and ending atgiven stop position.

Namefunction::stringat — Returns the char at a given position in the string.

Synopsis

function stringat:long(str:string,pos:long)

Argumentsstr

The string to fetch the character from.

posThe position to get the character from. 0 = start of the string.

General Syntaxstringat:long(srt:string, pos:long)

DescriptionThis function returns the character at a given position in the string or zero if thestring doesn't have asmany characters.

Namefunction::isinstr — Returns whether a string is a substring of another string.

Synopsis

function isinstr:long(s1:string,s2:string)

Argumentss1

String to search in.

s2Substring to find.

General syntaxisinstr:long (s1:string, s2:string)

153

DescriptionThis function returns 1 if string s1 contains s2, otherwise zero.

Namefunction::text_str — Escape any non-printable chars in a string.

Synopsis

function text_str:string(input:string)

Argumentsinput

The string to escape.

General Syntaxtext_str:string (input:string)

DescriptionThis function accepts a string argument, and any ASCII characters that are not printable are replacedby the corresponding escape sequence in the returned string.

Namefunction::text_strn — Escape any non-printable chars in a string.

Synopsis

function text_strn:string(input:string,len:long,quoted:long)

Argumentsinput

The string to escape.

lenMaximum length of string to return. 0 means MAXSTRINGLEN.

quotedPut double quotes around the string. If input string is truncated it will have “...” after the secondquote.

General Syntaxtext_strn:string (input:string, len:long, quoted:long)


154

DescriptionThis function accepts a string of designated length, and any ASCII characters that are not printable arereplaced by the corresponding escape sequence in the returned string.

Namefunction::tokenize — Return the next non-empty token in a string.

Synopsis

function tokenize:string(input:string,delim:string)

Argumentsinput

String to tokenize. If NULL, returns the next non-empty token in the string passed in the previouscall to tokenize.

delimToken delimiter. Set of characters that delimit the tokens.

General Syntaxtokenize:string (input:string, delim:string)

DescriptionThis function returns the next non-empty token in the given input string, where the tokens are delimitedby characters in the delim string. If the input string is non-NULL, it returns the first token. If the inputstring is NULL, it returns the next token in the string passed in the previous call to tokenize. If nodelimiter is found, the entire remaining input string is returned. It returns NULL when no more tokensare available.

Namefunction::str_replace — str_replace Replaces all instances of a substring with another.

Synopsis

function str_replace:string(prnt_str:string,srch_str:string,rplc_str:string)

Argumentsprnt_str

The string to search and replace in.

srch_strThe substring which is used to search in prnt_str string.

155

rplc_strThe substring which is used to replace srch_str.

General Syntaxstr_replace:string(prnt_str:string, srch_str:string, rplc_str:string)

DescriptionThis function returns the given string with substrings replaced.

Namefunction::strtol — strtol - Convert a string to a long.

Synopsis

function strtol:long(str:string,base:long)

Argumentsstr

String to convert.

baseThe base to use

General Syntaxstrtol:long (str:string, base:long)

DescriptionThis function converts the string representation of a number to an integer. The base parameterindicates the number base to assume for the string (eg. 16 for hex, 8 for octal, 2 for binary).

Namefunction::isdigit — Checks for a digit.

Synopsis

function isdigit:long(str:string)

Argumentsstr

String to check.


156

General Syntaxisdigit:long(str:string)

DescriptionChecks for a digit (0 through 9) as the first character of a string. Returns non-zero if true, and a zero iffalse.

Chapter 20.

157

Utility functions for using ansi controlchars in logsUtility functions for logging using ansi control characters. This lets you manipulate the cursor positionand character color output and attributes of log messages.

Namefunction::ansi_clear_screen — Move cursor to top left and clear screen.

Synopsis

function ansi_clear_screen()

ArgumentsNone

General Syntaxansi_clear_screen

DescriptionSends ansi code for moving cursor to top left and then the ansi code for clearing the screen from thecursor position to the end.

Namefunction::ansi_set_color — Set the ansi Select Graphic Rendition mode.

Synopsis

function ansi_set_color(fg:long)

Argumentsfg

Foreground color to set.

General Syntaxansi_set_color(fh:long)

DescriptionSends ansi code for Select Graphic Rendition mode for the given forground color. Black (30), Blue(34), Green (32), Cyan (36), Red (31), Purple (35), Brown (33), Light Gray (37).

Chapter 20. Utility functions for using ansi control chars in logs

158

Namefunction::ansi_set_color2 — Set the ansi Select Graphic Rendition mode.

Synopsis

function ansi_set_color2(fg:long,bg:long)

Argumentsfg


bgBackground color to set.

General Syntaxansi_set_color2(fg:long, bg:long)

DescriptionSends ansi code for Select Graphic Rendition mode for the given forground color, Black (30),Blue (34), Green (32), Cyan (36), Red (31), Purple (35), Brown (33), Light Gray (37) and the givenbackground color, Black (40), Red (41), Green (42), Yellow (43), Blue (44), Magenta (45), Cyan (46),White (47).

Namefunction::ansi_set_color3 — Set the ansi Select Graphic Rendition mode.

Synopsis

function ansi_set_color3(fg:long,bg:long,attr:long)

Argumentsfg


bgBackground color to set.

attrColor attribute to set.

General Syntaxansi_set_color3(fg:long, bg:long, attr:long)

159

DescriptionSends ansi code for Select Graphic Rendition mode for the given forground color, Black (30), Blue(34), Green (32), Cyan (36), Red (31), Purple (35), Brown (33), Light Gray (37), the given backgroundcolor, Black (40), Red (41), Green (42), Yellow (43), Blue (44), Magenta (45), Cyan (46), White (47)and the color attribute All attributes off (0), Intensity Bold (1), Underline Single (4), Blink Slow (5), BlinkRapid (6), Image Negative (7).

Namefunction::ansi_reset_color — Resets Select Graphic Rendition mode.

Synopsis

function ansi_reset_color()

ArgumentsNone

General Syntaxansi_reset_color

DescriptionSends ansi code to reset foreground, background and color attribute to default values.

Namefunction::ansi_new_line — Move cursor to new line.

Synopsis

function ansi_new_line()

ArgumentsNone

General Syntaxansi_new_line

DescriptionSends ansi code new line.

Namefunction::ansi_cursor_move — Move cursor to new coordinates.

Chapter 20. Utility functions for using ansi control chars in logs

160

Synopsis

function ansi_cursor_move(x:long,y:long)

Argumentsx

Row to move the cursor to.

yColomn to move the cursor to.

General Syntaxansi_curos_move(x:long, y:long)

DescriptionSends ansi code for positioning the cursor at row x and column y. Coordinates start at one, (1,1) is thetop-left corner.

Namefunction::ansi_cursor_hide — Hides the cursor.

Synopsis

function ansi_cursor_hide()

ArgumentsNone

General Syntaxansi_cusor_hide

DescriptionSends ansi code for hiding the cursor.

Namefunction::ansi_cursor_save — Saves the cursor position.

Synopsis

function ansi_cursor_save()

161

ArgumentsNone

General Syntaxansi_cursor_save

DescriptionSends ansi code for saving the current cursor position.

Namefunction::ansi_cursor_restore — Restores a previously saved cursor position.

Synopsis

function ansi_cursor_restore()

ArgumentsNone

General Syntaxansi_cursor_restore

DescriptionSends ansi code for restoring the current cursor position previously saved with ansi_cursor_save.

Namefunction::ansi_cursor_show — Shows the cursor.

Synopsis

function ansi_cursor_show()

ArgumentsNone

General Syntaxansi_cursor_show

DescriptionSends ansi code for showing the cursor.

162

Documents

SystemTap Tapset Reference - linux. · PDF fileSystemTap Tapset Reference Red Hat Enterprise Linux 6 SystemTap Tapset Reference For SystemTap in Red Hat Enterprise Linux 6 Edition