---

   stap    ( 1 )

---

PROCESSING

The translator begins pass 1 by parsing the given input script,
       and all scripts (files named *.stp) found in a tapset directory.
       The directories listed with -I are processed in sequence, each
       processed in "guru mode".  For each directory, a number of
       subdirectories are also searched.  These subdirectories are
       derived from the selected kernel version (the -R option), in
       order to allow more kernel-version-specific scripts to override
       less specific ones.  For example, for a kernel version
       2.6.12-23.FC3 the following patterns would be searched, in
       sequence: 2.6.12-23.FC3/*.stp, 2.6.12/*.stp, 2.6/*.stp, and
       finally *.stp.  Stopping the translator after pass 1 causes it to
       print the parse trees.

       In pass 2, the translator analyzes the input script to resolve
       symbols and types.  References to variables, functions, and probe
       aliases that are unresolved internally are satisfied by searching
       through the parsed tapset script files.  If any tapset script
       file is selected because it defines an unresolved symbol, then
       the entirety of that file is added to the translator's resolution
       queue.  This process iterates until all symbols are resolved and
       a subset of tapset script files is selected.

       Next, all probe point descriptions are validated against the wide
       variety supported by the translator.  Probe points that refer to
       code locations ("synchronous probe points") require the
       appropriate kernel debugging information to be installed.  In the
       associated probe handlers, target-side variables (whose names
       begin with "$") are found and have their run-time locations
       decoded.

       Next, all probes and functions are analyzed for optimization
       opportunities, in order to remove variables, expressions, and
       functions that have no useful value and no side-effect.
       Embedded-C functions are assumed to have side-effects unless they
       include the magic string /* pure */.  Since this optimization can
       hide latent code errors such as type mismatches or invalid
       $context variables, it sometimes may be useful to disable the
       optimizations with the -u option.

       Finally, all variable, function, parameter, array, and index
       types are inferred from context (literals and operators).
       Stopping the translator after pass 2 causes it to list all the
       probes, functions, and variables, along with all inferred types.
       Any inconsistent or unresolved types cause an error.

       In pass 3, the translator writes C code that represents the
       actions of all selected script files, and creates a Makefile to
       build that into a kernel object.  These files are placed into a
       temporary directory.  Stopping the translator at this point
       causes it to print the contents of the C file.

       In pass 4, the translator invokes the Linux kernel build system
       to create the actual kernel object file.  This involves running
       make in the temporary directory, and requires a kernel module
       build system (headers, config and Makefiles) to be installed in
       the usual spot /lib/modules/VERSION/build.  Stopping the
       translator after pass 4 is the last chance before running the
       kernel object.  This may be useful if you want to archive the
       file.

       In pass 5, the translator invokes the systemtap auxiliary program
       staprun program for the given kernel object.  This program
       arranges to load the module then communicates with it, copying
       trace data from the kernel into temporary files, until the user
       sends an interrupt signal.  Any run-time error encountered by the
       probe handlers, such as running out of memory, division by zero,
       exceeding nesting or runtime limits, results in a soft error
       indication.  Soft errors in excess of MAXERRORS block of all
       subsequent probes (except error-handling probes), and terminate
       the session.  Finally, staprun unloads the module, and cleans up.

   ABNORMAL TERMINATION
       One should avoid killing the stap process forcibly, for example
       with SIGKILL, because the stapio process (a child process of the
       stap process) and the loaded module may be left running on the
       system.  If this happens, send SIGTERM or SIGINT to any remaining
       stapio processes, then use rmmod to unload the systemtap module.