This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
[PATCH doc/langref.tex] Add pointer typecasting information
- From: Robb Romans <robb at linux dot vnet dot ibm dot com>
- To: systemtap at sources dot redhat dot com
- Cc: Prerna Saxena <prerna at linux dot vnet dot ibm dot com>
- Date: Tue, 1 Sep 2009 12:17:54 -0500 (CDT)
- Subject: [PATCH doc/langref.tex] Add pointer typecasting information
Please review. Thanks.
Signed-off-by: Robb Romans <robb@linux.vnet.ibm.com>
---
doc/langref.tex | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 55 insertions(+), 1 deletions(-)
diff --git a/doc/langref.tex b/doc/langref.tex
index f1c14d3..640ad79 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -1194,9 +1194,63 @@ STAP_PROBE1(handle, LABEL, arg1)
\end{description}
-\section{Language elements\label{sec:Language-Elements}}
+\subsection{Pointer typecasting}
+\index{Pointer typecasting}
+
+\emph{Typecasting} is supported using the \texttt{@cast} operator. A
+script can define a pointer type for a ``long'' value, and then access
+type members using the same syntax as with \texttt{\$target}
+variables.
+
+Once a pointer is saved into a script integer variable, the translator
+loses the necessary type information to access members from that
+pointer. The \texttt{@cast()} operator tells the translator how to read a
+pointer.
+
+The following statement interprets \texttt{p} as a pointer to a struct
+or union named \texttt{type\_name} and dereferences the \texttt{member}
+value:
+\begin{vindent}
+\begin{verbatim}
+@cast(p, "type_name"[, "module"])->member
+\end{verbatim}
+\end{vindent}
+The optional \texttt{module} parameter tells the translator where to
+look for information about that type. If you do not specify the module
+parameter, the translator defaults to either the probe module for
+dwarf probes or to ``kernel'' for functions and all other probe
+types.
+For example, the following statement retrieves the parent pid from a kernel
+task\_struct:
+\begin{vindent}
+\begin{verbatim}
+@cast(pointer, "task_struct", "kernel")->parent->pid
+\end{verbatim}
+\end{vindent}
+
+In guru mode, the translator allows scripts to assign new values to
+members of typecasted pointers.
+
+Typecasting is also useful in the case of \texttt{void*} members whose
+type might be determinable at runtime.
+
+\begin{vindent}
+\begin{verbatim}
+probe foo {
+ if ($var->type == 1) {
+ value = @cast($var->data, "type1")->bar
+ } else {
+ value = @cast($var->data, "type2")->baz
+ }
+ print(value)
+}
+\end{verbatim}
+\end{vindent}
+
+
+\section{Language elements\label{sec:Language-Elements}}
\subsection{Identifiers}
\index{identifiers}
\emph{Identifiers} are used to name variables and functions. They are an
--
1.6.0.4
--
Robb Romans
IBM LTC Information Development
robb@linux.vnet.ibm.com