| This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo. |
| |
| Copyright (C) 1988-2020 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| 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 |
| |
| 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 9.2. |
| |
| Copyright (C) 1988-2020 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Screen Size, Next: Output Styling, Prev: Command History, Up: Controlling GDB |
| |
| 22.4 Screen Size |
| ================ |
| |
| Certain commands to GDB may produce large amounts of information output |
| to the screen. To help you read all of it, GDB pauses and asks you for |
| input at the end of each page of output. Type <RET> when you want to |
| see one more page of output, 'q' to discard the remaining output, or 'c' |
| to continue without paging for the rest of the current command. Also, |
| the screen width setting determines when to wrap lines of output. |
| Depending on what is being printed, GDB tries to break the line at a |
| readable place, rather than simply letting it overflow onto the |
| following line. |
| |
| Normally GDB knows the size of the screen from the terminal driver |
| software. For example, on Unix GDB uses the termcap data base together |
| with the value of the 'TERM' environment variable and the 'stty rows' |
| and 'stty cols' settings. If this is not correct, you can override it |
| with the 'set height' and 'set width' commands: |
| |
| 'set height LPP' |
| '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 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 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 unlimited'. Note |
| that running GDB with the '--batch' option (*note -batch: Mode |
| Options.) also automatically disables pagination. |
| |
| 'show pagination' |
| Show the current pagination mode. |
| |
| |
| File: gdb.info, Node: Output Styling, Next: Numbers, Prev: Screen Size, Up: Controlling GDB |
| |
| 22.5 Output Styling |
| =================== |
| |
| GDB can style its output on a capable terminal. This is enabled by |
| default on most systems, but disabled by default when in batch mode |
| (*note Mode Options::). Various style settings are available; and |
| styles can also be disabled entirely. |
| |
| 'set style enabled 'on|off'' |
| Enable or disable all styling. The default is host-dependent, with |
| most hosts defaulting to 'on'. |
| |
| 'show style enabled' |
| Show the current state of styling. |
| |
| 'set style sources 'on|off'' |
| Enable or disable source code styling. This affects whether source |
| code, such as the output of the 'list' command, is styled. Note |
| that source styling only works if styling in general is enabled, |
| and if GDB was linked with the GNU Source Highlight library. The |
| default is 'on'. |
| |
| 'show style sources' |
| Show the current state of source code styling. |
| |
| Subcommands of 'set style' control specific forms of styling. These |
| subcommands all follow the same pattern: each style-able object can be |
| styled with a foreground color, a background color, and an intensity. |
| |
| For example, the style of file names can be controlled using the 'set |
| style filename' group of commands: |
| |
| 'set style filename background COLOR' |
| Set the background to COLOR. Valid colors are 'none' (meaning the |
| terminal's default color), 'black', 'red', 'green', 'yellow', |
| 'blue', 'magenta', 'cyan', and'white'. |
| |
| 'set style filename foreground COLOR' |
| Set the foreground to COLOR. Valid colors are 'none' (meaning the |
| terminal's default color), 'black', 'red', 'green', 'yellow', |
| 'blue', 'magenta', 'cyan', and'white'. |
| |
| 'set style filename intensity VALUE' |
| Set the intensity to VALUE. Valid intensities are 'normal' (the |
| default), 'bold', and 'dim'. |
| |
| The 'show style' command and its subcommands are styling a style name |
| in their output using its own style. So, use 'show style' to see the |
| complete list of styles, their characteristics and the visual aspect of |
| each style. |
| |
| The style-able objects are: |
| 'filename' |
| Control the styling of file names. By default, this style's |
| foreground color is green. |
| |
| 'function' |
| Control the styling of function names. These are managed with the |
| 'set style function' family of commands. By default, this style's |
| foreground color is yellow. |
| |
| 'variable' |
| Control the styling of variable names. These are managed with the |
| 'set style variable' family of commands. By default, this style's |
| foreground color is cyan. |
| |
| 'address' |
| Control the styling of addresses. These are managed with the 'set |
| style address' family of commands. By default, this style's |
| foreground color is blue. |
| |
| 'title' |
| Control the styling of titles. These are managed with the 'set |
| style title' family of commands. By default, this style's |
| intensity is bold. Commands are using the title style to improve |
| the readability of large output. For example, the commands |
| 'apropos' and 'help' are using the title style for the command |
| names. |
| |
| 'highlight' |
| Control the styling of highlightings. These are managed with the |
| 'set style highlight' family of commands. By default, this style's |
| foreground color is red. Commands are using the highlight style to |
| draw the user attention to some specific parts of their output. |
| For example, the command 'apropos -v REGEXP' uses the highlight |
| style to mark the documentation parts matching REGEXP. |
| |
| 'tui-border' |
| Control the styling of the TUI border. Note that, unlike other |
| styling options, only the color of the border can be controlled via |
| 'set style'. This was done for compatibility reasons, as TUI |
| controls to set the border's intensity predated the addition of |
| general styling to GDB. *Note TUI Configuration::. |
| |
| 'tui-active-border' |
| Control the styling of the active TUI border; that is, the TUI |
| window that has the focus. |
| |
| |
| File: gdb.info, Node: Numbers, Next: ABI, Prev: Output Styling, Up: Controlling GDB |
| |
| 22.6 Numbers |
| ============ |
| |
| You can always enter numbers in octal, decimal, or hexadecimal in GDB by |
| the usual conventions: octal numbers begin with '0', decimal numbers end |
| with '.', and hexadecimal numbers begin with '0x'. Numbers that neither |
| begin with '0' or '0x', nor end with a '.' are, by default, entered in |
| base 10; likewise, the default display for numbers--when no particular |
| format is specified--is base 10. You can change the default base for |
| both input and output with the commands described below. |
| |
| 'set input-radix BASE' |
| Set the default base for numeric input. Supported choices for BASE |
| are decimal 8, 10, or 16. The base must itself be specified either |
| unambiguously or using the current input radix; for example, any of |
| |
| set input-radix 012 |
| set input-radix 10. |
| set input-radix 0xa |
| |
| sets the input base to decimal. On the other hand, 'set |
| input-radix 10' leaves the input radix unchanged, no matter what it |
| was, since '10', being without any leading or trailing signs of its |
| base, is interpreted in the current radix. Thus, if the current |
| radix is 16, '10' is interpreted in hex, i.e. as 16 decimal, which |
| doesn't change the radix. |
| |
| 'set output-radix BASE' |
| Set the default base for numeric display. Supported choices for |
| BASE are decimal 8, 10, or 16. The base must itself be specified |
| either unambiguously or using the current input radix. |
| |
| 'show input-radix' |
| Display the current default base for numeric input. |
| |
| 'show output-radix' |
| Display the current default base for numeric display. |
| |
| 'set radix [BASE]' |
| 'show radix' |
| These commands set and show the default base for both input and |
| output of numbers. 'set radix' sets the radix of input and output |
| to the same base; without an argument, it resets the radix back to |
| its default value of 10. |
| |
| |
| File: gdb.info, Node: ABI, Next: Auto-loading, Prev: Numbers, Up: Controlling GDB |
| |
| 22.7 Configuring the Current ABI |
| ================================ |
| |
| GDB can determine the "ABI" (Application Binary Interface) of your |
| application automatically. However, sometimes you need to override its |
| conclusions. Use these commands to manage GDB's view of the current |
| ABI. |
| |
| One GDB configuration can debug binaries for multiple operating |
| system targets, either via remote debugging or native emulation. GDB |
| will autodetect the "OS ABI" (Operating System ABI) in use, but you can |
| override its conclusion using the 'set osabi' command. One example |
| where this is useful is in debugging of binaries which use an alternate |
| C library (e.g. UCLIBC for GNU/Linux) which does not have the same |
| identifying marks that the standard C library for your platform |
| provides. |
| |
| 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. |
| |
| 'set osabi' |
| With no argument, show the list of registered available OS ABI's. |
| |
| 'set osabi ABI' |
| Set the current OS ABI to ABI. |
| |
| Generally, the way that an argument of type 'float' is passed to a |
| function depends on whether the function is prototyped. For a |
| prototyped (i.e. ANSI/ISO style) function, 'float' arguments are passed |
| unchanged, according to the architecture's convention for 'float'. For |
| unprototyped (i.e. K&R style) functions, 'float' arguments are first |
| promoted to type 'double' and then passed. |
| |
| Unfortunately, some forms of debug information do not reliably |
| indicate whether a function is prototyped. If GDB calls a function that |
| is not marked as prototyped, it consults 'set coerce-float-to-double'. |
| |
| 'set coerce-float-to-double' |
| 'set coerce-float-to-double on' |
| Arguments of type 'float' will be promoted to 'double' when passed |
| to an unprototyped function. This is the default setting. |
| |
| 'set coerce-float-to-double off' |
| Arguments of type 'float' will be passed directly to unprototyped |
| functions. |
| |
| 'show coerce-float-to-double' |
| Show the current setting of promoting 'float' to 'double'. |
| |
| GDB needs to know the ABI used for your program's C++ objects. The |
| correct C++ ABI depends on which C++ compiler was used to build your |
| application. GDB only fully supports programs with a single C++ ABI; if |
| your program contains code using multiple C++ ABI's or if GDB can not |
| identify your program's ABI correctly, you can tell GDB which ABI to |
| use. Currently supported ABI's include "gnu-v2", for 'g++' versions |
| before 3.0, "gnu-v3", for 'g++' versions 3.0 and later, and "hpaCC" for |
| the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or |
| "gnu-v3" ABI's as well. The default setting is "auto". |
| |
| 'show cp-abi' |
| Show the C++ ABI currently in use. |
| |
| 'set cp-abi' |
| With no argument, show the list of supported C++ ABI's. |
| |
| 'set cp-abi ABI' |
| 'set cp-abi auto' |
| Set the current C++ ABI to ABI, or return to automatic detection. |
| |
| |
| File: gdb.info, Node: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up: Controlling GDB |
| |
| 22.8 Automatically loading associated files |
| =========================================== |
| |
| GDB sometimes reads files with commands and settings automatically, |
| without being explicitly told so by the user. We call this feature |
| "auto-loading". While auto-loading is useful for automatically adapting |
| GDB to the needs of your project, it can sometimes produce unexpected |
| results or introduce security risks (e.g., if the file comes from |
| untrusted sources). |
| |
| * Menu: |
| |
| * Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit' |
| * libthread_db.so.1 file:: 'set/show/info auto-load libthread-db' |
| |
| * Auto-loading safe path:: 'set/show/info auto-load safe-path' |
| * Auto-loading verbose mode:: 'set/show debug auto-load' |
| |
| There are various kinds of files GDB can automatically load. In |
| addition to these files, GDB supports auto-loading code written in |
| various extension languages. *Note Auto-loading extensions::. |
| |
| Note that loading of these associated files (including the local |
| '.gdbinit' file) requires accordingly configured 'auto-load safe-path' |
| (*note Auto-loading safe path::). |
| |
| For these reasons, GDB includes commands and options to let you |
| control when to auto-load files and which files should be auto-loaded. |
| |
| 'set auto-load off' |
| Globally disable loading of all auto-loaded files. You may want to |
| use this command with the '-iex' option (*note Option |
| -init-eval-command::) such as: |
| $ gdb -iex "set auto-load off" untrusted-executable corefile |
| |
| Be aware that system init file (*note System-wide configuration::) |
| and init files from your home directory (*note Home Directory Init |
| File::) still get read (as they come from generally trusted |
| directories). To prevent GDB from auto-loading even those init |
| files, use the '-nx' option (*note Mode Options::), in addition to |
| 'set auto-load no'. |
| |
| 'show auto-load' |
| Show whether auto-loading of each specific 'auto-load' file(s) is |
| enabled or disabled. |
| |
| (gdb) show auto-load |
| gdb-scripts: Auto-loading of canned sequences of commands scripts is on. |
| libthread-db: Auto-loading of inferior specific libthread_db is on. |
| local-gdbinit: Auto-loading of .gdbinit script from current directory |
| is on. |
| python-scripts: Auto-loading of Python scripts is on. |
| safe-path: List of directories from which it is safe to auto-load files |
| is $debugdir:$datadir/auto-load. |
| scripts-directory: List of directories from which to load auto-loaded scripts |
| is $debugdir:$datadir/auto-load. |
| |
| 'info auto-load' |
| Print whether each specific 'auto-load' file(s) have been |
| auto-loaded or not. |
| |
| (gdb) info auto-load |
| gdb-scripts: |
| Loaded Script |
| Yes /home/user/gdb/gdb-gdb.gdb |
| libthread-db: No auto-loaded libthread-db. |
| local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been |
| loaded. |
| python-scripts: |
| Loaded Script |
| Yes /home/user/gdb/gdb-gdb.py |
| |
| These are GDB control commands for the auto-loading: |
| |
| *Note set auto-load off::. Disable auto-loading globally. |
| *Note show auto-load::. Show setting of all kinds of |
| files. |
| *Note info auto-load::. Show state of all kinds of files. |
| *Note set auto-load gdb-scripts::. Control for GDB command scripts. |
| *Note show auto-load gdb-scripts::. Show setting of GDB command |
| scripts. |
| *Note info auto-load gdb-scripts::. Show state of GDB command scripts. |
| *Note set auto-load python-scripts::.Control for GDB Python scripts. |
| *Note show auto-load python-scripts::.Show setting of GDB Python |
| scripts. |
| *Note info auto-load python-scripts::.Show state of GDB Python scripts. |
| *Note set auto-load guile-scripts::. Control for GDB Guile scripts. |
| *Note show auto-load guile-scripts::.Show setting of GDB Guile scripts. |
| *Note info auto-load guile-scripts::.Show state of GDB Guile scripts. |
| *Note set auto-load scripts-directory::.Control for GDB auto-loaded |
| scripts location. |
| *Note show auto-load scripts-directory::.Show GDB auto-loaded scripts |
| location. |
| *Note add-auto-load-scripts-directory::.Add directory for auto-loaded |
| scripts location list. |
| *Note set auto-load local-gdbinit::. Control for init file in the |
| current directory. |
| *Note show auto-load local-gdbinit::.Show setting of init file in the |
| current directory. |
| *Note info auto-load local-gdbinit::.Show state of init file in the |
| current directory. |
| *Note set auto-load libthread-db::. Control for thread debugging |
| library. |
| *Note show auto-load libthread-db::. Show setting of thread debugging |
| library. |
| *Note info auto-load libthread-db::. Show state of thread debugging |
| library. |
| *Note set auto-load safe-path::. Control directories trusted for |
| automatic loading. |
| *Note show auto-load safe-path::. Show directories trusted for |
| automatic loading. |
| *Note add-auto-load-safe-path::. Add directory trusted for |
| automatic loading. |
| |
| |
| File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.so.1 file, Up: Auto-loading |
| |
| 22.8.1 Automatically loading init file in the current directory |
| --------------------------------------------------------------- |
| |
| By default, GDB reads and executes the canned sequences of commands from |
| init file (if any) in the current working directory, see *note Init File |
| in the Current Directory during Startup::. |
| |
| Note that loading of this local '.gdbinit' file also requires |
| accordingly configured 'auto-load safe-path' (*note Auto-loading safe |
| path::). |
| |
| 'set auto-load local-gdbinit [on|off]' |
| Enable or disable the auto-loading of canned sequences of commands |
| (*note Sequences::) found in init file in the current directory. |
| |
| 'show auto-load local-gdbinit' |
| Show whether auto-loading of canned sequences of commands from init |
| file in the current directory is enabled or disabled. |
| |
| 'info auto-load local-gdbinit' |
| Print whether canned sequences of commands from init file in the |
| current directory have been auto-loaded. |
| |
| |
| File: gdb.info, Node: libthread_db.so.1 file, Next: Auto-loading safe path, Prev: Init File in the Current Directory, Up: Auto-loading |
| |
| 22.8.2 Automatically loading thread debugging library |
| ----------------------------------------------------- |
| |
| This feature is currently present only on GNU/Linux native hosts. |
| |
| GDB reads in some cases thread debugging library from places specific |
| to the inferior (*note set libthread-db-search-path::). |
| |
| The special 'libthread-db-search-path' entry '$sdir' is processed |
| without checking this 'set auto-load libthread-db' switch as system |
| libraries have to be trusted in general. In all other cases of |
| 'libthread-db-search-path' entries GDB checks first if 'set auto-load |
| libthread-db' is enabled before trying to open such thread debugging |
| library. |
| |
| Note that loading of this debugging library also requires accordingly |
| configured 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| 'set auto-load libthread-db [on|off]' |
| Enable or disable the auto-loading of inferior specific thread |
| debugging library. |
| |
| 'show auto-load libthread-db' |
| Show whether auto-loading of inferior specific thread debugging |
| library is enabled or disabled. |
| |
| 'info auto-load libthread-db' |
| Print the list of all loaded inferior specific thread debugging |
| libraries and for each such library print list of inferior PIDs |
| using it. |
| |
| |
| File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode, Prev: libthread_db.so.1 file, Up: Auto-loading |
| |
| 22.8.3 Security restriction for auto-loading |
| -------------------------------------------- |
| |
| As the files of inferior can come from untrusted source (such as |
| submitted by an application user) GDB does not always load any files |
| automatically. GDB provides the 'set auto-load safe-path' setting to |
| list directories trusted for loading files not explicitly requested by |
| user. Each directory can also be a shell wildcard pattern. |
| |
| If the path is not set properly you will see a warning and the file |
| will not get loaded: |
| |
| $ ./gdb -q ./gdb |
| Reading symbols from /home/user/gdb/gdb...done. |
| warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been |
| declined by your `auto-load safe-path' set |
| to "$debugdir:$datadir/auto-load". |
| warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been |
| declined by your `auto-load safe-path' set |
| to "$debugdir:$datadir/auto-load". |
| |
| 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: |
| |
| 'set auto-load safe-path [DIRECTORIES]' |
| Set the list of directories (and their subdirectories) trusted for |
| automatic loading and execution of scripts. You can also enter a |
| specific trusted file. Each directory can also be a shell wildcard |
| pattern; wildcards do not match directory separator - see |
| 'FNM_PATHNAME' for system function 'fnmatch' (*note fnmatch: |
| (libc)Wildcard Matching.). If you omit DIRECTORIES, 'auto-load |
| safe-path' will be reset to its default value as specified during |
| GDB compilation. |
| |
| The list of directories uses path separator (':' on GNU and Unix |
| systems, ';' on MS-Windows and MS-DOS) to separate directories, |
| similarly to the 'PATH' environment variable. |
| |
| 'show auto-load safe-path' |
| Show the list of directories trusted for automatic loading and |
| execution of scripts. |
| |
| 'add-auto-load-safe-path' |
| Add an entry (or list of entries) to the list of directories |
| trusted for automatic loading and execution of scripts. Multiple |
| entries may be delimited by the host platform path separator in |
| use. |
| |
| This variable defaults to what '--with-auto-load-dir' has been |
| configured to (*note with-auto-load-dir::). '$debugdir' and '$datadir' |
| substitution applies the same as for *note set auto-load |
| scripts-directory::. The default 'set auto-load safe-path' value can be |
| also overriden by GDB configuration option '--with-auto-load-safe-path'. |
| |
| Setting this variable to '/' disables this security protection, |
| corresponding GDB configuration option is |
| '--without-auto-load-safe-path'. This variable is supposed to be set to |
| the system directories writable by the system superuser only. Users can |
| add their source directories in init files in their home directories |
| (*note Home Directory Init File::). See also deprecated init file in |
| the current directory (*note Init File in the Current Directory during |
| Startup::). |
| |
| To force GDB to load the files it declined to load in the previous |
| example, you could use one of the following ways: |
| |
| '~/.gdbinit': 'add-auto-load-safe-path ~/src/gdb' |
| Specify this trusted directory (or a file) as additional component |
| of the list. You have to specify also any existing directories |
| displayed by by 'show auto-load safe-path' (such as '/usr:/bin' in |
| this example). |
| |
| 'gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...' |
| Specify this directory as in the previous case but just for a |
| single GDB session. |
| |
| 'gdb -iex "set auto-load safe-path /" ...' |
| Disable auto-loading safety for a single GDB session. This assumes |
| all the files you debug during this GDB session will come from |
| trusted sources. |
| |
| './configure --without-auto-load-safe-path' |
| During compilation of GDB you may disable any auto-loading safety. |
| This assumes all the files you will ever debug with this GDB come |
| from trusted sources. |
| |
| On the other hand you can also explicitly forbid automatic files |
| loading which also suppresses any such warning messages: |
| |
| 'gdb -iex "set auto-load no" ...' |
| You can use GDB command-line option for a single GDB session. |
| |
| '~/.gdbinit': 'set auto-load no' |
| Disable auto-loading globally for the user (*note Home Directory |
| Init File::). While it is improbable, you could also use system |
| init file instead (*note System-wide configuration::). |
| |
| This setting applies to the file names as entered by user. If no |
| entry matches GDB tries as a last resort to also resolve all the file |
| names into their canonical form (typically resolving symbolic links) and |
| compare the entries again. GDB already canonicalizes most of the |
| filenames on its own before starting the comparison so a canonical form |
| of directories is recommended to be entered. |
| |
| |
| File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path, Up: Auto-loading |
| |
| 22.8.4 Displaying files tried for auto-load |
| ------------------------------------------- |
| |
| For better visibility of all the file locations where you can place |
| scripts to be auto-loaded with inferior -- or to protect yourself |
| against accidental execution of untrusted scripts -- GDB provides a |
| feature for printing all the files attempted to be loaded. Both |
| existing and non-existing files may be printed. |
| |
| For example the list of directories from which it is safe to |
| auto-load files (*note Auto-loading safe path::) applies also to |
| canonicalized filenames which may not be too obvious while setting it |
| up. |
| |
| (gdb) set debug auto-load on |
| (gdb) file ~/src/t/true |
| auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" |
| for objfile "/tmp/true". |
| auto-load: Updating directories of "/usr:/opt". |
| auto-load: Using directory "/usr". |
| auto-load: Using directory "/opt". |
| warning: File "/tmp/true-gdb.gdb" auto-loading has been declined |
| by your `auto-load safe-path' set to "/usr:/opt". |
| |
| 'set debug auto-load [on|off]' |
| Set whether to print the filenames attempted to be auto-loaded. |
| |
| 'show debug auto-load' |
| Show whether printing of the filenames attempted to be auto-loaded |
| is turned on or off. |
| |
| |
| File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-loading, Up: Controlling GDB |
| |
| 22.9 Optional Warnings and Messages |
| =================================== |
| |
| By default, GDB is silent about its inner workings. If you are running |
| on a slow machine, you may want to use the 'set verbose' command. This |
| makes GDB tell you when it does a lengthy internal operation, so you |
| will not think it has crashed. |
| |
| Currently, the messages controlled by 'set verbose' are those which |
| announce that the symbol table for a source file is being read; see |
| 'symbol-file' in *note Commands to Specify Files: Files. |
| |
| 'set verbose on' |
| Enables GDB output of certain informational messages. |
| |
| 'set verbose off' |
| Disables GDB output of certain informational messages. |
| |
| 'show verbose' |
| Displays whether 'set verbose' is on or off. |
| |
| By default, if GDB encounters bugs in the symbol table of an object |
| file, it is silent; but if you are debugging a compiler, you may find |
| this information useful (*note Errors Reading Symbol Files: Symbol |
| Errors.). |
| |
| 'set complaints LIMIT' |
| Permits GDB to output LIMIT complaints about each type of unusual |
| symbols before becoming silent about the problem. Set LIMIT to |
| zero to suppress all complaints; set it to a large number to |
| prevent complaints from being suppressed. |
| |
| 'show complaints' |
| Displays how many symbol complaints GDB is permitted to produce. |
| |
| By default, GDB is cautious, and asks what sometimes seems to be a |
| lot of stupid questions to confirm certain commands. For example, if |
| you try to run a program which is already running: |
| |
| (gdb) run |
| The program being debugged has been started already. |
| Start it from the beginning? (y or n) |
| |
| If you are willing to unflinchingly face the consequences of your own |
| commands, you can disable this "feature": |
| |
| 'set confirm off' |
| Disables confirmation requests. Note that running GDB with the |
| '--batch' option (*note -batch: Mode Options.) also automatically |
| disables confirmation requests. |
| |
| 'set confirm on' |
| Enables confirmation requests (the default). |
| |
| 'show confirm' |
| Displays state of confirmation requests. |
| |
| If you need to debug user-defined commands or sourced files you may |
| find it useful to enable "command tracing". In this mode each command |
| will be printed as it is executed, prefixed with one or more '+' |
| symbols, the quantity denoting the call depth of each command. |
| |
| 'set trace-commands on' |
| Enable command tracing. |
| 'set trace-commands off' |
| Disable command tracing. |
| 'show trace-commands' |
| Display the current state of command tracing. |
| |
| |
| File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB |
| |
| 22.10 Optional Messages about Internal Happenings |
| ================================================= |
| |
| GDB has commands that enable optional debugging messages from various |
| GDB subsystems; normally these commands are of interest to GDB |
| maintainers, or when reporting a bug. This section documents those |
| commands. |
| |
| 'set exec-done-display' |
| Turns on or off the notification of asynchronous commands' |
| completion. When on, GDB will print a message when an asynchronous |
| command finishes its execution. The default is off. |
| 'show exec-done-display' |
| Displays the current setting of asynchronous command completion |
| notification. |
| 'set debug 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 |
| '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. |
| 'show debug aix-thread' |
| Show the current state of AIX thread debugging info display. |
| 'set debug check-physname' |
| Check the results of the "physname" computation. When reading |
| DWARF debugging information for C++, GDB attempts to compute each |
| entity's name. GDB can do this computation in two different ways, |
| depending on exactly what information is present. When enabled, |
| this setting causes GDB to compute the names both ways and display |
| any discrepancies. |
| 'show debug check-physname' |
| Show the current state of "physname" checking. |
| 'set debug 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 dwarf-die' |
| Dump DWARF DIEs after they are read in. The value is the number of |
| nesting levels to print. A value of zero turns off the display. |
| 'show debug dwarf-die' |
| Show the current state of DWARF DIE debugging. |
| 'set debug dwarf-line' |
| Turns on or off display of debugging messages related to reading |
| DWARF line tables. The default is 0 (off). A value of 1 provides |
| basic information. A value greater than 1 provides more verbose |
| information. |
| 'show debug dwarf-line' |
| Show the current state of DWARF line table debugging. |
| 'set debug dwarf-read' |
| Turns on or off display of debugging messages related to reading |
| 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 dwarf-read' |
| Show the current state of DWARF reader debugging. |
| 'set debug displaced' |
| Turns on or off display of GDB debugging info for the displaced |
| stepping support. The default is off. |
| 'show debug displaced' |
| Displays the current state of displaying GDB debugging info related |
| to displaced stepping. |
| 'set debug event' |
| Turns on or off display of GDB event debugging info. The default |
| is off. |
| 'show debug event' |
| Displays the current state of displaying GDB event debugging info. |
| 'set debug expression' |
| Turns on or off display of debugging info about GDB expression |
| parsing. The default is off. |
| 'show debug expression' |
| Displays the current state of displaying debugging info about GDB |
| expression parsing. |
| 'set debug fbsd-lwp' |
| Turns on or off debugging messages from the FreeBSD LWP debug |
| support. |
| 'show debug fbsd-lwp' |
| Show the current state of FreeBSD LWP debugging messages. |
| 'set debug fbsd-nat' |
| Turns on or off debugging messages from the FreeBSD native target. |
| 'show debug fbsd-nat' |
| Show the current state of FreeBSD native target debugging messages. |
| 'set debug frame' |
| Turns on or off display of GDB frame debugging info. The default |
| is off. |
| 'show debug frame' |
| Displays the current state of displaying GDB frame debugging info. |
| 'set debug gnu-nat' |
| Turn on or off debugging messages from the GNU/Hurd debug support. |
| 'show debug gnu-nat' |
| Show the current state of GNU/Hurd debugging messages. |
| 'set debug infrun' |
| Turns on or off display of GDB debugging info for running the |
| inferior. The default is off. 'infrun.c' contains GDB's runtime |
| state machine used for implementing operations such as |
| single-stepping the inferior. |
| 'show debug infrun' |
| Displays the current state of GDB inferior debugging. |
| 'set debug jit' |
| Turn on or off debugging messages from JIT debug support. |
| 'show debug jit' |
| Displays the current state of GDB JIT debugging. |
| 'set debug lin-lwp' |
| Turn on or off debugging messages from the Linux LWP debug support. |
| 'show debug lin-lwp' |
| Show the current state of Linux LWP debugging messages. |
| 'set debug linux-namespaces' |
| Turn on or off debugging messages from the Linux namespaces debug |
| support. |
| 'show debug linux-namespaces' |
| Show the current state of Linux namespaces 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' |
| Turn 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. |
| 'show debug observer' |
| Displays the current state of observer debugging. |
| 'set debug overload' |
| Turns on or off display of GDB C++ overload debugging info. This |
| includes info such as ranking of functions, etc. The default is |
| off. |
| 'show debug overload' |
| Displays the current state of displaying GDB C++ overload debugging |
| info. |
| 'set debug parser' |
| Turns on or off the display of expression parser debugging output. |
| Internally, this sets the 'yydebug' variable in the expression |
| parser. *Note Tracing Your Parser: (bison)Tracing, for details. |
| The default is off. |
| 'show debug parser' |
| Show the current state of expression parser debugging. |
| 'set debug remote' |
| Turns on or off display of reports on all packets sent back and |
| forth across the serial line to the remote machine. The info is |
| printed on the GDB standard output stream. The default is off. |
| 'show debug remote' |
| Displays the state of display of remote packets. |
| |
| 'set debug remote-packet-max-chars' |
| Sets the maximum number of characters to display for each remote |
| packet when 'set debug remote' is on. This is useful to prevent |
| GDB from displaying lengthy remote packets and polluting the |
| console. |
| |
| The default value is '512', which means GDB will truncate each |
| remote packet after 512 bytes. |
| |
| Setting this option to 'unlimited' will disable truncation and will |
| output the full length of the remote packets. |
| 'show debug remote-packet-max-chars' |
| Displays the number of bytes to output for remote packet debugging. |
| |
| 'set debug separate-debug-file' |
| Turns on or off display of debug output about separate debug file |
| search. |
| 'show debug separate-debug-file' |
| Displays the state of separate debug file search debug output. |
| |
| 'set debug serial' |
| Turns on or off display of GDB serial debugging info. The default |
| is off. |
| 'show debug serial' |
| Displays the current state of displaying GDB serial debugging info. |
| 'set debug solib-frv' |
| Turn on or off debugging messages for FR-V shared-library code. |
| 'show debug solib-frv' |
| Display the current state of FR-V shared-library code debugging |
| messages. |
| 'set debug symbol-lookup' |
| Turns on or off display of debugging messages related to symbol |
| lookup. The default is 0 (off). A value of 1 provides basic |
| information. A value greater than 1 provides more verbose |
| information. |
| 'show debug symbol-lookup' |
| Show the current state of symbol lookup 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 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. |
| 'set debug target' |
| Turns on or off display of GDB target debugging info. This info |
| includes what is going on at the target level of GDB, as it |
| happens. The default is 0. Set it to 1 to track events, and to 2 |
| to also track the value of large memory transfers. |
| 'show debug target' |
| Displays the current state of displaying GDB target debugging info. |
| 'set debug timestamp' |
| Turns on or off display of timestamps with GDB debugging info. |
| When enabled, seconds and microseconds are displayed before each |
| debugging message. |
| 'show debug timestamp' |
| Displays the current state of displaying timestamps with GDB |
| debugging info. |
| 'set debug varobj' |
| Turns on or off display of GDB variable object debugging info. The |
| default is off. |
| 'show debug varobj' |
| Displays the current state of displaying GDB variable object |
| debugging info. |
| 'set debug xml' |
| Turn on or off debugging messages for built-in XML parsers. |
| 'show debug xml' |
| Displays the current state of XML debugging messages. |
| |
| |
| File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB |
| |
| 22.11 Other Miscellaneous Settings |
| ================================== |
| |
| 'set interactive-mode' |
| If 'on', forces GDB to assume that GDB was started in a terminal. |
| In practice, this means that GDB should wait for the user to answer |
| queries generated by commands entered at the command prompt. If |
| 'off', forces GDB to operate in the opposite mode, and it uses the |
| default answers to all queries. If 'auto' (the default), GDB tries |
| to determine whether its standard input is a terminal, and works in |
| interactive-mode if it is, non-interactively otherwise. |
| |
| In the vast majority of cases, the debugger should be able to guess |
| correctly which mode should be used. But this setting can be |
| useful in certain specific cases, such as running a MinGW GDB |
| inside a cygwin window. |
| |
| 'show interactive-mode' |
| Displays whether the debugger is operating in interactive mode or |
| not. |
| |
| |
| File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top |
| |
| 23 Extending GDB |
| **************** |
| |
| GDB provides several mechanisms for extension. GDB also provides the |
| ability to automatically load extensions when it reads a file for |
| debugging. This allows the user to automatically customize GDB for the |
| program being debugged. |
| |
| * Menu: |
| |
| * Sequences:: Canned Sequences of GDB Commands |
| * Python:: Extending GDB using Python |
| * Guile:: Extending GDB using Guile |
| * Auto-loading extensions:: Automatically loading extensions |
| * Multiple Extension Languages:: Working with multiple extension languages |
| * Aliases:: Creating new spellings of existing commands |
| |
| To facilitate the use of extension languages, GDB is capable of |
| evaluating the contents of a file. When doing so, GDB can recognize |
| which extension language is being used by looking at the filename |
| extension. Files with an unrecognized filename extension are always |
| treated as a GDB Command Files. *Note Command files: Command Files. |
| |
| You can control how GDB evaluates these files with the following |
| setting: |
| |
| 'set script-extension off' |
| All scripts are always evaluated as GDB Command Files. |
| |
| 'set script-extension soft' |
| The debugger determines the scripting language based on filename |
| extension. If this scripting language is supported, GDB evaluates |
| the script using that language. Otherwise, it evaluates the file |
| as a GDB Command File. |
| |
| 'set script-extension strict' |
| The debugger determines the scripting language based on filename |
| extension, and evaluates the script using that language. If the |
| language is not supported, then the evaluation fails. |
| |
| 'show script-extension' |
| Display the current value of the 'script-extension' option. |
| |
| |
| File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB |
| |
| 23.1 Canned Sequences of Commands |
| ================================= |
| |
| Aside from breakpoint commands (*note Breakpoint Command Lists: Break |
| Commands.), GDB provides two ways to store sequences of commands for |
| execution as a unit: user-defined commands and command files. |
| |
| * Menu: |
| |
| * Define:: How to define your own commands |
| * Hooks:: Hooks for user-defined commands |
| * Command Files:: How to write scripts of commands to be stored in a file |
| * Output:: Commands for controlled output |
| * Auto-loading sequences:: Controlling auto-loaded command files |
| |
| |
| File: gdb.info, Node: Define, Next: Hooks, Up: Sequences |
| |
| 23.1.1 User-defined Commands |
| ---------------------------- |
| |
| A "user-defined command" is a sequence of GDB commands to which you |
| assign a new name as a command. This is done with the 'define' command. |
| User commands may accept an unlimited number of arguments separated by |
| whitespace. Arguments are accessed within the user command via |
| '$arg0...$argN'. A trivial example: |
| |
| define adder |
| print $arg0 + $arg1 + $arg2 |
| end |
| |
| To execute the command use: |
| |
| adder 1 2 3 |
| |
| This defines the command 'adder', which prints the sum of its three |
| arguments. Note the arguments are text substitutions, so they may |
| reference variables, use complex expressions, or even perform inferior |
| functions calls. |
| |
| In addition, '$argc' may be used to find out how many arguments have |
| been passed. |
| |
| define adder |
| if $argc == 2 |
| print $arg0 + $arg1 |
| end |
| if $argc == 3 |
| print $arg0 + $arg1 + $arg2 |
| end |
| end |
| |
| Combining with the 'eval' command (*note eval::) makes it easier to |
| process a variable number of arguments: |
| |
| define adder |
| set $i = 0 |
| set $sum = 0 |
| while $i < $argc |
| eval "set $sum = $sum + $arg%d", $i |
| set $i = $i + 1 |
| end |
| print $sum |
| end |
| |
| 'define COMMANDNAME' |
| Define a command named COMMANDNAME. If there is already a command |
| by that name, you are asked to confirm that you want to redefine |
| it. The argument COMMANDNAME may be a bare command name consisting |
| of letters, numbers, dashes, dots, and underscores. It may also |
| start with any predefined or user-defined prefix command. For |
| example, 'define target my-target' creates a user-defined 'target |
| my-target' command. |
| |
| The definition of the command is made up of other GDB command |
| lines, which are given following the 'define' command. The end of |
| these commands is marked by a line containing 'end'. |
| |
| 'document COMMANDNAME' |
| Document the user-defined command COMMANDNAME, so that it can be |
| accessed by 'help'. The command COMMANDNAME must already be |
| defined. This command reads lines of documentation just as |
| 'define' reads the lines of the command definition, ending with |
| 'end'. After the 'document' command is finished, 'help' on command |
| COMMANDNAME displays the documentation you have written. |
| |
| You may use the 'document' command again to change the |
| documentation of a command. Redefining the command with 'define' |
| does not change the documentation. |
| |
| 'define-prefix COMMANDNAME' |
| Define or mark the command COMMANDNAME as a user-defined prefix |
| command. Once marked, COMMANDNAME can be used as prefix command by |
| the 'define' command. Note that 'define-prefix' can be used with a |
| not yet defined COMMANDNAME. In such a case, COMMANDNAME is |
| defined as an empty user-defined command. In case you redefine a |
| command that was marked as a user-defined prefix command, the |
| subcommands of the redefined command are kept (and GDB indicates so |
| to the user). |
| |
| Example: |
| (gdb) define-prefix abc |
| (gdb) define-prefix abc def |
| (gdb) define abc def |
| Type commands for definition of "abc def". |
| End with a line saying just "end". |
| >echo command initial def\n |
| >end |
| (gdb) define abc def ghi |
| Type commands for definition of "abc def ghi". |
| End with a line saying just "end". |
| >echo command ghi\n |
| >end |
| (gdb) define abc def |
| Keeping subcommands of prefix command "def". |
| Redefine command "def"? (y or n) y |
| Type commands for definition of "abc def". |
| End with a line saying just "end". |
| >echo command def\n |
| >end |
| (gdb) abc def ghi |
| command ghi |
| (gdb) abc def |
| command def |
| (gdb) |
| |
| 'dont-repeat' |
| Used inside a user-defined command, this tells GDB that this |
| command should not be repeated when the user hits <RET> (*note |
| repeat last command: Command Syntax.). |
| |
| 'help user-defined' |
| List all user-defined commands and all python commands defined in |
| class COMMAND_USER. The first line of the documentation or |
| docstring is included (if any). |
| |
| 'show user' |
| 'show user COMMANDNAME' |
| Display the GDB commands used to define COMMANDNAME (but not its |
| documentation). If no COMMANDNAME is given, display the |
| definitions for all user-defined commands. This does not work for |
| user-defined python commands. |
| |
| 'show max-user-call-depth' |
| 'set max-user-call-depth' |
| The value of 'max-user-call-depth' controls how many recursion |
| levels are allowed in user-defined commands before GDB suspects an |
| infinite recursion and aborts the command. This does not apply to |
| user-defined python commands. |
| |
| In addition to the above commands, user-defined commands frequently |
| use control flow commands, described in *note Command Files::. |
| |
| When user-defined commands are executed, the commands of the |
| definition are not printed. An error in any command stops execution of |
| the user-defined command. |
| |
| If used interactively, commands that would ask for confirmation |
| proceed without asking when used inside a user-defined command. Many |
| GDB commands that normally print messages to say what they are doing |
| omit the messages when used in a user-defined command. |
| |
| |
| File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences |
| |
| 23.1.2 User-defined Command Hooks |
| --------------------------------- |
| |
| You may define "hooks", which are a special kind of user-defined |
| command. Whenever you run the command 'foo', if the user-defined |
| command 'hook-foo' exists, it is executed (with no arguments) before |
| that command. |
| |
| A hook may also be defined which is run after the command you |
| executed. Whenever you run the command 'foo', if the user-defined |
| command 'hookpost-foo' exists, it is executed (with no arguments) after |
| that command. Post-execution hooks may exist simultaneously with |
| pre-execution hooks, for the same command. |
| |
| It is valid for a hook to call the command which it hooks. If this |
| occurs, the hook is not re-executed, thereby avoiding infinite |
| recursion. |
| |
| In addition, a pseudo-command, 'stop' exists. Defining ('hook-stop') |
| makes the associated commands execute every time execution stops in your |
| program: before breakpoint commands are run, displays are printed, or |
| the stack frame is printed. |
| |
| For example, to ignore 'SIGALRM' signals while single-stepping, but |
| treat them normally during normal execution, you could define: |
| |
| define hook-stop |
| handle SIGALRM nopass |
| end |
| |
| define hook-run |
| handle SIGALRM pass |
| end |
| |
| define hook-continue |
| handle SIGALRM pass |
| end |
| |
| As a further example, to hook at the beginning and end of the 'echo' |
| command, and to add extra text to the beginning and end of the message, |
| you could define: |
| |
| define hook-echo |
| echo <<<--- |
| end |
| |
| define hookpost-echo |
| echo --->>>\n |
| end |
| |
| (gdb) echo Hello World |
| <<<---Hello World--->>> |
| (gdb) |
| |
| |
| You can define a hook for any single-word command in GDB, but not for |
| command aliases; you should define a hook for the basic command name, |
| e.g. 'backtrace' rather than 'bt'. You can hook a multi-word command by |
| adding 'hook-' or 'hookpost-' to the last word of the command, e.g. |
| 'define target hook-remote' to add a hook to 'target remote'. |
| |
| If an error occurs during the execution of your hook, execution of |
| GDB commands stops and GDB issues a prompt (before the command that you |
| actually typed had a chance to run). |
| |
| If you try to define a hook which does not match any known command, |
| you get a warning from the 'define' command. |
| |
| |
| File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences |
| |
| 23.1.3 Command Files |
| -------------------- |
| |
| A command file for GDB is a text file made of lines that are GDB |
| commands. Comments (lines starting with '#') may also be included. An |
| empty line in a command file does nothing; it does not mean to repeat |
| the last command, as it would from the terminal. |
| |
| You can request the execution of a command file with the 'source' |
| command. Note that the 'source' command is also used to evaluate |
| scripts that are not Command Files. The exact behavior can be |
| configured using the 'script-extension' setting. *Note Extending GDB: |
| Extending GDB. |
| |
| 'source [-s] [-v] FILENAME' |
| Execute the command file FILENAME. |
| |
| The lines in a command file are generally executed sequentially, |
| unless the order of execution is changed by one of the _flow-control |
| commands_ described below. The commands are not printed as they are |
| executed. An error in any command terminates execution of the command |
| file and control is returned to the console. |
| |
| GDB first searches for FILENAME in the current directory. If the |
| file is not found there, and FILENAME does not specify a directory, then |
| GDB also looks for the file on the source search path (specified with |
| the 'directory' command); except that '$cdir' is not searched because |
| the compilation directory is not relevant to scripts. |
| |
| If '-s' is specified, then GDB searches for FILENAME on the search |
| path even if FILENAME specifies a directory. The search is done by |
| appending FILENAME to each element of the search path. So, for example, |
| if FILENAME is 'mylib/myscript' and the search path contains |
| '/home/user' then GDB will look for the script |
| '/home/user/mylib/myscript'. The search is also done if FILENAME is an |
| absolute path. For example, if FILENAME is '/tmp/myscript' and the |
| search path contains '/home/user' then GDB will look for the script |
| '/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains a |
| drive specification, it is stripped before concatenation. For example, |
| if FILENAME is 'd:myscript' and the search path contains 'c:/tmp' then |
| GDB will look for the script 'c:/tmp/myscript'. |
| |
| If '-v', for verbose mode, is given then GDB displays each command as |
| it is executed. The option must be given before FILENAME, and is |
| interpreted as part of the filename anywhere else. |
| |
| Commands that would ask for confirmation if used interactively |
| proceed without asking when used in a command file. Many GDB commands |
| that normally print messages to say what they are doing omit the |
| messages when called from command files. |
| |
| GDB also accepts command input from standard input. In this mode, |
| normal output goes to standard output and error output goes to standard |
| error. Errors in a command file supplied on standard input do not |
| terminate execution of the command file--execution continues with the |
| next command. |
| |
| gdb < cmds > log 2>&1 |
| |
| (The syntax above will vary depending on the shell used.) This |
| example will execute commands from the file 'cmds'. All output and |
| errors would be directed to 'log'. |
| |
| Since commands stored on command files tend to be more general than |
| commands typed interactively, they frequently need to deal with |
| complicated situations, such as different or unexpected values of |
| variables and symbols, changes in how the program being debugged is |
| built, etc. GDB provides a set of flow-control commands to deal with |
| these complexities. Using these commands, you can write complex scripts |
| that loop over data structures, execute commands conditionally, etc. |
| |
| 'if' |
| 'else' |
| This command allows to include in your script conditionally |
| executed commands. The 'if' command takes a single argument, which |
| is an expression to evaluate. It is followed by a series of |
| commands that are executed only if the expression is true (its |
| value is nonzero). There can then optionally be an 'else' line, |
| followed by a series of commands that are only executed if the |
| expression was false. The end of the list is marked by a line |
| containing 'end'. |
| |
| 'while' |
| This command allows to write loops. Its syntax is similar to 'if': |
| the command takes a single argument, which is an expression to |
| evaluate, and must be followed by the commands to execute, one per |
| line, terminated by an 'end'. These commands are called the "body" |
| of the loop. The commands in the body of 'while' are executed |
| repeatedly as long as the expression evaluates to true. |
| |
| 'loop_break' |
| This command exits the 'while' loop in whose body it is included. |
| Execution of the script continues after that 'while's 'end' line. |
| |
| 'loop_continue' |
| This command skips the execution of the rest of the body of |
| commands in the 'while' loop in whose body it is included. |
| Execution branches to the beginning of the 'while' loop, where it |
| evaluates the controlling expression. |
| |
| 'end' |
| Terminate the block of commands that are the body of 'if', 'else', |
| or 'while' flow-control commands. |
| |
| |
| File: gdb.info, Node: Output, Next: Auto-loading sequences, Prev: Command Files, Up: Sequences |
| |
| 23.1.4 Commands for Controlled Output |
| ------------------------------------- |
| |
| During the execution of a command file or a user-defined command, normal |
| GDB output is suppressed; the only output that appears is what is |
| explicitly printed by the commands in the definition. This section |
| describes three commands useful for generating exactly the output you |
| want. |
| |
| 'echo TEXT' |
| Print TEXT. Nonprinting characters can be included in TEXT using C |
| escape sequences, such as '\n' to print a newline. *No newline is |
| printed unless you specify one.* In addition to the standard C |
| escape sequences, a backslash followed by a space stands for a |
| space. This is useful for displaying a string with spaces at the |
| beginning or the end, since leading and trailing spaces are |
| otherwise trimmed from all arguments. To print ' and foo = ', use |
| the command 'echo \ and foo = \ '. |
| |
| A backslash at the end of TEXT can be used, as in C, to continue |
| the command onto subsequent lines. For example, |
| |
| echo This is some text\n\ |
| which is continued\n\ |
| onto several lines.\n |
| |
| produces the same output as |
| |
| echo This is some text\n |
| echo which is continued\n |
| echo onto several lines.\n |
| |
| 'output EXPRESSION' |
| Print the value of EXPRESSION and nothing but that value: no |
| newlines, no '$NN = '. The value is not entered in the value |
| history either. *Note Expressions: Expressions, for more |
| information on expressions. |
| |
| 'output/FMT EXPRESSION' |
| Print the value of EXPRESSION in format FMT. You can use the same |
| formats as for 'print'. *Note Output Formats: Output Formats, for |
| more information. |
| |
| 'printf TEMPLATE, EXPRESSIONS...' |
| Print the values of one or more EXPRESSIONS under the control of |
| the string TEMPLATE. To print several values, make EXPRESSIONS be |
| a comma-separated list of individual expressions, which may be |
| either numbers or pointers. Their values are printed as specified |
| by TEMPLATE, exactly as a C program would do by executing the code |
| below: |
| |
| printf (TEMPLATE, EXPRESSIONS...); |
| |
| As in 'C' 'printf', ordinary characters in TEMPLATE are printed |
| verbatim, while "conversion specification" introduced by the '%' |
| character cause subsequent EXPRESSIONS to be evaluated, their |
| values converted and formatted according to type and style |
| information encoded in the conversion specifications, and then |
| printed. |
| |
| For example, you can print two values in hex like this: |
| |
| printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo |
| |
| 'printf' supports all the standard 'C' conversion specifications, |
| including the flags and modifiers between the '%' character and the |
| conversion letter, with the following exceptions: |
| |
| * The argument-ordering modifiers, such as '2$', are not |
| supported. |
| |
| * The modifier '*' is not supported for specifying precision or |
| width. |
| |
| * The ''' flag (for separation of digits into groups according |
| to 'LC_NUMERIC'') is not supported. |
| |
| * The type modifiers 'hh', 'j', 't', and 'z' are not supported. |
| |
| * The conversion letter 'n' (as in '%n') is not supported. |
| |
| * The conversion letters 'a' and 'A' are not supported. |
| |
| Note that the 'll' type modifier is supported only if the |
| underlying 'C' implementation used to build GDB supports the 'long |
| long int' type, and the 'L' type modifier is supported only if |
| 'long double' type is available. |
| |
| As in 'C', 'printf' supports simple backslash-escape sequences, |
| such as '\n', '\t', '\\', '\"', '\a', and '\f', that consist of |
| backslash followed by a single character. Octal and hexadecimal |
| escape sequences are not supported. |
| |
| Additionally, 'printf' supports conversion specifications for DFP |
| ("Decimal Floating Point") types using the following length |
| modifiers together with a floating point specifier. letters: |
| |
| * 'H' for printing 'Decimal32' types. |
| |
| * 'D' for printing 'Decimal64' types. |
| |
| * 'DD' for printing 'Decimal128' types. |
| |
| If the underlying 'C' implementation used to build GDB has support |
| for the three length modifiers for DFP types, other modifiers such |
| as width and precision will also be available for GDB to use. |
| |
| In case there is no such 'C' support, no additional modifiers will |
| be available and the value will be printed in the standard way. |
| |
| Here's an example of printing DFP types using the above conversion |
| letters: |
| printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl |
| |
| 'eval TEMPLATE, EXPRESSIONS...' |
| Convert the values of one or more EXPRESSIONS under the control of |
| the string TEMPLATE to a command line, and call it. |
| |
| |
| File: gdb.info, Node: Auto-loading sequences, Prev: Output, Up: Sequences |
| |
| 23.1.5 Controlling auto-loading native GDB scripts |
| -------------------------------------------------- |
| |
| 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 |
| the command file 'OBJFILE-gdb.gdb'. *Note Auto-loading extensions::. |
| |
| Auto-loading can be enabled or disabled, and the list of auto-loaded |
| scripts can be printed. |
| |
| 'set auto-load gdb-scripts [on|off]' |
| Enable or disable the auto-loading of canned sequences of commands |
| scripts. |
| |
| 'show auto-load gdb-scripts' |
| Show whether auto-loading of canned sequences of commands scripts |
| is enabled or disabled. |
| |
| 'info auto-load gdb-scripts [REGEXP]' |
| Print the list of all canned sequences of commands scripts that GDB |
| auto-loaded. |
| |
| If REGEXP is supplied only canned sequences of commands scripts with |
| matching names are printed. |
| |
| |
| File: gdb.info, Node: Python, Next: Guile, Prev: Sequences, Up: Extending GDB |
| |
| 23.2 Extending GDB using Python |
| =============================== |
| |
| You can extend GDB using the Python programming language |
| (http://www.python.org/). This feature is available only if GDB was |
| configured using '--with-python'. GDB can be built against either |
| Python 2 or Python 3; which one you have depends on this configure-time |
| option. |
| |
| Python scripts used by GDB should be installed in |
| 'DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as |
| determined at GDB startup (*note Data Files::). This directory, known |
| as the "python directory", is automatically added to the Python Search |
| Path in order to allow the Python interpreter to locate all scripts |
| installed at this location. |
| |
| Additionally, GDB commands and convenience functions which are |
| written in Python and are located in the |
| 'DATA-DIRECTORY/python/gdb/command' or |
| 'DATA-DIRECTORY/python/gdb/function' directories are automatically |
| imported when GDB starts. |
| |
| * Menu: |
| |
| * Python Commands:: Accessing Python from GDB. |
| * Python API:: Accessing GDB from Python. |
| * Python Auto-loading:: Automatically loading Python code. |
| * Python modules:: Python modules provided by GDB. |
| |
| |
| File: gdb.info, Node: Python Commands, Next: Python API, Up: Python |
| |
| 23.2.1 Python Commands |
| ---------------------- |
| |
| GDB provides two commands for accessing the Python interpreter, and one |
| related setting: |
| |
| '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 |
| argument as a Python command. For example: |
| |
| (gdb) python print 23 |
| 23 |
| |
| If you do not provide an argument to 'python', it will act as a |
| multi-line command, like 'define'. In this case, the Python script |
| is made up of subsequent command lines, given after the 'python' |
| command. This command list is terminated using a line containing |
| 'end'. For example: |
| |
| (gdb) python |
| >print 23 |
| >end |
| 23 |
| |
| 'set python print-stack' |
| By default, GDB will print only the message component of a Python |
| exception when an error occurs in a Python script. This can be |
| controlled using 'set python print-stack': if 'full', then full |
| Python stack printing is enabled; if 'none', then Python stack and |
| message printing is disabled; if 'message', the default, only the |
| message component of the error is printed. |
| |
| It is also possible to execute a Python script from the GDB |
| interpreter: |
| |
| 'source script-name' |
| The script name must end with '.py' and GDB must be configured to |
| recognize the script language based on filename extension using the |
| 'script-extension' setting. *Note Extending GDB: Extending GDB. |
| |
| |
| File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Commands, Up: Python |
| |
| 23.2.2 Python API |
| ----------------- |
| |
| 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: |
| |
| * Basic Python:: Basic Python Functions. |
| * Exception Handling:: How Python exceptions are translated. |
| * Values From Inferior:: Python representation of values. |
| * Types In Python:: Python representation of types. |
| * Pretty Printing API:: Pretty-printing values. |
| * Selecting Pretty-Printers:: How GDB chooses a pretty-printer. |
| * Writing a Pretty-Printer:: Writing a Pretty-Printer. |
| * Type Printing API:: Pretty-printing types. |
| * Frame Filter API:: Filtering Frames. |
| * Frame Decorator API:: Decorating Frames. |
| * Writing a Frame Filter:: Writing a Frame Filter. |
| * Unwinding Frames in Python:: Writing frame unwinder. |
| * Xmethods In Python:: Adding and replacing methods of C++ classes. |
| * Xmethod API:: Xmethod types. |
| * Writing an Xmethod:: Writing an xmethod. |
| * Inferiors In Python:: Python representation of inferiors (processes) |
| * Events In Python:: Listening for events from GDB. |
| * Threads In Python:: Accessing inferior threads from Python. |
| * Recordings In Python:: Accessing recordings from Python. |
| * Commands In Python:: Implementing new commands in Python. |
| * Parameters In Python:: Adding new GDB parameters. |
| * Functions In Python:: Writing new convenience functions. |
| * Progspaces In Python:: Program spaces. |
| * Objfiles In Python:: Object files. |
| * Frames In Python:: Accessing inferior stack frames from Python. |
| * Blocks In Python:: Accessing 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 |
| |
| 23.2.2.1 Basic Python |
| ..................... |
| |
| 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. |
| |
| Some types of the 'gdb' module come with a textual representation |
| (accessible through the 'repr' or 'str' functions). These are offered |
| for debugging purposes only, expect them to change over time. |
| |
| -- Variable: gdb.PYTHONDIR |
| A string containing the python directory (*note Python::). |
| |
| -- Function: gdb.execute (command [, from_tty [, to_string]]) |
| Evaluate COMMAND, a string, as a GDB CLI command. If a GDB |
| exception happens while COMMAND runs, it is translated as described |
| in *note Exception Handling: Exception Handling. |
| |
| The FROM_TTY flag specifies whether GDB ought to consider this |
| command as having originated from the user invoking it |
| interactively. It must be a boolean value. If omitted, it |
| defaults to 'False'. |
| |
| By default, any output produced by COMMAND is sent to GDB's |
| standard output (and to the log output if logging is turned on). |
| If the TO_STRING parameter is 'True', then output will be collected |
| by 'gdb.execute' and returned as a string. The default is 'False', |
| in which case the return value is 'None'. If TO_STRING is 'True', |
| the GDB virtual terminal will be temporarily set to unlimited width |
| and height, and its pagination will be disabled; *note Screen |
| Size::. |
| |
| -- Function: gdb.breakpoints () |
| Return a sequence holding all of GDB's breakpoints. *Note |
| Breakpoints In Python::, for more information. In GDB version 7.11 |
| and earlier, this function returned 'None' if there were no |
| breakpoints. This peculiarity was subsequently fixed, and now |
| 'gdb.breakpoints' returns an empty sequence in this case. |
| |
| -- Function: gdb.rbreak (regex [, minsyms [, throttle, [, symtabs ]]]) |
| Return a Python list holding a collection of newly set |
| 'gdb.Breakpoint' objects matching function names defined by the |
| REGEX pattern. If the MINSYMS keyword is 'True', all system |
| functions (those not explicitly defined in the inferior) will also |
| be included in the match. The THROTTLE keyword takes an integer |
| that defines the maximum number of pattern matches for functions |
| matched by the REGEX pattern. If the number of matches exceeds the |
| integer value of THROTTLE, a 'RuntimeError' will be raised and no |
| breakpoints will be created. If THROTTLE is not defined then there |
| is no imposed limit on the maximum number of matches and |
| breakpoints to be created. The SYMTABS keyword takes a Python |
| iterable that yields a collection of 'gdb.Symtab' objects and will |
| restrict the search to those functions only contained within the |
| 'gdb.Symtab' objects. |
| |
| -- Function: gdb.parameter (parameter) |
| Return the value of a GDB PARAMETER given by its name, a string; |
| the parameter name string may contain spaces if the parameter has a |
| multi-part name. For example, 'print object' is a valid parameter |
| name. |
| |
| If the named parameter does not exist, this function throws a |
| 'gdb.error' (*note Exception Handling::). Otherwise, the |
| parameter's value is converted to a Python value of the appropriate |
| type, and returned. |
| |
| -- Function: gdb.history (number) |
| Return a value from GDB's value history (*note Value History::). |
| The NUMBER argument indicates which history element to return. If |
| NUMBER is negative, then GDB will take its absolute value and count |
| backward from the last element (i.e., the most recent element) to |
| find the value to return. If NUMBER is zero, then GDB will return |
| the most recent element. If the element specified by NUMBER |
| doesn't exist in the value history, a 'gdb.error' exception will be |
| raised. |
| |
| If no exception is raised, the return value is always an instance |
| of 'gdb.Value' (*note Values From Inferior::). |
| |
| -- Function: gdb.convenience_variable (name) |
| Return the value of the convenience variable (*note Convenience |
| Vars::) named NAME. NAME must be a string. The name should not |
| include the '$' that is used to mark a convenience variable in an |
| expression. If the convenience variable does not exist, then |
| 'None' is returned. |
| |
| -- Function: gdb.set_convenience_variable (name, value) |
| Set the value of the convenience variable (*note Convenience |
| Vars::) named NAME. NAME must be a string. The name should not |
| include the '$' that is used to mark a convenience variable in an |
| expression. If VALUE is 'None', then the convenience variable is |
| removed. Otherwise, if VALUE is not a 'gdb.Value' (*note Values |
| From Inferior::), it is is converted using the 'gdb.Value' |
| constructor. |
| |
| -- Function: gdb.parse_and_eval (expression) |
| Parse EXPRESSION, which must be a string, as an expression in the |
| current language, evaluate it, and return the result as a |
| 'gdb.Value'. |
| |
| This function can be useful when implementing a new command (*note |
| Commands In Python::), as it provides a way to parse the command's |
| argument as an expression. It is also useful simply to compute |
| values. |
| |
| -- Function: gdb.find_pc_line (pc) |
| Return the 'gdb.Symtab_and_line' object corresponding to the PC |
| value. *Note Symbol Tables In Python::. If an invalid value of PC |
| is passed as an argument, then the 'symtab' and 'line' attributes |
| of the returned 'gdb.Symtab_and_line' object will be 'None' and 0 |
| respectively. This is identical to |
| 'gdb.current_progspace().find_pc_line(pc)' and is included for |
| historical compatibility. |
| |
| -- Function: gdb.post_event (event) |
| Put EVENT, a callable object taking no arguments, into GDB's |
| internal event queue. This callable will be invoked at some later |
| point, during GDB's event processing. Events posted using |
| 'post_event' will be run in the order in which they were posted; |
| however, there is no way to know when they will be processed |
| relative to other events inside GDB. |
| |
| GDB is not thread-safe. If your Python program uses multiple |
| threads, you must be careful to only call GDB-specific functions in |
| the GDB thread. 'post_event' ensures this. For example: |
| |
| (gdb) python |
| >import threading |
| > |
| >class Writer(): |
| > def __init__(self, message): |
| > self.message = message; |
| > def __call__(self): |
| > gdb.write(self.message) |
| > |
| >class MyThread1 (threading.Thread): |
| > def run (self): |
| > gdb.post_event(Writer("Hello ")) |
| > |
| >class MyThread2 (threading.Thread): |
| > def run (self): |
| > gdb.post_event(Writer("World\n")) |
| > |
| >MyThread1().start() |
| >MyThread2().start() |
| >end |
| (gdb) Hello World |
| |
| -- Function: gdb.write (string [, stream]) |
| Print a string to GDB's paginated output stream. The optional |
| STREAM determines the stream to print to. The default stream is |
| GDB's standard output stream. Possible stream values are: |
| |
| 'gdb.STDOUT' |
| GDB's standard output stream. |
| |
| 'gdb.STDERR' |
| GDB's standard error stream. |
| |
| 'gdb.STDLOG' |
| GDB's log stream (*note Logging Output::). |
| |
| Writing to 'sys.stdout' or 'sys.stderr' will automatically call |
| this function and will automatically direct the output to the |
| relevant stream. |
| |
| -- Function: gdb.flush () |
| Flush the buffer of a GDB paginated stream so that the contents are |
| displayed immediately. GDB will flush the contents of a stream |
| automatically when it encounters a newline in the buffer. The |
| optional STREAM determines the stream to flush. The default stream |
| is GDB's standard output stream. Possible stream values are: |
| |
| 'gdb.STDOUT' |
| GDB's standard output stream. |
| |
| 'gdb.STDERR' |
| GDB's standard error stream. |
| |
| 'gdb.STDLOG' |
| GDB's log stream (*note Logging Output::). |
| |
| Flushing 'sys.stdout' or 'sys.stderr' will automatically call this |
| function for the relevant stream. |
| |
| -- Function: gdb.target_charset () |
| Return the name of the current target character set (*note |
| Character Sets::). This differs from |
| 'gdb.parameter('target-charset')' in that 'auto' is never returned. |
| |
| -- Function: gdb.target_wide_charset () |
| Return the name of the current target wide character set (*note |
| Character Sets::). This differs from |
| 'gdb.parameter('target-wide-charset')' in that 'auto' is never |
| returned. |
| |
| -- Function: gdb.solib_name (address) |
| Return the name of the shared library holding the given ADDRESS as |
| a string, or 'None'. This is identical to |
| 'gdb.current_progspace().solib_name(address)' and is included for |
| historical compatibility. |
| |
| -- Function: gdb.decode_line ([expression]) |
| Return locations of the line specified by EXPRESSION, or of the |
| current line if no argument was given. This function returns a |
| Python tuple containing two elements. The first element contains a |
| string holding any unparsed section of EXPRESSION (or 'None' if the |
| expression has been fully parsed). The second element contains |
| either 'None' or another tuple that contains all the locations that |
| match the expression represented as 'gdb.Symtab_and_line' objects |
| (*note Symbol Tables In Python::). If EXPRESSION is provided, it |
| is decoded the way that GDB's inbuilt 'break' or 'edit' commands do |
| (*note Specify Location::). |
| |
| -- Function: gdb.prompt_hook (current_prompt) |
| |
| If PROMPT_HOOK is callable, GDB will call the method assigned to |
| this operation before a prompt is displayed by GDB. |
| |
| The parameter 'current_prompt' contains the current GDB prompt. |
| This method must return a Python string, or 'None'. If a string is |
| returned, the GDB prompt will be set to that string. If 'None' is |
| returned, GDB will continue to use the current prompt. |
| |
| Some prompts cannot be substituted in GDB. Secondary prompts such |
| as those used by readline for command input, and annotation related |
| prompts are prohibited from being changed. |
| |
| |
| File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API |
| |
| 23.2.2.2 Exception Handling |
| ........................... |
| |
| When executing the 'python' command, Python exceptions uncaught within |
| the Python code are translated to calls to GDB error-reporting |
| mechanism. If the command that called 'python' does not handle the |
| error, GDB will terminate it and print an error message containing the |
| Python exception name, the associated value, and the Python call stack |
| backtrace at the point where the exception was raised. Example: |
| |
| (gdb) python print foo |
| Traceback (most recent call last): |
| File "<string>", line 1, in <module> |
| NameError: name 'foo' is not defined |
| |
| GDB errors that happen in GDB commands invoked by Python code are |
| converted to Python exceptions. The type of the Python exception |
| depends on the error. |
| |
| 'gdb.error' |
| This is the base class for most exceptions generated by GDB. It is |
| derived from 'RuntimeError', for compatibility with earlier |
| versions of GDB. |
| |
| If an error occurring in GDB does not fit into some more specific |
| category, then the generated exception will have this type. |
| |
| 'gdb.MemoryError' |
| This is a subclass of 'gdb.error' which is thrown when an operation |
| tried to access invalid memory in the inferior. |
| |
| 'KeyboardInterrupt' |
| User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) |
| is translated to a Python 'KeyboardInterrupt' exception. |
| |
| In all cases, your exception handler will see the GDB error message |
| as its value and the Python call stack backtrace at the Python statement |
| closest to where the GDB error occured as the traceback. |
| |
| When implementing GDB commands in Python via 'gdb.Command', or |
| functions via 'gdb.Function', it is useful to be able to throw an |
| exception that doesn't cause a traceback to be printed. For example, |
| the user may have invoked the command incorrectly. GDB provides a |
| special exception class that can be used for this purpose. |
| |
| 'gdb.GdbError' |
| When thrown from a command or function, this exception will cause |
| the command or function to fail, but the Python stack will not be |
| displayed. GDB does not throw this exception itself, but rather |
| recognizes it when thrown from user Python code. Example: |
| |
| (gdb) python |
| >class HelloWorld (gdb.Command): |
| > """Greet the whole world.""" |
| > def __init__ (self): |
| > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) |
| > def invoke (self, args, from_tty): |
| > argv = gdb.string_to_argv (args) |
| > if len (argv) != 0: |
| > raise gdb.GdbError ("hello-world takes no arguments") |
| > print "Hello, World!" |
| >HelloWorld () |
| >end |
| (gdb) hello-world 42 |
| hello-world takes no arguments |
| |
| |
| File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API |
| |
| 23.2.2.3 Values From Inferior |
| ............................. |
| |
| GDB provides values it obtains from the inferior program in an object of |
| type 'gdb.Value'. GDB uses this object for its internal bookkeeping of |
| the inferior's values, and for fetching values when necessary. |
| |
| Inferior values that are simple scalars can be used directly in |
| Python expressions that are valid for the value's data type. Here's an |
| example for an integer or floating-point value 'some_val': |
| |
| bar = some_val + 2 |
| |
| As result of this, 'bar' will also be a 'gdb.Value' object whose values |
| are of the same type as those of 'some_val'. Valid Python operations |
| can also be performed on 'gdb.Value' objects representing a 'struct' or |
| 'class' object. For such cases, the overloaded operator (if present), |
| is used to perform the operation. For example, if 'val1' and 'val2' are |
| 'gdb.Value' objects representing instances of a 'class' which overloads |
| the '+' operator, then one can use the '+' operator in their Python |
| script as follows: |
| |
| val3 = val1 + val2 |
| |
| The result of the operation 'val3' is also a 'gdb.Value' object |
| corresponding to the value returned by the overloaded '+' operator. In |
| general, overloaded operators are invoked for the following operations: |
| '+' (binary addition), '-' (binary subtraction), '*' (multiplication), |
| '/', '%', '<<', '>>', '|', '&', '^'. |
| |
| Inferior values that are structures or instances of some class can be |
| accessed using the Python "dictionary syntax". For example, if |
| 'some_val' is a 'gdb.Value' instance holding a structure, you can access |
| its 'foo' element with: |
| |
| bar = some_val['foo'] |
| |
| Again, 'bar' will also be a 'gdb.Value' object. Structure elements |
| can also be accessed by using 'gdb.Field' objects as subscripts (*note |
| Types In Python::, for more information on 'gdb.Field' objects). For |
| example, if 'foo_field' is a 'gdb.Field' object corresponding to element |
| 'foo' of the above structure, then 'bar' can also be accessed as |
| follows: |
| |
| bar = some_val[foo_field] |
| |
| A 'gdb.Value' that represents a function can be executed via inferior |
| function call. Any arguments provided to the call must match the |
| function's prototype, and must be provided in the order specified by |
| that prototype. |
| |
| For example, 'some_val' is a 'gdb.Value' instance representing a |
| function that takes two integers as arguments. To execute this |
| function, call it like so: |
| |
| result = some_val (10,20) |
| |
| Any values returned from a function call will be stored as a |
| 'gdb.Value'. |
| |
| The following attributes are provided: |
| |
| -- Variable: Value.address |
| If this object is addressable, this read-only attribute holds a |
| 'gdb.Value' object representing the address. Otherwise, this |
| attribute holds 'None'. |
| |
| -- Variable: Value.is_optimized_out |
| This read-only boolean attribute is true if the compiler optimized |
| out this value, thus it is not available for fetching from the |
| inferior. |
| |
| -- Variable: Value.type |
| The type of this 'gdb.Value'. The value of this attribute is a |
| 'gdb.Type' object (*note Types In Python::). |
| |
| -- Variable: Value.dynamic_type |
| The dynamic type of this 'gdb.Value'. This uses the object's |
| virtual table and the 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 in the current |
| target language using the current target encoding. If a |
| character cannot be represented in the current target |
| encoding, then an exception is thrown. |
| |
| '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.__init__ (VAL, TYPE) |
| This second form of the 'gdb.Value' constructor returns a |
| 'gdb.Value' of type TYPE where the value contents are taken from |
| the Python buffer object specified by VAL. The number of bytes in |
| the Python buffer object must be greater than or equal to the size |
| of TYPE. |
| |
| -- 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 corresponding 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.reference_value () |
| Return a 'gdb.Value' object which is a reference to the value |
| encapsulated by this instance. |
| |
| -- Function: Value.const_value () |
| Return a 'gdb.Value' object which is a 'const' version of the value |
| encapsulated by this instance. |
| |
| -- 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.format_string (...) |
| Convert a 'gdb.Value' to a string, similarly to what the 'print' |
| command does. Invoked with no arguments, this is equivalent to |
| calling the 'str' function on the 'gdb.Value'. The representation |
| of the same value may change across different versions of GDB, so |
| you shouldn't, for instance, parse the strings returned by this |
| method. |
| |
| All the arguments are keyword only. If an argument is not |
| specified, the current global default setting is used. |
| |
| 'raw' |
| 'True' if pretty-printers (*note Pretty Printing::) should not |
| be used to format the value. 'False' if enabled |
| pretty-printers matching the type represented by the |
| 'gdb.Value' should be used to format it. |
| |
| 'pretty_arrays' |
| 'True' if arrays should be pretty printed to be more |
| convenient to read, 'False' if they shouldn't (see 'set print |
| array' in *note Print Settings::). |
| |
| 'pretty_structs' |
| 'True' if structs should be pretty printed to be more |
| convenient to read, 'False' if they shouldn't (see 'set print |
| pretty' in *note Print Settings::). |
| |
| 'array_indexes' |
| 'True' if array indexes should be included in the string |
| representation of arrays, 'False' if they shouldn't (see 'set |
| print array-indexes' in *note Print Settings::). |
| |
| 'symbols' |
| 'True' if the string representation of a pointer should |
| include the corresponding symbol name (if one exists), 'False' |
| if it shouldn't (see 'set print symbol' in *note Print |
| Settings::). |
| |
| 'unions' |
| 'True' if unions which are contained in other structures or |
| unions should be expanded, 'False' if they shouldn't (see 'set |
| print union' in *note Print Settings::). |
| |
| 'deref_refs' |
| 'True' if C++ references should be resolved to the value they |
| refer to, 'False' (the default) if they shouldn't. Note that, |
| unlike for the 'print' command, references are not |
| automatically expanded when using the 'format_string' method |
| or the 'str' function. There is no global 'print' setting to |
| change the default behaviour. |
| |
| 'actual_objects' |
| 'True' if the representation of a pointer to an object should |
| identify the _actual_ (derived) type of the object rather than |
| the _declared_ type, using the virtual function table. |
| 'False' if the _declared_ type should be used. (See 'set |
| print object' in *note Print Settings::). |
| |
| 'static_fields' |
| 'True' if static members should be included in the string |
| representation of a C++ object, 'False' if they shouldn't (see |
| 'set print static-members' in *note Print Settings::). |
| |
| 'max_elements' |
| Number of array elements to print, or '0' to print an |
| unlimited number of elements (see 'set print elements' in |
| *note Print Settings::). |
| |
| 'max_depth' |
| The maximum depth to print for nested structs and unions, or |
| '-1' to print an unlimited number of elements (see 'set print |
| max-depth' in *note Print Settings::). |
| |
| 'repeat_threshold' |
| Set the threshold for suppressing display of repeated array |
| elements, or '0' to represent all elements, even if repeated. |
| (See 'set print repeats' in *note Print Settings::). |
| |
| 'format' |
| A string containing a single character representing the format |
| to use for the returned string. For instance, ''x'' is |
| equivalent to using the GDB command 'print' with the '/x' |
| option and formats the value as a hexadecimal number. |
| |
| -- 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. |
| |
| Values are interpreted as strings according to the rules of the |
| current language. If the optional length argument is given, the |
| string will be converted to that length, and will include any |
| embedded zeroes that the string may contain. Otherwise, for |
| languages where the string is zero-terminated, the entire string |
| will be converted. |
| |
| For example, in C-like languages, a value is a string if it is a |
| pointer to or an array of characters or ints of type 'wchar_t', |
| 'char16_t', or 'char32_t'. |
| |
| If the optional ENCODING argument is given, it must be a string |
| naming the encoding of the string in the 'gdb.Value', such as |
| '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same |
| encodings as the corresponding argument to Python's 'string.decode' |
| method, and the Python codec machinery will be used to convert the |
| string. If ENCODING is not given, or if ENCODING is the empty |
| string, then either the 'target-charset' (*note Character Sets::) |
| will be used, or a language-specific encoding will be used, if the |
| current language is able to supply one. |
| |
| The optional ERRORS argument is the same as the corresponding |
| argument to Python's 'string.decode' method. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and converted to the given length. |
| |
| -- Function: Value.lazy_string ([encoding [, length]]) |
| If this 'gdb.Value' represents a string, then this method converts |
| the contents to a 'gdb.LazyString' (*note Lazy Strings In |
| Python::). Otherwise, this method will throw an exception. |
| |
| If the optional ENCODING argument is given, it must be a string |
| naming the encoding of the 'gdb.LazyString'. Some examples are: |
| 'ascii', 'iso-8859-6' or 'utf-8'. If the ENCODING argument is an |
| encoding that GDB does recognize, GDB will raise an error. |
| |
| When a lazy string is printed, the GDB encoding machinery is used |
| to convert the string during printing. If the optional ENCODING |
| argument is not provided, or is an empty string, GDB will |
| automatically select the encoding most suitable for the string |
| type. For further information on encoding in GDB please see *note |
| Character Sets::. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and encoded to the length of characters specified. If the |
| LENGTH argument is not provided, the string will be fetched and |
| encoded until a null of appropriate width is found. |
| |
| -- Function: Value.fetch_lazy () |
| If the 'gdb.Value' object is currently a lazy value |
| ('gdb.Value.is_lazy' is 'True'), then the value is fetched from the |
| inferior. Any errors that occur in the process will produce a |
| Python exception. |
| |
| If the 'gdb.Value' object is not a lazy value, this method has no |
| effect. |
| |
| This method does not return a value. |
| |
| |
| File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API |
| |
| 23.2.2.4 Types In Python |
| ........................ |
| |
| GDB represents types from the inferior using the class 'gdb.Type'. |
| |
| The following type-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.lookup_type (name [, block]) |
| This function looks up a type by its NAME, which must be a string. |
| |
| If BLOCK is given, then NAME is looked up in that scope. |
| Otherwise, it is searched for globally. |
| |
| Ordinarily, this function will return an instance of 'gdb.Type'. |
| If the named type cannot be found, it will throw an exception. |
| |
| If the type is a structure or class type, or an enum type, the fields |
| of that type can be accessed using the Python "dictionary syntax". For |
| example, if 'some_type' is a 'gdb.Type' instance holding a structure |
| type, you can access its 'foo' field with: |
| |
| bar = some_type['foo'] |
| |
| 'bar' will be a 'gdb.Field' object; see below under the description |
| of the 'Type.fields' method for a description of the 'gdb.Field' class. |
| |
| An instance of 'Type' has the following attributes: |
| |
| -- Variable: Type.alignof |
| The alignment of this type, in bytes. Type alignment comes from |
| the debugging information; if it was not specified, then GDB will |
| use the relevant ABI to try to determine the alignment. In some |
| cases, even this is not possible, and zero will be returned. |
| |
| -- Variable: Type.code |
| The type code for this type. The type code will be one of the |
| 'TYPE_CODE_' constants defined below. |
| |
| -- Variable: Type.name |
| The name of this type. If this type has no name, then 'None' is |
| returned. |
| |
| -- 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.objfile |
| The 'gdb.Objfile' that this type was defined in, or 'None' if there |
| is no associated objfile. |
| |
| 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 'enum' or 'static' (as in |
| C++) fields. The value is the position, counting in bits, |
| from the start of the containing type. |
| |
| 'enumval' |
| This attribute is only available for 'enum' fields, and its |
| 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. |
| |
| 'parent_type' |
| The type which contains this field. This is an instance of |
| 'gdb.Type'. |
| |
| -- 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.Value' or 'gdb.Type' which represents the value |
| of the Nth template argument (indexed starting at 0). |
| |
| If this 'gdb.Type' is not a template type, or if the type has fewer |
| than N template arguments, 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.optimized_out () |
| Return 'gdb.Value' instance of this type whose value is optimized |
| out. This allows a frame decorator to indicate that the value of |
| an argument or a local variable is not known. |
| |
| Each type has a code, which indicates what category this type falls |
| into. The available type categories are represented by constants |
| defined in the 'gdb' module: |
| |
| 'gdb.TYPE_CODE_PTR' |
| The type is a pointer. |
| |
| 'gdb.TYPE_CODE_ARRAY' |
| The type is an array. |
| |
| 'gdb.TYPE_CODE_STRUCT' |
| The type is a structure. |
| |
| 'gdb.TYPE_CODE_UNION' |
| The type is a union. |
| |
| 'gdb.TYPE_CODE_ENUM' |
| The type is an enum. |
| |
| 'gdb.TYPE_CODE_FLAGS' |
| A bit flags type, used for things such as status registers. |
| |
| 'gdb.TYPE_CODE_FUNC' |
| The type is a function. |
| |
| 'gdb.TYPE_CODE_INT' |
| The type is an integer type. |
| |
| 'gdb.TYPE_CODE_FLT' |
| A floating point type. |
| |
| 'gdb.TYPE_CODE_VOID' |
| The special type 'void'. |
| |
| 'gdb.TYPE_CODE_SET' |
| A Pascal set type. |
| |
| 'gdb.TYPE_CODE_RANGE' |
| A range type, that is, an integer type with bounds. |
| |
| 'gdb.TYPE_CODE_STRING' |
| A string type. Note that this is only used for certain languages |
| with language-defined string types; C strings are not represented |
| this way. |
| |
| 'gdb.TYPE_CODE_BITSTRING' |
| A string of bits. It is deprecated. |
| |
| 'gdb.TYPE_CODE_ERROR' |
| An unknown or erroneous type. |
| |
| 'gdb.TYPE_CODE_METHOD' |
| A method type, as found in C++. |
| |
| 'gdb.TYPE_CODE_METHODPTR' |
| A pointer-to-member-function. |
| |
| 'gdb.TYPE_CODE_MEMBERPTR' |
| A pointer-to-member. |
| |
| 'gdb.TYPE_CODE_REF' |
| A reference type. |
| |
| 'gdb.TYPE_CODE_RVALUE_REF' |
| A C++11 rvalue reference type. |
| |
| 'gdb.TYPE_CODE_CHAR' |
| A character type. |
| |
| 'gdb.TYPE_CODE_BOOL' |
| A boolean type. |
| |
| 'gdb.TYPE_CODE_COMPLEX' |
| A complex float type. |
| |
| 'gdb.TYPE_CODE_TYPEDEF' |
| A typedef to some other type. |
| |
| 'gdb.TYPE_CODE_NAMESPACE' |
| A C++ namespace. |
| |
| 'gdb.TYPE_CODE_DECFLOAT' |
| A decimal floating point type. |
| |
| 'gdb.TYPE_CODE_INTERNAL_FUNCTION' |
| A function internal to GDB. This is the type used to represent |
| convenience functions. |
| |
| Further support for types is provided in the 'gdb.types' Python |
| module (*note gdb.types::). |
| |
| |
| File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API |
| |
| 23.2.2.5 Pretty Printing API |
| ............................ |
| |
| A pretty-printer is just an object that holds a value and implements a |
| specific interface, defined here. An example output is provided (*note |
| Pretty Printing::). |
| |
| -- Function: pretty_printer.children (self) |
| GDB will call this method on a pretty-printer to compute the |
| children of the pretty-printer's value. |
| |
| This method must return an object conforming to the Python iterator |
| protocol. Each item returned by the iterator must be a tuple |
| holding two elements. The first element is the "name" of the |
| child; the second element is the child's value. The value can be |
| any Python object which is convertible to a GDB value. |
| |
| This method is optional. If it does not exist, GDB will act as |
| though the value has no children. |
| |
| For efficiency, the 'children' method should lazily compute its |
| results. This will let GDB read as few elements as necessary, for |
| example when various print settings (*note Print Settings::) or |
| '-var-list-children' (*note GDB/MI Variable Objects::) limit the |
| number of elements to be displayed. |
| |
| Children may be hidden from display based on the value of 'set |
| print max-depth' (*note Print Settings::). |
| |
| -- Function: pretty_printer.display_hint (self) |
| The CLI may call this method and use its result to change the |
| formatting of a value. The result will also be supplied to an MI |
| consumer as a 'displayhint' attribute of the variable being |
| printed. |
| |
| This method is optional. If it does exist, this method must return |
| a string or the special value 'None'. |
| |
| Some display hints are predefined by GDB: |
| |
| 'array' |
| Indicate that the object being printed is "array-like". The |
| CLI uses this to respect parameters such as 'set print |
| elements' and 'set print array'. |
| |
| 'map' |
| Indicate that the object being printed is "map-like", and that |
| the children of this value can be assumed to alternate between |
| keys and values. |
| |
| 'string' |
| Indicate that the object being printed is "string-like". If |
| the printer's 'to_string' method returns a Python string of |
| some kind, then GDB will call its internal language-specific |
| string-printing function to format the string. For the CLI |
| this means adding quotation marks, possibly escaping some |
| characters, respecting 'set print elements', and the like. |
| |
| The special value 'None' causes GDB to apply the default display |
| rules. |
| |
| -- Function: pretty_printer.to_string (self) |
| GDB will call this method to display the string representation of |
| the value passed to the object's constructor. |
| |
| When printing from the CLI, if the 'to_string' method exists, then |
| GDB will prepend its result to the values returned by 'children'. |
| Exactly how this formatting is done is dependent on the display |
| hint, and may change as more hints are added. Also, depending on |
| the print settings (*note Print Settings::), the CLI may print just |
| the result of 'to_string' in a stack trace, omitting the result of |
| 'children'. |
| |
| If this method returns a string, it is printed verbatim. |
| |
| Otherwise, if this method returns an instance of 'gdb.Value', then |
| GDB prints this value. This may result in a call to another |
| pretty-printer. |
| |
| If instead the method returns a Python value which is convertible |
| to a 'gdb.Value', then GDB performs the conversion and prints the |
| resulting value. Again, this may result in a call to another |
| pretty-printer. Python scalars (integers, floats, and booleans) |
| and strings are convertible to 'gdb.Value'; other types are not. |
| |
| Finally, if this method returns 'None' then no further operations |
| are peformed in this method and nothing is printed. |
| |
| If the result is not one of these types, an exception is raised. |
| |
| GDB provides a function which can be used to look up the default |
| pretty-printer for a 'gdb.Value': |
| |
| -- Function: gdb.default_visualizer (value) |
| This function takes a 'gdb.Value' object as an argument. If a |
| pretty-printer for this value exists, then it is returned. If no |
| such printer exists, then this returns 'None'. |
| |
| |
| File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API |
| |
| 23.2.2.6 Selecting Pretty-Printers |
| .................................. |
| |
| GDB provides several ways to register a pretty-printer: globally, per |
| program space, and per objfile. When choosing how to register your |
| pretty-printer, a good rule is to register it with the smallest scope |
| possible: that is prefer a specific objfile first, then a program space, |
| and only register a printer globally as a last resort. |
| |
| -- Variable: gdb.pretty_printers |
| The Python list 'gdb.pretty_printers' contains an array of |
| functions or callable objects that have been registered via |
| addition as a pretty-printer. Printers in this list are called |
| 'global' printers, they're available when debugging all inferiors. |
| |
| Each 'gdb.Progspace' contains a 'pretty_printers' attribute. Each |
| 'gdb.Objfile' also contains a 'pretty_printers' attribute. |
| |
| Each function on these lists is passed a single 'gdb.Value' argument |
| and should return a pretty-printer object conforming to the interface |
| definition above (*note Pretty Printing API::). If a function cannot |
| create a pretty-printer for the value, it should return 'None'. |
| |
| GDB first checks the 'pretty_printers' attribute of each |
| 'gdb.Objfile' in the current program space and iteratively calls each |
| enabled lookup routine in the list for that 'gdb.Objfile' until it |
| receives a pretty-printer object. If no pretty-printer is found in the |
| objfile lists, GDB then searches the pretty-printer list of the current |
| program space, calling each enabled function until an object is |
| returned. After these lists have been exhausted, it tries the global |
| 'gdb.pretty_printers' list, again calling each enabled function until an |
| object is returned. |
| |
| The order in which the objfiles are searched is not specified. For a |
| given list, functions are always invoked from the head of the list, and |
| iterated over sequentially until the end of the list, or a printer |
| object is returned. |
| |
| For various reasons a pretty-printer may not work. For example, the |
| underlying data structure may have changed and the pretty-printer is out |
| of date. |
| |
| The consequences of a broken pretty-printer are severe enough that |
| GDB provides support for enabling and disabling individual printers. |
| For example, if 'print frame-arguments' is on, a backtrace can become |
| highly illegible if any argument is printed with a broken printer. |
| |
| Pretty-printers are enabled and disabled by attaching an 'enabled' |
| attribute to the registered function or callable object. If this |
| attribute is present and its value is 'False', the printer is disabled, |
| otherwise the printer is enabled. |
| |
| |
| File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API |
| |
| 23.2.2.7 Writing a Pretty-Printer |
| ................................. |
| |
| A pretty-printer consists of two parts: a lookup function to detect if |
| the type is supported, and the printer itself. |
| |
| Here is an example showing how a 'std::string' printer might be |
| written. *Note Pretty Printing API::, for details on the API this class |
| must provide. |
| |
| class StdStringPrinter(object): |
| "Print a std::string" |
| |
| def __init__(self, val): |
| self.val = val |
| |
| def to_string(self): |
| return self.val['_M_dataplus']['_M_p'] |
| |
| def display_hint(self): |
| return 'string' |
| |
| And here is an example showing how a lookup function for the printer |
| example above might be written. |
| |
| def str_lookup_function(val): |
| lookup_tag = val.type.tag |
| if lookup_tag == None: |
| return None |
| regex = re.compile("^std::basic_string<char,.*>$") |
| if regex.match(lookup_tag): |
| return StdStringPrinter(val) |
| return None |
| |
| The example lookup function extracts the value's type, and attempts |
| to match it to a type that it can pretty-print. If it is a type the |
| printer can pretty-print, it will return a printer object. If not, it |
| returns 'None'. |
| |
| We recommend that you put your core pretty-printers into a Python |
| package. If your pretty-printers are for use with a library, we further |
| recommend embedding a version number into the package name. This |
| practice will enable GDB to load multiple versions of your |
| pretty-printers at the same time, because they will have different |
| names. |
| |
| You should write auto-loaded code (*note Python Auto-loading::) such |
| that it can be evaluated multiple times without changing its meaning. |
| An ideal auto-load file will consist solely of 'import's of your printer |
| modules, followed by a call to a register pretty-printers with the |
| current objfile. |
| |
| Taken as a whole, this approach will scale nicely to multiple |
| inferiors, each potentially using a different library version. |
| Embedding a version number in the Python package name will ensure that |
| GDB is able to load both sets of printers simultaneously. Then, because |
| the search for pretty-printers is done by objfile, and because your |
| auto-loaded code took care to register your library's printers with a |
| specific objfile, GDB will find the correct printers for the specific |
| version of the library used by each inferior. |
| |
| To continue the 'std::string' example (*note Pretty Printing API::), |
| this code might appear in 'gdb.libstdcxx.v6': |
| |
| def register_printers(objfile): |
| objfile.pretty_printers.append(str_lookup_function) |
| |
| And then the corresponding contents of the auto-load file would be: |
| |
| import gdb.libstdcxx.v6 |
| gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) |
| |
| The previous example illustrates a basic pretty-printer. There are a |
| few things that can be improved on. The printer doesn't have a name, |
| making it hard to identify in a list of installed printers. The lookup |
| function has a name, but lookup functions can have arbitrary, even |
| identical, names. |
| |
| Second, the printer only handles one type, whereas a library |
| typically has several types. One could install a lookup function for |
| each desired type in the library, but one could also have a single |
| lookup function recognize several types. The latter is the conventional |
| way this is handled. If a pretty-printer can handle multiple data |
| types, then its "subprinters" are the printers for the individual data |
| types. |
| |
| The 'gdb.printing' module provides a formal way of solving these |
| problems (*note gdb.printing::). Here is another example that handles |
| multiple types. |
| |
| These are the types we are going to pretty-print: |
| |
| struct foo { int a, b; }; |
| struct bar { struct foo x, y; }; |
| |
| Here are the printers: |
| |
| class fooPrinter: |
| """Print a foo object.""" |
| |
| def __init__(self, val): |
| self.val = val |
| |
| def to_string(self): |
| return ("a=<" + str(self.val["a"]) + |
| "> b=<" + str(self.val["b"]) + ">") |
| |
| class barPrinter: |
| """Print a bar object.""" |
| |
| def __init__(self, val): |
| self.val = val |
| |
| def to_string(self): |
| return ("x=<" + str(self.val["x"]) + |
| "> y=<" + str(self.val["y"]) + ">") |
| |
| This example doesn't need a lookup function, that is handled by the |
| 'gdb.printing' module. Instead a function is provided to build up the |
| object that handles the lookup. |
| |
| import gdb.printing |
| |
| def build_pretty_printer(): |
| pp = gdb.printing.RegexpCollectionPrettyPrinter( |
| "my_library") |
| pp.add_printer('foo', '^foo$', fooPrinter) |
| pp.add_printer('bar', '^bar$', barPrinter) |
| return pp |
| |
| And here is the autoload support: |
| |
| import gdb.printing |
| import my_library |
| gdb.printing.register_pretty_printer( |
| gdb.current_objfile(), |
| my_library.build_pretty_printer()) |
| |
| Finally, when this printer is loaded into GDB, here is the |
| corresponding output of 'info pretty-printer': |
| |
| (gdb) info pretty-printer |
| my_library.so: |
| my_library |
| foo |
| bar |
| |
| |
| File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API |
| |
| 23.2.2.8 Type Printing API |
| .......................... |
| |
| GDB provides a way for Python code to customize type display. This is |
| mainly useful for substituting canonical typedef names for types. |
| |
| 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: |
| |
| -- 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. |
| |
| -- 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. |
| |
| -- 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. The TYPE |
| argument 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: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API |
| |
| 23.2.2.9 Filtering Frames |
| ......................... |
| |
| 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::). |
| |
| 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. 100 is a good default priority. |
| |
| |
| File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API |
| |
| 23.2.2.10 Decorating Frames |
| ........................... |
| |
| 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. |
| |
| 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. |
| |
| 'FrameDecorator' is defined in the Python module |
| 'gdb.FrameDecorator', so your code can import it like: |
| from gdb.FrameDecorator import FrameDecorator |
| |
| -- 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. |
| |
| |
| File: gdb.info, Node: Writing a Frame Filter, Next: Unwinding Frames in Python, Prev: Frame Decorator API, Up: Python API |
| |
| 23.2.2.11 Writing a Frame Filter |
| ................................ |
| |
| There are three basic elements that a frame filter must implement: it |
| must correctly implement the documented interface (*note Frame Filter |
| API::), it must register itself with GDB, and finally, it must decide if |
| it is to work on the data provided by GDB. In all cases, whether it |
| works on the iterator or not, each frame filter must return an iterator. |
| A bare-bones frame filter follows the pattern in the following example. |
| |
| import gdb |
| |
| class FrameFilter(): |
| |
| def __init__(self): |
| # Frame filter attribute creation. |
| # |
| # 'name' is the name of the filter that GDB will display. |
| # |
| # 'priority' is the priority of the filter relative to other |
| # filters. |
| # |
| # 'enabled' is a boolean that indicates whether this filter is |
| # enabled and should be executed. |
| |
| self.name = "Foo" |
| self.priority = 100 |
| self.enabled = True |
| |
| # Register this frame filter with the global frame_filters |
| # dictionary. |
| gdb.frame_filters[self.name] = self |
| |
| def filter(self, frame_iter): |
| # Just return the iterator. |
| return frame_iter |
| |
| The frame filter in the example above implements the three |
| requirements for all frame filters. It implements the API, self |
| registers, and makes a decision on the iterator (in this case, it just |
| returns the iterator untouched). |
| |
| The first step is attribute creation and assignment, and as shown in |
| the comments the filter assigns the following attributes: 'name', |
| 'priority' and whether the filter should be enabled with the 'enabled' |
| attribute. |
| |
| The second step is registering the frame filter with the dictionary |
| or dictionaries that the frame filter has interest in. As shown in the |
| comments, this filter just registers itself with the global dictionary |
| 'gdb.frame_filters'. As noted earlier, 'gdb.frame_filters' is a |
| dictionary that is initialized in the 'gdb' module when GDB starts. |
| What dictionary a filter registers with is an important consideration. |
| Generally, if a filter is specific to a set of code, it should be |
| registered either in the 'objfile' or 'progspace' dictionaries as they |
| are specific to the program currently loaded in GDB. The global |
| dictionary is always present in GDB and is never unloaded. Any filters |
| registered with the global dictionary will exist until GDB exits. To |
| avoid filters that may conflict, it is generally better to register |
| frame filters against the dictionaries that more closely align with the |
| usage of the filter currently in question. *Note Python Auto-loading::, |
| for further information on auto-loading Python scripts. |
| |
| GDB takes a hands-off approach to frame filter registration, |
| therefore it is the frame filter's responsibility to ensure registration |
| has occurred, and that any exceptions are handled appropriately. In |
| particular, you may wish to handle exceptions relating to Python |
| dictionary key uniqueness. It is mandatory that the dictionary key is |
| the same as frame filter's 'name' attribute. When a user manages frame |
| filters (*note Frame Filter Management::), the names GDB will display |
| are those contained in the 'name' attribute. |
| |
| The final step of this example is the implementation of the 'filter' |
| method. As shown in the example comments, we define the 'filter' method |
| and note that the method must take an iterator, and also must return an |
| iterator. In this bare-bones example, the frame filter is not very |
| useful as it just returns the iterator untouched. However this is a |
| valid operation for frame filters that have the 'enabled' attribute set, |
| but decide not to operate on any frames. |
| |
| In the next example, the frame filter operates on all frames and |
| utilizes a frame decorator to perform some work on the frames. *Note |
| Frame Decorator API::, for further information on the frame decorator |
| interface. |
| |
| This example works on inlined frames. It highlights frames which are |
| inlined by tagging them with an "[inlined]" tag. By applying a frame |
| decorator to all frames with the Python 'itertools imap' method, the |
| example defers actions to the frame decorator. Frame decorators are |
| only processed when GDB prints the backtrace. |
| |
| This introduces a new decision making topic: whether to perform |
| decision making operations at the filtering step, or at the printing |
| step. In this example's approach, it does not perform any filtering |
| decisions at the filtering step beyond mapping a frame decorator to each |
| frame. This allows the actual decision making to be performed when each |
| frame is printed. This is an important consideration, and well worth |
| reflecting upon when designing a frame filter. An issue that frame |
| filters should avoid is unwinding the stack if possible. Some stacks |
| can run very deep, into the tens of thousands in some cases. To search |
| every frame to determine if it is inlined ahead of time may be too |
| expensive at the filtering step. The frame filter cannot know how many |
| frames it has to iterate over, and it would have to iterate through them |
| all. This ends up duplicating effort as GDB performs this iteration |
| when it prints the frames. |
| |
| In this example decision making can be deferred to the printing step. |
| As each frame is printed, the frame decorator can examine each frame in |
| turn when GDB iterates. From a performance viewpoint, this is the most |
| appropriate decision to make as it avoids duplicating the effort that |
| the printing step would undertake anyway. Also, if there are many frame |
| filters unwinding the stack during filtering, it can substantially delay |
| the printing of the backtrace which will result in large memory usage, |
| and a poor user experience. |
| |
| class InlineFilter(): |
| |
| def __init__(self): |
| self.name = "InlinedFrameFilter" |
| self.priority = 100 |
| self.enabled = True |
| gdb.frame_filters[self.name] = self |
| |
| def filter(self, frame_iter): |
| frame_iter = itertools.imap(InlinedFrameDecorator, |
| frame_iter) |
| return frame_iter |
| |
| This frame filter is somewhat similar to the earlier example, except |
| that the 'filter' method applies a frame decorator object called |
| 'InlinedFrameDecorator' to each element in the iterator. The 'imap' |
| Python method is light-weight. It does not proactively iterate over the |
| iterator, but rather creates a new iterator which wraps the existing |
| one. |
| |
| Below is the frame decorator for this example. |
| |
| class InlinedFrameDecorator(FrameDecorator): |
| |
| def __init__(self, fobj): |
| super(InlinedFrameDecorator, self).__init__(fobj) |
| |
| def function(self): |
| frame = fobj.inferior_frame() |
| name = str(frame.name()) |
| |
| if frame.type() == gdb.INLINE_FRAME: |
| name = name + " [inlined]" |
| |
| return name |
| |
| This frame decorator only defines and overrides the 'function' |
| method. It lets the supplied 'FrameDecorator', which is shipped with |
| GDB, perform the other work associated with printing this frame. |
| |
| The combination of these two objects create this output from a |
| backtrace: |
| |
| #0 0x004004e0 in bar () at inline.c:11 |
| #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21 |
| #2 0x00400566 in main () at inline.c:31 |
| |
| So in the case of this example, a frame decorator is applied to all |
| frames, regardless of whether they may be inlined or not. As GDB |
| iterates over the iterator produced by the frame filters, GDB executes |
| each frame decorator which then makes a decision on what to print in the |
| 'function' callback. Using a strategy like this is a way to defer |
| decisions on the frame content to printing time. |
| |
| Eliding Frames |
| -------------- |
| |
| It might be that the above example is not desirable for representing |
| inlined frames, and a hierarchical approach may be preferred. If we |
| want to hierarchically represent frames, the 'elided' frame decorator |
| interface might be preferable. |
| |
| This example approaches the issue with the 'elided' method. This |
| example is quite long, but very simplistic. It is out-of-scope for this |
| section to write a complete example that comprehensively covers all |
| approaches of finding and printing inlined frames. However, this |
| example illustrates the approach an author might use. |
| |
| This example comprises of three sections. |
| |
| class InlineFrameFilter(): |
| |
| def __init__(self): |
| self.name = "InlinedFrameFilter" |
| self.priority = 100 |
| self.enabled = True |
| gdb.frame_filters[self.name] = self |
| |
| def filter(self, frame_iter): |
| return ElidingInlineIterator(frame_iter) |
| |
| This frame filter is very similar to the other examples. The only |
| difference is this frame filter is wrapping the iterator provided to it |
| ('frame_iter') with a custom iterator called 'ElidingInlineIterator'. |
| This again defers actions to when GDB prints the backtrace, as the |
| iterator is not traversed until printing. |
| |
| The iterator for this example is as follows. It is in this section |
| of the example where decisions are made on the content of the backtrace. |
| |
| class ElidingInlineIterator: |
| def __init__(self, ii): |
| self.input_iterator = ii |
| |
| def __iter__(self): |
| return self |
| |
| def next(self): |
| frame = next(self.input_iterator) |
| |
| if frame.inferior_frame().type() != gdb.INLINE_FRAME: |
| return frame |
| |
| try: |
| eliding_frame = next(self.input_iterator) |
| except StopIteration: |
| return frame |
| return ElidingFrameDecorator(eliding_frame, [frame]) |
| |
| This iterator implements the Python iterator protocol. When the |
| 'next' function is called (when GDB prints each frame), the iterator |
| checks if this frame decorator, 'frame', is wrapping an inlined frame. |
| If it is not, it returns the existing frame decorator untouched. If it |
| is wrapping an inlined frame, it assumes that the inlined frame was |
| contained within the next oldest frame, 'eliding_frame', which it |
| fetches. It then creates and returns a frame decorator, |
| 'ElidingFrameDecorator', which contains both the elided frame, and the |
| eliding frame. |
| |
| class ElidingInlineDecorator(FrameDecorator): |
| |
| def __init__(self, frame, elided_frames): |
| super(ElidingInlineDecorator, self).__init__(frame) |
| self.frame = frame |
| self.elided_frames = elided_frames |
| |
| def elided(self): |
| return iter(self.elided_frames) |
| |
| This frame decorator overrides one function and returns the inlined |
| frame in the 'elided' method. As before it lets 'FrameDecorator' do the |
| rest of the work involved in printing this frame. This produces the |
| following output. |
| |
| #0 0x004004e0 in bar () at inline.c:11 |
| #2 0x00400529 in main () at inline.c:25 |
| #1 0x00400529 in max (b=6, a=12) at inline.c:15 |
| |
| In that output, 'max' which has been inlined into 'main' is printed |
| hierarchically. Another approach would be to combine the 'function' |
| method, and the 'elided' method to both print a marker in the inlined |
| frame, and also show the hierarchical relationship. |
| |
| |
| File: gdb.info, Node: Unwinding Frames in Python, Next: Xmethods In Python, Prev: Writing a Frame Filter, Up: Python API |
| |
| 23.2.2.12 Unwinding Frames in Python |
| .................................... |
| |
| In GDB terminology "unwinding" is the process of finding the previous |
| frame (that is, caller's) from the current one. An unwinder has three |
| methods. The first one checks if it can handle given frame ("sniff" |
| it). For the frames it can sniff an unwinder provides two additional |
| methods: it can return frame's ID, and it can fetch registers from the |
| previous frame. A running GDB mantains a list of the unwinders and |
| calls each unwinder's sniffer in turn until it finds the one that |
| recognizes the current frame. There is an API to register an unwinder. |
| |
| The unwinders that come with GDB handle standard frames. However, |
| mixed language applications (for example, an application running Java |
| Virtual Machine) sometimes use frame layouts that cannot be handled by |
| the GDB unwinders. You can write Python code that can handle such |
| custom frames. |
| |
| You implement a frame unwinder in Python as a class with which has |
| two attributes, 'name' and 'enabled', with obvious meanings, and a |
| single method '__call__', which examines a given frame and returns an |
| object (an instance of 'gdb.UnwindInfo class)' describing it. If an |
| unwinder does not recognize a frame, it should return 'None'. The code |
| in GDB that enables writing unwinders in Python uses this object to |
| return frame's ID and previous frame registers when GDB core asks for |
| them. |
| |
| An unwinder should do as little work as possible. Some otherwise |
| innocuous operations can cause problems (even crashes, as this code is |
| not not well-hardened yet). For example, making an inferior call from |
| an unwinder is unadvisable, as an inferior call will reset GDB's stack |
| unwinding process, potentially causing re-entrant unwinding. |
| |
| Unwinder Input |
| -------------- |
| |
| An object passed to an unwinder (a 'gdb.PendingFrame' instance) provides |
| a method to read frame's registers: |
| |
| -- Function: PendingFrame.read_register (reg) |
| This method returns the contents of the register REG in the frame |
| as a 'gdb.Value' object. REG can be either a register number or a |
| register name; the values are platform-specific. They are usually |
| found in the corresponding 'PLATFORM-tdep.h' file in the GDB source |
| tree. If REG does not name a register for the current |
| architecture, this method will throw an exception. |
| |
| Note that this method will always return a 'gdb.Value' for a valid |
| register name. This does not mean that the value will be valid. |
| For example, you may request a register that an earlier unwinder |
| could not unwind--the value will be unavailable. Instead, the |
| 'gdb.Value' returned from this method will be lazy; that is, its |
| underlying bits will not be fetched until it is first used. So, |
| attempting to use such a value will cause an exception at the point |
| of use. |
| |
| The type of the returned 'gdb.Value' depends on the register and |
| the architecture. It is common for registers to have a scalar |
| type, like 'long long'; but many other types are possible, such as |
| pointer, pointer-to-function, floating point or vector types. |
| |
| It also provides a factory method to create a 'gdb.UnwindInfo' |
| instance to be returned to GDB: |
| |
| -- Function: PendingFrame.create_unwind_info (frame_id) |
| Returns a new 'gdb.UnwindInfo' instance identified by given |
| FRAME_ID. The argument is used to build GDB's frame ID using one |
| of functions provided by GDB. FRAME_ID's attributes determine |
| which function will be used, as follows: |
| |
| 'sp, pc' |
| The frame is identified by the given stack address and PC. The |
| stack address must be chosen so that it is constant throughout |
| the lifetime of the frame, so a typical choice is the value of |
| the stack pointer at the start of the function--in the DWARF |
| standard, this would be the "Call Frame Address". |
| |
| This is the most common case by far. The other cases are |
| documented for completeness but are only useful in specialized |
| situations. |
| |
| 'sp, pc, special' |
| The frame is identified by the stack address, the PC, and a |
| "special" address. The special address is used on |
| architectures that can have frames that do not change the |
| stack, but which are still distinct, for example the IA-64, |
| which has a second stack for registers. Both SP and SPECIAL |
| must be constant throughout the lifetime of the frame. |
| |
| 'sp' |
| The frame is identified by the stack address only. Any other |
| stack frame with a matching SP will be considered to match |
| this frame. Inside gdb, this is called a "wild frame". You |
| will never need this. |
| |
| Each attribute value should be an instance of 'gdb.Value'. |
| |
| Unwinder Output: UnwindInfo |
| --------------------------- |
| |
| Use 'PendingFrame.create_unwind_info' method described above to create a |
| 'gdb.UnwindInfo' instance. Use the following method to specify caller |
| registers that have been saved in this frame: |
| |
| -- Function: gdb.UnwindInfo.add_saved_register (reg, value) |
| REG identifies the register. It can be a number or a name, just as |
| for the 'PendingFrame.read_register' method above. VALUE is a |
| register value (a 'gdb.Value' object). |
| |
| Unwinder Skeleton Code |
| ---------------------- |
| |
| GDB comes with the module containing the base 'Unwinder' class. Derive |
| your unwinder class from it and structure the code as follows: |
| |
| from gdb.unwinders import Unwinder |
| |
| class FrameId(object): |
| def __init__(self, sp, pc): |
| self.sp = sp |
| self.pc = pc |
| |
| |
| class MyUnwinder(Unwinder): |
| def __init__(....): |
| super(MyUnwinder, self).__init___(<expects unwinder name argument>) |
| |
| def __call__(pending_frame): |
| if not <we recognize frame>: |
| return None |
| # Create UnwindInfo. Usually the frame is identified by the stack |
| # pointer and the program counter. |
| sp = pending_frame.read_register(<SP number>) |
| pc = pending_frame.read_register(<PC number>) |
| unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc)) |
| |
| # Find the values of the registers in the caller's frame and |
| # save them in the result: |
| unwind_info.add_saved_register(<register>, <value>) |
| .... |
| |
| # Return the result: |
| return unwind_info |
| |
| |
| Registering a Unwinder |
| ---------------------- |
| |
| An object file, a program space, and the GDB proper can have unwinders |
| registered with it. |
| |
| The 'gdb.unwinders' module provides the function to register a |
| unwinder: |
| |
| -- Function: gdb.unwinder.register_unwinder (locus, unwinder, |
| replace=False) |
| LOCUS is specifies an object file or a program space to which |
| UNWINDER is added. Passing 'None' or 'gdb' adds UNWINDER to the |
| GDB's global unwinder list. The newly added UNWINDER will be |
| called before any other unwinder from the same locus. Two |
| unwinders in the same locus cannot have the same name. An attempt |
| to add a unwinder with already existing name raises an exception |
| unless REPLACE is 'True', in which case the old unwinder is |
| deleted. |
| |
| Unwinder Precedence |
| ------------------- |
| |
| GDB first calls the unwinders from all the object files in no particular |
| order, then the unwinders from the current program space, and finally |
| the unwinders from GDB. |
| |
| |
| File: gdb.info, Node: Xmethods In Python, Next: Xmethod API, Prev: Unwinding Frames in Python, Up: Python API |
| |
| 23.2.2.13 Xmethods In Python |
| ............................ |
| |
| "Xmethods" are additional methods or replacements for existing methods |
| of a C++ class. This feature is useful for those cases where a method |
| defined in C++ source code could be inlined or optimized out by the |
| compiler, making it unavailable to GDB. For such cases, one can define |
| an xmethod to serve as a replacement for the method defined in the C++ |
| source code. GDB will then invoke the xmethod, instead of the C++ |
| method, to evaluate expressions. One can also use xmethods when |
| debugging with core files. Moreover, when debugging live programs, |
| invoking an xmethod need not involve running the inferior (which can |
| potentially perturb its state). Hence, even if the C++ method is |
| available, it is better to use its replacement xmethod if one is |
| defined. |
| |
| The xmethods feature in Python is available via the concepts of an |
| "xmethod matcher" and an "xmethod worker". To implement an xmethod, one |
| has to implement a matcher and a corresponding worker for it (more than |
| one worker can be implemented, each catering to a different overloaded |
| instance of the method). Internally, GDB invokes the 'match' method of |
| a matcher to match the class type and method name. On a match, the |
| 'match' method returns a list of matching _worker_ objects. Each worker |
| object typically corresponds to an overloaded instance of the xmethod. |
| They implement a 'get_arg_types' method which returns a sequence of |
| types corresponding to the arguments the xmethod requires. GDB uses |
| this sequence of types to perform overload resolution and picks a |
| winning xmethod worker. A winner is also selected from among the |
| methods GDB finds in the C++ source code. Next, the winning xmethod |
| worker and the winning C++ method are compared to select an overall |
| winner. In case of a tie between a xmethod worker and a C++ method, the |
| xmethod worker is selected as the winner. That is, if a winning xmethod |
| worker is found to be equivalent to the winning C++ method, then the |
| xmethod worker is treated as a replacement for the C++ method. GDB uses |
| the overall winner to invoke the method. If the winning xmethod worker |
| is the overall winner, then the corresponding xmethod is invoked via the |
| '__call__' method of the worker object. |
| |
| If one wants to implement an xmethod as a replacement for an existing |
| C++ method, then they have to implement an equivalent xmethod which has |
| exactly the same name and takes arguments of exactly the same type as |
| the C++ method. If the user wants to invoke the C++ method even though |
| a replacement xmethod is available for that method, then they can |
| disable the xmethod. |
| |
| *Note Xmethod API::, for API to implement xmethods in Python. *Note |
| Writing an Xmethod::, for implementing xmethods in Python. |
| |
| |
| File: gdb.info, Node: Xmethod API, Next: Writing an Xmethod, Prev: Xmethods In Python, Up: Python API |
| |
| 23.2.2.14 Xmethod API |
| ..................... |
| |
| The GDB Python API provides classes, interfaces and functions to |
| implement, register and manipulate xmethods. *Note Xmethods In |
| Python::. |
| |
| An xmethod matcher should be an instance of a class derived from |
| 'XMethodMatcher' defined in the module 'gdb.xmethod', or an object with |
| similar interface and attributes. An instance of 'XMethodMatcher' has |
| the following attributes: |
| |
| -- Variable: name |
| The name of the matcher. |
| |
| -- Variable: enabled |
| A boolean value indicating whether the matcher is enabled or |
| disabled. |
| |
| -- Variable: methods |
| A list of named methods managed by the matcher. Each object in the |
| list is an instance of the class 'XMethod' defined in the module |
| 'gdb.xmethod', or any object with the following attributes: |
| |
| 'name' |
| Name of the xmethod which should be unique for each xmethod |
| managed by the matcher. |
| |
| 'enabled' |
| A boolean value indicating whether the xmethod is enabled or |
| disabled. |
| |
| The class 'XMethod' is a convenience class with same attributes as |
| above along with the following constructor: |
| |
| -- Function: XMethod.__init__ (self, name) |
| Constructs an enabled xmethod with name NAME. |
| |
| The 'XMethodMatcher' class has the following methods: |
| |
| -- Function: XMethodMatcher.__init__ (self, name) |
| Constructs an enabled xmethod matcher with name NAME. The |
| 'methods' attribute is initialized to 'None'. |
| |
| -- Function: XMethodMatcher.match (self, class_type, method_name) |
| Derived classes should override this method. It should return a |
| xmethod worker object (or a sequence of xmethod worker objects) |
| matching the CLASS_TYPE and METHOD_NAME. CLASS_TYPE is a |
| 'gdb.Type' object, and METHOD_NAME is a string value. If the |
| matcher manages named methods as listed in its 'methods' attribute, |
| then only those worker objects whose corresponding entries in the |
| 'methods' list are enabled should be returned. |
| |
| An xmethod worker should be an instance of a class derived from |
| 'XMethodWorker' defined in the module 'gdb.xmethod', or support the |
| following interface: |
| |
| -- Function: XMethodWorker.get_arg_types (self) |
| This method returns a sequence of 'gdb.Type' objects corresponding |
| to the arguments that the xmethod takes. It can return an empty |
| sequence or 'None' if the xmethod does not take any arguments. If |
| the xmethod takes a single argument, then a single 'gdb.Type' |
| object corresponding to it can be returned. |
| |
| -- Function: XMethodWorker.get_result_type (self, *args) |
| This method returns a 'gdb.Type' object representing the type of |
| the result of invoking this xmethod. The ARGS argument is the same |
| tuple of arguments that would be passed to the '__call__' method of |
| this worker. |
| |
| -- Function: XMethodWorker.__call__ (self, *args) |
| This is the method which does the _work_ of the xmethod. The ARGS |
| arguments is the tuple of arguments to the xmethod. Each element |
| in this tuple is a gdb.Value object. The first element is always |
| the 'this' pointer value. |
| |
| For GDB to lookup xmethods, the xmethod matchers should be registered |
| using the following function defined in the module 'gdb.xmethod': |
| |
| -- Function: register_xmethod_matcher (locus, matcher, replace=False) |
| The 'matcher' is registered with 'locus', replacing an existing |
| matcher with the same name as 'matcher' if 'replace' is 'True'. |
| 'locus' can be a 'gdb.Objfile' object (*note Objfiles In Python::), |
| or a 'gdb.Progspace' object (*note Progspaces In Python::), or |
| 'None'. If it is 'None', then 'matcher' is registered globally. |
| |
| |
| File: gdb.info, Node: Writing an Xmethod, Next: Inferiors In Python, Prev: Xmethod API, Up: Python API |
| |
| 23.2.2.15 Writing an Xmethod |
| ............................ |
| |
| Implementing xmethods in Python will require implementing xmethod |
| matchers and xmethod workers (*note Xmethods In Python::). Consider the |
| following C++ class: |
| |
| class MyClass |
| { |
| public: |
| MyClass (int a) : a_(a) { } |
| |
| int geta (void) { return a_; } |
| int operator+ (int b); |
| |
| private: |
| int a_; |
| }; |
| |
| int |
| MyClass::operator+ (int b) |
| { |
| return a_ + b; |
| } |
| |
| Let us define two xmethods for the class 'MyClass', one replacing the |
| method 'geta', and another adding an overloaded flavor of 'operator+' |
| which takes a 'MyClass' argument (the C++ code above already has an |
| overloaded 'operator+' which takes an 'int' argument). The xmethod |
| matcher can be defined as follows: |
| |
| class MyClass_geta(gdb.xmethod.XMethod): |
| def __init__(self): |
| gdb.xmethod.XMethod.__init__(self, 'geta') |
| |
| def get_worker(self, method_name): |
| if method_name == 'geta': |
| return MyClassWorker_geta() |
| |
| |
| class MyClass_sum(gdb.xmethod.XMethod): |
| def __init__(self): |
| gdb.xmethod.XMethod.__init__(self, 'sum') |
| |
| def get_worker(self, method_name): |
| if method_name == 'operator+': |
| return MyClassWorker_plus() |
| |
| |
| class MyClassMatcher(gdb.xmethod.XMethodMatcher): |
| def __init__(self): |
| gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher') |
| # List of methods 'managed' by this matcher |
| self.methods = [MyClass_geta(), MyClass_sum()] |
| |
| def match(self, class_type, method_name): |
| if class_type.tag != 'MyClass': |
| return None |
| workers = [] |
| for method in self.methods: |
| if method.enabled: |
| worker = method.get_worker(method_name) |
| if worker: |
| workers.append(worker) |
| |
| return workers |
| |
| Notice that the 'match' method of 'MyClassMatcher' returns a worker |
| object of type 'MyClassWorker_geta' for the 'geta' method, and a worker |
| object of type 'MyClassWorker_plus' for the 'operator+' method. This is |
| done indirectly via helper classes derived from 'gdb.xmethod.XMethod'. |
| One does not need to use the 'methods' attribute in a matcher as it is |
| optional. However, if a matcher manages more than one xmethod, it is a |
| good practice to list the xmethods in the 'methods' attribute of the |
| matcher. This will then facilitate enabling and disabling individual |
| xmethods via the 'enable/disable' commands. Notice also that a worker |
| object is returned only if the corresponding entry in the 'methods' |
| attribute of the matcher is enabled. |
| |
| The implementation of the worker classes returned by the matcher |
| setup above is as follows: |
| |
| class MyClassWorker_geta(gdb.xmethod.XMethodWorker): |
| def get_arg_types(self): |
| return None |
| |
| def get_result_type(self, obj): |
| return gdb.lookup_type('int') |
| |
| def __call__(self, obj): |
| return obj['a_'] |
| |
| |
| class MyClassWorker_plus(gdb.xmethod.XMethodWorker): |
| def get_arg_types(self): |
| return gdb.lookup_type('MyClass') |
| |
| def get_result_type(self, obj): |
| return gdb.lookup_type('int') |
| |
| def __call__(self, obj, other): |
| return obj['a_'] + other['a_'] |
| |
| For GDB to actually lookup a xmethod, it has to be registered with |
| it. The matcher defined above is registered with GDB globally as |
| follows: |
| |
| gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher()) |
| |
| If an object 'obj' of type 'MyClass' is initialized in C++ code as |
| follows: |
| |
| MyClass obj(5); |
| |
| then, after loading the Python script defining the xmethod matchers and |
| workers into 'GDBN', invoking the method 'geta' or using the operator |
| '+' on 'obj' will invoke the xmethods defined above: |
| |
| (gdb) p obj.geta() |
| $1 = 5 |
| |
| (gdb) p obj + obj |
| $2 = 10 |
| |
| Consider another example with a C++ template class: |
| |
| template <class T> |
| class MyTemplate |
| { |
| public: |
| MyTemplate () : dsize_(10), data_ (new T [10]) { } |
| ~MyTemplate () { delete [] data_; } |
| |
| int footprint (void) |
| { |
| return sizeof (T) * dsize_ + sizeof (MyTemplate<T>); |
| } |
| |
| private: |
| int dsize_; |
| T *data_; |
| }; |
| |
| Let us implement an xmethod for the above class which serves as a |
| replacement for the 'footprint' method. The full code listing of the |
| xmethod workers and xmethod matchers is as follows: |
| |
| class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker): |
| def __init__(self, class_type): |
| self.class_type = class_type |
| |
| def get_arg_types(self): |
| return None |
| |
| def get_result_type(self): |
| return gdb.lookup_type('int') |
| |
| def __call__(self, obj): |
| return (self.class_type.sizeof + |
| obj['dsize_'] * |
| self.class_type.template_argument(0).sizeof) |
| |
| |
| class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher): |
| def __init__(self): |
| gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher') |
| |
| def match(self, class_type, method_name): |
| if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>', |
| class_type.tag) and |
| method_name == 'footprint'): |
| return MyTemplateWorker_footprint(class_type) |
| |
| Notice that, in this example, we have not used the 'methods' |
| attribute of the matcher as the matcher manages only one xmethod. The |
| user can enable/disable this xmethod by enabling/disabling the matcher |
| itself. |
| |
| |
| File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing an Xmethod, Up: Python API |
| |
| 23.2.2.16 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. |
| |
| -- Variable: Inferior.progspace |
| The inferior's program space. *Note Progspaces In Python::. |
| |
| 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.architecture () |
| Return the 'gdb.Architecture' (*note Architectures In Python::) for |
| this inferior. This represents the architecture of the inferior as |
| a whole. Some platforms can have multiple architectures in a |
| single address space, so this may not match the architecture of a |
| particular frame (*note Frames In Python::). |
| |
| -- Function: Inferior.read_memory (address, length) |
| Read LENGTH addressable memory units 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. In Python 3, the return value is |
| a 'memoryview' object. |
| |
| -- 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 addressable memory units 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. |
| |
| -- Function: Inferior.thread_from_handle (handle) |
| Return the thread object corresponding to HANDLE, a thread library |
| specific data structure such as 'pthread_t' for pthreads library |
| implementations. |
| |
| The function 'Inferior.thread_from_thread_handle' provides the same |
| functionality, but use of 'Inferior.thread_from_thread_handle' is |
| deprecated. |
| |
| |
| File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API |
| |
| 23.2.2.17 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. |
| |
| 'events.clear_objfiles' |
| Emits 'gdb.ClearObjFilesEvent' which indicates that the list of |
| object files for a program space has been reset. |
| 'gdb.ClearObjFilesEvent' has one attribute: |
| |
| -- Variable: ClearObjFilesEvent.progspace |
| A reference to the program space ('gdb.Progspace') whose |
| objfile list has been cleared. *Note Progspaces In Python::. |
| |
| 'events.inferior_call' |
| Emits events just before and after a function in the inferior is |
| called by GDB. Before an inferior call, this emits an event of |
| type 'gdb.InferiorCallPreEvent', and after an inferior call, this |
| emits an event of type 'gdb.InferiorCallPostEvent'. |
| |
| 'gdb.InferiorCallPreEvent' |
| Indicates that a function in the inferior is about to be |
| called. |
| |
| -- Variable: InferiorCallPreEvent.ptid |
| The thread in which the call will be run. |
| |
| -- Variable: InferiorCallPreEvent.address |
| The location of the function to be called. |
| |
| 'gdb.InferiorCallPostEvent' |
| Indicates that a function in the inferior has just been |
| called. |
| |
| -- Variable: InferiorCallPostEvent.ptid |
| The thread in which the call was run. |
| |
| -- Variable: InferiorCallPostEvent.address |
| The location of the function that was called. |
| |
| 'events.memory_changed' |
| Emits 'gdb.MemoryChangedEvent' which indicates that the memory of |
| the inferior has been modified by the GDB user, for instance via a |
| command like 'set *addr = value'. The event has the following |
| attributes: |
| |
| -- Variable: MemoryChangedEvent.address |
| The start address of the changed region. |
| |
| -- Variable: MemoryChangedEvent.length |
| Length in bytes of the changed region. |
| |
| 'events.register_changed' |
| Emits 'gdb.RegisterChangedEvent' which indicates that a register in |
| the inferior has been modified by the GDB user. |
| |
| -- Variable: RegisterChangedEvent.frame |
| A gdb.Frame object representing the frame in which the |
| register was modified. |
| -- Variable: RegisterChangedEvent.regnum |
| Denotes which register was modified. |
| |
| 'events.breakpoint_created' |
| This is emitted when a new breakpoint has been created. The |
| argument that is passed is the new 'gdb.Breakpoint' object. |
| |
| 'events.breakpoint_modified' |
| This is emitted when a breakpoint has been modified in some way. |
| The argument that is passed is the new 'gdb.Breakpoint' object. |
| |
| 'events.breakpoint_deleted' |
| This is emitted when a breakpoint has been deleted. The argument |
| that is passed is the 'gdb.Breakpoint' object. When this event is |
| emitted, the 'gdb.Breakpoint' object will already be in its invalid |
| state; that is, the 'is_valid' method will return 'False'. |
| |
| 'events.before_prompt' |
| This event carries no payload. It is emitted each time GDB |
| presents a prompt to the user. |
| |
| 'events.new_inferior' |
| This is emitted when a new inferior is created. Note that the |
| inferior is not necessarily running; in fact, it may not even have |
| an associated executable. |
| |
| The event is of type 'gdb.NewInferiorEvent'. This has a single |
| attribute: |
| |
| -- Variable: NewInferiorEvent.inferior |
| The new inferior, a 'gdb.Inferior' object. |
| |
| 'events.inferior_deleted' |
| This is emitted when an inferior has been deleted. Note that this |
| is not the same as process exit; it is notified when the inferior |
| itself is removed, say via 'remove-inferiors'. |
| |
| The event is of type 'gdb.InferiorDeletedEvent'. This has a single |
| attribute: |
| |
| -- Variable: NewInferiorEvent.inferior |
| The inferior that is being removed, a 'gdb.Inferior' object. |
| |
| 'events.new_thread' |
| This is emitted when GDB notices a new thread. The event is of |
| type 'gdb.NewThreadEvent', which extends 'gdb.ThreadEvent'. This |
| has a single attribute: |
| |
| -- Variable: NewThreadEvent.inferior_thread |
| The new thread. |
| |
| |
| File: gdb.info, Node: Threads In Python, Next: Recordings In Python, Prev: Events In Python, Up: Python API |
| |
| 23.2.2.18 Threads In Python |
| ........................... |
| |
| Python scripts can access information about, and manipulate inferior |
| threads controlled by GDB, via objects of the 'gdb.InferiorThread' |
| class. |
| |
| The following thread-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.selected_thread () |
| This function returns the thread object for the selected thread. |
| If there is no selected thread, this will return 'None'. |
| |
| To get the list of threads for an inferior, use the |
| 'Inferior.threads()' method. *Note Inferiors In Python:: |
| |
| 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 |
| The per-inferior number of the thread, as assigned by GDB. |
| |
| -- Variable: InferiorThread.global_num |
| The global ID of the thread, as assigned by GDB. You can use this |
| to make Python breakpoints thread-specific, for example (*note The |
| Breakpoint.thread attribute: python_breakpoint_thread.). |
| |
| -- 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. |
| |
| -- Variable: InferiorThread.inferior |
| The inferior this thread belongs to. This attribute is represented |
| as a 'gdb.Inferior' object. This attribute is not writable. |
| |
| 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. |
| |
| -- Function: InferiorThread.handle () |
| Return the thread object's handle, represented as a Python 'bytes' |
| object. A 'gdb.Value' representation of the handle may be |
| constructed via 'gdb.Value(bufobj, type)' where BUFOBJ is the |
| Python 'bytes' representation of the handle and TYPE is a |
| 'gdb.Type' for the handle type. |
| |
| |
| File: gdb.info, Node: Recordings In Python, Next: Commands In Python, Prev: Threads In Python, Up: Python API |
| |
| 23.2.2.19 Recordings In Python |
| .............................. |
| |
| The following recordings-related functions (*note Process Record and |
| Replay::) are available in the 'gdb' module: |
| |
| -- Function: gdb.start_recording ([method], [format]) |
| Start a recording using the given METHOD and FORMAT. If no FORMAT |
| is given, the default format for the recording method is used. If |
| no METHOD is given, the default method will be used. Returns a |
| 'gdb.Record' object on success. Throw an exception on failure. |
| |
| The following strings can be passed as METHOD: |
| |
| * '"full"' |
| * '"btrace"': Possible values for FORMAT: '"pt"', '"bts"' or |
| leave out for default format. |
| |
| -- Function: gdb.current_recording () |
| Access a currently running recording. Return a 'gdb.Record' object |
| on success. Return 'None' if no recording is currently active. |
| |
| -- Function: gdb.stop_recording () |
| Stop the current recording. Throw an exception if no recording is |
| currently active. All record objects become invalid after this |
| call. |
| |
| A 'gdb.Record' object has the following attributes: |
| |
| -- Variable: Record.method |
| A string with the current recording method, e.g. 'full' or |
| 'btrace'. |
| |
| -- Variable: Record.format |
| A string with the current recording format, e.g. 'bt', 'pts' or |
| 'None'. |
| |
| -- Variable: Record.begin |
| A method specific instruction object representing the first |
| instruction in this recording. |
| |
| -- Variable: Record.end |
| A method specific instruction object representing the current |
| instruction, that is not actually part of the recording. |
| |
| -- Variable: Record.replay_position |
| The instruction representing the current replay position. If there |
| is no replay active, this will be 'None'. |
| |
| -- Variable: Record.instruction_history |
| A list with all recorded instructions. |
| |
| -- Variable: Record.function_call_history |
| A list with all recorded function call segments. |
| |
| A 'gdb.Record' object has the following methods: |
| |
| -- Function: Record.goto (instruction) |
| Move the replay position to the given INSTRUCTION. |
| |
| The common 'gdb.Instruction' class that recording method specific |
| instruction objects inherit from, has the following attributes: |
| |
| -- Variable: Instruction.pc |
| An integer representing this instruction's address. |
| |
| -- Variable: Instruction.data |
| A buffer with the raw instruction data. In Python 3, the return |
| value is a 'memoryview' object. |
| |
| -- Variable: Instruction.decoded |
| A human readable string with the disassembled instruction. |
| |
| -- Variable: Instruction.size |
| The size of the instruction in bytes. |
| |
| Additionally 'gdb.RecordInstruction' has the following attributes: |
| |
| -- Variable: RecordInstruction.number |
| An integer identifying this instruction. 'number' corresponds to |
| the numbers seen in 'record instruction-history' (*note Process |
| Record and Replay::). |
| |
| -- Variable: RecordInstruction.sal |
| A 'gdb.Symtab_and_line' object representing the associated symtab |
| and line of this instruction. May be 'None' if no debug |
| information is available. |
| |
| -- Variable: RecordInstruction.is_speculative |
| A boolean indicating whether the instruction was executed |
| speculatively. |
| |
| If an error occured during recording or decoding a recording, this |
| error is represented by a 'gdb.RecordGap' object in the instruction |
| list. It has the following attributes: |
| |
| -- Variable: RecordGap.number |
| An integer identifying this gap. 'number' corresponds to the |
| numbers seen in 'record instruction-history' (*note Process Record |
| and Replay::). |
| |
| -- Variable: RecordGap.error_code |
| A numerical representation of the reason for the gap. The value is |
| specific to the current recording method. |
| |
| -- Variable: RecordGap.error_string |
| A human readable string with the reason for the gap. |
| |
| A 'gdb.RecordFunctionSegment' object has the following attributes: |
| |
| -- Variable: RecordFunctionSegment.number |
| An integer identifying this function segment. 'number' corresponds |
| to the numbers seen in 'record function-call-history' (*note |
| Process Record and Replay::). |
| |
| -- Variable: RecordFunctionSegment.symbol |
| A 'gdb.Symbol' object representing the associated symbol. May be |
| 'None' if no debug information is available. |
| |
| -- Variable: RecordFunctionSegment.level |
| An integer representing the function call's stack level. May be |
| 'None' if the function call is a gap. |
| |
| -- Variable: RecordFunctionSegment.instructions |
| A list of 'gdb.RecordInstruction' or 'gdb.RecordGap' objects |
| associated with this function call. |
| |
| -- Variable: RecordFunctionSegment.up |
| A 'gdb.RecordFunctionSegment' object representing the caller's |
| function segment. If the call has not been recorded, this will be |
| the function segment to which control returns. If neither the call |
| nor the return have been recorded, this will be 'None'. |
| |
| -- Variable: RecordFunctionSegment.prev |
| A 'gdb.RecordFunctionSegment' object representing the previous |
| segment of this function call. May be 'None'. |
| |
| -- Variable: RecordFunctionSegment.next |
| A 'gdb.RecordFunctionSegment' object representing the next segment |
| of this function call. May be 'None'. |
| |
| The following example demonstrates the usage of these objects and |
| functions to create a function that will rewind a record to the last |
| time a function in a different file was executed. This would typically |
| be used to track the execution of user provided callback functions in a |
| library which typically are not visible in a back trace. |
| |
| def bringback (): |
| rec = gdb.current_recording () |
| if not rec: |
| return |
| |
| insn = rec.instruction_history |
| if len (insn) == 0: |
| return |
| |
| try: |
| position = insn.index (rec.replay_position) |
| except: |
| position = -1 |
| try: |
| filename = insn[position].sal.symtab.fullname () |
| except: |
| filename = None |
| |
| for i in reversed (insn[:position]): |
| try: |
| current = i.sal.symtab.fullname () |
| except: |
| current = None |
| |
| if filename == current: |
| continue |
| |
| rec.goto (i) |
| return |
| |
| Another possible application is to write a function that counts the |
| number of code executions in a given line range. This line range can |
| contain parts of functions or span across several functions and is not |
| limited to be contiguous. |
| |
| def countrange (filename, linerange): |
| count = 0 |
| |
| def filter_only (file_name): |
| for call in gdb.current_recording ().function_call_history: |
| try: |
| if file_name in call.symbol.symtab.fullname (): |
| yield call |
| except: |
| pass |
| |
| for c in filter_only (filename): |
| for i in c.instructions: |
| try: |
| if i.sal.line in linerange: |
| count += 1 |
| break; |
| except: |
| pass |
| |
| return count |
| |
| |
| File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Recordings In Python, Up: Python API |
| |
| 23.2.2.20 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, while 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. |
| |
| 'gdb.COMPLETE_EXPRESSION' |
| This constant means that completion should be done on expressions. |
| Often this means completing on symbol names, but some language |
| parsers also have support for completing on field names. |
| |
| 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.21 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 may be implemented in any 'Parameter' |
| class. These are: |
| |
| -- Function: Parameter.get_set_string (self) |
| If this method exists, GDB will call it 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. If |
| the returned string is not empty, GDB will present it to the user. |
| |
| If this method raises the 'gdb.GdbError' exception (*note Exception |
| Handling::), then GDB will print the exception's string and the |
| 'set' command will fail. Note, however, that the 'value' attribute |
| will not be reset in this case. So, if your parameter must |
| validate values, it should store the old value internally and reset |
| the exposed value, like so: |
| |
| class ExampleParam (gdb.Parameter): |
| def __init__ (self, name): |
| super (ExampleParam, self).__init__ (name, |
| gdb.COMMAND_DATA, |
| gdb.PARAM_BOOLEAN) |
| self.value = True |
| self.saved_value = True |
| def validate(self): |
| return False |
| def get_set_string (self): |
| if not self.validate(): |
| self.value = self.saved_value |
| raise gdb.GdbError('Failed to validate') |
| self.saved_value = self.value |
| |
| -- 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_ZUINTEGER' |
| The value is an unsigned integer. This is like 'PARAM_INTEGER', |
| except 0 is interpreted as itself, and the value cannot be |
| negative. |
| |
| 'gdb.PARAM_ZUINTEGER_UNLIMITED' |
| The value is a signed integer. This is like 'PARAM_ZUINTEGER', |
| except the special value -1 should be interpreted to mean |
| "unlimited". Other negative values are not allowed. |
| |
| '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.22 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. |
| |
| Now you can use the function in an expression: |
| |
| (gdb) print $greet("Bob") |
| $1 = "Hello, Bob!" |
| |
| |
| File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API |
| |
| 23.2.2.23 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::. This is identical to |
| 'gdb.selected_inferior().progspace' (*note Inferiors In Python::) |
| and is included for historical compatibility. |
| |
| -- 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. |
| |
| -- Variable: Progspace.type_printers |
| The 'type_printers' attribute is a list of type printer objects. |
| *Note Type Printing API::, for more information. |
| |
| -- Variable: Progspace.frame_filters |
| The 'frame_filters' attribute is a dictionary of frame filter |
| objects. *Note Frame Filter API::, for more information. |
| |
| A program space has the following methods: |
| |
| -- Function: Progspace.block_for_pc (pc) |
| Return the innermost 'gdb.Block' containing the given PC value. If |
| the block cannot be found for the PC value specified, the function |
| will return 'None'. |
| |
| -- Function: Progspace.find_pc_line (pc) |
| Return the 'gdb.Symtab_and_line' object corresponding to the PC |
| value. *Note Symbol Tables In Python::. If an invalid value of PC |
| is passed as an argument, then the 'symtab' and 'line' attributes |
| of the returned 'gdb.Symtab_and_line' object will be 'None' and 0 |
| respectively. |
| |
| -- Function: Progspace.is_valid () |
| Returns 'True' if the 'gdb.Progspace' object is valid, 'False' if |
| not. A 'gdb.Progspace' object can become invalid if the program |
| space file it refers to is not referenced by any inferior. All |
| other 'gdb.Progspace' methods will throw an exception if it is |
| invalid at the time the method is called. |
| |
| -- Function: Progspace.objfiles () |
| Return a sequence of all the objfiles referenced by this program |
| space. *Note Objfiles In Python::. |
| |
| -- Function: Progspace.solib_name (address) |
| Return the name of the shared library holding the given ADDRESS as |
| a string, or 'None'. |
| |
| One may add arbitrary attributes to 'gdb.Progspace' objects in the |
| usual Python way. This is useful if, for example, one needs to do some |
| extra record keeping associated with the program space. |
| |
| In this contrived example, we want to perform some processing when an |
| objfile with a certain symbol is loaded, but we only want to do this |
| once because it is expensive. To achieve this we record the results |
| with the program space because we can't predict when the desired objfile |
| will be loaded. |
| |
| (gdb) python |
| def clear_objfiles_handler(event): |
| event.progspace.expensive_computation = None |
| def expensive(symbol): |
| """A mock routine to perform an "expensive" computation on symbol.""" |
| print "Computing the answer to the ultimate question ..." |
| return 42 |
| def new_objfile_handler(event): |
| objfile = event.new_objfile |
| progspace = objfile.progspace |
| if not hasattr(progspace, 'expensive_computation') or \ |
| progspace.expensive_computation is None: |
| # We use 'main' for the symbol to keep the example simple. |
| # Note: There's no current way to constrain the lookup |
| # to one objfile. |
| symbol = gdb.lookup_global_symbol('main') |
| if symbol is not None: |
| progspace.expensive_computation = expensive(symbol) |
| gdb.events.clear_objfiles.connect(clear_objfiles_handler) |
| gdb.events.new_objfile.connect(new_objfile_handler) |
| end |
| (gdb) file /tmp/hello |
| Reading symbols from /tmp/hello...done. |
| Computing the answer to the ultimate question ... |
| (gdb) python print gdb.current_progspace().expensive_computation |
| 42 |
| (gdb) run |
| Starting program: /tmp/hello |
| Hello. |
| [Inferior 1 (process 4242) exited normally] |
| |
| |
| File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API |
| |
| 23.2.2.24 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 objfiles referenced by the current program |
| space. *Note Objfiles In Python::, and *note Progspaces In |
| Python::. This is identical to |
| 'gdb.selected_inferior().progspace.objfiles()' and is included for |
| historical compatibility. |
| |
| -- Function: gdb.lookup_objfile (name [, by_build_id]) |
| Look up NAME, a file name or build ID, in the list of objfiles for |
| the current program space (*note Progspaces In Python::). If the |
| objfile is not found throw the Python 'ValueError' exception. |
| |
| If NAME is a relative file name, then it will match any source file |
| name with the same trailing components. For example, if NAME is |
| 'gcc/expr.c', then it will match source file name of |
| '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or |
| '/build/trunk/gcc/x-expr.c'. |
| |
| If BY_BUILD_ID is provided and is 'True' then NAME is the build ID |
| of the objfile. Otherwise, NAME is a file name. 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)Options. |
| |
| Each objfile is represented by an instance of the 'gdb.Objfile' |
| class. |
| |
| -- Variable: Objfile.filename |
| The file name of the objfile as a string, with symbolic links |
| resolved. |
| |
| The value is 'None' if the objfile is no longer valid. See the |
| 'gdb.Objfile.is_valid' method, described below. |
| |
| -- Variable: Objfile.username |
| The file name of the objfile as specified by the user as a string. |
| |
| The value is 'None' if the objfile is no longer valid. See the |
| 'gdb.Objfile.is_valid' method, described below. |
| |
| -- Variable: Objfile.owner |
| For separate debug info objfiles this is the corresponding |
| 'gdb.Objfile' object that debug info is being provided for. |
| Otherwise this is 'None'. Separate debug info objfiles are added |
| with the 'gdb.Objfile.add_separate_debug_file' method, described |
| below. |
| |
| -- Variable: Objfile.build_id |
| The build ID of the objfile as a string. If the objfile does not |
| have a build ID then the value is 'None'. |
| |
| 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)Options. |
| |
| -- Variable: Objfile.progspace |
| The containing program space of the objfile as a 'gdb.Progspace' |
| object. *Note Progspaces In Python::. |
| |
| -- 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. |
| |
| -- Variable: Objfile.type_printers |
| The 'type_printers' attribute is a list of type printer objects. |
| *Note Type Printing API::, for more information. |
| |
| -- Variable: Objfile.frame_filters |
| The 'frame_filters' attribute is a dictionary of frame filter |
| objects. *Note Frame Filter API::, for more information. |
| |
| One may add arbitrary attributes to 'gdb.Objfile' objects in the |
| usual Python way. This is useful if, for example, one needs to do some |
| extra record keeping associated with the objfile. |
| |
| In this contrived example we record the time when GDB loaded the |
| objfile. |
| |
| (gdb) python |
| import datetime |
| def new_objfile_handler(event): |
| # Set the time_loaded attribute of the new objfile. |
| event.new_objfile.time_loaded = datetime.datetime.today() |
| gdb.events.new_objfile.connect(new_objfile_handler) |
| end |
| (gdb) file ./hello |
| Reading symbols from ./hello...done. |
| (gdb) python print gdb.objfiles()[0].time_loaded |
| 2014-10-09 11:41:36.770345 |
| |
| 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. |
| |
| -- Function: Objfile.add_separate_debug_file (file) |
| Add FILE to the list of files that GDB will search for debug |
| information for the objfile. This is useful when the debug info |
| has been removed from the program and stored in a separate file. |
| GDB has built-in support for finding separate debug info files |
| (*note Separate Debug Files::), but if the file doesn't live in one |
| of the standard places that GDB searches then this function can be |
| used to add a debug info file from a different place. |
| |
| -- Function: Objfile.lookup_global_symbol (name [, domain]) |
| Search for a global symbol named NAME in this objfile. Optionally, |
| the search scope can be restricted with the DOMAIN argument. The |
| DOMAIN argument must be a domain constant defined in the 'gdb' |
| module and described in *note Symbols In Python::. This function |
| is similar to 'gdb.lookup_global_symbol', except that the search is |
| limited to this objfile. |
| |
| The result is a 'gdb.Symbol' object or 'None' if the symbol is not |
| found. |
| |
| -- Function: Objfile.lookup_static_symbol (name [, domain]) |
| Like 'Objfile.lookup_global_symbol', but searches for a global |
| symbol with static linkage named NAME in this objfile. |
| |
| |
| File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API |
| |
| 23.2.2.25 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). |
| |
| -- Function: gdb.invalidate_cached_frames |
| GDB internally keeps a cache of the frames that have been unwound. |
| This function invalidates this cache. |
| |
| This function should not generally be called by ordinary Python |
| code. It is documented for the sake of completeness. |
| |
| 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.architecture () |
| Returns the 'gdb.Architecture' object corresponding to the frame's |
| architecture. *Note Architectures In Python::. |
| |
| -- 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. This |
| is no longer used by GDB, and is kept only for backward |
| compatibility. |
| |
| '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_MEMORY_ERROR' |
| The frame unwinder caused an error while trying to access |
| memory. |
| |
| '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::. If the |
| frame does not have a block - for example, if there is no debugging |
| information for the code in question - then this will throw an |
| exception. |
| |
| -- 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_register (register) |
| Return the value of REGISTER in this frame. The REGISTER argument |
| must be a string (e.g., ''sp'' or ''rax''). Returns a 'Gdb.Value' |
| object. Throws an exception if REGISTER does not exist. |
| |
| -- 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). The VARIABLE |
| argument 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.26 Accessing blocks from Python |
| ...................................... |
| |
| In GDB, symbols are stored in blocks. A block corresponds roughly to a |
| scope in the source code. Blocks are organized hierarchically, and are |
| represented individually in Python as a 'gdb.Block'. Blocks rely on |
| debugging information being available. |
| |
| A frame has a block. Please see *note Frames In Python::, for a more |
| in-depth discussion of frames. |
| |
| The outermost block is known as the "global block". The global block |
| typically holds public global variables and functions. |
| |
| The block nested just inside the global block is the "static block". |
| The static block typically holds file-scoped variables and functions. |
| |
| GDB provides a method to get a block's superblock, but there is |
| currently no way to examine the sub-blocks of a block, or to iterate |
| over all the blocks in a symbol table (*note Symbol Tables In Python::). |
| |
| Here is a short example that should help explain blocks: |
| |
| /* This is in the global block. */ |
| int global; |
| |
| /* This is in the static block. */ |
| static int file_scope; |
| |
| /* 'function' is in the global block, and 'argument' is |
| in a block nested inside of 'function'. */ |
| int function (int argument) |
| { |
| /* 'local' is in a block inside 'function'. It may or may |
| not be in the same block as 'argument'. */ |
| int local; |
| |
| { |
| /* 'inner' is in a block whose superblock is the one holding |
| 'local'. */ |
| int inner; |
| |
| /* If this call is expanded by the compiler, you may see |
| a nested block here whose function is 'inline_function' |
| and whose superblock is the one holding 'inner'. */ |
| inline_function (); |
| } |
| } |
| |
| 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. You can also use Python's "dictionary |
| syntax" to access variables in this block, e.g.: |
| |
| symbol = some_block['variable'] # symbol is of type gdb.Symbol |
| |
| The following block-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.block_for_pc (pc) |
| Return the innermost 'gdb.Block' containing the given PC value. If |
| the block cannot be found for the PC value specified, the function |
| will return 'None'. This is identical to |
| 'gdb.current_progspace().block_for_pc(pc)' and is included for |
| historical compatibility. |
| |
| 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 |
| One past the last address that appears in 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. |
| |
| For ordinary function blocks, the superblock is the static block. |
| However, you should note that it is possible for a function block |
| to have a superblock that is not the static block - for instance |
| this happens for an inlined function. |
| |
| -- 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.27 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. |
| |
| -- Function: gdb.lookup_static_symbol (name [, domain]) |
| This function searches for a global symbol with static linkage 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. |
| |
| Note that this function will not find function-scoped static |
| variables. To look up such variables, iterate over the variables |
| of the function's 'gdb.Block' and check that 'block.addr_class' is |
| 'gdb.SYMBOL_LOC_STATIC'. |
| |
| There can be multiple global symbols with static linkage with the |
| same name. This function will only return the first matching |
| symbol that it finds. Which symbol is found depends on where GDB |
| is currently stopped, as GDB will first search for matching symbols |
| in the current object file, and then search all other object files. |
| If the application is not yet running then GDB will search all |
| object files in the order they appear in the debug information. |
| |
| -- Function: gdb.lookup_static_symbols (name [, domain]) |
| Similar to 'gdb.lookup_static_symbol', this function searches for |
| global symbols with static linkage by name, and optionally |
| restricted by the domain argument. However, this function returns |
| a list of all matching symbols found, not just the first one. |
| |
| 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 list of 'gdb.Symbol' objects which could be empty |
| if no matching symbols were found. |
| |
| Note that this function will not find function-scoped static |
| variables. To look up such variables, iterate over the variables |
| of the function's 'gdb.Block' and check that 'block.addr_class' is |
| 'gdb.SYMBOL_LOC_STATIC'. |
| |
| 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_MODULE_DOMAIN' |
| This domain contains names of Fortran module types. |
| |
| 'gdb.SYMBOL_COMMON_BLOCK_DOMAIN' |
| This domain contains names of Fortran common blocks. |
| |
| 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. |
| |
| 'gdb.SYMBOL_LOC_COMPUTED' |
| The value's address is a symbol. This is only used for Fortran |
| common blocks. |
| |
| |
| File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API |
| |
| 23.2.2.28 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. |
| |
| -- Variable: Symtab.producer |
| The name and possibly version number of the program that compiled |
| the code in the symbol table. The contents of this string is up to |
| the compiler. If no producer information is available then 'None' |
| is returned. This attribute is not writable. |
| |
| A 'gdb.Symtab' object has the following methods: |
| |
| -- Function: Symtab.is_valid () |
| Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not. |
| A 'gdb.Symtab' object can become invalid if the symbol table it |
| refers to does not exist in GDB any longer. All other 'gdb.Symtab' |
| methods will throw an exception if it is invalid at the time the |
| method is called. |
| |
| -- Function: Symtab.fullname () |
| Return the symbol table's source absolute file name. |
| |
| -- Function: Symtab.global_block () |
| Return the global block of the underlying symbol table. *Note |
| Blocks In Python::. |
| |
| -- Function: Symtab.static_block () |
| Return the static block of the underlying symbol table. *Note |
| Blocks In Python::. |
| |
| -- Function: Symtab.linetable () |
| Return the line table associated with the symbol table. *Note Line |
| Tables In Python::. |
| |
| |
| File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API |
| |
| 23.2.2.29 Manipulating line tables using Python |
| ............................................... |
| |
| Python code can request and inspect line table information from a symbol |
| table that is loaded in GDB. A line table is a mapping of source lines |
| to their executable locations in memory. To acquire the line table |
| information for a particular symbol table, use the 'linetable' function |
| (*note Symbol Tables In Python::). |
| |
| A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry' |
| objects that correspond to the source line and address for each line |
| table entry. 'LineTableEntry' objects have the following attributes: |
| |
| -- Variable: LineTableEntry.line |
| The source line number for this line table entry. This number |
| corresponds to the actual line of source. This attribute is not |
| writable. |
| |
| -- Variable: LineTableEntry.pc |
| The address that is associated with the line table entry where the |
| executable code for that source line resides in memory. This |
| attribute is not writable. |
| |
| As there can be multiple addresses for a single source line, you may |
| receive multiple 'LineTableEntry' objects with matching 'line' |
| attributes, but with different 'pc' attributes. The iterator is sorted |
| in ascending 'pc' order. Here is a small example illustrating iterating |
| over a line table. |
| |
| symtab = gdb.selected_frame().find_sal().symtab |
| linetable = symtab.linetable() |
| for line in linetable: |
| print "Line: "+str(line.line)+" Address: "+hex(line.pc) |
| |
| This will have the following output: |
| |
| Line: 33 Address: 0x4005c8L |
| Line: 37 Address: 0x4005caL |
| Line: 39 Address: 0x4005d2L |
| Line: 40 Address: 0x4005f8L |
| Line: 42 Address: 0x4005ffL |
| Line: 44 Address: 0x400608L |
| Line: 42 Address: 0x40060cL |
| Line: 45 Address: 0x400615L |
| |
| In addition to being able to iterate over a 'LineTable', it also has |
| the following direct access methods: |
| |
| -- Function: LineTable.line (line) |
| Return a Python 'Tuple' of 'LineTableEntry' objects for any entries |
| in the line table for the given LINE, which specifies the source |
| code line. If there are no entries for that source code LINE, the |
| Python 'None' is returned. |
| |
| -- Function: LineTable.has_line (line) |
| Return a Python 'Boolean' indicating whether there is an entry in |
| the line table for this source line. Return 'True' if an entry is |
| found, or 'False' if not. |
| |
| -- Function: LineTable.source_lines () |
| Return a Python 'List' of the source line numbers in the symbol |
| table. Only lines with executable code locations are returned. |
| The contents of the 'List' will just be the source line entries |
| represented as Python 'Long' values. |
| |
| |
| File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API |
| |
| 23.2.2.30 Manipulating breakpoints using Python |
| ............................................... |
| |
| Python code can manipulate breakpoints via the 'gdb.Breakpoint' class. |
| |
| A breakpoint can be created using one of the two forms of the |
| 'gdb.Breakpoint' constructor. The first one accepts a string like one |
| would pass to the 'break' (*note Setting Breakpoints: Set Breaks.) and |
| 'watch' (*note Setting Watchpoints: Set Watchpoints.) commands, and can |
| be used to create both breakpoints and watchpoints. The second accepts |
| separate Python arguments similar to *note Explicit Locations::, and can |
| only be used to create breakpoints. |
| |
| -- Function: Breakpoint.__init__ (spec [, type ][, wp_class ][, |
| internal ][, temporary ][, qualified ]) |
| Create a new breakpoint according to SPEC, which is a string naming |
| the location of a breakpoint, or an expression that defines a |
| watchpoint. The string should describe a location in a format |
| recognized by the 'break' command (*note Setting Breakpoints: Set |
| Breaks.) or, in the case of a watchpoint, by the 'watch' command |
| (*note Setting Watchpoints: Set Watchpoints.). |
| |
| The optional TYPE argument specifies the type of the breakpoint to |
| create, as defined below. |
| |
| The optional WP_CLASS argument defines the class of watchpoint to |
| create, if TYPE is 'gdb.BP_WATCHPOINT'. If WP_CLASS is omitted, it |
| defaults to 'gdb.WP_WRITE'. |
| |
| 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 TEMPORARY argument makes the breakpoint a temporary |
| breakpoint. Temporary breakpoints are deleted after they have been |
| hit. Any further access to the Python breakpoint after it has been |
| hit will result in a runtime error (as that breakpoint has now been |
| automatically deleted). |
| |
| The optional QUALIFIED argument is a boolean that allows |
| interpreting the function passed in 'spec' as a fully-qualified |
| name. It is equivalent to 'break''s '-qualified' flag (*note |
| Linespec Locations:: and *note Explicit Locations::). |
| |
| -- Function: Breakpoint.__init__ ([ source ][, function ][, label ][, |
| line ], ][ internal ][, temporary ][, qualified ]) |
| This second form of creating a new breakpoint specifies the |
| explicit location (*note Explicit Locations::) using keywords. The |
| new breakpoint will be created in the specified source file SOURCE, |
| at the specified FUNCTION, LABEL and LINE. |
| |
| INTERNAL, TEMPORARY and QUALIFIED have the same usage as explained |
| previously. |
| |
| 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. |
| |
| 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.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 in 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 |
| |
| -- 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. You can use it to enable |
| or disable the breakpoint. |
| |
| -- 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.pending |
| This attribute is 'True' if the breakpoint is pending, and 'False' |
| otherwise. *Note Set Breaks::. This attribute is read-only. |
| |
| -- Variable: Breakpoint.thread |
| If the breakpoint is thread-specific, this attribute holds the |
| thread's global 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. |
| |
| -- Variable: Breakpoint.temporary |
| This attribute indicates whether the breakpoint was created as a |
| temporary breakpoint. Temporary breakpoints are automatically |
| deleted after that breakpoint has been hit. Access to this |
| attribute, and all other attributes and functions other than the |
| 'is_valid' function, will result in an error after the breakpoint |
| has been hit (as it has been automatically deleted). This |
| attribute is not writable. |
| |
| -- Variable: Breakpoint.hit_count |
| This attribute holds the hit count for the breakpoint, an integer. |
| This attribute is writable, but currently it can only be set to |
| zero. |
| |
| -- Variable: Breakpoint.location |
| This attribute holds the location of the breakpoint, as specified |
| by the user. It is a string. If the breakpoint does not have a |
| location (that is, it is a watchpoint) the attribute's value is |
| 'None'. This attribute is not writable. |
| |
| -- Variable: Breakpoint.expression |
| This attribute holds a breakpoint expression, as specified by the |
| user. It is a string. If the breakpoint does not have an |
| expression (the breakpoint is not a watchpoint) the attribute's |
| value is 'None'. This attribute is not writable. |
| |
| -- Variable: Breakpoint.condition |
| This attribute holds the condition of the breakpoint, as specified |
| by the user. It is a string. If there is no condition, this |
| attribute's value is 'None'. This attribute is writable. |
| |
| -- Variable: Breakpoint.commands |
| This attribute holds the commands attached to the breakpoint. If |
| there are commands, this attribute's value is a string holding all |
| the commands, separated by newlines. If there are no commands, |
| this attribute is 'None'. This attribute is writable. |
| |
| |
| File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API |
| |
| 23.2.2.31 Finish Breakpoints |
| ............................ |
| |
| A finish breakpoint is a temporary breakpoint set at the return address |
| of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint' |
| extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled |
| and deleted when the execution will run out of the breakpoint scope |
| (i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered). |
| Finish breakpoints are thread specific and must be create with the right |
| thread selected. |
| |
| -- Function: FinishBreakpoint.__init__ ([frame] [, internal]) |
| Create a finish breakpoint at the return address of the 'gdb.Frame' |
| object FRAME. If FRAME is not provided, this defaults to the |
| newest frame. The optional INTERNAL argument allows the breakpoint |
| to become invisible to the user. *Note Breakpoints In Python::, |
| for further details about this argument. |
| |
| -- Function: FinishBreakpoint.out_of_scope (self) |
| In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return' |
| command, ...), a function may not properly terminate, and thus |
| never hit the finish breakpoint. When GDB notices such a |
| situation, the 'out_of_scope' callback will be triggered. |
| |
| You may want to sub-class 'gdb.FinishBreakpoint' and override this |
| method: |
| |
| class MyFinishBreakpoint (gdb.FinishBreakpoint) |
| def stop (self): |
| print "normal finish" |
| return True |
| |
| def out_of_scope (): |
| print "abnormal finish" |
| |
| -- Variable: FinishBreakpoint.return_value |
| When GDB is stopped at a finish breakpoint and the frame used to |
| build the 'gdb.FinishBreakpoint' object had debug symbols, this |
| attribute will contain a 'gdb.Value' object corresponding to the |
| return value of the function. The value will be 'None' if the |
| function return type is 'void' or if the return value was not |
| computable. This attribute is not writable. |
| |
| |
| File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API |
| |
| 23.2.2.32 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 is a pointer or array 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: Architectures In Python, Prev: Lazy Strings In Python, Up: Python API |
| |
| 23.2.2.33 Python representation of architectures |
| ................................................ |
| |
| GDB uses architecture specific parameters and artifacts in a number of |
| its various computations. An architecture is represented by an instance |
| of the 'gdb.Architecture' class. |
| |
| A 'gdb.Architecture' class has the following methods: |
| |
| -- Function: Architecture.name () |
| Return the name (string value) of the architecture. |
| |
| -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]]) |
| Return a list of disassembled instructions starting from the memory |
| address START_PC. The optional arguments END_PC and COUNT |
| determine the number of instructions in the returned list. If both |
| the optional arguments END_PC and COUNT are specified, then a list |
| of at most COUNT disassembled instructions whose start address |
| falls in the closed memory address interval from START_PC to END_PC |
| are returned. If END_PC is not specified, but COUNT is specified, |
| then COUNT number of instructions starting from the address |
| START_PC are returned. If COUNT is not specified but END_PC is |
| specified, then all instructions whose start address falls in the |
| closed memory address interval from START_PC to END_PC are |
| returned. If neither END_PC nor COUNT are specified, then a single |
| instruction at START_PC is returned. For all of these cases, each |
| element of the returned list is a Python 'dict' with the following |
| string keys: |
| |
| 'addr' |
| The value corresponding to this key is a Python long integer |
| capturing the memory address of the instruction. |
| |
| 'asm' |
| The value corresponding to this key is a string value which |
| represents the instruction with assembly language mnemonics. |
| The assembly language flavor used is the same as that |
| specified by the current CLI variable 'disassembly-flavor'. |
| *Note Machine Code::. |
| |
| 'length' |
| The value corresponding to this key is the length (integer |
| value) of the instruction in bytes. |
| |
| |
| 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' and |
| '.debug_gdb_scripts' section. *Note Auto-loading extensions::. |
| |
| 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 either not found (*note |
| dotdebug_gdb_scripts section::) or were not auto-loaded due to |
| 'auto-load safe-path' rejection (*note Auto-loading::). 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 or script, 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 and frame-filters. |
| |
| |
| File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python |
| |
| 23.2.4 Python modules |
| --------------------- |
| |
| GDB comes with several modules to assist writing Python code. |
| |
| * Menu: |
| |
| * gdb.printing:: Building and registering pretty-printers. |
| * gdb.types:: Utilities for working with types. |
| * gdb.prompt:: Utilities for prompt value substitution. |
| |
| |
| File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules |
| |
| 23.2.4.1 gdb.printing |
| ..................... |
| |
| This module provides a collection of utilities for working with |
| pretty-printers. |
| |
| 'PrettyPrinter (NAME, SUBPRINTERS=None)' |
| This class specifies the API that makes 'info pretty-printer', |
| 'enable pretty-printer' and 'disable pretty-printer' work. |
| Pretty-printers should generally inherit from this class. |
| |
| 'SubPrettyPrinter (NAME)' |
| For printers that handle multiple types, this class specifies the |
| corresponding API for the subprinters. |
| |
| 'RegexpCollectionPrettyPrinter (NAME)' |
| Utility class for handling multiple printers, all recognized via |
| regular expressions. *Note Writing a Pretty-Printer::, for an |
| example. |
| |
| 'FlagEnumerationPrinter (NAME)' |
| A pretty-printer which handles printing of 'enum' values. Unlike |
| GDB's built-in 'enum' printing, this printer attempts to work |
| properly when there is some overlap between the enumeration |
| constants. The argument NAME is the name of the printer and also |
| the name of the 'enum' type to look up. |
| |
| 'register_pretty_printer (OBJ, PRINTER, REPLACE=False)' |
| Register PRINTER with the pretty-printer list of OBJ. If REPLACE |
| is 'True' then any existing copy of the printer is replaced. |
| Otherwise a 'RuntimeError' exception is raised if a printer with |
| the same name already exists. |
| |
| |
| File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules |
| |
| 23.2.4.2 gdb.types |
| .................. |
| |
| This module provides a collection of utilities for working with |
| 'gdb.Type' objects. |
| |
| 'get_basic_type (TYPE)' |
| Return TYPE with const and volatile qualifiers stripped, and with |
| typedefs and C++ references converted to the underlying type. |
| |
| C++ example: |
| |
| typedef const int const_int; |
| const_int foo (3); |
| const_int& foo_ref (foo); |
| int main () { return 0; } |
| |
| Then in gdb: |
| |
| (gdb) start |
| (gdb) python import gdb.types |
| (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") |
| (gdb) python print gdb.types.get_basic_type(foo_ref.type) |
| int |
| |
| 'has_field (TYPE, FIELD)' |
| Return 'True' if TYPE, assumed to be a type with fields (e.g., a |
| structure or union), has field FIELD. |
| |
| 'make_enum_dict (ENUM_TYPE)' |
| Return a Python 'dictionary' type produced from ENUM_TYPE. |
| |
| 'deep_items (TYPE)' |
| Returns a Python iterator similar to the standard |
| 'gdb.Type.iteritems' method, except that the iterator returned by |
| 'deep_items' will recursively traverse anonymous struct or union |
| fields. For example: |
| |
| struct A |
| { |
| int a; |
| union { |
| int b0; |
| int b1; |
| }; |
| }; |
| |
| Then in GDB: |
| (gdb) python import gdb.types |
| (gdb) python struct_a = gdb.lookup_type("struct A") |
| (gdb) python print struct_a.keys () |
| {['a', '']} |
| (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] |
| {['a', 'b0', 'b1']} |
| |
| 'get_type_recognizers ()' |
| Return a list of the enabled type recognizers for the current |
| context. This is called by GDB during the type-printing process |
| (*note Type Printing API::). |
| |
| 'apply_type_recognizers (recognizers, type_obj)' |
| Apply the type recognizers, RECOGNIZERS, to the type object |
| TYPE_OBJ. If any recognizer returns a string, return that string. |
| Otherwise, return 'None'. This is called by GDB during the |
| type-printing process (*note Type Printing API::). |
| |
| 'register_type_printer (locus, printer)' |
| This is a convenience function to register a type printer PRINTER. |
| The printer must implement the type printer protocol. The LOCUS |
| argument is either a 'gdb.Objfile', in which case the printer is |
| registered with that objfile; a 'gdb.Progspace', in which case the |
| printer is registered with that progspace; or 'None', in which case |
| the printer is registered globally. |
| |
| 'TypePrinter' |
| This is a base class that implements the type printer protocol. |
| Type printers are encouraged, but not required, to derive from this |
| class. It defines a constructor: |
| |
| -- Method on TypePrinter: __init__ (self, name) |
| Initialize the type printer with the given name. The new |
| printer starts in the enabled state. |
| |
| |
| File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules |
| |
| 23.2.4.3 gdb.prompt |
| ................... |
| |
| This module provides a method for prompt value-substitution. |
| |
| 'substitute_prompt (STRING)' |
| Return STRING with escape sequences substituted by values. Some |
| escape sequences take arguments. You can specify arguments inside |
| "{}" immediately following the escape sequence. |
| |
| The escape sequences you can pass to this function are: |
| |
| '\\' |
| Substitute a backslash. |
| '\e' |
| Substitute an ESC character. |
| '\f' |
| Substitute the selected frame; an argument names a frame |
| parameter. |
| '\n' |
| Substitute a newline. |
| '\p' |
| Substitute a parameter's value; the argument names the |
| parameter. |
| '\r' |
| Substitute a carriage return. |
| '\t' |
| Substitute the selected thread; an argument names a thread |
| parameter. |
| '\v' |
| Substitute the version of GDB. |
| '\w' |
| Substitute the current working directory. |
| '\[' |
| Begin a sequence of non-printing characters. These sequences |
| are typically used with the ESC character, and are not counted |
| in the string length. Example: "\[\e[0;34m\](gdb)\[\e[0m\]" |
| will return a blue-colored "(gdb)" prompt where the length is |
| five. |
| '\]' |
| End a sequence of non-printing characters. |
| |
| For example: |
| |
| substitute_prompt ("frame: \f, args: \p{print frame-arguments}") |
| |
| will return the string: |
| |
| "frame: main, args: scalars" |
| |
| |
| File: gdb.info, Node: Guile, Next: Auto-loading extensions, Prev: Python, Up: Extending GDB |
| |
| 23.3 Extending GDB using Guile |
| ============================== |
| |
| You can extend GDB using the Guile implementation of the Scheme |
| programming language (http://www.gnu.org/software/guile/). This feature |
| is available only if GDB was configured using '--with-guile'. |
| |
| * Menu: |
| |
| * Guile Introduction:: Introduction to Guile scripting in GDB |
| * Guile Commands:: Accessing Guile from GDB |
| * Guile API:: Accessing GDB from Guile |
| * Guile Auto-loading:: Automatically loading Guile code |
| * Guile Modules:: Guile modules provided by GDB |
| |
| |
| File: gdb.info, Node: Guile Introduction, Next: Guile Commands, Up: Guile |
| |
| 23.3.1 Guile Introduction |
| ------------------------- |
| |
| Guile is an implementation of the Scheme programming language and is the |
| GNU project's official extension language. |
| |
| Guile support in GDB follows the Python support in GDB reasonably |
| closely, so concepts there should carry over. However, some things are |
| done differently where it makes sense. |
| |
| GDB requires Guile version 2.0 or greater. Older versions are not |
| supported. |
| |
| Guile scripts used by GDB should be installed in |
| 'DATA-DIRECTORY/guile', where DATA-DIRECTORY is the data directory as |
| determined at GDB startup (*note Data Files::). This directory, known |
| as the "guile directory", is automatically added to the Guile Search |
| Path in order to allow the Guile interpreter to locate all scripts |
| installed at this location. |
| |
| |
| File: gdb.info, Node: Guile Commands, Next: Guile API, Prev: Guile Introduction, Up: Guile |
| |
| 23.3.2 Guile Commands |
| --------------------- |
| |
| GDB provides two commands for accessing the Guile interpreter: |
| |
| 'guile-repl' |
| 'gr' |
| The 'guile-repl' command can be used to start an interactive Guile |
| prompt or "repl". To return to GDB, type ',q' or the 'EOF' |
| character (e.g., 'Ctrl-D' on an empty prompt). These commands do |
| not take any arguments. |
| |
| 'guile [SCHEME-EXPRESSION]' |
| 'gu [SCHEME-EXPRESSION]' |
| The 'guile' command can be used to evaluate a Scheme expression. |
| |
| If given an argument, GDB will pass the argument to the Guile |
| interpreter for evaluation. |
| |
| (gdb) guile (display (+ 20 3)) (newline) |
| 23 |
| |
| The result of the Scheme expression is displayed using normal Guile |
| rules. |
| |
| (gdb) guile (+ 20 3) |
| 23 |
| |
| If you do not provide an argument to 'guile', it will act as a |
| multi-line command, like 'define'. In this case, the Guile script |
| is made up of subsequent command lines, given after the 'guile' |
| command. This command list is terminated using a line containing |
| 'end'. For example: |
| |
| (gdb) guile |
| >(display 23) |
| >(newline) |
| >end |
| 23 |
| |
| It is also possible to execute a Guile script from the GDB |
| interpreter: |
| |
| 'source script-name' |
| The script name must end with '.scm' and GDB must be configured to |
| recognize the script language based on filename extension using the |
| 'script-extension' setting. *Note Extending GDB: Extending GDB. |
| |
| 'guile (load "script-name")' |
| This method uses the 'load' Guile function. It takes a string |
| argument that is the name of the script to load. See the Guile |
| documentation for a description of this function. (*note |
| (guile)Loading::). |
| |
| |
| File: gdb.info, Node: Guile API, Next: Guile Auto-loading, Prev: Guile Commands, Up: Guile |
| |
| 23.3.3 Guile API |
| ---------------- |
| |
| You can get quick online help for GDB's Guile API by issuing the command |
| 'help guile', or by issuing the command ',help' from an interactive |
| Guile session. Furthermore, most Guile procedures provided by GDB have |
| doc strings which can be obtained with ',describe PROCEDURE-NAME' or ',d |
| PROCEDURE-NAME' from the Guile interactive prompt. |
| |
| * Menu: |
| |
| * Basic Guile:: Basic Guile Functions |
| * Guile Configuration:: Guile configuration variables |
| * GDB Scheme Data Types:: Scheme representations of GDB objects |
| * Guile Exception Handling:: How Guile exceptions are translated |
| * Values From Inferior In Guile:: Guile representation of values |
| * Arithmetic In Guile:: Arithmetic in Guile |
| * Types In Guile:: Guile representation of types |
| * Guile Pretty Printing API:: Pretty-printing values with Guile |
| * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer |
| * Writing a Guile Pretty-Printer:: Writing a pretty-printer |
| * Commands In Guile:: Implementing new commands in Guile |
| * Parameters In Guile:: Adding new GDB parameters |
| * Progspaces In Guile:: Program spaces |
| * Objfiles In Guile:: Object files in Guile |
| * Frames In Guile:: Accessing inferior stack frames from Guile |
| * Blocks In Guile:: Accessing blocks from Guile |
| * Symbols In Guile:: Guile representation of symbols |
| * Symbol Tables In Guile:: Guile representation of symbol tables |
| * Breakpoints In Guile:: Manipulating breakpoints using Guile |
| * Lazy Strings In Guile:: Guile representation of lazy strings |
| * Architectures In Guile:: Guile representation of architectures |
| * Disassembly In Guile:: Disassembling instructions from Guile |
| * I/O Ports in Guile:: GDB I/O ports |
| * Memory Ports in Guile:: Accessing memory through ports and bytevectors |
| * Iterators In Guile:: Basic iterator support |
| |
| |
| File: gdb.info, Node: Basic Guile, Next: Guile Configuration, Up: Guile API |
| |
| 23.3.3.1 Basic Guile |
| .................... |
| |
| At startup, GDB overrides Guile's 'current-output-port' and |
| 'current-error-port' to print using GDB's output-paging streams. A |
| Guile program which outputs to one of these streams may have its output |
| interrupted by the user (*note Screen Size::). In this situation, a |
| Guile 'signal' exception is thrown with value 'SIGINT'. |
| |
| Guile's history mechanism uses the same naming as GDB's, namely the |
| user of dollar-variables (e.g., $1, $2, etc.). The results of |
| evaluations in Guile and in GDB are counted separately, '$1' in Guile is |
| not the same value as '$1' in GDB. |
| |
| GDB is not thread-safe. If your Guile program uses multiple threads, |
| you must be careful to only call GDB-specific functions in the GDB |
| thread. |
| |
| Some care must be taken when writing Guile code to run in GDB. Two |
| things are worth noting in particular: |
| |
| * GDB installs handlers for 'SIGCHLD' and 'SIGINT'. Guile 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 Guile 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 Guile module, named 'gdb'. All methods and |
| classes added by GDB are placed in this module. GDB does not |
| automatically 'import' the 'gdb' module, scripts must do this |
| themselves. There are various options for how to import a module, so |
| GDB leaves the choice of how the 'gdb' module is imported to the user. |
| To simplify interactive use, it is recommended to add one of the |
| following to your ~/.gdbinit. |
| |
| guile (use-modules (gdb)) |
| |
| guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:))) |
| |
| Which one to choose depends on your preference. The second one adds |
| 'gdb:' as a prefix to all module functions and variables. |
| |
| The rest of this manual assumes the 'gdb' module has been imported |
| without any prefix. See the Guile documentation for 'use-modules' for |
| more information (*note (guile)Using Guile Modules::). |
| |
| Example: |
| |
| (gdb) guile (value-type (make-value 1)) |
| ERROR: Unbound variable: value-type |
| Error while executing Scheme code. |
| (gdb) guile (use-modules (gdb)) |
| (gdb) guile (value-type (make-value 1)) |
| int |
| (gdb) |
| |
| The '(gdb)' module provides these basic Guile functions. |
| |
| -- Scheme Procedure: execute command [#:from-tty boolean] [#:to-string |
| boolean] |
| Evaluate COMMAND, a string, as a GDB CLI command. If a GDB |
| exception happens while COMMAND runs, it is translated as described |
| in *note Guile Exception Handling: Guile Exception Handling. |
| |
| FROM-TTY specifies whether GDB ought to consider this command as |
| having originated from the user invoking it interactively. It must |
| be a boolean value. If omitted, it defaults to '#f'. |
| |
| By default, any output produced by COMMAND is sent to GDB's |
| standard output (and to the log output if logging is turned on). |
| If the TO-STRING parameter is '#t', then output will be collected |
| by 'execute' and returned as a string. The default is '#f', in |
| which case the return value is unspecified. If TO-STRING is '#t', |
| the GDB virtual terminal will be temporarily set to unlimited width |
| and height, and its pagination will be disabled; *note Screen |
| Size::. |
| |
| -- Scheme Procedure: history-ref number |
| Return a value from GDB's value history (*note Value History::). |
| The NUMBER argument indicates which history element to return. If |
| NUMBER is negative, then GDB will take its absolute value and count |
| backward from the last element (i.e., the most recent element) to |
| find the value to return. If NUMBER is zero, then GDB will return |
| the most recent element. If the element specified by NUMBER |
| doesn't exist in the value history, a 'gdb:error' exception will be |
| raised. |
| |
| If no exception is raised, the return value is always an instance |
| of '<gdb:value>' (*note Values From Inferior In Guile::). |
| |
| _Note:_ GDB's value history is independent of Guile's. '$1' in |
| GDB's value history contains the result of evaluating an expression |
| from GDB's command line and '$1' from Guile's history contains the |
| result of evaluating an expression from Guile's command line. |
| |
| -- Scheme Procedure: history-append! value |
| Append VALUE, an instance of '<gdb:value>', to GDB's value history. |
| Return its index in the history. |
| |
| Putting into history values returned by Guile extensions will allow |
| the user convenient access to those values via CLI history |
| facilities. |
| |
| -- Scheme Procedure: parse-and-eval expression |
| Parse EXPRESSION as an expression in the current language, evaluate |
| it, and return the result as a '<gdb:value>'. The EXPRESSION must |
| be a string. |
| |
| This function can be useful when implementing a new command (*note |
| Commands In Guile::), as it provides a way to parse the command's |
| arguments as an expression. It is also is useful when computing |
| values. For example, it is the only way to get the value of a |
| convenience variable (*note Convenience Vars::) as a '<gdb:value>'. |
| |
| |
| File: gdb.info, Node: Guile Configuration, Next: GDB Scheme Data Types, Prev: Basic Guile, Up: Guile API |
| |
| 23.3.3.2 Guile Configuration |
| ............................ |
| |
| GDB provides these Scheme functions to access various configuration |
| parameters. |
| |
| -- Scheme Procedure: data-directory |
| Return a string containing GDB's data directory. This directory |
| contains GDB's ancillary files. |
| |
| -- Scheme Procedure: guile-data-directory |
| Return a string containing GDB's Guile data directory. This |
| directory contains the Guile modules provided by GDB. |
| |
| -- Scheme Procedure: gdb-version |
| Return a string containing the GDB version. |
| |
| -- Scheme Procedure: host-config |
| Return a string containing the host configuration. This is the |
| string passed to '--host' when GDB was configured. |
| |
| -- Scheme Procedure: target-config |
| Return a string containing the target configuration. This is the |
| string passed to '--target' when GDB was configured. |
| |
| |
| File: gdb.info, Node: GDB Scheme Data Types, Next: Guile Exception Handling, Prev: Guile Configuration, Up: Guile API |
| |
| 23.3.3.3 GDB Scheme Data Types |
| .............................. |
| |
| The values exposed by GDB to Guile are known as "GDB objects". There |
| are several kinds of GDB object, and each is disjoint from all other |
| types known to Guile. |
| |
| -- Scheme Procedure: gdb-object-kind object |
| Return the kind of the GDB object, e.g., '<gdb:breakpoint>', as a |
| symbol. |
| |
| GDB defines the following object types: |
| |
| '<gdb:arch>' |
| *Note Architectures In Guile::. |
| |
| '<gdb:block>' |
| *Note Blocks In Guile::. |
| |
| '<gdb:block-symbols-iterator>' |
| *Note Blocks In Guile::. |
| |
| '<gdb:breakpoint>' |
| *Note Breakpoints In Guile::. |
| |
| '<gdb:command>' |
| *Note Commands In Guile::. |
| |
| '<gdb:exception>' |
| *Note Guile Exception Handling::. |
| |
| '<gdb:frame>' |
| *Note Frames In Guile::. |
| |
| '<gdb:iterator>' |
| *Note Iterators In Guile::. |
| |
| '<gdb:lazy-string>' |
| *Note Lazy Strings In Guile::. |
| |
| '<gdb:objfile>' |
| *Note Objfiles In Guile::. |
| |
| '<gdb:parameter>' |
| *Note Parameters In Guile::. |
| |
| '<gdb:pretty-printer>' |
| *Note Guile Pretty Printing API::. |
| |
| '<gdb:pretty-printer-worker>' |
| *Note Guile Pretty Printing API::. |
| |
| '<gdb:progspace>' |
| *Note Progspaces In Guile::. |
| |
| '<gdb:symbol>' |
| *Note Symbols In Guile::. |
| |
| '<gdb:symtab>' |
| *Note Symbol Tables In Guile::. |
| |
| '<gdb:sal>' |
| *Note Symbol Tables In Guile::. |
| |
| '<gdb:type>' |
| *Note Types In Guile::. |
| |
| '<gdb:field>' |
| *Note Types In Guile::. |
| |
| '<gdb:value>' |
| *Note Values From Inferior In Guile::. |
| |
| The following GDB objects are managed internally so that the Scheme |
| function 'eq?' may be applied to them. |
| |
| '<gdb:arch>' |
| '<gdb:block>' |
| '<gdb:breakpoint>' |
| '<gdb:frame>' |
| '<gdb:objfile>' |
| '<gdb:progspace>' |
| '<gdb:symbol>' |
| '<gdb:symtab>' |
| '<gdb:type>' |
| |
| |
| File: gdb.info, Node: Guile Exception Handling, Next: Values From Inferior In Guile, Prev: GDB Scheme Data Types, Up: Guile API |
| |
| 23.3.3.4 Guile Exception Handling |
| ................................. |
| |
| When executing the 'guile' command, Guile exceptions uncaught within the |
| Guile code are translated to calls to the GDB error-reporting mechanism. |
| If the command that called 'guile' does not handle the error, GDB will |
| terminate it and report the error according to the setting of the 'guile |
| print-stack' parameter. |
| |
| The 'guile print-stack' parameter has three settings: |
| |
| 'none' |
| Nothing is printed. |
| |
| 'message' |
| An error message is printed containing the Guile exception name, |
| the associated value, and the Guile call stack backtrace at the |
| point where the exception was raised. Example: |
| |
| (gdb) guile (display foo) |
| ERROR: In procedure memoize-variable-access!: |
| ERROR: Unbound variable: foo |
| Error while executing Scheme code. |
| |
| 'full' |
| In addition to an error message a full backtrace is printed. |
| |
| (gdb) set guile print-stack full |
| (gdb) guile (display foo) |
| Guile Backtrace: |
| In ice-9/boot-9.scm: |
| 157: 10 [catch #t #<catch-closure 2c76e20> ...] |
| In unknown file: |
| ?: 9 [apply-smob/1 #<catch-closure 2c76e20>] |
| In ice-9/boot-9.scm: |
| 157: 8 [catch #t #<catch-closure 2c76d20> ...] |
| In unknown file: |
| ?: 7 [apply-smob/1 #<catch-closure 2c76d20>] |
| ?: 6 [call-with-input-string "(display foo)" ...] |
| In ice-9/boot-9.scm: |
| 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>] |
| In ice-9/eval-string.scm: |
| 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...] |
| 37: 3 [lp (display foo)] |
| In ice-9/eval.scm: |
| 387: 2 [eval # ()] |
| 393: 1 [eval #<memoized foo> ()] |
| In unknown file: |
| ?: 0 [memoize-variable-access! #<memoized foo> ...] |
| |
| ERROR: In procedure memoize-variable-access!: |
| ERROR: Unbound variable: foo |
| Error while executing Scheme code. |
| |
| GDB errors that happen in GDB commands invoked by Guile code are |
| converted to Guile exceptions. The type of the Guile exception depends |
| on the error. |
| |
| Guile procedures provided by GDB can throw the standard Guile |
| exceptions like 'wrong-type-arg' and 'out-of-range'. |
| |
| User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) is |
| translated to a Guile 'signal' exception with value 'SIGINT'. |
| |
| GDB Guile procedures can also throw these exceptions: |
| |
| 'gdb:error' |
| This exception is a catch-all for errors generated from within GDB. |
| |
| 'gdb:invalid-object' |
| This exception is thrown when accessing Guile objects that wrap |
| underlying GDB objects have become invalid. For example, a |
| '<gdb:breakpoint>' object becomes invalid if the user deletes it |
| from the command line. The object still exists in Guile, but the |
| object it represents is gone. Further operations on this |
| breakpoint will throw this exception. |
| |
| 'gdb:memory-error' |
| This exception is thrown when an operation tried to access invalid |
| memory in the inferior. |
| |
| 'gdb:pp-type-error' |
| This exception is thrown when a Guile pretty-printer passes a bad |
| object to GDB. |
| |
| The following exception-related procedures are provided by the |
| '(gdb)' module. |
| |
| -- Scheme Procedure: make-exception key args |
| Return a '<gdb:exception>' object given by its KEY and ARGS, which |
| are the standard Guile parameters of an exception. See the Guile |
| documentation for more information (*note (guile)Exceptions::). |
| |
| -- Scheme Procedure: exception? object |
| Return '#t' if OBJECT is a '<gdb:exception>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: exception-key exception |
| Return the ARGS field of a '<gdb:exception>' object. |
| |
| -- Scheme Procedure: exception-args exception |
| Return the ARGS field of a '<gdb:exception>' object. |
| |
| |
| File: gdb.info, Node: Values From Inferior In Guile, Next: Arithmetic In Guile, Prev: Guile Exception Handling, Up: Guile API |
| |
| 23.3.3.5 Values From Inferior In Guile |
| ...................................... |
| |
| GDB provides values it obtains from the inferior program in an object of |
| type '<gdb:value>'. GDB uses this object for its internal bookkeeping |
| of the inferior's values, and for fetching values when necessary. |
| |
| GDB does not memoize '<gdb:value>' objects. 'make-value' always |
| returns a fresh object. |
| |
| (gdb) guile (eq? (make-value 1) (make-value 1)) |
| $1 = #f |
| (gdb) guile (equal? (make-value 1) (make-value 1)) |
| $1 = #t |
| |
| A '<gdb:value>' that represents a function can be executed via |
| inferior function call with 'value-call'. Any arguments provided to the |
| call must match the function's prototype, and must be provided in the |
| order specified by that prototype. |
| |
| For example, 'some-val' is a '<gdb:value>' instance representing a |
| function that takes two integers as arguments. To execute this |
| function, call it like so: |
| |
| (define result (value-call some-val 10 20)) |
| |
| Any values returned from a function call are '<gdb:value>' objects. |
| |
| Note: Unlike Python scripting in GDB, inferior values that are simple |
| scalars cannot be used directly in Scheme expressions that are valid for |
| the value's data type. For example, '(+ (parse-and-eval "int_variable") |
| 2)' does not work. And inferior values that are structures or instances |
| of some class cannot be accessed using any special syntax, instead |
| 'value-field' must be used. |
| |
| The following value-related procedures are provided by the '(gdb)' |
| module. |
| |
| -- Scheme Procedure: value? object |
| Return '#t' if OBJECT is a '<gdb:value>' object. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: make-value value [#:type type] |
| Many Scheme values can be converted directly to a '<gdb:value>' |
| with this procedure. If TYPE is specified, the result is a value |
| of this type, and if VALUE can't be represented with this type an |
| exception is thrown. Otherwise the type of the result is |
| determined from VALUE as described below. |
| |
| *Note Architectures In Guile::, for a list of the builtin types for |
| an architecture. |
| |
| Here's how Scheme values are converted when TYPE argument to |
| 'make-value' is not specified: |
| |
| Scheme boolean |
| A Scheme boolean is converted the boolean type for the current |
| language. |
| |
| Scheme integer |
| A Scheme integer is converted to the first of a C 'int', |
| 'unsigned int', 'long', 'unsigned long', 'long long' or |
| 'unsigned long long' type for the current architecture that |
| can represent the value. |
| |
| If the Scheme integer cannot be represented as a target |
| integer an 'out-of-range' exception is thrown. |
| |
| Scheme real |
| A Scheme real is converted to the C 'double' type for the |
| current architecture. |
| |
| Scheme string |
| A Scheme string is converted to a string in the current target |
| language using the current target encoding. Characters that |
| cannot be represented in the current target encoding are |
| replaced with the corresponding escape sequence. This is |
| Guile's 'SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE' conversion |
| strategy (*note (guile)Strings::). |
| |
| Passing TYPE is not supported in this case, if it is provided |
| a 'wrong-type-arg' exception is thrown. |
| |
| '<gdb:lazy-string>' |
| If VALUE is a '<gdb:lazy-string>' object (*note Lazy Strings |
| In Guile::), then the 'lazy-string->value' procedure is |
| called, and its result is used. |
| |
| Passing TYPE is not supported in this case, if it is provided |
| a 'wrong-type-arg' exception is thrown. |
| |
| Scheme bytevector |
| If VALUE is a Scheme bytevector and TYPE is provided, VALUE |
| must be the same size, in bytes, of values of type TYPE, and |
| the result is essentially created by using 'memcpy'. |
| |
| If VALUE is a Scheme bytevector and TYPE is not provided, the |
| result is an array of type 'uint8' of the same length. |
| |
| -- Scheme Procedure: value-optimized-out? value |
| Return '#t' if the compiler optimized out VALUE, thus it is not |
| available for fetching from the inferior. Otherwise return '#f'. |
| |
| -- Scheme Procedure: value-address value |
| If VALUE is addressable, returns a '<gdb:value>' object |
| representing the address. Otherwise, '#f' is returned. |
| |
| -- Scheme Procedure: value-type value |
| Return the type of VALUE as a '<gdb:type>' object (*note Types In |
| Guile::). |
| |
| -- Scheme Procedure: value-dynamic-type value |
| Return the dynamic type of VALUE. This uses C++ run-time type |
| information (RTTI) to determine the dynamic type of the value. If |
| the value is of class type, it will return the class in which the |
| value is embedded, if any. If the 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. |
| |
| -- Scheme Procedure: value-cast value type |
| Return a new instance of '<gdb:value>' that is the result of |
| casting VALUE 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. |
| |
| -- Scheme Procedure: value-dynamic-cast value type |
| Like 'value-cast', but works as if the C++ 'dynamic_cast' operator |
| were used. Consult a C++ reference for details. |
| |
| -- Scheme Procedure: value-reinterpret-cast value type |
| Like 'value-cast', but works as if the C++ 'reinterpret_cast' |
| operator were used. Consult a C++ reference for details. |
| |
| -- Scheme Procedure: value-dereference value |
| For pointer data types, this method returns a new '<gdb:value>' |
| object whose contents is the object pointed to by VALUE. 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: |
| |
| (define bar (value-dereference foo)) |
| |
| 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 corresponding 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'. |
| |
| (define scm-ptrref (parse-and-eval "ptrref")) |
| (define scm-val (value-dereference scm-ptrref)) |
| (define scm-ptr (value-referenced-value scm-ptrref)) |
| |
| The '<gdb:value>' object 'scm-val' is identical to that |
| corresponding to 'val', and 'scm-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. |
| |
| -- Scheme Procedure: value-referenced-value 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'. |
| |
| (define scm-ref (parse-and-eval "ref")) |
| (define err-ref (value-dereference scm-ref)) ;; error |
| (define scm-val (value-referenced-value scm-ref)) ;; ok |
| |
| The '<gdb:value>' object 'scm-val' is identical to that |
| corresponding to 'val'. |
| |
| -- Scheme Procedure: value-field value field-name |
| Return field FIELD-NAME from '<gdb:value>' object VALUE. |
| |
| -- Scheme Procedure: value-subscript value index |
| Return the value of array VALUE at index INDEX. The VALUE argument |
| must be a subscriptable '<gdb:value>' object. |
| |
| -- Scheme Procedure: value-call value arg-list |
| Perform an inferior function call, taking VALUE as a pointer to the |
| function to call. Each element of list ARG-LIST must be a |
| <gdb:value> object or an object that can be converted to a value. |
| The result is the value returned by the function. |
| |
| -- Scheme Procedure: value->bool value |
| Return the Scheme boolean representing '<gdb:value>' VALUE. The |
| value must be "integer like". Pointers are ok. |
| |
| -- Scheme Procedure: value->integer |
| Return the Scheme integer representing '<gdb:value>' VALUE. The |
| value must be "integer like". Pointers are ok. |
| |
| -- Scheme Procedure: value->real |
| Return the Scheme real number representing '<gdb:value>' VALUE. |
| The value must be a number. |
| |
| -- Scheme Procedure: value->bytevector |
| Return a Scheme bytevector with the raw contents of '<gdb:value>' |
| VALUE. No transformation, endian or otherwise, is performed. |
| |
| -- Scheme Procedure: value->string value [#:encoding encoding] |
| [#:errors errors] [#:length length] |
| If VALUE> represents a string, then this method converts the |
| contents to a Guile string. Otherwise, this method will throw an |
| exception. |
| |
| Values are interpreted as strings according to the rules of the |
| current language. If the optional length argument is given, the |
| string will be converted to that length, and will include any |
| embedded zeroes that the string may contain. Otherwise, for |
| languages where the string is zero-terminated, the entire string |
| will be converted. |
| |
| For example, in C-like languages, a value is a string if it is a |
| pointer to or an array of characters or ints of type 'wchar_t', |
| 'char16_t', or 'char32_t'. |
| |
| 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 Guile's |
| 'scm_from_stringn' function, and the Guile 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 one of '#f', 'error' or |
| 'substitute'. 'error' and 'substitute' must be symbols. If ERRORS |
| is not specified, or if its value is '#f', then the default |
| conversion strategy is used, which is set with the Scheme function |
| 'set-port-conversion-strategy!'. If the value is ''error' then an |
| exception is thrown if there is any conversion error. If the value |
| is ''substitute' then any conversion error is replaced with |
| question marks. *Note (guile)Strings::. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and converted to the given length. The length must be a |
| Scheme integer and not a '<gdb:value>' integer. |
| |
| -- Scheme Procedure: value->lazy-string value [#:encoding encoding] |
| [#:length length] |
| If this '<gdb:value>' represents a string, then this method |
| converts VALUE to a '<gdb:lazy-string' (*note Lazy Strings In |
| Guile::). 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:lazy-string'. Some examples are: |
| '"ascii"', '"iso-8859-6"' or '"utf-8"'. If the ENCODING argument |
| is an encoding that GDB does not 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. The length |
| must be a Scheme integer and not a '<gdb:value>' integer. |
| |
| -- Scheme Procedure: value-lazy? value |
| Return '#t' if VALUE has not yet been fetched from the inferior. |
| Otherwise return '#f'. GDB does not fetch values until necessary, |
| for efficiency. For example: |
| |
| (define myval (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' |
| procedure is invoked. |
| |
| -- Scheme Procedure: make-lazy-value type address |
| Return a '<gdb:value>' that will be lazily fetched from the target. |
| The object of type '<gdb:type>' whose value to fetch is specified |
| by its TYPE and its target memory ADDRESS, which is a Scheme |
| integer. |
| |
| -- Scheme Procedure: value-fetch-lazy! value |
| If VALUE is a lazy value ('(value-lazy? value)' is '#t'), then the |
| value is fetched from the inferior. Any errors that occur in the |
| process will produce a Guile exception. |
| |
| If VALUE is not a lazy value, this method has no effect. |
| |
| The result of this function is unspecified. |
| |
| -- Scheme Procedure: value-print value |
| Return the string representation (print form) of '<gdb:value>' |
| VALUE. |
| |