commit 179a00c3efb5ceac52a70debb17a91ee0c07722d Author: Mark Wielaard Date: Mon Mar 12 13:00:40 2012 +0100 Document new @var construct in NEWS, langref, beginners and stapprobes. diff --git a/NEWS b/NEWS index 60060ed..16a422c 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,16 @@ * What's new in version 1.8 +- @var now an alternative language syntax for accessing DWARF variables + in uprobe and kprobe handlers (process, kernel, module). @var("somevar") + can be used where $somevar can be used. The @var syntax also makes it + possible to access non-local, global compile unit (CU) variables by + specifying the CU source file as follows @var("somevar@some/src/file.c"). + This will provide the target variable value of global "somevar" as defined + in the source file "some/src/file.c". The @var syntax combines with all + normal features of DWARF target variables like @defined(), @entry(), + [N] array indexing, field access through ->, taking the address with + the & prefix and swallow or deep pretty printing with a $ or $$ suffix. + - Stap now has resource limit options: --rlimit-as=NUM --rlimit-cpu=NUM diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml index 9f6c669..155ab61 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml @@ -164,6 +164,13 @@ target variables at the entry to the function. +When a target variable is not local to the probe point, like a global +external variable or a file local static variable defined in another file +then it can be referenced through +@var("varname@src/file.c"). + + + SystemTap tracks the typing information of the target variable and can examine the fields of a structure with the -> operator. The -> operator can be chained to look at data structures @@ -175,6 +182,27 @@ in a substructure or accessing another structure through a pointer. +For example to access a field of the static files_stat target variable +defined in fs/file_table.c (which holds some of the current file system +sysctl tunables), one could write: + + + +stap -e 'probe kernel.function("vfs_read") { + printf ("current files_stat max_files: %d\n", + @var("files_stat@fs/file_table.c")->max_files); + exit(); }' + + + +Which will yield something similar to the following: + + + +current files_stat max_files: 386070 + + + For pointers to base types such as integers and strings there are a number of functions listed below to access kernel-space data. The first argument for each functions is the pointer to the data item. diff --git a/doc/langref.tex b/doc/langref.tex index 5cee2ed..fb8ea19 100644 --- a/doc/langref.tex +++ b/doc/langref.tex @@ -52,7 +52,7 @@ \newpage{} This document was derived from other documents contributed to the SystemTap project by employees of Red Hat, IBM and Intel.\newline -Copyright \copyright\space 2007-2010 Red Hat Inc.\newline +Copyright \copyright\space 2007-2012 Red Hat Inc.\newline Copyright \copyright\space 2007-2009 IBM Corp.\newline Copyright \copyright\space 2007 Intel Corporation.\newline @@ -799,19 +799,47 @@ module address or an absolute kernel address. Some of the source-level variables, such as function parameters, locals, or globals visible in the compilation unit, are visible to probe handlers. Refer to these variables by prefixing their name with a dollar sign within -the scripts. In addition, a special syntax allows limited traversal of structures, -pointers, and arrays. +the scripts. In addition, a special syntax allows limited traversal of +structures, pointers, arrays, taking the address of a variable or pretty +printing a whole structure. \texttt{\$var} refers to an in-scope variable var. If it is a type similar to an integer, it will be cast to a 64-bit integer for script use. Pointers similar to a string (char {*}) are copied to SystemTap string values by the \texttt{kernel\_string()} or \texttt{user\_string()} functions. -\texttt{\$var->field} traverses a structure's field. The indirection operator -may be repeated to follow additional levels of pointers. - -\texttt{\$var{[}N]} indexes into an array. The index is given with a literal -number. +\texttt{@var("varname")} is an alternative syntax for \texttt{\$varname}. +It can also be used to access global variables in a particular compile +unit (CU). \texttt{@var("varname@src/file.c")} refers to the global +(either file local or external) variable varname defined when the file +src/file.c was compiled. The CU in which the variable is resolved is +the first CU in the module of the probe point which matches the given +file name at the end and has the shortest file name path (e.g. given +\texttt{@var("foo@bar/baz.c")} and CUs with file name paths +\texttt{src/sub/module/bar/baz.c} and \texttt{src/bar/baz.c} the second +CU will be chosen to resolve \texttt{foo}). + +\texttt{\$var->field} or \texttt{@var("var@file.c")->field} traverses a +structure's field. The indirection operator may be repeated to follow +additional levels of pointers. + +\texttt{\$var{[}N]} or \texttt{@var("var@file.c"){[}N]} indexes into an +array. The index is given with a literal number. + +\texttt{\&\$var} or \texttt{\&@var("var@file.c")} provides the address of +a variable as a long. It can also be used in combination with field access +or array indexing to provide the address of a particular field or an +element in an array with \texttt{\&var->field}, +\texttt{\&@var("var@file.c"){[}N]} or a combination of those accessors. + +Using a single \texttt{\$} or a double \texttt{\$\$} suffix provides a +swallow or deep string representation of the variable data type. Using +a single \texttt{\$}, as in \texttt{\$var\$}, will provide a string that +only includes the values of all basic type values of fields of the variable +structure type but not any nested complex type values (which will be +represented with \texttt{\{...\}}). Using a double \texttt{\$\$}, +as in \texttt{@var("var")\$\$} will provide a string that also includes +all values of nested data types. \texttt{\$\$vars} expands to a character string that is equivalent to \texttt{sprintf("parm1=\%x ... parmN=\%x var1=\%x ... varN=\%x", \$parm1, ..., \$parmN, diff --git a/stapprobes.3stap b/stapprobes.3stap index 48c8602..14c426b 100644 --- a/stapprobes.3stap +++ b/stapprobes.3stap @@ -410,6 +410,28 @@ pointers (char *) may be copied to systemtap string values using the .IR kernel_string " or " user_string functions. .TP +@var("varname") +an alternative syntax for +.IR $varname +. +.TP +@var("varname@src/file.c") +refers to the global (either file local or external) variable +.IR varname +defined when the file +.IR src/file.c +was compiled. The CU in which the variable is resolved is the first CU +in the module of the probe point which matches the given file name at +the end and has the shortest file name path (e.g. given +.IR @var("foo@bar/baz.c") +and CUs with file name paths +.IR src/sub/module/bar/baz.c +and +.IR src/bar/baz.c +the second CU will be chosen to resolve the (file) global variable +.IR foo +. +.TP $var\->field traversal via a structure's or a pointer's field. This generalized indirection operator may be repeated to follow more levels. Note that the