[PATCHv3,02/13] gdb/doc: extend the documentation for conditional breakpoints

  This documentation update adds more text to describe what happens if a
conditional breakpoint calls an inferior function, and the inferior
function is interrupted for some reason.
---
 gdb/doc/gdb.texinfo | 11 +++++++++++
 1 file changed, 11 insertions(+)
  

> Cc: Andrew Burgess <aburgess@redhat.com>
> Date: Tue, 31 Jan 2023 17:27:07 +0000
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
> 
> +If a breakpoint condition calls a function in your program, then it is
> +possible that your program could stop for some reason while in the
> +called function.  For example, @value{GDBN} might hit a breakpoint in
> +the called function, or the called function may receive a signal
> +(e.g.@ a @code{SIGSEGV}) as a result of some undefined behavior.  If
> +this happens then @value{GDBN} will stop.  Depending on the settings
> +@code{unwindonsignal} and @code{unwind-on-terminating-exception}
> +(@pxref{Calling,,Calling Program Functions}) @value{GDBN} may unwind
> +the stack back to the breakpoint location, or may leave the program at
> +the frame where the stop occurred.

This is okay, but should we perhaps tell the reader how to deal with
these calamities?  I presume there's something to say, otherwise why
do we describe these situations?

Thanks.
  

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: Andrew Burgess <aburgess@redhat.com>
>> Date: Tue, 31 Jan 2023 17:27:07 +0000
>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>> 
>> +If a breakpoint condition calls a function in your program, then it is
>> +possible that your program could stop for some reason while in the
>> +called function.  For example, @value{GDBN} might hit a breakpoint in
>> +the called function, or the called function may receive a signal
>> +(e.g.@ a @code{SIGSEGV}) as a result of some undefined behavior.  If
>> +this happens then @value{GDBN} will stop.  Depending on the settings
>> +@code{unwindonsignal} and @code{unwind-on-terminating-exception}
>> +(@pxref{Calling,,Calling Program Functions}) @value{GDBN} may unwind
>> +the stack back to the breakpoint location, or may leave the program at
>> +the frame where the stop occurred.
>
> This is okay, but should we perhaps tell the reader how to deal with
> these calamities?  I presume there's something to say, otherwise why
> do we describe these situations?

How about if I add an extra sentence at the end of the paragraph to say
that it is possible to continue debugging from the point where GDB
stops, like this (new text starts "If @value{GDBN} remains in the..."):

  If a breakpoint condition calls a function in your program, then it is
  possible that your program could stop for some reason while in the
  called function.  For example, @value{GDBN} might hit a breakpoint in
  the called function, or the called function may receive a signal
  (e.g.@ a @code{SIGSEGV}) as a result of some undefined behavior.  If
  this happens then @value{GDBN} will stop.  Depending on the settings
  @code{unwindonsignal} and @code{unwind-on-terminating-exception}
  (@pxref{Calling,,Calling Program Functions}) @value{GDBN} may unwind
  the stack back to the breakpoint location, or may leave the program at
  the frame where the stop occurred.  If @value{GDBN} remains in the
  frame where the stop occurred then you can debug the inferior from
  this point to understand why the called function failed.

Does this address your concerns?

Thanks,
Andrew
  

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Wed, 01 Feb 2023 17:47:52 +0000
> 
>   If a breakpoint condition calls a function in your program, then it is
>   possible that your program could stop for some reason while in the
>   called function.  For example, @value{GDBN} might hit a breakpoint in
>   the called function, or the called function may receive a signal
>   (e.g.@ a @code{SIGSEGV}) as a result of some undefined behavior.  If
>   this happens then @value{GDBN} will stop.  Depending on the settings
>   @code{unwindonsignal} and @code{unwind-on-terminating-exception}
>   (@pxref{Calling,,Calling Program Functions}) @value{GDBN} may unwind
>   the stack back to the breakpoint location, or may leave the program at
>   the frame where the stop occurred.  If @value{GDBN} remains in the
>   frame where the stop occurred then you can debug the inferior from
>   this point to understand why the called function failed.
> 
> Does this address your concerns?

Some.  But I also think that the text should more explicitly explain
that the various values of the unwind-* options are there precisely to
tailor what happens to the needs of the debugging session.  The text
is now written as purely descriptional: if you set the option this
way, what will happen is so-and-so.  It would be better, I think, to
turn the table and say: if you want to debug the called function when
this happen, set the option to this value; OTOH if you want ignore
that and continue debugging the inferior, set the option to that other
value.  Does this make sense?
  

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrew Burgess <aburgess@redhat.com>
>> Cc: gdb-patches@sourceware.org
>> Date: Wed, 01 Feb 2023 17:47:52 +0000
>> 
>>   If a breakpoint condition calls a function in your program, then it is
>>   possible that your program could stop for some reason while in the
>>   called function.  For example, @value{GDBN} might hit a breakpoint in
>>   the called function, or the called function may receive a signal
>>   (e.g.@ a @code{SIGSEGV}) as a result of some undefined behavior.  If
>>   this happens then @value{GDBN} will stop.  Depending on the settings
>>   @code{unwindonsignal} and @code{unwind-on-terminating-exception}
>>   (@pxref{Calling,,Calling Program Functions}) @value{GDBN} may unwind
>>   the stack back to the breakpoint location, or may leave the program at
>>   the frame where the stop occurred.  If @value{GDBN} remains in the
>>   frame where the stop occurred then you can debug the inferior from
>>   this point to understand why the called function failed.
>> 
>> Does this address your concerns?
>
> Some.  But I also think that the text should more explicitly explain
> that the various values of the unwind-* options are there precisely to
> tailor what happens to the needs of the debugging session.  The text
> is now written as purely descriptional: if you set the option this
> way, what will happen is so-and-so.  It would be better, I think, to
> turn the table and say: if you want to debug the called function when
> this happen, set the option to this value; OTOH if you want ignore
> that and continue debugging the inferior, set the option to that other
> value.  Does this make sense?

OK thanks.

I spent some time thinking about what I was trying to say here, and in
the end I'm not convinced I'm actually adding much value with this
change.  I think the previous patch, and the doc changes in later
commits probably contains enough information.

So, for now at least, I'm going to propose dropping just hist patch from
the series.

Thanks,
Andrew