<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="TapsetRef">
 <bookinfo>
  <title>SystemTap Tapset Reference Manual</title>
<!--starthere-->
  <copyright>
   <year>2008-2025</year> <!-- PRERELEASE -->
   <holder>Red Hat, Inc. and others</holder>
  </copyright>

  <authorgroup>
   <author>
    <othername>SystemTap</othername>
    <contrib>Hackers</contrib>
   </author>
  </authorgroup>


  <legalnotice>
   <para>
     This documentation is free software; you can redistribute
     it and/or modify it under the terms of the GNU General Public
     License version 2 as published by the Free Software Foundation.
   </para>
      
   <para>
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     See the GNU General Public License for more details.
   </para>
      
   <para>
     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., 51 Franklin Street, Fifth Floor,
     Boston, MA 02110-1301 USA.
   </para>
      
   <para>
     For more details see the file COPYING in the source
     distribution of Linux.
   </para>
  </legalnotice>
 </bookinfo>
<!-- pls dont remove marker comments, as they are used in publican conversion-->
<toc></toc>
<chapter id="introduction">
  <title>Introduction</title>
  <para>
    SystemTap provides free software (GPL) infrastructure to simplify the
    gathering of information about the running Linux system. This assists
    diagnosis of a performance or functional problem. SystemTap eliminates 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.
  </para>

  <para>
    SystemTap provides a simple command line interface and scripting language
    for writing instrumentation for a live running kernel. The instrumentation
    makes extensive use of the probe points and functions provided in the
    <firstterm>tapset</firstterm> library. This document describes the various
    probe points and functions.
  </para>
  
    <section id="format">
      <title>Tapset Name Format</title>
	
      <para>In this guide, tapset definitions appear in the following format:</para>

      <screen>
	name:return (parameters)
	definition
      </screen>
	
      <para>
	The <replaceable>return</replaceable> field specifies what data type the
	tapset extracts and returns from the kernel during a probe (and thus,
	returns).  Tapsets use 2 data types for
	<replaceable>return</replaceable>: <literal>long</literal> (tapset
	extracts and returns an integer) and <literal>string</literal> (tapset
	extracts and returns a string).
      </para>

      <para>
	In some cases, tapsets do not have a <replaceable>return</replaceable>
	value. This simply means that the tapset does not extract anything from
	the kernel.  This is common among asynchronous events such as timers,
	exit functions, and print functions.
      </para>
<!--
<varlistentry>
<term></term>
<listitem>
	<para></para>
</listitem>
</varlistentry>
-->

    </section>
  
  </chapter>
<!--endhere-->
<!--markerforxi-->
<!-- pls dont remove marker comments, as they are used in publican conversion-->
  <chapter id="context_stp">
    <title>Context Functions</title>
    <para>
      The context functions provide additional information about where
      an event occurred.
      These functions can provide information such as a backtrace to 
      where the event occurred
      and the current register values for the processor.
    </para>
!Itapset/context.stp
!Itapset/linux/context.stp
!Itapset/linux/context-envvar.stp
!Itapset/linux/context-symbols.stp
!Itapset/linux/ucontext.stp
!Itapset/linux/ucontext-symbols.stp
!Itapset/linux/context-unwind.stp
!Itapset/linux/context-caller.stp
!Itapset/linux/ucontext-unwind.stp
!Itapset/linux/task.stp
!Itapset/linux/task_ancestry.stp
!Itapset/pn.stp
!Itapset/linux/pstrace.stp
!Itapset/registers.stp
  </chapter>

  <chapter id="timestamp_stp">
    <title>Timestamp Functions</title>
    <para>
      Each timestamp function returns a value to indicate when
      a function is executed.
      These returned values can then be used to indicate
      when an event occurred, provide an ordering for events, or compute
      the amount of time elapsed between two time stamps.
    </para>
!Itapset/linux/timestamp.stp
!Itapset/linux/timestamp_gtod.stp
!Itapset/linux/timestamp_monotonic.stp
!Itapset/stopwatch.stp
  </chapter>

  <chapter id="ctime.stp">
    <title>Time utility functions</title>
    <para>
      Utility functions to turn seconds since the epoch (as returned by
      the timestamp function gettimeofday_s()) into a human readable
      date/time strings.
    </para>
!Itapset/linux/ctime.stp
!Itapset/linux/tzinfo.stp
!Itapset/tzinfo.stp
  </chapter>


  <chapter id="system.stp">
    <title>Shell command functions</title>
    <para>
      Utility functions to enqueue shell commands.
    </para>
!Itapset/system.stp
  </chapter>

  <chapter id="memory_stp">
    <title>Memory Tapset</title>
 <para>
      This family of probe points is used to probe memory-related events
      or query the memory usage of the current process.
      It contains the following probe points:
    </para>
!Itapset/linux/memory.stp
!Itapset/linux/proc_mem.stp
  </chapter>

  <chapter id="task_time_stp">
    <title>Task Time Tapset</title>
    <para>
      This tapset defines utility functions to query time related
      properties of the current tasks, translate those in miliseconds
      and human readable strings.
    </para>
