@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
that situation.
+It is also possible to insert a breakpoint that will stop the program
+only if a specific thread (@pxref{Thread-Specific Breakpoints})
+or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
+
@item break
When called without any arguments, @code{break} sets a breakpoint at
the next instruction to be executed in the selected stack frame
another command. In background execution, @value{GDBN} immediately gives
a command prompt so that you can issue other commands while your program runs.
+You need to explicitly enable asynchronous mode before you can use
+background execution commands. You can use these commands to
+manipulate the asynchronous mode setting:
+
+@table @code
+@kindex set target-async
+@item set target-async on
+Enable asynchronous mode.
+@item set target-async off
+Disable asynchronous mode.
+@kindex show target-async
+@item show target-async
+Show the current target-async setting.
+@end table
+
+If the target doesn't support async mode, @value{GDBN} issues an error
+message if you attempt to use the background execution commands.
+
To specify background execution, add a @code{&} to the command. For example,
the background form of the @code{continue} command is @code{continue&}, or
just @code{c&}. The execution commands that accept background execution
use @code{interrupt -a}.
@end table
-You may need to explicitly enable async mode before you can use background
-execution commands, with the @code{set target-async 1} command. If the
-target doesn't support async mode, @value{GDBN} issues an error message
-if you attempt to use the background execution commands.
-
@node Thread-Specific Breakpoints
@subsection Thread-Specific Breakpoints
@group
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
-#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
+#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
+@noindent
+The value of parameter @code{data} in frame 1 has been replaced by
+@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter
+only if it is a scalar (integer, pointer, enumeration, etc). See command
+@kbd{set print frame-arguments} in @ref{Print Settings} for more details
+on how to configure the way function parameter values are printed.
+
@cindex value optimized out, in backtrace
@cindex function call arguments, optimized out
If your program was compiled with optimizations, some compilers will
located at the original location, a substitution rule is the only
method available to point @value{GDBN} at the new location.
+@cindex @samp{--with-relocated-sources}
+@cindex default source path substitution
+You can configure a default source path substitution rule by
+configuring @value{GDBN} with the
+@samp{--with-relocated-sources=@var{dir}} option. The @var{dir}
+should be the name of a directory under @value{GDBN}'s configured
+prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and
+directory names in debug information under @var{dir} will be adjusted
+automatically if the installed @value{GDBN} is moved to a new
+location. This is useful if @value{GDBN}, libraries or executables
+with debug information and corresponding source code are being moved
+together.
+
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
You can use the command @code{info line} to map source lines to program
addresses (and vice versa), and the command @code{disassemble} to display
-a range of addresses as machine instructions. When run under @sc{gnu} Emacs
+a range of addresses as machine instructions. You can use the command
+@code{set disassemble-next-line} to set whether to disassemble next
+source line when execution stops. When run under @sc{gnu} Emacs
mode, the @code{info line} command causes the arrow to point to the
line specified. Also, @code{info line} prints addresses in symbolic form as
well as hex.
Show the current setting of the disassembly flavor.
@end table
+@table @code
+@kindex set disassemble-next-line
+@kindex show disassemble-next-line
+@item set disassemble-next-line
+@itemx show disassemble-next-line
+Control whether or not @value{GDBN} will disassemble the next source
+line or instruction when execution stops. If ON, @value{GDBN} will
+display disassembly of the next source line when execution of the
+program being debugged stops. This is @emph{in addition} to
+displaying the source line itself, which @value{GDBN} always does if
+possible. If the next source line cannot be displayed for some reason
+(e.g., if @value{GDBN} cannot find the source file, or there's no line
+info in the debug info), @value{GDBN} will display disassembly of the
+next @emph{instruction} instead of showing the next source line. If
+AUTO, @value{GDBN} will display disassembly of next instruction only
+if the source line cannot be displayed. This setting causes
+@value{GDBN} to display some feedback when you step through a function
+with no line info or whose source file is unavailable. The default is
+OFF, which means never display the disassembly of the next line or
+instruction.
+@end table
+
@node Data
@chapter Examining Data
If the number is 0, then the printing is unlimited.
@item set print frame-arguments @var{value}
+@kindex set print frame-arguments
@cindex printing frame argument values
@cindex print all frame argument values
@cindex print frame argument values for scalars only
@table @code
@item all
-The values of all arguments are printed. This is the default.
+The values of all arguments are printed.
@item scalars
Print the value of an argument only if it is a scalar. The value of more
complex arguments such as arrays, structures, unions, etc, is replaced
-by @code{@dots{}}. Here is an example where only scalar arguments are shown:
+by @code{@dots{}}. This is the default. Here is an example where
+only scalar arguments are shown:
@smallexample
#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
@end smallexample
@end table
-By default, all argument values are always printed. But this command
-can be useful in several cases. For instance, it can be used to reduce
-the amount of information printed in each frame, making the backtrace
-more readable. Also, this command can be used to improve performance
-when displaying Ada frames, because the computation of large arguments
-can sometimes be CPU-intensive, especiallly in large applications.
-Setting @code{print frame-arguments} to @code{scalars} or @code{none}
-avoids this computation, thus speeding up the display of each Ada frame.
+By default, only scalar arguments are printed. This command can be used
+to configure the debugger to print the value of all arguments, regardless
+of their type. However, it is often advantageous to not print the value
+of more complex parameters. For instance, it reduces the amount of
+information printed in each frame, making the backtrace more readable.
+Also, it improves performance when displaying Ada frames, because
+the computation of large arguments can sometimes be CPU-intensive,
+especially in large applications. Setting @code{print frame-arguments}
+to @code{scalars} (the default) or @code{none} avoids this computation,
+thus speeding up the display of each Ada frame.
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
+@cindex convenience functions
+@value{GDBN} also supplies some @dfn{convenience functions}. These
+have a syntax similar to convenience variables. A convenience
+function can be used in an expression just like an ordinary function;
+however, a convenience function is implemented internally to
+@value{GDBN}.
+
+@table @code
+@item help function
+@kindex help function
+@cindex show all convenience functions
+Print a list of all convenience functions.
+@end table
+
@node Registers
@section Registers
@table @code
@item set target-charset @var{charset}
@kindex set target-charset
-Set the current target character set to @var{charset}. We list the
-character set names @value{GDBN} recognizes below, but if you type
-@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
-list the target character sets it supports.
-@end table
+Set the current target character set to @var{charset}. To display the
+list of supported target character sets, type
+@kbd{@w{set target-charset @key{TAB}@key{TAB}}}.
-@table @code
@item set host-charset @var{charset}
@kindex set host-charset
Set the current host character set to @var{charset}.
By default, @value{GDBN} uses a host character set appropriate to the
system it is running on; you can override that default using the
-@code{set host-charset} command.
+@code{set host-charset} command. On some systems, @value{GDBN} cannot
+automatically determine the appropriate host character set. In this
+case, @value{GDBN} uses @samp{UTF-8}.
@value{GDBN} can only use certain character sets as its host character
-set. We list the character set names @value{GDBN} recognizes below, and
-indicate which can be host character sets, but if you type
-@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
-list the host character sets it supports.
+set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}},
+@value{GDBN} will list the host character sets it supports.
@item set charset @var{charset}
@kindex set charset
Set the current host and target character sets to @var{charset}. As
-above, if you type @code{set charset} followed by @key{TAB}@key{TAB},
-@value{GDBN} will list the name of the character sets that can be used
+above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}},
+@value{GDBN} will list the names of the character sets that can be used
for both host and target.
-
@item show charset
@kindex show charset
-Show the names of the current host and target charsets.
+Show the names of the current host and target character sets.
-@itemx show host-charset
+@item show host-charset
@kindex show host-charset
-Show the name of the current host charset.
+Show the name of the current host character set.
-@itemx show target-charset
+@item show target-charset
@kindex show target-charset
-Show the name of the current target charset.
-
-@end table
-
-@value{GDBN} currently includes support for the following character
-sets:
-
-@table @code
+Show the name of the current target character set.
-@item ASCII
-@cindex ASCII character set
-Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host
-character set.
-
-@item ISO-8859-1
-@cindex ISO 8859-1 character set
-@cindex ISO Latin 1 character set
-The ISO Latin 1 character set. This extends @sc{ascii} with accented
-characters needed for French, German, and Spanish. @value{GDBN} can use
-this as its host character set.
-
-@item EBCDIC-US
-@itemx IBM1047
-@cindex EBCDIC character set
-@cindex IBM1047 character set
-Variants of the @sc{ebcdic} character set, used on some of IBM's
-mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.)
-@value{GDBN} cannot use these as its host character set.
+@item set target-wide-charset @var{charset}
+@kindex set target-wide-charset
+Set the current target's wide character set to @var{charset}. This is
+the character set used by the target's @code{wchar_t} type. To
+display the list of supported wide character sets, type
+@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}.
+@item show target-wide-charset
+@kindex show target-wide-charset
+Show the name of the current target's wide character set.
@end table
-Note that these are all single-byte character sets. More work inside
-@value{GDBN} is needed to support multi-byte or variable-width character
-encodings, like the UTF-8 and UCS-2 encodings of Unicode.
-
Here is an example of @value{GDBN}'s character set support in action.
Assume that the following source code has been placed in the file
@file{charset-test.c}:
@cindex definition, showing a macro's
@item info macro @var{macro}
Show the definition of the macro named @var{macro}, and describe the
-source location where that definition was established.
+source location or compiler command-line where that definition was established.
@kindex macro define
@cindex user-defined macros
(@value{GDBP})
@end smallexample
+In addition to source files, macros can be defined on the compilation command
+line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in
+such a way, @value{GDBN} displays the location of their definition as line zero
+of the source file submitted to the compiler.
+
+@smallexample
+(@value{GDBP}) info macro __STDC__
+Defined at /home/jimb/gdb/macros/play/sample.c:0
+-D__STDC__=1
+(@value{GDBP})
+@end smallexample
+
@node Tracepoints
@chapter Tracepoints
@section Commands to Set Tracepoints
Before running such a @dfn{trace experiment}, an arbitrary number of
-tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
-tracepoint has a number assigned to it by @value{GDBN}. Like with
-breakpoints, tracepoint numbers are successive integers starting from
-one. Many of the commands associated with tracepoints take the
-tracepoint number as their argument, to identify which tracepoint to
-work on.
+tracepoints can be set. A tracepoint is actually a special type of
+breakpoint (@pxref{Set Breaks}), so you can manipulate it using
+standard breakpoint commands. For instance, as with breakpoints,
+tracepoint numbers are successive integers starting from one, and many
+of the commands associated with tracepoints take the tracepoint number
+as their argument, to identify which tracepoint to work on.
For each tracepoint, you can specify, in advance, some arbitrary set
of data that you want the target to collect in the trace buffer when
commands to examine the values these data had at the time the
tracepoint was hit.
+Tracepoints do not support every breakpoint feature. Conditional
+expressions and ignore counts on tracepoints have no effect, and
+tracepoints cannot run @value{GDBN} commands when they are
+hit. Tracepoints may not be thread-specific either.
+
This section describes commands to set tracepoints and associated
conditions and actions.
@table @code
@cindex set tracepoint
@kindex trace
-@item trace
+@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument can be a source line, a function name, or an address in
-the target program. @xref{Set Breaks}. The @code{trace} command
-defines a tracepoint, which is a point in the target program where the
-debugger will briefly stop, collect some data, and then allow the
-program to continue. Setting a tracepoint or changing its commands
-doesn't take effect until the next @code{tstart} command; thus, you
-cannot change the tracepoint attributes once a trace experiment is
-running.
+Its argument @var{location} can be a source line, a function name, or
+an address in the target program. @xref{Specify Location}. The
+@code{trace} command defines a tracepoint, which is a point in the
+target program where the debugger will briefly stop, collect some
+data, and then allow the program to continue. Setting a tracepoint or
+changing its actions doesn't take effect until the next @code{tstart}
+command, and once a trace experiment is running, further changes will
+not have any effect until the next trace experiment starts.
Here are some examples of using the @code{trace} command:
@cindex tracepoint deletion
@item delete tracepoint @r{[}@var{num}@r{]}
Permanently delete one or more tracepoints. With no argument, the
-default is to delete all tracepoints.
+default is to delete all tracepoints. Note that the regular
+@code{delete} command can remove tracepoints also.
Examples:
@node Enable and Disable Tracepoints
@subsection Enable and Disable Tracepoints
+These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}.
+
@table @code
@kindex disable tracepoint
@item disable tracepoint @r{[}@var{num}@r{]}
@kindex info tp
@cindex information about tracepoints
@item info tracepoints @r{[}@var{num}@r{]}
-Display information about the tracepoint @var{num}. If you don't specify
-a tracepoint number, displays information about all the tracepoints
-defined so far. For each tracepoint, the following information is
-shown:
+Display information about the tracepoint @var{num}. If you don't
+specify a tracepoint number, displays information about all the
+tracepoints defined so far. The format is similar to that used for
+@code{info breakpoints}; in fact, @code{info tracepoints} is the same
+command, simply restricting itself to tracepoints.
+
+A tracepoint's listing may include additional information specific to
+tracing:
@itemize @bullet
@item
-its number
-@item
-whether it is enabled or disabled
-@item
-its address
-@item
its passcount as given by the @code{passcount @var{n}} command
@item
its step count as given by the @code{while-stepping @var{n}} command
@item
-where in the source files is the tracepoint set
-@item
-its action list as given by the @code{actions} command
+its action list as given by the @code{actions} command. The actions
+are prefixed with an @samp{A} so as to distinguish them from commands.
@end itemize
@smallexample
(@value{GDBP}) @b{info trace}
-Num Enb Address PassC StepC What
-1 y 0x002117c4 0 0 <gdb_asm>
-2 y 0x0020dc64 0 0 in g_test at g_test.c:1375
-3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
+Num Type Disp Enb Address What
+1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
+ pass count 1200
+ step count 20
+ A while-stepping 20
+ A collect globfoo, $regs
+ A end
+ A collect globfoo2
+ A end
(@value{GDBP})
@end smallexample
1 8088000 0 15 Child Activation Wait main_task
2 80a4000 1 15 Accept Statement b
3 809a800 1 15 Child Activation Wait a
-* 4 80ae800 3 15 Running c
+* 4 80ae800 3 15 Runnable c
@end smallexample
The task has been created but has not been activated. It cannot be
executing.
-@item Running
-The task currently running.
-
@item Runnable
The task is not blocked for any reason known to Ada. (It may be waiting
for a mutex, though.) It is conceptually "executing" in normal mode.
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077880 0 15 Child Activation Wait main_task
-* 2 807c468 1 15 Running task_1
+* 2 807c468 1 15 Runnable task_1
(@value{GDBP}) info task 2
Ada Task: 0x807c468
Name: task_1
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077870 0 15 Child Activation Wait main_task
-* 2 807c458 1 15 Running t
+* 2 807c458 1 15 Runnable t
(@value{GDBP}) task
[Current task is 2]
@end smallexample
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077870 0 15 Child Activation Wait main_task
-* 2 807c458 1 15 Running t
+* 2 807c458 1 15 Runnable t
(@value{GDBP}) task 1
[Switching to task 1]
#0 0x8067726 in pthread_cond_wait ()
#4 0x804aacc in un () at un.adb:5
@end smallexample
+@item break @var{linespec} task @var{taskno}
+@itemx break @var{linespec} task @var{taskno} if @dots{}
+@cindex breakpoints and tasks, in Ada
+@cindex task breakpoints, in Ada
+@kindex break @dots{} task @var{taskno}@r{ (Ada)}
+These commands are like the @code{break @dots{} thread @dots{}}
+command (@pxref{Thread Stops}).
+@var{linespec} specifies source lines, as described
+in @ref{Specify Location}.
+
+Use the qualifier @samp{task @var{taskno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular Ada task reaches this breakpoint. @var{taskno} is one of the
+numeric task identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info tasks} display.
+
+If you do not specify @samp{task @var{taskno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @samp{task @var{taskno}} before the
+breakpoint condition (before the @code{if}).
+
+For example,
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 140022020 0 15 Child Activation Wait main_task
+ 2 140045060 1 15 Accept/Select Wait t2
+ 3 140044840 1 15 Runnable t1
+* 4 140056040 1 15 Runnable t3
+(@value{GDBP}) b 15 task 2
+Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
+(@value{GDBP}) cont
+Continuing.
+task # 1 running
+task # 2 running
+
+Breakpoint 5, test_task_debug () at test_task_debug.adb:15
+15 flush;
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 140022020 0 15 Child Activation Wait main_task
+* 2 140045060 1 15 Runnable t2
+ 3 140044840 1 15 Runnable t1
+ 4 140056040 1 15 Delay Sleep t3
+@end smallexample
@end table
@node Ada Tasks and Core Files
and Stepping, ,Continuing and Stepping}) resumes execution until the
selected stack frame returns naturally.
+@value{GDBN} needs to know how the @var{expression} argument should be set for
+the inferior. The concrete registers assignment depends on the OS ABI and the
+type being returned by the selected stack frame. For example it is common for
+OS ABI to return floating point values in FPU registers while integer values in
+CPU registers. Still some ABIs return even floating point values in CPU
+registers. Larger integer widths (such as @code{long long int}) also have
+specific placement rules. @value{GDBN} already knows the OS ABI from its
+current target so it needs to find out also the type being returned to make the
+assignment into the right register(s).
+
+Normally, the selected stack frame has debug info. @value{GDBN} will always
+use the debug info instead of the implicit type of @var{expression} when the
+debug info is available. For example, if you type @kbd{return -1}, and the
+function in the current stack frame is declared to return a @code{long long
+int}, @value{GDBN} transparently converts the implicit @code{int} value of -1
+into a @code{long long int}:
+
+@smallexample
+Breakpoint 1, func () at gdb.base/return-nodebug.c:29
+29 return 31;
+(@value{GDBP}) return -1
+Make func return now? (y or n) y
+#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
+43 printf ("result=%lld\n", func ());
+(@value{GDBP})
+@end smallexample
+
+However, if the selected stack frame does not have a debug info, e.g., if the
+function was compiled without debug info, @value{GDBN} has to find out the type
+to return from user. Specifying a different type by mistake may set the value
+in different inferior registers than the caller code expects. For example,
+typing @kbd{return -1} with its implicit type @code{int} would set only a part
+of a @code{long long int} result for a debug info less function (on 32-bit
+architectures). Therefore the user is required to specify the return type by
+an appropriate cast explicitly:
+
+@smallexample
+Breakpoint 2, 0x0040050b in func ()
+(@value{GDBP}) return -1
+Return value type not available for selected stack frame.
+Please use an explicit cast of the value to return.
+(@value{GDBP}) return (long long int) -1
+Make selected stack frame return now? (y or n) y
+#0 0x00400526 in main ()
+(@value{GDBP})
+@end smallexample
+
@node Calling
@section Calling Program Functions
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
* Symbol Errors:: Errors reading symbol files
+* Data Files:: GDB data files
@end menu
@node Files
@end table
+@node Data Files
+@section GDB Data Files
+
+@cindex prefix for data files
+@value{GDBN} will sometimes read an auxiliary data file. These files
+are kept in a directory known as the @dfn{data directory}.
+
+You can set the data directory's name, and view the name @value{GDBN}
+is currently using.
+
+@table @code
+@kindex set data-directory
+@item set data-directory @var{directory}
+Set the directory which @value{GDBN} searches for auxiliary data files
+to @var{directory}.
+
+@kindex show data-directory
+@item show data-directory
+Show the directory @value{GDBN} searches for auxiliary data files.
+@end table
+
+@cindex default data directory
+@cindex @samp{--with-gdb-datadir}
+You can set the default data directory by using the configure-time
+@samp{--with-gdb-datadir} option. If the data directory is inside
+@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
+@samp{--exec-prefix}), then the default data directory will be updated
+automatically if the installed @value{GDBN} is moved to a new
+location.
+
@node Targets
@chapter Specifying a Debugging Target
@item @code{osdata}
@tab @code{qXfer:osdata:read}
@tab @code{info os}
+
+@item @code{query-attached}
+@tab @code{qAttached}
+@tab Querying remote process attach state.
@end multitable
@node Remote Stub
* Exception Handling::
* Values From Inferior::
* Commands In Python:: Implementing new commands in Python.
+* Functions In Python:: Writing new convenience functions.
+* Frames In Python:: Acessing inferior stack frames from Python.
@end menu
@node Basic Python
Again, @code{bar} will also be a @code{gdb.Value} object.
-For pointer data types, @code{gdb.Value} provides a method for
-dereferencing the pointer to obtain the object it points to.
+The following attributes are provided:
+@table @code
+@defmethod Value address
+If this object is addressable, this read-only attribute holds a
+@code{gdb.Value} object representing the address. Otherwise,
+this attribute holds @code{None}.
+@end defmethod
+
+@cindex optimized out value in Python
+@defmethod Value is_optimized_out
+This read-only boolean attribute is true if the compiler optimized out
+this value, thus it is not available for fetching from the inferior.
+@end defmethod
+@end table
+
+The following methods are provided:
+
+@table @code
@defmethod Value dereference
-This method returns a new @code{gdb.Value} object whose contents is
-the object pointed to by the pointer. For example, if @code{foo} is
-a C pointer to an @code{int}, declared in your C program as
+For pointer data types, this method returns a new @code{gdb.Value} object
+whose contents is the object pointed to by the pointer. For example, if
+@code{foo} is a C pointer to an @code{int}, declared in your C program as
@smallexample
int *foo;
value pointed to by @code{foo}.
@end defmethod
-@defmethod Value string @r{[}encoding @r{[}errors@r{]}@r{]}
+@defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]}
If this @code{gdb.Value} represents a string, then this method
converts the contents to a Python string. Otherwise, this method will
throw an exception.
The optional @var{errors} argument is the same as the corresponding
argument to Python's @code{string.decode} method.
@end defmethod
+@end table
@node Commands In Python
@subsubsection Commands In Python
@cindex commands in python
@cindex python commands
-@tindex Command
-@tindex gdb.Command
You can implement new @value{GDBN} CLI commands in Python. A CLI
command is implemented using an instance of the @code{gdb.Command}
class, most commonly using a subclass.
-@defmethod Command __init__ name @var{command-class} @r{[}@var{completer-class} @var{prefix}@r{]}
+@defmethod Command __init__ name @var{command_class} @r{[}@var{completer_class}@r{]} @r{[}@var{prefix}@r{]}
The object initializer for @code{Command} registers the new command
with @value{GDBN}. This initializer is normally invoked from the
subclass' own @code{__init__} method.
There is no support for multi-line commands.
-@var{command-class} should be one of the @samp{COMMAND_} constants
+@var{command_class} should be one of the @samp{COMMAND_} constants
defined below. This argument tells @value{GDBN} how to categorize the
new command in the help system.
-@var{completer-class} is an optional argument. If given, it should be
+@var{completer_class} is an optional argument. If given, it should be
one of the @samp{COMPLETE_} constants defined below. This argument
tells @value{GDBN} how to perform completion for this command. If not
given, @value{GDBN} will attempt to complete using the object's
Python code is read into @value{GDBN}, you may need to import the
@code{gdb} module explicitly.
+@node Functions In Python
+@subsubsection Writing new convenience functions
+
+@cindex writing convenience functions
+@cindex convenience functions in python
+@cindex python convenience functions
+@tindex gdb.Function
+@tindex Function
+You can implement new convenience functions (@pxref{Convenience Vars})
+in Python. A convenience function is an instance of a subclass of the
+class @code{gdb.Function}.
+
+@defmethod Function __init__ name
+The initializer for @code{Function} registers the new function with
+@value{GDBN}. The argument @var{name} is the name of the function,
+a string. The function will be visible to the user as a convenience
+variable of type @code{internal function}, whose name is the same as
+the given @var{name}.
+
+The documentation for the new function is taken from the documentation
+string for the new class.
+@end defmethod
+
+@defmethod Function invoke @var{*args}
+When a convenience function is evaluated, its arguments are converted
+to instances of @code{gdb.Value}, and then the function's
+@code{invoke} method is called. Note that @value{GDBN} does not
+predetermine the arity of convenience functions. Instead, all
+available arguments are passed to @code{invoke}, following the
+standard Python calling convention. In particular, a convenience
+function can have default values for parameters without ill effect.
+
+The return value of this method is used as its value in the enclosing
+expression. If an ordinary Python value is returned, it is converted
+to a @code{gdb.Value} following the usual rules.
+@end defmethod
+
+The following code snippet shows how a trivial convenience function can
+be implemented in Python:
+
+@smallexample
+class Greet (gdb.Function):
+ """Return string to greet someone.
+Takes a name as argument."""
+
+ def __init__ (self):
+ super (Greet, self).__init__ ("greet")
+
+ def invoke (self, name):
+ return "Hello, %s!" % name.string ()
+
+Greet ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the function with @value{GDBN}. Depending on how the
+Python code is read into @value{GDBN}, you may need to import the
+@code{gdb} module explicitly.
+
+@node Frames In Python
+@subsubsection Acessing inferior stack frames from Python.
+
+@cindex frames in python
+When the debugged program stops, @value{GDBN} is able to analyze its call
+stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
+represents a frame in the stack. A @code{gdb.Frame} object is only valid
+while its corresponding frame exists in the inferior's stack. If you try
+to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError}
+exception.
+
+Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
+operator, like:
+
+@smallexample
+(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
+True
+@end smallexample
+
+The following frame-related functions are available in the @code{gdb} module:
+
+@findex gdb.selected_frame
+@defun selected_frame
+Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
+@end defun
+
+@defun frame_stop_reason_string reason
+Return a string explaining the reason why @value{GDBN} stopped unwinding
+frames, as expressed by the given @var{reason} code (an integer, see the
+@code{unwind_stop_reason} method further down in this section).
+@end defun
+
+A @code{gdb.Frame} object has the following methods:
+
+@table @code
+@defmethod Frame is_valid
+Returns true if the @code{gdb.Frame} object is valid, false if not.
+A frame object can become invalid if the frame it refers to doesn't
+exist anymore in the inferior. All @code{gdb.Frame} methods will throw
+an exception if it is invalid at the time the method is called.
+@end defmethod
+
+@defmethod Frame name
+Returns the function name of the frame, or @code{None} if it can't be
+obtained.
+@end defmethod
+
+@defmethod Frame type
+Returns the type of the frame. The value can be one of
+@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
+or @code{gdb.SENTINEL_FRAME}.
+@end defmethod
+
+@defmethod Frame unwind_stop_reason
+Return an integer representing the reason why it's not possible to find
+more frames toward the outermost frame. Use
+@code{gdb.frame_stop_reason_string} to convert the value returned by this
+function to a string.
+@end defmethod
+
+@defmethod Frame pc
+Returns the frame's resume address.
+@end defmethod
+
+@defmethod Frame older
+Return the frame that called this frame.
+@end defmethod
+
+@defmethod Frame newer
+Return the frame called by this frame.
+@end defmethod
+
+@defmethod Frame read_var variable
+Return the value of the given variable in this frame. @var{variable} must
+be a string.
+@end defmethod
+@end table
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
(gdb)
@end smallexample
+@subheading The @code{-exec-jump} Command
+@findex -exec-jump
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-jump @var{location}
+@end smallexample
+
+Resumes execution of the inferior program at the location specified by
+parameter. @xref{Specify Location}, for a description of the
+different forms of @var{location}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{jump}.
+
+@subsubheading Example
+
+@smallexample
+-exec-jump foo.c:10
+*running,thread-id="all"
+^running
+@end smallexample
+
@subheading The @code{-exec-next} Command
@findex -exec-next
distribution; if it is not, you can get the latest version from
@url{http://zlib.net}.
+@item iconv
+@value{GDBN}'s features related to character sets (@pxref{Character
+Sets}) require a functioning @code{iconv} implementation. If you are
+on a GNU system, then this is provided by the GNU C Library. Some
+other systems also provide a working @code{iconv}.
+
+On systems with @code{iconv}, you can install GNU Libiconv. If you
+have previously installed Libiconv, you can use the
+@option{--with-libiconv-prefix} option to configure.
+
+@value{GDBN}'s top-level @file{configure} and @file{Makefile} will
+arrange to build Libiconv if a directory named @file{libiconv} appears
+in the top-most source directory. If Libiconv is built this way, and
+if the operating system does not provide a suitable @code{iconv}
+implementation, then the just-built library will automatically be used
+by @value{GDBN}. One easy way to set this up is to download GNU
+Libiconv, unpack it, and then rename the directory holding the
+Libiconv source code to @samp{libiconv}.
@end table
@node Running Configure
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
compiled with the @samp{-pg} compiler option.
-@kindex maint set linux-async
-@kindex maint show linux-async
-@cindex asynchronous support
-@item maint set linux-async
-@itemx maint show linux-async
-Control the GNU/Linux native asynchronous support
-(@pxref{Background Execution}) of @value{GDBN}.
-
-GNU/Linux native asynchronous support will be disabled until you use
-the @samp{maint set linux-async} command to enable it.
-
-@kindex maint set remote-async
-@kindex maint show remote-async
-@cindex asynchronous support
-@item maint set remote-async
-@itemx maint show remote-async
-Control the remote asynchronous support
-(@pxref{Background Execution}) of @value{GDBN}.
-
-Remote asynchronous support will be disabled until you use
-the @samp{maint set remote-async} command to enable it.
-
@kindex maint show-debug-regs
-@cindex x86 hardware debug registers
+@cindex hardware debug registers
@item maint show-debug-regs
-Control whether to show variables that mirror the x86 hardware debug
+Control whether to show variables that mirror the hardware debug
registers. Use @code{ON} to enable, @code{OFF} to disable. If
enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
@var{object} does not recognize the @var{operation} keyword, the stub
must respond with an empty packet.
+@item qAttached:@var{pid}
+@cindex query attached, remote request
+@cindex @samp{qAttached} packet
+Return an indication of whether the remote server attached to an
+existing process or created a new process. When the multiprocess
+protocol extensions are supported (@pxref{multiprocess extensions}),
+@var{pid} is an integer in hexadecimal format identifying the target
+process. Otherwise, @value{GDBN} will omit the @var{pid} field and
+the query packet will be simplified as @samp{qAttached}.
+
+This query is used, for example, to know whether the remote process
+should be detached or killed when a @value{GDBN} session is ended with
+the @code{quit} command.
+
+Reply:
+@table @samp
+@item 1
+The remote server attached to an existing process.
+@item 0
+The remote server created a new process.
+@item E @var{NN}
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Register Packet Format
projects / deliverable / binutils-gdb.git / blobdiff