| 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 2011, 2012 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 Tenth Edition, of `Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 7.5. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 2011, 2012 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: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files |
| |
| 18.4 Errors Reading Symbol Files |
| ================================ |
| |
| While reading a symbol file, GDB occasionally encounters problems, such |
| as symbol types it does not recognize, or known bugs in compiler |
| output. By default, GDB does not notify you of such problems, since |
| they are relatively common and primarily of interest to people |
| debugging compilers. If you are interested in seeing information about |
| ill-constructed symbol tables, you can either ask GDB to print only one |
| message about each such type of problem, no matter how many times the |
| problem occurs; or you can ask GDB to print more messages, to see how |
| many times the problems occur, with the `set complaints' command (*note |
| Optional Warnings and Messages: Messages/Warnings.). |
| |
| The messages currently printed, and their meanings, include: |
| |
| `inner block not inside outer block in SYMBOL' |
| The symbol information shows where symbol scopes begin and end |
| (such as at the start of a function or a block of statements). |
| This error indicates that an inner scope block is not fully |
| contained in its outer scope blocks. |
| |
| GDB circumvents the problem by treating the inner block as if it |
| had the same scope as the outer block. In the error message, |
| SYMBOL may be shown as "`(don't know)'" if the outer block is not a |
| function. |
| |
| `block at ADDRESS out of order' |
| The symbol information for symbol scope blocks should occur in |
| order of increasing addresses. This error indicates that it does |
| not do so. |
| |
| GDB does not circumvent this problem, and has trouble locating |
| symbols in the source file whose symbols it is reading. (You can |
| often determine what source file is affected by specifying `set |
| verbose on'. *Note Optional Warnings and Messages: |
| Messages/Warnings.) |
| |
| `bad block start address patched' |
| The symbol information for a symbol scope block has a start address |
| smaller than the address of the preceding source line. This is |
| known to occur in the SunOS 4.1.1 (and earlier) C compiler. |
| |
| GDB circumvents the problem by treating the symbol scope block as |
| starting on the previous source line. |
| |
| `bad string table offset in symbol N' |
| Symbol number N contains a pointer into the string table which is |
| larger than the size of the string table. |
| |
| GDB circumvents the problem by considering the symbol to have the |
| name `foo', which may cause other problems if many symbols end up |
| with this name. |
| |
| `unknown symbol type `0xNN'' |
| The symbol information contains new data types that GDB does not |
| yet know how to read. `0xNN' is the symbol type of the |
| uncomprehended information, in hexadecimal. |
| |
| GDB circumvents the error by ignoring this symbol information. |
| This usually allows you to debug your program, though certain |
| symbols are not accessible. If you encounter such a problem and |
| feel like debugging it, you can debug `gdb' with itself, breakpoint |
| on `complain', then go up to the function `read_dbx_symtab' and |
| examine `*bufp' to see the symbol. |
| |
| `stub type has NULL name' |
| GDB could not find the full definition for a struct or class. |
| |
| `const/volatile indicator missing (ok if using g++ v1.x), got...' |
| The symbol information for a C++ member function is missing some |
| information that recent versions of the compiler should have |
| output for it. |
| |
| `info mismatch between compiler and debugger' |
| GDB could not parse a type specification output by the compiler. |
| |
| |
| |
| File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files |
| |
| 18.5 GDB Data Files |
| =================== |
| |
| GDB will sometimes read an auxiliary data file. These files are kept |
| in a directory known as the "data directory". |
| |
| You can set the data directory's name, and view the name GDB is |
| currently using. |
| |
| `set data-directory DIRECTORY' |
| Set the directory which GDB searches for auxiliary data files to |
| DIRECTORY. |
| |
| `show data-directory' |
| Show the directory GDB searches for auxiliary data files. |
| |
| You can set the default data directory by using the configure-time |
| `--with-gdb-datadir' option. If the data directory is inside GDB's |
| configured binary prefix (set with `--prefix' or `--exec-prefix'), then |
| the default data directory will be updated automatically if the |
| installed GDB is moved to a new location. |
| |
| The data directory may also be specified with the `--data-directory' |
| command line option. *Note Mode Options::. |
| |
| |
| File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top |
| |
| 19 Specifying a Debugging Target |
| ******************************** |
| |
| A "target" is the execution environment occupied by your program. |
| |
| Often, GDB runs in the same host environment as your program; in |
| that case, the debugging target is specified as a side effect when you |
| use the `file' or `core' commands. When you need more flexibility--for |
| example, running GDB on a physically separate host, or controlling a |
| standalone system over a serial port or a realtime system over a TCP/IP |
| connection--you can use the `target' command to specify one of the |
| target types configured for GDB (*note Commands for Managing Targets: |
| Target Commands.). |
| |
| It is possible to build GDB for several different "target |
| architectures". When GDB is built like that, you can choose one of the |
| available architectures with the `set architecture' command. |
| |
| `set architecture ARCH' |
| This command sets the current target architecture to ARCH. The |
| value of ARCH can be `"auto"', in addition to one of the supported |
| architectures. |
| |
| `show architecture' |
| Show the current target architecture. |
| |
| `set processor' |
| `processor' |
| These are alias commands for, respectively, `set architecture' and |
| `show architecture'. |
| |
| * Menu: |
| |
| * Active Targets:: Active targets |
| * Target Commands:: Commands for managing targets |
| * Byte Order:: Choosing target byte order |
| |
| |
| File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets |
| |
| 19.1 Active Targets |
| =================== |
| |
| There are multiple classes of targets such as: processes, executable |
| files or recording sessions. Core files belong to the process class, |
| making core file and process mutually exclusive. Otherwise, GDB can |
| work concurrently on multiple active targets, one in each class. This |
| allows you to (for example) start a process and inspect its activity, |
| while still having access to the executable file after the process |
| finishes. Or if you start process recording (*note Reverse |
| Execution::) and `reverse-step' there, you are presented a virtual |
| layer of the recording target, while the process target remains stopped |
| at the chronologically last point of the process execution. |
| |
| Use the `core-file' and `exec-file' commands to select a new core |
| file or executable target (*note Commands to Specify Files: Files.). To |
| specify as a target a process that is already running, use the `attach' |
| command (*note Debugging an Already-running Process: Attach.). |
| |
| |
| File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets |
| |
| 19.2 Commands for Managing Targets |
| ================================== |
| |
| `target TYPE PARAMETERS' |
| Connects the GDB host environment to a target machine or process. |
| A target is typically a protocol for talking to debugging |
| facilities. You use the argument TYPE to specify the type or |
| protocol of the target machine. |
| |
| Further PARAMETERS are interpreted by the target protocol, but |
| typically include things like device names or host names to connect |
| with, process numbers, and baud rates. |
| |
| The `target' command does not repeat if you press <RET> again |
| after executing the command. |
| |
| `help target' |
| Displays the names of all targets available. To display targets |
| currently selected, use either `info target' or `info files' |
| (*note Commands to Specify Files: Files.). |
| |
| `help target NAME' |
| Describe a particular target, including any parameters necessary to |
| select it. |
| |
| `set gnutarget ARGS' |
| GDB uses its own library BFD to read your files. GDB knows |
| whether it is reading an "executable", a "core", or a ".o" file; |
| however, you can specify the file format with the `set gnutarget' |
| command. Unlike most `target' commands, with `gnutarget' the |
| `target' refers to a program, not a machine. |
| |
| _Warning:_ To specify a file format with `set gnutarget', you |
| must know the actual BFD name. |
| |
| *Note Commands to Specify Files: Files. |
| |
| `show gnutarget' |
| Use the `show gnutarget' command to display what file format |
| `gnutarget' is set to read. If you have not set `gnutarget', GDB |
| will determine the file format for each file automatically, and |
| `show gnutarget' displays `The current BDF target is "auto"'. |
| |
| Here are some common targets (available, or not, depending on the GDB |
| configuration): |
| |
| `target exec PROGRAM' |
| An executable file. `target exec PROGRAM' is the same as |
| `exec-file PROGRAM'. |
| |
| `target core FILENAME' |
| A core dump file. `target core FILENAME' is the same as |
| `core-file FILENAME'. |
| |
| `target remote MEDIUM' |
| A remote system connected to GDB via a serial line or network |
| connection. This command tells GDB to use its own remote protocol |
| over MEDIUM for debugging. *Note Remote Debugging::. |
| |
| For example, if you have a board connected to `/dev/ttya' on the |
| machine running GDB, you could say: |
| |
| target remote /dev/ttya |
| |
| `target remote' supports the `load' command. This is only useful |
| if you have some other way of getting the stub to the target |
| system, and you can put it somewhere in memory where it won't get |
| clobbered by the download. |
| |
| `target sim [SIMARGS] ...' |
| Builtin CPU simulator. GDB includes simulators for most |
| architectures. In general, |
| target sim |
| load |
| run |
| works; however, you cannot assume that a specific memory map, |
| device drivers, or even basic I/O is available, although some |
| simulators do provide these. For info about any |
| processor-specific simulator details, see the appropriate section |
| in *Note Embedded Processors: Embedded Processors. |
| |
| |
| Some configurations may include these targets as well: |
| |
| `target nrom DEV' |
| NetROM ROM emulator. This target only supports downloading. |
| |
| |
| Different targets are available on different configurations of GDB; |
| your configuration may have more or fewer targets. |
| |
| Many remote targets require you to download the executable's code |
| once you've successfully established a connection. You may wish to |
| control various aspects of this process. |
| |
| `set hash' |
| This command controls whether a hash mark `#' is displayed while |
| downloading a file to the remote monitor. If on, a hash mark is |
| displayed after each S-record is successfully downloaded to the |
| monitor. |
| |
| `show hash' |
| Show the current status of displaying the hash mark. |
| |
| `set debug monitor' |
| Enable or disable display of communications messages between GDB |
| and the remote monitor. |
| |
| `show debug monitor' |
| Show the current status of displaying communications between GDB |
| and the remote monitor. |
| |
| `load FILENAME' |
| Depending on what remote debugging facilities are configured into |
| GDB, the `load' command may be available. Where it exists, it is |
| meant to make FILENAME (an executable) available for debugging on |
| the remote system--by downloading, or dynamic linking, for example. |
| `load' also records the FILENAME symbol table in GDB, like the |
| `add-symbol-file' command. |
| |
| If your GDB does not have a `load' command, attempting to execute |
| it gets the error message "`You can't do that when your target is |
| ...'" |
| |
| The file is loaded at whatever address is specified in the |
| executable. For some object file formats, you can specify the |
| load address when you link the program; for other formats, like |
| a.out, the object file format specifies a fixed address. |
| |
| Depending on the remote side capabilities, GDB may be able to load |
| programs into flash memory. |
| |
| `load' does not repeat if you press <RET> again after using it. |
| |
| |
| File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets |
| |
| 19.3 Choosing Target Byte Order |
| =============================== |
| |
| Some types of processors, such as the MIPS, PowerPC, and Renesas SH, |
| offer the ability to run either big-endian or little-endian byte |
| orders. Usually the executable or symbol will include a bit to |
| designate the endian-ness, and you will not need to worry about which |
| to use. However, you may still find it useful to adjust GDB's idea of |
| processor endian-ness manually. |
| |
| `set endian big' |
| Instruct GDB to assume the target is big-endian. |
| |
| `set endian little' |
| Instruct GDB to assume the target is little-endian. |
| |
| `set endian auto' |
| Instruct GDB to use the byte order associated with the executable. |
| |
| `show endian' |
| Display GDB's current idea of the target byte order. |
| |
| |
| Note that these commands merely adjust interpretation of symbolic |
| data on the host, and that they have absolutely no effect on the target |
| system. |
| |
| |
| File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top |
| |
| 20 Debugging Remote Programs |
| **************************** |
| |
| If you are trying to debug a program running on a machine that cannot |
| run GDB in the usual way, it is often useful to use remote debugging. |
| For example, you might use remote debugging on an operating system |
| kernel, or on a small system which does not have a general purpose |
| operating system powerful enough to run a full-featured debugger. |
| |
| Some configurations of GDB have special serial or TCP/IP interfaces |
| to make this work with particular debugging targets. In addition, GDB |
| comes with a generic serial protocol (specific to GDB, but not specific |
| to any particular target system) which you can use if you write the |
| remote stubs--the code that runs on the remote system to communicate |
| with GDB. |
| |
| Other remote targets may be available in your configuration of GDB; |
| use `help target' to list them. |
| |
| * Menu: |
| |
| * Connecting:: Connecting to a remote target |
| * File Transfer:: Sending files to a remote system |
| * Server:: Using the gdbserver program |
| * Remote Configuration:: Remote configuration |
| * Remote Stub:: Implementing a remote stub |
| |
| |
| File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging |
| |
| 20.1 Connecting to a Remote Target |
| ================================== |
| |
| On the GDB host machine, you will need an unstripped copy of your |
| program, since GDB needs symbol and debugging information. Start up |
| GDB as usual, using the name of the local copy of your program as the |
| first argument. |
| |
| GDB can communicate with the target over a serial line, or over an |
| IP network using TCP or UDP. In each case, GDB uses the same protocol |
| for debugging your program; only the medium carrying the debugging |
| packets varies. The `target remote' command establishes a connection |
| to the target. Its arguments indicate which medium to use: |
| |
| `target remote SERIAL-DEVICE' |
| Use SERIAL-DEVICE to communicate with the target. For example, to |
| use a serial line connected to the device named `/dev/ttyb': |
| |
| target remote /dev/ttyb |
| |
| If you're using a serial line, you may want to give GDB the |
| `--baud' option, or use the `set remotebaud' command (*note set |
| remotebaud: Remote Configuration.) before the `target' command. |
| |
| `target remote `HOST:PORT'' |
| `target remote `tcp:HOST:PORT'' |
| Debug using a TCP connection to PORT on HOST. The HOST may be |
| either a host name or a numeric IP address; PORT must be a decimal |
| number. The HOST could be the target machine itself, if it is |
| directly connected to the net, or it might be a terminal server |
| which in turn has a serial line to the target. |
| |
| For example, to connect to port 2828 on a terminal server named |
| `manyfarms': |
| |
| target remote manyfarms:2828 |
| |
| If your remote target is actually running on the same machine as |
| your debugger session (e.g. a simulator for your target running on |
| the same host), you can omit the hostname. For example, to |
| connect to port 1234 on your local machine: |
| |
| target remote :1234 |
| Note that the colon is still required here. |
| |
| `target remote `udp:HOST:PORT'' |
| Debug using UDP packets to PORT on HOST. For example, to connect |
| to UDP port 2828 on a terminal server named `manyfarms': |
| |
| target remote udp:manyfarms:2828 |
| |
| When using a UDP connection for remote debugging, you should keep |
| in mind that the `U' stands for "Unreliable". UDP can silently |
| drop packets on busy or unreliable networks, which will cause |
| havoc with your debugging session. |
| |
| `target remote | COMMAND' |
| Run COMMAND in the background and communicate with it using a |
| pipe. The COMMAND is a shell command, to be parsed and expanded |
| by the system's command shell, `/bin/sh'; it should expect remote |
| protocol packets on its standard input, and send replies on its |
| standard output. You could use this to run a stand-alone simulator |
| that speaks the remote debugging protocol, to make net connections |
| using programs like `ssh', or for other similar tricks. |
| |
| If COMMAND closes its standard output (perhaps by exiting), GDB |
| will try to send it a `SIGTERM' signal. (If the program has |
| already exited, this will have no effect.) |
| |
| |
| Once the connection has been established, you can use all the usual |
| commands to examine and change data. The remote program is already |
| running; you can use `step' and `continue', and you do not need to use |
| `run'. |
| |
| Whenever GDB is waiting for the remote program, if you type the |
| interrupt character (often `Ctrl-c'), GDB attempts to stop the program. |
| This may or may not succeed, depending in part on the hardware and the |
| serial drivers the remote system uses. If you type the interrupt |
| character once again, GDB displays this prompt: |
| |
| Interrupted while waiting for the program. |
| Give up (and stop debugging it)? (y or n) |
| |
| If you type `y', GDB abandons the remote debugging session. (If you |
| decide you want to try again later, you can use `target remote' again |
| to connect once more.) If you type `n', GDB goes back to waiting. |
| |
| `detach' |
| When you have finished debugging the remote program, you can use |
| the `detach' command to release it from GDB control. Detaching |
| from the target normally resumes its execution, but the results |
| will depend on your particular remote stub. After the `detach' |
| command, GDB is free to connect to another target. |
| |
| `disconnect' |
| The `disconnect' command behaves like `detach', except that the |
| target is generally not resumed. It will wait for GDB (this |
| instance or another one) to connect and continue debugging. After |
| the `disconnect' command, GDB is again free to connect to another |
| target. |
| |
| `monitor CMD' |
| This command allows you to send arbitrary commands directly to the |
| remote monitor. Since GDB doesn't care about the commands it |
| sends like this, this command is the way to extend GDB--you can |
| add new commands that only the external monitor will understand |
| and implement. |
| |
| |
| File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging |
| |
| 20.2 Sending files to a remote system |
| ===================================== |
| |
| Some remote targets offer the ability to transfer files over the same |
| connection used to communicate with GDB. This is convenient for |
| targets accessible through other means, e.g. GNU/Linux systems running |
| `gdbserver' over a network interface. For other targets, e.g. embedded |
| devices with only a single serial port, this may be the only way to |
| upload or download files. |
| |
| Not all remote targets support these commands. |
| |
| `remote put HOSTFILE TARGETFILE' |
| Copy file HOSTFILE from the host system (the machine running GDB) |
| to TARGETFILE on the target system. |
| |
| `remote get TARGETFILE HOSTFILE' |
| Copy file TARGETFILE from the target system to HOSTFILE on the |
| host system. |
| |
| `remote delete TARGETFILE' |
| Delete TARGETFILE from the target system. |
| |
| |
| |
| File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging |
| |
| 20.3 Using the `gdbserver' Program |
| ================================== |
| |
| `gdbserver' is a control program for Unix-like systems, which allows |
| you to connect your program with a remote GDB via `target remote'--but |
| without linking in the usual debugging stub. |
| |
| `gdbserver' is not a complete replacement for the debugging stubs, |
| because it requires essentially the same operating-system facilities |
| that GDB itself does. In fact, a system that can run `gdbserver' to |
| connect to a remote GDB could also run GDB locally! `gdbserver' is |
| sometimes useful nevertheless, because it is a much smaller program |
| than GDB itself. It is also easier to port than all of GDB, so you may |
| be able to get started more quickly on a new system by using |
| `gdbserver'. Finally, if you develop code for real-time systems, you |
| may find that the tradeoffs involved in real-time operation make it |
| more convenient to do as much development work as possible on another |
| system, for example by cross-compiling. You can use `gdbserver' to |
| make a similar choice for debugging. |
| |
| GDB and `gdbserver' communicate via either a serial line or a TCP |
| connection, using the standard GDB remote serial protocol. |
| |
| _Warning:_ `gdbserver' does not have any built-in security. Do |
| not run `gdbserver' connected to any public network; a GDB |
| connection to `gdbserver' provides access to the target system |
| with the same privileges as the user running `gdbserver'. |
| |
| 20.3.1 Running `gdbserver' |
| -------------------------- |
| |
| Run `gdbserver' on the target system. You need a copy of the program |
| you want to debug, including any libraries it requires. `gdbserver' |
| does not need your program's symbol table, so you can strip the program |
| if necessary to save space. GDB on the host system does all the symbol |
| handling. |
| |
| To use the server, you must tell it how to communicate with GDB; the |
| name of your program; and the arguments for your program. The usual |
| syntax is: |
| |
| target> gdbserver COMM PROGRAM [ ARGS ... ] |
| |
| COMM is either a device name (to use a serial line), or a TCP |
| hostname and portnumber, or `-' or `stdio' to use stdin/stdout of |
| `gdbserver'. For example, to debug Emacs with the argument `foo.txt' |
| and communicate with GDB over the serial port `/dev/com1': |
| |
| target> gdbserver /dev/com1 emacs foo.txt |
| |
| `gdbserver' waits passively for the host GDB to communicate with it. |
| |
| To use a TCP connection instead of a serial line: |
| |
| target> gdbserver host:2345 emacs foo.txt |
| |
| The only difference from the previous example is the first argument, |
| specifying that you are communicating with the host GDB via TCP. The |
| `host:2345' argument means that `gdbserver' is to expect a TCP |
| connection from machine `host' to local TCP port 2345. (Currently, the |
| `host' part is ignored.) You can choose any number you want for the |
| port number as long as it does not conflict with any TCP ports already |
| in use on the target system (for example, `23' is reserved for |
| `telnet').(1) You must use the same port number with the host GDB |
| `target remote' command. |
| |
| The `stdio' connection is useful when starting `gdbserver' with ssh: |
| |
| (gdb) target remote | ssh -T hostname gdbserver - hello |
| |
| The `-T' option to ssh is provided because we don't need a remote |
| pty, and we don't want escape-character handling. Ssh does this by |
| default when a command is provided, the flag is provided to make it |
| explicit. You could elide it if you want to. |
| |
| Programs started with stdio-connected gdbserver have `/dev/null' for |
| `stdin', and `stdout',`stderr' are sent back to gdb for display through |
| a pipe connected to gdbserver. Both `stdout' and `stderr' use the same |
| pipe. |
| |
| 20.3.1.1 Attaching to a Running Program |
| ....................................... |
| |
| On some targets, `gdbserver' can also attach to running programs. This |
| is accomplished via the `--attach' argument. The syntax is: |
| |
| target> gdbserver --attach COMM PID |
| |
| PID is the process ID of a currently running process. It isn't |
| necessary to point `gdbserver' at a binary for the running process. |
| |
| You can debug processes by name instead of process ID if your target |
| has the `pidof' utility: |
| |
| target> gdbserver --attach COMM `pidof PROGRAM` |
| |
| In case more than one copy of PROGRAM is running, or PROGRAM has |
| multiple threads, most versions of `pidof' support the `-s' option to |
| only return the first process ID. |
| |
| 20.3.1.2 Multi-Process Mode for `gdbserver' |
| ........................................... |
| |
| When you connect to `gdbserver' using `target remote', `gdbserver' |
| debugs the specified program only once. When the program exits, or you |
| detach from it, GDB closes the connection and `gdbserver' exits. |
| |
| If you connect using `target extended-remote', `gdbserver' enters |
| multi-process mode. When the debugged program exits, or you detach |
| from it, GDB stays connected to `gdbserver' even though no program is |
| running. The `run' and `attach' commands instruct `gdbserver' to run |
| or attach to a new program. The `run' command uses `set remote |
| exec-file' (*note set remote exec-file::) to select the program to run. |
| Command line arguments are supported, except for wildcard expansion |
| and I/O redirection (*note Arguments::). |
| |
| To start `gdbserver' without supplying an initial command to run or |
| process ID to attach, use the `--multi' command line option. Then you |
| can connect using `target extended-remote' and start the program you |
| want to debug. |
| |
| In multi-process mode `gdbserver' does not automatically exit unless |
| you use the option `--once'. You can terminate it by using `monitor |
| exit' (*note Monitor Commands for gdbserver::). Note that the |
| conditions under which `gdbserver' terminates depend on how GDB |
| connects to it (`target remote' or `target extended-remote'). The |
| `--multi' option to `gdbserver' has no influence on that. |
| |
| 20.3.1.3 TCP port allocation lifecycle of `gdbserver' |
| ..................................................... |
| |
| This section applies only when `gdbserver' is run to listen on a TCP |
| port. |
| |
| `gdbserver' normally terminates after all of its debugged processes |
| have terminated in `target remote' mode. On the other hand, for `target |
| extended-remote', `gdbserver' stays running even with no processes left. |
| GDB normally terminates the spawned debugged process on its exit, which |
| normally also terminates `gdbserver' in the `target remote' mode. |
| Therefore, when the connection drops unexpectedly, and GDB cannot ask |
| `gdbserver' to kill its debugged processes, `gdbserver' stays running |
| even in the `target remote' mode. |
| |
| When `gdbserver' stays running, GDB can connect to it again later. |
| Such reconnecting is useful for features like *Note disconnected |
| tracing::. For completeness, at most one GDB can be connected at a |
| time. |
| |
| By default, `gdbserver' keeps the listening TCP port open, so that |
| additional connections are possible. However, if you start `gdbserver' |
| with the `--once' option, it will stop listening for any further |
| connection attempts after connecting to the first GDB session. This |
| means no further connections to `gdbserver' will be possible after the |
| first one. It also means `gdbserver' will terminate after the first |
| connection with remote GDB has closed, even for unexpectedly closed |
| connections and even in the `target extended-remote' mode. The |
| `--once' option allows reusing the same port number for connecting to |
| multiple instances of `gdbserver' running on the same host, since each |
| instance closes its port after the first connection. |
| |
| 20.3.1.4 Other Command-Line Arguments for `gdbserver' |
| ..................................................... |
| |
| The `--debug' option tells `gdbserver' to display extra status |
| information about the debugging process. The `--remote-debug' option |
| tells `gdbserver' to display remote protocol debug output. These |
| options are intended for `gdbserver' development and for bug reports to |
| the developers. |
| |
| The `--wrapper' option specifies a wrapper to launch programs for |
| debugging. The option should be followed by the name of the wrapper, |
| then any command-line arguments to pass to the wrapper, then `--' |
| indicating the end of the wrapper arguments. |
| |
| `gdbserver' runs the specified wrapper program with a combined |
| command line including the wrapper arguments, then the name of the |
| program to debug, then any arguments to the program. The wrapper runs |
| until it executes your program, and then GDB gains control. |
| |
| You can use any program that eventually calls `execve' with its |
| arguments as a wrapper. Several standard Unix utilities do this, e.g. |
| `env' and `nohup'. Any Unix shell script ending with `exec "$@"' will |
| also work. |
| |
| For example, you can use `env' to pass an environment variable to |
| the debugged program, without setting the variable in `gdbserver''s |
| environment: |
| |
| $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog |
| |
| 20.3.2 Connecting to `gdbserver' |
| -------------------------------- |
| |
| Run GDB on the host system. |
| |
| First make sure you have the necessary symbol files. Load symbols |
| for your application using the `file' command before you connect. Use |
| `set sysroot' to locate target libraries (unless your GDB was compiled |
| with the correct sysroot using `--with-sysroot'). |
| |
| The symbol file and target libraries must exactly match the |
| executable and libraries on the target, with one exception: the files |
| on the host system should not be stripped, even if the files on the |
| target system are. Mismatched or missing files will lead to confusing |
| results during debugging. On GNU/Linux targets, mismatched or missing |
| files may also prevent `gdbserver' from debugging multi-threaded |
| programs. |
| |
| Connect to your target (*note Connecting to a Remote Target: |
| Connecting.). For TCP connections, you must start up `gdbserver' prior |
| to using the `target remote' command. Otherwise you may get an error |
| whose text depends on the host system, but which usually looks |
| something like `Connection refused'. Don't use the `load' command in |
| GDB when using `gdbserver', since the program is already on the target. |
| |
| 20.3.3 Monitor Commands for `gdbserver' |
| --------------------------------------- |
| |
| During a GDB session using `gdbserver', you can use the `monitor' |
| command to send special requests to `gdbserver'. Here are the |
| available commands. |
| |
| `monitor help' |
| List the available monitor commands. |
| |
| `monitor set debug 0' |
| `monitor set debug 1' |
| Disable or enable general debugging messages. |
| |
| `monitor set remote-debug 0' |
| `monitor set remote-debug 1' |
| Disable or enable specific debugging messages associated with the |
| remote protocol (*note Remote Protocol::). |
| |
| `monitor set libthread-db-search-path [PATH]' |
| When this command is issued, PATH is a colon-separated list of |
| directories to search for `libthread_db' (*note set |
| libthread-db-search-path: Threads.). If you omit PATH, |
| `libthread-db-search-path' will be reset to its default value. |
| |
| The special entry `$pdir' for `libthread-db-search-path' is not |
| supported in `gdbserver'. |
| |
| `monitor exit' |
| Tell gdbserver to exit immediately. This command should be |
| followed by `disconnect' to close the debugging session. |
| `gdbserver' will detach from any attached processes and kill any |
| processes it created. Use `monitor exit' to terminate `gdbserver' |
| at the end of a multi-process mode debug session. |
| |
| |
| 20.3.4 Tracepoints support in `gdbserver' |
| ----------------------------------------- |
| |
| On some targets, `gdbserver' supports tracepoints, fast tracepoints and |
| static tracepoints. |
| |
| For fast or static tracepoints to work, a special library called the |
| "in-process agent" (IPA), must be loaded in the inferior process. This |
| library is built and distributed as an integral part of `gdbserver'. |
| In addition, support for static tracepoints requires building the |
| in-process agent library with static tracepoints support. At present, |
| the UST (LTTng Userspace Tracer, `http://lttng.org/ust') tracing engine |
| is supported. This support is automatically available if UST |
| development headers are found in the standard include path when |
| `gdbserver' is built, or if `gdbserver' was explicitly configured using |
| `--with-ust' to point at such headers. You can explicitly disable the |
| support using `--with-ust=no'. |
| |
| There are several ways to load the in-process agent in your program: |
| |
| `Specifying it as dependency at link time' |
| You can link your program dynamically with the in-process agent |
| library. On most systems, this is accomplished by adding |
| `-linproctrace' to the link command. |
| |
| `Using the system's preloading mechanisms' |
| You can force loading the in-process agent at startup time by using |
| your system's support for preloading shared libraries. Many Unixes |
| support the concept of preloading user defined libraries. In most |
| cases, you do that by specifying `LD_PRELOAD=libinproctrace.so' in |
| the environment. See also the description of `gdbserver''s |
| `--wrapper' command line option. |
| |
| `Using GDB to force loading the agent at run time' |
| On some systems, you can force the inferior to load a shared |
| library, by calling a dynamic loader function in the inferior that |
| takes care of dynamically looking up and loading a shared library. |
| On most Unix systems, the function is `dlopen'. You'll use the |
| `call' command for that. For example: |
| |
| (gdb) call dlopen ("libinproctrace.so", ...) |
| |
| Note that on most Unix systems, for the `dlopen' function to be |
| available, the program needs to be linked with `-ldl'. |
| |
| On systems that have a userspace dynamic loader, like most Unix |
| systems, when you connect to `gdbserver' using `target remote', you'll |
| find that the program is stopped at the dynamic loader's entry point, |
| and no shared library has been loaded in the program's address space |
| yet, including the in-process agent. In that case, before being able |
| to use any of the fast or static tracepoints features, you need to let |
| the loader run and load the shared libraries. The simplest way to do |
| that is to run the program to the main procedure. E.g., if debugging a |
| C or C++ program, start `gdbserver' like so: |
| |
| $ gdbserver :9999 myprogram |
| |
| Start GDB and connect to `gdbserver' like so, and run to main: |
| |
| $ gdb myprogram |
| (gdb) target remote myhost:9999 |
| 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 |
| (gdb) b main |
| (gdb) continue |
| |
| The in-process tracing agent library should now be loaded into the |
| process; you can confirm it with the `info sharedlibrary' command, |
| which will list `libinproctrace.so' as loaded in the process. You are |
| now ready to install fast tracepoints, list static tracepoint markers, |
| probe static tracepoints markers, and start tracing. |
| |
| ---------- Footnotes ---------- |
| |
| (1) If you choose a port number that conflicts with another service, |
| `gdbserver' prints an error message and exits. |
| |
| |
| File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging |
| |
| 20.4 Remote Configuration |
| ========================= |
| |
| This section documents the configuration options available when |
| debugging remote programs. For the options related to the File I/O |
| extensions of the remote protocol, see *Note system-call-allowed: |
| system. |
| |
| `set remoteaddresssize BITS' |
| Set the maximum size of address in a memory packet to the specified |
| number of bits. GDB will mask off the address bits above that |
| number, when it passes addresses to the remote target. The |
| default value is the number of bits in the target's address. |
| |
| `show remoteaddresssize' |
| Show the current value of remote address size in bits. |
| |
| `set remotebaud N' |
| Set the baud rate for the remote serial I/O to N baud. The value |
| is used to set the speed of the serial port used for debugging |
| remote targets. |
| |
| `show remotebaud' |
| Show the current speed of the remote connection. |
| |
| `set remotebreak' |
| If set to on, GDB sends a `BREAK' signal to the remote when you |
| type `Ctrl-c' to interrupt the program running on the remote. If |
| set to off, GDB sends the `Ctrl-C' character instead. The default |
| is off, since most remote systems expect to see `Ctrl-C' as the |
| interrupt signal. |
| |
| `show remotebreak' |
| Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote |
| program. |
| |
| `set remoteflow on' |
| `set remoteflow off' |
| Enable or disable hardware flow control (`RTS'/`CTS') on the |
| serial port used to communicate to the remote target. |
| |
| `show remoteflow' |
| Show the current setting of hardware flow control. |
| |
| `set remotelogbase BASE' |
| Set the base (a.k.a. radix) of logging serial protocol |
| communications to BASE. Supported values of BASE are: `ascii', |
| `octal', and `hex'. The default is `ascii'. |
| |
| `show remotelogbase' |
| Show the current setting of the radix for logging remote serial |
| protocol. |
| |
| `set remotelogfile FILE' |
| Record remote serial communications on the named FILE. The |
| default is not to record at all. |
| |
| `show remotelogfile.' |
| Show the current setting of the file name on which to record the |
| serial communications. |
| |
| `set remotetimeout NUM' |
| Set the timeout limit to wait for the remote target to respond to |
| NUM seconds. The default is 2 seconds. |
| |
| `show remotetimeout' |
| Show the current number of seconds to wait for the remote target |
| responses. |
| |
| `set remote hardware-watchpoint-limit LIMIT' |
| `set remote hardware-breakpoint-limit LIMIT' |
| Restrict GDB to using LIMIT remote hardware breakpoint or |
| watchpoints. A limit of -1, the default, is treated as unlimited. |
| |
| `set remote hardware-watchpoint-length-limit LIMIT' |
| Restrict GDB to using LIMIT bytes for the maximum length of a |
| remote hardware watchpoint. A limit of -1, the default, is treated |
| as unlimited. |
| |
| `show remote hardware-watchpoint-length-limit' |
| Show the current limit (in bytes) of the maximum length of a |
| remote hardware watchpoint. |
| |
| `set remote exec-file FILENAME' |
| `show remote exec-file' |
| Select the file used for `run' with `target extended-remote'. |
| This should be set to a filename valid on the target system. If |
| it is not set, the target will use a default filename (e.g. the |
| last program run). |
| |
| `set remote interrupt-sequence' |
| Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g' |
| as the sequence to the remote target in order to interrupt the |
| execution. `Ctrl-C' is a default. Some system prefers `BREAK' |
| which is high level of serial line for some certain time. Linux |
| kernel prefers `BREAK-g', a.k.a Magic SysRq g. It is `BREAK' |
| signal followed by character `g'. |
| |
| `show interrupt-sequence' |
| Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to |
| interrupt the remote program. `BREAK-g' is BREAK signal followed |
| by `g' and also known as Magic SysRq g. |
| |
| `set remote interrupt-on-connect' |
| Specify whether interrupt-sequence is sent to remote target when |
| GDB connects to it. This is mostly needed when you debug Linux |
| kernel. Linux kernel expects `BREAK' followed by `g' which is |
| known as Magic SysRq g in order to connect GDB. |
| |
| `show interrupt-on-connect' |
| Show whether interrupt-sequence is sent to remote target when GDB |
| connects to it. |
| |
| `set tcp auto-retry on' |
| Enable auto-retry for remote TCP connections. This is useful if |
| the remote debugging agent is launched in parallel with GDB; there |
| is a race condition because the agent may not become ready to |
| accept the connection before GDB attempts to connect. When |
| auto-retry is enabled, if the initial attempt to connect fails, |
| GDB reattempts to establish the connection using the timeout |
| specified by `set tcp connect-timeout'. |
| |
| `set tcp auto-retry off' |
| Do not auto-retry failed TCP connections. |
| |
| `show tcp auto-retry' |
| Show the current auto-retry setting. |
| |
| `set tcp connect-timeout SECONDS' |
| Set the timeout for establishing a TCP connection to the remote |
| target to SECONDS. The timeout affects both polling to retry |
| failed connections (enabled by `set tcp auto-retry on') and |
| waiting for connections that are merely slow to complete, and |
| represents an approximate cumulative value. |
| |
| `show tcp connect-timeout' |
| Show the current connection timeout setting. |
| |
| The GDB remote protocol autodetects the packets supported by your |
| debugging stub. If you need to override the autodetection, you can use |
| these commands to enable or disable individual packets. Each packet |
| can be set to `on' (the remote target supports this packet), `off' (the |
| remote target does not support this packet), or `auto' (detect remote |
| target support for this packet). They all default to `auto'. For more |
| information about each packet, see *Note Remote Protocol::. |
| |
| During normal use, you should not have to use any of these commands. |
| If you do, that may be a bug in your remote debugging stub, or a bug in |
| GDB. You may want to report the problem to the GDB developers. |
| |
| For each packet NAME, the command to enable or disable the packet is |
| `set remote NAME-packet'. The available settings are: |
| |
| Command Name Remote Packet Related Features |
| `fetch-register' `p' `info registers' |
| `set-register' `P' `set' |
| `binary-download' `X' `load', `set' |
| `read-aux-vector' `qXfer:auxv:read' `info auxv' |
| `symbol-lookup' `qSymbol' Detecting |
| multiple threads |
| `attach' `vAttach' `attach' |
| `verbose-resume' `vCont' Stepping or |
| resuming multiple |
| threads |
| `run' `vRun' `run' |
| `software-breakpoint'`Z0' `break' |
| `hardware-breakpoint'`Z1' `hbreak' |
| `write-watchpoint' `Z2' `watch' |
| `read-watchpoint' `Z3' `rwatch' |
| `access-watchpoint' `Z4' `awatch' |
| `target-features' `qXfer:features:read' `set architecture' |
| `library-info' `qXfer:libraries:read' `info |
| sharedlibrary' |
| `memory-map' `qXfer:memory-map:read' `info mem' |
| `read-sdata-object' `qXfer:sdata:read' `print $_sdata' |
| `read-spu-object' `qXfer:spu:read' `info spu' |
| `write-spu-object' `qXfer:spu:write' `info spu' |
| `read-siginfo-object'`qXfer:siginfo:read' `print $_siginfo' |
| `write-siginfo-object'`qXfer:siginfo:write' `set $_siginfo' |
| `threads' `qXfer:threads:read' `info threads' |
| `get-thread-local- `qGetTLSAddr' Displaying |
| storage-address' `__thread' |
| variables |
| `get-thread-information-block-address'`qGetTIBAddr' Display |
| MS-Windows Thread |
| Information Block. |
| `search-memory' `qSearch:memory' `find' |
| `supported-packets' `qSupported' Remote |
| communications |
| parameters |
| `pass-signals' `QPassSignals' `handle SIGNAL' |
| `program-signals' `QProgramSignals' `handle SIGNAL' |
| `hostio-close-packet'`vFile:close' `remote get', |
| `remote put' |
| `hostio-open-packet' `vFile:open' `remote get', |
| `remote put' |
| `hostio-pread-packet'`vFile:pread' `remote get', |
| `remote put' |
| `hostio-pwrite-packet'`vFile:pwrite' `remote get', |
| `remote put' |
| `hostio-unlink-packet'`vFile:unlink' `remote delete' |
| `hostio-readlink-packet'`vFile:readlink' Host I/O |
| `noack-packet' `QStartNoAckMode' Packet |
| acknowledgment |
| `osdata' `qXfer:osdata:read' `info os' |
| `query-attached' `qAttached' Querying remote |
| process attach |
| state. |
| `traceframe-info' `qXfer:traceframe-info:read'Traceframe info |
| `install-in-trace' `InstallInTrace' Install |
| tracepoint in |
| tracing |
| `disable-randomization'`QDisableRandomization' `set |
| disable-randomization' |
| `conditional-breakpoints-packet'`Z0 and Z1' `Support for |
| target-side |
| breakpoint |
| condition |
| evaluation' |
| |
| |
| File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging |
| |
| 20.5 Implementing a Remote Stub |
| =============================== |
| |
| The stub files provided with GDB implement the target side of the |
| communication protocol, and the GDB side is implemented in the GDB |
| source file `remote.c'. Normally, you can simply allow these |
| subroutines to communicate, and ignore the details. (If you're |
| implementing your own stub file, you can still ignore the details: start |
| with one of the existing stub files. `sparc-stub.c' is the best |
| organized, and therefore the easiest to read.) |
| |
| To debug a program running on another machine (the debugging |
| "target" machine), you must first arrange for all the usual |
| prerequisites for the program to run by itself. For example, for a C |
| program, you need: |
| |
| 1. A startup routine to set up the C runtime environment; these |
| usually have a name like `crt0'. The startup routine may be |
| supplied by your hardware supplier, or you may have to write your |
| own. |
| |
| 2. A C subroutine library to support your program's subroutine calls, |
| notably managing input and output. |
| |
| 3. A way of getting your program to the other machine--for example, a |
| download program. These are often supplied by the hardware |
| manufacturer, but you may have to write your own from hardware |
| documentation. |
| |
| The next step is to arrange for your program to use a serial port to |
| communicate with the machine where GDB is running (the "host" machine). |
| In general terms, the scheme looks like this: |
| |
| _On the host,_ |
| GDB already understands how to use this protocol; when everything |
| else is set up, you can simply use the `target remote' command |
| (*note Specifying a Debugging Target: Targets.). |
| |
| _On the target,_ |
| you must link with your program a few special-purpose subroutines |
| that implement the GDB remote serial protocol. The file |
| containing these subroutines is called a "debugging stub". |
| |
| On certain remote targets, you can use an auxiliary program |
| `gdbserver' instead of linking a stub into your program. *Note |
| Using the `gdbserver' Program: Server, for details. |
| |
| The debugging stub is specific to the architecture of the remote |
| machine; for example, use `sparc-stub.c' to debug programs on SPARC |
| boards. |
| |
| These working remote stubs are distributed with GDB: |
| |
| `i386-stub.c' |
| For Intel 386 and compatible architectures. |
| |
| `m68k-stub.c' |
| For Motorola 680x0 architectures. |
| |
| `sh-stub.c' |
| For Renesas SH architectures. |
| |
| `sparc-stub.c' |
| For SPARC architectures. |
| |
| `sparcl-stub.c' |
| For Fujitsu SPARCLITE architectures. |
| |
| |
| The `README' file in the GDB distribution may list other recently |
| added stubs. |
| |
| * Menu: |
| |
| * Stub Contents:: What the stub can do for you |
| * Bootstrapping:: What you must do for the stub |
| * Debug Session:: Putting it all together |
| |
| |
| File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub |
| |
| 20.5.1 What the Stub Can Do for You |
| ----------------------------------- |
| |
| The debugging stub for your architecture supplies these three |
| subroutines: |
| |
| `set_debug_traps' |
| This routine arranges for `handle_exception' to run when your |
| program stops. You must call this subroutine explicitly in your |
| program's startup code. |
| |
| `handle_exception' |
| This is the central workhorse, but your program never calls it |
| explicitly--the setup code arranges for `handle_exception' to run |
| when a trap is triggered. |
| |
| `handle_exception' takes control when your program stops during |
| execution (for example, on a breakpoint), and mediates |
| communications with GDB on the host machine. This is where the |
| communications protocol is implemented; `handle_exception' acts as |
| the GDB representative on the target machine. It begins by |
| sending summary information on the state of your program, then |
| continues to execute, retrieving and transmitting any information |
| GDB needs, until you execute a GDB command that makes your program |
| resume; at that point, `handle_exception' returns control to your |
| own code on the target machine. |
| |
| `breakpoint' |
| Use this auxiliary subroutine to make your program contain a |
| breakpoint. Depending on the particular situation, this may be |
| the only way for GDB to get control. For instance, if your target |
| machine has some sort of interrupt button, you won't need to call |
| this; pressing the interrupt button transfers control to |
| `handle_exception'--in effect, to GDB. On some machines, simply |
| receiving characters on the serial port may also trigger a trap; |
| again, in that situation, you don't need to call `breakpoint' from |
| your own program--simply running `target remote' from the host GDB |
| session gets control. |
| |
| Call `breakpoint' if none of these is true, or if you simply want |
| to make certain your program stops at a predetermined point for the |
| start of your debugging session. |
| |
| |
| File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub |
| |
| 20.5.2 What You Must Do for the Stub |
| ------------------------------------ |
| |
| The debugging stubs that come with GDB are set up for a particular chip |
| architecture, but they have no information about the rest of your |
| debugging target machine. |
| |
| First of all you need to tell the stub how to communicate with the |
| serial port. |
| |
| `int getDebugChar()' |
| Write this subroutine to read a single character from the serial |
| port. It may be identical to `getchar' for your target system; a |
| different name is used to allow you to distinguish the two if you |
| wish. |
| |
| `void putDebugChar(int)' |
| Write this subroutine to write a single character to the serial |
| port. It may be identical to `putchar' for your target system; a |
| different name is used to allow you to distinguish the two if you |
| wish. |
| |
| If you want GDB to be able to stop your program while it is running, |
| you need to use an interrupt-driven serial driver, and arrange for it |
| to stop when it receives a `^C' (`\003', the control-C character). |
| That is the character which GDB uses to tell the remote system to stop. |
| |
| Getting the debugging target to return the proper status to GDB |
| probably requires changes to the standard stub; one quick and dirty way |
| is to just execute a breakpoint instruction (the "dirty" part is that |
| GDB reports a `SIGTRAP' instead of a `SIGINT'). |
| |
| Other routines you need to supply are: |
| |
| `void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' |
| Write this function to install EXCEPTION_ADDRESS in the exception |
| handling tables. You need to do this because the stub does not |
| have any way of knowing what the exception handling tables on your |
| target system are like (for example, the processor's table might |
| be in ROM, containing entries which point to a table in RAM). |
| EXCEPTION_NUMBER is the exception number which should be changed; |
| its meaning is architecture-dependent (for example, different |
| numbers might represent divide by zero, misaligned access, etc). |
| When this exception occurs, control should be transferred directly |
| to EXCEPTION_ADDRESS, and the processor state (stack, registers, |
| and so on) should be just as it is when a processor exception |
| occurs. So if you want to use a jump instruction to reach |
| EXCEPTION_ADDRESS, it should be a simple jump, not a jump to |
| subroutine. |
| |
| For the 386, EXCEPTION_ADDRESS should be installed as an interrupt |
| gate so that interrupts are masked while the handler runs. The |
| gate should be at privilege level 0 (the most privileged level). |
| The SPARC and 68k stubs are able to mask interrupts themselves |
| without help from `exceptionHandler'. |
| |
| `void flush_i_cache()' |
| On SPARC and SPARCLITE only, write this subroutine to flush the |
| instruction cache, if any, on your target machine. If there is no |
| instruction cache, this subroutine may be a no-op. |
| |
| On target machines that have instruction caches, GDB requires this |
| function to make certain that the state of your program is stable. |
| |
| You must also make sure this library routine is available: |
| |
| `void *memset(void *, int, int)' |
| This is the standard library function `memset' that sets an area of |
| memory to a known value. If you have one of the free versions of |
| `libc.a', `memset' can be found there; otherwise, you must either |
| obtain it from your hardware manufacturer, or write your own. |
| |
| If you do not use the GNU C compiler, you may need other standard |
| library subroutines as well; this varies from one stub to another, but |
| in general the stubs are likely to use any of the common library |
| subroutines which `GCC' generates as inline code. |
| |
| |
| File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub |
| |
| 20.5.3 Putting it All Together |
| ------------------------------ |
| |
| In summary, when your program is ready to debug, you must follow these |
| steps. |
| |
| 1. Make sure you have defined the supporting low-level routines |
| (*note What You Must Do for the Stub: Bootstrapping.): |
| `getDebugChar', `putDebugChar', |
| `flush_i_cache', `memset', `exceptionHandler'. |
| |
| 2. Insert these lines in your program's startup code, before the main |
| procedure is called: |
| |
| set_debug_traps(); |
| breakpoint(); |
| |
| On some machines, when a breakpoint trap is raised, the hardware |
| automatically makes the PC point to the instruction after the |
| breakpoint. If your machine doesn't do that, you may need to |
| adjust `handle_exception' to arrange for it to return to the |
| instruction after the breakpoint on this first invocation, so that |
| your program doesn't keep hitting the initial breakpoint instead |
| of making progress. |
| |
| 3. For the 680x0 stub only, you need to provide a variable called |
| `exceptionHook'. Normally you just use: |
| |
| void (*exceptionHook)() = 0; |
| |
| but if before calling `set_debug_traps', you set it to point to a |
| function in your program, that function is called when `GDB' |
| continues after stopping on a trap (for example, bus error). The |
| function indicated by `exceptionHook' is called with one |
| parameter: an `int' which is the exception number. |
| |
| 4. Compile and link together: your program, the GDB debugging stub for |
| your target architecture, and the supporting subroutines. |
| |
| 5. Make sure you have a serial connection between your target machine |
| and the GDB host, and identify the serial port on the host. |
| |
| 6. Download your program to your target machine (or get it there by |
| whatever means the manufacturer provides), and start it. |
| |
| 7. Start GDB on the host, and connect to the target (*note Connecting |
| to a Remote Target: Connecting.). |
| |
| |
| |
| File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top |
| |
| 21 Configuration-Specific Information |
| ************************************* |
| |
| While nearly all GDB commands are available for all native and cross |
| versions of the debugger, there are some exceptions. This chapter |
| describes things that are only available in certain configurations. |
| |
| There are three major categories of configurations: native |
| configurations, where the host and target are the same, embedded |
| operating system configurations, which are usually the same for several |
| different processor architectures, and bare embedded processors, which |
| are quite different from each other. |
| |
| * Menu: |
| |
| * Native:: |
| * Embedded OS:: |
| * Embedded Processors:: |
| * Architectures:: |
| |
| |
| File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations |
| |
| 21.1 Native |
| =========== |
| |
| This section describes details specific to particular native |
| configurations. |
| |
| * Menu: |
| |
| * HP-UX:: HP-UX |
| * BSD libkvm Interface:: Debugging BSD kernel memory images |
| * SVR4 Process Information:: SVR4 process information |
| * DJGPP Native:: Features specific to the DJGPP port |
| * Cygwin Native:: Features specific to the Cygwin port |
| * Hurd Native:: Features specific to GNU Hurd |
| * Neutrino:: Features specific to QNX Neutrino |
| * Darwin:: Features specific to Darwin |
| |
| |
| File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native |
| |
| 21.1.1 HP-UX |
| ------------ |
| |
| On HP-UX systems, if you refer to a function or variable name that |
| begins with a dollar sign, GDB searches for a user or system name |
| first, before it searches for a convenience variable. |
| |
| |
| File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native |
| |
| 21.1.2 BSD libkvm Interface |
| --------------------------- |
| |
| BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory |
| interface that provides a uniform interface for accessing kernel virtual |
| memory images, including live systems and crash dumps. GDB uses this |
| interface to allow you to debug live kernels and kernel crash dumps on |
| many native BSD configurations. This is implemented as a special `kvm' |
| debugging target. For debugging a live system, load the currently |
| running kernel into GDB and connect to the `kvm' target: |
| |
| (gdb) target kvm |
| |
| For debugging crash dumps, provide the file name of the crash dump |
| as an argument: |
| |
| (gdb) target kvm /var/crash/bsd.0 |
| |
| Once connected to the `kvm' target, the following commands are |
| available: |
| |
| `kvm pcb' |
| Set current context from the "Process Control Block" (PCB) address. |
| |
| `kvm proc' |
| Set current context from proc address. This command isn't |
| available on modern FreeBSD systems. |
| |
| |
| File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native |
| |
| 21.1.3 SVR4 Process Information |
| ------------------------------- |
| |
| Many versions of SVR4 and compatible systems provide a facility called |
| `/proc' that can be used to examine the image of a running process |
| using file-system subroutines. If GDB is configured for an operating |
| system with this facility, the command `info proc' is available to |
| report information about the process running your program, or about any |
| process running on your system. `info proc' works only on SVR4 systems |
| that include the `procfs' code. This includes, as of this writing, |
| GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not |
| HP-UX, for example. |
| |
| `info proc' |
| `info proc PROCESS-ID' |
| Summarize available information about any running process. If a |
| process ID is specified by PROCESS-ID, display information about |
| that process; otherwise display information about the program being |
| debugged. The summary includes the debugged process ID, the |
| command line used to invoke it, its current working directory, and |
| its executable file's absolute file name. |
| |
| On some systems, PROCESS-ID can be of the form `[PID]/TID' which |
| specifies a certain thread ID within a process. If the optional |
| PID part is missing, it means a thread from the process being |
| debugged (the leading `/' still needs to be present, or else GDB |
| will interpret the number as a process ID rather than a thread ID). |
| |
| `info proc mappings' |
| Report the memory address space ranges accessible in the program, |
| with information on whether the process has read, write, or |
| execute access rights to each range. On GNU/Linux systems, each |
| memory range includes the object file which is mapped to that |
| range, instead of the memory access rights to that range. |
| |
| `info proc stat' |
| `info proc status' |
| These subcommands are specific to GNU/Linux systems. They show |
| the process-related information, including the user ID and group |
| ID; how many threads are there in the process; its virtual memory |
| usage; the signals that are pending, blocked, and ignored; its |
| TTY; its consumption of system and user time; its stack size; its |
| `nice' value; etc. For more information, see the `proc' man page |
| (type `man 5 proc' from your shell prompt). |
| |
| `info proc all' |
| Show all the information about the process described under all of |
| the above `info proc' subcommands. |
| |
| `set procfs-trace' |
| This command enables and disables tracing of `procfs' API calls. |
| |
| `show procfs-trace' |
| Show the current state of `procfs' API call tracing. |
| |
| `set procfs-file FILE' |
| Tell GDB to write `procfs' API trace to the named FILE. GDB |
| appends the trace info to the previous contents of the file. The |
| default is to display the trace on the standard output. |
| |
| `show procfs-file' |
| Show the file to which `procfs' API trace is written. |
| |
| `proc-trace-entry' |
| `proc-trace-exit' |
| `proc-untrace-entry' |
| `proc-untrace-exit' |
| These commands enable and disable tracing of entries into and exits |
| from the `syscall' interface. |
| |
| `info pidlist' |
| For QNX Neutrino only, this command displays the list of all the |
| processes and all the threads within each process. |
| |
| `info meminfo' |
| For QNX Neutrino only, this command displays the list of all |
| mapinfos. |
| |
| |
| 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 |
| * PowerPC Embedded:: PowerPC Embedded |
| * PA:: HP PA 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-elf'. |
| |
| 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-elf'.) |
| |
| 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: PowerPC Embedded, 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: PA, Prev: OpenRISC 1000, 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 when GDB detects such |
| pattern in a condition expression, and the created watchpoint uses one |
| debug register (either the `exact-watchpoints' option is on and the |
| variable is scalar, or the variable has a length of one byte). This |
| feature is available in native GDB running on a Linux kernel version |
| 2.6.34 or newer. |
| |
| When running on PowerPC embedded processors, GDB automatically uses |
| ranged hardware watchpoints, unless the `exact-watchpoints' option is |
| on, in which case watchpoints using only one debug register are created |
| when watching variables of scalar types. |
| |
| You can create an artificial array to watch an arbitrary memory |
| region using one of the following commands (*note Expressions::): |
| |
| (gdb) watch *((char *) ADDRESS)@LENGTH |
| (gdb) watch {char[LENGTH]} ADDRESS |
| |
| PowerPC embedded processors support masked watchpoints. See the |
| discussion about the `mask' argument in *Note Set Watchpoints::. |
| |
| PowerPC embedded processors support hardware accelerated "ranged |
| breakpoints". A ranged breakpoint stops execution of the inferior |
| whenever it executes an instruction at any address within the range it |
| specifies. To set a ranged breakpoint in GDB, use the `break-range' |
| command. |
| |
| GDB provides the following PowerPC-specific commands: |
| |
| `break-range START-LOCATION, END-LOCATION' |
| Set a breakpoint for an address range. START-LOCATION and |
| END-LOCATION can specify a function name, a line number, an offset |
| of lines from the current line or from the start location, or an |
| address of an instruction (see *Note Specify Location::, for a |
| list of all the possible ways to specify a LOCATION.) The |
| breakpoint will stop execution of the inferior whenever it |
| executes an instruction at any address within the specified range, |
| (including START-LOCATION and END-LOCATION.) |
| |
| `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. |
| |
| `set powerpc exact-watchpoints' |
| `show powerpc exact-watchpoints' |
| Allow GDB to use only one debug register when watching a variable |
| of scalar type, thus assuming that the variable is accessed |
| through the address of its first byte. |
| |
| `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: Sparclet, Prev: PowerPC Embedded, 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: PA, 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' |
| This command is deprecated, and `info all-registers' should be |
| used instead. |
| |
| 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:: |
| * Alpha:: |
| * MIPS:: |
| * HPPA:: HP PA architecture |
| * SPU:: Cell Broadband Engine SPU architecture |
| * PowerPC:: |
| |
| |
| File: gdb.info, Node: i386, Next: Alpha, 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: Alpha, Next: MIPS, Prev: i386, Up: Architectures |
| |
| 21.4.2 Alpha |
| ------------ |
| |
| See the following section. |
| |
| |
| File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures |
| |
| 21.4.3 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' |
| |
| `show mips abi' |
| Show the MIPS ABI used by GDB to debug the inferior. |
| |
| `set mips compression ARG' |
| Tell GDB which MIPS compressed ISA (Instruction Set Architecture) |
| encoding is used by the inferior. GDB uses this for code |
| disassembly and other internal interpretation purposes. This |
| setting is only referred to when no executable has been associated |
| with the debugging session or the executable does not provide |
| information about the encoding it uses. Otherwise this setting is |
| automatically updated from information provided by the executable. |
| |
| Possible values of ARG are `mips16' and `micromips'. The default |
| compressed ISA encoding is `mips16', as executables containing |
| MIPS16 code frequently are not identified as such. |
| |
| This setting is "sticky"; that is, it retains its value across |
| debugging sessions until reset either explicitly with this command |
| or implicitly from an executable. |
| |
| The compiler and/or assembler typically add symbol table |
| annotations to identify functions compiled for the MIPS16 or |
| microMIPS ISAs. If these function-scope annotations are present, |
| GDB uses them in preference to the global compressed ISA encoding |
| setting. |
| |
| `show mips compression' |
| Show the MIPS compressed ISA encoding 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.4 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.5 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.6 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 |
| * Auto-loading:: Automatically loading associated files |
| * 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' |
| |
| Versions of GDB that ship with Python scripting enabled have prompt |
| extensions. The commands for interacting with these extensions are: |
| |
| `set extended-prompt PROMPT' |
| Set an extended prompt that allows for substitutions. *Note |
| gdb.prompt::, for a list of escape sequences that can be used for |
| substitution. Any escape sequences specified as part of the prompt |
| string are replaced with the corresponding strings each time the |
| prompt is displayed. |
| |
| For example: |
| |
| set extended-prompt Current working directory: \w (gdb) |
| |
| Note that when an extended-prompt is set, it takes control of the |
| PROMPT_HOOK hook. *Note prompt_hook::, for further information. |
| |
| `show extended-prompt' |
| Prints the extended prompt. Any escape sequences specified as |
| part of the prompt string with `set extended-prompt', are replaced |
| with the corresponding strings each time the prompt is displayed. |
| |
| |
| 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: Auto-loading, 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: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up: Controlling GDB |
| |
| 22.7 Automatically loading associated files |
| =========================================== |
| |
| GDB sometimes reads files with commands and settings automatically, |
| without being explicitly told so by the user. We call this feature |
| "auto-loading". While auto-loading is useful for automatically adapting |
| GDB to the needs of your project, it can sometimes produce unexpected |
| results or introduce security risks (e.g., if the file comes from |
| untrusted sources). |
| |
| Note that loading of these associated files (including the local |
| `.gdbinit' file) requires accordingly configured `auto-load safe-path' |
| (*note Auto-loading safe path::). |
| |
| For these reasons, GDB includes commands and options to let you |
| control when to auto-load files and which files should be auto-loaded. |
| |
| `set auto-load off' |
| Globally disable loading of all auto-loaded files. You may want |
| to use this command with the `-iex' option (*note Option |
| -init-eval-command::) such as: |
| $ gdb -iex "set auto-load off" untrusted-executable corefile |
| |
| Be aware that system init file (*note System-wide configuration::) |
| and init files from your home directory (*note Home Directory Init |
| File::) still get read (as they come from generally trusted |
| directories). To prevent GDB from auto-loading even those init |
| files, use the `-nx' option (*note Mode Options::), in addition to |
| `set auto-load no'. |
| |
| `show auto-load' |
| Show whether auto-loading of each specific `auto-load' file(s) is |
| enabled or disabled. |
| |
| (gdb) show auto-load |
| gdb-scripts: Auto-loading of canned sequences of commands scripts is on. |
| libthread-db: Auto-loading of inferior specific libthread_db is on. |
| local-gdbinit: Auto-loading of .gdbinit script from current directory |
| is on. |
| python-scripts: Auto-loading of Python scripts is on. |
| safe-path: List of directories from which it is safe to auto-load files |
| is $debugdir:$datadir/auto-load. |
| scripts-directory: List of directories from which to load auto-loaded scripts |
| is $debugdir:$datadir/auto-load. |
| |
| `info auto-load' |
| Print whether each specific `auto-load' file(s) have been |
| auto-loaded or not. |
| |
| (gdb) info auto-load |
| gdb-scripts: |
| Loaded Script |
| Yes /home/user/gdb/gdb-gdb.gdb |
| libthread-db: No auto-loaded libthread-db. |
| local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been |
| loaded. |
| python-scripts: |
| Loaded Script |
| Yes /home/user/gdb/gdb-gdb.py |
| |
| These are various kinds of files GDB can automatically load: |
| |
| * *Note objfile-gdb.py file::, controlled by *Note set auto-load |
| python-scripts::. |
| |
| * *Note objfile-gdb.gdb file::, controlled by *Note set auto-load |
| gdb-scripts::. |
| |
| * *Note dotdebug_gdb_scripts section::, controlled by *Note set |
| auto-load python-scripts::. |
| |
| * *Note Init File in the Current Directory::, controlled by *Note |
| set auto-load local-gdbinit::. |
| |
| * *Note libthread_db.so.1 file::, controlled by *Note set auto-load |
| libthread-db::. |
| |
| These are GDB control commands for the auto-loading: |
| |
| *Note set auto-load off::. Disable auto-loading globally. |
| *Note show auto-load::. Show setting of all kinds of files. |
| *Note info auto-load::. Show state of all kinds of files. |
| *Note set auto-load gdb-scripts::. Control for GDB command scripts. |
| *Note show auto-load gdb-scripts::. Show setting of GDB command scripts. |
| *Note info auto-load gdb-scripts::. Show state of GDB command scripts. |
| *Note set auto-load Control for GDB Python scripts. |
| python-scripts::. |
| *Note show auto-load Show setting of GDB Python scripts. |
| python-scripts::. |
| *Note info auto-load Show state of GDB Python scripts. |
| python-scripts::. |
| *Note set auto-load Control for GDB auto-loaded scripts |
| scripts-directory::. location. |
| *Note show auto-load Show GDB auto-loaded scripts |
| scripts-directory::. location. |
| *Note set auto-load local-gdbinit::. Control for init file in the |
| current directory. |
| *Note show auto-load Show setting of init file in the |
| local-gdbinit::. current directory. |
| *Note info auto-load Show state of init file in the |
| local-gdbinit::. current directory. |
| *Note set auto-load libthread-db::. Control for thread debugging |
| library. |
| *Note show auto-load libthread-db::. Show setting of thread debugging |
| library. |
| *Note info auto-load libthread-db::. Show state of thread debugging |
| library. |
| *Note set auto-load safe-path::. Control directories trusted for |
| automatic loading. |
| *Note show auto-load safe-path::. Show directories trusted for |
| automatic loading. |
| *Note add-auto-load-safe-path::. Add directory trusted for automatic |
| loading. |
| |
| * Menu: |
| |
| * Init File in the Current Directory:: `set/show/info auto-load local-gdbinit' |
| * libthread_db.so.1 file:: `set/show/info auto-load libthread-db' |
| * objfile-gdb.gdb file:: `set/show/info auto-load gdb-script' |
| * Auto-loading safe path:: `set/show/info auto-load safe-path' |
| * Auto-loading verbose mode:: `set/show debug auto-load' |
| *Note Python Auto-loading::. |
| |
| |
| File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.so.1 file, Up: Auto-loading |
| |
| 22.7.1 Automatically loading init file in the current directory |
| --------------------------------------------------------------- |
| |
| By default, GDB reads and executes the canned sequences of commands |
| from init file (if any) in the current working directory, see *Note |
| Init File in the Current Directory during Startup::. |
| |
| Note that loading of this local `.gdbinit' file also requires |
| accordingly configured `auto-load safe-path' (*note Auto-loading safe |
| path::). |
| |
| `set auto-load local-gdbinit [on|off]' |
| Enable or disable the auto-loading of canned sequences of commands |
| (*note Sequences::) found in init file in the current directory. |
| |
| `show auto-load local-gdbinit' |
| Show whether auto-loading of canned sequences of commands from |
| init file in the current directory is enabled or disabled. |
| |
| `info auto-load local-gdbinit' |
| Print whether canned sequences of commands from init file in the |
| current directory have been auto-loaded. |
| |
| |
| File: gdb.info, Node: libthread_db.so.1 file, Next: objfile-gdb.gdb file, Prev: Init File in the Current Directory, Up: Auto-loading |
| |
| 22.7.2 Automatically loading thread debugging library |
| ----------------------------------------------------- |
| |
| This feature is currently present only on GNU/Linux native hosts. |
| |
| GDB reads in some cases thread debugging library from places specific |
| to the inferior (*note set libthread-db-search-path::). |
| |
| The special `libthread-db-search-path' entry `$sdir' is processed |
| without checking this `set auto-load libthread-db' switch as system |
| libraries have to be trusted in general. In all other cases of |
| `libthread-db-search-path' entries GDB checks first if `set auto-load |
| libthread-db' is enabled before trying to open such thread debugging |
| library. |
| |
| Note that loading of this debugging library also requires |
| accordingly configured `auto-load safe-path' (*note Auto-loading safe |
| path::). |
| |
| `set auto-load libthread-db [on|off]' |
| Enable or disable the auto-loading of inferior specific thread |
| debugging library. |
| |
| `show auto-load libthread-db' |
| Show whether auto-loading of inferior specific thread debugging |
| library is enabled or disabled. |
| |
| `info auto-load libthread-db' |
| Print the list of all loaded inferior specific thread debugging |
| libraries and for each such library print list of inferior PIDs |
| using it. |
| |
| |
| File: gdb.info, Node: objfile-gdb.gdb file, Next: Auto-loading safe path, Prev: libthread_db.so.1 file, Up: Auto-loading |
| |
| 22.7.3 The `OBJFILE-gdb.gdb' file |
| --------------------------------- |
| |
| GDB tries to load an `OBJFILE-gdb.gdb' file containing canned sequences |
| of commands (*note Sequences::), as long as `set auto-load gdb-scripts' |
| is set to `on'. |
| |
| Note that loading of this script file also requires accordingly |
| configured `auto-load safe-path' (*note Auto-loading safe path::). |
| |
| For more background refer to the similar Python scripts auto-loading |
| description (*note objfile-gdb.py file::). |
| |
| `set auto-load gdb-scripts [on|off]' |
| Enable or disable the auto-loading of canned sequences of commands |
| scripts. |
| |
| `show auto-load gdb-scripts' |
| Show whether auto-loading of canned sequences of commands scripts |
| is enabled or disabled. |
| |
| `info auto-load gdb-scripts [REGEXP]' |
| Print the list of all canned sequences of commands scripts that |
| GDB auto-loaded. |
| |
| If REGEXP is supplied only canned sequences of commands scripts with |
| matching names are printed. |
| |
| |
| File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode, Prev: objfile-gdb.gdb file, Up: Auto-loading |
| |
| 22.7.4 Security restriction for auto-loading |
| -------------------------------------------- |
| |
| As the files of inferior can come from untrusted source (such as |
| submitted by an application user) GDB does not always load any files |
| automatically. GDB provides the `set auto-load safe-path' setting to |
| list directories trusted for loading files not explicitly requested by |
| user. Each directory can also be a shell wildcard pattern. |
| |
| If the path is not set properly you will see a warning and the file |
| will not get loaded: |
| |
| $ ./gdb -q ./gdb |
| Reading symbols from /home/user/gdb/gdb...done. |
| warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been |
| declined by your `auto-load safe-path' set |
| to "$debugdir:$datadir/auto-load". |
| warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been |
| declined by your `auto-load safe-path' set |
| to "$debugdir:$datadir/auto-load". |
| |
| The list of trusted directories is controlled by the following |
| commands: |
| |
| `set auto-load safe-path [DIRECTORIES]' |
| Set the list of directories (and their subdirectories) trusted for |
| automatic loading and execution of scripts. You can also enter a |
| specific trusted file. Each directory can also be a shell |
| wildcard pattern; wildcards do not match directory separator - see |
| `FNM_PATHNAME' for system function `fnmatch' (*note fnmatch: |
| (libc)Wildcard Matching.). If you omit DIRECTORIES, `auto-load |
| safe-path' will be reset to its default value as specified during |
| GDB compilation. |
| |
| The list of directories uses path separator (`:' on GNU and Unix |
| systems, `;' on MS-Windows and MS-DOS) to separate directories, |
| similarly to the `PATH' environment variable. |
| |
| `show auto-load safe-path' |
| Show the list of directories trusted for automatic loading and |
| execution of scripts. |
| |
| `add-auto-load-safe-path' |
| Add an entry (or list of entries) the list of directories trusted |
| for automatic loading and execution of scripts. Multiple entries |
| may be delimited by the host platform path separator in use. |
| |
| This variable defaults to what `--with-auto-load-dir' has been |
| configured to (*note with-auto-load-dir::). `$debugdir' and `$datadir' |
| substitution applies the same as for *Note set auto-load |
| scripts-directory::. The default `set auto-load safe-path' value can |
| be also overriden by GDB configuration option |
| `--with-auto-load-safe-path'. |
| |
| Setting this variable to `/' disables this security protection, |
| corresponding GDB configuration option is |
| `--without-auto-load-safe-path'. This variable is supposed to be set |
| to the system directories writable by the system superuser only. Users |
| can add their source directories in init files in their home |
| directories (*note Home Directory Init File::). See also deprecated |
| init file in the current directory (*note Init File in the Current |
| Directory during Startup::). |
| |
| To force GDB to load the files it declined to load in the previous |
| example, you could use one of the following ways: |
| |
| `~/.gdbinit': `add-auto-load-safe-path ~/src/gdb' |
| Specify this trusted directory (or a file) as additional component |
| of the list. You have to specify also any existing directories |
| displayed by by `show auto-load safe-path' (such as `/usr:/bin' in |
| this example). |
| |
| `gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...' |
| Specify this directory as in the previous case but just for a |
| single GDB session. |
| |
| `gdb -iex "set auto-load safe-path /" ...' |
| Disable auto-loading safety for a single GDB session. This |
| assumes all the files you debug during this GDB session will come |
| from trusted sources. |
| |
| `./configure --without-auto-load-safe-path' |
| During compilation of GDB you may disable any auto-loading safety. |
| This assumes all the files you will ever debug with this GDB come |
| from trusted sources. |
| |
| On the other hand you can also explicitly forbid automatic files |
| loading which also suppresses any such warning messages: |
| |
| `gdb -iex "set auto-load no" ...' |
| You can use GDB command-line option for a single GDB session. |
| |
| `~/.gdbinit': `set auto-load no' |
| Disable auto-loading globally for the user (*note Home Directory |
| Init File::). While it is improbable, you could also use system |
| init file instead (*note System-wide configuration::). |
| |
| This setting applies to the file names as entered by user. If no |
| entry matches GDB tries as a last resort to also resolve all the file |
| names into their canonical form (typically resolving symbolic links) |
| and compare the entries again. GDB already canonicalizes most of the |
| filenames on its own before starting the comparison so a canonical form |
| of directories is recommended to be entered. |
| |
| |
| File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path, Up: Auto-loading |
| |
| 22.7.5 Displaying files tried for auto-load |
| ------------------------------------------- |
| |
| For better visibility of all the file locations where you can place |
| scripts to be auto-loaded with inferior -- or to protect yourself |
| against accidental execution of untrusted scripts -- GDB provides a |
| feature for printing all the files attempted to be loaded. Both |
| existing and non-existing files may be printed. |
| |
| For example the list of directories from which it is safe to |
| auto-load files (*note Auto-loading safe path::) applies also to |
| canonicalized filenames which may not be too obvious while setting it |
| up. |
| |
| (gdb) set debug auto-load on |
| (gdb) file ~/src/t/true |
| auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" |
| for objfile "/tmp/true". |
| auto-load: Updating directories of "/usr:/opt". |
| auto-load: Using directory "/usr". |
| auto-load: Using directory "/opt". |
| warning: File "/tmp/true-gdb.gdb" auto-loading has been declined |
| by your `auto-load safe-path' set to "/usr:/opt". |
| |
| `set debug auto-load [on|off]' |
| Set whether to print the filenames attempted to be auto-loaded. |
| |
| `show debug auto-load' |
| Show whether printing of the filenames attempted to be auto-loaded |
| is turned on or off. |
| |
| |
| File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-loading, Up: Controlling GDB |
| |
| 22.8 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.9 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 check-physname' |
| Check the results of the "physname" computation. When reading |
| DWARF debugging information for C++, GDB attempts to compute each |
| entity's name. GDB can do this computation in two different ways, |
| depending on exactly what information is present. When enabled, |
| this setting causes GDB to compute the names both ways and display |
| any discrepancies. |
| |
| `show debug check-physname' |
| Show the current state of "physname" checking. |
| |
| `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 dwarf2-read' |
| Turns on or off display of debugging messages related to reading |
| DWARF debug info. The default is off. |
| |
| `show debug dwarf2-read' |
| Show the current state of DWARF2 reader 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 jit' |
| Turns on or off debugging messages from JIT debug support. |
| |
| `show debug jit' |
| Displays the current state of GDB JIT 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 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 symtab-create' |
| Turns on or off display of debugging messages related to symbol |
| table creation. The default is off. |
| |
| `show debug symtab-create' |
| Show the current state of symbol table creation debugging. |
| |
| `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.10 Other Miscellaneous Settings |
| ================================== |
| |
| `set interactive-mode' |
| If `on', forces GDB to assume that GDB was started in a terminal. |
| In practice, this means that GDB should wait for the user to |
| answer queries generated by commands entered at the command |
| prompt. If `off', forces GDB to operate in the opposite mode, and |
| it uses the default answers to all queries. If `auto' (the |
| default), GDB tries to determine whether its standard input is a |
| terminal, and works in interactive-mode if it is, |
| non-interactively otherwise. |
| |
| 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 three mechanisms for extension. The first is based on |
| composition of GDB commands, the second is based on the Python |
| scripting language, and the third is for defining new aliases of |
| existing commands. |
| |
| To facilitate the use of the first two 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 |
| * Aliases:: Creating new spellings of existing commands |
| |
| |
| 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 and all python commands defined in |
| class COMAND_USER. The first line of the documentation or |
| docstring is included (if any). |
| |
| `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. This does not work for |
| user-defined python 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. This does not apply to |
| user-defined python commands. |
| |
| 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, Next: Aliases, 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. |
| |
| Additionally, GDB commands and convenience functions which are |
| written in Python and are located in the |
| `DATA-DIRECTORY/python/gdb/command' or |
| `DATA-DIRECTORY/python/gdb/function' directories are automatically |
| imported when GDB starts. |
| |
| * Menu: |
| |
| * Python Commands:: Accessing Python from GDB. |
| * Python API:: Accessing GDB from Python. |
| * Python Auto-loading:: Automatically loading Python code. |
| * Python modules:: Python modules provided by GDB. |
| |
| |
| 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 |
| |
| `set python print-stack' |
| By default, GDB will print only the message component of a Python |
| exception when an error occurs in a Python script. This can be |
| controlled using `set python print-stack': if `full', then full |
| Python stack printing is enabled; if `none', then Python stack and |
| message printing is disabled; if `message', the default, only the |
| message component of the error is printed. |
| |
| 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: Python 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:: How Python exceptions are translated. |
| * Values From Inferior:: Python representation of values. |
| * Types In Python:: Python representation of types. |
| * Pretty Printing API:: Pretty-printing values. |
| * Selecting Pretty-Printers:: How GDB chooses a pretty-printer. |
| * Writing a Pretty-Printer:: Writing a Pretty-Printer. |
| * Inferiors In Python:: Python representation of inferiors (processes) |
| * Events In Python:: Listening for events from GDB. |
| * 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. |
| * Breakpoints In Python:: Manipulating breakpoints using Python. |
| * Finish Breakpoints in Python:: Setting Breakpoints on function return |
| using Python. |
| * Lazy Strings In Python:: Python representation of lazy strings. |
| |
| |
| 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: gdb.PYTHONDIR |
| A string containing the python directory (*note Python::). |
| |
| -- Function: gdb.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: gdb.breakpoints () |
| Return a sequence holding all of GDB's breakpoints. *Note |
| Breakpoints In Python::, for more information. |
| |
| -- Function: gdb.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 |
| `gdb.error' (*note Exception Handling::). Otherwise, the |
| parameter's value is converted to a Python value of the appropriate |
| type, and returned. |
| |
| -- Function: gdb.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 `gdb.error' exception will be raised. |
| |
| If no exception is raised, the return value is always an instance |
| of `gdb.Value' (*note Values From Inferior::). |
| |
| -- Function: gdb.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: gdb.find_pc_line (pc) |
| Return the `gdb.Symtab_and_line' object corresponding to the PC |
| value. *Note Symbol Tables In Python::. If an invalid value of |
| PC is passed as an argument, then the `symtab' and `line' |
| attributes of the returned `gdb.Symtab_and_line' object will be |
| `None' and 0 respectively. |
| |
| -- Function: gdb.post_event (event) |
| Put EVENT, a callable object taking no arguments, into GDB's |
| internal event queue. This callable will be invoked at some later |
| point, during GDB's event processing. Events posted using |
| `post_event' will be run in the order in which they were posted; |
| however, there is no way to know when they will be processed |
| relative to other events inside GDB. |
| |
| GDB is not thread-safe. If your Python program uses multiple |
| threads, you must be careful to only call GDB-specific functions |
| in the main GDB thread. `post_event' ensures this. For example: |
| |
| (gdb) python |
| >import threading |
| > |
| >class Writer(): |
| > def __init__(self, message): |
| > self.message = message; |
| > def __call__(self): |
| > gdb.write(self.message) |
| > |
| >class MyThread1 (threading.Thread): |
| > def run (self): |
| > gdb.post_event(Writer("Hello ")) |
| > |
| >class MyThread2 (threading.Thread): |
| > def run (self): |
| > gdb.post_event(Writer("World\n")) |
| > |
| >MyThread1().start() |
| >MyThread2().start() |
| >end |
| (gdb) Hello World |
| |
| -- Function: gdb.write (string [, stream]) |
| Print a string to GDB's paginated output stream. The optional |
| STREAM determines the stream to print to. The default stream is |
| GDB's standard output stream. Possible stream values are: |
| |
| `gdb.STDOUT' |
| GDB's standard output stream. |
| |
| `gdb.STDERR' |
| GDB's standard error stream. |
| |
| `gdb.STDLOG' |
| GDB's log stream (*note Logging Output::). |
| |
| Writing to `sys.stdout' or `sys.stderr' will automatically call |
| this function and will automatically direct the output to the |
| relevant stream. |
| |
| -- Function: gdb.flush () |
| Flush the buffer of a GDB paginated stream so that the contents |
| are displayed immediately. GDB will flush the contents of a |
| stream automatically when it encounters a newline in the buffer. |
| The optional STREAM determines the stream to flush. The default |
| stream is GDB's standard output stream. Possible stream values |
| are: |
| |
| `gdb.STDOUT' |
| GDB's standard output stream. |
| |
| `gdb.STDERR' |
| GDB's standard error stream. |
| |
| `gdb.STDLOG' |
| GDB's log stream (*note Logging Output::). |
| |
| |
| Flushing `sys.stdout' or `sys.stderr' will automatically call this |
| function for the relevant stream. |
| |
| -- Function: gdb.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: gdb.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. |
| |
| -- Function: gdb.solib_name (address) |
| Return the name of the shared library holding the given ADDRESS as |
| a string, or `None'. |
| |
| -- Function: gdb.decode_line [expression] |
| Return locations of the line specified by EXPRESSION, or of the |
| current line if no argument was given. This function returns a |
| Python tuple containing two elements. The first element contains |
| a string holding any unparsed section of EXPRESSION (or `None' if |
| the expression has been fully parsed). The second element contains |
| either `None' or another tuple that contains all the locations |
| that match the expression represented as `gdb.Symtab_and_line' |
| objects (*note Symbol Tables In Python::). If EXPRESSION is |
| provided, it is decoded the way that GDB's inbuilt `break' or |
| `edit' commands do (*note Specify Location::). |
| |
| -- Function: gdb.prompt_hook (current_prompt) |
| If PROMPT_HOOK is callable, GDB will call the method assigned to |
| this operation before a prompt is displayed by GDB. |
| |
| The parameter `current_prompt' contains the current GDB prompt. |
| This method must return a Python string, or `None'. If a string |
| is returned, the GDB prompt will be set to that string. If `None' |
| is returned, GDB will continue to use the current prompt. |
| |
| Some prompts cannot be substituted in GDB. Secondary prompts such |
| as those used by readline for command input, and annotation |
| related prompts are prohibited from being changed. |
| |
| |
| 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 exceptions. The type of the Python exception |
| depends on the error. |
| |
| `gdb.error' |
| This is the base class for most exceptions generated by GDB. It |
| is derived from `RuntimeError', for compatibility with earlier |
| versions of GDB. |
| |
| If an error occurring in GDB does not fit into some more specific |
| category, then the generated exception will have this type. |
| |
| `gdb.MemoryError' |
| This is a subclass of `gdb.error' which is thrown when an |
| operation tried to access invalid memory in the inferior. |
| |
| `KeyboardInterrupt' |
| User interrupt (via `C-c' or by typing `q' at a pagination prompt) |
| is translated to a Python `KeyboardInterrupt' exception. |
| |
| In all cases, your exception handler will see 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_USER) |
| > 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. |
| |
| A `gdb.Value' that represents a function can be executed via |
| inferior function call. Any arguments provided to the call must match |
| the function's prototype, and must be provided in the order specified |
| by that prototype. |
| |
| For example, `some_val' is a `gdb.Value' instance representing a |
| function that takes two integers as arguments. To execute this |
| function, call it like so: |
| |
| result = some_val (10,20) |
| |
| Any values returned from a function call will be stored as a |
| `gdb.Value'. |
| |
| The following attributes are provided: |
| |
| -- Variable: Value.address |
| If this object is addressable, this read-only attribute holds |
| a `gdb.Value' object representing the address. Otherwise, |
| this attribute holds `None'. |
| |
| -- Variable: 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. |
| |
| -- Variable: Value.type |
| The type of this `gdb.Value'. The value of this attribute is |
| a `gdb.Type' object (*note Types In Python::). |
| |
| -- Variable: Value.dynamic_type |
| The dynamic type of this `gdb.Value'. This uses C++ run-time |
| type information (RTTI) to determine the dynamic type of the |
| value. If this value is of class type, it will return the |
| class in which the value is embedded, if any. If this value |
| is of pointer or reference to a class type, it will compute |
| the dynamic type of the referenced object, and return a |
| pointer or reference to that type, respectively. In all |
| other cases, it will return the value's static type. |
| |
| Note that this feature will only work when debugging a C++ |
| program that includes RTTI for the object in question. |
| Otherwise, it will just return the static type of the value |
| as in `ptype foo' (*note ptype: Symbols.). |
| |
| -- Variable: Value.is_lazy |
| The value of this read-only boolean attribute is `True' if |
| this `gdb.Value' has not yet been fetched from the inferior. |
| GDB does not fetch values until necessary, for efficiency. |
| For example: |
| |
| myval = gdb.parse_and_eval ('somevar') |
| |
| The value of `somevar' is not fetched at this time. It will |
| be fetched when the value is needed, or when the `fetch_lazy' |
| method is invoked. |
| |
| The following methods are provided: |
| |
| -- Function: Value.__init__ (VAL) |
| Many Python values can be converted directly to a `gdb.Value' |
| via this object initializer. Specifically: |
| |
| Python boolean |
| A Python boolean is converted to the boolean type from |
| the current language. |
| |
| Python integer |
| A Python integer is converted to the C `long' type for |
| the current architecture. |
| |
| Python long |
| A Python long is converted to the C `long long' type for |
| the current architecture. |
| |
| Python float |
| A Python float is converted to the C `double' type for |
| the current architecture. |
| |
| Python string |
| A Python string is converted to a target string, using |
| the current target encoding. |
| |
| `gdb.Value' |
| If `val' is a `gdb.Value', then a copy of the value is |
| made. |
| |
| `gdb.LazyString' |
| If `val' is a `gdb.LazyString' (*note Lazy Strings In |
| Python::), then the lazy string's `value' method is |
| called, and its result is used. |
| |
| -- Function: 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. |
| |
| -- Function: 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'. |
| |
| A similar function `Value.referenced_value' exists which also |
| returns `gdb.Value' objects corresonding to the values |
| pointed to by pointer values (and additionally, values |
| referenced by reference values). However, the behavior of |
| `Value.dereference' differs from `Value.referenced_value' by |
| the fact that the behavior of `Value.dereference' is |
| identical to applying the C unary operator `*' on a given |
| value. For example, consider a reference to a pointer |
| `ptrref', declared in your C++ program as |
| |
| typedef int *intptr; |
| ... |
| int val = 10; |
| intptr ptr = &val; |
| intptr &ptrref = ptr; |
| |
| Though `ptrref' is a reference value, one can apply the method |
| `Value.dereference' to the `gdb.Value' object corresponding |
| to it and obtain a `gdb.Value' which is identical to that |
| corresponding to `val'. However, if you apply the method |
| `Value.referenced_value', the result would be a `gdb.Value' |
| object identical to that corresponding to `ptr'. |
| |
| py_ptrref = gdb.parse_and_eval ("ptrref") |
| py_val = py_ptrref.dereference () |
| py_ptr = py_ptrref.referenced_value () |
| |
| The `gdb.Value' object `py_val' is identical to that |
| corresponding to `val', and `py_ptr' is identical to that |
| corresponding to `ptr'. In general, `Value.dereference' can |
| be applied whenever the C unary operator `*' can be applied |
| to the corresponding C value. For those cases where applying |
| both `Value.dereference' and `Value.referenced_value' is |
| allowed, the results obtained need not be identical (as we |
| have seen in the above example). The results are however |
| identical when applied on `gdb.Value' objects corresponding |
| to pointers (`gdb.Value' objects with type code |
| `TYPE_CODE_PTR') in a C/C++ program. |
| |
| -- Function: Value.referenced_value () |
| For pointer or reference data types, this method returns a new |
| `gdb.Value' object corresponding to the value referenced by |
| the pointer/reference value. For pointer data types, |
| `Value.dereference' and `Value.referenced_value' produce |
| identical results. The difference between these methods is |
| that `Value.dereference' cannot get the values referenced by |
| reference values. For example, consider a reference to an |
| `int', declared in your C++ program as |
| |
| int val = 10; |
| int &ref = val; |
| |
| then applying `Value.dereference' to the `gdb.Value' object |
| corresponding to `ref' will result in an error, while applying |
| `Value.referenced_value' will result in a `gdb.Value' object |
| identical to that corresponding to `val'. |
| |
| py_ref = gdb.parse_and_eval ("ref") |
| er_ref = py_ref.dereference () # Results in error |
| py_val = py_ref.referenced_value () # Returns the referenced value |
| |
| The `gdb.Value' object `py_val' is identical to that |
| corresponding to `val'. |
| |
| -- Function: Value.dynamic_cast (type) |
| Like `Value.cast', but works as if the C++ `dynamic_cast' |
| operator were used. Consult a C++ reference for details. |
| |
| -- Function: Value.reinterpret_cast (type) |
| Like `Value.cast', but works as if the C++ `reinterpret_cast' |
| operator were used. Consult a C++ reference for details. |
| |
| -- Function: 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. |
| |
| -- Function: 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. |
| |
| -- Function: Value.fetch_lazy () |
| If the `gdb.Value' object is currently a lazy value |
| (`gdb.Value.is_lazy' is `True'), then the value is fetched |
| from the inferior. Any errors that occur in the process will |
| produce a Python exception. |
| |
| If the `gdb.Value' object is not a lazy value, this method |
| has no effect. |
| |
| This method does not return a value. |
| |
| |
| |
| 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: gdb.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. |
| |
| If the type is a structure or class type, or an enum type, the fields |
| of that type can be accessed using the Python "dictionary syntax". For |
| example, if `some_type' is a `gdb.Type' instance holding a structure |
| type, you can access its `foo' field with: |
| |
| bar = some_type['foo'] |
| |
| `bar' will be a `gdb.Field' object; see below under the description |
| of the `Type.fields' method for a description of the `gdb.Field' class. |
| |
| An instance of `Type' has the following attributes: |
| |
| -- Variable: Type.code |
| The type code for this type. The type code will be one of the |
| `TYPE_CODE_' constants defined below. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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: |
| |
| -- Function: 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 a `gdb.Field' 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. For `enum' fields, the |
| value is the enumeration member's integer representation. |
| |
| `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. |
| |
| -- Function: Type.array (N1 [, N2]) |
| Return a new `gdb.Type' object which represents an array of |
| this type. If one argument is given, it is the inclusive |
| upper bound of the array; in this case the lower bound is |
| zero. If two arguments are given, the first argument is the |
| lower bound of the array, and the second argument is the |
| upper bound of the array. An array's length must not be |
| negative, but the bounds can be. |
| |
| -- Function: Type.const () |
| Return a new `gdb.Type' object which represents a |
| `const'-qualified variant of this type. |
| |
| -- Function: Type.volatile () |
| Return a new `gdb.Type' object which represents a |
| `volatile'-qualified variant of this type. |
| |
| -- Function: 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'. |
| |
| -- Function: 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 |
| `gdb.error' exception (*note Exception Handling::). |
| |
| -- Function: Type.reference () |
| Return a new `gdb.Type' object which represents a reference |
| to this type. |
| |
| -- Function: Type.pointer () |
| Return a new `gdb.Type' object which represents a pointer to |
| this type. |
| |
| -- Function: Type.strip_typedefs () |
| Return a new `gdb.Type' that represents the real type, after |
| removing all layers of typedefs. |
| |
| -- Function: 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. |
| |
| -- Function: 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: |
| |
| `gdb.TYPE_CODE_PTR' |
| The type is a pointer. |
| |
| `gdb.TYPE_CODE_ARRAY' |
| The type is an array. |
| |
| `gdb.TYPE_CODE_STRUCT' |
| The type is a structure. |
| |
| `gdb.TYPE_CODE_UNION' |
| The type is a union. |
| |
| `gdb.TYPE_CODE_ENUM' |
| The type is an enum. |
| |
| `gdb.TYPE_CODE_FLAGS' |
| A bit flags type, used for things such as status registers. |
| |
| `gdb.TYPE_CODE_FUNC' |
| The type is a function. |
| |
| `gdb.TYPE_CODE_INT' |
| The type is an integer type. |
| |
| `gdb.TYPE_CODE_FLT' |
| A floating point type. |
| |
| `gdb.TYPE_CODE_VOID' |
| The special type `void'. |
| |
| `gdb.TYPE_CODE_SET' |
| A Pascal set type. |
| |
| `gdb.TYPE_CODE_RANGE' |
| A range type, that is, an integer type with bounds. |
| |
| `gdb.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. |
| |
| `gdb.TYPE_CODE_BITSTRING' |
| A string of bits. |
| |
| `gdb.TYPE_CODE_ERROR' |
| An unknown or erroneous type. |
| |
| `gdb.TYPE_CODE_METHOD' |
| A method type, as found in C++ or Java. |
| |
| `gdb.TYPE_CODE_METHODPTR' |
| A pointer-to-member-function. |
| |
| `gdb.TYPE_CODE_MEMBERPTR' |
| A pointer-to-member. |
| |
| `gdb.TYPE_CODE_REF' |
| A reference type. |
| |
| `gdb.TYPE_CODE_CHAR' |
| A character type. |
| |
| `gdb.TYPE_CODE_BOOL' |
| A boolean type. |
| |
| `gdb.TYPE_CODE_COMPLEX' |
| A complex float type. |
| |
| `gdb.TYPE_CODE_TYPEDEF' |
| A typedef to some other type. |
| |
| `gdb.TYPE_CODE_NAMESPACE' |
| A C++ namespace. |
| |
| `gdb.TYPE_CODE_DECFLOAT' |
| A decimal floating point type. |
| |
| `gdb.TYPE_CODE_INTERNAL_FUNCTION' |
| A function internal to GDB. This is the type used to represent |
| convenience functions. |
| |
| Further support for types is provided in the `gdb.types' Python |
| module (*note gdb.types::). |
| |
| |
| 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. |
| |
| -- Function: 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. |
| |
| -- Function: 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. |
| |
| -- Function: 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: gdb.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: Writing a Pretty-Printer, 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. Printers in this list are called `global' printers, |
| they're available when debugging all inferiors. Each `gdb.Progspace' |
| contains a `pretty_printers' attribute. Each `gdb.Objfile' also |
| contains a `pretty_printers' attribute. |
| |
| Each function on 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 lookup routine 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. |
| |
| 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: Writing a Pretty-Printer, Next: Inferiors In Python, Prev: Selecting Pretty-Printers, Up: Python API |
| |
| 23.2.2.7 Writing a Pretty-Printer |
| ................................. |
| |
| A pretty-printer consists of two parts: a lookup function to detect if |
| the type is supported, and the printer itself. |
| |
| Here is an example showing how a `std::string' printer might be |
| written. *Note Pretty Printing API::, for details on the API this class |
| must provide. |
| |
| class StdStringPrinter(object): |
| "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 |
| if lookup_tag == None: |
| return None |
| regex = re.compile("^std::basic_string<char,.*>$") |
| 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 Python 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.append(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()) |
| |
| The previous example illustrates a basic pretty-printer. There are |
| a few things that can be improved on. The printer doesn't have a name, |
| making it hard to identify in a list of installed printers. The lookup |
| function has a name, but lookup functions can have arbitrary, even |
| identical, names. |
| |
| Second, the printer only handles one type, whereas a library |
| typically has several types. One could install a lookup function for |
| each desired type in the library, but one could also have a single |
| lookup function recognize several types. The latter is the |
| conventional way this is handled. If a pretty-printer can handle |
| multiple data types, then its "subprinters" are the printers for the |
| individual data types. |
| |
| The `gdb.printing' module provides a formal way of solving these |
| problems (*note gdb.printing::). Here is another example that handles |
| multiple types. |
| |
| These are the types we are going to pretty-print: |
| |
| struct foo { int a, b; }; |
| struct bar { struct foo x, y; }; |
| |
| Here are the printers: |
| |
| class fooPrinter: |
| """Print a foo object.""" |
| |
| def __init__(self, val): |
| self.val = val |
| |
| def to_string(self): |
| return ("a=<" + str(self.val["a"]) + |
| "> b=<" + str(self.val["b"]) + ">") |
| |
| class barPrinter: |
| """Print a bar object.""" |
| |
| def __init__(self, val): |
| self.val = val |
| |
| def to_string(self): |
| return ("x=<" + str(self.val["x"]) + |
| "> y=<" + str(self.val["y"]) + ">") |
| |
| This example doesn't need a lookup function, that is handled by the |
| `gdb.printing' module. Instead a function is provided to build up the |
| object that handles the lookup. |
| |
| import gdb.printing |
| |
| def build_pretty_printer(): |
| pp = gdb.printing.RegexpCollectionPrettyPrinter( |
| "my_library") |
| pp.add_printer('foo', '^foo$', fooPrinter) |
| pp.add_printer('bar', '^bar$', barPrinter) |
| return pp |
| |
| And here is the autoload support: |
| |
| import gdb.printing |
| import my_library |
| gdb.printing.register_pretty_printer( |
| gdb.current_objfile(), |
| my_library.build_pretty_printer()) |
| |
| Finally, when this printer is loaded into GDB, here is the |
| corresponding output of `info pretty-printer': |
| |
| (gdb) info pretty-printer |
| my_library.so: |
| my_library |
| foo |
| bar |
| |
| |
| File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing a Pretty-Printer, 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: gdb.inferiors () |
| Return a tuple containing all inferior objects. |
| |
| -- Function: gdb.selected_inferior () |
| Return an object representing the current inferior. |
| |
| A `gdb.Inferior' object has the following attributes: |
| |
| -- Variable: Inferior.num |
| ID of inferior, as assigned by GDB. |
| |
| -- Variable: Inferior.pid |
| Process ID of the inferior, as assigned by the underlying |
| operating system. |
| |
| -- Variable: 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: |
| |
| -- Function: Inferior.is_valid () |
| Returns `True' if the `gdb.Inferior' object is valid, `False' |
| if not. A `gdb.Inferior' object will become invalid if the |
| inferior no longer exists within GDB. All other |
| `gdb.Inferior' methods will throw an exception if it is |
| invalid at the time the method is called. |
| |
| -- Function: 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. |
| |
| -- Function: 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 |
| `Inferior.write_memory' function. |
| |
| -- Function: 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 `Inferior.read_memory'. If given, LENGTH |
| determines the number of bytes from BUFFER to be written. |
| |
| -- Function: 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: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API |
| |
| 23.2.2.9 Events In Python |
| ......................... |
| |
| GDB provides a general event facility so that Python code can be |
| notified of various state changes, particularly changes that occur in |
| the inferior. |
| |
| An "event" is just an object that describes some state change. The |
| type of the object and its attributes will vary depending on the details |
| of the change. All the existing events are described below. |
| |
| In order to be notified of an event, you must register an event |
| handler with an "event registry". An event registry is an object in the |
| `gdb.events' module which dispatches particular events. A registry |
| provides methods to register and unregister event handlers: |
| |
| -- Function: EventRegistry.connect (object) |
| Add the given callable OBJECT to the registry. This object |
| will be called when an event corresponding to this registry |
| occurs. |
| |
| -- Function: EventRegistry.disconnect (object) |
| Remove the given OBJECT from the registry. Once removed, the |
| object will no longer receive notifications of events. |
| |
| Here is an example: |
| |
| def exit_handler (event): |
| print "event type: exit" |
| print "exit code: %d" % (event.exit_code) |
| |
| gdb.events.exited.connect (exit_handler) |
| |
| In the above example we connect our handler `exit_handler' to the |
| registry `events.exited'. Once connected, `exit_handler' gets called |
| when the inferior exits. The argument "event" in this example is of |
| type `gdb.ExitedEvent'. As you can see in the example the |
| `ExitedEvent' object has an attribute which indicates the exit code of |
| the inferior. |
| |
| The following is a listing of the event registries that are |
| available and details of the events they emit: |
| |
| `events.cont' |
| Emits `gdb.ThreadEvent'. |
| |
| Some events can be thread specific when GDB is running in non-stop |
| mode. When represented in Python, these events all extend |
| `gdb.ThreadEvent'. Note, this event is not emitted directly; |
| instead, events which are emitted by this or other modules might |
| extend this event. Examples of these events are |
| `gdb.BreakpointEvent' and `gdb.ContinueEvent'. |
| |
| -- Variable: ThreadEvent.inferior_thread |
| In non-stop mode this attribute will be set to the |
| specific thread which was involved in the emitted event. |
| Otherwise, it will be set to `None'. |
| |
| Emits `gdb.ContinueEvent' which extends `gdb.ThreadEvent'. |
| |
| This event indicates that the inferior has been continued after a |
| stop. For inherited attribute refer to `gdb.ThreadEvent' above. |
| |
| `events.exited' |
| Emits `events.ExitedEvent' which indicates that the inferior has |
| exited. `events.ExitedEvent' has two attributes: |
| -- Variable: ExitedEvent.exit_code |
| An integer representing the exit code, if available, |
| which the inferior has returned. (The exit code could |
| be unavailable if, for example, GDB detaches from the |
| inferior.) If the exit code is unavailable, the |
| attribute does not exist. |
| |
| -- Variable: ExitedEvent inferior |
| A reference to the inferior which triggered the `exited' |
| event. |
| |
| `events.stop' |
| Emits `gdb.StopEvent' which extends `gdb.ThreadEvent'. |
| |
| Indicates that the inferior has stopped. All events emitted by |
| this registry extend StopEvent. As a child of `gdb.ThreadEvent', |
| `gdb.StopEvent' will indicate the stopped thread when GDB is |
| running in non-stop mode. Refer to `gdb.ThreadEvent' above for |
| more details. |
| |
| Emits `gdb.SignalEvent' which extends `gdb.StopEvent'. |
| |
| This event indicates that the inferior or one of its threads has |
| received as signal. `gdb.SignalEvent' has the following |
| attributes: |
| |
| -- Variable: SignalEvent.stop_signal |
| A string representing the signal received by the |
| inferior. A list of possible signal values can be |
| obtained by running the command `info signals' in the |
| GDB command prompt. |
| |
| Also emits `gdb.BreakpointEvent' which extends `gdb.StopEvent'. |
| |
| `gdb.BreakpointEvent' event indicates that one or more breakpoints |
| have been hit, and has the following attributes: |
| |
| -- Variable: BreakpointEvent.breakpoints |
| A sequence containing references to all the breakpoints |
| (type `gdb.Breakpoint') that were hit. *Note |
| Breakpoints In Python::, for details of the |
| `gdb.Breakpoint' object. |
| |
| -- Variable: BreakpointEvent.breakpoint |
| A reference to the first breakpoint that was hit. This |
| function is maintained for backward compatibility and is |
| now deprecated in favor of the |
| `gdb.BreakpointEvent.breakpoints' attribute. |
| |
| `events.new_objfile' |
| Emits `gdb.NewObjFileEvent' which indicates that a new object file |
| has been loaded by GDB. `gdb.NewObjFileEvent' has one attribute: |
| |
| -- Variable: NewObjFileEvent.new_objfile |
| A reference to the object file (`gdb.Objfile') which has |
| been loaded. *Note Objfiles In Python::, for details of |
| the `gdb.Objfile' object. |
| |
| |
| |
| File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Events In Python, Up: Python API |
| |
| 23.2.2.10 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: gdb.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: |
| |
| -- Variable: InferiorThread.name |
| The name of the thread. If the user specified a name using |
| `thread name', then this returns that name. Otherwise, if an |
| OS-supplied name is available, then it is returned. |
| Otherwise, this returns `None'. |
| |
| This attribute can be assigned to. The new value must be a |
| string object, which sets the new name, or `None', which |
| removes any user-specified thread name. |
| |
| -- Variable: InferiorThread.num |
| ID of the thread, as assigned by GDB. |
| |
| -- Variable: 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: |
| |
| -- Function: InferiorThread.is_valid () |
| Returns `True' if the `gdb.InferiorThread' object is valid, |
| `False' if not. A `gdb.InferiorThread' object will become |
| invalid if the thread exits, or the inferior that the thread |
| belongs is deleted. All other `gdb.InferiorThread' methods |
| will throw an exception if it is invalid at the time the |
| method is called. |
| |
| -- Function: InferiorThread.switch () |
| This changes GDB's currently selected thread to the one |
| represented by this object. |
| |
| -- Function: InferiorThread.is_stopped () |
| Return a Boolean indicating whether the thread is stopped. |
| |
| -- Function: InferiorThread.is_running () |
| Return a Boolean indicating whether the thread is running. |
| |
| -- Function: 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.11 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. |
| |
| -- Function: 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. |
| |
| -- Function: 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. |
| |
| -- Function: 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"] |
| |
| |
| -- Function: 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: |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.COMMAND_USER' |
| The command is a general purpose command for the user, and |
| typically does not fit in one of the other categories. Type `help |
| user-defined' at the GDB prompt to see a list of commands in this |
| category, as well as the list of gdb macros (*note Sequences::). |
| |
| `gdb.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. |
| |
| `gdb.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: |
| |
| `gdb.COMPLETE_NONE' |
| This constant means that no completion should be done. |
| |
| `gdb.COMPLETE_FILENAME' |
| This constant means that filename completion should be performed. |
| |
| `gdb.COMPLETE_LOCATION' |
| This constant means that location completion should be done. |
| *Note Specify Location::. |
| |
| `gdb.COMPLETE_COMMAND' |
| This constant means that completion should examine GDB command |
| names. |
| |
| `gdb.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_USER) |
| |
| 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.12 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. |
| |
| -- Function: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| There are two methods that should be implemented in any `Parameter' |
| class. These are: |
| |
| -- Function: Parameter.get_set_string (self) |
| GDB will call this method when a PARAMETER's value has been |
| changed via the `set' API (for example, `set foo off'). The |
| `value' attribute has already been populated with the new value |
| and may be used in output. This method must return a string. |
| |
| -- Function: Parameter.get_show_string (self, svalue) |
| GDB will call this method when a PARAMETER's `show' API has been |
| invoked (for example, `show foo'). The argument `svalue' receives |
| the string representation of the current value. This method must |
| return a string. |
| |
| When a new parameter is defined, its type must be specified. The |
| available types are represented by constants defined in the `gdb' |
| module: |
| |
| `gdb.PARAM_BOOLEAN' |
| The value is a plain boolean. The Python boolean values, `True' |
| and `False' are the only valid values. |
| |
| `gdb.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'. |
| |
| `gdb.PARAM_UINTEGER' |
| The value is an unsigned integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| `gdb.PARAM_INTEGER' |
| The value is a signed integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| `gdb.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. |
| |
| `gdb.PARAM_STRING_NOESCAPE' |
| The value is a string. When the user modifies the string, escapes |
| are passed through untranslated. |
| |
| `gdb.PARAM_OPTIONAL_FILENAME' |
| The value is a either a filename (a string), or `None'. |
| |
| `gdb.PARAM_FILENAME' |
| The value is a filename. This is just like |
| `PARAM_STRING_NOESCAPE', but uses file names for completion. |
| |
| `gdb.PARAM_ZINTEGER' |
| The value is an integer. This is like `PARAM_INTEGER', except 0 |
| is interpreted as itself. |
| |
| `gdb.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.13 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'. |
| |
| -- Function: 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. |
| |
| -- Function: 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.14 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: gdb.current_progspace () |
| This function returns the program space of the currently selected |
| inferior. *Note Inferiors and Programs::. |
| |
| -- Function: gdb.progspaces () |
| Return a sequence of all the progspaces currently known to GDB. |
| |
| Each progspace is represented by an instance of the `gdb.Progspace' |
| class. |
| |
| -- Variable: Progspace.filename |
| The file name of the progspace as a string. |
| |
| -- Variable: 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.15 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: gdb.current_objfile () |
| When auto-loading a Python script (*note Python 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: gdb.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. |
| |
| -- Variable: Objfile.filename |
| The file name of the objfile as a string. |
| |
| -- Variable: 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. |
| |
| A `gdb.Objfile' object has the following methods: |
| |
| -- Function: Objfile.is_valid () |
| Returns `True' if the `gdb.Objfile' object is valid, `False' if |
| not. A `gdb.Objfile' object can become invalid if the object file |
| it refers to is not loaded in GDB any longer. All other |
| `gdb.Objfile' methods will throw an exception if it is invalid at |
| the time the method is called. |
| |
| |
| File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API |
| |
| 23.2.2.16 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 `gdb.error' exception (*note |
| Exception Handling::). |
| |
| 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: gdb.selected_frame () |
| Return the selected frame object. (*note Selecting a Frame: |
| Selection.). |
| |
| -- Function: gdb.newest_frame () |
| Return the newest frame object for the selected thread. |
| |
| -- Function: gdb.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: |
| |
| -- Function: 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. |
| |
| -- Function: Frame.name () |
| Returns the function name of the frame, or `None' if it can't |
| be obtained. |
| |
| -- Function: Frame.type () |
| Returns the type of the frame. The value can be one of: |
| `gdb.NORMAL_FRAME' |
| An ordinary stack frame. |
| |
| `gdb.DUMMY_FRAME' |
| A fake stack frame that was created by GDB when |
| performing an inferior function call. |
| |
| `gdb.INLINE_FRAME' |
| A frame representing an inlined function. The function |
| was inlined into a `gdb.NORMAL_FRAME' that is older than |
| this one. |
| |
| `gdb.TAILCALL_FRAME' |
| A frame representing a tail call. *Note Tail Call |
| Frames::. |
| |
| `gdb.SIGTRAMP_FRAME' |
| A signal trampoline frame. This is the frame created by |
| the OS when it calls into a signal handler. |
| |
| `gdb.ARCH_FRAME' |
| A fake stack frame representing a cross-architecture |
| call. |
| |
| `gdb.SENTINEL_FRAME' |
| This is like `gdb.NORMAL_FRAME', but it is only used for |
| the newest frame. |
| |
| -- Function: 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. The value can be one of: |
| |
| `gdb.FRAME_UNWIND_NO_REASON' |
| No particular reason (older frames should be available). |
| |
| `gdb.FRAME_UNWIND_NULL_ID' |
| The previous frame's analyzer returns an invalid result. |
| |
| `gdb.FRAME_UNWIND_OUTERMOST' |
| This frame is the outermost. |
| |
| `gdb.FRAME_UNWIND_UNAVAILABLE' |
| Cannot unwind further, because that would require |
| knowing the values of registers or memory that have not |
| been collected. |
| |
| `gdb.FRAME_UNWIND_INNER_ID' |
| This frame ID looks like it ought to belong to a NEXT |
| frame, but we got it for a PREV frame. Normally, this |
| is a sign of unwinder failure. It could also indicate |
| stack corruption. |
| |
| `gdb.FRAME_UNWIND_SAME_ID' |
| This frame has the same ID as the previous one. That |
| means that unwinding further would almost certainly give |
| us another frame with exactly the same ID, so break the |
| chain. Normally, this is a sign of unwinder failure. |
| It could also indicate stack corruption. |
| |
| `gdb.FRAME_UNWIND_NO_SAVED_PC' |
| The frame unwinder did not find any saved PC, but we |
| needed one to unwind further. |
| |
| `gdb.FRAME_UNWIND_FIRST_ERROR' |
| Any stop reason greater or equal to this value indicates |
| some kind of error. This special value facilitates |
| writing code that tests for errors in unwinding in a way |
| that will work correctly even if the list of the other |
| values is modified in future GDB versions. Using it, |
| you could write: |
| reason = gdb.selected_frame().unwind_stop_reason () |
| reason_str = gdb.frame_stop_reason_string (reason) |
| if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: |
| print "An error occured: %s" % reason_str |
| |
| |
| -- Function: Frame.pc () |
| Returns the frame's resume address. |
| |
| -- Function: Frame.block () |
| Return the frame's code block. *Note Blocks In Python::. |
| |
| -- Function: Frame.function () |
| Return the symbol for the function corresponding to this |
| frame. *Note Symbols In Python::. |
| |
| -- Function: Frame.older () |
| Return the frame that called this frame. |
| |
| -- Function: Frame.newer () |
| Return the frame called by this frame. |
| |
| -- Function: Frame.find_sal () |
| Return the frame's symtab and line object. *Note Symbol |
| Tables In Python::. |
| |
| -- Function: 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. |
| |
| -- Function: 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.17 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. |
| |
| A `gdb.Block' is iterable. The iterator returns the symbols (*note |
| Symbols In Python::) local to the block. Python programs should not |
| assume that a specific block object will always contain a given symbol, |
| since changes in GDB features and infrastructure may cause symbols move |
| across blocks in a symbol table. |
| |
| The following block-related functions are available in the `gdb' |
| module: |
| |
| -- Function: gdb.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 methods: |
| |
| -- Function: Block.is_valid () |
| Returns `True' if the `gdb.Block' object is valid, `False' if |
| not. A block object can become invalid if the block it |
| refers to doesn't exist anymore in the inferior. All other |
| `gdb.Block' methods will throw an exception if it is invalid |
| at the time the method is called. The block's validity is |
| also checked during iteration over symbols of the block. |
| |
| A `gdb.Block' object has the following attributes: |
| |
| -- Variable: Block.start |
| The start address of the block. This attribute is not |
| writable. |
| |
| -- Variable: Block.end |
| The end address of the block. This attribute is not writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: Block.superblock |
| The block containing this block. If this parent block does |
| not exist, this attribute holds `None'. This attribute is |
| not writable. |
| |
| -- Variable: Block.global_block |
| The global block associated with this block. This attribute |
| is not writable. |
| |
| -- Variable: Block.static_block |
| The static block associated with this block. This attribute |
| is not writable. |
| |
| -- Variable: Block.is_global |
| `True' if the `gdb.Block' object is a global block, `False' |
| if not. This attribute is not writable. |
| |
| -- Variable: Block.is_static |
| `True' if the `gdb.Block' object is a static block, `False' |
| if not. 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.18 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: gdb.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. If |
| omitted, the block for the current frame is used. 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. |
| |
| The result is a tuple of two elements. The first element is a |
| `gdb.Symbol' object or `None' if the symbol is not found. If the |
| symbol is found, the second element is `True' if the symbol is a |
| field of a method's object (e.g., `this' in C++), otherwise it is |
| `False'. If the symbol is not found, the second element is |
| `False'. |
| |
| -- Function: gdb.lookup_global_symbol (name [, domain]) |
| This function searches for a global symbol by name. The search |
| scope can be restricted to by the domain argument. |
| |
| NAME is the name of the symbol. It must be a string. 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. |
| |
| The result is a `gdb.Symbol' object or `None' if the symbol is not |
| found. |
| |
| A `gdb.Symbol' object has the following attributes: |
| |
| -- Variable: Symbol.type |
| The type of the symbol or `None' if no type is recorded. |
| This attribute is represented as a `gdb.Type' object. *Note |
| Types In Python::. This attribute is not writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: Symbol.line |
| The line number in the source code at which the symbol was |
| defined. This is an integer. |
| |
| -- Variable: Symbol.name |
| The name of the symbol as a string. This attribute is not |
| writable. |
| |
| -- Variable: Symbol.linkage_name |
| The name of the symbol, as used by the linker (i.e., may be |
| mangled). This attribute is not writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: Symbol.needs_frame |
| This is `True' if evaluating this symbol's value requires a |
| frame (*note Frames In Python::) and `False' otherwise. |
| Typically, local variables will require a frame, but other |
| symbols will not. |
| |
| -- Variable: Symbol.is_argument |
| `True' if the symbol is an argument of a function. |
| |
| -- Variable: Symbol.is_constant |
| `True' if the symbol is a constant. |
| |
| -- Variable: Symbol.is_function |
| `True' if the symbol is a function or a method. |
| |
| -- Variable: Symbol.is_variable |
| `True' if the symbol is a variable. |
| |
| A `gdb.Symbol' object has the following methods: |
| |
| -- Function: Symbol.is_valid () |
| Returns `True' if the `gdb.Symbol' object is valid, `False' |
| if not. A `gdb.Symbol' object can become invalid if the |
| symbol it refers to does not exist in GDB any longer. All |
| other `gdb.Symbol' methods will throw an exception if it is |
| invalid at the time the method is called. |
| |
| -- Function: Symbol.value ([frame]) |
| Compute the value of the symbol, as a `gdb.Value'. For |
| functions, this computes the address of the function, cast to |
| the appropriate type. If the symbol requires a frame in |
| order to compute its value, then FRAME must be given. If |
| FRAME is not given, or if FRAME is invalid, then this method |
| will throw an exception. |
| |
| The available domain categories in `gdb.Symbol' are represented as |
| constants in the `gdb' module: |
| |
| `gdb.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. |
| |
| `gdb.SYMBOL_VAR_DOMAIN' |
| This domain contains variables, function names, typedef names and |
| enum type values. |
| |
| `gdb.SYMBOL_STRUCT_DOMAIN' |
| This domain holds struct, union and enum type names. |
| |
| `gdb.SYMBOL_LABEL_DOMAIN' |
| This domain contains names of labels (for gotos). |
| |
| `gdb.SYMBOL_VARIABLES_DOMAIN' |
| This domain holds a subset of the `SYMBOLS_VAR_DOMAIN'; it |
| contains everything minus functions and types. |
| |
| `gdb.SYMBOL_FUNCTION_DOMAIN' |
| This domain contains all functions. |
| |
| `gdb.SYMBOL_TYPES_DOMAIN' |
| This domain contains all types. |
| |
| The available address class categories in `gdb.Symbol' are |
| represented as constants in the `gdb' module: |
| |
| `gdb.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. |
| |
| `gdb.SYMBOL_LOC_CONST' |
| Value is constant int. |
| |
| `gdb.SYMBOL_LOC_STATIC' |
| Value is at a fixed address. |
| |
| `gdb.SYMBOL_LOC_REGISTER' |
| Value is in a register. |
| |
| `gdb.SYMBOL_LOC_ARG' |
| Value is an argument. This value is at the offset stored within |
| the symbol inside the frame's argument list. |
| |
| `gdb.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. |
| |
| `gdb.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. |
| |
| `gdb.SYMBOL_LOC_LOCAL' |
| Value is a local variable. |
| |
| `gdb.SYMBOL_LOC_TYPEDEF' |
| Value not used. Symbols in the domain `SYMBOL_STRUCT_DOMAIN' all |
| have this class. |
| |
| `gdb.SYMBOL_LOC_BLOCK' |
| Value is a block. |
| |
| `gdb.SYMBOL_LOC_CONST_BYTES' |
| Value is a byte-sequence. |
| |
| `gdb.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. |
| |
| `gdb.SYMBOL_LOC_OPTIMIZED_OUT' |
| The value does not actually exist in the program. |
| |
| `gdb.SYMBOL_LOC_COMPUTED' |
| The value's address is a computed location. |
| |
| |
| File: gdb.info, Node: Symbol Tables In Python, Next: Breakpoints In Python, Prev: Symbols In Python, Up: Python API |
| |
| 23.2.2.19 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: |
| |
| -- Variable: Symtab_and_line.symtab |
| The symbol table object (`gdb.Symtab') for this frame. This |
| attribute is not writable. |
| |
| -- Variable: Symtab_and_line.pc |
| Indicates the start of the address range occupied by code for |
| the current source line. This attribute is not writable. |
| |
| -- Variable: Symtab_and_line.last |
| Indicates the end of the address range occupied by code for |
| the current source line. This attribute is not writable. |
| |
| -- Variable: Symtab_and_line.line |
| Indicates the current line number for this object. This |
| attribute is not writable. |
| |
| A `gdb.Symtab_and_line' object has the following methods: |
| |
| -- Function: Symtab_and_line.is_valid () |
| Returns `True' if the `gdb.Symtab_and_line' object is valid, |
| `False' if not. A `gdb.Symtab_and_line' object can become |
| invalid if the Symbol table and line object it refers to does |
| not exist in GDB any longer. All other `gdb.Symtab_and_line' |
| methods will throw an exception if it is invalid at the time |
| the method is called. |
| |
| A `gdb.Symtab' object has the following attributes: |
| |
| -- Variable: Symtab.filename |
| The symbol table's source filename. This attribute is not |
| writable. |
| |
| -- Variable: Symtab.objfile |
| The symbol table's backing object file. *Note Objfiles In |
| Python::. This attribute is not writable. |
| |
| A `gdb.Symtab' object has the following methods: |
| |
| -- Function: Symtab.is_valid () |
| Returns `True' if the `gdb.Symtab' object is valid, `False' |
| if not. A `gdb.Symtab' object can become invalid if the |
| symbol table it refers to does not exist in GDB any longer. |
| All other `gdb.Symtab' methods will throw an exception if it |
| is invalid at the time the method is called. |
| |
| -- Function: Symtab.fullname () |
| Return the symbol table's source absolute file name. |
| |
| -- Function: Symtab.global_block () |
| Return the global block of the underlying symbol table. |
| *Note Blocks In Python::. |
| |
| -- Function: Symtab.static_block () |
| Return the static block of the underlying symbol table. |
| *Note Blocks In Python::. |
| |
| |
| File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Symbol Tables In Python, Up: Python API |
| |
| 23.2.2.20 Manipulating breakpoints using Python |
| ............................................... |
| |
| Python code can manipulate breakpoints via the `gdb.Breakpoint' class. |
| |
| -- Function: Breakpoint.__init__ (spec [, type [, wp_class |
| [,internal]]]) |
| 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: `gdb.BP_BREAKPOINT' |
| or `gdb.BP_WATCHPOINT'. TYPE defaults to `gdb.BP_BREAKPOINT'. |
| The optional INTERNAL argument allows the breakpoint to become |
| invisible to the user. The breakpoint will neither be reported |
| when created, nor will it be listed in the output from `info |
| breakpoints' (but will be listed with the `maint info breakpoints' |
| command). The optional WP_CLASS argument defines the class of |
| watchpoint to create, if TYPE is `gdb.BP_WATCHPOINT'. If a |
| watchpoint class is not provided, it is assumed to be a |
| `gdb.WP_WRITE' class. |
| |
| -- Function: Breakpoint.stop (self) |
| The `gdb.Breakpoint' class can be sub-classed and, in particular, |
| you may choose to implement the `stop' method. If this method is |
| defined as a sub-class of `gdb.Breakpoint', it will be called when |
| the inferior reaches any location of a breakpoint which |
| instantiates that sub-class. If the method returns `True', the |
| inferior will be stopped at the location of the breakpoint, |
| otherwise the inferior will continue. |
| |
| If there are multiple breakpoints at the same location with a |
| `stop' method, each one will be called regardless of the return |
| status of the previous. This ensures that all `stop' methods have |
| a chance to execute at that location. In this scenario if one of |
| the methods returns `True' but the others return `False', the |
| inferior will still be stopped. |
| |
| You should not alter the execution state of the inferior (i.e., |
| step, next, etc.), alter the current frame context (i.e., change |
| the current active frame), or alter, add or delete any breakpoint. |
| As a general rule, you should not alter any data within GDB or |
| the inferior at this time. |
| |
| Example `stop' implementation: |
| |
| class MyBreakpoint (gdb.Breakpoint): |
| def stop (self): |
| inf_val = gdb.parse_and_eval("foo") |
| if inf_val == 3: |
| return True |
| return False |
| |
| The available watchpoint types represented by constants are defined |
| in the `gdb' module: |
| |
| `gdb.WP_READ' |
| Read only watchpoint. |
| |
| `gdb.WP_WRITE' |
| Write only watchpoint. |
| |
| `gdb.WP_ACCESS' |
| Read/Write watchpoint. |
| |
| -- Function: 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. |
| |
| -- Function: Breakpoint.delete |
| Permanently deletes the GDB breakpoint. This also invalidates the |
| Python `Breakpoint' object. Any further access to this object's |
| attributes or methods will raise an error. |
| |
| -- Variable: Breakpoint.enabled |
| This attribute is `True' if the breakpoint is enabled, and `False' |
| otherwise. This attribute is writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: Breakpoint.ignore_count |
| This attribute holds the ignore count for the breakpoint, an |
| integer. This attribute is writable. |
| |
| -- Variable: Breakpoint.number |
| This attribute holds the breakpoint's number -- the identifier |
| used by the user to manipulate the breakpoint. This attribute is |
| not writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: Breakpoint.visible |
| This attribute tells whether the breakpoint is visible to the user |
| when set, or when the `info breakpoints' command is run. This |
| attribute is not writable. |
| |
| The available types are represented by constants defined in the `gdb' |
| module: |
| |
| `gdb.BP_BREAKPOINT' |
| Normal code breakpoint. |
| |
| `gdb.BP_WATCHPOINT' |
| Watchpoint breakpoint. |
| |
| `gdb.BP_HARDWARE_WATCHPOINT' |
| Hardware assisted watchpoint. |
| |
| `gdb.BP_READ_WATCHPOINT' |
| Hardware assisted read watchpoint. |
| |
| `gdb.BP_ACCESS_WATCHPOINT' |
| Hardware assisted access watchpoint. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API |
| |
| 23.2.2.21 Finish Breakpoints |
| ............................ |
| |
| A finish breakpoint is a temporary breakpoint set at the return address |
| of a frame, based on the `finish' command. `gdb.FinishBreakpoint' |
| extends `gdb.Breakpoint'. The underlying breakpoint will be disabled |
| and deleted when the execution will run out of the breakpoint scope |
| (i.e. `Breakpoint.stop' or `FinishBreakpoint.out_of_scope' triggered). |
| Finish breakpoints are thread specific and must be create with the right |
| thread selected. |
| |
| -- Function: FinishBreakpoint.__init__ ([frame] [, internal]) |
| Create a finish breakpoint at the return address of the `gdb.Frame' |
| object FRAME. If FRAME is not provided, this defaults to the |
| newest frame. The optional INTERNAL argument allows the |
| breakpoint to become invisible to the user. *Note Breakpoints In |
| Python::, for further details about this argument. |
| |
| -- Function: FinishBreakpoint.out_of_scope (self) |
| In some circumstances (e.g. `longjmp', C++ exceptions, GDB |
| `return' command, ...), a function may not properly terminate, and |
| thus never hit the finish breakpoint. When GDB notices such a |
| situation, the `out_of_scope' callback will be triggered. |
| |
| You may want to sub-class `gdb.FinishBreakpoint' and override this |
| method: |
| |
| class MyFinishBreakpoint (gdb.FinishBreakpoint) |
| def stop (self): |
| print "normal finish" |
| return True |
| |
| def out_of_scope (): |
| print "abnormal finish" |
| |
| -- Variable: FinishBreakpoint.return_value |
| When GDB is stopped at a finish breakpoint and the frame used to |
| build the `gdb.FinishBreakpoint' object had debug symbols, this |
| attribute will contain a `gdb.Value' object corresponding to the |
| return value of the function. The value will be `None' if the |
| function return type is `void' or if the return value was not |
| computable. This attribute is not writable. |
| |
| |
| File: gdb.info, Node: Lazy Strings In Python, Prev: Finish Breakpoints in Python, Up: Python API |
| |
| 23.2.2.22 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: |
| |
| -- Function: 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'. |
| |
| -- Variable: LazyString.address |
| This attribute holds the address of the string. This attribute is |
| not writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python |
| |
| 23.2.3 Python 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' (*note |
| objfile-gdb.py file::) and `.debug_gdb_scripts' section (*note |
| dotdebug_gdb_scripts section::). |
| |
| The auto-loading feature is useful for supplying application-specific |
| debugging commands and scripts. |
| |
| Auto-loading can be enabled or disabled, and the list of auto-loaded |
| scripts can be printed. |
| |
| `set auto-load python-scripts [on|off]' |
| Enable or disable the auto-loading of Python scripts. |
| |
| `show auto-load python-scripts' |
| Show whether auto-loading of Python scripts is enabled or disabled. |
| |
| `info auto-load python-scripts [REGEXP]' |
| Print the list of all Python scripts that GDB auto-loaded. |
| |
| Also printed is the list of Python scripts that were mentioned in |
| the `.debug_gdb_scripts' section and were not found (*note |
| dotdebug_gdb_scripts section::). This is useful because their |
| names are not printed when GDB tries to load them and fails. |
| There may be many of them, and printing an error message for each |
| one is problematic. |
| |
| If REGEXP is supplied only Python scripts with matching names are |
| printed. |
| |
| Example: |
| |
| (gdb) info auto-load python-scripts |
| Loaded Script |
| Yes py-section-script.py |
| full name: /tmp/py-section-script.py |
| No my-foo-pretty-printers.py |
| |
| 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. |
| |
| * Menu: |
| |
| * objfile-gdb.py file:: The `OBJFILE-gdb.py' file |
| * dotdebug_gdb_scripts section:: The `.debug_gdb_scripts' section |
| * Which flavor to choose?:: |
| |