!Itapset/linux/task_time.stp
  </chapter>

  <chapter id="sched.stp">
    <title>Scheduler Tapset</title>
    <para>
      This family of probe points is used to probe the task scheduler activities.
      It contains the following probe points:
    </para>
!Itapset/linux/scheduler.stp
  </chapter>

  <chapter id="iosched.stp">
    <title>IO Scheduler and block IO Tapset</title>
    <para>
      This family of probe points is used to probe block IO layer and IO scheduler activities.
      It contains the following probe points:
    </para>
!Itapset/linux/ioscheduler.stp
!Itapset/linux/ioblock.stp
  </chapter>

  <chapter id="scsi.stp">
    <title>SCSI Tapset</title>
    <para>
      This family of probe points is used to probe SCSI activities.  
      It contains the following probe points:
    </para>
!Itapset/linux/scsi.stp
  </chapter>

  <chapter id="tty.stp">
    <title>TTY Tapset</title>
    <para>
      This family of probe points is used to probe TTY (Teletype) activities.
      It contains the following probe points:
    </para>
!Itapset/linux/tty.stp
  </chapter>

  <chapter id="irq.stp">
    <title>Interrupt Request (IRQ) Tapset</title>
    <para>
      This family of probe points is used to probe interrupt request
      (IRQ) activities.
      It contains the following probe points:
    </para>
!Itapset/linux/irq.stp
  </chapter>

  <chapter id="networking.stp">
    <title>Networking Tapset</title>
    <para>
      This family of probe points is used to probe the activities of
      the network device and protocol layers.
    </para>
!Itapset/linux/networking.stp
!Itapset/linux/tcp.stp
!Itapset/linux/udp.stp
!Itapset/linux/ip.stp
!Itapset/linux/inet.stp
!Itapset/linux/rpc.stp
!Itapset/linux/netfilter.stp
  </chapter>

  <chapter id="socket.stp">
    <title>Socket Tapset</title>
    <para>
      This family of probe points is used to probe socket activities.
      It contains the following probe points:
   </para>
!Itapset/linux/socket.stp
!Itapset/linux/inet_sock.stp
  </chapter>
  <chapter id="snmp.stp">
    <title>SNMP Information Tapset</title>
    <para>
      This family of probe points is used to probe socket activities to
      provide SNMP type information. It contains the following functions
      and probe points:
   </para>
!Itapset/linux/ipmib.stp
!Itapset/linux/ipmib-filter-default.stp
!Itapset/linux/tcpmib.stp
!Itapset/linux/tcpmib-filter-default.stp
!Itapset/linux/linuxmib.stp
!Itapset/linux/linuxmib-filter-default.stp
  </chapter>
  <chapter id="kprocess.stp">
    <title>Kernel Process Tapset</title>
    <para>
      This family of probe points is used to probe process-related activities.
      It contains the following probe points:
    </para>
!Itapset/linux/kprocess.stp
!Itapset/linux/target_set.stp
!Itapset/linux/loadavg.stp
  </chapter>
  <chapter id="signal.stp">
    <title>Signal Tapset</title>
    <para>
      This family of probe points is used to probe signal activities.
      It contains the following probe points:
    </para>
!Itapset/linux/signal.stp
  </chapter>
  <chapter id="errno.stp">
    <title>Errno Tapset</title>
    <para>
      This set of functions is used to handle errno number values.
      It contains the following functions:
    </para>
!Itapset/errno.stp
  </chapter>
  <chapter id="rlimit.stp">
    <title>RLIMIT Tapset</title>
    <para>
      This set of functions is used to handle string which defines resource limits (RLIMIT_*) and returns
      corresponding number of resource limit.
      It contains the following functions:
    </para>
!Itapset/linux/rlimit.stp
  </chapter>
  <chapter id="dev.stp">
    <title>Device Tapset</title>
    <para>
      This set of functions is used to handle kernel and userspace device numbers.
      It contains the following functions:
    </para>
!Itapset/linux/dev.stp
  </chapter>
  <chapter id="dentry.stp">
    <title>Directory-entry (dentry) Tapset</title>
    <para>
      This family of functions is used to map kernel VFS
      directory entry pointers to file or full path names.
    </para>
!Itapset/linux/dentry.stp
    </chapter>
  <chapter id="logging.stp">
    <title>Logging Tapset</title>
    <para>
      This family of functions is used to send simple
      message strings to various destinations.
    </para>
!Itapset/logging.stp
!Itapset/linux/logging.stp
    </chapter>
  <chapter id="queue_stats.stp">
    <title>Queue Statistics Tapset</title>
    <para>
      This family of functions is used to track performance of queuing systems.
    </para>
!Itapset/queue_stats.stp
    </chapter>
  <chapter id="random.stp">
    <title>Random functions Tapset</title>
    <para>
      These functions deal with random number generation.
    </para>
