| This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| END-INFO-DIR-ENTRY |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Ninth Edition, of `Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 7.2. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native |
| |
| 21.1.4 Features for Debugging DJGPP Programs |
| -------------------------------------------- |
| |
| DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. |
| DJGPP programs are 32-bit protected-mode programs that use the "DPMI" |
| (DOS Protected-Mode Interface) API to run on top of real-mode DOS |
| systems and their emulations. |
| |
| GDB supports native debugging of DJGPP programs, and defines a few |
| commands specific to the DJGPP port. This subsection describes those |
| commands. |
| |
| `info dos' |
| This is a prefix of DJGPP-specific commands which print |
| information about the target system and important OS structures. |
| |
| `info dos sysinfo' |
| This command displays assorted information about the underlying |
| platform: the CPU type and features, the OS version and flavor, the |
| DPMI version, and the available conventional and DPMI memory. |
| |
| `info dos gdt' |
| `info dos ldt' |
| `info dos idt' |
| These 3 commands display entries from, respectively, Global, Local, |
| and Interrupt Descriptor Tables (GDT, LDT, and IDT). The |
| descriptor tables are data structures which store a descriptor for |
| each segment that is currently in use. The segment's selector is |
| an index into a descriptor table; the table entry for that index |
| holds the descriptor's base address and limit, and its attributes |
| and access rights. |
| |
| A typical DJGPP program uses 3 segments: a code segment, a data |
| segment (used for both data and the stack), and a DOS segment |
| (which allows access to DOS/BIOS data structures and absolute |
| addresses in conventional memory). However, the DPMI host will |
| usually define additional segments in order to support the DPMI |
| environment. |
| |
| These commands allow to display entries from the descriptor tables. |
| Without an argument, all entries from the specified table are |
| displayed. An argument, which should be an integer expression, |
| means display a single entry whose index is given by the argument. |
| For example, here's a convenient way to display information about |
| the debugged program's data segment: |
| |
| `(gdb) info dos ldt $ds' |
| `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' |
| |
| |
| This comes in handy when you want to see whether a pointer is |
| outside the data segment's limit (i.e. "garbled"). |
| |
| `info dos pde' |
| `info dos pte' |
| These two commands display entries from, respectively, the Page |
| Directory and the Page Tables. Page Directories and Page Tables |
| are data structures which control how virtual memory addresses are |
| mapped into physical addresses. A Page Table includes an entry |
| for every page of memory that is mapped into the program's address |
| space; there may be several Page Tables, each one holding up to |
| 4096 entries. A Page Directory has up to 4096 entries, one each |
| for every Page Table that is currently in use. |
| |
| Without an argument, `info dos pde' displays the entire Page |
| Directory, and `info dos pte' displays all the entries in all of |
| the Page Tables. An argument, an integer expression, given to the |
| `info dos pde' command means display only that entry from the Page |
| Directory table. An argument given to the `info dos pte' command |
| means display entries from a single Page Table, the one pointed to |
| by the specified entry in the Page Directory. |
| |
| These commands are useful when your program uses "DMA" (Direct |
| Memory Access), which needs physical addresses to program the DMA |
| controller. |
| |
| These commands are supported only with some DPMI servers. |
| |
| `info dos address-pte ADDR' |
| This command displays the Page Table entry for a specified linear |
| address. The argument ADDR is a linear address which should |
| already have the appropriate segment's base address added to it, |
| because this command accepts addresses which may belong to _any_ |
| segment. For example, here's how to display the Page Table entry |
| for the page where a variable `i' is stored: |
| |
| `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' |
| `Page Table entry for address 0x11a00d30:' |
| `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' |
| |
| |
| This says that `i' is stored at offset `0xd30' from the page whose |
| physical base address is `0x02698000', and shows all the |
| attributes of that page. |
| |
| Note that you must cast the addresses of variables to a `char *', |
| since otherwise the value of `__djgpp_base_address', the base |
| address of all variables and functions in a DJGPP program, will be |
| added using the rules of C pointer arithmetics: if `i' is declared |
| an `int', GDB will add 4 times the value of `__djgpp_base_address' |
| to the address of `i'. |
| |
| Here's another example, it displays the Page Table entry for the |
| transfer buffer: |
| |
| `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' |
| `Page Table entry for address 0x29110:' |
| `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' |
| |
| |
| (The `+ 3' offset is because the transfer buffer's address is the |
| 3rd member of the `_go32_info_block' structure.) The output |
| clearly shows that this DPMI server maps the addresses in |
| conventional memory 1:1, i.e. the physical (`0x00029000' + |
| `0x110') and linear (`0x29110') addresses are identical. |
| |
| This command is supported only with some DPMI servers. |
| |
| In addition to native debugging, the DJGPP port supports remote |
| debugging via a serial data link. The following commands are specific |
| to remote serial debugging in the DJGPP port of GDB. |
| |
| `set com1base ADDR' |
| This command sets the base I/O port address of the `COM1' serial |
| port. |
| |
| `set com1irq IRQ' |
| This command sets the "Interrupt Request" (`IRQ') line to use for |
| the `COM1' serial port. |
| |
| There are similar commands `set com2base', `set com3irq', etc. for |
| setting the port address and the `IRQ' lines for the other 3 COM |
| ports. |
| |
| The related commands `show com1base', `show com1irq' etc. display |
| the current settings of the base address and the `IRQ' lines used |
| by the COM ports. |
| |
| `info serial' |
| This command prints the status of the 4 DOS serial ports. For each |
| port, it prints whether it's active or not, its I/O base address |
| and IRQ number, whether it uses a 16550-style FIFO, its baudrate, |
| and the counts of various errors encountered so far. |
| |
| |
| File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native |
| |
| 21.1.5 Features for Debugging MS Windows PE Executables |
| ------------------------------------------------------- |
| |
| GDB supports native debugging of MS Windows programs, including DLLs |
| with and without symbolic debugging information. |
| |
| MS-Windows programs that call `SetConsoleMode' to switch off the |
| special meaning of the `Ctrl-C' keystroke cannot be interrupted by |
| typing `C-c'. For this reason, GDB on MS-Windows supports `C-<BREAK>' |
| as an alternative interrupt key sequence, which can be used to |
| interrupt the debuggee even if it ignores `C-c'. |
| |
| There are various additional Cygwin-specific commands, described in |
| this section. Working with DLLs that have no debugging symbols is |
| described in *Note Non-debug DLL Symbols::. |
| |
| `info w32' |
| This is a prefix of MS Windows-specific commands which print |
| information about the target system and important OS structures. |
| |
| `info w32 selector' |
| This command displays information returned by the Win32 API |
| `GetThreadSelectorEntry' function. It takes an optional argument |
| that is evaluated to a long value to give the information about |
| this given selector. Without argument, this command displays |
| information about the six segment registers. |
| |
| `info w32 thread-information-block' |
| This command displays thread specific information stored in the |
| Thread Information Block (readable on the X86 CPU family using |
| `$fs' selector for 32-bit programs and `$gs' for 64-bit programs). |
| |
| `info dll' |
| This is a Cygwin-specific alias of `info shared'. |
| |
| `dll-symbols' |
| This command loads symbols from a dll similarly to add-sym command |
| but without the need to specify a base address. |
| |
| `set cygwin-exceptions MODE' |
| If MODE is `on', GDB will break on exceptions that happen inside |
| the Cygwin DLL. If MODE is `off', GDB will delay recognition of |
| exceptions, and may ignore some exceptions which seem to be caused |
| by internal Cygwin DLL "bookkeeping". This option is meant |
| primarily for debugging the Cygwin DLL itself; the default value |
| is `off' to avoid annoying GDB users with false `SIGSEGV' signals. |
| |
| `show cygwin-exceptions' |
| Displays whether GDB will break on exceptions that happen inside |
| the Cygwin DLL itself. |
| |
| `set new-console MODE' |
| If MODE is `on' the debuggee will be started in a new console on |
| next start. If MODE is `off', the debuggee will be started in the |
| same console as the debugger. |
| |
| `show new-console' |
| Displays whether a new console is used when the debuggee is |
| started. |
| |
| `set new-group MODE' |
| This boolean value controls whether the debuggee should start a |
| new group or stay in the same group as the debugger. This affects |
| the way the Windows OS handles `Ctrl-C'. |
| |
| `show new-group' |
| Displays current value of new-group boolean. |
| |
| `set debugevents' |
| This boolean value adds debug output concerning kernel events |
| related to the debuggee seen by the debugger. This includes |
| events that signal thread and process creation and exit, DLL |
| loading and unloading, console interrupts, and debugging messages |
| produced by the Windows `OutputDebugString' API call. |
| |
| `set debugexec' |
| This boolean value adds debug output concerning execute events |
| (such as resume thread) seen by the debugger. |
| |
| `set debugexceptions' |
| This boolean value adds debug output concerning exceptions in the |
| debuggee seen by the debugger. |
| |
| `set debugmemory' |
| This boolean value adds debug output concerning debuggee memory |
| reads and writes by the debugger. |
| |
| `set shell' |
| This boolean values specifies whether the debuggee is called via a |
| shell or directly (default value is on). |
| |
| `show shell' |
| Displays if the debuggee will be started with a shell. |
| |
| |
| * Menu: |
| |
| * Non-debug DLL Symbols:: Support for DLLs without debugging symbols |
| |
| |
| File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native |
| |
| 21.1.5.1 Support for DLLs without Debugging Symbols |
| ................................................... |
| |
| Very often on windows, some of the DLLs that your program relies on do |
| not include symbolic debugging information (for example, |
| `kernel32.dll'). When GDB doesn't recognize any debugging symbols in a |
| DLL, it relies on the minimal amount of symbolic information contained |
| in the DLL's export table. This section describes working with such |
| symbols, known internally to GDB as "minimal symbols". |
| |
| Note that before the debugged program has started execution, no DLLs |
| will have been loaded. The easiest way around this problem is simply to |
| start the program -- either by setting a breakpoint or letting the |
| program run once to completion. It is also possible to force GDB to |
| load a particular DLL before starting the executable -- see the shared |
| library information in *Note Files::, or the `dll-symbols' command in |
| *Note Cygwin Native::. Currently, explicitly loading symbols from a |
| DLL with no debugging information will cause the symbol names to be |
| duplicated in GDB's lookup table, which may adversely affect symbol |
| lookup performance. |
| |
| 21.1.5.2 DLL Name Prefixes |
| .......................... |
| |
| In keeping with the naming conventions used by the Microsoft debugging |
| tools, DLL export symbols are made available with a prefix based on the |
| DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also |
| entered into the symbol table, so `CreateFileA' is often sufficient. |
| In some cases there will be name clashes within a program (particularly |
| if the executable itself includes full debugging symbols) necessitating |
| the use of the fully qualified name when referring to the contents of |
| the DLL. Use single-quotes around the name to avoid the exclamation |
| mark ("!") being interpreted as a language operator. |
| |
| Note that the internal name of the DLL may be all upper-case, even |
| though the file name of the DLL is lower-case, or vice-versa. Since |
| symbols within GDB are _case-sensitive_ this may cause some confusion. |
| If in doubt, try the `info functions' and `info variables' commands or |
| even `maint print msymbols' (*note Symbols::). Here's an example: |
| |
| (gdb) info function CreateFileA |
| All functions matching regular expression "CreateFileA": |
| |
| Non-debugging symbols: |
| 0x77e885f4 CreateFileA |
| 0x77e885f4 KERNEL32!CreateFileA |
| |
| (gdb) info function ! |
| All functions matching regular expression "!": |
| |
| Non-debugging symbols: |
| 0x6100114c cygwin1!__assert |
| 0x61004034 cygwin1!_dll_crt0@0 |
| 0x61004240 cygwin1!dll_crt0(per_process *) |
| [etc...] |
| |
| 21.1.5.3 Working with Minimal Symbols |
| ..................................... |
| |
| Symbols extracted from a DLL's export table do not contain very much |
| type information. All that GDB can do is guess whether a symbol refers |
| to a function or variable depending on the linker section that contains |
| the symbol. Also note that the actual contents of the memory contained |
| in a DLL are not available unless the program is running. This means |
| that you cannot examine the contents of a variable or disassemble a |
| function within a DLL without a running program. |
| |
| Variables are generally treated as pointers and dereferenced |
| automatically. For this reason, it is often necessary to prefix a |
| variable name with the address-of operator ("&") and provide explicit |
| type information in the command. Here's an example of the type of |
| problem: |
| |
| (gdb) print 'cygwin1!__argv' |
| $1 = 268572168 |
| |
| (gdb) x 'cygwin1!__argv' |
| 0x10021610: "\230y\"" |
| |
| And two possible solutions: |
| |
| (gdb) print ((char **)'cygwin1!__argv')[0] |
| $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" |
| |
| (gdb) x/2x &'cygwin1!__argv' |
| 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 |
| (gdb) x/x 0x10021608 |
| 0x10021608: 0x0022fd98 |
| (gdb) x/s 0x0022fd98 |
| 0x22fd98: "/cygdrive/c/mydirectory/myprogram" |
| |
| Setting a break point within a DLL is possible even before the |
| program starts execution. However, under these circumstances, GDB can't |
| examine the initial instructions of the function in order to skip the |
| function's frame set-up code. You can work around this by using "*&" to |
| set the breakpoint at a raw memory address: |
| |
| (gdb) break *&'python22!PyOS_Readline' |
| Breakpoint 1 at 0x1e04eff0 |
| |
| The author of these extensions is not entirely convinced that |
| setting a break point within a shared DLL like `kernel32.dll' is |
| completely safe. |
| |
| |
| File: gdb.info, Node: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native |
| |
| 21.1.6 Commands Specific to GNU Hurd Systems |
| -------------------------------------------- |
| |
| This subsection describes GDB commands specific to the GNU Hurd native |
| debugging. |
| |
| `set signals' |
| `set sigs' |
| This command toggles the state of inferior signal interception by |
| GDB. Mach exceptions, such as breakpoint traps, are not affected |
| by this command. `sigs' is a shorthand alias for `signals'. |
| |
| `show signals' |
| `show sigs' |
| Show the current state of intercepting inferior's signals. |
| |
| `set signal-thread' |
| `set sigthread' |
| This command tells GDB which thread is the `libc' signal thread. |
| That thread is run when a signal is delivered to a running |
| process. `set sigthread' is the shorthand alias of `set |
| signal-thread'. |
| |
| `show signal-thread' |
| `show sigthread' |
| These two commands show which thread will run when the inferior is |
| delivered a signal. |
| |
| `set stopped' |
| This commands tells GDB that the inferior process is stopped, as |
| with the `SIGSTOP' signal. The stopped process can be continued |
| by delivering a signal to it. |
| |
| `show stopped' |
| This command shows whether GDB thinks the debuggee is stopped. |
| |
| `set exceptions' |
| Use this command to turn off trapping of exceptions in the |
| inferior. When exception trapping is off, neither breakpoints nor |
| single-stepping will work. To restore the default, set exception |
| trapping on. |
| |
| `show exceptions' |
| Show the current state of trapping exceptions in the inferior. |
| |
| `set task pause' |
| This command toggles task suspension when GDB has control. |
| Setting it to on takes effect immediately, and the task is |
| suspended whenever GDB gets control. Setting it to off will take |
| effect the next time the inferior is continued. If this option is |
| set to off, you can use `set thread default pause on' or `set |
| thread pause on' (see below) to pause individual threads. |
| |
| `show task pause' |
| Show the current state of task suspension. |
| |
| `set task detach-suspend-count' |
| This command sets the suspend count the task will be left with when |
| GDB detaches from it. |
| |
| `show task detach-suspend-count' |
| Show the suspend count the task will be left with when detaching. |
| |
| `set task exception-port' |
| `set task excp' |
| This command sets the task exception port to which GDB will |
| forward exceptions. The argument should be the value of the "send |
| rights" of the task. `set task excp' is a shorthand alias. |
| |
| `set noninvasive' |
| This command switches GDB to a mode that is the least invasive as |
| far as interfering with the inferior is concerned. This is the |
| same as using `set task pause', `set exceptions', and `set |
| signals' to values opposite to the defaults. |
| |
| `info send-rights' |
| `info receive-rights' |
| `info port-rights' |
| `info port-sets' |
| `info dead-names' |
| `info ports' |
| `info psets' |
| These commands display information about, respectively, send |
| rights, receive rights, port rights, port sets, and dead names of |
| a task. There are also shorthand aliases: `info ports' for `info |
| port-rights' and `info psets' for `info port-sets'. |
| |
| `set thread pause' |
| This command toggles current thread suspension when GDB has |
| control. Setting it to on takes effect immediately, and the |
| current thread is suspended whenever GDB gets control. Setting it |
| to off will take effect the next time the inferior is continued. |
| Normally, this command has no effect, since when GDB has control, |
| the whole task is suspended. However, if you used `set task pause |
| off' (see above), this command comes in handy to suspend only the |
| current thread. |
| |
| `show thread pause' |
| This command shows the state of current thread suspension. |
| |
| `set thread run' |
| This command sets whether the current thread is allowed to run. |
| |
| `show thread run' |
| Show whether the current thread is allowed to run. |
| |
| `set thread detach-suspend-count' |
| This command sets the suspend count GDB will leave on a thread |
| when detaching. This number is relative to the suspend count |
| found by GDB when it notices the thread; use `set thread |
| takeover-suspend-count' to force it to an absolute value. |
| |
| `show thread detach-suspend-count' |
| Show the suspend count GDB will leave on the thread when detaching. |
| |
| `set thread exception-port' |
| `set thread excp' |
| Set the thread exception port to which to forward exceptions. This |
| overrides the port set by `set task exception-port' (see above). |
| `set thread excp' is the shorthand alias. |
| |
| `set thread takeover-suspend-count' |
| Normally, GDB's thread suspend counts are relative to the value |
| GDB finds when it notices each thread. This command changes the |
| suspend counts to be absolute instead. |
| |
| `set thread default' |
| `show thread default' |
| Each of the above `set thread' commands has a `set thread default' |
| counterpart (e.g., `set thread default pause', `set thread default |
| exception-port', etc.). The `thread default' variety of commands |
| sets the default thread properties for all threads; you can then |
| change the properties of individual threads with the non-default |
| commands. |
| |
| |
| File: gdb.info, Node: Neutrino, Next: Darwin, Prev: Hurd Native, Up: Native |
| |
| 21.1.7 QNX Neutrino |
| ------------------- |
| |
| GDB provides the following commands specific to the QNX Neutrino target: |
| |
| `set debug nto-debug' |
| When set to on, enables debugging messages specific to the QNX |
| Neutrino support. |
| |
| `show debug nto-debug' |
| Show the current state of QNX Neutrino messages. |
| |
| |
| File: gdb.info, Node: Darwin, Prev: Neutrino, Up: Native |
| |
| 21.1.8 Darwin |
| ------------- |
| |
| GDB provides the following commands specific to the Darwin target: |
| |
| `set debug darwin NUM' |
| When set to a non zero value, enables debugging messages specific |
| to the Darwin support. Higher values produce more verbose output. |
| |
| `show debug darwin' |
| Show the current state of Darwin messages. |
| |
| `set debug mach-o NUM' |
| When set to a non zero value, enables debugging messages while GDB |
| is reading Darwin object files. ("Mach-O" is the file format used |
| on Darwin for object and executable files.) Higher values produce |
| more verbose output. This is a command to diagnose problems |
| internal to GDB and should not be needed in normal usage. |
| |
| `show debug mach-o' |
| Show the current state of Mach-O file messages. |
| |
| `set mach-exceptions on' |
| `set mach-exceptions off' |
| On Darwin, faults are first reported as a Mach exception and are |
| then mapped to a Posix signal. Use this command to turn on |
| trapping of Mach exceptions in the inferior. This might be |
| sometimes useful to better understand the cause of a fault. The |
| default is off. |
| |
| `show mach-exceptions' |
| Show the current state of exceptions trapping. |
| |
| |
| File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations |
| |
| 21.2 Embedded Operating Systems |
| =============================== |
| |
| This section describes configurations involving the debugging of |
| embedded operating systems that are available for several different |
| architectures. |
| |
| * Menu: |
| |
| * VxWorks:: Using GDB with VxWorks |
| |
| GDB includes the ability to debug programs running on various |
| real-time operating systems. |
| |
| |
| File: gdb.info, Node: VxWorks, Up: Embedded OS |
| |
| 21.2.1 Using GDB with VxWorks |
| ----------------------------- |
| |
| `target vxworks MACHINENAME' |
| A VxWorks system, attached via TCP/IP. The argument MACHINENAME |
| is the target system's machine name or IP address. |
| |
| |
| On VxWorks, `load' links FILENAME dynamically on the current target |
| system as well as adding its symbols in GDB. |
| |
| GDB enables developers to spawn and debug tasks running on networked |
| VxWorks targets from a Unix host. Already-running tasks spawned from |
| the VxWorks shell can also be debugged. GDB uses code that runs on |
| both the Unix host and on the VxWorks target. The program `gdb' is |
| installed and executed on the Unix host. (It may be installed with the |
| name `vxgdb', to distinguish it from a GDB for debugging programs on |
| the host itself.) |
| |
| `VxWorks-timeout ARGS' |
| All VxWorks-based targets now support the option `vxworks-timeout'. |
| This option is set by the user, and ARGS represents the number of |
| seconds GDB waits for responses to rpc's. You might use this if |
| your VxWorks target is a slow software simulator or is on the far |
| side of a thin network line. |
| |
| The following information on connecting to VxWorks was current when |
| this manual was produced; newer releases of VxWorks may use revised |
| procedures. |
| |
| To use GDB with VxWorks, you must rebuild your VxWorks kernel to |
| include the remote debugging interface routines in the VxWorks library |
| `rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration |
| file `configAll.h' and rebuild your VxWorks kernel. The resulting |
| kernel contains `rdb.a', and spawns the source debugging task |
| `tRdbTask' when VxWorks is booted. For more information on configuring |
| and remaking VxWorks, see the manufacturer's manual. |
| |
| Once you have included `rdb.a' in your VxWorks system image and set |
| your Unix execution search path to find GDB, you are ready to run GDB. |
| From your Unix host, run `gdb' (or `vxgdb', depending on your |
| installation). |
| |
| GDB comes up showing the prompt: |
| |
| (vxgdb) |
| |
| * Menu: |
| |
| * VxWorks Connection:: Connecting to VxWorks |
| * VxWorks Download:: VxWorks download |
| * VxWorks Attach:: Running tasks |
| |
| |
| File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks |
| |
| 21.2.1.1 Connecting to VxWorks |
| .............................. |
| |
| The GDB command `target' lets you connect to a VxWorks target on the |
| network. To connect to a target whose host name is "`tt'", type: |
| |
| (vxgdb) target vxworks tt |
| |
| GDB displays messages like these: |
| |
| Attaching remote machine across net... |
| Connected to tt. |
| |
| GDB then attempts to read the symbol tables of any object modules |
| loaded into the VxWorks target since it was last booted. GDB locates |
| these files by searching the directories listed in the command search |
| path (*note Your Program's Environment: Environment.); if it fails to |
| find an object file, it displays a message such as: |
| |
| prog.o: No such file or directory. |
| |
| When this happens, add the appropriate directory to the search path |
| with the GDB command `path', and execute the `target' command again. |
| |
| |
| File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks |
| |
| 21.2.1.2 VxWorks Download |
| ......................... |
| |
| If you have connected to the VxWorks target and you want to debug an |
| object that has not yet been loaded, you can use the GDB `load' command |
| to download a file from Unix to VxWorks incrementally. The object file |
| given as an argument to the `load' command is actually opened twice: |
| first by the VxWorks target in order to download the code, then by GDB |
| in order to read the symbol table. This can lead to problems if the |
| current working directories on the two systems differ. If both systems |
| have NFS mounted the same filesystems, you can avoid these problems by |
| using absolute paths. Otherwise, it is simplest to set the working |
| directory on both systems to the directory in which the object file |
| resides, and then to reference the file by its name, without any path. |
| For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in |
| VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this |
| program, type this on VxWorks: |
| |
| -> cd "VXPATH/vw/demo/rdb" |
| |
| Then, in GDB, type: |
| |
| (vxgdb) cd HOSTPATH/vw/demo/rdb |
| (vxgdb) load prog.o |
| |
| GDB displays a response similar to this: |
| |
| Reading symbol data from wherever/vw/demo/rdb/prog.o... done. |
| |
| You can also use the `load' command to reload an object module after |
| editing and recompiling the corresponding source file. Note that this |
| makes GDB delete all currently-defined breakpoints, auto-displays, and |
| convenience variables, and to clear the value history. (This is |
| necessary in order to preserve the integrity of debugger's data |
| structures that reference the target system's symbol table.) |
| |
| |
| File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks |
| |
| 21.2.1.3 Running Tasks |
| ...................... |
| |
| You can also attach to an existing task using the `attach' command as |
| follows: |
| |
| (vxgdb) attach TASK |
| |
| where TASK is the VxWorks hexadecimal task ID. The task can be running |
| or suspended when you attach to it. Running tasks are suspended at the |
| time of attachment. |
| |
| |
| File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations |
| |
| 21.3 Embedded Processors |
| ======================== |
| |
| This section goes into details specific to particular embedded |
| configurations. |
| |
| Whenever a specific embedded processor has a simulator, GDB allows |
| to send an arbitrary command to the simulator. |
| |
| `sim COMMAND' |
| Send an arbitrary COMMAND string to the simulator. Consult the |
| documentation for the specific simulator in use for information |
| about acceptable commands. |
| |
| * Menu: |
| |
| * ARM:: ARM RDI |
| * M32R/D:: Renesas M32R/D |
| * M68K:: Motorola M68K |
| * MicroBlaze:: Xilinx MicroBlaze |
| * MIPS Embedded:: MIPS Embedded |
| * OpenRISC 1000:: OpenRisc 1000 |
| * PA:: HP PA Embedded |
| * PowerPC Embedded:: PowerPC Embedded |
| * Sparclet:: Tsqware Sparclet |
| * Sparclite:: Fujitsu Sparclite |
| * Z8000:: Zilog Z8000 |
| * AVR:: Atmel AVR |
| * CRIS:: CRIS |
| * Super-H:: Renesas Super-H |
| |
| |
| File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors |
| |
| 21.3.1 ARM |
| ---------- |
| |
| `target rdi DEV' |
| ARM Angel monitor, via RDI library interface to ADP protocol. You |
| may use this target to communicate with both boards running the |
| Angel monitor, or with the EmbeddedICE JTAG debug device. |
| |
| `target rdp DEV' |
| ARM Demon monitor. |
| |
| |
| GDB provides the following ARM-specific commands: |
| |
| `set arm disassembler' |
| This commands selects from a list of disassembly styles. The |
| `"std"' style is the standard style. |
| |
| `show arm disassembler' |
| Show the current disassembly style. |
| |
| `set arm apcs32' |
| This command toggles ARM operation mode between 32-bit and 26-bit. |
| |
| `show arm apcs32' |
| Display the current usage of the ARM 32-bit mode. |
| |
| `set arm fpu FPUTYPE' |
| This command sets the ARM floating-point unit (FPU) type. The |
| argument FPUTYPE can be one of these: |
| |
| `auto' |
| Determine the FPU type by querying the OS ABI. |
| |
| `softfpa' |
| Software FPU, with mixed-endian doubles on little-endian ARM |
| processors. |
| |
| `fpa' |
| GCC-compiled FPA co-processor. |
| |
| `softvfp' |
| Software FPU with pure-endian doubles. |
| |
| `vfp' |
| VFP co-processor. |
| |
| `show arm fpu' |
| Show the current type of the FPU. |
| |
| `set arm abi' |
| This command forces GDB to use the specified ABI. |
| |
| `show arm abi' |
| Show the currently used ABI. |
| |
| `set arm fallback-mode (arm|thumb|auto)' |
| GDB uses the symbol table, when available, to determine whether |
| instructions are ARM or Thumb. This command controls GDB's |
| default behavior when the symbol table is not available. The |
| default is `auto', which causes GDB to use the current execution |
| mode (from the `T' bit in the `CPSR' register). |
| |
| `show arm fallback-mode' |
| Show the current fallback instruction mode. |
| |
| `set arm force-mode (arm|thumb|auto)' |
| This command overrides use of the symbol table to determine whether |
| instructions are ARM or Thumb. The default is `auto', which |
| causes GDB to use the symbol table and then the setting of `set |
| arm fallback-mode'. |
| |
| `show arm force-mode' |
| Show the current forced instruction mode. |
| |
| `set debug arm' |
| Toggle whether to display ARM-specific debugging messages from the |
| ARM target support subsystem. |
| |
| `show debug arm' |
| Show whether ARM-specific debugging messages are enabled. |
| |
| The following commands are available when an ARM target is debugged |
| using the RDI interface: |
| |
| `rdilogfile [FILE]' |
| Set the filename for the ADP (Angel Debugger Protocol) packet log. |
| With an argument, sets the log file to the specified FILE. With |
| no argument, show the current log file name. The default log file |
| is `rdi.log'. |
| |
| `rdilogenable [ARG]' |
| Control logging of ADP packets. With an argument of 1 or `"yes"' |
| enables logging, with an argument 0 or `"no"' disables it. With |
| no arguments displays the current setting. When logging is |
| enabled, ADP packets exchanged between GDB and the RDI target |
| device are logged to a file. |
| |
| `set rdiromatzero' |
| Tell GDB whether the target has ROM at address 0. If on, vector |
| catching is disabled, so that zero address can be used. If off |
| (the default), vector catching is enabled. For this command to |
| take effect, it needs to be invoked prior to the `target rdi' |
| command. |
| |
| `show rdiromatzero' |
| Show the current setting of ROM at zero address. |
| |
| `set rdiheartbeat' |
| Enable or disable RDI heartbeat packets. It is not recommended to |
| turn on this option, since it confuses ARM and EPI JTAG interface, |
| as well as the Angel monitor. |
| |
| `show rdiheartbeat' |
| Show the setting of RDI heartbeat packets. |
| |
| `target sim [SIMARGS] ...' |
| The GDB ARM simulator accepts the following optional arguments. |
| |
| `--swi-support=TYPE' |
| Tell the simulator which SWI interfaces to support. TYPE may |
| be a comma separated list of the following values. The |
| default value is `all'. |
| |
| `none' |
| |
| `demon' |
| |
| `angel' |
| |
| `redboot' |
| |
| `all' |
| |
| |
| File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors |
| |
| 21.3.2 Renesas M32R/D and M32R/SDI |
| ---------------------------------- |
| |
| `target m32r DEV' |
| Renesas M32R/D ROM monitor. |
| |
| `target m32rsdi DEV' |
| Renesas M32R SDI server, connected via parallel port to the board. |
| |
| The following GDB commands are specific to the M32R monitor: |
| |
| `set download-path PATH' |
| Set the default path for finding downloadable SREC files. |
| |
| `show download-path' |
| Show the default path for downloadable SREC files. |
| |
| `set board-address ADDR' |
| Set the IP address for the M32R-EVA target board. |
| |
| `show board-address' |
| Show the current IP address of the target board. |
| |
| `set server-address ADDR' |
| Set the IP address for the download server, which is the GDB's |
| host machine. |
| |
| `show server-address' |
| Display the IP address of the download server. |
| |
| `upload [FILE]' |
| Upload the specified SREC FILE via the monitor's Ethernet upload |
| capability. If no FILE argument is given, the current executable |
| file is uploaded. |
| |
| `tload [FILE]' |
| Test the `upload' command. |
| |
| The following commands are available for M32R/SDI: |
| |
| `sdireset' |
| This command resets the SDI connection. |
| |
| `sdistatus' |
| This command shows the SDI connection status. |
| |
| `debug_chaos' |
| Instructs the remote that M32R/Chaos debugging is to be used. |
| |
| `use_debug_dma' |
| Instructs the remote to use the DEBUG_DMA method of accessing |
| memory. |
| |
| `use_mon_code' |
| Instructs the remote to use the MON_CODE method of accessing |
| memory. |
| |
| `use_ib_break' |
| Instructs the remote to set breakpoints by IB break. |
| |
| `use_dbt_break' |
| Instructs the remote to set breakpoints by DBT. |
| |
| |
| File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors |
| |
| 21.3.3 M68k |
| ----------- |
| |
| The Motorola m68k configuration includes ColdFire support, and a target |
| command for the following ROM monitor. |
| |
| `target dbug DEV' |
| dBUG ROM monitor for Motorola ColdFire. |
| |
| |
| |
| File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors |
| |
| 21.3.4 MicroBlaze |
| ----------------- |
| |
| The MicroBlaze is a soft-core processor supported on various Xilinx |
| FPGAs, such as Spartan or Virtex series. Boards with these processors |
| usually have JTAG ports which connect to a host system running the |
| Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). |
| This host system is used to download the configuration bitstream to the |
| target FPGA. The Xilinx Microprocessor Debugger (XMD) program |
| communicates with the target board using the JTAG interface and |
| presents a `gdbserver' interface to the board. By default `xmd' uses |
| port `1234'. (While it is possible to change this default port, it |
| requires the use of undocumented `xmd' commands. Contact Xilinx |
| support if you need to do this.) |
| |
| Use these GDB commands to connect to the MicroBlaze target processor. |
| |
| `target remote :1234' |
| Use this command to connect to the target if you are running GDB |
| on the same system as `xmd'. |
| |
| `target remote XMD-HOST:1234' |
| Use this command to connect to the target if it is connected to |
| `xmd' running on a different system named XMD-HOST. |
| |
| `load' |
| Use this command to download a program to the MicroBlaze target. |
| |
| `set debug microblaze N' |
| Enable MicroBlaze-specific debugging messages if non-zero. |
| |
| `show debug microblaze N' |
| Show MicroBlaze-specific debugging level. |
| |
| |
| File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors |
| |
| 21.3.5 MIPS Embedded |
| -------------------- |
| |
| GDB can use the MIPS remote debugging protocol to talk to a MIPS board |
| attached to a serial line. This is available when you configure GDB |
| with `--target=mips-idt-ecoff'. |
| |
| Use these GDB commands to specify the connection to your target |
| board: |
| |
| `target mips PORT' |
| To run a program on the board, start up `gdb' with the name of |
| your program as the argument. To connect to the board, use the |
| command `target mips PORT', where PORT is the name of the serial |
| port connected to the board. If the program has not already been |
| downloaded to the board, you may use the `load' command to |
| download it. You can then use all the usual GDB commands. |
| |
| For example, this sequence connects to the target board through a |
| serial port, and loads and runs a program called PROG through the |
| debugger: |
| |
| host$ gdb PROG |
| GDB is free software and ... |
| (gdb) target mips /dev/ttyb |
| (gdb) load PROG |
| (gdb) run |
| |
| `target mips HOSTNAME:PORTNUMBER' |
| On some GDB host configurations, you can specify a TCP connection |
| (for instance, to a serial line managed by a terminal |
| concentrator) instead of a serial port, using the syntax |
| `HOSTNAME:PORTNUMBER'. |
| |
| `target pmon PORT' |
| PMON ROM monitor. |
| |
| `target ddb PORT' |
| NEC's DDB variant of PMON for Vr4300. |
| |
| `target lsi PORT' |
| LSI variant of PMON. |
| |
| `target r3900 DEV' |
| Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. |
| |
| `target array DEV' |
| Array Tech LSI33K RAID controller board. |
| |
| |
| GDB also supports these special commands for MIPS targets: |
| |
| `set mipsfpu double' |
| `set mipsfpu single' |
| `set mipsfpu none' |
| `set mipsfpu auto' |
| `show mipsfpu' |
| If your target board does not support the MIPS floating point |
| coprocessor, you should use the command `set mipsfpu none' (if you |
| need this, you may wish to put the command in your GDB init file). |
| This tells GDB how to find the return value of functions which |
| return floating point values. It also allows GDB to avoid saving |
| the floating point registers when calling functions on the board. |
| If you are using a floating point coprocessor with only single |
| precision floating point support, as on the R4650 processor, use |
| the command `set mipsfpu single'. The default double precision |
| floating point coprocessor may be selected using `set mipsfpu |
| double'. |
| |
| In previous versions the only choices were double precision or no |
| floating point, so `set mipsfpu on' will select double precision |
| and `set mipsfpu off' will select no floating point. |
| |
| As usual, you can inquire about the `mipsfpu' variable with `show |
| mipsfpu'. |
| |
| `set timeout SECONDS' |
| `set retransmit-timeout SECONDS' |
| `show timeout' |
| `show retransmit-timeout' |
| You can control the timeout used while waiting for a packet, in |
| the MIPS remote protocol, with the `set timeout SECONDS' command. |
| The default is 5 seconds. Similarly, you can control the timeout |
| used while waiting for an acknowledgment of a packet with the `set |
| retransmit-timeout SECONDS' command. The default is 3 seconds. |
| You can inspect both values with `show timeout' and `show |
| retransmit-timeout'. (These commands are _only_ available when |
| GDB is configured for `--target=mips-idt-ecoff'.) |
| |
| The timeout set by `set timeout' does not apply when GDB is |
| waiting for your program to stop. In that case, GDB waits forever |
| because it has no way of knowing how long the program is going to |
| run before stopping. |
| |
| `set syn-garbage-limit NUM' |
| Limit the maximum number of characters GDB should ignore when it |
| tries to synchronize with the remote target. The default is 10 |
| characters. Setting the limit to -1 means there's no limit. |
| |
| `show syn-garbage-limit' |
| Show the current limit on the number of characters to ignore when |
| trying to synchronize with the remote system. |
| |
| `set monitor-prompt PROMPT' |
| Tell GDB to expect the specified PROMPT string from the remote |
| monitor. The default depends on the target: |
| pmon target |
| `PMON' |
| |
| ddb target |
| `NEC010' |
| |
| lsi target |
| `PMON>' |
| |
| `show monitor-prompt' |
| Show the current strings GDB expects as the prompt from the remote |
| monitor. |
| |
| `set monitor-warnings' |
| Enable or disable monitor warnings about hardware breakpoints. |
| This has effect only for the `lsi' target. When on, GDB will |
| display warning messages whose codes are returned by the `lsi' |
| PMON monitor for breakpoint commands. |
| |
| `show monitor-warnings' |
| Show the current setting of printing monitor warnings. |
| |
| `pmon COMMAND' |
| This command allows sending an arbitrary COMMAND string to the |
| monitor. The monitor must be in debug mode for this to work. |
| |
| |
| File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors |
| |
| 21.3.6 OpenRISC 1000 |
| -------------------- |
| |
| See OR1k Architecture document (`www.opencores.org') for more |
| information about platform and commands. |
| |
| `target jtag jtag://HOST:PORT' |
| Connects to remote JTAG server. JTAG remote server can be either |
| an or1ksim or JTAG server, connected via parallel port to the |
| board. |
| |
| Example: `target jtag jtag://localhost:9999' |
| |
| `or1ksim COMMAND' |
| If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, |
| proprietary commands can be executed. |
| |
| `info or1k spr' |
| Displays spr groups. |
| |
| `info or1k spr GROUP' |
| `info or1k spr GROUPNO' |
| Displays register names in selected group. |
| |
| `info or1k spr GROUP REGISTER' |
| `info or1k spr REGISTER' |
| `info or1k spr GROUPNO REGISTERNO' |
| `info or1k spr REGISTERNO' |
| Shows information about specified spr register. |
| |
| `spr GROUP REGISTER VALUE' |
| `spr REGISTER VALUE' |
| `spr GROUPNO REGISTERNO VALUE' |
| `spr REGISTERNO VALUE' |
| Writes VALUE to specified spr register. |
| |
| Some implementations of OpenRISC 1000 Architecture also have |
| hardware trace. It is very similar to GDB trace, except it does not |
| interfere with normal program execution and is thus much faster. |
| Hardware breakpoints/watchpoint triggers can be set using: |
| `$LEA/$LDATA' |
| Load effective address/data |
| |
| `$SEA/$SDATA' |
| Store effective address/data |
| |
| `$AEA/$ADATA' |
| Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) |
| |
| `$FETCH' |
| Fetch data |
| |
| When triggered, it can capture low level data, like: `PC', `LSEA', |
| `LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. |
| |
| `htrace' commands: |
| `hwatch CONDITIONAL' |
| Set hardware watchpoint on combination of Load/Store Effective |
| Address(es) or Data. For example: |
| |
| `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && |
| ($SDATA >= 50)' |
| |
| `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && |
| ($SDATA >= 50)' |
| |
| `htrace info' |
| Display information about current HW trace configuration. |
| |
| `htrace trigger CONDITIONAL' |
| Set starting criteria for HW trace. |
| |
| `htrace qualifier CONDITIONAL' |
| Set acquisition qualifier for HW trace. |
| |
| `htrace stop CONDITIONAL' |
| Set HW trace stopping criteria. |
| |
| `htrace record [DATA]*' |
| Selects the data to be recorded, when qualifier is met and HW |
| trace was triggered. |
| |
| `htrace enable' |
| `htrace disable' |
| Enables/disables the HW trace. |
| |
| `htrace rewind [FILENAME]' |
| Clears currently recorded trace data. |
| |
| If filename is specified, new trace file is made and any newly |
| collected data will be written there. |
| |
| `htrace print [START [LEN]]' |
| Prints trace buffer, using current record configuration. |
| |
| `htrace mode continuous' |
| Set continuous trace mode. |
| |
| `htrace mode suspend' |
| Set suspend trace mode. |
| |
| |
| |
| File: gdb.info, Node: PowerPC Embedded, Next: Sparclet, Prev: PA, Up: Embedded Processors |
| |
| 21.3.7 PowerPC Embedded |
| ----------------------- |
| |
| GDB supports using the DVC (Data Value Compare) register to implement |
| in hardware simple hardware watchpoint conditions of the form: |
| |
| (gdb) watch ADDRESS|VARIABLE \ |
| if ADDRESS|VARIABLE == CONSTANT EXPRESSION |
| |
| The DVC register will be automatically used whenever GDB detects |
| such pattern in a condition expression. This feature is available in |
| native GDB running on a Linux kernel version 2.6.34 or newer. |
| |
| GDB provides the following PowerPC-specific commands: |
| |
| `set powerpc soft-float' |
| `show powerpc soft-float' |
| Force GDB to use (or not use) a software floating point calling |
| convention. By default, GDB selects the calling convention based |
| on the selected architecture and the provided executable file. |
| |
| `set powerpc vector-abi' |
| `show powerpc vector-abi' |
| Force GDB to use the specified calling convention for vector |
| arguments and return values. The valid options are `auto'; |
| `generic', to avoid vector registers even if they are present; |
| `altivec', to use AltiVec registers; and `spe' to use SPE |
| registers. By default, GDB selects the calling convention based |
| on the selected architecture and the provided executable file. |
| |
| `target dink32 DEV' |
| DINK32 ROM monitor. |
| |
| `target ppcbug DEV' |
| |
| `target ppcbug1 DEV' |
| PPCBUG ROM monitor for PowerPC. |
| |
| `target sds DEV' |
| SDS monitor, running on a PowerPC board (such as Motorola's ADS). |
| |
| The following commands specific to the SDS protocol are supported by |
| GDB: |
| |
| `set sdstimeout NSEC' |
| Set the timeout for SDS protocol reads to be NSEC seconds. The |
| default is 2 seconds. |
| |
| `show sdstimeout' |
| Show the current value of the SDS timeout. |
| |
| `sds COMMAND' |
| Send the specified COMMAND string to the SDS monitor. |
| |
| |
| File: gdb.info, Node: PA, Next: PowerPC Embedded, Prev: OpenRISC 1000, Up: Embedded Processors |
| |
| 21.3.8 HP PA Embedded |
| --------------------- |
| |
| `target op50n DEV' |
| OP50N monitor, running on an OKI HPPA board. |
| |
| `target w89k DEV' |
| W89K monitor, running on a Winbond HPPA board. |
| |
| |
| |
| File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC Embedded, Up: Embedded Processors |
| |
| 21.3.9 Tsqware Sparclet |
| ----------------------- |
| |
| GDB enables developers to debug tasks running on Sparclet targets from |
| a Unix host. GDB uses code that runs on both the Unix host and on the |
| Sparclet target. The program `gdb' is installed and executed on the |
| Unix host. |
| |
| `remotetimeout ARGS' |
| GDB supports the option `remotetimeout'. This option is set by |
| the user, and ARGS represents the number of seconds GDB waits for |
| responses. |
| |
| When compiling for debugging, include the options `-g' to get debug |
| information and `-Ttext' to relocate the program to where you wish to |
| load it on the target. You may also want to add the options `-n' or |
| `-N' in order to reduce the size of the sections. Example: |
| |
| sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N |
| |
| You can use `objdump' to verify that the addresses are what you |
| intended: |
| |
| sparclet-aout-objdump --headers --syms prog |
| |
| Once you have set your Unix execution search path to find GDB, you |
| are ready to run GDB. From your Unix host, run `gdb' (or |
| `sparclet-aout-gdb', depending on your installation). |
| |
| GDB comes up showing the prompt: |
| |
| (gdbslet) |
| |
| * Menu: |
| |
| * Sparclet File:: Setting the file to debug |
| * Sparclet Connection:: Connecting to Sparclet |
| * Sparclet Download:: Sparclet download |
| * Sparclet Execution:: Running and debugging |
| |
| |
| File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet |
| |
| 21.3.9.1 Setting File to Debug |
| .............................. |
| |
| The GDB command `file' lets you choose with program to debug. |
| |
| (gdbslet) file prog |
| |
| GDB then attempts to read the symbol table of `prog'. GDB locates |
| the file by searching the directories listed in the command search path. |
| If the file was compiled with debug information (option `-g'), source |
| files will be searched as well. GDB locates the source files by |
| searching the directories listed in the directory search path (*note |
| Your Program's Environment: Environment.). If it fails to find a file, |
| it displays a message such as: |
| |
| prog: No such file or directory. |
| |
| When this happens, add the appropriate directories to the search |
| paths with the GDB commands `path' and `dir', and execute the `target' |
| command again. |
| |
| |
| File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet |
| |
| 21.3.9.2 Connecting to Sparclet |
| ............................... |
| |
| The GDB command `target' lets you connect to a Sparclet target. To |
| connect to a target on serial port "`ttya'", type: |
| |
| (gdbslet) target sparclet /dev/ttya |
| Remote target sparclet connected to /dev/ttya |
| main () at ../prog.c:3 |
| |
| GDB displays messages like these: |
| |
| Connected to ttya. |
| |
| |
| File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet |
| |
| 21.3.9.3 Sparclet Download |
| .......................... |
| |
| Once connected to the Sparclet target, you can use the GDB `load' |
| command to download the file from the host to the target. The file |
| name and load offset should be given as arguments to the `load' command. |
| Since the file format is aout, the program must be loaded to the |
| starting address. You can use `objdump' to find out what this value |
| is. The load offset is an offset which is added to the VMA (virtual |
| memory address) of each of the file's sections. For instance, if the |
| program `prog' was linked to text address 0x1201000, with data at |
| 0x12010160 and bss at 0x12010170, in GDB, type: |
| |
| (gdbslet) load prog 0x12010000 |
| Loading section .text, size 0xdb0 vma 0x12010000 |
| |
| If the code is loaded at a different address then what the program |
| was linked to, you may need to use the `section' and `add-symbol-file' |
| commands to tell GDB where to map the symbol table. |
| |
| |
| File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet |
| |
| 21.3.9.4 Running and Debugging |
| .............................. |
| |
| You can now begin debugging the task using GDB's execution control |
| commands, `b', `step', `run', etc. See the GDB manual for the list of |
| commands. |
| |
| (gdbslet) b main |
| Breakpoint 1 at 0x12010000: file prog.c, line 3. |
| (gdbslet) run |
| Starting program: prog |
| Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 |
| 3 char *symarg = 0; |
| (gdbslet) step |
| 4 char *execarg = "hello!"; |
| (gdbslet) |
| |
| |
| File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors |
| |
| 21.3.10 Fujitsu Sparclite |
| ------------------------- |
| |
| `target sparclite DEV' |
| Fujitsu sparclite boards, used only for the purpose of loading. |
| You must use an additional command to debug the program. For |
| example: target remote DEV using GDB standard remote protocol. |
| |
| |
| |
| File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors |
| |
| 21.3.11 Zilog Z8000 |
| ------------------- |
| |
| When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 |
| simulator. |
| |
| For the Z8000 family, `target sim' simulates either the Z8002 (the |
| unsegmented variant of the Z8000 architecture) or the Z8001 (the |
| segmented variant). The simulator recognizes which architecture is |
| appropriate by inspecting the object code. |
| |
| `target sim ARGS' |
| Debug programs on a simulated CPU. If the simulator supports setup |
| options, specify them via ARGS. |
| |
| After specifying this target, you can debug programs for the simulated |
| CPU in the same style as programs for your host computer; use the |
| `file' command to load a new program image, the `run' command to run |
| your program, and so on. |
| |
| As well as making available all the usual machine registers (*note |
| Registers: Registers.), the Z8000 simulator provides three additional |
| items of information as specially named registers: |
| |
| `cycles' |
| Counts clock-ticks in the simulator. |
| |
| `insts' |
| Counts instructions run in the simulator. |
| |
| `time' |
| Execution time in 60ths of a second. |
| |
| |
| You can refer to these values in GDB expressions with the usual |
| conventions; for example, `b fputc if $cycles>5000' sets a conditional |
| breakpoint that suspends only after at least 5000 simulated clock ticks. |
| |
| |
| File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors |
| |
| 21.3.12 Atmel AVR |
| ----------------- |
| |
| When configured for debugging the Atmel AVR, GDB supports the following |
| AVR-specific commands: |
| |
| `info io_registers' |
| This command displays information about the AVR I/O registers. For |
| each register, GDB prints its number and value. |
| |
| |
| File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors |
| |
| 21.3.13 CRIS |
| ------------ |
| |
| When configured for debugging CRIS, GDB provides the following |
| CRIS-specific commands: |
| |
| `set cris-version VER' |
| Set the current CRIS version to VER, either `10' or `32'. The |
| CRIS version affects register names and sizes. This command is |
| useful in case autodetection of the CRIS version fails. |
| |
| `show cris-version' |
| Show the current CRIS version. |
| |
| `set cris-dwarf2-cfi' |
| Set the usage of DWARF-2 CFI for CRIS debugging. The default is |
| `on'. Change to `off' when using `gcc-cris' whose version is below |
| `R59'. |
| |
| `show cris-dwarf2-cfi' |
| Show the current state of using DWARF-2 CFI. |
| |
| `set cris-mode MODE' |
| Set the current CRIS mode to MODE. It should only be changed when |
| debugging in guru mode, in which case it should be set to `guru' |
| (the default is `normal'). |
| |
| `show cris-mode' |
| Show the current CRIS mode. |
| |
| |
| File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors |
| |
| 21.3.14 Renesas Super-H |
| ----------------------- |
| |
| For the Renesas Super-H processor, GDB provides these commands: |
| |
| `regs' |
| Show the values of all Super-H registers. |
| |
| `set sh calling-convention CONVENTION' |
| Set the calling-convention used when calling functions from GDB. |
| Allowed values are `gcc', which is the default setting, and |
| `renesas'. With the `gcc' setting, functions are called using the |
| GCC calling convention. If the DWARF-2 information of the called |
| function specifies that the function follows the Renesas calling |
| convention, the function is called using the Renesas calling |
| convention. If the calling convention is set to `renesas', the |
| Renesas calling convention is always used, regardless of the |
| DWARF-2 information. This can be used to override the default of |
| `gcc' if debug information is missing, or the compiler does not |
| emit the DWARF-2 calling convention entry for a function. |
| |
| `show sh calling-convention' |
| Show the current calling convention setting. |
| |
| |
| |
| File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations |
| |
| 21.4 Architectures |
| ================== |
| |
| This section describes characteristics of architectures that affect all |
| uses of GDB with the architecture, both native and cross. |
| |
| * Menu: |
| |
| * i386:: |
| * A29K:: |
| * Alpha:: |
| * MIPS:: |
| * HPPA:: HP PA architecture |
| * SPU:: Cell Broadband Engine SPU architecture |
| * PowerPC:: |
| |
| |
| File: gdb.info, Node: i386, Next: A29K, Up: Architectures |
| |
| 21.4.1 x86 Architecture-specific Issues |
| --------------------------------------- |
| |
| `set struct-convention MODE' |
| Set the convention used by the inferior to return `struct's and |
| `union's from functions to MODE. Possible values of MODE are |
| `"pcc"', `"reg"', and `"default"' (the default). `"default"' or |
| `"pcc"' means that `struct's are returned on the stack, while |
| `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, |
| or 8 bytes will be returned in a register. |
| |
| `show struct-convention' |
| Show the current setting of the convention to return `struct's |
| from functions. |
| |
| |
| File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures |
| |
| 21.4.2 A29K |
| ----------- |
| |
| `set rstack_high_address ADDRESS' |
| On AMD 29000 family processors, registers are saved in a separate |
| "register stack". There is no way for GDB to determine the extent |
| of this stack. Normally, GDB just assumes that the stack is |
| "large enough". This may result in GDB referencing memory |
| locations that do not exist. If necessary, you can get around |
| this problem by specifying the ending address of the register |
| stack with the `set rstack_high_address' command. The argument |
| should be an address, which you probably want to precede with `0x' |
| to specify in hexadecimal. |
| |
| `show rstack_high_address' |
| Display the current limit of the register stack, on AMD 29000 |
| family processors. |
| |
| |
| |
| File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures |
| |
| 21.4.3 Alpha |
| ------------ |
| |
| See the following section. |
| |
| |
| File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures |
| |
| 21.4.4 MIPS |
| ----------- |
| |
| Alpha- and MIPS-based computers use an unusual stack frame, which |
| sometimes requires GDB to search backward in the object code to find |
| the beginning of a function. |
| |
| To improve response time (especially for embedded applications, where |
| GDB may be restricted to a slow serial line for this search) you may |
| want to limit the size of this search, using one of these commands: |
| |
| `set heuristic-fence-post LIMIT' |
| Restrict GDB to examining at most LIMIT bytes in its search for |
| the beginning of a function. A value of 0 (the default) means |
| there is no limit. However, except for 0, the larger the limit |
| the more bytes `heuristic-fence-post' must search and therefore |
| the longer it takes to run. You should only need to use this |
| command when debugging a stripped executable. |
| |
| `show heuristic-fence-post' |
| Display the current limit. |
| |
| These commands are available _only_ when GDB is configured for |
| debugging programs on Alpha or MIPS processors. |
| |
| Several MIPS-specific commands are available when debugging MIPS |
| programs: |
| |
| `set mips abi ARG' |
| Tell GDB which MIPS ABI is used by the inferior. Possible values |
| of ARG are: |
| |
| `auto' |
| The default ABI associated with the current binary (this is |
| the default). |
| |
| `o32' |
| |
| `o64' |
| |
| `n32' |
| |
| `n64' |
| |
| `eabi32' |
| |
| `eabi64' |
| |
| `auto' |
| |
| `show mips abi' |
| Show the MIPS ABI used by GDB to debug the inferior. |
| |
| `set mipsfpu' |
| `show mipsfpu' |
| *Note set mipsfpu: MIPS Embedded. |
| |
| `set mips mask-address ARG' |
| This command determines whether the most-significant 32 bits of |
| 64-bit MIPS addresses are masked off. The argument ARG can be |
| `on', `off', or `auto'. The latter is the default setting, which |
| lets GDB determine the correct value. |
| |
| `show mips mask-address' |
| Show whether the upper 32 bits of MIPS addresses are masked off or |
| not. |
| |
| `set remote-mips64-transfers-32bit-regs' |
| This command controls compatibility with 64-bit MIPS targets that |
| transfer data in 32-bit quantities. If you have an old MIPS 64 |
| target that transfers 32 bits for some registers, like SR and FSR, |
| and 64 bits for other registers, set this option to `on'. |
| |
| `show remote-mips64-transfers-32bit-regs' |
| Show the current setting of compatibility with older MIPS 64 |
| targets. |
| |
| `set debug mips' |
| This command turns on and off debugging messages for the |
| MIPS-specific target code in GDB. |
| |
| `show debug mips' |
| Show the current setting of MIPS debugging messages. |
| |
| |
| File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures |
| |
| 21.4.5 HPPA |
| ----------- |
| |
| When GDB is debugging the HP PA architecture, it provides the following |
| special commands: |
| |
| `set debug hppa' |
| This command determines whether HPPA architecture-specific |
| debugging messages are to be displayed. |
| |
| `show debug hppa' |
| Show whether HPPA debugging messages are displayed. |
| |
| `maint print unwind ADDRESS' |
| This command displays the contents of the unwind table entry at the |
| given ADDRESS. |
| |
| |
| |
| File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures |
| |
| 21.4.6 Cell Broadband Engine SPU architecture |
| --------------------------------------------- |
| |
| When GDB is debugging the Cell Broadband Engine SPU architecture, it |
| provides the following special commands: |
| |
| `info spu event' |
| Display SPU event facility status. Shows current event mask and |
| pending event status. |
| |
| `info spu signal' |
| Display SPU signal notification facility status. Shows pending |
| signal-control word and signal notification mode of both signal |
| notification channels. |
| |
| `info spu mailbox' |
| Display SPU mailbox facility status. Shows all pending entries, |
| in order of processing, in each of the SPU Write Outbound, SPU |
| Write Outbound Interrupt, and SPU Read Inbound mailboxes. |
| |
| `info spu dma' |
| Display MFC DMA status. Shows all pending commands in the MFC DMA |
| queue. For each entry, opcode, tag, class IDs, effective and |
| local store addresses and transfer size are shown. |
| |
| `info spu proxydma' |
| Display MFC Proxy-DMA status. Shows all pending commands in the |
| MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, |
| effective and local store addresses and transfer size are shown. |
| |
| |
| When GDB is debugging a combined PowerPC/SPU application on the Cell |
| Broadband Engine, it provides in addition the following special |
| commands: |
| |
| `set spu stop-on-load ARG' |
| Set whether to stop for new SPE threads. When set to `on', GDB |
| will give control to the user when a new SPE thread enters its |
| `main' function. The default is `off'. |
| |
| `show spu stop-on-load' |
| Show whether to stop for new SPE threads. |
| |
| `set spu auto-flush-cache ARG' |
| Set whether to automatically flush the software-managed cache. |
| When set to `on', GDB will automatically cause the SPE |
| software-managed cache to be flushed whenever SPE execution stops. |
| This provides a consistent view of PowerPC memory that is |
| accessed via the cache. If an application does not use the |
| software-managed cache, this option has no effect. |
| |
| `show spu auto-flush-cache' |
| Show whether to automatically flush the software-managed cache. |
| |
| |
| |
| File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures |
| |
| 21.4.7 PowerPC |
| -------------- |
| |
| When GDB is debugging the PowerPC architecture, it provides a set of |
| pseudo-registers to enable inspection of 128-bit wide Decimal Floating |
| Point numbers stored in the floating point registers. These values must |
| be stored in two consecutive registers, always starting at an even |
| register like `f0' or `f2'. |
| |
| The pseudo-registers go from `$dl0' through `$dl15', and are formed |
| by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2' |
| and `f3' for `$dl1' and so on. |
| |
| For POWER7 processors, GDB provides a set of pseudo-registers, the |
| 64-bit wide Extended Floating Point Registers (`f32' through `f63'). |
| |
| |
| File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top |
| |
| 22 Controlling GDB |
| ****************** |
| |
| You can alter the way GDB interacts with you by using the `set' |
| command. For commands controlling how GDB displays data, see *Note |
| Print Settings: Print Settings. Other settings are described here. |
| |
| * Menu: |
| |
| * Prompt:: Prompt |
| * Editing:: Command editing |
| * Command History:: Command history |
| * Screen Size:: Screen size |
| * Numbers:: Numbers |
| * ABI:: Configuring the current ABI |
| * Messages/Warnings:: Optional warnings and messages |
| * Debugging Output:: Optional messages about internal happenings |
| * Other Misc Settings:: Other Miscellaneous Settings |
| |
| |
| File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB |
| |
| 22.1 Prompt |
| =========== |
| |
| GDB indicates its readiness to read a command by printing a string |
| called the "prompt". This string is normally `(gdb)'. You can change |
| the prompt string with the `set prompt' command. For instance, when |
| debugging GDB with GDB, it is useful to change the prompt in one of the |
| GDB sessions so that you can always tell which one you are talking to. |
| |
| _Note:_ `set prompt' does not add a space for you after the prompt |
| you set. This allows you to set a prompt which ends in a space or a |
| prompt that does not. |
| |
| `set prompt NEWPROMPT' |
| Directs GDB to use NEWPROMPT as its prompt string henceforth. |
| |
| `show prompt' |
| Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' |
| |
| |
| File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB |
| |
| 22.2 Command Editing |
| ==================== |
| |
| GDB reads its input commands via the "Readline" interface. This GNU |
| library provides consistent behavior for programs which provide a |
| command line interface to the user. Advantages are GNU Emacs-style or |
| "vi"-style inline editing of commands, `csh'-like history substitution, |
| and a storage and recall of command history across debugging sessions. |
| |
| You may control the behavior of command line editing in GDB with the |
| command `set'. |
| |
| `set editing' |
| `set editing on' |
| Enable command line editing (enabled by default). |
| |
| `set editing off' |
| Disable command line editing. |
| |
| `show editing' |
| Show whether command line editing is enabled. |
| |
| *Note Command Line Editing::, for more details about the Readline |
| interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to |
| read that chapter. |
| |
| |
| File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB |
| |
| 22.3 Command History |
| ==================== |
| |
| GDB can keep track of the commands you type during your debugging |
| sessions, so that you can be certain of precisely what happened. Use |
| these commands to manage the GDB command history facility. |
| |
| GDB uses the GNU History library, a part of the Readline package, to |
| provide the history facility. *Note Using History Interactively::, for |
| the detailed description of the History library. |
| |
| To issue a command to GDB without affecting certain aspects of the |
| state which is seen by users, prefix it with `server ' (*note Server |
| Prefix::). This means that this command will not affect the command |
| history, nor will it affect GDB's notion of which command to repeat if |
| <RET> is pressed on a line by itself. |
| |
| The server prefix does not affect the recording of values into the |
| value history; to print a value without recording it into the value |
| history, use the `output' command instead of the `print' command. |
| |
| Here is the description of GDB commands related to command history. |
| |
| `set history filename FNAME' |
| Set the name of the GDB command history file to FNAME. This is |
| the file where GDB reads an initial command history list, and |
| where it writes the command history from this session when it |
| exits. You can access this list through history expansion or |
| through the history command editing characters listed below. This |
| file defaults to the value of the environment variable |
| `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) |
| if this variable is not set. |
| |
| `set history save' |
| `set history save on' |
| Record command history in a file, whose name may be specified with |
| the `set history filename' command. By default, this option is |
| disabled. |
| |
| `set history save off' |
| Stop recording command history in a file. |
| |
| `set history size SIZE' |
| Set the number of commands which GDB keeps in its history list. |
| This defaults to the value of the environment variable `HISTSIZE', |
| or to 256 if this variable is not set. |
| |
| History expansion assigns special meaning to the character `!'. |
| *Note Event Designators::, for more details. |
| |
| Since `!' is also the logical not operator in C, history expansion |
| is off by default. If you decide to enable history expansion with the |
| `set history expansion on' command, you may sometimes need to follow |
| `!' (when it is used as logical not, in an expression) with a space or |
| a tab to prevent it from being expanded. The readline history |
| facilities do not attempt substitution on the strings `!=' and `!(', |
| even when history expansion is enabled. |
| |
| The commands to control history expansion are: |
| |
| `set history expansion on' |
| `set history expansion' |
| Enable history expansion. History expansion is off by default. |
| |
| `set history expansion off' |
| Disable history expansion. |
| |
| `show history' |
| `show history filename' |
| `show history save' |
| `show history size' |
| `show history expansion' |
| These commands display the state of the GDB history parameters. |
| `show history' by itself displays all four states. |
| |
| `show commands' |
| Display the last ten commands in the command history. |
| |
| `show commands N' |
| Print ten commands centered on command number N. |
| |
| `show commands +' |
| Print ten commands just after the commands last printed. |
| |
| |
| File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB |
| |
| 22.4 Screen Size |
| ================ |
| |
| Certain commands to GDB may produce large amounts of information output |
| to the screen. To help you read all of it, GDB pauses and asks you for |
| input at the end of each page of output. Type <RET> when you want to |
| continue the output, or `q' to discard the remaining output. Also, the |
| screen width setting determines when to wrap lines of output. |
| Depending on what is being printed, GDB tries to break the line at a |
| readable place, rather than simply letting it overflow onto the |
| following line. |
| |
| Normally GDB knows the size of the screen from the terminal driver |
| software. For example, on Unix GDB uses the termcap data base together |
| with the value of the `TERM' environment variable and the `stty rows' |
| and `stty cols' settings. If this is not correct, you can override it |
| with the `set height' and `set width' commands: |
| |
| `set height LPP' |
| `show height' |
| `set width CPL' |
| `show width' |
| These `set' commands specify a screen height of LPP lines and a |
| screen width of CPL characters. The associated `show' commands |
| display the current settings. |
| |
| If you specify a height of zero lines, GDB does not pause during |
| output no matter how long the output is. This is useful if output |
| is to a file or to an editor buffer. |
| |
| Likewise, you can specify `set width 0' to prevent GDB from |
| wrapping its output. |
| |
| `set pagination on' |
| `set pagination off' |
| Turn the output pagination on or off; the default is on. Turning |
| pagination off is the alternative to `set height 0'. Note that |
| running GDB with the `--batch' option (*note -batch: Mode |
| Options.) also automatically disables pagination. |
| |
| `show pagination' |
| Show the current pagination mode. |
| |
| |
| File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB |
| |
| 22.5 Numbers |
| ============ |
| |
| You can always enter numbers in octal, decimal, or hexadecimal in GDB |
| by the usual conventions: octal numbers begin with `0', decimal numbers |
| end with `.', and hexadecimal numbers begin with `0x'. Numbers that |
| neither begin with `0' or `0x', nor end with a `.' are, by default, |
| entered in base 10; likewise, the default display for numbers--when no |
| particular format is specified--is base 10. You can change the default |
| base for both input and output with the commands described below. |
| |
| `set input-radix BASE' |
| Set the default base for numeric input. Supported choices for |
| BASE are decimal 8, 10, or 16. BASE must itself be specified |
| either unambiguously or using the current input radix; for |
| example, any of |
| |
| set input-radix 012 |
| set input-radix 10. |
| set input-radix 0xa |
| |
| sets the input base to decimal. On the other hand, `set |
| input-radix 10' leaves the input radix unchanged, no matter what |
| it was, since `10', being without any leading or trailing signs of |
| its base, is interpreted in the current radix. Thus, if the |
| current radix is 16, `10' is interpreted in hex, i.e. as 16 |
| decimal, which doesn't change the radix. |
| |
| `set output-radix BASE' |
| Set the default base for numeric display. Supported choices for |
| BASE are decimal 8, 10, or 16. BASE must itself be specified |
| either unambiguously or using the current input radix. |
| |
| `show input-radix' |
| Display the current default base for numeric input. |
| |
| `show output-radix' |
| Display the current default base for numeric display. |
| |
| `set radix [BASE]' |
| `show radix' |
| These commands set and show the default base for both input and |
| output of numbers. `set radix' sets the radix of input and output |
| to the same base; without an argument, it resets the radix back to |
| its default value of 10. |
| |
| |
| |
| File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB |
| |
| 22.6 Configuring the Current ABI |
| ================================ |
| |
| GDB can determine the "ABI" (Application Binary Interface) of your |
| application automatically. However, sometimes you need to override its |
| conclusions. Use these commands to manage GDB's view of the current |
| ABI. |
| |
| One GDB configuration can debug binaries for multiple operating |
| system targets, either via remote debugging or native emulation. GDB |
| will autodetect the "OS ABI" (Operating System ABI) in use, but you can |
| override its conclusion using the `set osabi' command. One example |
| where this is useful is in debugging of binaries which use an alternate |
| C library (e.g. UCLIBC for GNU/Linux) which does not have the same |
| identifying marks that the standard C library for your platform |
| provides. |
| |
| `show osabi' |
| Show the OS ABI currently in use. |
| |
| `set osabi' |
| With no argument, show the list of registered available OS ABI's. |
| |
| `set osabi ABI' |
| Set the current OS ABI to ABI. |
| |
| Generally, the way that an argument of type `float' is passed to a |
| function depends on whether the function is prototyped. For a |
| prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed |
| unchanged, according to the architecture's convention for `float'. For |
| unprototyped (i.e. K&R style) functions, `float' arguments are first |
| promoted to type `double' and then passed. |
| |
| Unfortunately, some forms of debug information do not reliably |
| indicate whether a function is prototyped. If GDB calls a function |
| that is not marked as prototyped, it consults `set |
| coerce-float-to-double'. |
| |
| `set coerce-float-to-double' |
| `set coerce-float-to-double on' |
| Arguments of type `float' will be promoted to `double' when passed |
| to an unprototyped function. This is the default setting. |
| |
| `set coerce-float-to-double off' |
| Arguments of type `float' will be passed directly to unprototyped |
| functions. |
| |
| `show coerce-float-to-double' |
| Show the current setting of promoting `float' to `double'. |
| |
| GDB needs to know the ABI used for your program's C++ objects. The |
| correct C++ ABI depends on which C++ compiler was used to build your |
| application. GDB only fully supports programs with a single C++ ABI; |
| if your program contains code using multiple C++ ABI's or if GDB can |
| not identify your program's ABI correctly, you can tell GDB which ABI |
| to use. Currently supported ABI's include "gnu-v2", for `g++' versions |
| before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for |
| the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or |
| "gnu-v3" ABI's as well. The default setting is "auto". |
| |
| `show cp-abi' |
| Show the C++ ABI currently in use. |
| |
| `set cp-abi' |
| With no argument, show the list of supported C++ ABI's. |
| |
| `set cp-abi ABI' |
| `set cp-abi auto' |
| Set the current C++ ABI to ABI, or return to automatic detection. |
| |
| |
| File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB |
| |
| 22.7 Optional Warnings and Messages |
| =================================== |
| |
| By default, GDB is silent about its inner workings. If you are running |
| on a slow machine, you may want to use the `set verbose' command. This |
| makes GDB tell you when it does a lengthy internal operation, so you |
| will not think it has crashed. |
| |
| Currently, the messages controlled by `set verbose' are those which |
| announce that the symbol table for a source file is being read; see |
| `symbol-file' in *Note Commands to Specify Files: Files. |
| |
| `set verbose on' |
| Enables GDB output of certain informational messages. |
| |
| `set verbose off' |
| Disables GDB output of certain informational messages. |
| |
| `show verbose' |
| Displays whether `set verbose' is on or off. |
| |
| By default, if GDB encounters bugs in the symbol table of an object |
| file, it is silent; but if you are debugging a compiler, you may find |
| this information useful (*note Errors Reading Symbol Files: Symbol |
| Errors.). |
| |
| `set complaints LIMIT' |
| Permits GDB to output LIMIT complaints about each type of unusual |
| symbols before becoming silent about the problem. Set LIMIT to |
| zero to suppress all complaints; set it to a large number to |
| prevent complaints from being suppressed. |
| |
| `show complaints' |
| Displays how many symbol complaints GDB is permitted to produce. |
| |
| |
| By default, GDB is cautious, and asks what sometimes seems to be a |
| lot of stupid questions to confirm certain commands. For example, if |
| you try to run a program which is already running: |
| |
| (gdb) run |
| The program being debugged has been started already. |
| Start it from the beginning? (y or n) |
| |
| If you are willing to unflinchingly face the consequences of your own |
| commands, you can disable this "feature": |
| |
| `set confirm off' |
| Disables confirmation requests. Note that running GDB with the |
| `--batch' option (*note -batch: Mode Options.) also automatically |
| disables confirmation requests. |
| |
| `set confirm on' |
| Enables confirmation requests (the default). |
| |
| `show confirm' |
| Displays state of confirmation requests. |
| |
| |
| If you need to debug user-defined commands or sourced files you may |
| find it useful to enable "command tracing". In this mode each command |
| will be printed as it is executed, prefixed with one or more `+' |
| symbols, the quantity denoting the call depth of each command. |
| |
| `set trace-commands on' |
| Enable command tracing. |
| |
| `set trace-commands off' |
| Disable command tracing. |
| |
| `show trace-commands' |
| Display the current state of command tracing. |
| |
| |
| File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB |
| |
| 22.8 Optional Messages about Internal Happenings |
| ================================================ |
| |
| GDB has commands that enable optional debugging messages from various |
| GDB subsystems; normally these commands are of interest to GDB |
| maintainers, or when reporting a bug. This section documents those |
| commands. |
| |
| `set exec-done-display' |
| Turns on or off the notification of asynchronous commands' |
| completion. When on, GDB will print a message when an |
| asynchronous command finishes its execution. The default is off. |
| |
| `show exec-done-display' |
| Displays the current setting of asynchronous command completion |
| notification. |
| |
| `set debug arch' |
| Turns on or off display of gdbarch debugging info. The default is |
| off |
| |
| `show debug arch' |
| Displays the current state of displaying gdbarch debugging info. |
| |
| `set debug aix-thread' |
| Display debugging messages about inner workings of the AIX thread |
| module. |
| |
| `show debug aix-thread' |
| Show the current state of AIX thread debugging info display. |
| |
| `set debug dwarf2-die' |
| Dump DWARF2 DIEs after they are read in. The value is the number |
| of nesting levels to print. A value of zero turns off the display. |
| |
| `show debug dwarf2-die' |
| Show the current state of DWARF2 DIE debugging. |
| |
| `set debug displaced' |
| Turns on or off display of GDB debugging info for the displaced |
| stepping support. The default is off. |
| |
| `show debug displaced' |
| Displays the current state of displaying GDB debugging info |
| related to displaced stepping. |
| |
| `set debug event' |
| Turns on or off display of GDB event debugging info. The default |
| is off. |
| |
| `show debug event' |
| Displays the current state of displaying GDB event debugging info. |
| |
| `set debug expression' |
| Turns on or off display of debugging info about GDB expression |
| parsing. The default is off. |
| |
| `show debug expression' |
| Displays the current state of displaying debugging info about GDB |
| expression parsing. |
| |
| `set debug frame' |
| Turns on or off display of GDB frame debugging info. The default |
| is off. |
| |
| `show debug frame' |
| Displays the current state of displaying GDB frame debugging info. |
| |
| `set debug gnu-nat' |
| Turns on or off debugging messages from the GNU/Hurd debug support. |
| |
| `show debug gnu-nat' |
| Show the current state of GNU/Hurd debugging messages. |
| |
| `set debug infrun' |
| Turns on or off display of GDB debugging info for running the |
| inferior. The default is off. `infrun.c' contains GDB's runtime |
| state machine used for implementing operations such as |
| single-stepping the inferior. |
| |
| `show debug infrun' |
| Displays the current state of GDB inferior debugging. |
| |
| `set debug lin-lwp' |
| Turns on or off debugging messages from the Linux LWP debug |
| support. |
| |
| `show debug lin-lwp' |
| Show the current state of Linux LWP debugging messages. |
| |
| `set debug lin-lwp-async' |
| Turns on or off debugging messages from the Linux LWP async debug |
| support. |
| |
| `show debug lin-lwp-async' |
| Show the current state of Linux LWP async debugging messages. |
| |
| `set debug observer' |
| Turns on or off display of GDB observer debugging. This includes |
| info such as the notification of observable events. |
| |
| `show debug observer' |
| Displays the current state of observer debugging. |
| |
| `set debug overload' |
| Turns on or off display of GDB C++ overload debugging info. This |
| includes info such as ranking of functions, etc. The default is |
| off. |
| |
| `show debug overload' |
| Displays the current state of displaying GDB C++ overload |
| debugging info. |
| |
| `set debug parser' |
| Turns on or off the display of expression parser debugging output. |
| Internally, this sets the `yydebug' variable in the expression |
| parser. *Note Tracing Your Parser: (bison)Tracing, for details. |
| The default is off. |
| |
| `show debug parser' |
| Show the current state of expression parser debugging. |
| |
| `set debug remote' |
| Turns on or off display of reports on all packets sent back and |
| forth across the serial line to the remote machine. The info is |
| printed on the GDB standard output stream. The default is off. |
| |
| `show debug remote' |
| Displays the state of display of remote packets. |
| |
| `set debug serial' |
| Turns on or off display of GDB serial debugging info. The default |
| is off. |
| |
| `show debug serial' |
| Displays the current state of displaying GDB serial debugging info. |
| |
| `set debug solib-frv' |
| Turns on or off debugging messages for FR-V shared-library code. |
| |
| `show debug solib-frv' |
| Display the current state of FR-V shared-library code debugging |
| messages. |
| |
| `set debug target' |
| Turns on or off display of GDB target debugging info. This info |
| includes what is going on at the target level of GDB, as it |
| happens. The default is 0. Set it to 1 to track events, and to 2 |
| to also track the value of large memory transfers. Changes to |
| this flag do not take effect until the next time you connect to a |
| target or use the `run' command. |
| |
| `show debug target' |
| Displays the current state of displaying GDB target debugging info. |
| |
| `set debug timestamp' |
| Turns on or off display of timestamps with GDB debugging info. |
| When enabled, seconds and microseconds are displayed before each |
| debugging message. |
| |
| `show debug timestamp' |
| Displays the current state of displaying timestamps with GDB |
| debugging info. |
| |
| `set debugvarobj' |
| Turns on or off display of GDB variable object debugging info. The |
| default is off. |
| |
| `show debugvarobj' |
| Displays the current state of displaying GDB variable object |
| debugging info. |
| |
| `set debug xml' |
| Turns on or off debugging messages for built-in XML parsers. |
| |
| `show debug xml' |
| Displays the current state of XML debugging messages. |
| |
| |
| File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB |
| |
| 22.9 Other Miscellaneous Settings |
| ================================= |
| |
| `set interactive-mode' |
| If `on', forces GDB to operate interactively. If `off', forces |
| GDB to operate non-interactively, If `auto' (the default), GDB |
| guesses which mode to use, based on whether the debugger was |
| started in a terminal or not. |
| |
| In the vast majority of cases, the debugger should be able to guess |
| correctly which mode should be used. But this setting can be |
| useful in certain specific cases, such as running a MinGW GDB |
| inside a cygwin window. |
| |
| `show interactive-mode' |
| Displays whether the debugger is operating in interactive mode or |
| not. |
| |
| |
| File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top |
| |
| 23 Extending GDB |
| **************** |
| |
| GDB provides two mechanisms for extension. The first is based on |
| composition of GDB commands, and the second is based on the Python |
| scripting language. |
| |
| To facilitate the use of these extensions, GDB is capable of |
| evaluating the contents of a file. When doing so, GDB can recognize |
| which scripting language is being used by looking at the filename |
| extension. Files with an unrecognized filename extension are always |
| treated as a GDB Command Files. *Note Command files: Command Files. |
| |
| You can control how GDB evaluates these files with the following |
| setting: |
| |
| `set script-extension off' |
| All scripts are always evaluated as GDB Command Files. |
| |
| `set script-extension soft' |
| The debugger determines the scripting language based on filename |
| extension. If this scripting language is supported, GDB evaluates |
| the script using that language. Otherwise, it evaluates the file |
| as a GDB Command File. |
| |
| `set script-extension strict' |
| The debugger determines the scripting language based on filename |
| extension, and evaluates the script using that language. If the |
| language is not supported, then the evaluation fails. |
| |
| `show script-extension' |
| Display the current value of the `script-extension' option. |
| |
| |
| * Menu: |
| |
| * Sequences:: Canned Sequences of Commands |
| * Python:: Scripting GDB using Python |
| |
| |
| File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB |
| |
| 23.1 Canned Sequences of Commands |
| ================================= |
| |
| Aside from breakpoint commands (*note Breakpoint Command Lists: Break |
| Commands.), GDB provides two ways to store sequences of commands for |
| execution as a unit: user-defined commands and command files. |
| |
| * Menu: |
| |
| * Define:: How to define your own commands |
| * Hooks:: Hooks for user-defined commands |
| * Command Files:: How to write scripts of commands to be stored in a file |
| * Output:: Commands for controlled output |
| |
| |
| File: gdb.info, Node: Define, Next: Hooks, Up: Sequences |
| |
| 23.1.1 User-defined Commands |
| ---------------------------- |
| |
| A "user-defined command" is a sequence of GDB commands to which you |
| assign a new name as a command. This is done with the `define' |
| command. User commands may accept up to 10 arguments separated by |
| whitespace. Arguments are accessed within the user command via |
| `$arg0...$arg9'. A trivial example: |
| |
| define adder |
| print $arg0 + $arg1 + $arg2 |
| end |
| |
| To execute the command use: |
| |
| adder 1 2 3 |
| |
| This defines the command `adder', which prints the sum of its three |
| arguments. Note the arguments are text substitutions, so they may |
| reference variables, use complex expressions, or even perform inferior |
| functions calls. |
| |
| In addition, `$argc' may be used to find out how many arguments have |
| been passed. This expands to a number in the range 0...10. |
| |
| define adder |
| if $argc == 2 |
| print $arg0 + $arg1 |
| end |
| if $argc == 3 |
| print $arg0 + $arg1 + $arg2 |
| end |
| end |
| |
| `define COMMANDNAME' |
| Define a command named COMMANDNAME. If there is already a command |
| by that name, you are asked to confirm that you want to redefine |
| it. COMMANDNAME may be a bare command name consisting of letters, |
| numbers, dashes, and underscores. It may also start with any |
| predefined prefix command. For example, `define target my-target' |
| creates a user-defined `target my-target' command. |
| |
| The definition of the command is made up of other GDB command |
| lines, which are given following the `define' command. The end of |
| these commands is marked by a line containing `end'. |
| |
| `document COMMANDNAME' |
| Document the user-defined command COMMANDNAME, so that it can be |
| accessed by `help'. The command COMMANDNAME must already be |
| defined. This command reads lines of documentation just as |
| `define' reads the lines of the command definition, ending with |
| `end'. After the `document' command is finished, `help' on command |
| COMMANDNAME displays the documentation you have written. |
| |
| You may use the `document' command again to change the |
| documentation of a command. Redefining the command with `define' |
| does not change the documentation. |
| |
| `dont-repeat' |
| Used inside a user-defined command, this tells GDB that this |
| command should not be repeated when the user hits <RET> (*note |
| repeat last command: Command Syntax.). |
| |
| `help user-defined' |
| List all user-defined commands, with the first line of the |
| documentation (if any) for each. |
| |
| `show user' |
| `show user COMMANDNAME' |
| Display the GDB commands used to define COMMANDNAME (but not its |
| documentation). If no COMMANDNAME is given, display the |
| definitions for all user-defined commands. |
| |
| `show max-user-call-depth' |
| `set max-user-call-depth' |
| The value of `max-user-call-depth' controls how many recursion |
| levels are allowed in user-defined commands before GDB suspects an |
| infinite recursion and aborts the command. |
| |
| In addition to the above commands, user-defined commands frequently |
| use control flow commands, described in *Note Command Files::. |
| |
| When user-defined commands are executed, the commands of the |
| definition are not printed. An error in any command stops execution of |
| the user-defined command. |
| |
| If used interactively, commands that would ask for confirmation |
| proceed without asking when used inside a user-defined command. Many |
| GDB commands that normally print messages to say what they are doing |
| omit the messages when used in a user-defined command. |
| |
| |
| File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences |
| |
| 23.1.2 User-defined Command Hooks |
| --------------------------------- |
| |
| You may define "hooks", which are a special kind of user-defined |
| command. Whenever you run the command `foo', if the user-defined |
| command `hook-foo' exists, it is executed (with no arguments) before |
| that command. |
| |
| A hook may also be defined which is run after the command you |
| executed. Whenever you run the command `foo', if the user-defined |
| command `hookpost-foo' exists, it is executed (with no arguments) after |
| that command. Post-execution hooks may exist simultaneously with |
| pre-execution hooks, for the same command. |
| |
| It is valid for a hook to call the command which it hooks. If this |
| occurs, the hook is not re-executed, thereby avoiding infinite |
| recursion. |
| |
| In addition, a pseudo-command, `stop' exists. Defining |
| (`hook-stop') makes the associated commands execute every time |
| execution stops in your program: before breakpoint commands are run, |
| displays are printed, or the stack frame is printed. |
| |
| For example, to ignore `SIGALRM' signals while single-stepping, but |
| treat them normally during normal execution, you could define: |
| |
| define hook-stop |
| handle SIGALRM nopass |
| end |
| |
| define hook-run |
| handle SIGALRM pass |
| end |
| |
| define hook-continue |
| handle SIGALRM pass |
| end |
| |
| As a further example, to hook at the beginning and end of the `echo' |
| command, and to add extra text to the beginning and end of the message, |
| you could define: |
| |
| define hook-echo |
| echo <<<--- |
| end |
| |
| define hookpost-echo |
| echo --->>>\n |
| end |
| |
| (gdb) echo Hello World |
| <<<---Hello World--->>> |
| (gdb) |
| |
| You can define a hook for any single-word command in GDB, but not |
| for command aliases; you should define a hook for the basic command |
| name, e.g. `backtrace' rather than `bt'. You can hook a multi-word |
| command by adding `hook-' or `hookpost-' to the last word of the |
| command, e.g. `define target hook-remote' to add a hook to `target |
| remote'. |
| |
| If an error occurs during the execution of your hook, execution of |
| GDB commands stops and GDB issues a prompt (before the command that you |
| actually typed had a chance to run). |
| |
| If you try to define a hook which does not match any known command, |
| you get a warning from the `define' command. |
| |
| |
| File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences |
| |
| 23.1.3 Command Files |
| -------------------- |
| |
| A command file for GDB is a text file made of lines that are GDB |
| commands. Comments (lines starting with `#') may also be included. An |
| empty line in a command file does nothing; it does not mean to repeat |
| the last command, as it would from the terminal. |
| |
| You can request the execution of a command file with the `source' |
| command. Note that the `source' command is also used to evaluate |
| scripts that are not Command Files. The exact behavior can be |
| configured using the `script-extension' setting. *Note Extending GDB: |
| Extending GDB. |
| |
| `source [-s] [-v] FILENAME' |
| Execute the command file FILENAME. |
| |
| The lines in a command file are generally executed sequentially, |
| unless the order of execution is changed by one of the _flow-control |
| commands_ described below. The commands are not printed as they are |
| executed. An error in any command terminates execution of the command |
| file and control is returned to the console. |
| |
| GDB first searches for FILENAME in the current directory. If the |
| file is not found there, and FILENAME does not specify a directory, |
| then GDB also looks for the file on the source search path (specified |
| with the `directory' command); except that `$cdir' is not searched |
| because the compilation directory is not relevant to scripts. |
| |
| If `-s' is specified, then GDB searches for FILENAME on the search |
| path even if FILENAME specifies a directory. The search is done by |
| appending FILENAME to each element of the search path. So, for |
| example, if FILENAME is `mylib/myscript' and the search path contains |
| `/home/user' then GDB will look for the script |
| `/home/user/mylib/myscript'. The search is also done if FILENAME is an |
| absolute path. For example, if FILENAME is `/tmp/myscript' and the |
| search path contains `/home/user' then GDB will look for the script |
| `/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains |
| a drive specification, it is stripped before concatenation. For |
| example, if FILENAME is `d:myscript' and the search path contains |
| `c:/tmp' then GDB will look for the script `c:/tmp/myscript'. |
| |
| If `-v', for verbose mode, is given then GDB displays each command |
| as it is executed. The option must be given before FILENAME, and is |
| interpreted as part of the filename anywhere else. |
| |
| Commands that would ask for confirmation if used interactively |
| proceed without asking when used in a command file. Many GDB commands |
| that normally print messages to say what they are doing omit the |
| messages when called from command files. |
| |
| GDB also accepts command input from standard input. In this mode, |
| normal output goes to standard output and error output goes to standard |
| error. Errors in a command file supplied on standard input do not |
| terminate execution of the command file--execution continues with the |
| next command. |
| |
| gdb < cmds > log 2>&1 |
| |
| (The syntax above will vary depending on the shell used.) This |
| example will execute commands from the file `cmds'. All output and |
| errors would be directed to `log'. |
| |
| Since commands stored on command files tend to be more general than |
| commands typed interactively, they frequently need to deal with |
| complicated situations, such as different or unexpected values of |
| variables and symbols, changes in how the program being debugged is |
| built, etc. GDB provides a set of flow-control commands to deal with |
| these complexities. Using these commands, you can write complex |
| scripts that loop over data structures, execute commands conditionally, |
| etc. |
| |
| `if' |
| `else' |
| This command allows to include in your script conditionally |
| executed commands. The `if' command takes a single argument, which |
| is an expression to evaluate. It is followed by a series of |
| commands that are executed only if the expression is true (its |
| value is nonzero). There can then optionally be an `else' line, |
| followed by a series of commands that are only executed if the |
| expression was false. The end of the list is marked by a line |
| containing `end'. |
| |
| `while' |
| This command allows to write loops. Its syntax is similar to |
| `if': the command takes a single argument, which is an expression |
| to evaluate, and must be followed by the commands to execute, one |
| per line, terminated by an `end'. These commands are called the |
| "body" of the loop. The commands in the body of `while' are |
| executed repeatedly as long as the expression evaluates to true. |
| |
| `loop_break' |
| This command exits the `while' loop in whose body it is included. |
| Execution of the script continues after that `while's `end' line. |
| |
| `loop_continue' |
| This command skips the execution of the rest of the body of |
| commands in the `while' loop in whose body it is included. |
| Execution branches to the beginning of the `while' loop, where it |
| evaluates the controlling expression. |
| |
| `end' |
| Terminate the block of commands that are the body of `if', `else', |
| or `while' flow-control commands. |
| |
| |
| File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences |
| |
| 23.1.4 Commands for Controlled Output |
| ------------------------------------- |
| |
| During the execution of a command file or a user-defined command, normal |
| GDB output is suppressed; the only output that appears is what is |
| explicitly printed by the commands in the definition. This section |
| describes three commands useful for generating exactly the output you |
| want. |
| |
| `echo TEXT' |
| Print TEXT. Nonprinting characters can be included in TEXT using |
| C escape sequences, such as `\n' to print a newline. *No newline |
| is printed unless you specify one.* In addition to the standard C |
| escape sequences, a backslash followed by a space stands for a |
| space. This is useful for displaying a string with spaces at the |
| beginning or the end, since leading and trailing spaces are |
| otherwise trimmed from all arguments. To print ` and foo = ', use |
| the command `echo \ and foo = \ '. |
| |
| A backslash at the end of TEXT can be used, as in C, to continue |
| the command onto subsequent lines. For example, |
| |
| echo This is some text\n\ |
| which is continued\n\ |
| onto several lines.\n |
| |
| produces the same output as |
| |
| echo This is some text\n |
| echo which is continued\n |
| echo onto several lines.\n |
| |
| `output EXPRESSION' |
| Print the value of EXPRESSION and nothing but that value: no |
| newlines, no `$NN = '. The value is not entered in the value |
| history either. *Note Expressions: Expressions, for more |
| information on expressions. |
| |
| `output/FMT EXPRESSION' |
| Print the value of EXPRESSION in format FMT. You can use the same |
| formats as for `print'. *Note Output Formats: Output Formats, for |
| more information. |
| |
| `printf TEMPLATE, EXPRESSIONS...' |
| Print the values of one or more EXPRESSIONS under the control of |
| the string TEMPLATE. To print several values, make EXPRESSIONS be |
| a comma-separated list of individual expressions, which may be |
| either numbers or pointers. Their values are printed as specified |
| by TEMPLATE, exactly as a C program would do by executing the code |
| below: |
| |
| printf (TEMPLATE, EXPRESSIONS...); |
| |
| As in `C' `printf', ordinary characters in TEMPLATE are printed |
| verbatim, while "conversion specification" introduced by the `%' |
| character cause subsequent EXPRESSIONS to be evaluated, their |
| values converted and formatted according to type and style |
| information encoded in the conversion specifications, and then |
| printed. |
| |
| For example, you can print two values in hex like this: |
| |
| printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo |
| |
| `printf' supports all the standard `C' conversion specifications, |
| including the flags and modifiers between the `%' character and |
| the conversion letter, with the following exceptions: |
| |
| * The argument-ordering modifiers, such as `2$', are not |
| supported. |
| |
| * The modifier `*' is not supported for specifying precision or |
| width. |
| |
| * The `'' flag (for separation of digits into groups according |
| to `LC_NUMERIC'') is not supported. |
| |
| * The type modifiers `hh', `j', `t', and `z' are not supported. |
| |
| * The conversion letter `n' (as in `%n') is not supported. |
| |
| * The conversion letters `a' and `A' are not supported. |
| |
| Note that the `ll' type modifier is supported only if the |
| underlying `C' implementation used to build GDB supports the `long |
| long int' type, and the `L' type modifier is supported only if |
| `long double' type is available. |
| |
| As in `C', `printf' supports simple backslash-escape sequences, |
| such as `\n', `\t', `\\', `\"', `\a', and `\f', that consist of |
| backslash followed by a single character. Octal and hexadecimal |
| escape sequences are not supported. |
| |
| Additionally, `printf' supports conversion specifications for DFP |
| ("Decimal Floating Point") types using the following length |
| modifiers together with a floating point specifier. letters: |
| |
| * `H' for printing `Decimal32' types. |
| |
| * `D' for printing `Decimal64' types. |
| |
| * `DD' for printing `Decimal128' types. |
| |
| If the underlying `C' implementation used to build GDB has support |
| for the three length modifiers for DFP types, other modifiers such |
| as width and precision will also be available for GDB to use. |
| |
| In case there is no such `C' support, no additional modifiers will |
| be available and the value will be printed in the standard way. |
| |
| Here's an example of printing DFP types using the above conversion |
| letters: |
| printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl |
| |
| `eval TEMPLATE, EXPRESSIONS...' |
| Convert the values of one or more EXPRESSIONS under the control of |
| the string TEMPLATE to a command line, and call it. |
| |
| |
| |
| File: gdb.info, Node: Python, Prev: Sequences, Up: Extending GDB |
| |
| 23.2 Scripting GDB using Python |
| =============================== |
| |
| You can script GDB using the Python programming language |
| (http://www.python.org/). This feature is available only if GDB was |
| configured using `--with-python'. |
| |
| Python scripts used by GDB should be installed in |
| `DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as |
| determined at GDB startup (*note Data Files::). This directory, known |
| as the "python directory", is automatically added to the Python Search |
| Path in order to allow the Python interpreter to locate all scripts |
| installed at this location. |
| |
| * Menu: |
| |
| * Python Commands:: Accessing Python from GDB. |
| * Python API:: Accessing GDB from Python. |
| * Auto-loading:: Automatically loading Python code. |
| |
| |
| File: gdb.info, Node: Python Commands, Next: Python API, Up: Python |
| |
| 23.2.1 Python Commands |
| ---------------------- |
| |
| GDB provides one command for accessing the Python interpreter, and one |
| related setting: |
| |
| `python [CODE]' |
| The `python' command can be used to evaluate Python code. |
| |
| If given an argument, the `python' command will evaluate the |
| argument as a Python command. For example: |
| |
| (gdb) python print 23 |
| 23 |
| |
| If you do not provide an argument to `python', it will act as a |
| multi-line command, like `define'. In this case, the Python |
| script is made up of subsequent command lines, given after the |
| `python' command. This command list is terminated using a line |
| containing `end'. For example: |
| |
| (gdb) python |
| Type python script |
| End with a line saying just "end". |
| >print 23 |
| >end |
| 23 |
| |
| `maint set python print-stack' |
| By default, GDB will print a stack trace when an error occurs in a |
| Python script. This can be controlled using `maint set python |
| print-stack': if `on', the default, then Python stack printing is |
| enabled; if `off', then Python stack printing is disabled. |
| |
| It is also possible to execute a Python script from the GDB |
| interpreter: |
| |
| `source `script-name'' |
| The script name must end with `.py' and GDB must be configured to |
| recognize the script language based on filename extension using |
| the `script-extension' setting. *Note Extending GDB: Extending |
| GDB. |
| |
| `python execfile ("script-name")' |
| This method is based on the `execfile' Python built-in function, |
| and thus is always available. |
| |
| |
| File: gdb.info, Node: Python API, Next: Auto-loading, Prev: Python Commands, Up: Python |
| |
| 23.2.2 Python API |
| ----------------- |
| |
| At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to |
| print using GDB's output-paging streams. A Python program which |
| outputs to one of these streams may have its output interrupted by the |
| user (*note Screen Size::). In this situation, a Python |
| `KeyboardInterrupt' exception is thrown. |
| |
| * Menu: |
| |
| * Basic Python:: Basic Python Functions. |
| * Exception Handling:: |
| * Values From Inferior:: |
| * Types In Python:: Python representation of types. |
| * Pretty Printing API:: Pretty-printing values. |
| * Selecting Pretty-Printers:: How GDB chooses a pretty-printer. |
| * Disabling Pretty-Printers:: Disabling broken printers. |
| * Inferiors In Python:: Python representation of inferiors (processes) |
| * Threads In Python:: Accessing inferior threads from Python. |
| * Commands In Python:: Implementing new commands in Python. |
| * Parameters In Python:: Adding new GDB parameters. |
| * Functions In Python:: Writing new convenience functions. |
| * Progspaces In Python:: Program spaces. |
| * Objfiles In Python:: Object files. |
| * Frames In Python:: Accessing inferior stack frames from Python. |
| * Blocks In Python:: Accessing frame blocks from Python. |
| * Symbols In Python:: Python representation of symbols. |
| * Symbol Tables In Python:: Python representation of symbol tables. |
| * Lazy Strings In Python:: Python representation of lazy strings. |
| * Breakpoints In Python:: Manipulating breakpoints using Python. |
| |
| |
| File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API |
| |
| 23.2.2.1 Basic Python |
| ..................... |
| |
| GDB introduces a new Python module, named `gdb'. All methods and |
| classes added by GDB are placed in this module. GDB automatically |
| `import's the `gdb' module for use in all scripts evaluated by the |
| `python' command. |
| |
| -- Variable: PYTHONDIR |
| A string containing the python directory (*note Python::). |
| |
| -- Function: execute command [from_tty] [to_string] |
| Evaluate COMMAND, a string, as a GDB CLI command. If a GDB |
| exception happens while COMMAND runs, it is translated as |
| described in *Note Exception Handling: Exception Handling. |
| |
| FROM_TTY specifies whether GDB ought to consider this command as |
| having originated from the user invoking it interactively. It |
| must be a boolean value. If omitted, it defaults to `False'. |
| |
| By default, any output produced by COMMAND is sent to GDB's |
| standard output. If the TO_STRING parameter is `True', then |
| output will be collected by `gdb.execute' and returned as a |
| string. The default is `False', in which case the return value is |
| `None'. If TO_STRING is `True', the GDB virtual terminal will be |
| temporarily set to unlimited width and height, and its pagination |
| will be disabled; *note Screen Size::. |
| |
| -- Function: breakpoints |
| Return a sequence holding all of GDB's breakpoints. *Note |
| Breakpoints In Python::, for more information. |
| |
| -- Function: parameter parameter |
| Return the value of a GDB parameter. PARAMETER is a string naming |
| the parameter to look up; PARAMETER may contain spaces if the |
| parameter has a multi-part name. For example, `print object' is a |
| valid parameter name. |
| |
| If the named parameter does not exist, this function throws a |
| `RuntimeError'. Otherwise, the parameter's value is converted to |
| a Python value of the appropriate type, and returned. |
| |
| -- Function: history number |
| Return a value from GDB's value history (*note Value History::). |
| NUMBER indicates which history element to return. If NUMBER is |
| negative, then GDB will take its absolute value and count backward |
| from the last element (i.e., the most recent element) to find the |
| value to return. If NUMBER is zero, then GDB will return the most |
| recent element. If the element specified by NUMBER doesn't exist |
| in the value history, a `RuntimeError' exception will be raised. |
| |
| If no exception is raised, the return value is always an instance |
| of `gdb.Value' (*note Values From Inferior::). |
| |
| -- Function: parse_and_eval expression |
| Parse EXPRESSION as an expression in the current language, |
| evaluate it, and return the result as a `gdb.Value'. EXPRESSION |
| must be a string. |
| |
| This function can be useful when implementing a new command (*note |
| Commands In Python::), as it provides a way to parse the command's |
| argument as an expression. It is also useful simply to compute |
| values, for example, it is the only way to get the value of a |
| convenience variable (*note Convenience Vars::) as a `gdb.Value'. |
| |
| -- Function: write string |
| Print a string to GDB's paginated standard output stream. Writing |
| to `sys.stdout' or `sys.stderr' will automatically call this |
| function. |
| |
| -- Function: flush |
| Flush GDB's paginated standard output stream. Flushing |
| `sys.stdout' or `sys.stderr' will automatically call this function. |
| |
| -- Function: target_charset |
| Return the name of the current target character set (*note |
| Character Sets::). This differs from |
| `gdb.parameter('target-charset')' in that `auto' is never returned. |
| |
| -- Function: target_wide_charset |
| Return the name of the current target wide character set (*note |
| Character Sets::). This differs from |
| `gdb.parameter('target-wide-charset')' in that `auto' is never |
| returned. |
| |
| |
| File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API |
| |
| 23.2.2.2 Exception Handling |
| ........................... |
| |
| When executing the `python' command, Python exceptions uncaught within |
| the Python code are translated to calls to GDB error-reporting |
| mechanism. If the command that called `python' does not handle the |
| error, GDB will terminate it and print an error message containing the |
| Python exception name, the associated value, and the Python call stack |
| backtrace at the point where the exception was raised. Example: |
| |
| (gdb) python print foo |
| Traceback (most recent call last): |
| File "<string>", line 1, in <module> |
| NameError: name 'foo' is not defined |
| |
| GDB errors that happen in GDB commands invoked by Python code are |
| converted to Python `RuntimeError' exceptions. User interrupt (via |
| `C-c' or by typing `q' at a pagination prompt) is translated to a |
| Python `KeyboardInterrupt' exception. If you catch these exceptions in |
| your Python code, your exception handler will see `RuntimeError' or |
| `KeyboardInterrupt' as the exception type, the GDB error message as its |
| value, and the Python call stack backtrace at the Python statement |
| closest to where the GDB error occured as the traceback. |
| |
| When implementing GDB commands in Python via `gdb.Command', it is |
| useful to be able to throw an exception that doesn't cause a traceback |
| to be printed. For example, the user may have invoked the command |
| incorrectly. Use the `gdb.GdbError' exception to handle this case. |
| Example: |
| |
| (gdb) python |
| >class HelloWorld (gdb.Command): |
| > """Greet the whole world.""" |
| > def __init__ (self): |
| > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) |
| > def invoke (self, args, from_tty): |
| > argv = gdb.string_to_argv (args) |
| > if len (argv) != 0: |
| > raise gdb.GdbError ("hello-world takes no arguments") |
| > print "Hello, World!" |
| >HelloWorld () |
| >end |
| (gdb) hello-world 42 |
| hello-world takes no arguments |
| |
| |
| File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API |
| |
| 23.2.2.3 Values From Inferior |
| ............................. |
| |
| GDB provides values it obtains from the inferior program in an object |
| of type `gdb.Value'. GDB uses this object for its internal bookkeeping |
| of the inferior's values, and for fetching values when necessary. |
| |
| Inferior values that are simple scalars can be used directly in |
| Python expressions that are valid for the value's data type. Here's an |
| example for an integer or floating-point value `some_val': |
| |
| bar = some_val + 2 |
| |
| As result of this, `bar' will also be a `gdb.Value' object whose values |
| are of the same type as those of `some_val'. |
| |
| Inferior values that are structures or instances of some class can |
| be accessed using the Python "dictionary syntax". For example, if |
| `some_val' is a `gdb.Value' instance holding a structure, you can |
| access its `foo' element with: |
| |
| bar = some_val['foo'] |
| |
| Again, `bar' will also be a `gdb.Value' object. |
| |
| The following attributes are provided: |
| |
| -- Instance Variable of Value: address |
| If this object is addressable, this read-only attribute holds |
| a `gdb.Value' object representing the address. Otherwise, |
| this attribute holds `None'. |
| |
| -- Instance Variable of 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. |
| |
| -- Instance Variable of Value: type |
| The type of this `gdb.Value'. The value of this attribute is |
| a `gdb.Type' object. |
| |
| The following methods are provided: |
| |
| -- Method on Value: cast type |
| Return a new instance of `gdb.Value' that is the result of |
| casting this instance to the type described by TYPE, which |
| must be a `gdb.Type' object. If the cast cannot be performed |
| for some reason, this method throws an exception. |
| |
| -- Method on Value: dereference |
| For pointer data types, this method returns a new `gdb.Value' |
| object whose contents is the object pointed to by the |
| pointer. For example, if `foo' is a C pointer to an `int', |
| declared in your C program as |
| |
| int *foo; |
| |
| then you can use the corresponding `gdb.Value' to access what |
| `foo' points to like this: |
| |
| bar = foo.dereference () |
| |
| The result `bar' will be a `gdb.Value' object holding the |
| value pointed to by `foo'. |
| |
| -- Method on Value: string [encoding] [errors] [length] |
| If this `gdb.Value' represents a string, then this method |
| converts the contents to a Python string. Otherwise, this |
| method will throw an exception. |
| |
| Strings are recognized in a language-specific way; whether a |
| given `gdb.Value' represents a string is determined by the |
| current language. |
| |
| For C-like languages, a value is a string if it is a pointer |
| to or an array of characters or ints. The string is assumed |
| to be terminated by a zero of the appropriate width. However |
| if the optional length argument is given, the string will be |
| converted to that given length, ignoring any embedded zeros |
| that the string may contain. |
| |
| If the optional ENCODING argument is given, it must be a |
| string naming the encoding of the string in the `gdb.Value', |
| such as `"ascii"', `"iso-8859-6"' or `"utf-8"'. It accepts |
| the same encodings as the corresponding argument to Python's |
| `string.decode' method, and the Python codec machinery will |
| be used to convert the string. If ENCODING is not given, or |
| if ENCODING is the empty string, then either the |
| `target-charset' (*note Character Sets::) will be used, or a |
| language-specific encoding will be used, if the current |
| language is able to supply one. |
| |
| The optional ERRORS argument is the same as the corresponding |
| argument to Python's `string.decode' method. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and converted to the given length. |
| |
| -- Method on Value: lazy_string [encoding] [length] |
| If this `gdb.Value' represents a string, then this method |
| converts the contents to a `gdb.LazyString' (*note Lazy |
| Strings In Python::). Otherwise, this method will throw an |
| exception. |
| |
| If the optional ENCODING argument is given, it must be a |
| string naming the encoding of the `gdb.LazyString'. Some |
| examples are: `ascii', `iso-8859-6' or `utf-8'. If the |
| ENCODING argument is an encoding that GDB does recognize, GDB |
| will raise an error. |
| |
| When a lazy string is printed, the GDB encoding machinery is |
| used to convert the string during printing. If the optional |
| ENCODING argument is not provided, or is an empty string, GDB |
| will automatically select the encoding most suitable for the |
| string type. For further information on encoding in GDB |
| please see *Note Character Sets::. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and encoded to the length of characters specified. If |
| the LENGTH argument is not provided, the string will be |
| fetched and encoded until a null of appropriate width is |
| found. |
| |
| |
| File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API |
| |
| 23.2.2.4 Types In Python |
| ........................ |
| |
| GDB represents types from the inferior using the class `gdb.Type'. |
| |
| The following type-related functions are available in the `gdb' |
| module: |
| |
| -- Function: lookup_type name [block] |
| This function looks up a type by name. NAME is the name of the |
| type to look up. It must be a string. |
| |
| If BLOCK is given, then NAME is looked up in that scope. |
| Otherwise, it is searched for globally. |
| |
| Ordinarily, this function will return an instance of `gdb.Type'. |
| If the named type cannot be found, it will throw an exception. |
| |
| An instance of `Type' has the following attributes: |
| |
| -- Instance Variable of Type: code |
| The type code for this type. The type code will be one of the |
| `TYPE_CODE_' constants defined below. |
| |
| -- Instance Variable of Type: sizeof |
| The size of this type, in target `char' units. Usually, a |
| target's `char' type will be an 8-bit byte. However, on some |
| unusual platforms, this type may have a different size. |
| |
| -- Instance Variable of Type: tag |
| The tag name for this type. The tag name is the name after |
| `struct', `union', or `enum' in C and C++; not all languages |
| have this concept. If this type has no tag name, then `None' |
| is returned. |
| |
| The following methods are provided: |
| |
| -- Method on Type: fields |
| For structure and union types, this method returns the |
| fields. Range types have two fields, the minimum and maximum |
| values. Enum types have one field per enum constant. |
| Function and method types have one field per parameter. The |
| base types of C++ classes are also represented as fields. If |
| the type has no fields, or does not fit into one of these |
| categories, an empty sequence will be returned. |
| |
| Each field is an object, with some pre-defined attributes: |
| `bitpos' |
| This attribute is not available for `static' fields (as |
| in C++ or Java). For non-`static' fields, the value is |
| the bit position of the field. |
| |
| `name' |
| The name of the field, or `None' for anonymous fields. |
| |
| `artificial' |
| This is `True' if the field is artificial, usually |
| meaning that it was provided by the compiler and not the |
| user. This attribute is always provided, and is `False' |
| if the field is not artificial. |
| |
| `is_base_class' |
| This is `True' if the field represents a base class of a |
| C++ structure. This attribute is always provided, and |
| is `False' if the field is not a base class of the type |
| that is the argument of `fields', or if that type was |
| not a C++ class. |
| |
| `bitsize' |
| If the field is packed, or is a bitfield, then this will |
| have a non-zero value, which is the size of the field in |
| bits. Otherwise, this will be zero; in this case the |
| field's size is given by its type. |
| |
| `type' |
| The type of the field. This is usually an instance of |
| `Type', but it can be `None' in some situations. |
| |
| -- Method on Type: const |
| Return a new `gdb.Type' object which represents a |
| `const'-qualified variant of this type. |
| |
| -- Method on Type: volatile |
| Return a new `gdb.Type' object which represents a |
| `volatile'-qualified variant of this type. |
| |
| -- Method on Type: unqualified |
| Return a new `gdb.Type' object which represents an unqualified |
| variant of this type. That is, the result is neither `const' |
| nor `volatile'. |
| |
| -- Method on Type: range |
| Return a Python `Tuple' object that contains two elements: the |
| low bound of the argument type and the high bound of that |
| type. If the type does not have a range, GDB will raise a |
| `RuntimeError' exception. |
| |
| -- Method on Type: reference |
| Return a new `gdb.Type' object which represents a reference |
| to this type. |
| |
| -- Method on Type: pointer |
| Return a new `gdb.Type' object which represents a pointer to |
| this type. |
| |
| -- Method on Type: strip_typedefs |
| Return a new `gdb.Type' that represents the real type, after |
| removing all layers of typedefs. |
| |
| -- Method on Type: target |
| Return a new `gdb.Type' object which represents the target |
| type of this type. |
| |
| For a pointer type, the target type is the type of the |
| pointed-to object. For an array type (meaning C-like |
| arrays), the target type is the type of the elements of the |
| array. For a function or method type, the target type is the |
| type of the return value. For a complex type, the target |
| type is the type of the elements. For a typedef, the target |
| type is the aliased type. |
| |
| If the type does not have a target, this method will throw an |
| exception. |
| |
| -- Method on Type: template_argument n [block] |
| If this `gdb.Type' is an instantiation of a template, this |
| will return a new `gdb.Type' which represents the type of the |
| Nth template argument. |
| |
| If this `gdb.Type' is not a template type, this will throw an |
| exception. Ordinarily, only C++ code will have template |
| types. |
| |
| If BLOCK is given, then NAME is looked up in that scope. |
| Otherwise, it is searched for globally. |
| |
| Each type has a code, which indicates what category this type falls |
| into. The available type categories are represented by constants |
| defined in the `gdb' module: |
| |
| `TYPE_CODE_PTR' |
| The type is a pointer. |
| |
| `TYPE_CODE_ARRAY' |
| The type is an array. |
| |
| `TYPE_CODE_STRUCT' |
| The type is a structure. |
| |
| `TYPE_CODE_UNION' |
| The type is a union. |
| |
| `TYPE_CODE_ENUM' |
| The type is an enum. |
| |
| `TYPE_CODE_FLAGS' |
| A bit flags type, used for things such as status registers. |
| |
| `TYPE_CODE_FUNC' |
| The type is a function. |
| |
| `TYPE_CODE_INT' |
| The type is an integer type. |
| |
| `TYPE_CODE_FLT' |
| A floating point type. |
| |
| `TYPE_CODE_VOID' |
| The special type `void'. |
| |
| `TYPE_CODE_SET' |
| A Pascal set type. |
| |
| `TYPE_CODE_RANGE' |
| A range type, that is, an integer type with bounds. |
| |
| `TYPE_CODE_STRING' |
| A string type. Note that this is only used for certain languages |
| with language-defined string types; C strings are not represented |
| this way. |
| |
| `TYPE_CODE_BITSTRING' |
| A string of bits. |
| |
| `TYPE_CODE_ERROR' |
| An unknown or erroneous type. |
| |
| `TYPE_CODE_METHOD' |
| A method type, as found in C++ or Java. |
| |
| `TYPE_CODE_METHODPTR' |
| A pointer-to-member-function. |
| |
| `TYPE_CODE_MEMBERPTR' |
| A pointer-to-member. |
| |
| `TYPE_CODE_REF' |
| A reference type. |
| |
| `TYPE_CODE_CHAR' |
| A character type. |
| |
| `TYPE_CODE_BOOL' |
| A boolean type. |
| |
| `TYPE_CODE_COMPLEX' |
| A complex float type. |
| |
| `TYPE_CODE_TYPEDEF' |
| A typedef to some other type. |
| |
| `TYPE_CODE_NAMESPACE' |
| A C++ namespace. |
| |
| `TYPE_CODE_DECFLOAT' |
| A decimal floating point type. |
| |
| `TYPE_CODE_INTERNAL_FUNCTION' |
| A function internal to GDB. This is the type used to represent |
| convenience functions. |
| |
| |
| File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API |
| |
| 23.2.2.5 Pretty Printing API |
| ............................ |
| |
| An example output is provided (*note Pretty Printing::). |
| |
| A pretty-printer is just an object that holds a value and implements |
| a specific interface, defined here. |
| |
| -- Operation on pretty printer: children (self) |
| GDB will call this method on a pretty-printer to compute the |
| children of the pretty-printer's value. |
| |
| This method must return an object conforming to the Python iterator |
| protocol. Each item returned by the iterator must be a tuple |
| holding two elements. The first element is the "name" of the |
| child; the second element is the child's value. The value can be |
| any Python object which is convertible to a GDB value. |
| |
| This method is optional. If it does not exist, GDB will act as |
| though the value has no children. |
| |
| -- Operation on pretty printer: display_hint (self) |
| The CLI may call this method and use its result to change the |
| formatting of a value. The result will also be supplied to an MI |
| consumer as a `displayhint' attribute of the variable being |
| printed. |
| |
| This method is optional. If it does exist, this method must |
| return a string. |
| |
| Some display hints are predefined by GDB: |
| |
| `array' |
| Indicate that the object being printed is "array-like". The |
| CLI uses this to respect parameters such as `set print |
| elements' and `set print array'. |
| |
| `map' |
| Indicate that the object being printed is "map-like", and |
| that the children of this value can be assumed to alternate |
| between keys and values. |
| |
| `string' |
| Indicate that the object being printed is "string-like". If |
| the printer's `to_string' method returns a Python string of |
| some kind, then GDB will call its internal language-specific |
| string-printing function to format the string. For the CLI |
| this means adding quotation marks, possibly escaping some |
| characters, respecting `set print elements', and the like. |
| |
| -- Operation on pretty printer: to_string (self) |
| GDB will call this method to display the string representation of |
| the value passed to the object's constructor. |
| |
| When printing from the CLI, if the `to_string' method exists, then |
| GDB will prepend its result to the values returned by `children'. |
| Exactly how this formatting is done is dependent on the display |
| hint, and may change as more hints are added. Also, depending on |
| the print settings (*note Print Settings::), the CLI may print |
| just the result of `to_string' in a stack trace, omitting the |
| result of `children'. |
| |
| If this method returns a string, it is printed verbatim. |
| |
| Otherwise, if this method returns an instance of `gdb.Value', then |
| GDB prints this value. This may result in a call to another |
| pretty-printer. |
| |
| If instead the method returns a Python value which is convertible |
| to a `gdb.Value', then GDB performs the conversion and prints the |
| resulting value. Again, this may result in a call to another |
| pretty-printer. Python scalars (integers, floats, and booleans) |
| and strings are convertible to `gdb.Value'; other types are not. |
| |
| Finally, if this method returns `None' then no further operations |
| are peformed in this method and nothing is printed. |
| |
| If the result is not one of these types, an exception is raised. |
| |
| GDB provides a function which can be used to look up the default |
| pretty-printer for a `gdb.Value': |
| |
| -- Function: default_visualizer value |
| This function takes a `gdb.Value' object as an argument. If a |
| pretty-printer for this value exists, then it is returned. If no |
| such printer exists, then this returns `None'. |
| |
| |
| File: gdb.info, Node: Selecting Pretty-Printers, Next: Disabling Pretty-Printers, Prev: Pretty Printing API, Up: Python API |
| |
| 23.2.2.6 Selecting Pretty-Printers |
| .................................. |
| |
| The Python list `gdb.pretty_printers' contains an array of functions or |
| callable objects that have been registered via addition as a |
| pretty-printer. Each `gdb.Progspace' contains a `pretty_printers' |
| attribute. Each `gdb.Objfile' also contains a `pretty_printers' |
| attribute. |
| |
| A function on one of these lists is passed a single `gdb.Value' |
| argument and should return a pretty-printer object conforming to the |
| interface definition above (*note Pretty Printing API::). If a function |
| cannot create a pretty-printer for the value, it should return `None'. |
| |
| GDB first checks the `pretty_printers' attribute of each |
| `gdb.Objfile' in the current program space and iteratively calls each |
| enabled function (*note Disabling Pretty-Printers::) in the list for |
| that `gdb.Objfile' until it receives a pretty-printer object. If no |
| pretty-printer is found in the objfile lists, GDB then searches the |
| pretty-printer list of the current program space, calling each enabled |
| function until an object is returned. After these lists have been |
| exhausted, it tries the global `gdb.pretty_printers' list, again |
| calling each enabled function until an object is returned. |
| |
| The order in which the objfiles are searched is not specified. For a |
| given list, functions are always invoked from the head of the list, and |
| iterated over sequentially until the end of the list, or a printer |
| object is returned. |
| |
| Here is an example showing how a `std::string' printer might be |
| written: |
| |
| class StdStringPrinter: |
| "Print a std::string" |
| |
| def __init__ (self, val): |
| self.val = val |
| |
| def to_string (self): |
| return self.val['_M_dataplus']['_M_p'] |
| |
| def display_hint (self): |
| return 'string' |
| |
| And here is an example showing how a lookup function for the printer |
| example above might be written. |
| |
| def str_lookup_function (val): |
| |
| lookup_tag = val.type.tag |
| regex = re.compile ("^std::basic_string<char,.*>$") |
| if lookup_tag == None: |
| return None |
| if regex.match (lookup_tag): |
| return StdStringPrinter (val) |
| |
| return None |
| |
| The example lookup function extracts the value's type, and attempts |
| to match it to a type that it can pretty-print. If it is a type the |
| printer can pretty-print, it will return a printer object. If not, it |
| returns `None'. |
| |
| We recommend that you put your core pretty-printers into a Python |
| package. If your pretty-printers are for use with a library, we |
| further recommend embedding a version number into the package name. |
| This practice will enable GDB to load multiple versions of your |
| pretty-printers at the same time, because they will have different |
| names. |
| |
| You should write auto-loaded code (*note Auto-loading::) such that it |
| can be evaluated multiple times without changing its meaning. An ideal |
| auto-load file will consist solely of `import's of your printer |
| modules, followed by a call to a register pretty-printers with the |
| current objfile. |
| |
| Taken as a whole, this approach will scale nicely to multiple |
| inferiors, each potentially using a different library version. |
| Embedding a version number in the Python package name will ensure that |
| GDB is able to load both sets of printers simultaneously. Then, |
| because the search for pretty-printers is done by objfile, and because |
| your auto-loaded code took care to register your library's printers |
| with a specific objfile, GDB will find the correct printers for the |
| specific version of the library used by each inferior. |
| |
| To continue the `std::string' example (*note Pretty Printing API::), |
| this code might appear in `gdb.libstdcxx.v6': |
| |
| def register_printers (objfile): |
| objfile.pretty_printers.add (str_lookup_function) |
| |
| And then the corresponding contents of the auto-load file would be: |
| |
| import gdb.libstdcxx.v6 |
| gdb.libstdcxx.v6.register_printers (gdb.current_objfile ()) |
| |
| |
| File: gdb.info, Node: Disabling Pretty-Printers, Next: Inferiors In Python, Prev: Selecting Pretty-Printers, Up: Python API |
| |
| 23.2.2.7 Disabling Pretty-Printers |
| .................................. |
| |
| For various reasons a pretty-printer may not work. For example, the |
| underlying data structure may have changed and the pretty-printer is |
| out of date. |
| |
| The consequences of a broken pretty-printer are severe enough that |
| GDB provides support for enabling and disabling individual printers. |
| For example, if `print frame-arguments' is on, a backtrace can become |
| highly illegible if any argument is printed with a broken printer. |
| |
| Pretty-printers are enabled and disabled by attaching an `enabled' |
| attribute to the registered function or callable object. If this |
| attribute is present and its value is `False', the printer is disabled, |
| otherwise the printer is enabled. |
| |
| |
| File: gdb.info, Node: Inferiors In Python, Next: Threads In Python, Prev: Disabling Pretty-Printers, Up: Python API |
| |
| 23.2.2.8 Inferiors In Python |
| ............................ |
| |
| Programs which are being run under GDB are called inferiors (*note |
| Inferiors and Programs::). Python scripts can access information about |
| and manipulate inferiors controlled by GDB via objects of the |
| `gdb.Inferior' class. |
| |
| The following inferior-related functions are available in the `gdb' |
| module: |
| |
| -- Function: inferiors |
| Return a tuple containing all inferior objects. |
| |
| A `gdb.Inferior' object has the following attributes: |
| |
| -- Instance Variable of Inferior: num |
| ID of inferior, as assigned by GDB. |
| |
| -- Instance Variable of Inferior: pid |
| Process ID of the inferior, as assigned by the underlying |
| operating system. |
| |
| -- Instance Variable of Inferior: was_attached |
| Boolean signaling whether the inferior was created using |
| `attach', or started by GDB itself. |
| |
| A `gdb.Inferior' object has the following methods: |
| |
| -- Method on Inferior: threads |
| This method returns a tuple holding all the threads which are |
| valid when it is called. If there are no valid threads, the |
| method will return an empty tuple. |
| |
| -- Method on Inferior: read_memory address length |
| Read LENGTH bytes of memory from the inferior, starting at |
| ADDRESS. Returns a buffer object, which behaves much like an |
| array or a string. It can be modified and given to the |
| `gdb.write_memory' function. |
| |
| -- Method on Inferior: write_memory address buffer [length] |
| Write the contents of BUFFER to the inferior, starting at |
| ADDRESS. The BUFFER parameter must be a Python object which |
| supports the buffer protocol, i.e., a string, an array or the |
| object returned from `gdb.read_memory'. If given, LENGTH |
| determines the number of bytes from BUFFER to be written. |
| |
| -- Method on Inferior: search_memory address length pattern |
| Search a region of the inferior memory starting at ADDRESS |
| with the given LENGTH using the search pattern supplied in |
| PATTERN. The PATTERN parameter must be a Python object which |
| supports the buffer protocol, i.e., a string, an array or the |
| object returned from `gdb.read_memory'. Returns a Python |
| `Long' containing the address where the pattern was found, or |
| `None' if the pattern could not be found. |
| |
| |
| File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Inferiors In Python, Up: Python API |
| |
| 23.2.2.9 Threads In Python |
| .......................... |
| |
| Python scripts can access information about, and manipulate inferior |
| threads controlled by GDB, via objects of the `gdb.InferiorThread' |
| class. |
| |
| The following thread-related functions are available in the `gdb' |
| module: |
| |
| -- Function: selected_thread |
| This function returns the thread object for the selected thread. |
| If there is no selected thread, this will return `None'. |
| |
| A `gdb.InferiorThread' object has the following attributes: |
| |
| -- Instance Variable of InferiorThread: num |
| ID of the thread, as assigned by GDB. |
| |
| -- Instance Variable of InferiorThread: ptid |
| ID of the thread, as assigned by the operating system. This |
| attribute is a tuple containing three integers. The first is |
| the Process ID (PID); the second is the Lightweight Process |
| ID (LWPID), and the third is the Thread ID (TID). Either the |
| LWPID or TID may be 0, which indicates that the operating |
| system does not use that identifier. |
| |
| A `gdb.InferiorThread' object has the following methods: |
| |
| -- Method on InferiorThread: switch |
| This changes GDB's currently selected thread to the one |
| represented by this object. |
| |
| -- Method on InferiorThread: is_stopped |
| Return a Boolean indicating whether the thread is stopped. |
| |
| -- Method on InferiorThread: is_running |
| Return a Boolean indicating whether the thread is running. |
| |
| -- Method on InferiorThread: is_exited |
| Return a Boolean indicating whether the thread is exited. |
| |
| |
| File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API |
| |
| 23.2.2.10 Commands In Python |
| ............................ |
| |
| You can implement new GDB CLI commands in Python. A CLI command is |
| implemented using an instance of the `gdb.Command' class, most commonly |
| using a subclass. |
| |
| -- Method on Command: __init__ name COMMAND_CLASS [COMPLETER_CLASS] |
| [PREFIX] |
| The object initializer for `Command' registers the new command |
| with GDB. This initializer is normally invoked from the subclass' |
| own `__init__' method. |
| |
| NAME is the name of the command. If NAME consists of multiple |
| words, then the initial words are looked for as prefix commands. |
| In this case, if one of the prefix commands does not exist, an |
| exception is raised. |
| |
| There is no support for multi-line commands. |
| |
| COMMAND_CLASS should be one of the `COMMAND_' constants defined |
| below. This argument tells GDB how to categorize the new command |
| in the help system. |
| |
| COMPLETER_CLASS is an optional argument. If given, it should be |
| one of the `COMPLETE_' constants defined below. This argument |
| tells GDB how to perform completion for this command. If not |
| given, GDB will attempt to complete using the object's `complete' |
| method (see below); if no such method is found, an error will |
| occur when completion is attempted. |
| |
| PREFIX is an optional argument. If `True', then the new command |
| is a prefix command; sub-commands of this command may be |
| registered. |
| |
| The help text for the new command is taken from the Python |
| documentation string for the command's class, if there is one. If |
| no documentation string is provided, the default value "This |
| command is not documented." is used. |
| |
| -- Method on Command: dont_repeat |
| By default, a GDB command is repeated when the user enters a blank |
| line at the command prompt. A command can suppress this behavior |
| by invoking the `dont_repeat' method. This is similar to the user |
| command `dont-repeat', see *Note dont-repeat: Define. |
| |
| -- Method on Command: invoke argument from_tty |
| This method is called by GDB when this command is invoked. |
| |
| ARGUMENT is a string. It is the argument to the command, after |
| leading and trailing whitespace has been stripped. |
| |
| FROM_TTY is a boolean argument. When true, this means that the |
| command was entered by the user at the terminal; when false it |
| means that the command came from elsewhere. |
| |
| If this method throws an exception, it is turned into a GDB |
| `error' call. Otherwise, the return value is ignored. |
| |
| To break ARGUMENT up into an argv-like string use |
| `gdb.string_to_argv'. This function behaves identically to GDB's |
| internal argument lexer `buildargv'. It is recommended to use |
| this for consistency. Arguments are separated by spaces and may |
| be quoted. Example: |
| |
| print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") |
| ['1', '2 "3', '4 "5', "6 '7"] |
| |
| |
| -- Method on Command: complete text word |
| This method is called by GDB when the user attempts completion on |
| this command. All forms of completion are handled by this method, |
| that is, the <TAB> and <M-?> key bindings (*note Completion::), |
| and the `complete' command (*note complete: Help.). |
| |
| The arguments TEXT and WORD are both strings. TEXT holds the |
| complete command line up to the cursor's location. WORD holds the |
| last word of the command line; this is computed using a |
| word-breaking heuristic. |
| |
| The `complete' method can return several values: |
| * If the return value is a sequence, the contents of the |
| sequence are used as the completions. It is up to `complete' |
| to ensure that the contents actually do complete the word. A |
| zero-length sequence is allowed, it means that there were no |
| completions available. Only string elements of the sequence |
| are used; other elements in the sequence are ignored. |
| |
| * If the return value is one of the `COMPLETE_' constants |
| defined below, then the corresponding GDB-internal completion |
| function is invoked, and its result is used. |
| |
| * All other results are treated as though there were no |
| available completions. |
| |
| When a new command is registered, it must be declared as a member of |
| some general class of commands. This is used to classify top-level |
| commands in the on-line help system; note that prefix commands are not |
| listed under their own category but rather that of their top-level |
| command. The available classifications are represented by constants |
| defined in the `gdb' module: |
| |
| `COMMAND_NONE' |
| The command does not belong to any particular class. A command in |
| this category will not be displayed in any of the help categories. |
| |
| `COMMAND_RUNNING' |
| The command is related to running the inferior. For example, |
| `start', `step', and `continue' are in this category. Type `help |
| running' at the GDB prompt to see a list of commands in this |
| category. |
| |
| `COMMAND_DATA' |
| The command is related to data or variables. For example, `call', |
| `find', and `print' are in this category. Type `help data' at the |
| GDB prompt to see a list of commands in this category. |
| |
| `COMMAND_STACK' |
| The command has to do with manipulation of the stack. For example, |
| `backtrace', `frame', and `return' are in this category. Type |
| `help stack' at the GDB prompt to see a list of commands in this |
| category. |
| |
| `COMMAND_FILES' |
| This class is used for file-related commands. For example, |
| `file', `list' and `section' are in this category. Type `help |
| files' at the GDB prompt to see a list of commands in this |
| category. |
| |
| `COMMAND_SUPPORT' |
| This should be used for "support facilities", generally meaning |
| things that are useful to the user when interacting with GDB, but |
| not related to the state of the inferior. For example, `help', |
| `make', and `shell' are in this category. Type `help support' at |
| the GDB prompt to see a list of commands in this category. |
| |
| `COMMAND_STATUS' |
| The command is an `info'-related command, that is, related to the |
| state of GDB itself. For example, `info', `macro', and `show' are |
| in this category. Type `help status' at the GDB prompt to see a |
| list of commands in this category. |
| |
| `COMMAND_BREAKPOINTS' |
| The command has to do with breakpoints. For example, `break', |
| `clear', and `delete' are in this category. Type `help |
| breakpoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| `COMMAND_TRACEPOINTS' |
| The command has to do with tracepoints. For example, `trace', |
| `actions', and `tfind' are in this category. Type `help |
| tracepoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| `COMMAND_OBSCURE' |
| The command is only used in unusual circumstances, or is not of |
| general interest to users. For example, `checkpoint', `fork', and |
| `stop' are in this category. Type `help obscure' at the GDB |
| prompt to see a list of commands in this category. |
| |
| `COMMAND_MAINTENANCE' |
| The command is only useful to GDB maintainers. The `maintenance' |
| and `flushregs' commands are in this category. Type `help |
| internals' at the GDB prompt to see a list of commands in this |
| category. |
| |
| A new command can use a predefined completion function, either by |
| specifying it via an argument at initialization, or by returning it |
| from the `complete' method. These predefined completion constants are |
| all defined in the `gdb' module: |
| |
| `COMPLETE_NONE' |
| This constant means that no completion should be done. |
| |
| `COMPLETE_FILENAME' |
| This constant means that filename completion should be performed. |
| |
| `COMPLETE_LOCATION' |
| This constant means that location completion should be done. |
| *Note Specify Location::. |
| |
| `COMPLETE_COMMAND' |
| This constant means that completion should examine GDB command |
| names. |
| |
| `COMPLETE_SYMBOL' |
| This constant means that completion should be done using symbol |
| names as the source. |
| |
| The following code snippet shows how a trivial CLI command can be |
| implemented in Python: |
| |
| class HelloWorld (gdb.Command): |
| """Greet the whole world.""" |
| |
| def __init__ (self): |
| super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) |
| |
| def invoke (self, arg, from_tty): |
| print "Hello, World!" |
| |
| HelloWorld () |
| |
| The last line instantiates the class, and is necessary to trigger the |
| registration of the command with GDB. Depending on how the Python code |
| is read into GDB, you may need to import the `gdb' module explicitly. |
| |
| |
| File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API |
| |
| 23.2.2.11 Parameters In Python |
| .............................. |
| |
| You can implement new GDB parameters using Python. A new parameter is |
| implemented as an instance of the `gdb.Parameter' class. |
| |
| Parameters are exposed to the user via the `set' and `show' |
| commands. *Note Help::. |
| |
| There are many parameters that already exist and can be set in GDB. |
| Two examples are: `set follow fork' and `set charset'. Setting these |
| parameters influences certain behavior in GDB. Similarly, you can |
| define parameters that can be used to influence behavior in custom |
| Python scripts and commands. |
| |
| -- Method on Parameter: __init__ name COMMAND-CLASS PARAMETER-CLASS |
| [ENUM-SEQUENCE] |
| The object initializer for `Parameter' registers the new parameter |
| with GDB. This initializer is normally invoked from the subclass' |
| own `__init__' method. |
| |
| NAME is the name of the new parameter. If NAME consists of |
| multiple words, then the initial words are looked for as prefix |
| parameters. An example of this can be illustrated with the `set |
| print' set of parameters. If NAME is `print foo', then `print' |
| will be searched as the prefix parameter. In this case the |
| parameter can subsequently be accessed in GDB as `set print foo'. |
| |
| If NAME consists of multiple words, and no prefix parameter group |
| can be found, an exception is raised. |
| |
| COMMAND-CLASS should be one of the `COMMAND_' constants (*note |
| Commands In Python::). This argument tells GDB how to categorize |
| the new parameter in the help system. |
| |
| PARAMETER-CLASS should be one of the `PARAM_' constants defined |
| below. This argument tells GDB the type of the new parameter; |
| this information is used for input validation and completion. |
| |
| If PARAMETER-CLASS is `PARAM_ENUM', then ENUM-SEQUENCE must be a |
| sequence of strings. These strings represent the possible values |
| for the parameter. |
| |
| If PARAMETER-CLASS is not `PARAM_ENUM', then the presence of a |
| fourth argument will cause an exception to be thrown. |
| |
| The help text for the new parameter is taken from the Python |
| documentation string for the parameter's class, if there is one. |
| If there is no documentation string, a default value is used. |
| |
| -- Instance Variable of Parameter: set_doc |
| If this attribute exists, and is a string, then its value is used |
| as the help text for this parameter's `set' command. The value is |
| examined when `Parameter.__init__' is invoked; subsequent changes |
| have no effect. |
| |
| -- Instance Variable of Parameter: show_doc |
| If this attribute exists, and is a string, then its value is used |
| as the help text for this parameter's `show' command. The value is |
| examined when `Parameter.__init__' is invoked; subsequent changes |
| have no effect. |
| |
| -- Instance Variable of Parameter: value |
| The `value' attribute holds the underlying value of the parameter. |
| It can be read and assigned to just as any other attribute. GDB |
| does validation when assignments are made. |
| |
| When a new parameter is defined, its type must be specified. The |
| available types are represented by constants defined in the `gdb' |
| module: |
| |
| `PARAM_BOOLEAN' |
| The value is a plain boolean. The Python boolean values, `True' |
| and `False' are the only valid values. |
| |
| `PARAM_AUTO_BOOLEAN' |
| The value has three possible states: true, false, and `auto'. In |
| Python, true and false are represented using boolean constants, and |
| `auto' is represented using `None'. |
| |
| `PARAM_UINTEGER' |
| The value is an unsigned integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| `PARAM_INTEGER' |
| The value is a signed integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| `PARAM_STRING' |
| The value is a string. When the user modifies the string, any |
| escape sequences, such as `\t', `\f', and octal escapes, are |
| translated into corresponding characters and encoded into the |
| current host charset. |
| |
| `PARAM_STRING_NOESCAPE' |
| The value is a string. When the user modifies the string, escapes |
| are passed through untranslated. |
| |
| `PARAM_OPTIONAL_FILENAME' |
| The value is a either a filename (a string), or `None'. |
| |
| `PARAM_FILENAME' |
| The value is a filename. This is just like |
| `PARAM_STRING_NOESCAPE', but uses file names for completion. |
| |
| `PARAM_ZINTEGER' |
| The value is an integer. This is like `PARAM_INTEGER', except 0 |
| is interpreted as itself. |
| |
| `PARAM_ENUM' |
| The value is a string, which must be one of a collection string |
| constants provided when the parameter is created. |
| |
| |
| File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API |
| |
| 23.2.2.12 Writing new convenience functions |
| ........................................... |
| |
| You can implement new convenience functions (*note Convenience Vars::) |
| in Python. A convenience function is an instance of a subclass of the |
| class `gdb.Function'. |
| |
| -- Method on Function: __init__ name |
| The initializer for `Function' registers the new function with |
| GDB. The argument NAME is the name of the function, a string. |
| The function will be visible to the user as a convenience variable |
| of type `internal function', whose name is the same as the given |
| NAME. |
| |
| The documentation for the new function is taken from the |
| documentation string for the new class. |
| |
| -- Method on Function: invoke *ARGS |
| When a convenience function is evaluated, its arguments are |
| converted to instances of `gdb.Value', and then the function's |
| `invoke' method is called. Note that GDB does not predetermine |
| the arity of convenience functions. Instead, all available |
| arguments are passed to `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 `gdb.Value' following the usual rules. |
| |
| The following code snippet shows how a trivial convenience function |
| can be implemented in Python: |
| |
| 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 () |
| |
| The last line instantiates the class, and is necessary to trigger the |
| registration of the function with GDB. Depending on how the Python |
| code is read into GDB, you may need to import the `gdb' module |
| explicitly. |
| |
| |
| File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API |
| |
| 23.2.2.13 Program Spaces In Python |
| .................................. |
| |
| A program space, or "progspace", represents a symbolic view of an |
| address space. It consists of all of the objfiles of the program. |
| *Note Objfiles In Python::. *Note program spaces: Inferiors and |
| Programs, for more details about program spaces. |
| |
| The following progspace-related functions are available in the `gdb' |
| module: |
| |
| -- Function: current_progspace |
| This function returns the program space of the currently selected |
| inferior. *Note Inferiors and Programs::. |
| |
| -- Function: progspaces |
| Return a sequence of all the progspaces currently known to GDB. |
| |
| Each progspace is represented by an instance of the `gdb.Progspace' |
| class. |
| |
| -- Instance Variable of Progspace: filename |
| The file name of the progspace as a string. |
| |
| -- Instance Variable of Progspace: pretty_printers |
| The `pretty_printers' attribute is a list of functions. It is |
| used to look up pretty-printers. A `Value' is passed to each |
| function in order; if the function returns `None', then the search |
| continues. Otherwise, the return value should be an object which |
| is used to format the value. *Note Pretty Printing API::, for more |
| information. |
| |
| |
| File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API |
| |
| 23.2.2.14 Objfiles In Python |
| ............................ |
| |
| GDB loads symbols for an inferior from various symbol-containing files |
| (*note Files::). These include the primary executable file, any shared |
| libraries used by the inferior, and any separate debug info files |
| (*note Separate Debug Files::). GDB calls these symbol-containing |
| files "objfiles". |
| |
| The following objfile-related functions are available in the `gdb' |
| module: |
| |
| -- Function: current_objfile |
| When auto-loading a Python script (*note Auto-loading::), GDB sets |
| the "current objfile" to the corresponding objfile. This function |
| returns the current objfile. If there is no current objfile, this |
| function returns `None'. |
| |
| -- Function: objfiles |
| Return a sequence of all the objfiles current known to GDB. *Note |
| Objfiles In Python::. |
| |
| Each objfile is represented by an instance of the `gdb.Objfile' |
| class. |
| |
| -- Instance Variable of Objfile: filename |
| The file name of the objfile as a string. |
| |
| -- Instance Variable of Objfile: pretty_printers |
| The `pretty_printers' attribute is a list of functions. It is |
| used to look up pretty-printers. A `Value' is passed to each |
| function in order; if the function returns `None', then the search |
| continues. Otherwise, the return value should be an object which |
| is used to format the value. *Note Pretty Printing API::, for more |
| information. |
| |
| |
| File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API |
| |
| 23.2.2.15 Accessing inferior stack frames from Python. |
| ...................................................... |
| |
| When the debugged program stops, GDB is able to analyze its call stack |
| (*note Stack frames: Frames.). The `gdb.Frame' class represents a |
| frame in the stack. A `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, GDB will throw a `RuntimeError' exception. |
| |
| Two `gdb.Frame' objects can be compared for equality with the `==' |
| operator, like: |
| |
| (gdb) python print gdb.newest_frame() == gdb.selected_frame () |
| True |
| |
| The following frame-related functions are available in the `gdb' |
| module: |
| |
| -- Function: selected_frame |
| Return the selected frame object. (*note Selecting a Frame: |
| Selection.). |
| |
| -- Function: frame_stop_reason_string reason |
| Return a string explaining the reason why GDB stopped unwinding |
| frames, as expressed by the given REASON code (an integer, see the |
| `unwind_stop_reason' method further down in this section). |
| |
| A `gdb.Frame' object has the following methods: |
| |
| -- Method on Frame: is_valid |
| Returns true if the `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 `gdb.Frame' |
| methods will throw an exception if it is invalid at the time |
| the method is called. |
| |
| -- Method on Frame: name |
| Returns the function name of the frame, or `None' if it can't |
| be obtained. |
| |
| -- Method on Frame: type |
| Returns the type of the frame. The value can be one of |
| `gdb.NORMAL_FRAME', `gdb.DUMMY_FRAME', `gdb.SIGTRAMP_FRAME' |
| or `gdb.SENTINEL_FRAME'. |
| |
| -- Method on Frame: unwind_stop_reason |
| Return an integer representing the reason why it's not |
| possible to find more frames toward the outermost frame. Use |
| `gdb.frame_stop_reason_string' to convert the value returned |
| by this function to a string. |
| |
| -- Method on Frame: pc |
| Returns the frame's resume address. |
| |
| -- Method on Frame: block |
| Return the frame's code block. *Note Blocks In Python::. |
| |
| -- Method on Frame: function |
| Return the symbol for the function corresponding to this |
| frame. *Note Symbols In Python::. |
| |
| -- Method on Frame: older |
| Return the frame that called this frame. |
| |
| -- Method on Frame: newer |
| Return the frame called by this frame. |
| |
| -- Method on Frame: find_sal |
| Return the frame's symtab and line object. *Note Symbol |
| Tables In Python::. |
| |
| -- Method on Frame: read_var variable [block] |
| Return the value of VARIABLE in this frame. If the optional |
| argument BLOCK is provided, search for the variable from that |
| block; otherwise start at the frame's current block (which is |
| determined by the frame's current program counter). VARIABLE |
| must be a string or a `gdb.Symbol' object. BLOCK must be a |
| `gdb.Block' object. |
| |
| -- Method on Frame: select |
| Set this frame to be the selected frame. *Note Examining the |
| Stack: Stack. |
| |
| |
| File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API |
| |
| 23.2.2.16 Accessing frame blocks from Python. |
| ............................................. |
| |
| Within each frame, GDB maintains information on each block stored in |
| that frame. These blocks are organized hierarchically, and are |
| represented individually in Python as a `gdb.Block'. Please see *Note |
| Frames In Python::, for a more in-depth discussion on frames. |
| Furthermore, see *Note Examining the Stack: Stack, for more detailed |
| technical information on GDB's book-keeping of the stack. |
| |
| The following block-related functions are available in the `gdb' |
| module: |
| |
| -- Function: block_for_pc pc |
| Return the `gdb.Block' containing the given PC value. If the |
| block cannot be found for the PC value specified, the function |
| will return `None'. |
| |
| A `gdb.Block' object has the following attributes: |
| |
| -- Instance Variable of Block: start |
| The start address of the block. This attribute is not |
| writable. |
| |
| -- Instance Variable of Block: end |
| The end address of the block. This attribute is not writable. |
| |
| -- Instance Variable of Block: function |
| The name of the block represented as a `gdb.Symbol'. If the |
| block is not named, then this attribute holds `None'. This |
| attribute is not writable. |
| |
| -- Instance Variable of Block: superblock |
| The block containing this block. If this parent block does |
| not exist, this attribute holds `None'. This attribute is |
| not writable. |
| |
| |
| File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API |
| |
| 23.2.2.17 Python representation of Symbols. |
| ........................................... |
| |
| GDB represents every variable, function and type as an entry in a |
| symbol table. *Note Examining the Symbol Table: Symbols. Similarly, |
| Python represents these symbols in GDB with the `gdb.Symbol' object. |
| |
| The following symbol-related functions are available in the `gdb' |
| module: |
| |
| -- Function: lookup_symbol name [block] [domain] |
| This function searches for a symbol by name. The search scope can |
| be restricted to the parameters defined in the optional domain and |
| block arguments. |
| |
| NAME is the name of the symbol. It must be a string. The |
| optional BLOCK argument restricts the search to symbols visible in |
| that BLOCK. The BLOCK argument must be a `gdb.Block' object. The |
| optional DOMAIN argument restricts the search to the domain type. |
| The DOMAIN argument must be a domain constant defined in the `gdb' |
| module and described later in this chapter. |
| |
| A `gdb.Symbol' object has the following attributes: |
| |
| -- Instance Variable of Symbol: symtab |
| The symbol table in which the symbol appears. This attribute |
| is represented as a `gdb.Symtab' object. *Note Symbol Tables |
| In Python::. This attribute is not writable. |
| |
| -- Instance Variable of Symbol: name |
| The name of the symbol as a string. This attribute is not |
| writable. |
| |
| -- Instance Variable of Symbol: linkage_name |
| The name of the symbol, as used by the linker (i.e., may be |
| mangled). This attribute is not writable. |
| |
| -- Instance Variable of Symbol: print_name |
| The name of the symbol in a form suitable for output. This |
| is either `name' or `linkage_name', depending on whether the |
| user asked GDB to display demangled or mangled names. |
| |
| -- Instance Variable of Symbol: addr_class |
| The address class of the symbol. This classifies how to find |
| the value of a symbol. Each address class is a constant |
| defined in the `gdb' module and described later in this |
| chapter. |
| |
| -- Instance Variable of Symbol: is_argument |
| `True' if the symbol is an argument of a function. |
| |
| -- Instance Variable of Symbol: is_constant |
| `True' if the symbol is a constant. |
| |
| -- Instance Variable of Symbol: is_function |
| `True' if the symbol is a function or a method. |
| |
| -- Instance Variable of Symbol: is_variable |
| `True' if the symbol is a variable. |
| |
| The available domain categories in `gdb.Symbol' are represented as |
| constants in the `gdb' module: |
| |
| `SYMBOL_UNDEF_DOMAIN' |
| This is used when a domain has not been discovered or none of the |
| following domains apply. This usually indicates an error either |
| in the symbol information or in GDB's handling of symbols. |
| |
| `SYMBOL_VAR_DOMAIN' |
| This domain contains variables, function names, typedef names and |
| enum type values. |
| |
| `SYMBOL_STRUCT_DOMAIN' |
| This domain holds struct, union and enum type names. |
| |
| `SYMBOL_LABEL_DOMAIN' |
| This domain contains names of labels (for gotos). |
| |
| `SYMBOL_VARIABLES_DOMAIN' |
| This domain holds a subset of the `SYMBOLS_VAR_DOMAIN'; it |
| contains everything minus functions and types. |
| |
| `SYMBOL_FUNCTION_DOMAIN' |
| This domain contains all functions. |
| |
| `SYMBOL_TYPES_DOMAIN' |
| This domain contains all types. |
| |
| The available address class categories in `gdb.Symbol' are |
| represented as constants in the `gdb' module: |
| |
| `SYMBOL_LOC_UNDEF' |
| If this is returned by address class, it indicates an error either |
| in the symbol information or in GDB's handling of symbols. |
| |
| `SYMBOL_LOC_CONST' |
| Value is constant int. |
| |
| `SYMBOL_LOC_STATIC' |
| Value is at a fixed address. |
| |
| `SYMBOL_LOC_REGISTER' |
| Value is in a register. |
| |
| `SYMBOL_LOC_ARG' |
| Value is an argument. This value is at the offset stored within |
| the symbol inside the frame's argument list. |
| |
| `SYMBOL_LOC_REF_ARG' |
| Value address is stored in the frame's argument list. Just like |
| `LOC_ARG' except that the value's address is stored at the offset, |
| not the value itself. |
| |
| `SYMBOL_LOC_REGPARM_ADDR' |
| Value is a specified register. Just like `LOC_REGISTER' except |
| the register holds the address of the argument instead of the |
| argument itself. |
| |
| `SYMBOL_LOC_LOCAL' |
| Value is a local variable. |
| |
| `SYMBOL_LOC_TYPEDEF' |
| Value not used. Symbols in the domain `SYMBOL_STRUCT_DOMAIN' all |
| have this class. |
| |
| `SYMBOL_LOC_BLOCK' |
| Value is a block. |
| |
| `SYMBOL_LOC_CONST_BYTES' |
| Value is a byte-sequence. |
| |
| `SYMBOL_LOC_UNRESOLVED' |
| Value is at a fixed address, but the address of the variable has |
| to be determined from the minimal symbol table whenever the |
| variable is referenced. |
| |
| `SYMBOL_LOC_OPTIMIZED_OUT' |
| The value does not actually exist in the program. |
| |
| `SYMBOL_LOC_COMPUTED' |
| The value's address is a computed location. |
| |
| |
| File: gdb.info, Node: Symbol Tables In Python, Next: Lazy Strings In Python, Prev: Symbols In Python, Up: Python API |
| |
| 23.2.2.18 Symbol table representation in Python. |
| ................................................ |
| |
| Access to symbol table data maintained by GDB on the inferior is |
| exposed to Python via two objects: `gdb.Symtab_and_line' and |
| `gdb.Symtab'. Symbol table and line data for a frame is returned from |
| the `find_sal' method in `gdb.Frame' object. *Note Frames In Python::. |
| |
| For more information on GDB's symbol table management, see *Note |
| Examining the Symbol Table: Symbols, for more information. |
| |
| A `gdb.Symtab_and_line' object has the following attributes: |
| |
| -- Instance Variable of Symtab_and_line: symtab |
| The symbol table object (`gdb.Symtab') for this frame. This |
| attribute is not writable. |
| |
| -- Instance Variable of Symtab_and_line: pc |
| Indicates the current program counter address. This |
| attribute is not writable. |
| |
| -- Instance Variable of Symtab_and_line: line |
| Indicates the current line number for this object. This |
| attribute is not writable. |
| |
| A `gdb.Symtab' object has the following attributes: |
| |
| -- Instance Variable of Symtab: filename |
| The symbol table's source filename. This attribute is not |
| writable. |
| |
| -- Instance Variable of Symtab: objfile |
| The symbol table's backing object file. *Note Objfiles In |
| Python::. This attribute is not writable. |
| |
| The following methods are provided: |
| |
| -- Method on Symtab: fullname |
| Return the symbol table's source absolute file name. |
| |
| |
| File: gdb.info, Node: Breakpoints In Python, Prev: Lazy Strings In Python, Up: Python API |
| |
| 23.2.2.19 Manipulating breakpoints using Python |
| ............................................... |
| |
| Python code can manipulate breakpoints via the `gdb.Breakpoint' class. |
| |
| -- Method on Breakpoint: __init__ spec [type] [wp_class] |
| Create a new breakpoint. SPEC is a string naming the location of |
| the breakpoint, or an expression that defines a watchpoint. The |
| contents can be any location recognized by the `break' command, or |
| in the case of a watchpoint, by the `watch' command. The optional |
| TYPE denotes the breakpoint to create from the types defined later |
| in this chapter. This argument can be either: `BP_BREAKPOINT' or |
| `BP_WATCHPOINT'. TYPE defaults to `BP_BREAKPOINT'. The optional |
| WP_CLASS argument defines the class of watchpoint to create, if |
| TYPE is defined as `BP_WATCHPOINT'. If a watchpoint class is not |
| provided, it is assumed to be a WP_WRITE class. |
| |
| The available watchpoint types represented by constants are defined |
| in the `gdb' module: |
| |
| `WP_READ' |
| Read only watchpoint. |
| |
| `WP_WRITE' |
| Write only watchpoint. |
| |
| `WP_ACCESS' |
| Read/Write watchpoint. |
| |
| -- Method on Breakpoint: is_valid |
| Return `True' if this `Breakpoint' object is valid, `False' |
| otherwise. A `Breakpoint' object can become invalid if the user |
| deletes the breakpoint. In this case, the object still exists, |
| but the underlying breakpoint does not. In the cases of |
| watchpoint scope, the watchpoint remains valid even if execution |
| of the inferior leaves the scope of that watchpoint. |
| |
| -- Instance Variable of Breakpoint: enabled |
| This attribute is `True' if the breakpoint is enabled, and `False' |
| otherwise. This attribute is writable. |
| |
| -- Instance Variable of Breakpoint: silent |
| This attribute is `True' if the breakpoint is silent, and `False' |
| otherwise. This attribute is writable. |
| |
| Note that a breakpoint can also be silent if it has commands and |
| the first command is `silent'. This is not reported by the |
| `silent' attribute. |
| |
| -- Instance Variable of Breakpoint: thread |
| If the breakpoint is thread-specific, this attribute holds the |
| thread id. If the breakpoint is not thread-specific, this |
| attribute is `None'. This attribute is writable. |
| |
| -- Instance Variable of Breakpoint: task |
| If the breakpoint is Ada task-specific, this attribute holds the |
| Ada task id. If the breakpoint is not task-specific (or the |
| underlying language is not Ada), this attribute is `None'. This |
| attribute is writable. |
| |
| -- Instance Variable of Breakpoint: ignore_count |
| This attribute holds the ignore count for the breakpoint, an |
| integer. This attribute is writable. |
| |
| -- Instance Variable of Breakpoint: number |
| This attribute holds the breakpoint's number -- the identifier |
| used by the user to manipulate the breakpoint. This attribute is |
| not writable. |
| |
| -- Instance Variable of Breakpoint: type |
| This attribute holds the breakpoint's type -- the identifier used |
| to determine the actual breakpoint type or use-case. This |
| attribute is not writable. |
| |
| The available types are represented by constants defined in the `gdb' |
| module: |
| |
| `BP_BREAKPOINT' |
| Normal code breakpoint. |
| |
| `BP_WATCHPOINT' |
| Watchpoint breakpoint. |
| |
| `BP_HARDWARE_WATCHPOINT' |
| Hardware assisted watchpoint. |
| |
| `BP_READ_WATCHPOINT' |
| Hardware assisted read watchpoint. |
| |
| `BP_ACCESS_WATCHPOINT' |
| Hardware assisted access watchpoint. |
| |
| -- Instance Variable of Breakpoint: hit_count |
| This attribute holds the hit count for the breakpoint, an integer. |
| This attribute is writable, but currently it can only be set to |
| zero. |
| |
| -- Instance Variable of Breakpoint: location |
| This attribute holds the location of the breakpoint, as specified |
| by the user. It is a string. If the breakpoint does not have a |
| location (that is, it is a watchpoint) the attribute's value is |
| `None'. This attribute is not writable. |
| |
| -- Instance Variable of Breakpoint: expression |
| This attribute holds a breakpoint expression, as specified by the |
| user. It is a string. If the breakpoint does not have an |
| expression (the breakpoint is not a watchpoint) the attribute's |
| value is `None'. This attribute is not writable. |
| |
| -- Instance Variable of Breakpoint: condition |
| This attribute holds the condition of the breakpoint, as specified |
| by the user. It is a string. If there is no condition, this |
| attribute's value is `None'. This attribute is writable. |
| |
| -- Instance Variable of Breakpoint: commands |
| This attribute holds the commands attached to the breakpoint. If |
| there are commands, this attribute's value is a string holding all |
| the commands, separated by newlines. If there are no commands, |
| this attribute is `None'. This attribute is not writable. |
| |
| |
| File: gdb.info, Node: Lazy Strings In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API |
| |
| 23.2.2.20 Python representation of lazy strings. |
| ................................................ |
| |
| A "lazy string" is a string whose contents is not retrieved or encoded |
| until it is needed. |
| |
| A `gdb.LazyString' is represented in GDB as an `address' that points |
| to a region of memory, an `encoding' that will be used to encode that |
| region of memory, and a `length' to delimit the region of memory that |
| represents the string. The difference between a `gdb.LazyString' and a |
| string wrapped within a `gdb.Value' is that a `gdb.LazyString' will be |
| treated differently by GDB when printing. A `gdb.LazyString' is |
| retrieved and encoded during printing, while a `gdb.Value' wrapping a |
| string is immediately retrieved and encoded on creation. |
| |
| A `gdb.LazyString' object has the following functions: |
| |
| -- Method on LazyString: value |
| Convert the `gdb.LazyString' to a `gdb.Value'. This value will |
| point to the string in memory, but will lose all the delayed |
| retrieval, encoding and handling that GDB applies to a |
| `gdb.LazyString'. |
| |
| -- Instance Variable of LazyString: address |
| This attribute holds the address of the string. This attribute is |
| not writable. |
| |
| -- Instance Variable of LazyString: length |
| This attribute holds the length of the string in characters. If |
| the length is -1, then the string will be fetched and encoded up |
| to the first null of appropriate width. This attribute is not |
| writable. |
| |
| -- Instance Variable of LazyString: encoding |
| This attribute holds the encoding that will be applied to the |
| string when the string is printed by GDB. If the encoding is not |
| set, or contains an empty string, then GDB will select the most |
| appropriate encoding when the string is printed. This attribute |
| is not writable. |
| |
| -- Instance Variable of LazyString: type |
| This attribute holds the type that is represented by the lazy |
| string's type. For a lazy string this will always be a pointer |
| type. To resolve this to the lazy string's character type, use |
| the type's `target' method. *Note Types In Python::. This |
| attribute is not writable. |
| |
| |
| File: gdb.info, Node: Auto-loading, Prev: Python API, Up: Python |
| |
| 23.2.3 Auto-loading |
| ------------------- |
| |
| When a new object file is read (for example, due to the `file' command, |
| or because the inferior has loaded a shared library), GDB will look for |
| Python support scripts in several ways: `OBJFILE-gdb.py' and |
| `.debug_gdb_scripts' section. |
| |
| * Menu: |
| |
| * objfile-gdb.py file:: The `OBJFILE-gdb.py' file |
| * .debug_gdb_scripts section:: The `.debug_gdb_scripts' section |
| * Which flavor to choose?:: |
| |
| The auto-loading feature is useful for supplying application-specific |
| debugging commands and scripts. |
| |
| Auto-loading can be enabled or disabled. |
| |
| `maint set python auto-load [yes|no]' |
| Enable or disable the Python auto-loading feature. |
| |
| `maint show python auto-load' |
| Show whether Python auto-loading is enabled or disabled. |
| |
| When reading an auto-loaded file, GDB sets the "current objfile". |
| This is available via the `gdb.current_objfile' function (*note |
| Objfiles In Python::). This can be useful for registering |
| objfile-specific pretty-printers. |
| |
| |
| File: gdb.info, Node: objfile-gdb.py file, Next: .debug_gdb_scripts section, Up: Auto-loading |
| |
| 23.2.3.1 The `OBJFILE-gdb.py' file |
| .................................. |
| |
| When a new object file is read, GDB looks for a file named |
| `OBJFILE-gdb.py', where OBJFILE is the object file's real name, formed |
| by ensuring that the file name is absolute, following all symlinks, and |
| resolving `.' and `..' components. If this file exists and is |
| readable, GDB will evaluate it as a Python script. |
| |
| If this file does not exist, and if the parameter |
| `debug-file-directory' is set (*note Separate Debug Files::), then GDB |
| will look for REAL-NAME in all of the directories mentioned in the |
| value of `debug-file-directory'. |
| |
| Finally, if this file does not exist, then GDB will look for a file |
| named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY |
| is GDB's data directory (available via `show data-directory', *note |
| Data Files::), and REAL-NAME is the object file's real name, as |
| described above. |
| |
| GDB does not track which files it has already auto-loaded this way. |
| GDB will load the associated script every time the corresponding |
| OBJFILE is opened. So your `-gdb.py' file should be careful to avoid |
| errors if it is evaluated more than once. |
| |
| |
| File: gdb.info, Node: .debug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdb.py file, Up: Auto-loading |
| |
| 23.2.3.2 The `.debug_gdb_scripts' section |
| ......................................... |
| |
| For systems using file formats like ELF and COFF, when GDB loads a new |
| object file it will look for a special section named |
| `.debug_gdb_scripts'. If this section exists, its contents is a list |
| of names of scripts to load. |
| |
| GDB will look for each specified script file first in the current |
| directory and then along the source search path (*note Specifying |
| Source Directories: Source Path.), except that `$cdir' is not searched, |
| since the compilation directory is not relevant to scripts. |
| |
| Entries can be placed in section `.debug_gdb_scripts' with, for |
| example, this GCC macro: |
| |
| /* Note: The "MS" section flags are to remove duplicates. */ |
| #define DEFINE_GDB_SCRIPT(script_name) \ |
| asm("\ |
| .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ |
| .byte 1\n\ |
| .asciz \"" script_name "\"\n\ |
| .popsection \n\ |
| "); |
| |
| Then one can reference the macro in a header or source file like this: |
| |
| DEFINE_GDB_SCRIPT ("my-app-scripts.py") |
| |
| The script name may include directories if desired. |
| |
| If the macro is put in a header, any application or library using |
| this header will get a reference to the specified script. |
| |
| |
| File: gdb.info, Node: Which flavor to choose?, Prev: .debug_gdb_scripts section, Up: Auto-loading |
| |
| 23.2.3.3 Which flavor to choose? |
| ................................ |
| |
| Given the multiple ways of auto-loading Python scripts, it might not |
| always be clear which one to choose. This section provides some |
| guidance. |
| |
| Benefits of the `-gdb.py' way: |
| |
| * Can be used with file formats that don't support multiple sections. |
| |
| * Ease of finding scripts for public libraries. |
| |
| Scripts specified in the `.debug_gdb_scripts' section are searched |
| for in the source search path. For publicly installed libraries, |
| e.g., `libstdc++', there typically isn't a source directory in |
| which to find the script. |
| |
| * Doesn't require source code additions. |
| |
| Benefits of the `.debug_gdb_scripts' way: |
| |
| * Works with static linking. |
| |
| Scripts for libraries done the `-gdb.py' way require an objfile to |
| trigger their loading. When an application is statically linked |
| the only objfile available is the executable, and it is cumbersome |
| to attach all the scripts from all the input libraries to the |
| executable's `-gdb.py' script. |
| |
| * Works with classes that are entirely inlined. |
| |
| Some classes can be entirely inlined, and thus there may not be an |
| associated shared library to attach a `-gdb.py' script to. |
| |
| * Scripts needn't be copied out of the source tree. |
| |
| In some circumstances, apps can be built out of large collections |
| of internal libraries, and the build infrastructure necessary to |
| install the `-gdb.py' scripts in a place where GDB can find them is |
| cumbersome. It may be easier to specify the scripts in the |
| `.debug_gdb_scripts' section as relative paths, and add a path to |
| the top of the source tree to the source search path. |
| |
| |
| File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top |
| |
| 24 Command Interpreters |
| *********************** |
| |
| GDB supports multiple command interpreters, and some command |
| infrastructure to allow users or user interface writers to switch |
| between interpreters or run commands in other interpreters. |
| |
| GDB currently supports two command interpreters, the console |
| interpreter (sometimes called the command-line interpreter or CLI) and |
| the machine interface interpreter (or GDB/MI). This manual describes |
| both of these interfaces in great detail. |
| |
| By default, GDB will start with the console interpreter. However, |
| the user may choose to start GDB with another interpreter by specifying |
| the `-i' or `--interpreter' startup options. Defined interpreters |
| include: |
| |
| `console' |
| The traditional console or command-line interpreter. This is the |
| most often used interpreter with GDB. With no interpreter |
| specified at runtime, GDB will use this interpreter. |
| |
| `mi' |
| The newest GDB/MI interface (currently `mi2'). Used primarily by |
| programs wishing to use GDB as a backend for a debugger GUI or an |
| IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. |
| |
| `mi2' |
| The current GDB/MI interface. |
| |
| `mi1' |
| The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. |
| |
| |
| The interpreter being used by GDB may not be dynamically switched at |
| runtime. Although possible, this could lead to a very precarious |
| situation. Consider an IDE using GDB/MI. If a user enters the command |
| "interpreter-set console" in a console view, GDB would switch to using |
| the console interpreter, rendering the IDE inoperable! |
| |
| Although you may only choose a single interpreter at startup, you |
| may execute commands in any interpreter from the current interpreter |
| using the appropriate command. If you are running the console |
| interpreter, simply use the `interpreter-exec' command: |
| |
| interpreter-exec mi "-data-list-register-names" |
| |
| GDB/MI has a similar command, although it is only available in |
| versions of GDB which support GDB/MI version 2 (or greater). |
| |
| |
| File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top |
| |
| 25 GDB Text User Interface |
| ************************** |
| |
| * Menu: |
| |
| * TUI Overview:: TUI overview |
| * TUI Keys:: TUI key bindings |
| * TUI Single Key Mode:: TUI single key mode |
| * TUI Commands:: TUI-specific commands |
| * TUI Configuration:: TUI configuration variables |
| |
| The GDB Text User Interface (TUI) is a terminal interface which uses |
| the `curses' library to show the source file, the assembly output, the |
| program registers and GDB commands in separate text windows. The TUI |
| mode is supported only on platforms where a suitable version of the |
| `curses' library is available. |
| |
| The TUI mode is enabled by default when you invoke GDB as either |
| `gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode |
| while GDB runs by using various TUI commands and key bindings, such as |
| `C-x C-a'. *Note TUI Key Bindings: TUI Keys. |
| |
| |
| File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI |
| |
| 25.1 TUI Overview |
| ================= |
| |
| In TUI mode, GDB can display several text windows: |
| |
| _command_ |
| This window is the GDB command window with the GDB prompt and the |
| GDB output. The GDB input is still managed using readline. |
| |
| _source_ |
| The source window shows the source file of the program. The |
| current line and active breakpoints are displayed in this window. |
| |
| _assembly_ |
| The assembly window shows the disassembly output of the program. |
| |
| _register_ |
| This window shows the processor registers. Registers are |
| highlighted when their values change. |
| |
| The source and assembly windows show the current program position by |
| highlighting the current line and marking it with a `>' marker. |
| Breakpoints are indicated with two markers. The first marker indicates |
| the breakpoint type: |
| |
| `B' |
| Breakpoint which was hit at least once. |
| |
| `b' |
| Breakpoint which was never hit. |
| |
| `H' |
| Hardware breakpoint which was hit at least once. |
| |
| `h' |
| Hardware breakpoint which was never hit. |
| |
| The second marker indicates whether the breakpoint is enabled or not: |
| |
| `+' |
| Breakpoint is enabled. |
| |
| `-' |
| Breakpoint is disabled. |
| |
| The source, assembly and register windows are updated when the |
| current thread changes, when the frame changes, or when the program |
| counter changes. |
| |
| These windows are not all visible at the same time. The command |
| window is always visible. The others can be arranged in several |
| layouts: |
| |
| * source only, |
| |
| * assembly only, |
| |
| * source and assembly, |
| |
| * source and registers, or |
| |
| * assembly and registers. |
| |
| A status line above the command window shows the following |
| information: |
| |
| _target_ |
| Indicates the current GDB target. (*note Specifying a Debugging |
| Target: Targets.). |
| |
| _process_ |
| Gives the current process or thread number. When no process is |
| being debugged, this field is set to `No process'. |
| |
| _function_ |
| Gives the current function name for the selected frame. The name |
| is demangled if demangling is turned on (*note Print Settings::). |
| When there is no symbol corresponding to the current program |
| counter, the string `??' is displayed. |
| |
| _line_ |
| Indicates the current line number for the selected frame. When |
| the current line number is not known, the string `??' is displayed. |
| |
| _pc_ |
| Indicates the current program counter address. |
| |
| |
| File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI |
| |
| 25.2 TUI Key Bindings |
| ===================== |
| |
| The TUI installs several key bindings in the readline keymaps (*note |
| Command Line Editing::). The following key bindings are installed for |
| both TUI mode and the GDB standard mode. |
| |
| `C-x C-a' |
| `C-x a' |
| `C-x A' |
| Enter or leave the TUI mode. When leaving the TUI mode, the |
| curses window management stops and GDB operates using its standard |
| mode, writing on the terminal directly. When reentering the TUI |
| mode, control is given back to the curses windows. The screen is |
| then refreshed. |
| |
| `C-x 1' |
| Use a TUI layout with only one window. The layout will either be |
| `source' or `assembly'. When the TUI mode is not active, it will |
| switch to the TUI mode. |
| |
| Think of this key binding as the Emacs `C-x 1' binding. |
| |
| `C-x 2' |
| Use a TUI layout with at least two windows. When the current |
| layout already has two windows, the next layout with two windows |
| is used. When a new layout is chosen, one window will always be |
| common to the previous layout and the new one. |
| |
| Think of it as the Emacs `C-x 2' binding. |
| |
| `C-x o' |
| Change the active window. The TUI associates several key bindings |
| (like scrolling and arrow keys) with the active window. This |
| command gives the focus to the next TUI window. |
| |
| Think of it as the Emacs `C-x o' binding. |
| |
| `C-x s' |
| Switch in and out of the TUI SingleKey mode that binds single keys |
| to GDB commands (*note TUI Single Key Mode::). |
| |
| The following key bindings only work in the TUI mode: |
| |
| <PgUp> |
| Scroll the active window one page up. |
| |
| <PgDn> |
| Scroll the active window one page down. |
| |
| <Up> |
| Scroll the active window one line up. |
| |
| <Down> |
| Scroll the active window one line down. |
| |
| <Left> |
| Scroll the active window one column left. |
| |
| <Right> |
| Scroll the active window one column right. |
| |
| `C-L' |
| Refresh the screen. |
| |
| Because the arrow keys scroll the active window in the TUI mode, they |
| are not available for their normal use by readline unless the command |
| window has the focus. When another window is active, you must use |
| other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to |
| control the command window. |
| |
| |
| File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI |
| |
| 25.3 TUI Single Key Mode |
| ======================== |
| |
| The TUI also provides a "SingleKey" mode, which binds several |
| frequently used GDB commands to single keys. Type `C-x s' to switch |
| into this mode, where the following key bindings are used: |
| |
| `c' |
| continue |
| |
| `d' |
| down |
| |
| `f' |
| finish |
| |
| `n' |
| next |
| |
| `q' |
| exit the SingleKey mode. |
| |
| `r' |
| run |
| |
| `s' |
| step |
| |
| `u' |
| up |
| |
| `v' |
| info locals |
| |
| `w' |
| where |
| |
| Other keys temporarily switch to the GDB command prompt. The key |
| that was pressed is inserted in the editing buffer so that it is |
| possible to type most GDB commands without interaction with the TUI |
| SingleKey mode. Once the command is entered the TUI SingleKey mode is |
| restored. The only way to permanently leave this mode is by typing `q' |
| or `C-x s'. |
| |
| |
| File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI |
| |
| 25.4 TUI-specific Commands |
| ========================== |
| |
| The TUI has specific commands to control the text windows. These |
| commands are always available, even when GDB is not in the TUI mode. |
| When GDB is in the standard mode, most of these commands will |
| automatically switch to the TUI mode. |
| |
| Note that if GDB's `stdout' is not connected to a terminal, or GDB |
| has been started with the machine interface interpreter (*note The |
| GDB/MI Interface: GDB/MI.), most of these commands will fail with an |
| error, because it would not be possible or desirable to enable curses |
| window management. |
| |
| `info win' |
| List and give the size of all displayed windows. |
| |
| `layout next' |
| Display the next layout. |
| |
| `layout prev' |
| Display the previous layout. |
| |
| `layout src' |
| Display the source window only. |
| |
| `layout asm' |
| Display the assembly window only. |
| |
| `layout split' |
| Display the source and assembly window. |
| |
| `layout regs' |
| Display the register window together with the source or assembly |
| window. |
| |
| `focus next' |
| Make the next window active for scrolling. |
| |
| `focus prev' |
| Make the previous window active for scrolling. |
| |
| `focus src' |
| Make the source window active for scrolling. |
| |
| `focus asm' |
| Make the assembly window active for scrolling. |
| |
| `focus regs' |
| Make the register window active for scrolling. |
| |
| `focus cmd' |
| Make the command window active for scrolling. |
| |
| `refresh' |
| Refresh the screen. This is similar to typing `C-L'. |
| |
| `tui reg float' |
| Show the floating point registers in the register window. |
| |
| `tui reg general' |
| Show the general registers in the register window. |
| |
| `tui reg next' |
| Show the next register group. The list of register groups as well |
| as their order is target specific. The predefined register groups |
| are the following: `general', `float', `system', `vector', `all', |
| `save', `restore'. |
| |
| `tui reg system' |
| Show the system registers in the register window. |
| |
| `update' |
| Update the source window and the current execution point. |
| |
| `winheight NAME +COUNT' |
| `winheight NAME -COUNT' |
| Change the height of the window NAME by COUNT lines. Positive |
| counts increase the height, while negative counts decrease it. |
| |
| `tabset NCHARS' |
| Set the width of tab stops to be NCHARS characters. |
| |
| |
| File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI |
| |
| 25.5 TUI Configuration Variables |
| ================================ |
| |
| Several configuration variables control the appearance of TUI windows. |
| |
| `set tui border-kind KIND' |
| Select the border appearance for the source, assembly and register |
| windows. The possible values are the following: |
| `space' |
| Use a space character to draw the border. |
| |
| `ascii' |
| Use ASCII characters `+', `-' and `|' to draw the border. |
| |
| `acs' |
| Use the Alternate Character Set to draw the border. The |
| border is drawn using character line graphics if the terminal |
| supports them. |
| |
| `set tui border-mode MODE' |
| `set tui active-border-mode MODE' |
| Select the display attributes for the borders of the inactive |
| windows or the active window. The MODE can be one of the |
| following: |
| `normal' |
| Use normal attributes to display the border. |
| |
| `standout' |
| Use standout mode. |
| |
| `reverse' |
| Use reverse video mode. |
| |
| `half' |
| Use half bright mode. |
| |
| `half-standout' |
| Use half bright and standout mode. |
| |
| `bold' |
| Use extra bright or bold mode. |
| |
| `bold-standout' |
| Use extra bright or bold and standout mode. |
| |
| |
| File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top |
| |
| 26 Using GDB under GNU Emacs |
| **************************** |
| |
| A special interface allows you to use GNU Emacs to view (and edit) the |
| source files for the program you are debugging with GDB. |
| |
| To use this interface, use the command `M-x gdb' in Emacs. Give the |
| executable file you want to debug as an argument. This command starts |
| GDB as a subprocess of Emacs, with input and output through a newly |
| created Emacs buffer. |
| |
| Running GDB under Emacs can be just like running GDB normally except |
| for two things: |
| |
| * All "terminal" input and output goes through an Emacs buffer, |
| called the GUD buffer. |
| |
| This applies both to GDB commands and their output, and to the |
| input and output done by the program you are debugging. |
| |
| This is useful because it means that you can copy the text of |
| previous commands and input them again; you can even use parts of |
| the output in this way. |
| |
| All the facilities of Emacs' Shell mode are available for |
| interacting with your program. In particular, you can send |
| signals the usual way--for example, `C-c C-c' for an interrupt, |
| `C-c C-z' for a stop. |
| |
| * GDB displays source code through Emacs. |
| |
| Each time GDB displays a stack frame, Emacs automatically finds the |
| source file for that frame and puts an arrow (`=>') at the left |
| margin of the current line. Emacs uses a separate buffer for |
| source display, and splits the screen to show both your GDB session |
| and the source. |
| |
| Explicit GDB `list' or search commands still produce output as |
| usual, but you probably have no reason to use them from Emacs. |
| |
| We call this "text command mode". Emacs 22.1, and later, also uses |
| a graphical mode, enabled by default, which provides further buffers |
| that can control the execution and describe the state of your program. |
| *Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. |
| |
| If you specify an absolute file name when prompted for the `M-x gdb' |
| argument, then Emacs sets your current working directory to where your |
| program resides. If you only specify the file name, then Emacs sets |
| your current working directory to to the directory associated with the |
| previous buffer. In this case, GDB may find your program by searching |
| your environment's `PATH' variable, but on some operating systems it |
| might not find the source. So, although the GDB input and output |
| session proceeds normally, the auxiliary buffer does not display the |
| current source and line of execution. |
| |
| The initial working directory of GDB is printed on the top line of |
| the GUD buffer and this serves as a default for the commands that |
| specify files for GDB to operate on. *Note Commands to Specify Files: |
| Files. |
| |
| By default, `M-x gdb' calls the program called `gdb'. If you need |
| to call GDB by a different name (for example, if you keep several |
| configurations around, with different names) you can customize the |
| Emacs variable `gud-gdb-command-name' to run the one you want. |
| |
| In the GUD buffer, you can use these special Emacs commands in |
| addition to the standard Shell mode commands: |
| |
| `C-h m' |
| Describe the features of Emacs' GUD Mode. |
| |
| `C-c C-s' |
| Execute to another source line, like the GDB `step' command; also |
| update the display window to show the current file and location. |
| |
| `C-c C-n' |
| Execute to next source line in this function, skipping all function |
| calls, like the GDB `next' command. Then update the display window |
| to show the current file and location. |
| |
| `C-c C-i' |
| Execute one instruction, like the GDB `stepi' command; update |
| display window accordingly. |
| |
| `C-c C-f' |
| Execute until exit from the selected stack frame, like the GDB |
| `finish' command. |
| |
| `C-c C-r' |
| Continue execution of your program, like the GDB `continue' |
| command. |
| |
| `C-c <' |
| Go up the number of frames indicated by the numeric argument |
| (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' |
| command. |
| |
| `C-c >' |
| Go down the number of frames indicated by the numeric argument, |
| like the GDB `down' command. |
| |
| In any source file, the Emacs command `C-x <SPC>' (`gud-break') |
| tells GDB to set a breakpoint on the source line point is on. |
| |
| In text command mode, if you type `M-x speedbar', Emacs displays a |
| separate frame which shows a backtrace when the GUD buffer is current. |
| Move point to any frame in the stack and type <RET> to make it become |
| the current frame and display the associated source in the source |
| buffer. Alternatively, click `Mouse-2' to make the selected frame |
| become the current one. In graphical mode, the speedbar displays watch |
| expressions. |
| |
| If you accidentally delete the source-display buffer, an easy way to |
| get it back is to type the command `f' in the GDB buffer, to request a |
| frame display; when you run under Emacs, this recreates the source |
| buffer if necessary to show you the context of the current frame. |
| |
| The source files displayed in Emacs are in ordinary Emacs buffers |
| which are visiting the source files in the usual way. You can edit the |
| files with these buffers if you wish; but keep in mind that GDB |
| communicates with Emacs in terms of line numbers. If you add or delete |
| lines from the text, the line numbers that GDB knows cease to |
| correspond properly with the code. |
| |
| A more detailed description of Emacs' interaction with GDB is given |
| in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). |
| |
| |
| File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top |
| |
| 27 The GDB/MI Interface |
| *********************** |
| |
| Function and Purpose |
| ==================== |
| |
| GDB/MI is a line based machine oriented text interface to GDB and is |
| activated by specifying using the `--interpreter' command line option |
| (*note Mode Options::). It is specifically intended to support the |
| development of systems which use the debugger as just one small |
| component of a larger system. |
| |
| This chapter is a specification of the GDB/MI interface. It is |
| written in the form of a reference manual. |
| |
| Note that GDB/MI is still under construction, so some of the |
| features described below are incomplete and subject to change (*note |
| GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). |
| |
| Notation and Terminology |
| ======================== |
| |
| This chapter uses the following notation: |
| |
| * `|' separates two alternatives. |
| |
| * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or |
| may not be given. |
| |
| * `( GROUP )*' means that GROUP inside the parentheses may repeat |
| zero or more times. |
| |
| * `( GROUP )+' means that GROUP inside the parentheses may repeat |
| one or more times. |
| |
| * `"STRING"' means a literal STRING. |
| |
| * Menu: |
| |
| * GDB/MI General Design:: |
| * GDB/MI Command Syntax:: |
| * GDB/MI Compatibility with CLI:: |
| * GDB/MI Development and Front Ends:: |
| * GDB/MI Output Records:: |
| * GDB/MI Simple Examples:: |
| * GDB/MI Command Description Format:: |
| * GDB/MI Breakpoint Commands:: |
| * GDB/MI Program Context:: |
| * GDB/MI Thread Commands:: |
| * GDB/MI Program Execution:: |
| * GDB/MI Stack Manipulation:: |
| * GDB/MI Variable Objects:: |
| * GDB/MI Data Manipulation:: |
| * GDB/MI Tracepoint Commands:: |
| * GDB/MI Symbol Query:: |
| * GDB/MI File Commands:: |
| * GDB/MI Target Manipulation:: |
| * GDB/MI File Transfer Commands:: |
| * GDB/MI Miscellaneous Commands:: |
| |
| |
| File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI |
| |
| 27.1 GDB/MI General Design |
| ========================== |
| |
| Interaction of a GDB/MI frontend with GDB involves three |
| parts--commands sent to GDB, responses to those commands and |
| notifications. Each command results in exactly one response, |
| indicating either successful completion of the command, or an error. |
| For the commands that do not resume the target, the response contains |
| the requested information. For the commands that resume the target, the |
| response only indicates whether the target was successfully resumed. |
| Notifications is the mechanism for reporting changes in the state of the |
| target, or in GDB state, that cannot conveniently be associated with a |
| command and reported as part of that command response. |
| |
| The important examples of notifications are: |
| * Exec notifications. These are used to report changes in target |
| state--when a target is resumed, or stopped. It would not be |
| feasible to include this information in response of resuming |
| commands, because one resume commands can result in multiple |
| events in different threads. Also, quite some time may pass |
| before any event happens in the target, while a frontend needs to |
| know whether the resuming command itself was successfully executed. |
| |
| * Console output, and status notifications. Console output |
| notifications are used to report output of CLI commands, as well as |
| diagnostics for other commands. Status notifications are used to |
| report the progress of a long-running operation. Naturally, |
| including this information in command response would mean no |
| output is produced until the command is finished, which is |
| undesirable. |
| |
| * General notifications. Commands may have various side effects on |
| the GDB or target state beyond their official purpose. For |
| example, a command may change the selected thread. Although such |
| changes can be included in command response, using notification |
| allows for more orthogonal frontend design. |
| |
| |
| There's no guarantee that whenever an MI command reports an error, |
| GDB or the target are in any specific state, and especially, the state |
| is not reverted to the state before the MI command was processed. |
| Therefore, whenever an MI command results in an error, we recommend |
| that the frontend refreshes all the information shown in the user |
| interface. |
| |
| * Menu: |
| |
| * Context management:: |
| * Asynchronous and non-stop modes:: |
| * Thread groups:: |
| |
| |
| File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design |
| |
| 27.1.1 Context management |
| ------------------------- |
| |
| In most cases when GDB accesses the target, this access is done in |
| context of a specific thread and frame (*note Frames::). Often, even |
| when accessing global data, the target requires that a thread be |
| specified. The CLI interface maintains the selected thread and frame, |
| and supplies them to target on each command. This is convenient, |
| because a command line user would not want to specify that information |
| explicitly on each command, and because user interacts with GDB via a |
| single terminal, so no confusion is possible as to what thread and |
| frame are the current ones. |
| |
| In the case of MI, the concept of selected thread and frame is less |
| useful. First, a frontend can easily remember this information itself. |
| Second, a graphical frontend can have more than one window, each one |
| used for debugging a different thread, and the frontend might want to |
| access additional threads for internal purposes. This increases the |
| risk that by relying on implicitly selected thread, the frontend may be |
| operating on a wrong one. Therefore, each MI command should explicitly |
| specify which thread and frame to operate on. To make it possible, |
| each MI command accepts the `--thread' and `--frame' options, the value |
| to each is GDB identifier for thread and frame to operate on. |
| |
| Usually, each top-level window in a frontend allows the user to |
| select a thread and a frame, and remembers the user selection for |
| further operations. However, in some cases GDB may suggest that the |
| current thread be changed. For example, when stopping on a breakpoint |
| it is reasonable to switch to the thread where breakpoint is hit. For |
| another example, if the user issues the CLI `thread' command via the |
| frontend, it is desirable to change the frontend's selected thread to |
| the one specified by user. GDB communicates the suggestion to change |
| current thread using the `=thread-selected' notification. No such |
| notification is available for the selected frame at the moment. |
| |
| Note that historically, MI shares the selected thread with CLI, so |
| frontends used the `-thread-select' to execute commands in the right |
| context. However, getting this to work right is cumbersome. The |
| simplest way is for frontend to emit `-thread-select' command before |
| every command. This doubles the number of commands that need to be |
| sent. The alternative approach is to suppress `-thread-select' if the |
| selected thread in GDB is supposed to be identical to the thread the |
| frontend wants to operate on. However, getting this optimization right |
| can be tricky. In particular, if the frontend sends several commands |
| to GDB, and one of the commands changes the selected thread, then the |
| behaviour of subsequent commands will change. So, a frontend should |
| either wait for response from such problematic commands, or explicitly |
| add `-thread-select' for all subsequent commands. No frontend is known |
| to do this exactly right, so it is suggested to just always pass the |
| `--thread' and `--frame' options. |
| |
| |
| File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design |
| |
| 27.1.2 Asynchronous command execution and non-stop mode |
| ------------------------------------------------------- |
| |
| On some targets, GDB is capable of processing MI commands even while |
| the target is running. This is called "asynchronous command execution" |
| (*note Background Execution::). The frontend may specify a preferrence |
| for asynchronous execution using the `-gdb-set target-async 1' command, |
| which should be emitted before either running the executable or |
| attaching to the target. After the frontend has started the executable |
| or attached to the target, it can find if asynchronous execution is |
| enabled using the `-list-target-features' command. |
| |
| Even if GDB can accept a command while target is running, many |
| commands that access the target do not work when the target is running. |
| Therefore, asynchronous command execution is most useful when combined |
| with non-stop mode (*note Non-Stop Mode::). Then, it is possible to |
| examine the state of one thread, while other threads are running. |
| |
| When a given thread is running, MI commands that try to access the |
| target in the context of that thread may not work, or may work only on |
| some targets. In particular, commands that try to operate on thread's |
| stack will not work, on any target. Commands that read memory, or |
| modify breakpoints, may work or not work, depending on the target. Note |
| that even commands that operate on global state, such as `print', |
| `set', and breakpoint commands, still access the target in the context |
| of a specific thread, so frontend should try to find a stopped thread |
| and perform the operation on that thread (using the `--thread' option). |
| |
| Which commands will work in the context of a running thread is |
| highly target dependent. However, the two commands `-exec-interrupt', |
| to stop a thread, and `-thread-info', to find the state of a thread, |
| will always work. |
| |
| |
| File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design |
| |
| 27.1.3 Thread groups |
| -------------------- |
| |
| GDB may be used to debug several processes at the same time. On some |
| platfroms, GDB may support debugging of several hardware systems, each |
| one having several cores with several different processes running on |
| each core. This section describes the MI mechanism to support such |
| debugging scenarios. |
| |
| The key observation is that regardless of the structure of the |
| target, MI can have a global list of threads, because most commands that |
| accept the `--thread' option do not need to know what process that |
| thread belongs to. Therefore, it is not necessary to introduce neither |
| additional `--process' option, nor an notion of the current process in |
| the MI interface. The only strictly new feature that is required is |
| the ability to find how the threads are grouped into processes. |
| |
| To allow the user to discover such grouping, and to support arbitrary |
| hierarchy of machines/cores/processes, MI introduces the concept of a |
| "thread group". Thread group is a collection of threads and other |
| thread groups. A thread group always has a string identifier, a type, |
| and may have additional attributes specific to the type. A new |
| command, `-list-thread-groups', returns the list of top-level thread |
| groups, which correspond to processes that GDB is debugging at the |
| moment. By passing an identifier of a thread group to the |
| `-list-thread-groups' command, it is possible to obtain the members of |
| specific thread group. |
| |
| To allow the user to easily discover processes, and other objects, he |
| wishes to debug, a concept of "available thread group" is introduced. |
| Available thread group is an thread group that GDB is not debugging, |
| but that can be attached to, using the `-target-attach' command. The |
| list of available top-level thread groups can be obtained using |
| `-list-thread-groups --available'. In general, the content of a thread |
| group may be only retrieved only after attaching to that thread group. |
| |
| Thread groups are related to inferiors (*note Inferiors and |
| Programs::). Each inferior corresponds to a thread group of a special |
| type `process', and some additional operations are permitted on such |
| thread groups. |
| |
| |
| File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI |
| |
| 27.2 GDB/MI Command Syntax |
| ========================== |
| |
| * Menu: |
| |
| * GDB/MI Input Syntax:: |
| * GDB/MI Output Syntax:: |
| |
| |
| File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax |
| |
| 27.2.1 GDB/MI Input Syntax |
| -------------------------- |
| |
| `COMMAND ==>' |
| `CLI-COMMAND | MI-COMMAND' |
| |
| `CLI-COMMAND ==>' |
| `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB |
| CLI command. |
| |
| `MI-COMMAND ==>' |
| `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " |
| PARAMETER )* NL' |
| |
| `TOKEN ==>' |
| "any sequence of digits" |
| |
| `OPTION ==>' |
| `"-" PARAMETER [ " " PARAMETER ]' |
| |
| `PARAMETER ==>' |
| `NON-BLANK-SEQUENCE | C-STRING' |
| |
| `OPERATION ==>' |
| _any of the operations described in this chapter_ |
| |
| `NON-BLANK-SEQUENCE ==>' |
| _anything, provided it doesn't contain special characters such as |
| "-", NL, """ and of course " "_ |
| |
| `C-STRING ==>' |
| `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' |
| |
| `NL ==>' |
| `CR | CR-LF' |
| |
| Notes: |
| |
| * The CLI commands are still handled by the MI interpreter; their |
| output is described below. |
| |
| * The `TOKEN', when present, is passed back when the command |
| finishes. |
| |
| * Some MI commands accept optional arguments as part of the parameter |
| list. Each option is identified by a leading `-' (dash) and may be |
| followed by an optional argument parameter. Options occur first |
| in the parameter list and can be delimited from normal parameters |
| using `--' (this is useful when some parameters begin with a dash). |
| |
| Pragmatics: |
| |
| * We want easy access to the existing CLI syntax (for debugging). |
| |
| * We want it to be easy to spot a MI operation. |
| |
| |
| File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax |
| |
| 27.2.2 GDB/MI Output Syntax |
| --------------------------- |
| |
| The output from GDB/MI consists of zero or more out-of-band records |
| followed, optionally, by a single result record. This result record is |
| for the most recent command. The sequence of output records is |
| terminated by `(gdb)'. |
| |
| If an input command was prefixed with a `TOKEN' then the |
| corresponding output for that command will also be prefixed by that same |
| TOKEN. |
| |
| `OUTPUT ==>' |
| `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' |
| |
| `RESULT-RECORD ==>' |
| ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' |
| |
| `OUT-OF-BAND-RECORD ==>' |
| `ASYNC-RECORD | STREAM-RECORD' |
| |
| `ASYNC-RECORD ==>' |
| `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' |
| |
| `EXEC-ASYNC-OUTPUT ==>' |
| `[ TOKEN ] "*" ASYNC-OUTPUT' |
| |
| `STATUS-ASYNC-OUTPUT ==>' |
| `[ TOKEN ] "+" ASYNC-OUTPUT' |
| |
| `NOTIFY-ASYNC-OUTPUT ==>' |
| `[ TOKEN ] "=" ASYNC-OUTPUT' |
| |
| `ASYNC-OUTPUT ==>' |
| `ASYNC-CLASS ( "," RESULT )* NL' |
| |
| `RESULT-CLASS ==>' |
| `"done" | "running" | "connected" | "error" | "exit"' |
| |
| `ASYNC-CLASS ==>' |
| `"stopped" | OTHERS' (where OTHERS will be added depending on the |
| needs--this is still in development). |
| |
| `RESULT ==>' |
| ` VARIABLE "=" VALUE' |
| |
| `VARIABLE ==>' |
| ` STRING ' |
| |
| `VALUE ==>' |
| ` CONST | TUPLE | LIST ' |
| |
| `CONST ==>' |
| `C-STRING' |
| |
| `TUPLE ==>' |
| ` "{}" | "{" RESULT ( "," RESULT )* "}" ' |
| |
| `LIST ==>' |
| ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* |
| "]" ' |
| |
| `STREAM-RECORD ==>' |
| `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' |
| |
| `CONSOLE-STREAM-OUTPUT ==>' |
| `"~" C-STRING' |
| |
| `TARGET-STREAM-OUTPUT ==>' |
| `"@" C-STRING' |
| |
| `LOG-STREAM-OUTPUT ==>' |
| `"&" C-STRING' |
| |
| `NL ==>' |
| `CR | CR-LF' |
| |
| `TOKEN ==>' |
| _any sequence of digits_. |
| |
| Notes: |
| |
| * All output sequences end in a single line containing a period. |
| |
| * The `TOKEN' is from the corresponding request. Note that for all |
| async output, while the token is allowed by the grammar and may be |
| output by future versions of GDB for select async output messages, |
| it is generally omitted. Frontends should treat all async output |
| as reporting general changes in the state of the target and there |
| should be no need to associate async output to any prior command. |
| |
| * STATUS-ASYNC-OUTPUT contains on-going status information about the |
| progress of a slow operation. It can be discarded. All status |
| output is prefixed by `+'. |
| |
| * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target |
| (stopped, started, disappeared). All async output is prefixed by |
| `*'. |
| |
| * NOTIFY-ASYNC-OUTPUT contains supplementary information that the |
| client should handle (e.g., a new breakpoint information). All |
| notify output is prefixed by `='. |
| |
| * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in |
| the console. It is the textual response to a CLI command. All |
| the console output is prefixed by `~'. |
| |
| * TARGET-STREAM-OUTPUT is the output produced by the target program. |
| All the target output is prefixed by `@'. |
| |
| * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for |
| instance messages that should be displayed as part of an error |
| log. All the log output is prefixed by `&'. |
| |
| * New GDB/MI commands should only output LISTS containing VALUES. |
| |
| |
| *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details |
| about the various output records. |
| |
| |
| File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI |
| |
| 27.3 GDB/MI Compatibility with CLI |
| ================================== |
| |
| For the developers convenience CLI commands can be entered directly, |
| but there may be some unexpected behaviour. For example, commands that |
| query the user will behave as if the user replied yes, breakpoint |
| command lists are not executed and some CLI commands, such as `if', |
| `when' and `define', prompt for further input with `>', which is not |
| valid MI output. |
| |
| This feature may be removed at some stage in the future and it is |
| recommended that front ends use the `-interpreter-exec' command (*note |
| -interpreter-exec::). |
| |
| |
| File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI |
| |
| 27.4 GDB/MI Development and Front Ends |
| ====================================== |
| |
| The application which takes the MI output and presents the state of the |
| program being debugged to the user is called a "front end". |
| |
| Although GDB/MI is still incomplete, it is currently being used by a |
| variety of front ends to GDB. This makes it difficult to introduce new |
| functionality without breaking existing usage. This section tries to |
| minimize the problems by describing how the protocol might change. |
| |
| Some changes in MI need not break a carefully designed front end, and |
| for these the MI version will remain unchanged. The following is a |
| list of changes that may occur within one level, so front ends should |
| parse MI output in a way that can handle them: |
| |
| * New MI commands may be added. |
| |
| * New fields may be added to the output of any MI command. |
| |
| * The range of values for fields with specified values, e.g., |
| `in_scope' (*note -var-update::) may be extended. |
| |
| |
| If the changes are likely to break front ends, the MI version level |
| will be increased by one. This will allow the front end to parse the |
| output according to the MI version. Apart from mi0, new versions of |
| GDB will not support old versions of MI and it will be the |
| responsibility of the front end to work with the new one. |
| |
| The best way to avoid unexpected changes in MI that might break your |
| front end is to make your project known to GDB developers and follow |
| development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>. |
| |
| |
| File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI |
| |
| 27.5 GDB/MI Output Records |
| ========================== |
| |
| * Menu: |
| |
| * GDB/MI Result Records:: |
| * GDB/MI Stream Records:: |
| * GDB/MI Async Records:: |
| * GDB/MI Frame Information:: |
| * GDB/MI Thread Information:: |
| |
| |
| File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 27.5.1 GDB/MI Result Records |
| ---------------------------- |
| |
| In addition to a number of out-of-band notifications, the response to a |
| GDB/MI command includes one of the following result indications: |
| |
| `"^done" [ "," RESULTS ]' |
| The synchronous operation was successful, `RESULTS' are the return |
| values. |
| |
| `"^running"' |
| This result record is equivalent to `^done'. Historically, it was |
| output instead of `^done' if the command has resumed the target. |
| This behaviour is maintained for backward compatibility, but all |
| frontends should treat `^done' and `^running' identically and rely |
| on the `*running' output record to determine which threads are |
| resumed. |
| |
| `"^connected"' |
| GDB has connected to a remote target. |
| |
| `"^error" "," C-STRING' |
| The operation failed. The `C-STRING' contains the corresponding |
| error message. |
| |
| `"^exit"' |
| GDB has terminated. |
| |
| |
| |
| File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records |
| |
| 27.5.2 GDB/MI Stream Records |
| ---------------------------- |
| |
| GDB internally maintains a number of output streams: the console, the |
| target, and the log. The output intended for each of these streams is |
| funneled through the GDB/MI interface using "stream records". |
| |
| Each stream record begins with a unique "prefix character" which |
| identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output |
| Syntax.). In addition to the prefix, each stream record contains a |
| `STRING-OUTPUT'. This is either raw text (with an implicit new line) |
| or a quoted C string (which does not contain an implicit newline). |
| |
| `"~" STRING-OUTPUT' |
| The console output stream contains text that should be displayed |
| in the CLI console window. It contains the textual responses to |
| CLI commands. |
| |
| `"@" STRING-OUTPUT' |
| The target output stream contains any textual output from the |
| running target. This is only present when GDB's event loop is |
| truly asynchronous, which is currently only the case for remote |
| targets. |
| |
| `"&" STRING-OUTPUT' |
| The log stream contains debugging messages being produced by GDB's |
| internals. |
| |
| |
| File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 27.5.3 GDB/MI Async Records |
| --------------------------- |
| |
| "Async" records are used to notify the GDB/MI client of additional |
| changes that have occurred. Those changes can either be a consequence |
| of GDB/MI commands (e.g., a breakpoint modified) or a result of target |
| activity (e.g., target stopped). |
| |
| The following is the list of possible async records: |
| |
| `*running,thread-id="THREAD"' |
| The target is now running. The THREAD field tells which specific |
| thread is now running, and can be `all' if all threads are |
| running. The frontend should assume that no interaction with a |
| running thread is possible after this notification is produced. |
| The frontend should not assume that this notification is output |
| only once for any command. GDB may emit this notification several |
| times, either for different threads, because it cannot resume all |
| threads together, or even for a single thread, if the thread must |
| be stepped though some code before letting it run freely. |
| |
| `*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' |
| The target has stopped. The REASON field can have one of the |
| following values: |
| |
| `breakpoint-hit' |
| A breakpoint was reached. |
| |
| `watchpoint-trigger' |
| A watchpoint was triggered. |
| |
| `read-watchpoint-trigger' |
| A read watchpoint was triggered. |
| |
| `access-watchpoint-trigger' |
| An access watchpoint was triggered. |
| |
| `function-finished' |
| An -exec-finish or similar CLI command was accomplished. |
| |
| `location-reached' |
| An -exec-until or similar CLI command was accomplished. |
| |
| `watchpoint-scope' |
| A watchpoint has gone out of scope. |
| |
| `end-stepping-range' |
| An -exec-next, -exec-next-instruction, -exec-step, |
| -exec-step-instruction or similar CLI command was |
| accomplished. |
| |
| `exited-signalled' |
| The inferior exited because of a signal. |
| |
| `exited' |
| The inferior exited. |
| |
| `exited-normally' |
| The inferior exited normally. |
| |
| `signal-received' |
| A signal was received by the inferior. |
| |
| The ID field identifies the thread that directly caused the stop - |
| for example by hitting a breakpoint. Depending on whether all-stop |
| mode is in effect (*note All-Stop Mode::), GDB may either stop all |
| threads, or only the thread that directly triggered the stop. If |
| all threads are stopped, the STOPPED field will have the value of |
| `"all"'. Otherwise, the value of the STOPPED field will be a list |
| of thread identifiers. Presently, this list will always include a |
| single thread, but frontend should be prepared to see several |
| threads in the list. The CORE field reports the processor core on |
| which the stop event has happened. This field may be absent if |
| such information is not available. |
| |
| `=thread-group-added,id="ID"' |
| `=thread-group-removed,id="ID"' |
| A thread group was either added or removed. The ID field contains |
| the GDB identifier of the thread group. When a thread group is |
| added, it generally might not be associated with a running |
| process. When a thread group is removed, its id becomes invalid |
| and cannot be used in any way. |
| |
| `=thread-group-started,id="ID",pid="PID"' |
| A thread group became associated with a running program, either |
| because the program was just started or the thread group was |
| attached to a program. The ID field contains the GDB identifier |
| of the thread group. The PID field contains process identifier, |
| specific to the operating system. |
| |
| `=thread-group-exited,id="ID"' |
| A thread group is no longer associated with a running program, |
| either because the program has exited, or because it was detached |
| from. The ID field contains the GDB identifier of the thread |
| group. |
| |
| `=thread-created,id="ID",group-id="GID"' |
| `=thread-exited,id="ID",group-id="GID"' |
| A thread either was created, or has exited. The ID field contains |
| the GDB identifier of the thread. The GID field identifies the |
| thread group this thread belongs to. |
| |
| `=thread-selected,id="ID"' |
| Informs that the selected thread was changed as result of the last |
| command. This notification is not emitted as result of |
| `-thread-select' command but is emitted whenever an MI command |
| that is not documented to change the selected thread actually |
| changes it. In particular, invoking, directly or indirectly (via |
| user-defined command), the CLI `thread' command, will generate |
| this notification. |
| |
| We suggest that in response to this notification, front ends |
| highlight the selected thread and cause subsequent commands to |
| apply to that thread. |
| |
| `=library-loaded,...' |
| Reports that a new library file was loaded by the program. This |
| notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and |
| SYMBOLS-LOADED. The ID field is an opaque identifier of the |
| library. For remote debugging case, TARGET-NAME and HOST-NAME |
| fields give the name of the library file on the target, and on the |
| host respectively. For native debugging, both those fields have |
| the same value. The SYMBOLS-LOADED field reports if the debug |
| symbols for this library are loaded. The THREAD-GROUP field, if |
| present, specifies the id of the thread group in whose context the |
| library was loaded. If the field is absent, it means the library |
| was loaded in the context of all present thread groups. |
| |
| `=library-unloaded,...' |
| Reports that a library was unloaded by the program. This |
| notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the |
| same meaning as for the `=library-loaded' notification. The |
| THREAD-GROUP field, if present, specifies the id of the thread |
| group in whose context the library was unloaded. If the field is |
| absent, it means the library was unloaded in the context of all |
| present thread groups. |
| |
| |
| |
| File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records |
| |
| 27.5.4 GDB/MI Frame Information |
| ------------------------------- |
| |
| Response from many MI commands includes an information about stack |
| frame. This information is a tuple that may have the following fields: |
| |
| `level' |
| The level of the stack frame. The innermost frame has the level of |
| zero. This field is always present. |
| |
| `func' |
| The name of the function corresponding to the frame. This field |
| may be absent if GDB is unable to determine the function name. |
| |
| `addr' |
| The code address for the frame. This field is always present. |
| |
| `file' |
| The name of the source files that correspond to the frame's code |
| address. This field may be absent. |
| |
| `line' |
| The source line corresponding to the frames' code address. This |
| field may be absent. |
| |
| `from' |
| The name of the binary file (either executable or shared library) |
| the corresponds to the frame's code address. This field may be |
| absent. |
| |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records |
| |
| 27.5.5 GDB/MI Thread Information |
| -------------------------------- |
| |
| Whenever GDB has to report an information about a thread, it uses a |
| tuple with the following fields: |
| |
| `id' |
| The numeric id assigned to the thread by GDB. This field is |
| always present. |
| |
| `target-id' |
| Target-specific string identifying the thread. This field is |
| always present. |
| |
| `details' |
| Additional information about the thread provided by the target. |
| It is supposed to be human-readable and not interpreted by the |
| frontend. This field is optional. |
| |
| `state' |
| Either `stopped' or `running', depending on whether the thread is |
| presently running. This field is always present. |
| |
| `core' |
| The value of this field is an integer number of the processor core |
| the thread was last seen on. This field is optional. |
| |
| |
| File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI |
| |
| 27.6 Simple Examples of GDB/MI Interaction |
| ========================================== |
| |
| This subsection presents several simple examples of interaction using |
| the GDB/MI interface. In these examples, `->' means that the following |
| line is passed to GDB/MI as input, while `<-' means the output received |
| from GDB/MI. |
| |
| Note the line breaks shown in the examples are here only for |
| readability, they don't appear in the real output. |
| |
| Setting a Breakpoint |
| -------------------- |
| |
| Setting a breakpoint generates synchronous output which contains |
| detailed information of the breakpoint. |
| |
| -> -break-insert main |
| <- ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x08048564",func="main",file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="68",times="0"} |
| <- (gdb) |
| |
| Program Execution |
| ----------------- |
| |
| Program execution generates asynchronous records and MI gives the |
| reason that execution stopped. |
| |
| -> -exec-run |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", |
| frame={addr="0x08048564",func="main", |
| args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], |
| file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} |
| <- (gdb) |
| -> -exec-continue |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="exited-normally" |
| <- (gdb) |
| |
| Quitting GDB |
| ------------ |
| |
| Quitting GDB just prints the result class `^exit'. |
| |
| -> (gdb) |
| <- -gdb-exit |
| <- ^exit |
| |
| Please note that `^exit' is printed immediately, but it might take |
| some time for GDB to actually exit. During that time, GDB performs |
| necessary cleanups, including killing programs being debugged or |
| disconnecting from debug hardware, so the frontend should wait till GDB |
| exits and should only forcibly kill GDB if it fails to exit in |
| reasonable time. |
| |
| A Bad Command |
| ------------- |
| |
| Here's what happens if you pass a non-existent command: |
| |
| -> -rubbish |
| <- ^error,msg="Undefined MI command: rubbish" |
| <- (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI |
| |
| 27.7 GDB/MI Command Description Format |
| ====================================== |
| |
| The remaining sections describe blocks of commands. Each block of |
| commands is laid out in a fashion similar to this section. |
| |
| Motivation |
| ---------- |
| |
| The motivation for this collection of commands. |
| |
| Introduction |
| ------------ |
| |
| A brief introduction to this collection of commands as a whole. |
| |
| Commands |
| -------- |
| |
| For each command in the block, the following is described: |
| |
| Synopsis |
| ........ |
| |
| -command ARGS... |
| |
| Result |
| ...... |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB CLI command(s), if any. |
| |
| Example |
| ....... |
| |
| Example(s) formatted for readability. Some of the described commands |
| have not been implemented yet and these are labeled N.A. (not |
| available). |
| |
| |
| File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI |
| |
| 27.8 GDB/MI Breakpoint Commands |
| =============================== |
| |
| This section documents GDB/MI commands for manipulating breakpoints. |
| |
| The `-break-after' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-after NUMBER COUNT |
| |
| The breakpoint number NUMBER is not in effect until it has been hit |
| COUNT times. To see how this is reflected in the output of the |
| `-break-list' command, see the description of the `-break-list' command |
| below. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `ignore'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x000100d0",func="main",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",times="0"} |
| (gdb) |
| -break-after 1 3 |
| ~ |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0",ignore="3"}]} |
| (gdb) |
| |
| The `-break-commands' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-commands NUMBER [ COMMAND1 ... COMMANDN ] |
| |
| Specifies the CLI commands that should be executed when breakpoint |
| NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. |
| If no command is specified, any previously-set commands are cleared. |
| *Note Break Commands::. Typical use of this functionality is tracing a |
| program, that is, printing of values of some variables whenever |
| breakpoint is hit and then continuing. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `commands'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x000100d0",func="main",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",times="0"} |
| (gdb) |
| -break-commands 1 "print v" "continue" |
| ^done |
| (gdb) |
| |
| The `-break-condition' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-condition NUMBER EXPR |
| |
| Breakpoint NUMBER will stop the program only if the condition in |
| EXPR is true. The condition becomes part of the `-break-list' output |
| (see the description of the `-break-list' command below). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `condition'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-condition 1 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",cond="1",times="0",ignore="3"}]} |
| (gdb) |
| |
| The `-break-delete' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-delete ( BREAKPOINT )+ |
| |
| Delete the breakpoint(s) whose number(s) are specified in the |
| argument list. This is obviously reflected in the breakpoint list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `delete'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-delete 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The `-break-disable' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-disable ( BREAKPOINT )+ |
| |
| Disable the named BREAKPOINT(s). The field `enabled' in the break |
| list is now set to `n' for the named BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `disable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-disable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0"}]} |
| (gdb) |
| |
| The `-break-enable' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-enable ( BREAKPOINT )+ |
| |
| Enable (previously disabled) BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `enable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-enable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0"}]} |
| (gdb) |
| |
| The `-break-info' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-info BREAKPOINT |
| |
| Get information about a single breakpoint. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info break BREAKPOINT'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-break-insert' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] |
| [ -c CONDITION ] [ -i IGNORE-COUNT ] |
| [ -p THREAD ] [ LOCATION ] |
| |
| If specified, LOCATION, can be one of: |
| |
| * function |
| |
| * filename:linenum |
| |
| * filename:function |
| |
| * *address |
| |
| The possible optional parameters of this command are: |
| |
| `-t' |
| Insert a temporary breakpoint. |
| |
| `-h' |
| Insert a hardware breakpoint. |
| |
| `-c CONDITION' |
| Make the breakpoint conditional on CONDITION. |
| |
| `-i IGNORE-COUNT' |
| Initialize the IGNORE-COUNT. |
| |
| `-f' |
| If LOCATION cannot be parsed (for example if it refers to unknown |
| files or functions), create a pending breakpoint. Without this |
| flag, GDB will report an error, and won't create a breakpoint, if |
| LOCATION cannot be parsed. |
| |
| `-d' |
| Create a disabled breakpoint. |
| |
| `-a' |
| Create a tracepoint. *Note Tracepoints::. When this parameter is |
| used together with `-h', a fast tracepoint is created. |
| |
| Result |
| ...... |
| |
| The result is in the form: |
| |
| ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", |
| enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", |
| fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] |
| times="TIMES"} |
| |
| where NUMBER is the GDB number for this breakpoint, FUNCNAME is the |
| name of the function where the breakpoint was inserted, FILENAME is the |
| name of the source file which contains this function, LINENO is the |
| source line number within that file and TIMES the number of times that |
| the breakpoint has been hit (always 0 for -break-insert but may be |
| greater for -break-info or -break-list which use the same output). |
| |
| Note: this format is open to change. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `break', `tbreak', `hbreak', |
| `thbreak', and `rbreak'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="4",times="0"} |
| (gdb) |
| -break-insert -t foo |
| ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="11",times="0"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x0001072c", func="main",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,"line="4",times="0"}, |
| bkpt={number="2",type="breakpoint",disp="del",enabled="y", |
| addr="0x00010774",func="foo",file="recursive2.c", |
| fullname="/home/foo/recursive2.c",line="11",times="0"}]} |
| (gdb) |
| -break-insert -r foo.* |
| ~int foo(int, int); |
| ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, |
| "fullname="/home/foo/recursive2.c",line="11",times="0"} |
| (gdb) |
| |
| The `-break-list' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-list |
| |
| Displays the list of inserted breakpoints, showing the following |
| fields: |
| |
| `Number' |
| number of the breakpoint |
| |
| `Type' |
| type of the breakpoint: `breakpoint' or `watchpoint' |
| |
| `Disposition' |
| should the breakpoint be deleted or disabled when it is hit: `keep' |
| or `nokeep' |
| |
| `Enabled' |
| is the breakpoint enabled or no: `y' or `n' |
| |
| `Address' |
| memory location at which the breakpoint is set |
| |
| `What' |
| logical location of the breakpoint, expressed by function name, |
| file name, line number |
| |
| `Times' |
| number of times the breakpoint has been hit |
| |
| If there are no breakpoints or watchpoints, the `BreakpointTable' |
| `body' field is an empty list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info break'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, |
| bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", |
| line="13",times="0"}]} |
| (gdb) |
| |
| Here's an example of the result when there are no breakpoints: |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The `-break-passcount' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-passcount TRACEPOINT-NUMBER PASSCOUNT |
| |
| Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If |
| the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, |
| error is emitted. This corresponds to CLI command `passcount'. |
| |
| The `-break-watch' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-watch [ -a | -r ] |
| |
| Create a watchpoint. With the `-a' option it will create an |
| "access" watchpoint, i.e., a watchpoint that triggers either on a read |
| from or on a write to the memory location. With the `-r' option, the |
| watchpoint created is a "read" watchpoint, i.e., it will trigger only |
| when the memory location is accessed for reading. Without either of |
| the options, the watchpoint created is a regular watchpoint, i.e., it |
| will trigger when the memory location is accessed for writing. *Note |
| Setting Watchpoints: Set Watchpoints. |
| |
| Note that `-break-list' will report a single list of watchpoints and |
| breakpoints inserted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `watch', `awatch', and `rwatch'. |
| |
| Example |
| ....... |
| |
| Setting a watchpoint on a variable in the `main' function: |
| |
| (gdb) |
| -break-watch x |
| ^done,wpt={number="2",exp="x"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, |
| value={old="-268439212",new="55"}, |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="5"} |
| (gdb) |
| |
| Setting a watchpoint on a variable local to a function. GDB will |
| stop the program execution twice: first for the variable changing |
| value, then for the watchpoint going out of scope. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="5",exp="C"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger", |
| wpt={number="5",exp="C"},value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-scope",wpnum="5", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| |
| Listing breakpoints and watchpoints, at different points in the |
| program execution. Note that once the watchpoint goes out of scope, it |
| is deleted. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="2",exp="C"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",times="0"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, |
| value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",times="-5"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-scope",wpnum="2", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", |
| times="1"}]} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI |
| |
| 27.9 GDB/MI Program Context |
| ============================ |
| |
| The `-exec-arguments' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-arguments ARGS |
| |
| Set the inferior program arguments, to be used in the next |
| `-exec-run'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `set args'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-arguments -v word |
| ^done |
| (gdb) |
| |
| The `-environment-cd' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-cd PATHDIR |
| |
| Set GDB's working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `cd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done |
| (gdb) |
| |
| The `-environment-directory' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-directory [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for source files. |
| If the `-r' option is used, the search path is reset to the default |
| search path. If directories PATHDIR are supplied in addition to the |
| `-r' option, the search path is first reset and then addition occurs as |
| normal. Multiple directories may be specified, separated by blanks. |
| Specifying multiple directories in a single command results in the |
| directories added to the beginning of the search path in the same order |
| they were presented in the command. If blanks are needed as part of a |
| directory name, double-quotes should be used around the name. In the |
| command output, the path will show up separated by the system |
| directory-separator character. The directory-separator character must |
| not be used in any directory name. If no directories are specified, |
| the current search path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `dir'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory "" |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r /home/jjohnstn/src/gdb /usr/src |
| ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r |
| ^done,source-path="$cdir:$cwd" |
| (gdb) |
| |
| The `-environment-path' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-path [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for object files. |
| If the `-r' option is used, the search path is reset to the original |
| search path that existed at gdb start-up. If directories PATHDIR are |
| supplied in addition to the `-r' option, the search path is first reset |
| and then addition occurs as normal. Multiple directories may be |
| specified, separated by blanks. Specifying multiple directories in a |
| single command results in the directories added to the beginning of the |
| search path in the same order they were presented in the command. If |
| blanks are needed as part of a directory name, double-quotes should be |
| used around the name. In the command output, the path will show up |
| separated by the system directory-separator character. The |
| directory-separator character must not be used in any directory name. |
| If no directories are specified, the current path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `path'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-path |
| ^done,path="/usr/bin" |
| (gdb) |
| -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin |
| ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" |
| (gdb) |
| -environment-path -r /usr/local/bin |
| ^done,path="/usr/local/bin:/usr/bin" |
| (gdb) |
| |
| The `-environment-pwd' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-pwd |
| |
| Show the current working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `pwd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-pwd |
| ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI |
| |
| 27.10 GDB/MI Thread Commands |
| ============================ |
| |
| The `-thread-info' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-info [ THREAD-ID ] |
| |
| Reports information about either a specific thread, if the THREAD-ID |
| parameter is present, or about all threads. When printing information |
| about all threads, also reports the current thread. |
| |
| GDB Command |
| ........... |
| |
| The `info thread' command prints the same information about all threads. |
| |
| Example |
| ....... |
| |
| -thread-info |
| ^done,threads=[ |
| {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", |
| frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, |
| {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", |
| frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], |
| file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}], |
| current-thread-id="1" |
| (gdb) |
| |
| The `state' field may have the following values: |
| |
| `stopped' |
| The thread is stopped. Frame information is available for stopped |
| threads. |
| |
| `running' |
| The thread is running. There's no frame information for running |
| threads. |
| |
| |
| The `-thread-list-ids' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -thread-list-ids |
| |
| Produces a list of the currently known GDB thread ids. At the end |
| of the list it also prints the total number of such threads. |
| |
| This command is retained for historical reasons, the `-thread-info' |
| command should be used instead. |
| |
| GDB Command |
| ........... |
| |
| Part of `info threads' supplies the same information. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| current-thread-id="1",number-of-threads="3" |
| (gdb) |
| |
| The `-thread-select' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-select THREADNUM |
| |
| Make THREADNUM the current thread. It prints the number of the new |
| current thread, and the topmost frame for that thread. |
| |
| This command is deprecated in favor of explicitly using the |
| `--thread' option to each command. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `thread'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",thread-id="2",line="187", |
| file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" |
| (gdb) |
| -thread-list-ids |
| ^done, |
| thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| number-of-threads="3" |
| (gdb) |
| -thread-select 3 |
| ^done,new-thread-id="3", |
| frame={level="0",func="vprintf", |
| args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, |
| {name="arg",value="0x2"}],file="vprintf.c",line="31"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI |
| |
| 27.11 GDB/MI Program Execution |
| ============================== |
| |
| These are the asynchronous commands which generate the out-of-band |
| record `*stopped'. Currently GDB only really executes asynchronously |
| with remote targets and this interaction is mimicked in other cases. |
| |
| The `-exec-continue' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-continue [--reverse] [--all|--thread-group N] |
| |
| Resumes the execution of the inferior program, which will continue |
| to execute until it reaches a debugger stop event. If the `--reverse' |
| option is specified, execution resumes in reverse until it reaches a |
| stop event. Stop events may include |
| * breakpoints or watchpoints |
| |
| * signals or exceptions |
| |
| * the end of the process (or its beginning under `--reverse') |
| |
| * the end or beginning of a replay log if one is being used. |
| In all-stop mode (*note All-Stop Mode::), may resume only one |
| thread, or all threads, depending on the value of the |
| `scheduler-locking' variable. If `--all' is specified, all threads (in |
| all inferiors) will be resumed. The `--all' option is ignored in |
| all-stop mode. If the `--thread-group' options is specified, then all |
| threads in that thread group are resumed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB corresponding is `continue'. |
| |
| Example |
| ....... |
| |
| -exec-continue |
| ^running |
| (gdb) |
| @Hello world |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ |
| func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", |
| line="13"} |
| (gdb) |
| |
| The `-exec-finish' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-finish [--reverse] |
| |
| Resumes the execution of the inferior program until the current |
| function is exited. Displays the results returned by the function. If |
| the `--reverse' option is specified, resumes the reverse execution of |
| the inferior program until the point where current function was called. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `finish'. |
| |
| Example |
| ....... |
| |
| Function returning `void'. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| @hello from foo |
| *stopped,reason="function-finished",frame={func="main",args=[], |
| file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} |
| (gdb) |
| |
| Function returning other than `void'. The name of the internal GDB |
| variable storing the result is printed, together with the value itself. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", |
| args=[{name="a",value="1"],{name="b",value="9"}}, |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| gdb-result-var="$1",return-value="0" |
| (gdb) |
| |
| The `-exec-interrupt' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-interrupt [--all|--thread-group N] |
| |
| Interrupts the background execution of the target. Note how the |
| token associated with the stop message is the one for the execution |
| command that has been interrupted. The token for the interrupt itself |
| only appears in the `^done' output. If the user is trying to interrupt |
| a non-running program, an error message will be printed. |
| |
| Note that when asynchronous execution is enabled, this command is |
| asynchronous just like other execution commands. That is, first the |
| `^done' response will be printed, and the target stop will be reported |
| after that using the `*stopped' notification. |
| |
| In non-stop mode, only the context thread is interrupted by default. |
| All threads (in all inferiors) will be interrupted if the `--all' |
| option is specified. If the `--thread-group' option is specified, all |
| threads in that group will be interrupted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `interrupt'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 111-exec-continue |
| 111^running |
| |
| (gdb) |
| 222-exec-interrupt |
| 222^done |
| (gdb) |
| 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", |
| frame={addr="0x00010140",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="13"} |
| (gdb) |
| |
| (gdb) |
| -exec-interrupt |
| ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." |
| (gdb) |
| |
| The `-exec-jump' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-jump LOCATION |
| |
| Resumes execution of the inferior program at the location specified |
| by parameter. *Note Specify Location::, for a description of the |
| different forms of LOCATION. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `jump'. |
| |
| Example |
| ....... |
| |
| -exec-jump foo.c:10 |
| *running,thread-id="all" |
| ^running |
| |
| The `-exec-next' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next [--reverse] |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached. |
| |
| If the `--reverse' option is specified, resumes reverse execution of |
| the inferior program, stopping at the beginning of the previous source |
| line. If you issue this command on the first line of a function, it |
| will take you back to the caller of that function, to the source line |
| where the function was called. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `next'. |
| |
| Example |
| ....... |
| |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="8",file="hello.c" |
| (gdb) |
| |
| The `-exec-next-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next-instruction [--reverse] |
| |
| Executes one machine instruction. If the instruction is a function |
| call, continues until the function returns. If the program stops at an |
| instruction in the middle of a source line, the address will be printed |
| as well. |
| |
| If the `--reverse' option is specified, resumes reverse execution of |
| the inferior program, stopping at the previous instruction. If the |
| previously executed instruction was a return from another function, it |
| will continue to execute in reverse until the call to that function |
| (from the current stack frame) is reached. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `nexti'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| addr="0x000100d4",line="5",file="hello.c" |
| (gdb) |
| |
| The `-exec-return' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-return |
| |
| Makes current function return immediately. Doesn't execute the |
| inferior. Displays the new current frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `return'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 200-break-insert callee4 |
| 200^done,bkpt={number="1",addr="0x00010734", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 000-exec-run |
| 000^running |
| (gdb) |
| 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 205-break-delete |
| 205^done |
| (gdb) |
| 111-exec-return |
| 111^done,frame={level="0",func="callee3", |
| args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| |
| The `-exec-run' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-run [--all | --thread-group N] |
| |
| Starts execution of the inferior from the beginning. The inferior |
| executes until either a breakpoint is encountered or the program exits. |
| In the latter case the output will include an exit code, if the |
| program has exited exceptionally. |
| |
| When no option is specified, the current inferior is started. If the |
| `--thread-group' option is specified, it should refer to a thread group |
| of type `process', and that thread group will be started. If the |
| `--all' option is specified, then all inferiors will be started. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `run'. |
| |
| Examples |
| ........ |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="4"} |
| (gdb) |
| |
| Program exited normally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited-normally" |
| (gdb) |
| |
| Program exited exceptionally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited",exit-code="01" |
| (gdb) |
| |
| Another way the program can terminate is if it receives a signal |
| such as `SIGINT'. In this case, GDB/MI displays this: |
| |
| (gdb) |
| *stopped,reason="exited-signalled",signal-name="SIGINT", |
| signal-meaning="Interrupt" |
| |
| The `-exec-step' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step [--reverse] |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached, if the next source line |
| is not a function call. If it is, stop at the first instruction of the |
| called function. If the `--reverse' option is specified, resumes |
| reverse execution of the inferior program, stopping at the beginning of |
| the previously executed source line. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `step'. |
| |
| Example |
| ....... |
| |
| Stepping into a function: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[{name="a",value="10"}, |
| {name="b",value="0"}],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="11"} |
| (gdb) |
| |
| Regular stepping: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="14",file="recursive2.c" |
| (gdb) |
| |
| The `-exec-step-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step-instruction [--reverse] |
| |
| Resumes the inferior which executes one machine instruction. If the |
| `--reverse' option is specified, resumes reverse execution of the |
| inferior program, stopping at the previously executed instruction. The |
| output, once GDB has stopped, will vary depending on whether we have |
| stopped in the middle of a source line or not. In the former case, the |
| address at which the program stopped will be printed as well. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `stepi'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10"} |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={addr="0x000100f4",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10"} |
| (gdb) |
| |
| The `-exec-until' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-until [ LOCATION ] |
| |
| Executes the inferior until the LOCATION specified in the argument |
| is reached. If there is no argument, the inferior executes until a |
| source line greater than the current one is reached. The reason for |
| stopping in this case will be `location-reached'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `until'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-until recursive2.c:6 |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="location-reached",frame={func="main",args=[], |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI |
| |
| 27.12 GDB/MI Stack Manipulation Commands |
| ======================================== |
| |
| The `-stack-info-frame' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-frame |
| |
| Get info on the selected frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info frame' or `frame' (without |
| arguments). |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-info-frame |
| ^done,frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} |
| (gdb) |
| |
| The `-stack-info-depth' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-depth [ MAX-DEPTH ] |
| |
| Return the depth of the stack. If the integer argument MAX-DEPTH is |
| specified, do not count beyond MAX-DEPTH frames. |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. |
| |
| Example |
| ....... |
| |
| For a stack with frame levels 0 through 11: |
| |
| (gdb) |
| -stack-info-depth |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 4 |
| ^done,depth="4" |
| (gdb) |
| -stack-info-depth 12 |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 11 |
| ^done,depth="11" |
| (gdb) |
| -stack-info-depth 13 |
| ^done,depth="12" |
| (gdb) |
| |
| The `-stack-list-arguments' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-arguments PRINT-VALUES |
| [ LOW-FRAME HIGH-FRAME ] |
| |
| Display a list of the arguments for the frames between LOW-FRAME and |
| HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, |
| list the arguments for the whole call stack. If the two arguments are |
| equal, show the single frame at the corresponding level. It is an |
| error if LOW-FRAME is larger than the actual number of frames. On the |
| other hand, HIGH-FRAME may be larger than the actual number of frames, |
| in which case only existing frames will be returned. |
| |
| If PRINT-VALUES is 0 or `--no-values', print only the names of the |
| variables; if it is 1 or `--all-values', print also their values; and |
| if it is 2 or `--simple-values', print the name, type and value for |
| simple data types, and the name and type for arrays, structures and |
| unions. |
| |
| Use of this command to obtain arguments in a single frame is |
| deprecated in favor of the `-stack-list-variables' command. |
| |
| GDB Command |
| ........... |
| |
| GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' |
| command which partially overlaps with the functionality of |
| `-stack-list-arguments'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-frames |
| ^done, |
| stack=[ |
| frame={level="0",addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, |
| frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, |
| frame={level="2",addr="0x0001078c",func="callee2", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, |
| frame={level="3",addr="0x000107b4",func="callee1", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, |
| frame={level="4",addr="0x000107e0",func="main", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] |
| (gdb) |
| -stack-list-arguments 0 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1",args=[name="strarg"]}, |
| frame={level="2",args=[name="intarg",name="strarg"]}, |
| frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 1 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1", |
| args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, |
| frame={level="2",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}, |
| {frame={level="3",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}, |
| {name="fltarg",value="3.5"}]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 0 2 2 |
| ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] |
| (gdb) |
| -stack-list-arguments 1 2 2 |
| ^done,stack-args=[frame={level="2", |
| args=[{name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}] |
| (gdb) |
| |
| The `-stack-list-frames' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-frames [ LOW-FRAME HIGH-FRAME ] |
| |
| List the frames currently on the stack. For each frame it displays |
| the following info: |
| |
| `LEVEL' |
| The frame number, 0 being the topmost frame, i.e., the innermost |
| function. |
| |
| `ADDR' |
| The `$pc' value for that frame. |
| |
| `FUNC' |
| Function name. |
| |
| `FILE' |
| File name of the source file where the function lives. |
| |
| `LINE' |
| Line number corresponding to the `$pc'. |
| |
| If invoked without arguments, this command prints a backtrace for the |
| whole stack. If given two integer arguments, it shows the frames whose |
| levels are between the two arguments (inclusive). If the two arguments |
| are equal, it shows the single frame at the corresponding level. It is |
| an error if LOW-FRAME is larger than the actual number of frames. On |
| the other hand, HIGH-FRAME may be larger than the actual number of |
| frames, in which case only existing frames will be returned. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `backtrace' and `where'. |
| |
| Example |
| ....... |
| |
| Full stack backtrace: |
| |
| (gdb) |
| -stack-list-frames |
| ^done,stack= |
| [frame={level="0",addr="0x0001076c",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, |
| frame={level="1",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="2",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="6",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="7",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="8",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="9",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="10",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="11",addr="0x00010738",func="main", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] |
| (gdb) |
| |
| Show frames between LOW_FRAME and HIGH_FRAME: |
| |
| (gdb) |
| -stack-list-frames 3 5 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] |
| (gdb) |
| |
| Show a single frame: |
| |
| (gdb) |
| -stack-list-frames 3 3 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] |
| (gdb) |
| |
| The `-stack-list-locals' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-locals PRINT-VALUES |
| |
| Display the local variable names for the selected frame. If |
| PRINT-VALUES is 0 or `--no-values', print only the names of the |
| variables; if it is 1 or `--all-values', print also their values; and |
| if it is 2 or `--simple-values', print the name, type and value for |
| simple data types, and the name and type for arrays, structures and |
| unions. In this last case, a frontend can immediately display the |
| value of simple data types and create variable objects for other data |
| types when the user wishes to explore their values in more detail. |
| |
| This command is deprecated in favor of the `-stack-list-variables' |
| command. |
| |
| GDB Command |
| ........... |
| |
| `info locals' in GDB, `gdb_get_locals' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-locals 0 |
| ^done,locals=[name="A",name="B",name="C"] |
| (gdb) |
| -stack-list-locals --all-values |
| ^done,locals=[{name="A",value="1"},{name="B",value="2"}, |
| {name="C",value="{1, 2, 3}"}] |
| -stack-list-locals --simple-values |
| ^done,locals=[{name="A",type="int",value="1"}, |
| {name="B",type="int",value="2"},{name="C",type="int [3]"}] |
| (gdb) |
| |
| The `-stack-list-variables' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-variables PRINT-VALUES |
| |
| Display the names of local variables and function arguments for the |
| selected frame. If PRINT-VALUES is 0 or `--no-values', print only the |
| names of the variables; if it is 1 or `--all-values', print also their |
| values; and if it is 2 or `--simple-values', print the name, type and |
| value for simple data types, and the name and type for arrays, |
| structures and unions. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-variables --thread 1 --frame 0 --all-values |
| ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] |
| (gdb) |
| |
| The `-stack-select-frame' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-select-frame FRAMENUM |
| |
| Change the selected frame. Select a different frame FRAMENUM on the |
| stack. |
| |
| This command in deprecated in favor of passing the `--frame' option |
| to every command. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `frame', `up', `down', |
| `select-frame', `up-silent', and `down-silent'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-select-frame 2 |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI |
| |
| 27.13 GDB/MI Variable Objects |
| ============================= |
| |
| Introduction to Variable Objects |
| -------------------------------- |
| |
| Variable objects are "object-oriented" MI interface for examining and |
| changing values of expressions. Unlike some other MI interfaces that |
| work with expressions, variable objects are specifically designed for |
| simple and efficient presentation in the frontend. A variable object |
| is identified by string name. When a variable object is created, the |
| frontend specifies the expression for that variable object. The |
| expression can be a simple variable, or it can be an arbitrary complex |
| expression, and can even involve CPU registers. After creating a |
| variable object, the frontend can invoke other variable object |
| operations--for example to obtain or change the value of a variable |
| object, or to change display format. |
| |
| Variable objects have hierarchical tree structure. Any variable |
| object that corresponds to a composite type, such as structure in C, has |
| a number of child variable objects, for example corresponding to each |
| element of a structure. A child variable object can itself have |
| children, recursively. Recursion ends when we reach leaf variable |
| objects, which always have built-in types. Child variable objects are |
| created only by explicit request, so if a frontend is not interested in |
| the children of a particular variable object, no child will be created. |
| |
| For a leaf variable object it is possible to obtain its value as a |
| string, or set the value from a string. String value can be also |
| obtained for a non-leaf variable object, but it's generally a string |
| that only indicates the type of the object, and does not list its |
| contents. Assignment to a non-leaf variable object is not allowed. |
| |
| A frontend does not need to read the values of all variable objects |
| each time the program stops. Instead, MI provides an update command |
| that lists all variable objects whose values has changed since the last |
| update operation. This considerably reduces the amount of data that |
| must be transferred to the frontend. As noted above, children variable |
| objects are created on demand, and only leaf variable objects have a |
| real value. As result, gdb will read target memory only for leaf |
| variables that frontend has created. |
| |
| The automatic update is not always desirable. For example, a |
| frontend might want to keep a value of some expression for future |
| reference, and never update it. For another example, fetching memory |
| is relatively slow for embedded targets, so a frontend might want to |
| disable automatic update for the variables that are either not visible |
| on the screen, or "closed". This is possible using so called "frozen |
| variable objects". Such variable objects are never implicitly updated. |
| |
| Variable objects can be either "fixed" or "floating". For the fixed |
| variable object, the expression is parsed when the variable object is |
| created, including associating identifiers to specific variables. The |
| meaning of expression never changes. For a floating variable object |
| the values of variables whose names appear in the expressions are |
| re-evaluated every time in the context of the current frame. Consider |
| this example: |
| |
| void do_work(...) |
| { |
| struct work_state state; |
| |
| if (...) |
| do_work(...); |
| } |
| |
| If a fixed variable object for the `state' variable is created in |
| this function, and we enter the recursive call, the the variable object |
| will report the value of `state' in the top-level `do_work' invocation. |
| On the other hand, a floating variable object will report the value of |
| `state' in the current frame. |
| |
| If an expression specified when creating a fixed variable object |
| refers to a local variable, the variable object becomes bound to the |
| thread and frame in which the variable object is created. When such |
| variable object is updated, GDB makes sure that the thread/frame |
| combination the variable object is bound to still exists, and |
| re-evaluates the variable object in context of that thread/frame. |
| |
| The following is the complete set of GDB/MI operations defined to |
| access this functionality: |
| |
| *Operation* *Description* |
| `-enable-pretty-printing' enable Python-based pretty-printing |
| `-var-create' create a variable object |
| `-var-delete' delete the variable object and/or its |
| children |
| `-var-set-format' set the display format of this variable |
| `-var-show-format' show the display format of this variable |
| `-var-info-num-children' tells how many children this object has |
| `-var-list-children' return a list of the object's children |
| `-var-info-type' show the type of this variable object |
| `-var-info-expression' print parent-relative expression that this |
| variable object represents |
| `-var-info-path-expression' print full expression that this variable |
| object represents |
| `-var-show-attributes' is this variable editable? does it exist |
| here? |
| `-var-evaluate-expression' get the value of this variable |
| `-var-assign' set the value of this variable |
| `-var-update' update the variable and its children |
| `-var-set-frozen' set frozeness attribute |
| `-var-set-update-range' set range of children to display on update |
| |
| In the next subsection we describe each operation in detail and |
| suggest how it can be used. |
| |
| Description And Use of Operations on Variable Objects |
| ----------------------------------------------------- |
| |
| The `-enable-pretty-printing' Command |
| ------------------------------------- |
| |
| -enable-pretty-printing |
| |
| GDB allows Python-based visualizers to affect the output of the MI |
| variable object commands. However, because there was no way to |
| implement this in a fully backward-compatible way, a front end must |
| request that this functionality be enabled. |
| |
| Once enabled, this feature cannot be disabled. |
| |
| Note that if Python support has not been compiled into GDB, this |
| command will still succeed (and do nothing). |
| |
| This feature is currently (as of GDB 7.0) experimental, and may work |
| differently in future versions of GDB. |
| |
| The `-var-create' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-create {NAME | "-"} |
| {FRAME-ADDR | "*" | "@"} EXPRESSION |
| |
| This operation creates a variable object, which allows the |
| monitoring of a variable, the result of an expression, a memory cell or |
| a CPU register. |
| |
| The NAME parameter is the string by which the object can be |
| referenced. It must be unique. If `-' is specified, the varobj system |
| will generate a string "varNNNNNN" automatically. It will be unique |
| provided that one does not specify NAME of that format. The command |
| fails if a duplicate name is found. |
| |
| The frame under which the expression should be evaluated can be |
| specified by FRAME-ADDR. A `*' indicates that the current frame should |
| be used. A `@' indicates that a floating variable object must be |
| created. |
| |
| EXPRESSION is any expression valid on the current language set (must |
| not begin with a `*'), or one of the following: |
| |
| * `*ADDR', where ADDR is the address of a memory cell |
| |
| * `*ADDR-ADDR' -- a memory address range (TBD) |
| |
| * `$REGNAME' -- a CPU register name |
| |
| A varobj's contents may be provided by a Python-based |
| pretty-printer. In this case the varobj is known as a "dynamic |
| varobj". Dynamic varobjs have slightly different semantics in some |
| cases. If the `-enable-pretty-printing' command is not sent, then GDB |
| will never create a dynamic varobj. This ensures backward |
| compatibility for existing clients. |
| |
| Result |
| ...... |
| |
| This operation returns attributes of the newly-created varobj. These |
| are: |
| |
| `name' |
| The name of the varobj. |
| |
| `numchild' |
| The number of children of the varobj. This number is not |
| necessarily reliable for a dynamic varobj. Instead, you must |
| examine the `has_more' attribute. |
| |
| `value' |
| The varobj's scalar value. For a varobj whose type is some sort of |
| aggregate (e.g., a `struct'), or for a dynamic varobj, this value |
| will not be interesting. |
| |
| `type' |
| The varobj's type. This is a string representation of the type, as |
| would be printed by the GDB CLI. |
| |
| `thread-id' |
| If a variable object is bound to a specific thread, then this is |
| the thread's identifier. |
| |
| `has_more' |
| For a dynamic varobj, this indicates whether there appear to be any |
| children available. For a non-dynamic varobj, this will be 0. |
| |
| `dynamic' |
| This attribute will be present and have the value `1' if the |
| varobj is a dynamic varobj. If the varobj is not a dynamic varobj, |
| then this attribute will not be present. |
| |
| `displayhint' |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| `display_hint' method. *Note Pretty Printing API::. |
| |
| Typical output will look like this: |
| |
| name="NAME",numchild="N",type="TYPE",thread-id="M", |
| has_more="HAS_MORE" |
| |
| The `-var-delete' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-delete [ -c ] NAME |
| |
| Deletes a previously created variable object and all of its children. |
| With the `-c' option, just deletes the children. |
| |
| Returns an error if the object NAME is not found. |
| |
| The `-var-set-format' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-format NAME FORMAT-SPEC |
| |
| Sets the output format for the value of the object NAME to be |
| FORMAT-SPEC. |
| |
| The syntax for the FORMAT-SPEC is as follows: |
| |
| FORMAT-SPEC ==> |
| {binary | decimal | hexadecimal | octal | natural} |
| |
| The natural format is the default format choosen automatically based |
| on the variable type (like decimal for an `int', hex for pointers, |
| etc.). |
| |
| For a variable with children, the format is set only on the variable |
| itself, and the children are not affected. |
| |
| The `-var-show-format' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-show-format NAME |
| |
| Returns the format used to display the value of the object NAME. |
| |
| FORMAT ==> |
| FORMAT-SPEC |
| |
| The `-var-info-num-children' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-info-num-children NAME |
| |
| Returns the number of children of a variable object NAME: |
| |
| numchild=N |
| |
| Note that this number is not completely reliable for a dynamic |
| varobj. It will return the current number of children, but more |
| children may be available. |
| |
| The `-var-list-children' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-list-children [PRINT-VALUES] NAME [FROM TO] |
| |
| Return a list of the children of the specified variable object and |
| create variable objects for them, if they do not already exist. With a |
| single argument or if PRINT-VALUES has a value of 0 or `--no-values', |
| print only the names of the variables; if PRINT-VALUES is 1 or |
| `--all-values', also print their values; and if it is 2 or |
| `--simple-values' print the name and value for simple data types and |
| just the name for arrays, structures and unions. |
| |
| FROM and TO, if specified, indicate the range of children to report. |
| If FROM or TO is less than zero, the range is reset and all children |
| will be reported. Otherwise, children starting at FROM (zero-based) |
| and up to and excluding TO will be reported. |
| |
| If a child range is requested, it will only affect the current call |
| to `-var-list-children', but not future calls to `-var-update'. For |
| this, you must instead use `-var-set-update-range'. The intent of this |
| approach is to enable a front end to implement any update approach it |
| likes; for example, scrolling a view may cause the front end to request |
| more children with `-var-list-children', and then the front end could |
| call `-var-set-update-range' with a different range to ensure that |
| future updates are restricted to just the visible items. |
| |
| For each child the following results are returned: |
| |
| NAME |
| Name of the variable object created for this child. |
| |
| EXP |
| The expression to be shown to the user by the front end to |
| designate this child. For example this may be the name of a |
| structure member. |
| |
| For a dynamic varobj, this value cannot be used to form an |
| expression. There is no way to do this at all with a dynamic |
| varobj. |
| |
| For C/C++ structures there are several pseudo children returned to |
| designate access qualifiers. For these pseudo children EXP is |
| `public', `private', or `protected'. In this case the type and |
| value are not present. |
| |
| A dynamic varobj will not report the access qualifying |
| pseudo-children, regardless of the language. This information is |
| not available at all with a dynamic varobj. |
| |
| NUMCHILD |
| Number of children this child has. For a dynamic varobj, this |
| will be 0. |
| |
| TYPE |
| The type of the child. |
| |
| VALUE |
| If values were requested, this is the value. |
| |
| THREAD-ID |
| If this variable object is associated with a thread, this is the |
| thread id. Otherwise this result is not present. |
| |
| FROZEN |
| If the variable object is frozen, this variable will be present |
| with a value of 1. |
| |
| The result may have its own attributes: |
| |
| `displayhint' |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| `display_hint' method. *Note Pretty Printing API::. |
| |
| `has_more' |
| This is an integer attribute which is nonzero if there are children |
| remaining after the end of the selected range. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-list-children n |
| ^done,numchild=N,children=[child={name=NAME,exp=EXP, |
| numchild=N,type=TYPE},(repeats N times)] |
| (gdb) |
| -var-list-children --all-values n |
| ^done,numchild=N,children=[child={name=NAME,exp=EXP, |
| numchild=N,value=VALUE,type=TYPE},(repeats N times)] |
| |
| The `-var-info-type' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-type NAME |
| |
| Returns the type of the specified variable NAME. The type is |
| returned as a string in the same format as it is output by the GDB CLI: |
| |
| type=TYPENAME |
| |
| The `-var-info-expression' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-expression NAME |
| |
| Returns a string that is suitable for presenting this variable |
| object in user interface. The string is generally not valid expression |
| in the current language, and cannot be evaluated. |
| |
| For example, if `a' is an array, and variable object `A' was created |
| for `a', then we'll get this output: |
| |
| (gdb) -var-info-expression A.1 |
| ^done,lang="C",exp="1" |
| |
| Here, the values of `lang' can be `{"C" | "C++" | "Java"}'. |
| |
| Note that the output of the `-var-list-children' command also |
| includes those expressions, so the `-var-info-expression' command is of |
| limited use. |
| |
| The `-var-info-path-expression' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-path-expression NAME |
| |
| Returns an expression that can be evaluated in the current context |
| and will yield the same value that a variable object has. Compare this |
| with the `-var-info-expression' command, which result can be used only |
| for UI presentation. Typical use of the `-var-info-path-expression' |
| command is creating a watchpoint from a variable object. |
| |
| This command is currently not valid for children of a dynamic varobj, |
| and will give an error when invoked on one. |
| |
| For example, suppose `C' is a C++ class, derived from class `Base', |
| and that the `Base' class has a member called `m_size'. Assume a |
| variable `c' is has the type of `C' and a variable object `C' was |
| created for variable `c'. Then, we'll get this output: |
| (gdb) -var-info-path-expression C.Base.public.m_size |
| ^done,path_expr=((Base)c).m_size) |
| |
| The `-var-show-attributes' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-show-attributes NAME |
| |
| List attributes of the specified variable object NAME: |
| |
| status=ATTR [ ( ,ATTR )* ] |
| |
| where ATTR is `{ { editable | noneditable } | TBD }'. |
| |
| The `-var-evaluate-expression' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-evaluate-expression [-f FORMAT-SPEC] NAME |
| |
| Evaluates the expression that is represented by the specified |
| variable object and returns its value as a string. The format of the |
| string can be specified with the `-f' option. The possible values of |
| this option are the same as for `-var-set-format' (*note |
| -var-set-format::). If the `-f' option is not specified, the current |
| display format will be used. The current display format can be changed |
| using the `-var-set-format' command. |
| |
| value=VALUE |
| |
| Note that one must invoke `-var-list-children' for a variable before |
| the value of a child variable can be evaluated. |
| |
| The `-var-assign' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-assign NAME EXPRESSION |
| |
| Assigns the value of EXPRESSION to the variable object specified by |
| NAME. The object must be `editable'. If the variable's value is |
| altered by the assign, the variable will show up in any subsequent |
| `-var-update' list. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update * |
| ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] |
| (gdb) |
| |
| The `-var-update' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-update [PRINT-VALUES] {NAME | "*"} |
| |
| Reevaluate the expressions corresponding to the variable object NAME |
| and all its direct and indirect children, and return the list of |
| variable objects whose values have changed; NAME must be a root |
| variable object. Here, "changed" means that the result of |
| `-var-evaluate-expression' before and after the `-var-update' is |
| different. If `*' is used as the variable object names, all existing |
| variable objects are updated, except for frozen ones (*note |
| -var-set-frozen::). The option PRINT-VALUES determines whether both |
| names and values, or just names are printed. The possible values of |
| this option are the same as for `-var-list-children' (*note |
| -var-list-children::). It is recommended to use the `--all-values' |
| option, to reduce the number of MI commands needed on each program stop. |
| |
| With the `*' parameter, if a variable object is bound to a currently |
| running thread, it will not be updated, without any diagnostic. |
| |
| If `-var-set-update-range' was previously used on a varobj, then |
| only the selected range of children will be reported. |
| |
| `-var-update' reports all the changed varobjs in a tuple named |
| `changelist'. |
| |
| Each item in the change list is itself a tuple holding: |
| |
| `name' |
| The name of the varobj. |
| |
| `value' |
| If values were requested for this update, then this field will be |
| present and will hold the value of the varobj. |
| |
| `in_scope' |
| This field is a string which may take one of three values: |
| |
| `"true"' |
| The variable object's current value is valid. |
| |
| `"false"' |
| The variable object does not currently hold a valid value but |
| it may hold one in the future if its associated expression |
| comes back into scope. |
| |
| `"invalid"' |
| The variable object no longer holds a valid value. This can |
| occur when the executable file being debugged has changed, |
| either through recompilation or by using the GDB `file' |
| command. The front end should normally choose to delete |
| these variable objects. |
| |
| In the future new values may be added to this list so the front |
| should be prepared for this possibility. *Note GDB/MI Development |
| and Front Ends: GDB/MI Development and Front Ends. |
| |
| `type_changed' |
| This is only present if the varobj is still valid. If the type |
| changed, then this will be the string `true'; otherwise it will be |
| `false'. |
| |
| `new_type' |
| If the varobj's type changed, then this field will be present and |
| will hold the new type. |
| |
| `new_num_children' |
| For a dynamic varobj, if the number of children changed, or if the |
| type changed, this will be the new number of children. |
| |
| The `numchild' field in other varobj responses is generally not |
| valid for a dynamic varobj - it will show the number of children |
| that GDB knows about, but because dynamic varobjs lazily |
| instantiate their children, this will not reflect the number of |
| children which may be available. |
| |
| The `new_num_children' attribute only reports changes to the |
| number of children known by GDB. This is the only way to detect |
| whether an update has removed children (which necessarily can only |
| happen at the end of the update range). |
| |
| `displayhint' |
| The display hint, if any. |
| |
| `has_more' |
| This is an integer value, which will be 1 if there are more |
| children available outside the varobj's update range. |
| |
| `dynamic' |
| This attribute will be present and have the value `1' if the |
| varobj is a dynamic varobj. If the varobj is not a dynamic varobj, |
| then this attribute will not be present. |
| |
| `new_children' |
| If new children were added to a dynamic varobj within the selected |
| update range (as set by `-var-set-update-range'), then they will |
| be listed in this attribute. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update --all-values var1 |
| ^done,changelist=[{name="var1",value="3",in_scope="true", |
| type_changed="false"}] |
| (gdb) |
| |
| The `-var-set-frozen' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-frozen NAME FLAG |
| |
| Set the frozenness flag on the variable object NAME. The FLAG |
| parameter should be either `1' to make the variable frozen or `0' to |
| make it unfrozen. If a variable object is frozen, then neither itself, |
| nor any of its children, are implicitly updated by `-var-update' of a |
| parent variable or by `-var-update *'. Only `-var-update' of the |
| variable itself will update its value and values of its children. |
| After a variable object is unfrozen, it is implicitly updated by all |
| subsequent `-var-update' operations. Unfreezing a variable does not |
| update it, only subsequent `-var-update' does. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-set-frozen V 1 |
| ^done |
| (gdb) |
| |
| The `-var-set-update-range' command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-update-range NAME FROM TO |
| |
| Set the range of children to be returned by future invocations of |
| `-var-update'. |
| |
| FROM and TO indicate the range of children to report. If FROM or TO |
| is less than zero, the range is reset and all children will be |
| reported. Otherwise, children starting at FROM (zero-based) and up to |
| and excluding TO will be reported. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-set-update-range V 1 2 |
| ^done |
| |
| The `-var-set-visualizer' command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-visualizer NAME VISUALIZER |
| |
| Set a visualizer for the variable object NAME. |
| |
| VISUALIZER is the visualizer to use. The special value `None' means |
| to disable any visualizer in use. |
| |
| If not `None', VISUALIZER must be a Python expression. This |
| expression must evaluate to a callable object which accepts a single |
| argument. GDB will call this object with the value of the varobj NAME |
| as an argument (this is done so that the same Python pretty-printing |
| code can be used for both the CLI and MI). When called, this object |
| must return an object which conforms to the pretty-printing interface |
| (*note Pretty Printing API::). |
| |
| The pre-defined function `gdb.default_visualizer' may be used to |
| select a visualizer by following the built-in process (*note Selecting |
| Pretty-Printers::). This is done automatically when a varobj is |
| created, and so ordinarily is not needed. |
| |
| This feature is only available if Python support is enabled. The MI |
| command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be |
| used to check this. |
| |
| Example |
| ....... |
| |
| Resetting the visualizer: |
| |
| (gdb) |
| -var-set-visualizer V None |
| ^done |
| |
| Reselecting the default (type-based) visualizer: |
| |
| (gdb) |
| -var-set-visualizer V gdb.default_visualizer |
| ^done |
| |
| Suppose `SomeClass' is a visualizer class. A lambda expression can |
| be used to instantiate this class for a varobj: |
| |
| (gdb) |
| -var-set-visualizer V "lambda val: SomeClass()" |
| ^done |
| |