suggestions for node "(gdb)Set Watchpoints"

suggestions for node "(gdb)Set Watchpoints"

[Samuel Bronson]

Hi Eli,
    Pedro Alves told me to prod you if I wanted to make suggestions
for the manual?

This paragraph is found very close to the end of the node "(gdb)Set
Watchpoints" in the GDB 6.8 manual:

/----
   GDB automatically deletes watchpoints that watch local (automatic)
variables, or expressions that involve such variables, when they go out
of scope, that is, when the execution leaves the block in which these
variables were defined.  In particular, when the program being debugged
terminates, _all_ local variables go out of scope, and so only
watchpoints that watch global variables remain set.  If you rerun the
program, you will need to set all such watchpoints again.  One way of
doing that would be to set a code breakpoint at the entry to the `main'
function and when it breaks, set all the watchpoints.
\----

I actually didn't see this until I claimed it wasn't in the
documentation, and Pedro quoted the beginning of the paragraph to me
and linked me to that node of the online manual to me in #gdb. I think
this kind of thing might be prevented by moving it much nearer to the
bulleted list at the top of the node -- especially with the paragraph
that was already added between 6.8 and CVS HEAD (as of a few days
ago), which also discusses scope:

/---
   You can set a watchpoint on an expression even if the expression can
not be evaluated yet.  For instance, you can set a watchpoint on
`*global_ptr' before `global_ptr' is initialized.  GDB will stop when
your program sets `global_ptr' and the expression produces a valid
value.  If the expression becomes valid in some other way than changing
a variable (e.g. if the memory pointed to by `*global_ptr' becomes
readable as the result of a `malloc' call), GDB may not stop until the
next time the expression changes.
\----

This paragraph does make things a lot better, but at the same time
makes it even stranger that the other paragraph is so far away from
the description of what kinds of expressions to watch. I think the
other paragraph should be moved up to be with this one -- probably
after it.

It would also be nice to have a more in-depth description of exactly
which watchpoint-related events GDB is actually able to intercept.

Re: suggestions for node "(gdb)Set Watchpoints"

[Eli Zaretskii]

> Date: Mon, 8 Jun 2009 15:30:20 -0400
> From: Samuel Bronson <naesten@gmail.com>
> Cc: gdb@sourceware.org
> 
> This paragraph does make things a lot better, but at the same time
> makes it even stranger that the other paragraph is so far away from
> the description of what kinds of expressions to watch. I think the
> other paragraph should be moved up to be with this one -- probably
> after it.

Thanks, I will look into how this section could be re-arranged
better.  Please understand, however, that it is impossible to move
everything to the beginning of the section.  Most manual sections do
not include unimportant information, so it could be a tough choice.
The reader is assumed to read the text in its entirety, not just the
first couple of paragraphs.

> It would also be nice to have a more in-depth description of exactly
> which watchpoint-related events GDB is actually able to intercept.

Please elaborate.  Unless I misunderstand what you mean, we already
describe this in depth.