diff options
author | Roland McGrath <roland@redhat.com> | 2009-03-24 15:43:25 -0700 |
---|---|---|
committer | Roland McGrath <roland@redhat.com> | 2009-03-24 15:43:25 -0700 |
commit | d10b4351a0bc2386ff15c806bfc3cd531fe883f0 (patch) | |
tree | 80d65fb5e4ec7d197d4b303826a6c9dead6027d0 /stap.1.in | |
parent | 5d6b014268ca47386ef92525b8669429dec6e49c (diff) | |
download | systemtap-steved-d10b4351a0bc2386ff15c806bfc3cd531fe883f0.tar.gz systemtap-steved-d10b4351a0bc2386ff15c806bfc3cd531fe883f0.tar.xz systemtap-steved-d10b4351a0bc2386ff15c806bfc3cd531fe883f0.zip |
Typo and whitespace.
Diffstat (limited to 'stap.1.in')
-rw-r--r-- | stap.1.in | 66 |
1 files changed, 33 insertions, 33 deletions
@@ -150,7 +150,7 @@ Add the given directory to the tapset search directory. See the description of pass 2 for details. .TP .BI \-D " NAME=VALUE" -Add the given C preprocessor directive to the module Makefile. These can +Add the given C preprocessor directive to the module Makefile. These can be used to override limit parameters described below. .TP .BI \-R " DIR" @@ -183,7 +183,7 @@ This supports a subset of strftime(3) (%%, %C, %Y, %y, %m, %d, %e, %F, Start the probes, run CMD, and exit when CMD finishes. .TP .BI \-x " PID" -Sets target() to PID. This allows scripts to be written that filter on +Sets target() to PID. This allows scripts to be written that filter on a specific process. .TP .BI \-l " PROBE" @@ -197,7 +197,7 @@ Similar to "-l", but list probe points and script-level local variables. .BI \-F Without -o option, load module and start probes, then detach from the module leaving the probes running. -With -o option, run staprun in background as a daemon and show it's pid. +With -o option, run staprun in background as a daemon and show its pid. .TP .BI \-S " size[,N]" Sets the maximum size of output file and the maximum number of output files. @@ -253,7 +253,7 @@ parser for substitution. See below. .SH SCRIPT LANGUAGE -The systemtap script language resembles +The systemtap script language resembles .IR awk . There are two main outermost constructs: probes and functions. Within these, statements and expressions use C-like operator syntax and @@ -292,7 +292,7 @@ number beyond what was actually given is an error. .SS PREPROCESSING A simple conditional preprocessing stage is run as a part of parsing. -The general form is similar to the +The general form is similar to the .RB cond " ? " exp1 " : " exp2 ternary operator: .SAMPLE @@ -316,7 +316,7 @@ version of the target kernel (as optionally overridden by the option) compares to the given version string. The comparison is performed by the glibc function .BR strverscmp . -As a special case, if the operator is for simple equality +As a special case, if the operator is for simple equality .RB ( == ), or inequality .RB ( != ), @@ -348,14 +348,14 @@ kernel version is newer than 2.6.5: .ESAMPLE The following code might adapt to hypothetical kernel version drift: .SAMPLE -probe kernel.function ( - %( kernel_v <= "2.6.12" %? "__mm_do_fault" %: +probe kernel.function ( + %( kernel_v <= "2.6.12" %? "__mm_do_fault" %: %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %: UNSUPPORTED %) %) ) { /* ... */ } %( arch == "ia64" %? - probe syscall.vliw = kernel.function("vliw_widget") {} + probe syscall.vliw = kernel.function("vliw_widget") {} %) .ESAMPLE @@ -423,7 +423,7 @@ Execute the string- or integer-valued expression and throw away the value. .TP .BR { " STMT1 STMT2 ... " } -Execute each statement in sequence in this block. Note that +Execute each statement in sequence in this block. Note that separators or terminators are generally not necessary between statements. .TP .BR ; @@ -445,12 +445,12 @@ STMT, then the iteration expression EXP3. .BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT" Loop over each element of the named global array, assigning current key to VAR. The array may not be modified within the statement. -By adding a single +By adding a single .BR + " or " \- operator after the VAR or the ARRAY identifier, the iteration will proceed in a sorted order, by ascending or descending index or value. Using the optional -.BR limit +.BR limit keyword limits the number of loop iterations to EXP times. EXP is evaluted once at the beginning of the loop. .TP @@ -503,7 +503,7 @@ string assignment operators .B = .= .TP unary numeric operators -.B + \- ! ~ ++ \-\- +.B + \- ! ~ ++ \-\- .TP binary numeric or string comparison operators .B < > <= >= == != @@ -542,7 +542,7 @@ The probe handler is interpreted relative to the context of each event. For events associated with kernel code, this context may include .I variables -defined in the +defined in the .I source code at that spot. These "target variables" are presented to the script as variables whose names are prefixed with "$". They may be accessed @@ -553,9 +553,9 @@ with optimized code. Some other events have very little context. New probe points may be defined using "aliases". Probe point aliases look similar to probe definitions, but instead of activating a probe at the given point, it just defines a new probe point name as an alias -to an existing one. There are two types of alias, i.e. the prologue +to an existing one. There are two types of alias, i.e. the prologue style and the epilogue style which are identified by "=" and "+=" -respectively. +respectively. .PP For prologue style alias, the statement block that follows an alias definition is implicitly added as a prologue to any probe that refers @@ -655,9 +655,9 @@ The .IR printf formatting directives similar to those of C, except that they are fully type-checked by the translator: -.RS +.RS .TP -%b +%b Writes a binary blob of the value given, instead of ASCII text. The width specifier determines the number of bytes to write; valid specifiers are %b %1b %2b %4b %8b. Default (%b) is 8 bytes. .TP %c @@ -738,7 +738,7 @@ distinct extraction function operating on a given identifier, the translator arranges to compute a set of statistics that satisfy it. The statistics system is thereby "on-demand". Each execution of an extraction function causes the aggregation to be computed for -that moment across all processors. +that moment across all processors. .PP Here is the set of extractor functions. The first argument of each is the same style of lvalue used on the left hand side of the accumulate @@ -751,7 +751,7 @@ integers. Histograms are also available, but are more complicated because they have a vector rather than scalar value. .I @hist_linear(v,start,stop,interval) -represents a linear histogram from "start" to "stop" by increments +represents a linear histogram from "start" to "stop" by increments of "interval". The interval must be positive. Similarly, .I @hist_log(v) represents a base-2 logarithmic histogram. Printing a histogram @@ -763,7 +763,7 @@ family of functions renders a histogram object as a tabular probe foo { x <<< $value } -probe end { +probe end { printf ("avg %d = sum %d / count %d\\n", @avg(x), @sum(x), @count(x)) print (@hist_log(v)) @@ -823,7 +823,7 @@ sequence, into the generated C code. At the outermost level, this may be useful to add .IR #include instructions, and any auxiliary definitions for use by other embedded -code. +code. .PP The other place where embedded code is permitted is as a function body. In this case, the script language body is replaced entirely by a piece @@ -884,7 +884,7 @@ the following patterns would be searched, in sequence: .IR 2.6/*.stp , and finally .IR *.stp -Stopping the translator after pass 1 causes it to print the parse trees. +Stopping the translator after pass 1 causes it to print the parse trees. .PP In pass 2, the translator analyzes the input script to resolve symbols @@ -896,7 +896,7 @@ added to the translator's resolution queue. This process iterates until all symbols are resolved and a subset of tapset scripts is selected. .PP -Next, all probe point descriptions are validated +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 @@ -913,7 +913,7 @@ Since this optimization can hide latent code errors such as type mismatches or invalid $target variables, it sometimes may be useful to disable the optimizations with the .BR \-u -option. +option. .PP Finally, all variable, function, parameter, array, and index types are inferred from context (literals and operators). Stopping the @@ -956,7 +956,7 @@ Finally, unloads the module, and cleans up. .SH EXAMPLES -See the +See the .IR stapex (3stap) manual page for a collection of samples. @@ -970,10 +970,10 @@ the .I $SYSTEMTAP_DIR/cache directory. The cache can be limited by having the file .I cache_mb_limit -placed in the cache directory (shown above) containing only an ASCII +placed in the cache directory (shown above) containing only an ASCII integer representing how many MiB the cache should not exceed. Note that this is a 'soft' limit in that the cache will be cleaned after a new entry -is added, so the total cache size may temporarily exceed this limit. In the +is added, so the total cache size may temporarily exceed this limit. In the absence of this file, a default will be created with the limit set to 64MiB. .SH SAFETY AND SECURITY @@ -1005,11 +1005,11 @@ program are run by the .IR staprun program. The latter is a part of the Systemtap package, dedicated to module loading and unloading (but only in the white zone), and -kernel-to-user data transfer. Since +kernel-to-user data transfer. Since .IR staprun does not perform any additional security checks on the kernel objects it is given, it would be unwise for a system administrator to add -untrusted users to the +untrusted users to the .I stapdev or .I stapusr @@ -1026,7 +1026,7 @@ to kernel crash or data corruption. The resource use limits are set by macros in the generated C code. These may be overridden with the .BR \-D -flag. A selection of these is as follows: +flag. A selection of these is as follows: .TP MAXNESTING Maximum number of recursive function call levels, default 10. @@ -1099,7 +1099,7 @@ Note that you must unload guests before unloading a host. If there are some guests connected to the host, unloading the host will be failed. .PP -In case something goes wrong with +In case something goes wrong with .IR stap " or " staprun after a probe has already started running, one may safely kill both user processes, and remove the active probe kernel module with @@ -1173,7 +1173,7 @@ environment variable. Temporary directory for systemtap files, including translated C code and kernel object. .TP -@prefix@/share/systemtap/tapset +@prefix@/share/systemtap/tapset The automatic tapset search directory, unless overridden by the .I SYSTEMTAP_TAPSET |