| Index: gdb/doc/gdb.info-3
|
| diff --git a/gdb/doc/gdb.info-3 b/gdb/doc/gdb.info-3
|
| index d5d80da285a62e43be56d1479243b92d351a1107..3f7741a306960b7e8e3af312307243042d0818b3 100644
|
| --- a/gdb/doc/gdb.info-3
|
| +++ b/gdb/doc/gdb.info-3
|
| @@ -1,13 +1,12 @@
|
| -This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
|
| +This is gdb.info, produced by makeinfo version 4.13 from ./gdb.texinfo.
|
|
|
| INFO-DIR-SECTION Software development
|
| START-INFO-DIR-ENTRY
|
| * Gdb: (gdb). The GNU debugger.
|
| +* gdbserver: (gdb) Server. The GNU debugging server.
|
| 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.
|
| + Copyright (C) 1988-2013 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
|
| @@ -23,11 +22,9 @@ 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.1.
|
| +Source-Level Debugger' for GDB (GDB) Version 7.6.50.20131211-cvs.
|
|
|
| - 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.
|
| + Copyright (C) 1988-2013 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
|
| @@ -41,9 +38,905 @@ this GNU Manual. Buying copies from GNU Press supports the FSF in
|
| developing GNU and promoting software freedom."
|
|
|
|
|
| +File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files
|
| +
|
| +18.1 Commands to Specify Files
|
| +==============================
|
| +
|
| +You may want to specify executable and core dump file names. The usual
|
| +way to do this is at start-up time, using the arguments to GDB's
|
| +start-up commands (*note Getting In and Out of GDB: Invocation.).
|
| +
|
| + Occasionally it is necessary to change to a different file during a
|
| +GDB session. Or you may run GDB and forget to specify a file you want
|
| +to use. Or you are debugging a remote target via `gdbserver' (*note
|
| +file: Server.). In these situations the GDB commands to specify new
|
| +files are useful.
|
| +
|
| +`file FILENAME'
|
| + Use FILENAME as the program to be debugged. It is read for its
|
| + symbols and for the contents of pure memory. It is also the
|
| + program executed when you use the `run' command. If you do not
|
| + specify a directory and the file is not found in the GDB working
|
| + directory, GDB uses the environment variable `PATH' as a list of
|
| + directories to search, just as the shell does when looking for a
|
| + program to run. You can change the value of this variable, for
|
| + both GDB and your program, using the `path' command.
|
| +
|
| + You can load unlinked object `.o' files into GDB using the `file'
|
| + command. You will not be able to "run" an object file, but you
|
| + can disassemble functions and inspect variables. Also, if the
|
| + underlying BFD functionality supports it, you could use `gdb
|
| + -write' to patch object files using this technique. Note that GDB
|
| + can neither interpret nor modify relocations in this case, so
|
| + branches and some initialized variables will appear to go to the
|
| + wrong place. But this feature is still handy from time to time.
|
| +
|
| +`file'
|
| + `file' with no argument makes GDB discard any information it has
|
| + on both executable file and the symbol table.
|
| +
|
| +`exec-file [ FILENAME ]'
|
| + Specify that the program to be run (but not the symbol table) is
|
| + found in FILENAME. GDB searches the environment variable `PATH'
|
| + if necessary to locate your program. Omitting FILENAME means to
|
| + discard information on the executable file.
|
| +
|
| +`symbol-file [ FILENAME ]'
|
| + Read symbol table information from file FILENAME. `PATH' is
|
| + searched when necessary. Use the `file' command to get both symbol
|
| + table and program to run from the same file.
|
| +
|
| + `symbol-file' with no argument clears out GDB information on your
|
| + program's symbol table.
|
| +
|
| + The `symbol-file' command causes GDB to forget the contents of
|
| + some breakpoints and auto-display expressions. This is because
|
| + they may contain pointers to the internal data recording symbols
|
| + and data types, which are part of the old symbol table data being
|
| + discarded inside GDB.
|
| +
|
| + `symbol-file' does not repeat if you press <RET> again after
|
| + executing it once.
|
| +
|
| + When GDB is configured for a particular environment, it
|
| + understands debugging information in whatever format is the
|
| + standard generated for that environment; you may use either a GNU
|
| + compiler, or other compilers that adhere to the local conventions.
|
| + Best results are usually obtained from GNU compilers; for example,
|
| + using `GCC' you can generate debugging information for optimized
|
| + code.
|
| +
|
| + For most kinds of object files, with the exception of old SVR3
|
| + systems using COFF, the `symbol-file' command does not normally
|
| + read the symbol table in full right away. Instead, it scans the
|
| + symbol table quickly to find which source files and which symbols
|
| + are present. The details are read later, one source file at a
|
| + time, as they are needed.
|
| +
|
| + The purpose of this two-stage reading strategy is to make GDB
|
| + start up faster. For the most part, it is invisible except for
|
| + occasional pauses while the symbol table details for a particular
|
| + source file are being read. (The `set verbose' command can turn
|
| + these pauses into messages if desired. *Note Optional Warnings
|
| + and Messages: Messages/Warnings.)
|
| +
|
| + We have not implemented the two-stage strategy for COFF yet. When
|
| + the symbol table is stored in COFF format, `symbol-file' reads the
|
| + symbol table data in full right away. Note that "stabs-in-COFF"
|
| + still does the two-stage strategy, since the debug info is actually
|
| + in stabs format.
|
| +
|
| +`symbol-file [ -readnow ] FILENAME'
|
| +`file [ -readnow ] FILENAME'
|
| + You can override the GDB two-stage strategy for reading symbol
|
| + tables by using the `-readnow' option with any of the commands that
|
| + load symbol table information, if you want to be sure GDB has the
|
| + entire symbol table available.
|
| +
|
| +`core-file [FILENAME]'
|
| +`core'
|
| + Specify the whereabouts of a core dump file to be used as the
|
| + "contents of memory". Traditionally, core files contain only some
|
| + parts of the address space of the process that generated them; GDB
|
| + can access the executable file itself for other parts.
|
| +
|
| + `core-file' with no argument specifies that no core file is to be
|
| + used.
|
| +
|
| + Note that the core file is ignored when your program is actually
|
| + running under GDB. So, if you have been running your program and
|
| + you wish to debug a core file instead, you must kill the
|
| + subprocess in which the program is running. To do this, use the
|
| + `kill' command (*note Killing the Child Process: Kill Process.).
|
| +
|
| +`add-symbol-file FILENAME ADDRESS'
|
| +`add-symbol-file FILENAME ADDRESS [ -readnow ]'
|
| +`add-symbol-file FILENAME ADDRESS -s SECTION ADDRESS ...'
|
| + The `add-symbol-file' command reads additional symbol table
|
| + information from the file FILENAME. You would use this command
|
| + when FILENAME has been dynamically loaded (by some other means)
|
| + into the program that is running. ADDRESS should be the memory
|
| + address at which the file has been loaded; GDB cannot figure this
|
| + out for itself. You can additionally specify an arbitrary number
|
| + of `-s SECTION ADDRESS' pairs, to give an explicit section name
|
| + and base address for that section. You can specify any ADDRESS as
|
| + an expression.
|
| +
|
| + The symbol table of the file FILENAME is added to the symbol table
|
| + originally read with the `symbol-file' command. You can use the
|
| + `add-symbol-file' command any number of times; the new symbol data
|
| + thus read is kept in addition to the old.
|
| +
|
| + Changes can be reverted using the command `remove-symbol-file'.
|
| +
|
| + Although FILENAME is typically a shared library file, an
|
| + executable file, or some other object file which has been fully
|
| + relocated for loading into a process, you can also load symbolic
|
| + information from relocatable `.o' files, as long as:
|
| +
|
| + * the file's symbolic information refers only to linker symbols
|
| + defined in that file, not to symbols defined by other object
|
| + files,
|
| +
|
| + * every section the file's symbolic information refers to has
|
| + actually been loaded into the inferior, as it appears in the
|
| + file, and
|
| +
|
| + * you can determine the address at which every section was
|
| + loaded, and provide these to the `add-symbol-file' command.
|
| +
|
| + Some embedded operating systems, like Sun Chorus and VxWorks, can
|
| + load relocatable files into an already running program; such
|
| + systems typically make the requirements above easy to meet.
|
| + However, it's important to recognize that many native systems use
|
| + complex link procedures (`.linkonce' section factoring and C++
|
| + constructor table assembly, for example) that make the
|
| + requirements difficult to meet. In general, one cannot assume
|
| + that using `add-symbol-file' to read a relocatable object file's
|
| + symbolic information will have the same effect as linking the
|
| + relocatable object file into the program in the normal way.
|
| +
|
| + `add-symbol-file' does not repeat if you press <RET> after using
|
| + it.
|
| +
|
| +`remove-symbol-file FILENAME'
|
| +
|
| +`remove-symbol-file -a ADDRESS'
|
| + Remove a symbol file added via the `add-symbol-file' command. The
|
| + file to remove can be identified by its FILENAME or by an ADDRESS
|
| + that lies within the boundaries of this symbol file in memory.
|
| + Example:
|
| +
|
| + (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
|
| + add symbol table from file "/home/user/gdb/mylib.so" at
|
| + .text_addr = 0x7ffff7ff9480
|
| + (y or n) y
|
| + Reading symbols from /home/user/gdb/mylib.so...done.
|
| + (gdb) remove-symbol-file -a 0x7ffff7ff9480
|
| + Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
|
| + (gdb)
|
| +
|
| + `remove-symbol-file' does not repeat if you press <RET> after
|
| + using it.
|
| +
|
| +`add-symbol-file-from-memory ADDRESS'
|
| + Load symbols from the given ADDRESS in a dynamically loaded object
|
| + file whose image is mapped directly into the inferior's memory.
|
| + For example, the Linux kernel maps a `syscall DSO' into each
|
| + process's address space; this DSO provides kernel-specific code for
|
| + some system calls. The argument can be any expression whose
|
| + evaluation yields the address of the file's shared object file
|
| + header. For this command to work, you must have used
|
| + `symbol-file' or `exec-file' commands in advance.
|
| +
|
| +`add-shared-symbol-files LIBRARY-FILE'
|
| +`assf LIBRARY-FILE'
|
| + The `add-shared-symbol-files' command can currently be used only
|
| + in the Cygwin build of GDB on MS-Windows OS, where it is an alias
|
| + for the `dll-symbols' command (*note Cygwin Native::). GDB
|
| + automatically looks for shared libraries, however if GDB does not
|
| + find yours, you can invoke `add-shared-symbol-files'. It takes
|
| + one argument: the shared library's file name. `assf' is a
|
| + shorthand alias for `add-shared-symbol-files'.
|
| +
|
| +`section SECTION ADDR'
|
| + The `section' command changes the base address of the named
|
| + SECTION of the exec file to ADDR. This can be used if the exec
|
| + file does not contain section addresses, (such as in the `a.out'
|
| + format), or when the addresses specified in the file itself are
|
| + wrong. Each section must be changed separately. The `info files'
|
| + command, described below, lists all the sections and their
|
| + addresses.
|
| +
|
| +`info files'
|
| +`info target'
|
| + `info files' and `info target' are synonymous; both print the
|
| + current target (*note Specifying a Debugging Target: Targets.),
|
| + including the names of the executable and core dump files
|
| + currently in use by GDB, and the files from which symbols were
|
| + loaded. The command `help target' lists all possible targets
|
| + rather than current ones.
|
| +
|
| +`maint info sections'
|
| + Another command that can give you extra information about program
|
| + sections is `maint info sections'. In addition to the section
|
| + information displayed by `info files', this command displays the
|
| + flags and file offset of each section in the executable and core
|
| + dump files. In addition, `maint info sections' provides the
|
| + following command options (which may be arbitrarily combined):
|
| +
|
| + `ALLOBJ'
|
| + Display sections for all loaded object files, including
|
| + shared libraries.
|
| +
|
| + `SECTIONS'
|
| + Display info only for named SECTIONS.
|
| +
|
| + `SECTION-FLAGS'
|
| + Display info only for sections for which SECTION-FLAGS are
|
| + true. The section flags that GDB currently knows about are:
|
| + `ALLOC'
|
| + Section will have space allocated in the process when
|
| + loaded. Set for all sections except those containing
|
| + debug information.
|
| +
|
| + `LOAD'
|
| + Section will be loaded from the file into the child
|
| + process memory. Set for pre-initialized code and data,
|
| + clear for `.bss' sections.
|
| +
|
| + `RELOC'
|
| + Section needs to be relocated before loading.
|
| +
|
| + `READONLY'
|
| + Section cannot be modified by the child process.
|
| +
|
| + `CODE'
|
| + Section contains executable code only.
|
| +
|
| + `DATA'
|
| + Section contains data only (no executable code).
|
| +
|
| + `ROM'
|
| + Section will reside in ROM.
|
| +
|
| + `CONSTRUCTOR'
|
| + Section contains data for constructor/destructor lists.
|
| +
|
| + `HAS_CONTENTS'
|
| + Section is not empty.
|
| +
|
| + `NEVER_LOAD'
|
| + An instruction to the linker to not output the section.
|
| +
|
| + `COFF_SHARED_LIBRARY'
|
| + A notification to the linker that the section contains
|
| + COFF shared library information.
|
| +
|
| + `IS_COMMON'
|
| + Section contains common symbols.
|
| +
|
| +`set trust-readonly-sections on'
|
| + Tell GDB that readonly sections in your object file really are
|
| + read-only (i.e. that their contents will not change). In that
|
| + case, GDB can fetch values from these sections out of the object
|
| + file, rather than from the target program. For some targets
|
| + (notably embedded ones), this can be a significant enhancement to
|
| + debugging performance.
|
| +
|
| + The default is off.
|
| +
|
| +`set trust-readonly-sections off'
|
| + Tell GDB not to trust readonly sections. This means that the
|
| + contents of the section might change while the program is running,
|
| + and must therefore be fetched from the target when needed.
|
| +
|
| +`show trust-readonly-sections'
|
| + Show the current setting of trusting readonly sections.
|
| +
|
| + All file-specifying commands allow both absolute and relative file
|
| +names as arguments. GDB always converts the file name to an absolute
|
| +file name and remembers it that way.
|
| +
|
| + GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and
|
| +IBM RS/6000 AIX shared libraries.
|
| +
|
| + On MS-Windows GDB must be linked with the Expat library to support
|
| +shared libraries. *Note Expat::.
|
| +
|
| + GDB automatically loads symbol definitions from shared libraries
|
| +when you use the `run' command, or when you examine a core file.
|
| +(Before you issue the `run' command, GDB does not understand references
|
| +to a function in a shared library, however--unless you are debugging a
|
| +core file).
|
| +
|
| + On HP-UX, if the program loads a library explicitly, GDB
|
| +automatically loads the symbols at the time of the `shl_load' call.
|
| +
|
| + There are times, however, when you may wish to not automatically load
|
| +symbol definitions from shared libraries, such as when they are
|
| +particularly large or there are many of them.
|
| +
|
| + To control the automatic loading of shared library symbols, use the
|
| +commands:
|
| +
|
| +`set auto-solib-add MODE'
|
| + If MODE is `on', symbols from all shared object libraries will be
|
| + loaded automatically when the inferior begins execution, you
|
| + attach to an independently started inferior, or when the dynamic
|
| + linker informs GDB that a new library has been loaded. If MODE is
|
| + `off', symbols must be loaded manually, using the `sharedlibrary'
|
| + command. The default value is `on'.
|
| +
|
| + If your program uses lots of shared libraries with debug info that
|
| + takes large amounts of memory, you can decrease the GDB memory
|
| + footprint by preventing it from automatically loading the symbols
|
| + from shared libraries. To that end, type `set auto-solib-add off'
|
| + before running the inferior, then load each library whose debug
|
| + symbols you do need with `sharedlibrary REGEXP', where REGEXP is a
|
| + regular expression that matches the libraries whose symbols you
|
| + want to be loaded.
|
| +
|
| +`show auto-solib-add'
|
| + Display the current autoloading mode.
|
| +
|
| + To explicitly load shared library symbols, use the `sharedlibrary'
|
| +command:
|
| +
|
| +`info share REGEX'
|
| +`info sharedlibrary REGEX'
|
| + Print the names of the shared libraries which are currently loaded
|
| + that match REGEX. If REGEX is omitted then print all shared
|
| + libraries that are loaded.
|
| +
|
| +`sharedlibrary REGEX'
|
| +`share REGEX'
|
| + Load shared object library symbols for files matching a Unix
|
| + regular expression. As with files loaded automatically, it only
|
| + loads shared libraries required by your program for a core file or
|
| + after typing `run'. If REGEX is omitted all shared libraries
|
| + required by your program are loaded.
|
| +
|
| +`nosharedlibrary'
|
| + Unload all shared object library symbols. This discards all
|
| + symbols that have been loaded from all shared libraries. Symbols
|
| + from shared libraries that were loaded by explicit user requests
|
| + are not discarded.
|
| +
|
| + Sometimes you may wish that GDB stops and gives you control when any
|
| +of shared library events happen. The best way to do this is to use
|
| +`catch load' and `catch unload' (*note Set Catchpoints::).
|
| +
|
| + GDB also supports the the `set stop-on-solib-events' command for
|
| +this. This command exists for historical reasons. It is less useful
|
| +than setting a catchpoint, because it does not allow for conditions or
|
| +commands as a catchpoint does.
|
| +
|
| +`set stop-on-solib-events'
|
| + This command controls whether GDB should give you control when the
|
| + dynamic linker notifies it about some shared library event. The
|
| + most common event of interest is loading or unloading of a new
|
| + shared library.
|
| +
|
| +`show stop-on-solib-events'
|
| + Show whether GDB stops and gives you control when shared library
|
| + events happen.
|
| +
|
| + Shared libraries are also supported in many cross or remote debugging
|
| +configurations. GDB needs to have access to the target's libraries;
|
| +this can be accomplished either by providing copies of the libraries on
|
| +the host system, or by asking GDB to automatically retrieve the
|
| +libraries from the target. If copies of the target libraries are
|
| +provided, they need to be the same as the target libraries, although the
|
| +copies on the target can be stripped as long as the copies on the host
|
| +are not.
|
| +
|
| + For remote debugging, you need to tell GDB where the target
|
| +libraries are, so that it can load the correct copies--otherwise, it
|
| +may try to load the host's libraries. GDB has two variables to specify
|
| +the search directories for target libraries.
|
| +
|
| +`set sysroot PATH'
|
| + Use PATH as the system root for the program being debugged. Any
|
| + absolute shared library paths will be prefixed with PATH; many
|
| + runtime loaders store the absolute paths to the shared library in
|
| + the target program's memory. If you use `set sysroot' to find
|
| + shared libraries, they need to be laid out in the same way that
|
| + they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy
|
| + under PATH.
|
| +
|
| + If PATH starts with the sequence `remote:', GDB will retrieve the
|
| + target libraries from the remote system. This is only supported
|
| + when using a remote target that supports the `remote get' command
|
| + (*note Sending files to a remote system: File Transfer.). The
|
| + part of PATH following the initial `remote:' (if present) is used
|
| + as system root prefix on the remote file system. (1)
|
| +
|
| + For targets with an MS-DOS based filesystem, such as MS-Windows and
|
| + SymbianOS, GDB tries prefixing a few variants of the target
|
| + absolute file name with PATH. But first, on Unix hosts, GDB
|
| + converts all backslash directory separators into forward slashes,
|
| + because the backslash is not a directory separator on Unix:
|
| +
|
| + c:\foo\bar.dll => c:/foo/bar.dll
|
| +
|
| + Then, GDB attempts prefixing the target file name with PATH, and
|
| + looks for the resulting file name in the host file system:
|
| +
|
| + c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll
|
| +
|
| + If that does not find the shared library, GDB tries removing the
|
| + `:' character from the drive spec, both for convenience, and, for
|
| + the case of the host file system not supporting file names with
|
| + colons:
|
| +
|
| + c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll
|
| +
|
| + This makes it possible to have a system root that mirrors a target
|
| + with more than one drive. E.g., you may want to setup your local
|
| + copies of the target system shared libraries like so (note `c' vs
|
| + `z'):
|
| +
|
| + `/path/to/sysroot/c/sys/bin/foo.dll'
|
| + `/path/to/sysroot/c/sys/bin/bar.dll'
|
| + `/path/to/sysroot/z/sys/bin/bar.dll'
|
| +
|
| + and point the system root at `/path/to/sysroot', so that GDB can
|
| + find the correct copies of both `c:\sys\bin\foo.dll', and
|
| + `z:\sys\bin\bar.dll'.
|
| +
|
| + If that still does not find the shared library, GDB tries removing
|
| + the whole drive spec from the target file name:
|
| +
|
| + c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll
|
| +
|
| + This last lookup makes it possible to not care about the drive
|
| + name, if you don't want or need to.
|
| +
|
| + The `set solib-absolute-prefix' command is an alias for `set
|
| + sysroot'.
|
| +
|
| + You can set the default system root by using the configure-time
|
| + `--with-sysroot' option. If the system root is inside GDB's
|
| + configured binary prefix (set with `--prefix' or `--exec-prefix'),
|
| + then the default system root will be updated automatically if the
|
| + installed GDB is moved to a new location.
|
| +
|
| +`show sysroot'
|
| + Display the current shared library prefix.
|
| +
|
| +`set solib-search-path PATH'
|
| + If this variable is set, PATH is a colon-separated list of
|
| + directories to search for shared libraries. `solib-search-path'
|
| + is used after `sysroot' fails to locate the library, or if the
|
| + path to the library is relative instead of absolute. If you want
|
| + to use `solib-search-path' instead of `sysroot', be sure to set
|
| + `sysroot' to a nonexistent directory to prevent GDB from finding
|
| + your host's libraries. `sysroot' is preferred; setting it to a
|
| + nonexistent directory may interfere with automatic loading of
|
| + shared library symbols.
|
| +
|
| +`show solib-search-path'
|
| + Display the current shared library search path.
|
| +
|
| +`set target-file-system-kind KIND'
|
| + Set assumed file system kind for target reported file names.
|
| +
|
| + Shared library file names as reported by the target system may not
|
| + make sense as is on the system GDB is running on. For example,
|
| + when remote debugging a target that has MS-DOS based file system
|
| + semantics, from a Unix host, the target may be reporting to GDB a
|
| + list of loaded shared libraries with file names such as
|
| + `c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of
|
| + drive letters, so the `c:\' prefix is not normally understood as
|
| + indicating an absolute file name, and neither is the backslash
|
| + normally considered a directory separator character. In that case,
|
| + the native file system would interpret this whole absolute file
|
| + name as a relative file name with no directory components. This
|
| + would make it impossible to point GDB at a copy of the remote
|
| + target's shared libraries on the host using `set sysroot', and
|
| + impractical with `set solib-search-path'. Setting
|
| + `target-file-system-kind' to `dos-based' tells GDB to interpret
|
| + such file names similarly to how the target would, and to map them
|
| + to file names valid on GDB's native file system semantics. The
|
| + value of KIND can be `"auto"', in addition to one of the supported
|
| + file system kinds. In that case, GDB tries to determine the
|
| + appropriate file system variant based on the current target's
|
| + operating system (*note Configuring the Current ABI: ABI.). The
|
| + supported file system settings are:
|
| +
|
| + `unix'
|
| + Instruct GDB to assume the target file system is of Unix
|
| + kind. Only file names starting the forward slash (`/')
|
| + character are considered absolute, and the directory
|
| + separator character is also the forward slash.
|
| +
|
| + `dos-based'
|
| + Instruct GDB to assume the target file system is DOS based.
|
| + File names starting with either a forward slash, or a drive
|
| + letter followed by a colon (e.g., `c:'), are considered
|
| + absolute, and both the slash (`/') and the backslash (`\\')
|
| + characters are considered directory separators.
|
| +
|
| + `auto'
|
| + Instruct GDB to use the file system kind associated with the
|
| + target operating system (*note Configuring the Current ABI:
|
| + ABI.). This is the default.
|
| +
|
| + When processing file names provided by the user, GDB frequently
|
| +needs to compare them to the file names recorded in the program's debug
|
| +info. Normally, GDB compares just the "base names" of the files as
|
| +strings, which is reasonably fast even for very large programs. (The
|
| +base name of a file is the last portion of its name, after stripping
|
| +all the leading directories.) This shortcut in comparison is based
|
| +upon the assumption that files cannot have more than one base name.
|
| +This is usually true, but references to files that use symlinks or
|
| +similar filesystem facilities violate that assumption. If your program
|
| +records files using such facilities, or if you provide file names to
|
| +GDB using symlinks etc., you can set `basenames-may-differ' to `true'
|
| +to instruct GDB to completely canonicalize each pair of file names it
|
| +needs to compare. This will make file-name comparisons accurate, but
|
| +at a price of a significant slowdown.
|
| +
|
| +`set basenames-may-differ'
|
| + Set whether a source file may have multiple base names.
|
| +
|
| +`show basenames-may-differ'
|
| + Show whether a source file may have multiple base names.
|
| +
|
| + ---------- Footnotes ----------
|
| +
|
| + (1) If you want to specify a local system root using a directory
|
| +that happens to be named `remote:', you need to use some equivalent
|
| +variant of the name like `./remote:'.
|
| +
|
| +
|
| +File: gdb.info, Node: Separate Debug Files, Next: MiniDebugInfo, Prev: Files, Up: GDB Files
|
| +
|
| +18.2 Debugging Information in Separate Files
|
| +============================================
|
| +
|
| +GDB allows you to put a program's debugging information in a file
|
| +separate from the executable itself, in a way that allows GDB to find
|
| +and load the debugging information automatically. Since debugging
|
| +information can be very large--sometimes larger than the executable
|
| +code itself--some systems distribute debugging information for their
|
| +executables in separate files, which users can install only when they
|
| +need to debug a problem.
|
| +
|
| + GDB supports two ways of specifying the separate debug info file:
|
| +
|
| + * The executable contains a "debug link" that specifies the name of
|
| + the separate debug info file. The separate debug file's name is
|
| + usually `EXECUTABLE.debug', where EXECUTABLE is the name of the
|
| + corresponding executable file without leading directories (e.g.,
|
| + `ls.debug' for `/usr/bin/ls'). In addition, the debug link
|
| + specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for
|
| + the debug file, which GDB uses to validate that the executable and
|
| + the debug file came from the same build.
|
| +
|
| + * The executable contains a "build ID", a unique bit string that is
|
| + also present in the corresponding debug info file. (This is
|
| + supported only on some operating systems, notably those which use
|
| + the ELF format for binary files and the GNU Binutils.) For more
|
| + details about this feature, see the description of the `--build-id'
|
| + command-line option in *note Command Line Options:
|
| + (ld.info)Options. The debug info file's name is not specified
|
| + explicitly by the build ID, but can be computed from the build ID,
|
| + see below.
|
| +
|
| + Depending on the way the debug info file is specified, GDB uses two
|
| +different methods of looking for the debug file:
|
| +
|
| + * For the "debug link" method, GDB looks up the named file in the
|
| + directory of the executable file, then in a subdirectory of that
|
| + directory named `.debug', and finally under each one of the global
|
| + debug directories, in a subdirectory whose name is identical to
|
| + the leading directories of the executable's absolute file name.
|
| +
|
| + * For the "build ID" method, GDB looks in the `.build-id'
|
| + subdirectory of each one of the global debug directories for a
|
| + file named `NN/NNNNNNNN.debug', where NN are the first 2 hex
|
| + characters of the build ID bit string, and NNNNNNNN are the rest
|
| + of the bit string. (Real build ID strings are 32 or more hex
|
| + characters, not 10.)
|
| +
|
| + So, for example, suppose you ask GDB to debug `/usr/bin/ls', which
|
| +has a debug link that specifies the file `ls.debug', and a build ID
|
| +whose value in hex is `abcdef1234'. If the list of the global debug
|
| +directories includes `/usr/lib/debug', then GDB will look for the
|
| +following debug information files, in the indicated order:
|
| +
|
| + - `/usr/lib/debug/.build-id/ab/cdef1234.debug'
|
| +
|
| + - `/usr/bin/ls.debug'
|
| +
|
| + - `/usr/bin/.debug/ls.debug'
|
| +
|
| + - `/usr/lib/debug/usr/bin/ls.debug'.
|
| +
|
| + Global debugging info directories default to what is set by GDB
|
| +configure option `--with-separate-debug-dir'. During GDB run you can
|
| +also set the global debugging info directories, and view the list GDB
|
| +is currently using.
|
| +
|
| +`set debug-file-directory DIRECTORIES'
|
| + Set the directories which GDB searches for separate debugging
|
| + information files to DIRECTORY. Multiple path components can be
|
| + set concatenating them by a path separator.
|
| +
|
| +`show debug-file-directory'
|
| + Show the directories GDB searches for separate debugging
|
| + information files.
|
| +
|
| +
|
| + A debug link is a special section of the executable file named
|
| +`.gnu_debuglink'. The section must contain:
|
| +
|
| + * A filename, with any leading directory components removed,
|
| + followed by a zero byte,
|
| +
|
| + * zero to three bytes of padding, as needed to reach the next
|
| + four-byte boundary within the section, and
|
| +
|
| + * a four-byte CRC checksum, stored in the same endianness used for
|
| + the executable file itself. The checksum is computed on the
|
| + debugging information file's full contents by the function given
|
| + below, passing zero as the CRC argument.
|
| +
|
| + Any executable file format can carry a debug link, as long as it can
|
| +contain a section named `.gnu_debuglink' with the contents described
|
| +above.
|
| +
|
| + The build ID is a special section in the executable file (and in
|
| +other ELF binary files that GDB may consider). This section is often
|
| +named `.note.gnu.build-id', but that name is not mandatory. It
|
| +contains unique identification for the built files--the ID remains the
|
| +same across multiple builds of the same build tree. The default
|
| +algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
|
| +content for the build ID string. The same section with an identical
|
| +value is present in the original built binary with symbols, in its
|
| +stripped variant, and in the separate debugging information file.
|
| +
|
| + The debugging information file itself should be an ordinary
|
| +executable, containing a full set of linker symbols, sections, and
|
| +debugging information. The sections of the debugging information file
|
| +should have the same names, addresses, and sizes as the original file,
|
| +but they need not contain any data--much like a `.bss' section in an
|
| +ordinary executable.
|
| +
|
| + The GNU binary utilities (Binutils) package includes the `objcopy'
|
| +utility that can produce the separated executable / debugging
|
| +information file pairs using the following commands:
|
| +
|
| + objcopy --only-keep-debug foo foo.debug
|
| + strip -g foo
|
| +
|
| +These commands remove the debugging information from the executable
|
| +file `foo' and place it in the file `foo.debug'. You can use the
|
| +first, second or both methods to link the two files:
|
| +
|
| + * The debug link method needs the following additional command to
|
| + also leave behind a debug link in `foo':
|
| +
|
| + objcopy --add-gnu-debuglink=foo.debug foo
|
| +
|
| + Ulrich Drepper's `elfutils' package, starting with version 0.53,
|
| + contains a version of the `strip' command such that the command
|
| + `strip foo -f foo.debug' has the same functionality as the two
|
| + `objcopy' commands and the `ln -s' command above, together.
|
| +
|
| + * Build ID gets embedded into the main executable using `ld
|
| + --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID
|
| + support plus compatibility fixes for debug files separation are
|
| + present in GNU binary utilities (Binutils) package since version
|
| + 2.18.
|
| +
|
| +The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3
|
| +using the polynomial:
|
| +
|
| + x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11
|
| + + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
|
| +
|
| + The function is computed byte at a time, taking the least
|
| +significant bit of each byte first. The initial pattern `0xffffffff'
|
| +is used, to ensure leading zeros affect the CRC and the final result is
|
| +inverted to ensure trailing zeros also affect the CRC.
|
| +
|
| + _Note:_ This is the same CRC polynomial as used in handling the
|
| +"Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial
|
| +Protocol: Remote Protocol.). However in the case of the Remote Serial
|
| +Protocol, the CRC is computed _most_ significant bit first, and the
|
| +result is not inverted, so trailing zeros have no effect on the CRC
|
| +value.
|
| +
|
| + To complete the description, we show below the code of the function
|
| +which produces the CRC used in `.gnu_debuglink'. Inverting the
|
| +initially supplied `crc' argument means that an initial call to this
|
| +function passing in zero will start computing the CRC using
|
| +`0xffffffff'.
|
| +
|
| + unsigned long
|
| + gnu_debuglink_crc32 (unsigned long crc,
|
| + unsigned char *buf, size_t len)
|
| + {
|
| + static const unsigned long crc32_table[256] =
|
| + {
|
| + 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
|
| + 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
|
| + 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
|
| + 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
|
| + 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
|
| + 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
|
| + 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
|
| + 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
|
| + 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
|
| + 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
|
| + 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
|
| + 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
|
| + 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
|
| + 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
|
| + 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
|
| + 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
|
| + 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
|
| + 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
|
| + 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
|
| + 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
|
| + 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
|
| + 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
|
| + 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
|
| + 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
|
| + 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
|
| + 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
|
| + 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
|
| + 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
|
| + 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
|
| + 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
|
| + 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
|
| + 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
|
| + 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
|
| + 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
|
| + 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
|
| + 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
|
| + 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
|
| + 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
|
| + 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
|
| + 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
|
| + 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
|
| + 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
|
| + 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
|
| + 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
|
| + 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
|
| + 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
|
| + 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
|
| + 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
|
| + 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
|
| + 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
|
| + 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
|
| + 0x2d02ef8d
|
| + };
|
| + unsigned char *end;
|
| +
|
| + crc = ~crc & 0xffffffff;
|
| + for (end = buf + len; buf < end; ++buf)
|
| + crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
|
| + return ~crc & 0xffffffff;
|
| + }
|
| +
|
| +This computation does not apply to the "build ID" method.
|
| +
|
| +
|
| +File: gdb.info, Node: MiniDebugInfo, Next: Index Files, Prev: Separate Debug Files, Up: GDB Files
|
| +
|
| +18.3 Debugging information in a special section
|
| +===============================================
|
| +
|
| +Some systems ship pre-built executables and libraries that have a
|
| +special `.gnu_debugdata' section. This feature is called
|
| +"MiniDebugInfo". This section holds an LZMA-compressed object and is
|
| +used to supply extra symbols for backtraces.
|
| +
|
| + The intent of this section is to provide extra minimal debugging
|
| +information for use in simple backtraces. It is not intended to be a
|
| +replacement for full separate debugging information (*note Separate
|
| +Debug Files::). The example below shows the intended use; however, GDB
|
| +does not currently put restrictions on what sort of debugging
|
| +information might be included in the section.
|
| +
|
| + GDB has support for this extension. If the section exists, then it
|
| +is used provided that no other source of debugging information can be
|
| +found, and that GDB was configured with LZMA support.
|
| +
|
| + This section can be easily created using `objcopy' and other
|
| +standard utilities:
|
| +
|
| + # Extract the dynamic symbols from the main binary, there is no need
|
| + # to also have these in the normal symbol table.
|
| + nm -D BINARY --format=posix --defined-only \
|
| + | awk '{ print $1 }' | sort > dynsyms
|
| +
|
| + # Extract all the text (i.e. function) symbols from the debuginfo.
|
| + # (Note that we actually also accept "D" symbols, for the benefit
|
| + # of platforms like PowerPC64 that use function descriptors.)
|
| + nm BINARY --format=posix --defined-only \
|
| + | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' \
|
| + | sort > funcsyms
|
| +
|
| + # Keep all the function symbols not already in the dynamic symbol
|
| + # table.
|
| + comm -13 dynsyms funcsyms > keep_symbols
|
| +
|
| + # Separate full debug info into debug binary.
|
| + objcopy --only-keep-debug BINARY debug
|
| +
|
| + # Copy the full debuginfo, keeping only a minimal set of symbols and
|
| + # removing some unnecessary sections.
|
| + objcopy -S --remove-section .gdb_index --remove-section .comment \
|
| + --keep-symbols=keep_symbols debug mini_debuginfo
|
| +
|
| + # Drop the full debug info from the original binary.
|
| + strip --strip-all -R .comment BINARY
|
| +
|
| + # Inject the compressed data into the .gnu_debugdata section of the
|
| + # original binary.
|
| + xz mini_debuginfo
|
| + objcopy --add-section .gnu_debugdata=mini_debuginfo.xz BINARY
|
| +
|
| +
|
| +File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: MiniDebugInfo, Up: GDB Files
|
| +
|
| +18.4 Index Files Speed Up GDB
|
| +=============================
|
| +
|
| +When GDB finds a symbol file, it scans the symbols in the file in order
|
| +to construct an internal symbol table. This lets most GDB operations
|
| +work quickly--at the cost of a delay early on. For large programs,
|
| +this delay can be quite lengthy, so GDB provides a way to build an
|
| +index, which speeds up startup.
|
| +
|
| + The index is stored as a section in the symbol file. GDB can write
|
| +the index to a file, then you can put it into the symbol file using
|
| +`objcopy'.
|
| +
|
| + To create an index file, use the `save gdb-index' command:
|
| +
|
| +`save gdb-index DIRECTORY'
|
| + Create an index file for each symbol file currently known by GDB.
|
| + Each file is named after its corresponding symbol file, with
|
| + `.gdb-index' appended, and is written into the given DIRECTORY.
|
| +
|
| + Once you have created an index file you can merge it into your symbol
|
| +file, here named `symfile', using `objcopy':
|
| +
|
| + $ objcopy --add-section .gdb_index=symfile.gdb-index \
|
| + --set-section-flags .gdb_index=readonly symfile symfile
|
| +
|
| + GDB will normally ignore older versions of `.gdb_index' sections
|
| +that have been deprecated. Usually they are deprecated because they
|
| +are missing a new feature or have performance issues. To tell GDB to
|
| +use a deprecated index section anyway specify `set
|
| +use-deprecated-index-sections on'. The default is `off'. This can
|
| +speed up startup, but may result in some functionality being lost.
|
| +*Note Index Section Format::.
|
| +
|
| + _Warning:_ Setting `use-deprecated-index-sections' to `on' must be
|
| +done before gdb reads the file. The following will not work:
|
| +
|
| + $ gdb -ex "set use-deprecated-index-sections on" <program>
|
| +
|
| + Instead you must do, for example,
|
| +
|
| + $ gdb -iex "set use-deprecated-index-sections on" <program>
|
| +
|
| + There are currently some limitation on indices. They only work when
|
| +for DWARF debugging information, not stabs. And, they do not currently
|
| +work for programs using Ada.
|
| +
|
| +
|
| File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files
|
|
|
| -18.4 Errors Reading Symbol Files
|
| +18.5 Errors Reading Symbol Files
|
| ================================
|
|
|
| While reading a symbol file, GDB occasionally encounters problems, such
|
| @@ -124,7 +1017,7 @@ Optional Warnings and Messages: Messages/Warnings.).
|
|
|
| File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files
|
|
|
| -18.5 GDB Data Files
|
| +18.6 GDB Data Files
|
| ===================
|
|
|
| GDB will sometimes read an auxiliary data file. These files are kept
|
| @@ -255,7 +1148,7 @@ File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets
|
| 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"'.
|
| + `show gnutarget' displays `The current BFD target is "auto"'.
|
|
|
| Here are some common targets (available, or not, depending on the GDB
|
| configuration):
|
| @@ -293,13 +1186,7 @@ configuration):
|
| 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.
|
| + in *note Embedded Processors: Embedded Processors.
|
|
|
|
|
| Different targets are available on different configurations of GDB;
|
| @@ -432,8 +1319,8 @@ to the target. Its arguments indicate which medium to use:
|
| 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.
|
| + `--baud' option, or use the `set serial baud' command (*note set
|
| + serial baud: Remote Configuration.) before the `target' command.
|
|
|
| `target remote `HOST:PORT''
|
| `target remote `tcp:HOST:PORT''
|
| @@ -663,8 +1550,8 @@ 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::).
|
| +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
|
| @@ -694,12 +1581,12 @@ Therefore, when the connection drops unexpectedly, and GDB cannot ask
|
| 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
|
| +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'
|
| +subsequent 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
|
| @@ -885,7 +1772,7 @@ File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server,
|
|
|
| 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:
|
| +extensions of the remote protocol, see *note system-call-allowed:
|
| system.
|
|
|
| `set remoteaddresssize BITS'
|
| @@ -897,12 +1784,12 @@ system.
|
| `show remoteaddresssize'
|
| Show the current value of remote address size in bits.
|
|
|
| -`set remotebaud N'
|
| +`set serial baud 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 serial baud'
|
| Show the current speed of the remote connection.
|
|
|
| `set remotebreak'
|
| @@ -1009,11 +1896,15 @@ system.
|
| Show the current auto-retry setting.
|
|
|
| `set tcp connect-timeout SECONDS'
|
| +`set tcp connect-timeout unlimited'
|
| 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.
|
| + represents an approximate cumulative value. If SECONDS is
|
| + `unlimited', there is no timeout and GDB will keep attempting to
|
| + establish a connection forever, unless interrupted with `Ctrl-c'.
|
| + The default is 15 seconds.
|
|
|
| `show tcp connect-timeout'
|
| Show the current connection timeout setting.
|
| @@ -1024,7 +1915,7 @@ 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::.
|
| +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
|
| @@ -1088,6 +1979,9 @@ storage-address' `__thread'
|
| `query-attached' `qAttached' Querying remote
|
| process attach
|
| state.
|
| +`trace-buffer-size' `QTBuffer:size' `set
|
| + trace-buffer-size'
|
| +`trace-status' `qTStatus' `tstatus'
|
| `traceframe-info' `qXfer:traceframe-info:read'Traceframe info
|
| `install-in-trace' `InstallInTrace' Install
|
| tracepoint in
|
| @@ -1399,7 +2293,6 @@ configurations.
|
| * 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
|
|
|
|
|
| @@ -1451,13 +2344,16 @@ File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD
|
|
|
| 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.
|
| +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. This includes, as of this writing, GNU/Linux, OSF/1 (Digital
|
| +Unix), Solaris, and Irix, but not HP-UX, for example.
|
| +
|
| + This command may also work on core files that were created on a
|
| +system that has the `/proc' facility.
|
|
|
| `info proc'
|
| `info proc PROCESS-ID'
|
| @@ -1474,6 +2370,18 @@ HP-UX, for example.
|
| 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 cmdline'
|
| + Show the original command line of the process. This command is
|
| + specific to GNU/Linux.
|
| +
|
| +`info proc cwd'
|
| + Show the current working directory of the process. This command is
|
| + specific to GNU/Linux.
|
| +
|
| +`info proc exe'
|
| + Show the name of executable of the process. This command is
|
| + specific to GNU/Linux.
|
| +
|
| `info proc mappings'
|
| Report the memory address space ranges accessible in the program,
|
| with information on whether the process has read, write, or
|
| @@ -1688,7 +2596,7 @@ 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::.
|
| +described in *note Non-debug DLL Symbols::.
|
|
|
| `info w32'
|
| This is a prefix of MS Windows-specific commands which print
|
| @@ -1791,8 +2699,8 @@ 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
|
| +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.
|
| @@ -1881,7 +2789,7 @@ 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
|
| +File: gdb.info, Node: Hurd Native, Next: Darwin, Prev: Cygwin Native, Up: Native
|
|
|
| 21.1.6 Commands Specific to GNU Hurd Systems
|
| --------------------------------------------
|
| @@ -2019,24 +2927,9 @@ debugging.
|
| 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.
|
| +File: gdb.info, Node: Darwin, Prev: Hurd Native, Up: Native
|
|
|
| -`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
|
| +21.1.7 Darwin
|
| -------------
|
|
|
| GDB provides the following commands specific to the Darwin target:
|
| @@ -2247,7 +3140,6 @@ to send an arbitrary command to the simulator.
|
| * 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
|
| @@ -2511,7 +3403,7 @@ support if you need to do this.)
|
| Show MicroBlaze-specific debugging level.
|
|
|
|
|
| -File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors
|
| +File: gdb.info, Node: MIPS Embedded, Next: PowerPC Embedded, Prev: MicroBlaze, Up: Embedded Processors
|
|
|
| 21.3.5 MIPS Embedded
|
| --------------------
|
| @@ -2646,114 +3538,9 @@ GDB also supports these special commands for MIPS targets:
|
| 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'.
|
| +File: gdb.info, Node: PowerPC Embedded, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors
|
|
|
| - `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
|
| +21.3.6 PowerPC Embedded
|
| -----------------------
|
|
|
| GDB supports using the DVC (Data Value Compare) register to implement
|
| @@ -2781,7 +3568,7 @@ region using one of the following commands (*note Expressions::):
|
| (gdb) watch {char[LENGTH]} ADDRESS
|
|
|
| PowerPC embedded processors support masked watchpoints. See the
|
| -discussion about the `mask' argument in *Note Set Watchpoints::.
|
| +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
|
| @@ -2795,7 +3582,7 @@ command.
|
| 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
|
| + 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,
|
| @@ -2849,7 +3636,7 @@ GDB:
|
|
|
| File: gdb.info, Node: PA, Next: Sparclet, Prev: PowerPC Embedded, Up: Embedded Processors
|
|
|
| -21.3.8 HP PA Embedded
|
| +21.3.7 HP PA Embedded
|
| ---------------------
|
|
|
| `target op50n DEV'
|
| @@ -2862,7 +3649,7 @@ File: gdb.info, Node: PA, Next: Sparclet, Prev: PowerPC Embedded, Up: Embedd
|
|
|
| File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PA, Up: Embedded Processors
|
|
|
| -21.3.9 Tsqware Sparclet
|
| +21.3.8 Tsqware Sparclet
|
| -----------------------
|
|
|
| GDB enables developers to debug tasks running on Sparclet targets from
|
| @@ -2905,7 +3692,7 @@ are ready to run GDB. From your Unix host, run `gdb' (or
|
|
|
| File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet
|
|
|
| -21.3.9.1 Setting File to Debug
|
| +21.3.8.1 Setting File to Debug
|
| ..............................
|
|
|
| The GDB command `file' lets you choose with program to debug.
|
| @@ -2929,7 +3716,7 @@ command again.
|
|
|
| File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet
|
|
|
| -21.3.9.2 Connecting to Sparclet
|
| +21.3.8.2 Connecting to Sparclet
|
| ...............................
|
|
|
| The GDB command `target' lets you connect to a Sparclet target. To
|
| @@ -2946,7 +3733,7 @@ connect to a target on serial port "`ttya'", type:
|
|
|
| File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet
|
|
|
| -21.3.9.3 Sparclet Download
|
| +21.3.8.3 Sparclet Download
|
| ..........................
|
|
|
| Once connected to the Sparclet target, you can use the GDB `load'
|
| @@ -2969,7 +3756,7 @@ 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
|
| +21.3.8.4 Running and Debugging
|
| ..............................
|
|
|
| You can now begin debugging the task using GDB's execution control
|
| @@ -2989,8 +3776,8 @@ commands.
|
|
|
| File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors
|
|
|
| -21.3.10 Fujitsu Sparclite
|
| --------------------------
|
| +21.3.9 Fujitsu Sparclite
|
| +------------------------
|
|
|
| `target sparclite DEV'
|
| Fujitsu sparclite boards, used only for the purpose of loading.
|
| @@ -3001,7 +3788,7 @@ File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded P
|
|
|
| File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors
|
|
|
| -21.3.11 Zilog Z8000
|
| +21.3.10 Zilog Z8000
|
| -------------------
|
|
|
| When configured for debugging Zilog Z8000 targets, GDB includes a Z8000
|
| @@ -3042,7 +3829,7 @@ 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
|
| +21.3.11 Atmel AVR
|
| -----------------
|
|
|
| When configured for debugging the Atmel AVR, GDB supports the following
|
| @@ -3055,7 +3842,7 @@ AVR-specific commands:
|
|
|
| File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors
|
|
|
| -21.3.13 CRIS
|
| +21.3.12 CRIS
|
| ------------
|
|
|
| When configured for debugging CRIS, GDB provides the following
|
| @@ -3088,17 +3875,11 @@ CRIS-specific commands:
|
|
|
| File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors
|
|
|
| -21.3.14 Renesas Super-H
|
| +21.3.13 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
|
| @@ -3127,17 +3908,36 @@ uses of GDB with the architecture, both native and cross.
|
|
|
| * Menu:
|
|
|
| +* AArch64::
|
| * i386::
|
| * Alpha::
|
| * MIPS::
|
| * HPPA:: HP PA architecture
|
| * SPU:: Cell Broadband Engine SPU architecture
|
| * PowerPC::
|
| +* Nios II::
|
|
|
|
|
| -File: gdb.info, Node: i386, Next: Alpha, Up: Architectures
|
| +File: gdb.info, Node: AArch64, Next: i386, Up: Architectures
|
| +
|
| +21.4.1 AArch64
|
| +--------------
|
| +
|
| +When GDB is debugging the AArch64 architecture, it provides the
|
| +following special commands:
|
| +
|
| +`set debug aarch64'
|
| + This command determines whether AArch64 architecture-specific
|
| + debugging messages are to be displayed.
|
|
|
| -21.4.1 x86 Architecture-specific Issues
|
| +`show debug aarch64'
|
| + Show whether AArch64 debugging messages are displayed.
|
| +
|
| +
|
| +
|
| +File: gdb.info, Node: i386, Next: Alpha, Prev: AArch64, Up: Architectures
|
| +
|
| +21.4.2 x86 Architecture-specific Issues
|
| ---------------------------------------
|
|
|
| `set struct-convention MODE'
|
| @@ -3152,10 +3952,46 @@ File: gdb.info, Node: i386, Next: Alpha, Up: Architectures
|
| Show the current setting of the convention to return `struct's
|
| from functions.
|
|
|
| +21.4.2.1 Intel(R) "Memory Protection Extensions" (MPX).
|
| +.......................................................
|
| +
|
| +Memory Protection Extension (MPX) adds the bound registers `BND0' (1)
|
| +through `BND3'. Bound registers store a pair of 64-bit values which
|
| +are the lower bound and upper bound. Bounds are effective addresses or
|
| +memory locations. The upper bounds are architecturally represented in
|
| +1's complement form. A bound having lower bound = 0, and upper bound =
|
| +0 (1's complement of all bits set) will allow access to the entire
|
| +address space.
|
| +
|
| + `BND0' through `BND3' are represented in GDB as `bnd0raw' through
|
| +`bnd3raw'. Pseudo registers `bnd0' through `bnd3' display the upper
|
| +bound performing the complement of one operation on the upper bound
|
| +value, i.e. when upper bound in `bnd0raw' is 0 in the GDB `bnd0' it
|
| +will be `0xfff...'. In this sense it can also be noted that the upper
|
| +bounds are inclusive.
|
| +
|
| + As an example, assume that the register BND0 holds bounds for a
|
| +pointer having access allowed for the range between 0x32 and 0x71. The
|
| +values present on bnd0raw and bnd registers are presented as follows:
|
| +
|
| + bnd0raw = {0x32, 0xffffffff8e}
|
| + bnd0 = {lbound = 0x32, ubound = 0x71} : size 64
|
| +
|
| + This way the raw value can be accessed via bnd0raw...bnd3raw. Any
|
| +change on bnd0...bnd3 or bnd0raw...bnd3raw is reflect on its
|
| +counterpart. When the bnd0...bnd3 registers are displayed via Python,
|
| +the display includes the memory size, in bits, accessible to the
|
| +pointer.
|
| +
|
| + ---------- Footnotes ----------
|
| +
|
| + (1) The register named with capital letters represent the
|
| +architecture registers.
|
| +
|
|
|
| File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures
|
|
|
| -21.4.2 Alpha
|
| +21.4.3 Alpha
|
| ------------
|
|
|
| See the following section.
|
| @@ -3163,7 +3999,7 @@ See the following section.
|
|
|
| File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures
|
|
|
| -21.4.3 MIPS
|
| +21.4.4 MIPS
|
| -----------
|
|
|
| Alpha- and MIPS-based computers use an unusual stack frame, which
|
| @@ -3275,7 +4111,7 @@ programs:
|
|
|
| File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures
|
|
|
| -21.4.4 HPPA
|
| +21.4.5 HPPA
|
| -----------
|
|
|
| When GDB is debugging the HP PA architecture, it provides the following
|
| @@ -3296,7 +4132,7 @@ special commands:
|
|
|
| File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures
|
|
|
| -21.4.5 Cell Broadband Engine SPU architecture
|
| +21.4.6 Cell Broadband Engine SPU architecture
|
| ---------------------------------------------
|
|
|
| When GDB is debugging the Cell Broadband Engine SPU architecture, it
|
| @@ -3343,8 +4179,8 @@ commands:
|
| 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
|
| + 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'
|
| @@ -3352,9 +4188,9 @@ commands:
|
|
|
|
|
|
|
| -File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures
|
| +File: gdb.info, Node: PowerPC, Next: Nios II, Prev: SPU, Up: Architectures
|
|
|
| -21.4.6 PowerPC
|
| +21.4.7 PowerPC
|
| --------------
|
|
|
| When GDB is debugging the PowerPC architecture, it provides a set of
|
| @@ -3371,13 +4207,29 @@ and `f3' for `$dl1' and so on.
|
| 64-bit wide Extended Floating Point Registers (`f32' through `f63').
|
|
|
|
|
| +File: gdb.info, Node: Nios II, Prev: PowerPC, Up: Architectures
|
| +
|
| +21.4.8 Nios II
|
| +--------------
|
| +
|
| +When GDB is debugging the Nios II architecture, it provides the
|
| +following special commands:
|
| +
|
| +`set debug nios2'
|
| + This command turns on and off debugging messages for the Nios II
|
| + target code in GDB.
|
| +
|
| +`show debug nios2'
|
| + Show the current setting of Nios II debugging messages.
|
| +
|
| +
|
| 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
|
| +command. For commands controlling how GDB displays data, see *note
|
| Print Settings: Print Settings. Other settings are described here.
|
|
|
| * Menu:
|
| @@ -3512,9 +4364,11 @@ history, use the `output' command instead of the `print' command.
|
| Stop recording command history in a file.
|
|
|
| `set history size SIZE'
|
| +`set history size unlimited'
|
| 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.
|
| + or to 256 if this variable is not set. If SIZE is `unlimited',
|
| + the number of commands GDB keeps in the history list is unlimited.
|
|
|
| History expansion assigns special meaning to the character `!'.
|
| *Note Event Designators::, for more details.
|
| @@ -3575,25 +4429,27 @@ and `stty cols' settings. If this is not correct, you can override it
|
| with the `set height' and `set width' commands:
|
|
|
| `set height LPP'
|
| +`set height unlimited'
|
| `show height'
|
| `set width CPL'
|
| +`set width unlimited'
|
| `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.
|
| + If you specify a height of either `unlimited' or 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.
|
| + Likewise, you can specify `set width unlimited' or `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
|
| + pagination off is the alternative to `set height unlimited'. Note
|
| + that running GDB with the `--batch' option (*note -batch: Mode
|
| Options.) also automatically disables pagination.
|
|
|
| `show pagination'
|
| @@ -3669,6 +4525,11 @@ 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.
|
|
|
| + When GDB is debugging the AArch64 architecture, it provides a
|
| +"Newlib" OS ABI. This is useful for handling `setjmp' and `longjmp'
|
| +when debugging binaries that use the NEWLIB C library. The "Newlib" OS
|
| +ABI can be selected by `set osabi Newlib'.
|
| +
|
| `show osabi'
|
| Show the OS ABI currently in use.
|
|
|
| @@ -3787,19 +4648,19 @@ control when to auto-load files and which files should be auto-loaded.
|
|
|
| These are various kinds of files GDB can automatically load:
|
|
|
| - * *Note objfile-gdb.py file::, controlled by *Note set auto-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
|
| + * *Note objfile-gdb.gdb file::, controlled by *note set auto-load
|
| gdb-scripts::.
|
|
|
| - * *Note dotdebug_gdb_scripts section::, controlled by *Note set
|
| + * *Note dotdebug_gdb_scripts section::, controlled by *note set
|
| auto-load python-scripts::.
|
|
|
| - * *Note Init File in the Current Directory::, controlled by *Note
|
| + * *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
|
| + * *Note libthread_db.so.1 file::, controlled by *note set auto-load
|
| libthread-db::.
|
|
|
| These are GDB control commands for the auto-loading:
|
| @@ -3855,7 +4716,7 @@ File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.s
|
| ---------------------------------------------------------------
|
|
|
| By default, GDB reads and executes the canned sequences of commands
|
| -from init file (if any) in the current working directory, see *Note
|
| +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
|
| @@ -3964,6 +4825,11 @@ will not get loaded:
|
| declined by your `auto-load safe-path' set
|
| to "$debugdir:$datadir/auto-load".
|
|
|
| +To instruct GDB to go ahead and use the init files anyway, invoke GDB
|
| +like this:
|
| +
|
| + $ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb
|
| +
|
| The list of trusted directories is controlled by the following
|
| commands:
|
|
|
| @@ -3992,7 +4858,7 @@ commands:
|
|
|
| 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
|
| +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'.
|
| @@ -4094,7 +4960,7 @@ 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.
|
| +`symbol-file' in *note Commands to Specify Files: Files.
|
|
|
| `set verbose on'
|
| Enables GDB output of certain informational messages.
|
| @@ -4177,13 +5043,29 @@ commands.
|
| Displays the current setting of asynchronous command completion
|
| notification.
|
|
|
| +`set debug aarch64'
|
| + Turns on or off display of debugging messages related to ARM
|
| + AArch64. The default is off.
|
| +
|
| +`show debug aarch64'
|
| + Displays the current state of displaying debugging messages
|
| + related to ARM AArch64.
|
| +
|
| `set debug arch'
|
| Turns on or off display of gdbarch debugging info. The default is
|
| - off
|
| + off
|
|
|
| `show debug arch'
|
| Displays the current state of displaying gdbarch debugging info.
|
|
|
| +`set debug aix-solib'
|
| + Control display of debugging messages from the AIX shared library
|
| + support module. The default is off.
|
| +
|
| +`show debug aix-thread'
|
| + Show the current state of displaying AIX shared library debugging
|
| + messages.
|
| +
|
| `set debug aix-thread'
|
| Display debugging messages about inner workings of the AIX thread
|
| module.
|
| @@ -4202,6 +5084,14 @@ commands.
|
| `show debug check-physname'
|
| Show the current state of "physname" checking.
|
|
|
| +`set debug coff-pe-read'
|
| + Control display of debugging messages related to reading of COFF/PE
|
| + exported symbols. The default is off.
|
| +
|
| +`show debug coff-pe-read'
|
| + Displays the current state of displaying debugging messages
|
| + related to reading of COFF/PE exported symbols.
|
| +
|
| `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.
|
| @@ -4211,7 +5101,9 @@ commands.
|
|
|
| `set debug dwarf2-read'
|
| Turns on or off display of debugging messages related to reading
|
| - DWARF debug info. The default is off.
|
| + DWARF debug info. The default is 0 (off). A value of 1 provides
|
| + basic information. A value greater than 1 provides more verbose
|
| + information.
|
|
|
| `show debug dwarf2-read'
|
| Show the current state of DWARF2 reader debugging.
|
| @@ -4274,6 +5166,22 @@ commands.
|
| `show debug lin-lwp'
|
| Show the current state of Linux LWP debugging messages.
|
|
|
| +`set debug mach-o'
|
| + Control display of debugging messages related to Mach-O symbols
|
| + processing. The default is off.
|
| +
|
| +`show debug mach-o'
|
| + Displays the current state of displaying debugging messages
|
| + related to reading of COFF/PE exported symbols.
|
| +
|
| +`set debug notification'
|
| + Turns on or off debugging messages about remote async notification.
|
| + The default is off.
|
| +
|
| +`show debug notification'
|
| + Displays the current state of remote async notification debugging
|
| + messages.
|
| +
|
| `set debug observer'
|
| Turns on or off display of GDB observer debugging. This includes
|
| info such as the notification of observable events.
|
| @@ -4321,9 +5229,18 @@ commands.
|
| Display the current state of FR-V shared-library code debugging
|
| messages.
|
|
|
| +`set debug symfile'
|
| + Turns on or off display of debugging messages related to symbol
|
| + file functions. The default is off. *Note Files::.
|
| +
|
| +`show debug symfile'
|
| + Show the current state of symbol file debugging messages.
|
| +
|
| `set debug symtab-create'
|
| Turns on or off display of debugging messages related to symbol
|
| - table creation. The default is off.
|
| + table creation. The default is 0 (off). A value of 1 provides
|
| + basic information. A value greater than 1 provides more verbose
|
| + information.
|
|
|
| `show debug symtab-create'
|
| Show the current state of symbol table creation debugging.
|
| @@ -4534,7 +5451,7 @@ been passed. This expands to a number in the range 0...10.
|
| user-defined python commands.
|
|
|
| In addition to the above commands, user-defined commands frequently
|
| -use control flow commands, described in *Note Command Files::.
|
| +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
|
| @@ -4882,10 +5799,25 @@ 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
|
| +GDB provides two commands for accessing the Python interpreter, and one
|
| related setting:
|
|
|
| -`python [CODE]'
|
| +`python-interactive [COMMAND]'
|
| +`pi [COMMAND]'
|
| + Without an argument, the `python-interactive' command can be used
|
| + to start an interactive Python prompt. To return to GDB, type the
|
| + `EOF' character (e.g., `Ctrl-D' on an empty prompt).
|
| +
|
| + Alternatively, a single-line Python command can be given as an
|
| + argument and evaluated. If the command is an expression, the
|
| + result will be printed; otherwise, nothing will be printed. For
|
| + example:
|
| +
|
| + (gdb) python-interactive 2 + 3
|
| + 5
|
| +
|
| +`python [COMMAND]'
|
| +`py [COMMAND]'
|
| The `python' command can be used to evaluate Python code.
|
|
|
| If given an argument, the `python' command will evaluate the
|
| @@ -4934,11 +5866,13 @@ File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Com
|
| 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.
|
| +You can get quick online help for GDB's Python API by issuing the
|
| +command `python help (gdb)'.
|
| +
|
| + Functions and methods which have two or more optional arguments allow
|
| +them to be specified using keyword syntax. This allows passing some
|
| +optional arguments while skipping others. Example:
|
| +`gdb.some_function ('foo', bar = 1, baz = 2)'.
|
|
|
| * Menu:
|
|
|
| @@ -4949,6 +5883,10 @@ user (*note Screen Size::). In this situation, a Python
|
| * Pretty Printing API:: Pretty-printing values.
|
| * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
|
| * Writing a Pretty-Printer:: Writing a Pretty-Printer.
|
| +* Type Printing API:: Pretty-printing types.
|
| +* Frame Filter API:: Filtering Frames.
|
| +* Frame Decorator API:: Decorating Frames.
|
| +* Writing a Frame Filter:: Writing a Frame Filter.
|
| * Inferiors In Python:: Python representation of inferiors (processes)
|
| * Events In Python:: Listening for events from GDB.
|
| * Threads In Python:: Accessing inferior threads from Python.
|
| @@ -4958,13 +5896,15 @@ user (*note Screen Size::). In this situation, a Python
|
| * 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.
|
| +* Blocks In Python:: Accessing blocks from Python.
|
| * Symbols In Python:: Python representation of symbols.
|
| * Symbol Tables In Python:: Python representation of symbol tables.
|
| +* Line Tables In Python:: Python representation of line 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.
|
| +* Architectures In Python:: Python representation of architectures.
|
|
|
|
|
| File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API
|
| @@ -4972,7 +5912,29 @@ 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
|
| +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.
|
| +
|
| + Some care must be taken when writing Python code to run in GDB. Two
|
| +things worth noting in particular:
|
| +
|
| + * GDB install handlers for `SIGCHLD' and `SIGINT'. Python code must
|
| + not override these, or even change the options using `sigaction'.
|
| + If your program changes the handling of these signals, GDB will
|
| + most likely stop working correctly. Note that it is unfortunately
|
| + common for GUI toolkits to install a `SIGCHLD' handler.
|
| +
|
| + * GDB takes care to mark its internal file descriptors as
|
| + close-on-exec. However, this cannot be done in a thread-safe way
|
| + on all platforms. Your Python programs should be aware of this and
|
| + should both create new file descriptors with the close-on-exec flag
|
| + set and arrange to close unneeded file descriptors before starting
|
| + a child process.
|
| +
|
| + 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.
|
| @@ -4983,7 +5945,7 @@ classes added by GDB are placed in this module. GDB automatically
|
| -- 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.
|
| + 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
|
| @@ -5262,245 +6224,236 @@ function, call it like so:
|
|
|
| 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.
|
| + -- 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.
|
| + -- Function: Value.__init__ (VAL)
|
| + Many Python values can be converted directly to a `gdb.Value' via
|
| + this object initializer. Specifically:
|
|
|
| - 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.
|
| + 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
|
| @@ -5535,132 +6488,141 @@ 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.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.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.
|
| + -- 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.
|
| + -- 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.vector (N1 [, N2])
|
| + Return a new `gdb.Type' object which represents a vector of this
|
| + type. If one argument is given, it is the inclusive upper bound of
|
| + the vector; in this case the lower bound is zero. If two
|
| + arguments are given, the first argument is the lower bound of the
|
| + vector, and the second argument is the upper bound of the vector.
|
| + A vector's length must not be negative, but the bounds can be.
|
| +
|
| + The difference between an `array' and a `vector' is that arrays
|
| + behave like in C: when used in expressions they decay to a pointer
|
| + to the first element whereas vectors are treated as first class
|
| + values.
|
| +
|
| + -- 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
|
| @@ -5708,7 +6670,7 @@ defined in the `gdb' module:
|
| this way.
|
|
|
| `gdb.TYPE_CODE_BITSTRING'
|
| - A string of bits.
|
| + A string of bits. It is deprecated.
|
|
|
| `gdb.TYPE_CODE_ERROR'
|
| An unknown or erroneous type.
|
| @@ -5888,7 +6850,7 @@ 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
|
| +File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API
|
|
|
| 23.2.2.7 Writing a Pretty-Printer
|
| .................................
|
| @@ -6038,1567 +7000,375 @@ corresponding output of `info pretty-printer':
|
| 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
|
| -...........................
|
| +File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API
|
|
|
| -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.
|
| +23.2.2.8 Type Printing API
|
| +..........................
|
|
|
| - A `gdb.Symtab' object has the following methods:
|
| +GDB provides a way for Python code to customize type display. This is
|
| +mainly useful for substituting canonical typedef names for types.
|
|
|
| - -- 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.
|
| + A "type printer" is just a Python object conforming to a certain
|
| +protocol. A simple base class implementing the protocol is provided;
|
| +see *note gdb.types::. A type printer must supply at least:
|
|
|
| - -- Function: Symtab.fullname ()
|
| - Return the symbol table's source absolute file name.
|
| + -- Instance Variable of type_printer: enabled
|
| + A boolean which is True if the printer is enabled, and False
|
| + otherwise. This is manipulated by the `enable type-printer' and
|
| + `disable type-printer' commands.
|
|
|
| - -- Function: Symtab.global_block ()
|
| - Return the global block of the underlying symbol table.
|
| - *Note Blocks In Python::.
|
| + -- Instance Variable of type_printer: name
|
| + The name of the type printer. This must be a string. This is
|
| + used by the `enable type-printer' and `disable type-printer'
|
| + commands.
|
|
|
| - -- Function: Symtab.static_block ()
|
| - Return the static block of the underlying symbol table.
|
| - *Note Blocks In Python::.
|
| + -- Method on type_printer: instantiate (self)
|
| + This is called by GDB at the start of type-printing. It is only
|
| + called if the type printer is enabled. This method must return a
|
| + new object that supplies a `recognize' method, as described below.
|
| +
|
| + When displaying a type, say via the `ptype' command, GDB will
|
| +compute a list of type recognizers. This is done by iterating first
|
| +over the per-objfile type printers (*note Objfiles In Python::),
|
| +followed by the per-progspace type printers (*note Progspaces In
|
| +Python::), and finally the global type printers.
|
| +
|
| + GDB will call the `instantiate' method of each enabled type printer.
|
| +If this method returns `None', then the result is ignored; otherwise,
|
| +it is appended to the list of recognizers.
|
| +
|
| + Then, when GDB is going to display a type name, it iterates over the
|
| +list of recognizers. For each one, it calls the recognition function,
|
| +stopping if the function returns a non-`None' value. The recognition
|
| +function is defined as:
|
| +
|
| + -- Method on type_recognizer: recognize (self, type)
|
| + If TYPE is not recognized, return `None'. Otherwise, return a
|
| + string which is to be printed as the name of TYPE. TYPE will be
|
| + an instance of `gdb.Type' (*note Types In Python::).
|
| +
|
| + GDB uses this two-pass approach so that type printers can
|
| +efficiently cache information without holding on to it too long. For
|
| +example, it can be convenient to look up type information in a type
|
| +printer and hold it for a recognizer's lifetime; if a single pass were
|
| +done then type printers would have to make use of the event system in
|
| +order to avoid holding information that could become stale as the
|
| +inferior changed.
|
|
|
|
|
| -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.
|
| +File: gdb.info, Node: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API
|
|
|
| - -- 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.
|
| +23.2.2.9 Filtering Frames.
|
| +..........................
|
|
|
| - -- 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.
|
| +Frame filters are Python objects that manipulate the visibility of a
|
| +frame or frames when a backtrace (*note Backtrace::) is printed by GDB.
|
| +
|
| + Only commands that print a backtrace, or, in the case of GDB/MI
|
| +commands (*note GDB/MI::), those that return a collection of frames are
|
| +affected. The commands that work with frame filters are:
|
| +
|
| + `backtrace' (*note The backtrace command: backtrace-command.),
|
| +`-stack-list-frames' (*note The -stack-list-frames command:
|
| +-stack-list-frames.), `-stack-list-variables' (*note The
|
| +-stack-list-variables command: -stack-list-variables.),
|
| +`-stack-list-arguments' *note The -stack-list-arguments command:
|
| +-stack-list-arguments.) and `-stack-list-locals' (*note The
|
| +-stack-list-locals command: -stack-list-locals.).
|
| +
|
| + A frame filter works by taking an iterator as an argument, applying
|
| +actions to the contents of that iterator, and returning another
|
| +iterator (or, possibly, the same iterator it was provided in the case
|
| +where the filter does not perform any operations). Typically, frame
|
| +filters utilize tools such as the Python's `itertools' module to work
|
| +with and create new iterators from the source iterator. Regardless of
|
| +how a filter chooses to apply actions, it must not alter the underlying
|
| +GDB frame or frames, or attempt to alter the call-stack within GDB.
|
| +This preserves data integrity within GDB. Frame filters are executed
|
| +on a priority basis and care should be taken that some frame filters
|
| +may have been executed before, and that some frame filters will be
|
| +executed after.
|
| +
|
| + An important consideration when designing frame filters, and well
|
| +worth reflecting upon, is that frame filters should avoid unwinding the
|
| +call stack if possible. Some stacks can run very deep, into the tens
|
| +of thousands in some cases. To search every frame when a frame filter
|
| +executes may be too expensive at that step. The frame filter cannot
|
| +know how many frames it has to iterate over, and it may have to iterate
|
| +through them all. This ends up duplicating effort as GDB performs this
|
| +iteration when it prints the frames. If the filter can defer unwinding
|
| +frames until frame decorators are executed, after the last filter has
|
| +executed, it should. *Note Frame Decorator API::, for more information
|
| +on decorators. Also, there are examples for both frame decorators and
|
| +filters in later chapters. *Note Writing a Frame Filter::, for more
|
| +information.
|
| +
|
| + The Python dictionary `gdb.frame_filters' contains key/object
|
| +pairings that comprise a frame filter. Frame filters in this
|
| +dictionary are called `global' frame filters, and they are available
|
| +when debugging all inferiors. These frame filters must register with
|
| +the dictionary directly. In addition to the `global' dictionary, there
|
| +are other dictionaries that are loaded with different inferiors via
|
| +auto-loading (*note Python Auto-loading::). The two other areas where
|
| +frame filter dictionaries can be found are: `gdb.Progspace' which
|
| +contains a `frame_filters' dictionary attribute, and each `gdb.Objfile'
|
| +object which also contains a `frame_filters' dictionary attribute.
|
| +
|
| + When a command is executed from GDB that is compatible with frame
|
| +filters, GDB combines the `global', `gdb.Progspace' and all
|
| +`gdb.Objfile' dictionaries currently loaded. All of the `gdb.Objfile'
|
| +dictionaries are combined, as several frames, and thus several object
|
| +files, might be in use. GDB then prunes any frame filter whose
|
| +`enabled' attribute is `False'. This pruned list is then sorted
|
| +according to the `priority' attribute in each filter.
|
| +
|
| + Once the dictionaries are combined, pruned and sorted, GDB creates
|
| +an iterator which wraps each frame in the call stack in a
|
| +`FrameDecorator' object, and calls each filter in order. The output
|
| +from the previous filter will always be the input to the next filter,
|
| +and so on.
|
| +
|
| + Frame filters have a mandatory interface which each frame filter must
|
| +implement, defined here:
|
| +
|
| + -- Function: FrameFilter.filter (iterator)
|
| + GDB will call this method on a frame filter when it has reached
|
| + the order in the priority list for that filter.
|
| +
|
| + For example, if there are four frame filters:
|
| +
|
| + Name Priority
|
| +
|
| + Filter1 5
|
| + Filter2 10
|
| + Filter3 100
|
| + Filter4 1
|
| +
|
| + The order that the frame filters will be called is:
|
| +
|
| + Filter3 -> Filter2 -> Filter1 -> Filter4
|
| +
|
| + Note that the output from `Filter3' is passed to the input of
|
| + `Filter2', and so on.
|
| +
|
| + This `filter' method is passed a Python iterator. This iterator
|
| + contains a sequence of frame decorators that wrap each
|
| + `gdb.Frame', or a frame decorator that wraps another frame
|
| + decorator. The first filter that is executed in the sequence of
|
| + frame filters will receive an iterator entirely comprised of
|
| + default `FrameDecorator' objects. However, after each frame
|
| + filter is executed, the previous frame filter may have wrapped
|
| + some or all of the frame decorators with their own frame
|
| + decorator. As frame decorators must also conform to a mandatory
|
| + interface, these decorators can be assumed to act in a uniform
|
| + manner (*note Frame Decorator API::).
|
|
|
| - -- 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.
|
| + This method must return an object conforming to the Python iterator
|
| + protocol. Each item in the iterator must be an object conforming
|
| + to the frame decorator interface. If a frame filter does not wish
|
| + to perform any operations on this iterator, it should return that
|
| + iterator untouched.
|
| +
|
| + This method is not optional. If it does not exist, GDB will raise
|
| + and print an error.
|
| +
|
| + -- Variable: FrameFilter.name
|
| + The `name' attribute must be Python string which contains the name
|
| + of the filter displayed by GDB (*note Frame Filter Management::).
|
| + This attribute may contain any combination of letters or numbers.
|
| + Care should be taken to ensure that it is unique. This attribute
|
| + is mandatory.
|
| +
|
| + -- Variable: FrameFilter.enabled
|
| + The `enabled' attribute must be Python boolean. This attribute
|
| + indicates to GDB whether the frame filter is enabled, and should
|
| + be considered when frame filters are executed. If `enabled' is
|
| + `True', then the frame filter will be executed when any of the
|
| + backtrace commands detailed earlier in this chapter are executed.
|
| + If `enabled' is `False', then the frame filter will not be
|
| + executed. This attribute is mandatory.
|
| +
|
| + -- Variable: FrameFilter.priority
|
| + The `priority' attribute must be Python integer. This attribute
|
| + controls the order of execution in relation to other frame filters.
|
| + There are no imposed limits on the range of `priority' other than
|
| + it must be a valid integer. The higher the `priority' attribute,
|
| + the sooner the frame filter will be executed in relation to other
|
| + frame filters. Although `priority' can be negative, it is
|
| + recommended practice to assume zero is the lowest priority that a
|
| + frame filter can be assigned. Frame filters that have the same
|
| + priority are executed in unsorted order in that priority slot.
|
| + This attribute is mandatory.
|
|
|
|
|
| -File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API
|
| +File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API
|
|
|
| -23.2.2.21 Finish Breakpoints
|
| +23.2.2.10 Decorating Frames.
|
| ............................
|
|
|
| -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:
|
| +Frame decorators are sister objects to frame filters (*note Frame
|
| +Filter API::). Frame decorators are applied by a frame filter and can
|
| +only be used in conjunction with frame filters.
|
|
|
| -* objfile-gdb.py file:: The `OBJFILE-gdb.py' file
|
| -* dotdebug_gdb_scripts section:: The `.debug_gdb_scripts' section
|
| -* Which flavor to choose?::
|
| + The purpose of a frame decorator is to customize the printed content
|
| +of each `gdb.Frame' in commands where frame filters are executed. This
|
| +concept is called decorating a frame. Frame decorators decorate a
|
| +`gdb.Frame' with Python code contained within each API call. This
|
| +separates the actual data contained in a `gdb.Frame' from the decorated
|
| +data produced by a frame decorator. This abstraction is necessary to
|
| +maintain integrity of the data contained in each `gdb.Frame'.
|
| +
|
| + Frame decorators have a mandatory interface, defined below.
|
| +
|
| + GDB already contains a frame decorator called `FrameDecorator'.
|
| +This contains substantial amounts of boilerplate code to decorate the
|
| +content of a `gdb.Frame'. It is recommended that other frame
|
| +decorators inherit and extend this object, and only to override the
|
| +methods needed.
|
| +
|
| + -- Function: FrameDecorator.elided (self)
|
| + The `elided' method groups frames together in a hierarchical
|
| + system. An example would be an interpreter, where multiple
|
| + low-level frames make up a single call in the interpreted
|
| + language. In this example, the frame filter would elide the
|
| + low-level frames and present a single high-level frame,
|
| + representing the call in the interpreted language, to the user.
|
| +
|
| + The `elided' function must return an iterable and this iterable
|
| + must contain the frames that are being elided wrapped in a suitable
|
| + frame decorator. If no frames are being elided this function may
|
| + return an empty iterable, or `None'. Elided frames are indented
|
| + from normal frames in a `CLI' backtrace, or in the case of
|
| + `GDB/MI', are placed in the `children' field of the eliding frame.
|
| +
|
| + It is the frame filter's task to also filter out the elided frames
|
| + from the source iterator. This will avoid printing the frame
|
| + twice.
|
| +
|
| + -- Function: FrameDecorator.function (self)
|
| + This method returns the name of the function in the frame that is
|
| + to be printed.
|
| +
|
| + This method must return a Python string describing the function, or
|
| + `None'.
|
| +
|
| + If this function returns `None', GDB will not print any data for
|
| + this field.
|
| +
|
| + -- Function: FrameDecorator.address (self)
|
| + This method returns the address of the frame that is to be printed.
|
| +
|
| + This method must return a Python numeric integer type of sufficient
|
| + size to describe the address of the frame, or `None'.
|
| +
|
| + If this function returns a `None', GDB will not print any data for
|
| + this field.
|
| +
|
| + -- Function: FrameDecorator.filename (self)
|
| + This method returns the filename and path associated with this
|
| + frame.
|
| +
|
| + This method must return a Python string containing the filename and
|
| + the path to the object file backing the frame, or `None'.
|
| +
|
| + If this function returns a `None', GDB will not print any data for
|
| + this field.
|
| +
|
| + -- Function: FrameDecorator.line (self):
|
| + This method returns the line number associated with the current
|
| + position within the function addressed by this frame.
|
| +
|
| + This method must return a Python integer type, or `None'.
|
| +
|
| + If this function returns a `None', GDB will not print any data for
|
| + this field.
|
| +
|
| + -- Function: FrameDecorator.frame_args (self)
|
| + This method must return an iterable, or `None'. Returning an
|
| + empty iterable, or `None' means frame arguments will not be
|
| + printed for this frame. This iterable must contain objects that
|
| + implement two methods, described here.
|
| +
|
| + This object must implement a `argument' method which takes a
|
| + single `self' parameter and must return a `gdb.Symbol' (*note
|
| + Symbols In Python::), or a Python string. The object must also
|
| + implement a `value' method which takes a single `self' parameter
|
| + and must return a `gdb.Value' (*note Values From Inferior::), a
|
| + Python value, or `None'. If the `value' method returns `None',
|
| + and the `argument' method returns a `gdb.Symbol', GDB will look-up
|
| + and print the value of the `gdb.Symbol' automatically.
|
| +
|
| + A brief example:
|
| +
|
| + class SymValueWrapper():
|
| +
|
| + def __init__(self, symbol, value):
|
| + self.sym = symbol
|
| + self.val = value
|
| +
|
| + def value(self):
|
| + return self.val
|
| +
|
| + def symbol(self):
|
| + return self.sym
|
| +
|
| + class SomeFrameDecorator()
|
| + ...
|
| + ...
|
| + def frame_args(self):
|
| + args = []
|
| + try:
|
| + block = self.inferior_frame.block()
|
| + except:
|
| + return None
|
| +
|
| + # Iterate over all symbols in a block. Only add
|
| + # symbols that are arguments.
|
| + for sym in block:
|
| + if not sym.is_argument:
|
| + continue
|
| + args.append(SymValueWrapper(sym,None))
|
| +
|
| + # Add example synthetic argument.
|
| + args.append(SymValueWrapper(``foo'', 42))
|
| +
|
| + return args
|
| +
|
| + -- Function: FrameDecorator.frame_locals (self)
|
| + This method must return an iterable or `None'. Returning an empty
|
| + iterable, or `None' means frame local arguments will not be
|
| + printed for this frame.
|
| +
|
| + The object interface, the description of the various strategies for
|
| + reading frame locals, and the example are largely similar to those
|
| + described in the `frame_args' function, (*note The frame filter
|
| + frame_args function: frame_args.). Below is a modified example:
|
| +
|
| + class SomeFrameDecorator()
|
| + ...
|
| + ...
|
| + def frame_locals(self):
|
| + vars = []
|
| + try:
|
| + block = self.inferior_frame.block()
|
| + except:
|
| + return None
|
| +
|
| + # Iterate over all symbols in a block. Add all
|
| + # symbols, except arguments.
|
| + for sym in block:
|
| + if sym.is_argument:
|
| + continue
|
| + vars.append(SymValueWrapper(sym,None))
|
| +
|
| + # Add an example of a synthetic local variable.
|
| + vars.append(SymValueWrapper(``bar'', 99))
|
| +
|
| + return vars
|
| +
|
| + -- Function: FrameDecorator.inferior_frame (self):
|
| + This method must return the underlying `gdb.Frame' that this frame
|
| + decorator is decorating. GDB requires the underlying frame for
|
| + internal frame information to determine how to print certain
|
| + values when printing a frame.
|
|
|
|
|
Chromium Code Reviews
Issue 124383005:
GDB 7.6.50 (Closed)
Base URL: http://git.chromium.org/native_client/nacl-gdb.git@upstream