From a0e555dd116964153f8a6f8a85e2c486bea77b58 Mon Sep 17 00:00:00 2001
From: Mark Wielaard <mjw@redhat.com>
Date: Sun, 17 Oct 2010 20:59:12 +0200
Subject: [PATCH] Add note to ubacktrace* context functions about -d and --ldd
 stap switches.

rhbz#643109 Suggested by jan.kratochvil@redhat.com.

* tapset/ucontext-unwind.stp (print_ubacktrace, sprint_ubacktrace,
  print_ubacktrace_brief, ubacktrace): Add comment note about -d and --ldd.
---
 tapset/ucontext-unwind.stp | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/tapset/ucontext-unwind.stp b/tapset/ucontext-unwind.stp
index d3ca07571..f22fb0c5c 100644
--- a/tapset/ucontext-unwind.stp
+++ b/tapset/ucontext-unwind.stp
@@ -18,8 +18,12 @@
 /**
  * sfunction print_ubacktrace - Print stack back trace for current task. EXPERIMENTAL!
  *
- *  Equivalent to print_ustack(ubacktrace()), 
- *  except that deeper stack nesting may be supported.  Return nothing.
+ * Equivalent to print_ustack(ubacktrace()), except that deeper stack
+ * nesting may be supported.  Returns nothing.
+ *
+ * Note: To get (full) backtraces for user space applications and shared
+ * shared libraries not mentioned in the current script run stap with
+ * -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
  */
 function print_ubacktrace () %{
 /* unprivileged */ /* pragma:uprobes */ /* pragma:vma */
@@ -66,6 +70,10 @@ function print_ubacktrace () %{
  * print_ubacktrace(). Equivalent to sprint_ustack(ubacktrace()),
  * but more efficient (no need to translate between hex strings and
  * final backtrace string).
+ *
+ * Note: To get (full) backtraces for user space applications and shared
+ * shared libraries not mentioned in the current script run stap with
+ * -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
  */
 function sprint_ubacktrace:string () %{
 /* pure */ /* unprivileged */ /* pragma:uprobes */ /* pragma:vma */
@@ -102,8 +110,13 @@ function sprint_ubacktrace:string () %{
 /**
  * sfunction print_ubacktrace_brief- Print stack back trace for current task. EXPERIMENTAL!
  *
- *  Equivalent to print_ubacktrace(), but output for each symbol is
- *  shorter (just name and offset, or just the hex address of no symbol could be found).
+ * Equivalent to print_ubacktrace(), but output for each symbol is
+ * shorter (just name and offset, or just the hex address of no symbol
+ * could be found).
+ *
+ * Note: To get (full) backtraces for user space applications and shared
+ * shared libraries not mentioned in the current script run stap with
+ * -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
  */
 function print_ubacktrace_brief () %{
 /* unprivileged */ /* pragma:uprobes */ /* pragma:vma */
@@ -139,10 +152,14 @@ function print_ubacktrace_brief () %{
 /**
  * sfunction ubacktrace - Hex backtrace of current task stack. EXPERIMENTAL!
  *
- *  Return a string of hex addresses that are a backtrace of the 
- *  stack of the current task.  Output may be truncated as per maximum
- *  string length. Returns empty string when current probe point cannot
- *  determine user backtrace.
+ * Return a string of hex addresses that are a backtrace of the 
+ * stack of the current task.  Output may be truncated as per maximum
+ * string length. Returns empty string when current probe point cannot
+ * determine user backtrace.
+ *
+ * Note: To get (full) backtraces for user space applications and shared
+ * shared libraries not mentioned in the current script run stap with
+ * -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
  */
 function ubacktrace:string () %{
 /* pure */ /* unprivileged */ /* pragma:uprobes */ /* pragma:vma */
-- 
2.43.5