Adjust backtrace2 signature

libunwind · Jan 11, 2023 · b1d6f6e · b1d6f6e
1 parent d753412
commit b1d6f6e
Show file tree

Hide file tree

Showing 5 changed files with 19 additions and 11 deletions.
diff --git a/doc/unw_backtrace.man b/doc/unw_backtrace.man
@@ -1,7 +1,7 @@
 .\" *********************************** start of \input{common.tex}
 .\" *********************************** end of \input{common.tex}
 '\" t
-.\" Manual page created with latex2man on Thu Dec  8 12:01:30 2022
+.\" Manual page created with latex2man on Thu Jan  5 15:33:00 2023
 .\" NOTE: This file is generated, DO NOT EDIT.
 .de Vb
 .ft CW
@@ -12,7 +12,7 @@
 
 .fi
 ..
-.TH "UNW\\_BACKTRACE" "3" "08 December 2022" "Programming Library " "Programming Library "
+.TH "UNW\\_BACKTRACE" "3" "05 January 2023" "Programming Library " "Programming Library "
 .SH NAME
 unw_backtrace
 \-\- return backtrace for the calling program 
@@ -30,7 +30,8 @@ int size);
 int
 unw_backtrace2(void **buffer,
 int size,
-unw_context_t *ctxt);
+unw_context_t *ctxt,
+int flag);
 .br
 .PP
 #include <execinfo.h>
@@ -68,11 +69,16 @@ is linked against libunwind,
 it may end up 
 calling unw_backtrace().
 .PP
+In case you want to obtain the backtrace from a specific unw_context_t,
+you can call unw_backtrace2
+with that context passing 0
+for flag. 
 If the unw_context_t
 is known to be a signal frame (i.e., from the third argument 
 in a sigaction handler on linux), unw_backtrace2
 can be used to collect 
-only the frames before the signal frame. 
+only the frames before the signal frame passing the UNW_INIT_SIGNAL_FRAME
+flag. 
 .PP
 .SH RETURN VALUE
 

diff --git a/doc/unw_backtrace.tex b/doc/unw_backtrace.tex
@@ -13,7 +13,7 @@ \section{Synopsis}
 \File{\#include $<$libunwind.h$>$}\\
 
 \Type{int} \Func{unw\_backtrace}(\Type{void~**}\Var{buffer}, \Type{int}~\Var{size});\\
-\Type{int} \Func{unw\_backtrace2}(\Type{void~**}\Var{buffer}, \Type{int}~\Var{size}, \Type{unw_context_t~*}\Var{ctxt});\\
+\Type{int} \Func{unw\_backtrace2}(\Type{void~**}\Var{buffer}, \Type{int}~\Var{size}, \Type{unw_context_t~*}\Var{ctxt}, \Type{int}~\Var{flag});\\
 
 \File{\#include $<$execinfo.h$>$}\\
 
@@ -33,9 +33,11 @@ \section{Description}
 calling \Func{backtrace}() is linked against \Prog{libunwind}, it may end up
 calling \Func{unw\_backtrace}().
 
+In case you want to obtain the backtrace from a specific \Type{unw\_context\_t},
+you can call \Func{unw\_backtrace2} with that context passing \Const{0} for flag. 
 If the \Type{unw\_context_t} is known to be a signal frame (i.e., from the third argument
 in a sigaction handler on linux), \Func{unw\_backtrace2} can be used to collect
-only the frames before the signal frame.
+only the frames before the signal frame passing the \Const{UNW\_INIT\_SIGNAL\_FRAME} flag.
 
 \section{Return Value}
 

diff --git a/include/libunwind-common.h.in b/include/libunwind-common.h.in
@@ -316,6 +316,6 @@ extern int unw_get_proc_name_by_ip (unw_addr_space_t, unw_word_t, char *,
 				    size_t, unw_word_t *, void *);
 extern const char *unw_strerror (int);
 extern int unw_backtrace (void **, int);
-extern int unw_backtrace2 (void **, int, unw_context_t*);
+extern int unw_backtrace2 (void **, int, unw_context_t*, int);
 
 extern unw_addr_space_t unw_local_addr_space;
diff --git a/src/mi/backtrace.c b/src/mi/backtrace.c
@@ -77,7 +77,7 @@ unw_backtrace (void **buffer, int size)
 }
 
 int
-unw_backtrace2 (void **buffer, int size, unw_context_t* uc2)
+unw_backtrace2 (void **buffer, int size, unw_context_t* uc2, int flag)
 {
   if (size == 0)
     return 0;
@@ -89,7 +89,7 @@ unw_backtrace2 (void **buffer, int size, unw_context_t* uc2)
   // need to copy, because the context will be modified by tdep_trace
   unw_context_t uc = *(unw_context_t*)uc2;
 
-  if (unlikely (unw_init_local2 (&cursor, &uc, UNW_INIT_SIGNAL_FRAME) < 0))
+  if (unlikely (unw_init_local2 (&cursor, &uc, flag) < 0))
     return 0;
 
   // get the first ip from the context
@@ -110,7 +110,7 @@ unw_backtrace2 (void **buffer, int size, unw_context_t* uc2)
   // and add 1 to it (the one we retrieved above)
   if (unlikely (tdep_trace (&cursor, buffer, &n) < 0))
     {
-      return slow_backtrace (buffer, remaining_size, &uc, UNW_INIT_SIGNAL_FRAME) + 1;
+      return slow_backtrace (buffer, remaining_size, &uc, flag) + 1;
     }
 
   return n + 1;

diff --git a/tests/Gtest-trace.c b/tests/Gtest-trace.c
@@ -174,7 +174,7 @@ do_backtrace_with_context(void *context)
   if (verbose)
     printf ("\n\tvia unw_backtrace2():\n");
 
-  m = unw_backtrace2 (addresses[1], 128, (unw_context_t*)context);
+  m = unw_backtrace2 (addresses[1], 128, (unw_context_t*)context, UNW_INIT_SIGNAL_FRAME);
 
   if (verbose)
     for (i = 0; i < m; ++i)