From 39e3139ab7d9422237b73773693617fff22aa67d Mon Sep 17 00:00:00 2001
From: fche <fche>
Date: Thu, 20 Mar 2008 17:58:06 +0000
Subject: [PATCH] * clarify $variables available in .return probes

---
 stapprobes.5.in | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/stapprobes.5.in b/stapprobes.5.in
index 55fcb3c77..ce8ef52df 100644
--- a/stapprobes.5.in
+++ b/stapprobes.5.in
@@ -192,9 +192,10 @@ Here is a list of probe point families currently supported.  The
 variant places a probe near the beginning of the named function, so that
 parameters are available as context variables.  The
 .B .return
-variant places a probe at the moment of return from the named function, so
-the return value is available as the "$return" context variable. 
-The
+variant places a probe at the moment
+.B after
+the return from the named function, so the return value is available
+as the "$return" context variable.  The
 .B .inline
 modifier for
 .B .function
@@ -262,7 +263,7 @@ As an alternative, PATTERN may be a numeric constant, indicating an
 only, absolute kernel addresses may be specified with the ".absolute"
 suffix.
 .PP
-Some of the source-level variables, such as function parameters,
+Some of the source-level context variables, such as function parameters,
 locals, globals visible in the compilation unit, may be visible to
 probe handlers.  They may refer to these variables by prefixing their
 name with "$" within the scripts.  In addition, a special syntax
@@ -282,6 +283,15 @@ may be repeated to follow more levels of pointers.
 $var[N]
 indexes into an array.  The index is given with a
 literal number.
+.PP
+For ".return" probes, context variables other than the "$return"
+value itself are only available for the function call parameters.
+The expressions evaluate to the
+.IR entry-time
+values of those variables, since that is when a snapshot is taken.
+Other local variables are not generally accessible, since by the time
+a ".return" probe hits, the probed function will have already returned.
+
 
 .SS USER-SPACE
 Early prototype support for user-space probing is available in the
-- 
2.43.5