diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index a92bec70f9..899fe88610 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +2006-01-04 Michael Snyder + + * gdb.texinfo: Add documentation for linux-fork. + * gdbint.texinfo: Add internal documentation for checkpoints. + 2006-01-02 Paul N. Hilfinger * gdb.texinfo (Omissions from Ada): Document that there is now diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 92f44d8424..5cb3bb0616 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 @emph{bookmark} to return to later @end menu @node Compilation @@ -2507,6 +2508,76 @@ unimpeded. Display the current debugger response to a @code{fork} or @code{vfork} call. @end table +@cindex debugging multiple processes +On Linux, 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 +@code{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 +@code{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 +@value{GDBN} 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 +from 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 from 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 +2596,120 @@ 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 @emph{bookmark} to return to later + +@cindex checkpoint +@cindex restart +@cindex bookmark +@cindex snapshot of a process +@cindex rewind program state + +On certain operating systems@footnote{Currently, only +@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a +program's state, called a @dfn{checkpoint}, and come back to it +later. + +Returning to a 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 id, similar to a 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 program 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. + +Note that breakpoints, @value{GDBN} variables, command history etc. +are not affected by restoring a checkpoint. In general, a checkpoint +only restores things that reside in the program being debugged, not in +the debugger. + +@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 the user state +of 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 of events so as to debug a +different execution path this time. + +@cindex checkpoints and process id +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. + +@subsection A non-obvious benefit of using checkpoints + +On some systems such as @sc{gnu}/Linux, address space randomization +is performed on new processes for security reasons. This makes it +difficult or impossible to set a breakpoint, or watchpoint, on an +absolute address if you have to restart the program, since the +absolute location of a symbol will change from one execution to the +next. + +A checkpoint, however, is an @emph{identical} copy of a process. +Therefore if you create a checkpoint at (eg.@:) the start of main, +and simply return to that checkpoint instead of restarting the +process, you can avoid the effects of address randomization and +your symbols will all stay in the same place. + @node Stopping @chapter Stopping and Continuing diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 68aa9b40e9..3007e0a24e 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -712,6 +712,38 @@ watchpoints might interfere with the underlying OS and are probably unavailable in many platforms. @end enumerate +@section Checkpoints +@cindex checkpoints +@cindex restart +In the abstract, a checkpoint is a point in the execution history of +the program, which the user may wish to return to at some later time. + +Internally, a checkpoint is a saved copy of the program state, including +whatever information is required in order to restore the program to that +state at a later time. This can be expected to include the state of +registers and memory, and may include external state such as the state +of open files and devices. + +There are a number of ways in which checkpoints may be implemented +in gdb, eg. as corefiles, as forked processes, and as some opaque +method implemented on the target side. + +A corefile can be used to save an image of target memory and register +state, which can in principle be restored later --- but corefiles do +not typically include information about external entities such as +open files. Currently this method is not implemented in gdb. + +A forked process can save the state of user memory and registers, +as well as some subset of external (kernel) state. This method +is used to implement checkpoints on Linux, and in principle might +be used on other systems. + +Some targets, eg.@: simulators, might have their own built-in +method for saving checkpoints, and gdb might be able to take +advantage of that capability without necessarily knowing any +details of how it is done. + + @section Observing changes in @value{GDBN} internals @cindex observer pattern interface @cindex notifications about changes in internals