From 60ea929119a82b462bc32dd42a48972ee04420e0 Mon Sep 17 00:00:00 2001
From: Josh Stone <jistone@redhat.com>
Date: Wed, 18 Feb 2009 17:59:14 -0800
Subject: Add NEWS and manpage info about @cast()

---
 NEWS      |  6 ++++++
 stap.1.in | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/NEWS b/NEWS
index 12e44323..280b6fb2 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,11 @@
 * What's new in version 0.9
 
+- Typecasting is now supported using the @cast operator.  A script can
+  define a pointer type for a "long" value, and then access type members
+  using the same syntax as with $target variables.  For example, this will
+  retrieve the parent pid from a kernel task_struct:
+    @cast(pointer, "task_struct", "kernel")->parent->pid
+
 - process().mark() probes are now possible to trace static user space
   markers put in programs with the STAP_PROBE macro using the new
   sys/sdt.h include file. This also provides dtrace compatible markers
diff --git a/stap.1.in b/stap.1.in
index cde049a3..6e4df024 100644
--- a/stap.1.in
+++ b/stap.1.in
@@ -755,6 +755,46 @@ probe end {
 }
 .ESAMPLE
 
+.SS TYPECASTING
+Once a pointer has been saved into a script integer variable, the
+translator loses the type information necessary to access members from
+that pointer.  Using the
+.I @cast()
+operator tells the translator how to read a pointer.
+.SAMPLE
+@cast(p, "type_name"[, "module"])->member
+.ESAMPLE
+.PP
+This will interpret
+.I p
+as a pointer to a struct/union named
+.I type_name
+and dereference the
+.I member
+value.  The optional
+.I module
+tells the translator where to look for information about that type.  If
+the module is not specified, it will default either to the probe module
+for dwarf probes, or to "kernel" for functions and all other probes
+types.
+.PP
+When in guru mode, the translator will also allow scripts to assign new
+values to members of typecasted pointers.
+.PP
+Typecasting is also useful in the case of
+.I void*
+members whose type may be determinable at runtime.
+.SAMPLE
+probe foo {
+  if ($var->type == 1) {
+    value = @cast($var->data, "type1")->bar
+  } else {
+    value = @cast($var->data, "type2")->baz
+  }
+  print(value)
+}
+.ESAMPLE
+
 .SS EMBEDDED C
 When in guru mode, the translator accepts embedded code in the
 script.  Such code is enclosed between
@@ -1076,6 +1116,8 @@ probe specifications that refer to inline functions
 .IP \(bu 4
 statements that refer to $target variables
 .IP \(bu 4
+statements that refer to @cast() variables
+.IP \(bu 4
 tapset-defined variables defined using any of the above constructs.
 In particular, at this writing,
 the prologue blocks for certain aliases in the syscall tapset
-- 
cgit