!Itapset/random.stp
    </chapter>
  <chapter id="conversions.stp">
    <title>String and data retrieving functions Tapset</title>
    <para>
      Functions to retrieve strings and other primitive types from
      the kernel or a user space programs based on addresses. All
      strings are of a maximum length given by MAXSTRINGLEN.
    </para>
!Itapset/linux/conversions.stp
!Itapset/linux/atomic.stp
!Itapset/uconversions.stp
   </chapter>

  <chapter id="conversions-guru.stp">
    <title>String and data writing functions Tapset</title>
    <para>
      The SystemTap guru mode can be used to test error handling
      in kernel code by simulating faults. The functions in the
      this tapset provide
      standard methods of writing to primitive types in the kernel's
      memory. All the functions in this tapset require the use of
      guru mode (<command>-g</command>).
    </para>
!Itapset/linux/conversions-guru.stp
!Itapset/uconversions-guru.stp
    </chapter>

  <chapter id="guru-delay.stp">
    <title>Guru tapsets</title>
    <para>
      Functions to deliberately interfere with the system's behavior, in
      order to inject faults or improve observability.
      All the functions in this tapset require the use of
      guru mode (<command>-g</command>).
    </para>
!Itapset/linux/guru-delay.stp
!Itapset/linux/panic.stp
!Itapset/linux/guru-signal.stp
  </chapter>

  <chapter id="string.stp">
    <title>A collection of standard string functions</title>
    <para>
      Functions to get the length, a substring, getting at individual
      characters, string seaching, escaping, tokenizing, and converting
      strings to longs.
    </para>
!Itapset/string.stp
!Itapset/tokenize.stp
!Itapset/regex.stp
    </chapter>
  <chapter id="ansi.stp">
    <title>Utility functions for using ansi control chars in logs</title>
    <para>
      Utility functions for logging using ansi control characters. This
      lets you manipulate the cursor position and character color output
      and attributes of log messages.
    </para>
!Itapset/ansi.stp
!Itapset/indent.stp
    </chapter>

  <chapter id="stap_staticmarkers.stp">
    <title>SystemTap Translator Tapset</title>
    <para>
      This family of user-space probe points is used to probe the operation of
      the SystemTap translator (<command>stap</command>) and run command
      (<command>staprun</command>).
      The tapset includes probes to watch the various phases of SystemTap
      and SystemTap's management of instrumentation cache.
      It contains the following probe points:
    </para>
!Itapset/stap_staticmarkers.stp
  </chapter>

  <chapter id="nfsd.stp">
    <title>Network File Storage Tapsets</title>
    <para>
      This family of probe points is used to probe network file storage
      functions and operations.
    </para>
!Itapset/linux/nfs_proc.stp
!Itapset/linux/nfs.stp
!Itapset/linux/nfsd.stp
!Itapset/linux/nfsderrno.stp
  </chapter>

  <chapter id="speculation.stp">
    <title>Speculation</title>
    <para>
      This family of functions provides the ability to speculative record
      information and then at a later point in the SystemTap script either
      commit the information or discard it.
    </para>
!Itapset/speculative.stp
  </chapter>

  <chapter id="json.stp">
    <title>JSON Tapset</title>
    <para>
      This family of probe points, functions, and macros is used to
      output data in JSON format.
      It contains the following probe points, functions, and macros:
    </para>
!Itapset/linux/json.stp
!Itapset/linux/json.stpm    
  </chapter>

  <chapter id="switchfile.stp">
    <title>Output file switching Tapset</title>
    <para>
      Utility function to allow switching of output files.
    </para>
!Itapset/switchfile.stp
  </chapter>

  <chapter id="floatingpoint.stp">
    <title>Floating point processing Tapset</title>
    <para>
      Utility functions to extract, convert, and perform arithmetic
      on IEEE-754 doubles.
    </para>
!Itapset/floatingpoint.stp
  </chapter>
  
  <chapter id="syscall_any.stp">
    <title>Syscall Any Tapset</title>
    <para>
      This family of probe points is designed to provide low cost
      instrumentation for cases where only the syscall name (or number)
      and return value are required and there is no need for the detailed
      syscall argument values. They are restricted versions of
      syscall.* and syscall.*.return.
    </para>
!Itapset/linux/syscall_any.stp
  </chapter>

  <chapter id="livepatch.stp">
    <title>CVE Livepatching Tapset</title>
    <para>
      Utility functions and control variables which can be used to create
      standardized CVE patches. The globals are cve_notify_p (non-zero if the
      patch should be verbose), cve_fix_p (non-zero if the fix should be applied),
      cve_trace_p (non-zero if only a trace should be run), cve_enabled_p (non-zero
      if the patch should be enabled). The controls can be changed in
      /proc/systemtap/MODULE_NAME/* and the recorded prometheus metrics can be
      viewed in the same directory.
    </para>
!Itapset/livepatch.stp
  </chapter>

!Syscalls

</book>