diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 4 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 162 |
2 files changed, 166 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 1eaf65c..4f375eb 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +2005-12-19 Michael Van Meter Snyder <michsnyd@clwang-lnx.cisco.com> + + * gdb.texinfo: Add documentation for multi-fork and checkpoint. + 2005-11-19 Jim Blandy <jimb@redhat.com> * gdb.texinfo (Tracepoint Packets): New node. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index d749732..76ab30a 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1740,6 +1740,7 @@ kill a child process. * Threads:: Debugging programs with multiple threads * Processes:: Debugging programs with multiple processes +* Checkpoint/Restart:: Setting a 'bookmark' to return to later @end menu @node Compilation @@ -2507,6 +2508,75 @@ unimpeded. Display the current debugger response to a @code{fork} or @code{vfork} call. @end table +If you want to debug both the parent and child processes, use the +command @w{@code{set detach-on-fork}}. + +@table @code +@kindex set detach-on-fork +@item set detach-on-fork @var{mode} +Tells gdb whether to detach one of the processes after a fork, or +retain debugger control over them both. + +@table @code +@item on +The child process (or parent process, depending on the value of +@var{follow-fork-mode}) will be detached and allowed to run +independently. This is the default. + +@item off +Both processes will be held under the control of @value{GDBN}. +One process (child or parent, depending on the value of +@var{follow-fork-mode}) is debugged as usual, while the other +is held suspended. + +@end table + +@kindex show detach-on-follow +@item show detach-on-follow +Show whether detach-on-follow mode is on/off. +@end table + +If you choose to set @var{detach-on-follow} mode off, then gdb will +retain control of all forked processes (including nested forks). +You can list the forked processes under the control of @value{GDBN} +by using the @w{@code{info forks}} command, and switch from one +fork to another by using the @w{@code{fork}} command. + +@table @code +@kindex info forks +@item info forks +Print a list of all forked processes under the control of @value{GDBN}. +The listing will include a fork id, a process id, and the current +position (program counter) of the process. + + +@kindex fork @var{fork-id} +@item fork @var{fork-id} +Make fork number @var{fork-id} the current process. The argument +@var{fork-id} is the internal fork number assigned by @value{GDBN}, +as shown in the first field of the @samp{info forks} display. + +@end table + +To quit debugging one of the forked processes, you can either +detach it by using the @w{@code{detach-fork}} command (allowing +it to run independently), or delete (and kill) it using the +@w{@code{delete-fork}} command. + +@table @code +@kindex detach-fork @var{fork-id} +@item detach-fork @var{fork-id} +Detach the process identified by @value{GDBN} fork number @var{fork-id}, +and remove it from the fork list. The process will be allowed to run +independently. + +@kindex delete-fork @var{fork-id} +@item delete-fork @var{fork-id} +Kill the process identified by @value{GDBN} fork number @var{fork-id}, +and remove it from the fork list. + +@end table + If you ask to debug a child process and a @code{vfork} is followed by an @code{exec}, @value{GDBN} executes the new target up to the first breakpoint in the new target. If you have a breakpoint set on @@ -2525,6 +2595,91 @@ You can use the @code{catch} command to make @value{GDBN} stop whenever a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set Catchpoints, ,Setting catchpoints}. +@node Checkpoint/Restart +@section Setting a 'bookmark' to return to later + +@cindex checkpoint +@cindex restart +@cindex bookmark + +On certain operating systems @footnote{Currently, only +@sc{gnu}/Linux.}, @value{GDBN} is able to save a @code{snapshot} of a +program's state, called a @code{checkpoint}, and come back to it +later. + +Returning to a @code{checkpoint} effectively undoes everything that +has happened in the program since the @code{checkpoint} was saved. +This includes changes in memory, registers, and even (within some +limits) system state. Effectively, it is like going back in time +to the moment when the checkpoint was saved. + +Thus, if you're stepping thru a program and you think you're +getting close to the point where things go wrong, you can save +a checkpoint. Then, if you accidentally go too far and miss +the critical statement, instead of having to restart your program +from the beginning, you can just go back to the checkpoint and +start again from there. + +This can be especially useful if it takes a lot of time or +steps to reach the point where you think the bug occurs. + +To use the @code{checkpoint}/@code{restart} method of debugging: + +@table @code +@kindex checkpoint +@item checkpoint +Save a snapshot of the debugged program's current execution state. +The @code{checkpoint} command takes no arguments, but each checkpoint +is assigned a small integer @code{id}, similar to a @code{breakpoint id}. + +@kindex info checkpoints +@item info checkpoints +List the checkpoints that have been saved in the current debugging +session. For each checkpoint, the following information will be +listed: + +@table @code +@item Checkpoint ID +@item Process ID +@item Code Address +@item Source line, or label +@end table + +@kindex restart @var{checkpoint-id} +@item restart @var{checkpoint-id} +Restore the program state that was saved as checkpoint number +@var{checkpoint-id}. All variables, registers, stack frames etc. +will be returned to the values that they had when the checkpoint +was saved. In essence, gdb will ``wind back the clock'' to the +point in time when the checkpoint was saved. + +@kindex delete-checkpoint @var{checkpoint-id} +@item delete-checkpoint @var{checkpoint-id} +Delete the previously-saved checkpoint identified by @var{checkpoint-id}. + +@end table + +Returning to a previously saved checkpoint will restore all program +state internal to the program being debugged, plus a significant +subset of the system (OS) state, including file pointers. It won't +``un-write'' data from a file, but it will rewind the file pointer +to the previous location, so that the previously written data can +be overwritten. For files opened in read mode, the pointer will +also be restored so that the previously read data can be read again. + +Of course, characters that have been sent to a printer (or other +external device) cannot be ``snatched back'', and characters received +from eg. a serial device can be removed from internal program buffers, +but they cannot be ``pushed back'' into the serial pipeline, ready to +be received again. Similarly, the actual contents of files that have +been changed cannot be restored (at this time). + +However, within those constraints, you actually can ``rewind'' your +program to a previously saved point in time, and begin debugging it +again -- and you can change the course events so as to debug a +different execution path this time. + + @node Stopping @chapter Stopping and Continuing @@ -2540,6 +2695,13 @@ continue execution. Usually, the messages shown by @value{GDBN} provide ample explanation of the status of your program---but you can also explicitly request this information at any time. +Finally, there is one bit of internal program state that will be +different when you return to a checkpoint -- the program's process +id. Each checkpoint will have a unique process id (or @var{pid}), +and each will be different from the program's original @var{pid}. +If your program has saved a local copy of its process id, this could +potentially pose a problem. + @table @code @kindex info program @item info program |