When you use libgdb, your code is providing a top level for the command language interpreter. The top level is significant because it provides commands for the the interpreter to execute. In addition, the top level is responsible for handling some kinds of errors, and performing certain cleanup operations on behalf of the interpreter.
Before calling any other libgdb functions, call this:
An application may wish to evaluate specific gdb commands as part of its own initialization. The details of how this can be accomplished are explained below.
There is a strong presumption in libgdb that the application has the form of a loop. Here is what such a loop might look like:
while (gdb_still_going ()) { if (!GDB_TOP_LEVEL ()) { char * command; gdb_start_top_loop (); command = process_events (); gdb_execute_command (command); gdb_finish_top_loop (); } }
The function gdb_still_going
returns 1 until the gdb command
`quit' is run.
The macro GDB_TOP_LEVEL
invokes setjmp to set the top level error
handler. When a command results in an error, the interpreter exits with
a longjmp. There is nothing special libgdb requires of the top level
error handler other than it be present and that it restart the top level
loop. Errors are explained in detail in a later chapter.
Each time through the top level loop two important things happen: a
debugger command is constructed on the basis of user input, and the
interpreter is invoked to execute that command. In the sample code, the
call to the imaginary function process_events
represents the
point at which a graphical interface should read input events until
ready to execute a debugger command. The call to
gdb_execute_command
invokes the command interpreter (what happens
to the output from the command will be explained later).
Libgdb manages some resources using the top-level loop. The primary
reason for this is error-handling: even if a command terminates with an
error, it may already have allocated resources which need to be freed.
The freeing of such resources takes place at the top-level, regardless
of how the the command exits. The calls to gdb_start_top_loop
and gdb_finish_top_loop
let libgdb know when it is safe to
perform operations associated with these resources.
Breakpoint commands are scripts of GDB operations associated with particular breakpoints. When a breakpoint is reached, its associated commands are executed.
Breakpoint commands are invoked by the libgdb function
gdb_finish_top_loop
.
Notice that if control returns to the top-level error handler, the
execution of breakpoint commands is bypassed. This can happen as a
result of errors during either gdb_execute_command
or
gdb_finish_top_loop
.
Sometimes it is inconvenient to execute commands via a command loop for
example, the commands an application uses to initialize itself. An
alternative to execute_command
is execute_catching_errors
.
When execute_catching_errors
is used, no top level error handler
need be in effect, and it is not necessary to call
gdb_start_top_loop
or gdb_finish_top_loop
.
The debugger command "quit" performs all necessary cleanup for libgdb.
After it has done so, it changes the return value of
gdb_still_going
to 0 and returns to the top level error handler.
Go to the first, previous, next, last section, table of contents.