Merge GDB 7.5.1

gdb/doc/gdb.info-3

 This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
 
 INFO-DIR-SECTION Software development
 START-INFO-DIR-ENTRY
 * Gdb: (gdb).                     The GNU debugger.
 END-INFO-DIR-ENTRY
 
    Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010 Free Software Foundation, Inc.
+2010 2011, 2012 Free Software Foundation, Inc.
 
    Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being "Free Software" and "Free Software Needs Free
 Documentation", with the Front-Cover Texts being "A GNU Manual," and
 with the Back-Cover Texts as in (a) below.
 
    (a) The FSF's Back-Cover Text is: "You are free to copy and modify
 this GNU Manual.  Buying copies from GNU Press supports the FSF in
 developing GNU and promoting software freedom."
 
    This file documents the GNU debugger GDB.
 
    This is the Tenth Edition, of `Debugging with GDB: the GNU
-Source-Level Debugger' for GDB (GDB) Version 7.4.1.
+Source-Level Debugger' for GDB (GDB) Version 7.5.1.
 
    Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010 Free Software Foundation, Inc.
+2010 2011, 2012 Free Software Foundation, Inc.
 
    Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being "Free Software" and "Free Software Needs Free
 Documentation", with the Front-Cover Texts being "A GNU Manual," and
 with the Back-Cover Texts as in (a) below.
 
    (a) The FSF's Back-Cover Text is: "You are free to copy and modify
 this GNU Manual.  Buying copies from GNU Press supports the FSF in
 developing GNU and promoting software freedom."
 
 
+File: gdb.info,  Node: Symbol Errors,  Next: Data Files,  Prev: Index Files,  Up: GDB Files
+
+18.4 Errors Reading Symbol Files
+================================
+
+While reading a symbol file, GDB occasionally encounters problems, such
+as symbol types it does not recognize, or known bugs in compiler
+output.  By default, GDB does not notify you of such problems, since
+they are relatively common and primarily of interest to people
+debugging compilers.  If you are interested in seeing information about
+ill-constructed symbol tables, you can either ask GDB to print only one
+message about each such type of problem, no matter how many times the
+problem occurs; or you can ask GDB to print more messages, to see how
+many times the problems occur, with the `set complaints' command (*note
+Optional Warnings and Messages: Messages/Warnings.).
+
+   The messages currently printed, and their meanings, include:
+
+`inner block not inside outer block in SYMBOL'
+     The symbol information shows where symbol scopes begin and end
+     (such as at the start of a function or a block of statements).
+     This error indicates that an inner scope block is not fully
+     contained in its outer scope blocks.
+
+     GDB circumvents the problem by treating the inner block as if it
+     had the same scope as the outer block.  In the error message,
+     SYMBOL may be shown as "`(don't know)'" if the outer block is not a
+     function.
+
+`block at ADDRESS out of order'
+     The symbol information for symbol scope blocks should occur in
+     order of increasing addresses.  This error indicates that it does
+     not do so.
+
+     GDB does not circumvent this problem, and has trouble locating
+     symbols in the source file whose symbols it is reading.  (You can
+     often determine what source file is affected by specifying `set
+     verbose on'.  *Note Optional Warnings and Messages:
+     Messages/Warnings.)
+
+`bad block start address patched'
+     The symbol information for a symbol scope block has a start address
+     smaller than the address of the preceding source line.  This is
+     known to occur in the SunOS 4.1.1 (and earlier) C compiler.
+
+     GDB circumvents the problem by treating the symbol scope block as
+     starting on the previous source line.
+
+`bad string table offset in symbol N'
+     Symbol number N contains a pointer into the string table which is
+     larger than the size of the string table.
+
+     GDB circumvents the problem by considering the symbol to have the
+     name `foo', which may cause other problems if many symbols end up
+     with this name.
+
+`unknown symbol type `0xNN''
+     The symbol information contains new data types that GDB does not
+     yet know how to read.  `0xNN' is the symbol type of the
+     uncomprehended information, in hexadecimal.
+
+     GDB circumvents the error by ignoring this symbol information.
+     This usually allows you to debug your program, though certain
+     symbols are not accessible.  If you encounter such a problem and
+     feel like debugging it, you can debug `gdb' with itself, breakpoint
+     on `complain', then go up to the function `read_dbx_symtab' and
+     examine `*bufp' to see the symbol.
+
+`stub type has NULL name'
+     GDB could not find the full definition for a struct or class.
+
+`const/volatile indicator missing (ok if using g++ v1.x), got...'
+     The symbol information for a C++ member function is missing some
+     information that recent versions of the compiler should have
+     output for it.
+
+`info mismatch between compiler and debugger'
+     GDB could not parse a type specification output by the compiler.
+
+
+
+File: gdb.info,  Node: Data Files,  Prev: Symbol Errors,  Up: GDB Files
+
+18.5 GDB Data Files
+===================
+
+GDB will sometimes read an auxiliary data file.  These files are kept
+in a directory known as the "data directory".
+
+   You can set the data directory's name, and view the name GDB is
+currently using.
+
+`set data-directory DIRECTORY'
+     Set the directory which GDB searches for auxiliary data files to
+     DIRECTORY.
+
+`show data-directory'
+     Show the directory GDB searches for auxiliary data files.
+
+   You can set the default data directory by using the configure-time
+`--with-gdb-datadir' option.  If the data directory is inside GDB's
+configured binary prefix (set with `--prefix' or `--exec-prefix'), then
+the default data directory will be updated automatically if the
+installed GDB is moved to a new location.
+
+   The data directory may also be specified with the `--data-directory'
+command line option.  *Note Mode Options::.
+
+
+File: gdb.info,  Node: Targets,  Next: Remote Debugging,  Prev: GDB Files,  Up: Top
+
+19 Specifying a Debugging Target
+********************************
+
+A "target" is the execution environment occupied by your program.
+
+   Often, GDB runs in the same host environment as your program; in
+that case, the debugging target is specified as a side effect when you
+use the `file' or `core' commands.  When you need more flexibility--for
+example, running GDB on a physically separate host, or controlling a
+standalone system over a serial port or a realtime system over a TCP/IP
+connection--you can use the `target' command to specify one of the
+target types configured for GDB (*note Commands for Managing Targets:
+Target Commands.).
+
+   It is possible to build GDB for several different "target
+architectures".  When GDB is built like that, you can choose one of the
+available architectures with the `set architecture' command.
+
+`set architecture ARCH'
+     This command sets the current target architecture to ARCH.  The
+     value of ARCH can be `"auto"', in addition to one of the supported
+     architectures.
+
+`show architecture'
+     Show the current target architecture.
+
+`set processor'
+`processor'
+     These are alias commands for, respectively, `set architecture' and
+     `show architecture'.
+
+* Menu:
+
+* Active Targets::              Active targets
+* Target Commands::             Commands for managing targets
+* Byte Order::                  Choosing target byte order
+
+
+File: gdb.info,  Node: Active Targets,  Next: Target Commands,  Up: Targets
+
+19.1 Active Targets
+===================
+
+There are multiple classes of targets such as: processes, executable
+files or recording sessions.  Core files belong to the process class,
+making core file and process mutually exclusive.  Otherwise, GDB can
+work concurrently on multiple active targets, one in each class.  This
+allows you to (for example) start a process and inspect its activity,
+while still having access to the executable file after the process
+finishes.  Or if you start process recording (*note Reverse
+Execution::) and `reverse-step' there, you are presented a virtual
+layer of the recording target, while the process target remains stopped
+at the chronologically last point of the process execution.
+
+   Use the `core-file' and `exec-file' commands to select a new core
+file or executable target (*note Commands to Specify Files: Files.).  To
+specify as a target a process that is already running, use the `attach'
+command (*note Debugging an Already-running Process: Attach.).
+
+
+File: gdb.info,  Node: Target Commands,  Next: Byte Order,  Prev: Active Targets,  Up: Targets
+
+19.2 Commands for Managing Targets
+==================================
+
+`target TYPE PARAMETERS'
+     Connects the GDB host environment to a target machine or process.
+     A target is typically a protocol for talking to debugging
+     facilities.  You use the argument TYPE to specify the type or
+     protocol of the target machine.
+
+     Further PARAMETERS are interpreted by the target protocol, but
+     typically include things like device names or host names to connect
+     with, process numbers, and baud rates.
+
+     The `target' command does not repeat if you press <RET> again
+     after executing the command.
+
+`help target'
+     Displays the names of all targets available.  To display targets
+     currently selected, use either `info target' or `info files'
+     (*note Commands to Specify Files: Files.).
+
+`help target NAME'
+     Describe a particular target, including any parameters necessary to
+     select it.
+
+`set gnutarget ARGS'
+     GDB uses its own library BFD to read your files.  GDB knows
+     whether it is reading an "executable", a "core", or a ".o" file;
+     however, you can specify the file format with the `set gnutarget'
+     command.  Unlike most `target' commands, with `gnutarget' the
+     `target' refers to a program, not a machine.
+
+          _Warning:_ To specify a file format with `set gnutarget', you
+          must know the actual BFD name.
+
+     *Note Commands to Specify Files: Files.
+
+`show gnutarget'
+     Use the `show gnutarget' command to display what file format
+     `gnutarget' is set to read.  If you have not set `gnutarget', GDB
+     will determine the file format for each file automatically, and
+     `show gnutarget' displays `The current BDF target is "auto"'.
+
+   Here are some common targets (available, or not, depending on the GDB
+configuration):
+
+`target exec PROGRAM'
+     An executable file.  `target exec PROGRAM' is the same as
+     `exec-file PROGRAM'.
+
+`target core FILENAME'
+     A core dump file.  `target core FILENAME' is the same as
+     `core-file FILENAME'.
+
+`target remote MEDIUM'
+     A remote system connected to GDB via a serial line or network
+     connection.  This command tells GDB to use its own remote protocol
+     over MEDIUM for debugging.  *Note Remote Debugging::.
+
+     For example, if you have a board connected to `/dev/ttya' on the
+     machine running GDB, you could say:
+
+          target remote /dev/ttya
+
+     `target remote' supports the `load' command.  This is only useful
+     if you have some other way of getting the stub to the target
+     system, and you can put it somewhere in memory where it won't get
+     clobbered by the download.
+
+`target sim [SIMARGS] ...'
+     Builtin CPU simulator.  GDB includes simulators for most
+     architectures.  In general,
+                  target sim
+                  load
+                  run
+     works; however, you cannot assume that a specific memory map,
+     device drivers, or even basic I/O is available, although some
+     simulators do provide these.  For info about any
+     processor-specific simulator details, see the appropriate section
+     in *Note Embedded Processors: Embedded Processors.
+
+
+   Some configurations may include these targets as well:
+
+`target nrom DEV'
+     NetROM ROM emulator.  This target only supports downloading.
+
+
+   Different targets are available on different configurations of GDB;
+your configuration may have more or fewer targets.
+
+   Many remote targets require you to download the executable's code
+once you've successfully established a connection.  You may wish to
+control various aspects of this process.
+
+`set hash'
+     This command controls whether a hash mark `#' is displayed while
+     downloading a file to the remote monitor.  If on, a hash mark is
+     displayed after each S-record is successfully downloaded to the
+     monitor.
+
+`show hash'
+     Show the current status of displaying the hash mark.
+
+`set debug monitor'
+     Enable or disable display of communications messages between GDB
+     and the remote monitor.
+
+`show debug monitor'
+     Show the current status of displaying communications between GDB
+     and the remote monitor.
+
+`load FILENAME'
+     Depending on what remote debugging facilities are configured into
+     GDB, the `load' command may be available.  Where it exists, it is
+     meant to make FILENAME (an executable) available for debugging on
+     the remote system--by downloading, or dynamic linking, for example.
+     `load' also records the FILENAME symbol table in GDB, like the
+     `add-symbol-file' command.
+
+     If your GDB does not have a `load' command, attempting to execute
+     it gets the error message "`You can't do that when your target is
+     ...'"
+
+     The file is loaded at whatever address is specified in the
+     executable.  For some object file formats, you can specify the
+     load address when you link the program; for other formats, like
+     a.out, the object file format specifies a fixed address.
+
+     Depending on the remote side capabilities, GDB may be able to load
+     programs into flash memory.
+
+     `load' does not repeat if you press <RET> again after using it.
+
+
+File: gdb.info,  Node: Byte Order,  Prev: Target Commands,  Up: Targets
+
+19.3 Choosing Target Byte Order
+===============================
+
+Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
+offer the ability to run either big-endian or little-endian byte
+orders.  Usually the executable or symbol will include a bit to
+designate the endian-ness, and you will not need to worry about which
+to use.  However, you may still find it useful to adjust GDB's idea of
+processor endian-ness manually.
+
+`set endian big'
+     Instruct GDB to assume the target is big-endian.
+
+`set endian little'
+     Instruct GDB to assume the target is little-endian.
+
+`set endian auto'
+     Instruct GDB to use the byte order associated with the executable.
+
+`show endian'
+     Display GDB's current idea of the target byte order.
+
+
+   Note that these commands merely adjust interpretation of symbolic
+data on the host, and that they have absolutely no effect on the target
+system.
+
+
+File: gdb.info,  Node: Remote Debugging,  Next: Configurations,  Prev: Targets,  Up: Top
+
+20 Debugging Remote Programs
+****************************
+
+If you are trying to debug a program running on a machine that cannot
+run GDB in the usual way, it is often useful to use remote debugging.
+For example, you might use remote debugging on an operating system
+kernel, or on a small system which does not have a general purpose
+operating system powerful enough to run a full-featured debugger.
+
+   Some configurations of GDB have special serial or TCP/IP interfaces
+to make this work with particular debugging targets.  In addition, GDB
+comes with a generic serial protocol (specific to GDB, but not specific
+to any particular target system) which you can use if you write the
+remote stubs--the code that runs on the remote system to communicate
+with GDB.
+
+   Other remote targets may be available in your configuration of GDB;
+use `help target' to list them.
+
+* Menu:
+
+* Connecting::                  Connecting to a remote target
+* File Transfer::               Sending files to a remote system
+* Server::                      Using the gdbserver program
+* Remote Configuration::        Remote configuration
+* Remote Stub::                 Implementing a remote stub
+
+
+File: gdb.info,  Node: Connecting,  Next: File Transfer,  Up: Remote Debugging
+
+20.1 Connecting to a Remote Target
+==================================
+
+On the GDB host machine, you will need an unstripped copy of your
+program, since GDB needs symbol and debugging information.  Start up
+GDB as usual, using the name of the local copy of your program as the
+first argument.
+
+   GDB can communicate with the target over a serial line, or over an
+IP network using TCP or UDP.  In each case, GDB uses the same protocol
+for debugging your program; only the medium carrying the debugging
+packets varies.  The `target remote' command establishes a connection
+to the target.  Its arguments indicate which medium to use:
+
+`target remote SERIAL-DEVICE'
+     Use SERIAL-DEVICE to communicate with the target.  For example, to
+     use a serial line connected to the device named `/dev/ttyb':
+
+          target remote /dev/ttyb
+
+     If you're using a serial line, you may want to give GDB the
+     `--baud' option, or use the `set remotebaud' command (*note set
+     remotebaud: Remote Configuration.) before the `target' command.
+
+`target remote `HOST:PORT''
+`target remote `tcp:HOST:PORT''
+     Debug using a TCP connection to PORT on HOST.  The HOST may be
+     either a host name or a numeric IP address; PORT must be a decimal
+     number.  The HOST could be the target machine itself, if it is
+     directly connected to the net, or it might be a terminal server
+     which in turn has a serial line to the target.
+
+     For example, to connect to port 2828 on a terminal server named
+     `manyfarms':
+
+          target remote manyfarms:2828
+
+     If your remote target is actually running on the same machine as
+     your debugger session (e.g. a simulator for your target running on
+     the same host), you can omit the hostname.  For example, to
+     connect to port 1234 on your local machine:
+
+          target remote :1234
+     Note that the colon is still required here.
+
+`target remote `udp:HOST:PORT''
+     Debug using UDP packets to PORT on HOST.  For example, to connect
+     to UDP port 2828 on a terminal server named `manyfarms':
+
+          target remote udp:manyfarms:2828
+
+     When using a UDP connection for remote debugging, you should keep
+     in mind that the `U' stands for "Unreliable".  UDP can silently
+     drop packets on busy or unreliable networks, which will cause
+     havoc with your debugging session.
+
+`target remote | COMMAND'
+     Run COMMAND in the background and communicate with it using a
+     pipe.  The COMMAND is a shell command, to be parsed and expanded
+     by the system's command shell, `/bin/sh'; it should expect remote
+     protocol packets on its standard input, and send replies on its
+     standard output.  You could use this to run a stand-alone simulator
+     that speaks the remote debugging protocol, to make net connections
+     using programs like `ssh', or for other similar tricks.
+
+     If COMMAND closes its standard output (perhaps by exiting), GDB
+     will try to send it a `SIGTERM' signal.  (If the program has
+     already exited, this will have no effect.)
+
+
+   Once the connection has been established, you can use all the usual
+commands to examine and change data.  The remote program is already
+running; you can use `step' and `continue', and you do not need to use
+`run'.
+
+   Whenever GDB is waiting for the remote program, if you type the
+interrupt character (often `Ctrl-c'), GDB attempts to stop the program.
+This may or may not succeed, depending in part on the hardware and the
+serial drivers the remote system uses.  If you type the interrupt
+character once again, GDB displays this prompt:
+
+     Interrupted while waiting for the program.
+     Give up (and stop debugging it)?  (y or n)
+
+   If you type `y', GDB abandons the remote debugging session.  (If you
+decide you want to try again later, you can use `target remote' again
+to connect once more.)  If you type `n', GDB goes back to waiting.
+
+`detach'
+     When you have finished debugging the remote program, you can use
+     the `detach' command to release it from GDB control.  Detaching
+     from the target normally resumes its execution, but the results
+     will depend on your particular remote stub.  After the `detach'
+     command, GDB is free to connect to another target.
+
+`disconnect'
+     The `disconnect' command behaves like `detach', except that the
+     target is generally not resumed.  It will wait for GDB (this
+     instance or another one) to connect and continue debugging.  After
+     the `disconnect' command, GDB is again free to connect to another
+     target.
+
+`monitor CMD'
+     This command allows you to send arbitrary commands directly to the
+     remote monitor.  Since GDB doesn't care about the commands it
+     sends like this, this command is the way to extend GDB--you can
+     add new commands that only the external monitor will understand
+     and implement.
+
+
+File: gdb.info,  Node: File Transfer,  Next: Server,  Prev: Connecting,  Up: Remote Debugging
+
+20.2 Sending files to a remote system
+=====================================
+
+Some remote targets offer the ability to transfer files over the same
+connection used to communicate with GDB.  This is convenient for
+targets accessible through other means, e.g. GNU/Linux systems running
+`gdbserver' over a network interface.  For other targets, e.g. embedded
+devices with only a single serial port, this may be the only way to
+upload or download files.
+
+   Not all remote targets support these commands.
+
+`remote put HOSTFILE TARGETFILE'
+     Copy file HOSTFILE from the host system (the machine running GDB)
+     to TARGETFILE on the target system.
+
+`remote get TARGETFILE HOSTFILE'
+     Copy file TARGETFILE from the target system to HOSTFILE on the
+     host system.
+
+`remote delete TARGETFILE'
+     Delete TARGETFILE from the target system.
+
+
+
 File: gdb.info,  Node: Server,  Next: Remote Configuration,  Prev: File Transfer,  Up: Remote Debugging
 
 20.3 Using the `gdbserver' Program
 ==================================
 
 `gdbserver' is a control program for Unix-like systems, which allows
 you to connect your program with a remote GDB via `target remote'--but
 without linking in the usual debugging stub.
 
    `gdbserver' is not a complete replacement for the debugging stubs,
@@ skipping 25 matching lines @@
 does not need your program's symbol table, so you can strip the program
 if necessary to save space.  GDB on the host system does all the symbol
 handling.
 
    To use the server, you must tell it how to communicate with GDB; the
 name of your program; and the arguments for your program.  The usual
 syntax is:
 
      target> gdbserver COMM PROGRAM [ ARGS ... ]
 
-   COMM is either a device name (to use a serial line) or a TCP
-hostname and portnumber.  For example, to debug Emacs with the argument
-`foo.txt' and communicate with GDB over the serial port `/dev/com1':
+   COMM is either a device name (to use a serial line), or a TCP
+hostname and portnumber, or `-' or `stdio' to use stdin/stdout of
+`gdbserver'.  For example, to debug Emacs with the argument `foo.txt'
+and communicate with GDB over the serial port `/dev/com1':
 
      target> gdbserver /dev/com1 emacs foo.txt
 
    `gdbserver' waits passively for the host GDB to communicate with it.
 
    To use a TCP connection instead of a serial line:
 
      target> gdbserver host:2345 emacs foo.txt
 
    The only difference from the previous example is the first argument,
 specifying that you are communicating with the host GDB via TCP.  The
 `host:2345' argument means that `gdbserver' is to expect a TCP
 connection from machine `host' to local TCP port 2345.  (Currently, the
 `host' part is ignored.)  You can choose any number you want for the
 port number as long as it does not conflict with any TCP ports already
 in use on the target system (for example, `23' is reserved for
 `telnet').(1)  You must use the same port number with the host GDB
 `target remote' command.
 
+   The `stdio' connection is useful when starting `gdbserver' with ssh:
+
+     (gdb) target remote | ssh -T hostname gdbserver - hello
+
+   The `-T' option to ssh is provided because we don't need a remote
+pty, and we don't want escape-character handling.  Ssh does this by
+default when a command is provided, the flag is provided to make it
+explicit.  You could elide it if you want to.
+
+   Programs started with stdio-connected gdbserver have `/dev/null' for
+`stdin', and `stdout',`stderr' are sent back to gdb for display through
+a pipe connected to gdbserver.  Both `stdout' and `stderr' use the same
+pipe.
+
 20.3.1.1 Attaching to a Running Program
 .......................................
 
 On some targets, `gdbserver' can also attach to running programs.  This
 is accomplished via the `--attach' argument.  The syntax is:
 
      target> gdbserver --attach COMM PID
 
    PID is the process ID of a currently running process.  It isn't
 necessary to point `gdbserver' at a binary for the running process.
@@ skipping 421 matching lines @@
 storage-address'                             `__thread'
                                              variables
 `get-thread-information-block-address'`qGetTIBAddr'           Display
                                              MS-Windows Thread
                                              Information Block.
 `search-memory'      `qSearch:memory'        `find'
 `supported-packets'  `qSupported'            Remote
                                              communications
                                              parameters
 `pass-signals'       `QPassSignals'          `handle SIGNAL'
+`program-signals'    `QProgramSignals'       `handle SIGNAL'
 `hostio-close-packet'`vFile:close'           `remote get',
                                              `remote put'
 `hostio-open-packet' `vFile:open'            `remote get',
                                              `remote put'
 `hostio-pread-packet'`vFile:pread'           `remote get',
                                              `remote put'
 `hostio-pwrite-packet'`vFile:pwrite'          `remote get',
                                              `remote put'
 `hostio-unlink-packet'`vFile:unlink'          `remote delete'
+`hostio-readlink-packet'`vFile:readlink'        Host I/O
 `noack-packet'       `QStartNoAckMode'       Packet
                                              acknowledgment
 `osdata'             `qXfer:osdata:read'     `info os'
 `query-attached'     `qAttached'             Querying remote
                                              process attach
                                              state.
 `traceframe-info'    `qXfer:traceframe-info:read'Traceframe info
 `install-in-trace'   `InstallInTrace'        Install
                                              tracepoint in
                                              tracing
 `disable-randomization'`QDisableRandomization' `set
                                              disable-randomization'
+`conditional-breakpoints-packet'`Z0 and Z1'             `Support for
+                                             target-side
+                                             breakpoint
+                                             condition
+                                             evaluation'
 
 
 File: gdb.info,  Node: Remote Stub,  Prev: Remote Configuration,  Up: Remote Debugging
 
 20.5 Implementing a Remote Stub
 ===============================
 
 The stub files provided with GDB implement the target side of the
 communication protocol, and the GDB side is implemented in the GDB
 source file `remote.c'.  Normally, you can simply allow these
@@ skipping 73 matching lines @@
 File: gdb.info,  Node: Stub Contents,  Next: Bootstrapping,  Up: Remote Stub
 
 20.5.1 What the Stub Can Do for You
 -----------------------------------
 
 The debugging stub for your architecture supplies these three
 subroutines:
 
 `set_debug_traps'
      This routine arranges for `handle_exception' to run when your
-     program stops.  You must call this subroutine explicitly near the
-     beginning of your program.
+     program stops.  You must call this subroutine explicitly in your
+     program's startup code.
 
 `handle_exception'
      This is the central workhorse, but your program never calls it
      explicitly--the setup code arranges for `handle_exception' to run
      when a trap is triggered.
 
      `handle_exception' takes control when your program stops during
      execution (for example, on a breakpoint), and mediates
      communications with GDB on the host machine.  This is where the
      communications protocol is implemented; `handle_exception' acts as
@@ skipping 107 matching lines @@
 ------------------------------
 
 In summary, when your program is ready to debug, you must follow these
 steps.
 
   1. Make sure you have defined the supporting low-level routines
      (*note What You Must Do for the Stub: Bootstrapping.):
           `getDebugChar', `putDebugChar',
           `flush_i_cache', `memset', `exceptionHandler'.
 
-  2. Insert these lines near the top of your program:
+  2. Insert these lines in your program's startup code, before the main
+     procedure is called:
 
           set_debug_traps();
           breakpoint();
 
+     On some machines, when a breakpoint trap is raised, the hardware
+     automatically makes the PC point to the instruction after the
+     breakpoint.  If your machine doesn't do that, you may need to
+     adjust `handle_exception' to arrange for it to return to the
+     instruction after the breakpoint on this first invocation, so that
+     your program doesn't keep hitting the initial breakpoint instead
+     of making progress.
+
   3. For the 680x0 stub only, you need to provide a variable called
      `exceptionHook'.  Normally you just use:
 
           void (*exceptionHook)() = 0;
 
      but if before calling `set_debug_traps', you set it to point to a
      function in your program, that function is called when `GDB'
      continues after stopping on a trap (for example, bus error).  The
      function indicated by `exceptionHook' is called with one
      parameter: an `int' which is the exception number.
@@ skipping 893 matching lines @@
      about acceptable commands.
 
 * Menu:
 
 * ARM::                         ARM RDI
 * M32R/D::                      Renesas M32R/D
 * M68K::                        Motorola M68K
 * MicroBlaze::                  Xilinx MicroBlaze
 * MIPS Embedded::               MIPS Embedded
 * OpenRISC 1000::               OpenRisc 1000
+* PowerPC Embedded::            PowerPC Embedded
 * PA::                          HP PA Embedded
-* PowerPC Embedded::            PowerPC Embedded
 * Sparclet::                    Tsqware Sparclet
 * Sparclite::                   Fujitsu Sparclite
 * Z8000::                       Zilog Z8000
 * AVR::                         Atmel AVR
 * CRIS::                        CRIS
 * Super-H::                     Renesas Super-H
 
 
 File: gdb.info,  Node: ARM,  Next: M32R/D,  Up: Embedded Processors
 
@@ skipping 248 matching lines @@
      Show MicroBlaze-specific debugging level.
 
 
 File: gdb.info,  Node: MIPS Embedded,  Next: OpenRISC 1000,  Prev: MicroBlaze,  Up: Embedded Processors
 
 21.3.5 MIPS Embedded
 --------------------
 
 GDB can use the MIPS remote debugging protocol to talk to a MIPS board
 attached to a serial line.  This is available when you configure GDB
-with `--target=mips-idt-ecoff'.
+with `--target=mips-elf'.
 
    Use these GDB commands to specify the connection to your target
 board:
 
 `target mips PORT'
      To run a program on the board, start up `gdb' with the name of
      your program as the argument.  To connect to the board, use the
      command `target mips PORT', where PORT is the name of the serial
      port connected to the board.  If the program has not already been
      downloaded to the board, you may use the `load' command to
@@ skipping 61 matching lines @@
 `set retransmit-timeout SECONDS'
 `show timeout'
 `show retransmit-timeout'
      You can control the timeout used while waiting for a packet, in
      the MIPS remote protocol, with the `set timeout SECONDS' command.
      The default is 5 seconds.  Similarly, you can control the timeout
      used while waiting for an acknowledgment of a packet with the `set
      retransmit-timeout SECONDS' command.  The default is 3 seconds.
      You can inspect both values with `show timeout' and `show
      retransmit-timeout'.  (These commands are _only_ available when
-     GDB is configured for `--target=mips-idt-ecoff'.)
+     GDB is configured for `--target=mips-elf'.)
 
      The timeout set by `set timeout' does not apply when GDB is
      waiting for your program to stop.  In that case, GDB waits forever
      because it has no way of knowing how long the program is going to
      run before stopping.
 
 `set syn-garbage-limit NUM'
      Limit the maximum number of characters GDB should ignore when it
      tries to synchronize with the remote target.  The default is 10
      characters.  Setting the limit to -1 means there's no limit.
@@ skipping 25 matching lines @@
      PMON monitor for breakpoint commands.
 
 `show monitor-warnings'
      Show the current setting of printing monitor warnings.
 
 `pmon COMMAND'
      This command allows sending an arbitrary COMMAND string to the
      monitor.  The monitor must be in debug mode for this to work.
 
 
-File: gdb.info,  Node: OpenRISC 1000,  Next: PA,  Prev: MIPS Embedded,  Up: Embedded Processors
+File: gdb.info,  Node: OpenRISC 1000,  Next: PowerPC Embedded,  Prev: MIPS Embedded,  Up: Embedded Processors
 
 21.3.6 OpenRISC 1000
 --------------------
 
 See OR1k Architecture document (`www.opencores.org') for more
 information about platform and commands.
 
 `target jtag jtag://HOST:PORT'
      Connects to remote JTAG server.  JTAG remote server can be either
      an or1ksim or JTAG server, connected via parallel port to the
@@ skipping 84 matching lines @@
      Prints trace buffer, using current record configuration.
 
 `htrace mode continuous'
      Set continuous trace mode.
 
 `htrace mode suspend'
      Set suspend trace mode.
 
 
 
-File: gdb.info,  Node: PowerPC Embedded,  Next: Sparclet,  Prev: PA,  Up: Embedded Processors
+File: gdb.info,  Node: PowerPC Embedded,  Next: PA,  Prev: OpenRISC 1000,  Up: Embedded Processors
 
 21.3.7 PowerPC Embedded
 -----------------------
 
 GDB supports using the DVC (Data Value Compare) register to implement
 in hardware simple hardware watchpoint conditions of the form:
 
      (gdb) watch ADDRESS|VARIABLE \
        if  ADDRESS|VARIABLE == CONSTANT EXPRESSION
 
@@ skipping 75 matching lines @@
      Set the timeout for SDS protocol reads to be NSEC seconds.  The
      default is 2 seconds.
 
 `show sdstimeout'
      Show the current value of the SDS timeout.
 
 `sds COMMAND'
      Send the specified COMMAND string to the SDS monitor.
 
 
-File: gdb.info,  Node: PA,  Next: PowerPC Embedded,  Prev: OpenRISC 1000,  Up: Embedded Processors
+File: gdb.info,  Node: PA,  Next: Sparclet,  Prev: PowerPC Embedded,  Up: Embedded Processors
 
 21.3.8 HP PA Embedded
 ---------------------
 
 `target op50n DEV'
      OP50N monitor, running on an OKI HPPA board.
 
 `target w89k DEV'
      W89K monitor, running on a Winbond HPPA board.
 
 
 
-File: gdb.info,  Node: Sparclet,  Next: Sparclite,  Prev: PowerPC Embedded,  Up: Embedded Processors
+File: gdb.info,  Node: Sparclet,  Next: Sparclite,  Prev: PA,  Up: Embedded Processors
 
 21.3.9 Tsqware Sparclet
 -----------------------
 
 GDB enables developers to debug tasks running on Sparclet targets from
 a Unix host.  GDB uses code that runs on both the Unix host and on the
 Sparclet target.  The program `gdb' is installed and executed on the
 Unix host.
 
 `remotetimeout ARGS'
@@ skipping 213 matching lines @@
 
 
 File: gdb.info,  Node: Super-H,  Prev: CRIS,  Up: Embedded Processors
 
 21.3.14 Renesas Super-H
 -----------------------
 
 For the Renesas Super-H processor, GDB provides these commands:
 
 `regs'
+     This command is deprecated, and `info all-registers' should be
+     used instead.
+
      Show the values of all Super-H registers.
 
 `set sh calling-convention CONVENTION'
      Set the calling-convention used when calling functions from GDB.
      Allowed values are `gcc', which is the default setting, and
      `renesas'.  With the `gcc' setting, functions are called using the
      GCC calling convention.  If the DWARF-2 information of the called
      function specifies that the function follows the Renesas calling
      convention, the function is called using the Renesas calling
      convention.  If the calling convention is set to `renesas', the
@@ skipping 11 matching lines @@
 
 21.4 Architectures
 ==================
 
 This section describes characteristics of architectures that affect all
 uses of GDB with the architecture, both native and cross.
 
 * Menu:
 
 * i386::
-* A29K::
 * Alpha::
 * MIPS::
 * HPPA::               HP PA architecture
 * SPU::                Cell Broadband Engine SPU architecture
 * PowerPC::
 
 
-File: gdb.info,  Node: i386,  Next: A29K,  Up: Architectures
+File: gdb.info,  Node: i386,  Next: Alpha,  Up: Architectures
 
 21.4.1 x86 Architecture-specific Issues
 ---------------------------------------
 
 `set struct-convention MODE'
      Set the convention used by the inferior to return `struct's and
      `union's from functions to MODE.  Possible values of MODE are
      `"pcc"', `"reg"', and `"default"' (the default).  `"default"' or
      `"pcc"' means that `struct's are returned on the stack, while
      `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4,
      or 8 bytes will be returned in a register.
 
 `show struct-convention'
      Show the current setting of the convention to return `struct's
      from functions.
 
 
-File: gdb.info,  Node: A29K,  Next: Alpha,  Prev: i386,  Up: Architectures
+File: gdb.info,  Node: Alpha,  Next: MIPS,  Prev: i386,  Up: Architectures
 
-21.4.2 A29K
------------
-
-`set rstack_high_address ADDRESS'
-     On AMD 29000 family processors, registers are saved in a separate
-     "register stack".  There is no way for GDB to determine the extent
-     of this stack.  Normally, GDB just assumes that the stack is
-     "large enough".  This may result in GDB referencing memory
-     locations that do not exist.  If necessary, you can get around
-     this problem by specifying the ending address of the register
-     stack with the `set rstack_high_address' command.  The argument
-     should be an address, which you probably want to precede with `0x'
-     to specify in hexadecimal.
-
-`show rstack_high_address'
-     Display the current limit of the register stack, on AMD 29000
-     family processors.
-
-
-
-File: gdb.info,  Node: Alpha,  Next: MIPS,  Prev: A29K,  Up: Architectures
-
-21.4.3 Alpha
+21.4.2 Alpha
 ------------
 
 See the following section.
 
 
 File: gdb.info,  Node: MIPS,  Next: HPPA,  Prev: Alpha,  Up: Architectures
 
-21.4.4 MIPS
+21.4.3 MIPS
 -----------
 
 Alpha- and MIPS-based computers use an unusual stack frame, which
 sometimes requires GDB to search backward in the object code to find
 the beginning of a function.
 
    To improve response time (especially for embedded applications, where
 GDB may be restricted to a slow serial line for this search) you may
 want to limit the size of this search, using one of these commands:
 
@@ skipping 30 matching lines @@
 
     `n64'
 
     `eabi32'
 
     `eabi64'
 
 `show mips abi'
      Show the MIPS ABI used by GDB to debug the inferior.
 
+`set mips compression ARG'
+     Tell GDB which MIPS compressed ISA (Instruction Set Architecture)
+     encoding is used by the inferior.  GDB uses this for code
+     disassembly and other internal interpretation purposes.  This
+     setting is only referred to when no executable has been associated
+     with the debugging session or the executable does not provide
+     information about the encoding it uses.  Otherwise this setting is
+     automatically updated from information provided by the executable.
+
+     Possible values of ARG are `mips16' and `micromips'.  The default
+     compressed ISA encoding is `mips16', as executables containing
+     MIPS16 code frequently are not identified as such.
+
+     This setting is "sticky"; that is, it retains its value across
+     debugging sessions until reset either explicitly with this command
+     or implicitly from an executable.
+
+     The compiler and/or assembler typically add symbol table
+     annotations to identify functions compiled for the MIPS16 or
+     microMIPS ISAs.  If these function-scope annotations are present,
+     GDB uses them in preference to the global compressed ISA encoding
+     setting.
+
+`show mips compression'
+     Show the MIPS compressed ISA encoding used by GDB to debug the
+     inferior.
+
 `set mipsfpu'
 `show mipsfpu'
      *Note set mipsfpu: MIPS Embedded.
 
 `set mips mask-address ARG'
      This command determines whether the most-significant 32 bits of
      64-bit MIPS addresses are masked off.  The argument ARG can be
      `on', `off', or `auto'.  The latter is the default setting, which
      lets GDB determine the correct value.
 
@@ skipping 14 matching lines @@
 `set debug mips'
      This command turns on and off debugging messages for the
      MIPS-specific target code in GDB.
 
 `show debug mips'
      Show the current setting of MIPS debugging messages.
 
 
 File: gdb.info,  Node: HPPA,  Next: SPU,  Prev: MIPS,  Up: Architectures
 
-21.4.5 HPPA
+21.4.4 HPPA
 -----------
 
 When GDB is debugging the HP PA architecture, it provides the following
 special commands:
 
 `set debug hppa'
      This command determines whether HPPA architecture-specific
      debugging messages are to be displayed.
 
 `show debug hppa'
      Show whether HPPA debugging messages are displayed.
 
 `maint print unwind ADDRESS'
      This command displays the contents of the unwind table entry at the
      given ADDRESS.
 
 
 
 File: gdb.info,  Node: SPU,  Next: PowerPC,  Prev: HPPA,  Up: Architectures
 
-21.4.6 Cell Broadband Engine SPU architecture
+21.4.5 Cell Broadband Engine SPU architecture
 ---------------------------------------------
 
 When GDB is debugging the Cell Broadband Engine SPU architecture, it
 provides the following special commands:
 
 `info spu event'
      Display SPU event facility status.  Shows current event mask and
      pending event status.
 
 `info spu signal'
@@ skipping 37 matching lines @@
      accessed via the cache.  If an application does not use the
      software-managed cache, this option has no effect.
 
 `show spu auto-flush-cache'
      Show whether to automatically flush the software-managed cache.
 
 
 
 File: gdb.info,  Node: PowerPC,  Prev: SPU,  Up: Architectures
 
-21.4.7 PowerPC
+21.4.6 PowerPC
 --------------
 
 When GDB is debugging the PowerPC architecture, it provides a set of
 pseudo-registers to enable inspection of 128-bit wide Decimal Floating
 Point numbers stored in the floating point registers. These values must
 be stored in two consecutive registers, always starting at an even
 register like `f0' or `f2'.
 
    The pseudo-registers go from `$dl0' through `$dl15', and are formed
 by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2'
@@ skipping 13 matching lines @@
 Print Settings: Print Settings.  Other settings are described here.
 
 * Menu:
 
 * Prompt::                      Prompt
 * Editing::                     Command editing
 * Command History::             Command history
 * Screen Size::                 Screen size
 * Numbers::                     Numbers
 * ABI::                         Configuring the current ABI
+* Auto-loading::                Automatically loading associated files
 * Messages/Warnings::           Optional warnings and messages
 * Debugging Output::            Optional messages about internal happenings
 * Other Misc Settings::         Other Miscellaneous Settings
 
 
 File: gdb.info,  Node: Prompt,  Next: Editing,  Up: Controlling GDB
 
 22.1 Prompt
 ===========
 
@@ skipping 241 matching lines @@
 
 `set radix [BASE]'
 `show radix'
      These commands set and show the default base for both input and
      output of numbers.  `set radix' sets the radix of input and output
      to the same base; without an argument, it resets the radix back to
      its default value of 10.
 
 
 
-File: gdb.info,  Node: ABI,  Next: Messages/Warnings,  Prev: Numbers,  Up: Controlling GDB
+File: gdb.info,  Node: ABI,  Next: Auto-loading,  Prev: Numbers,  Up: Controlling GDB
 
 22.6 Configuring the Current ABI
 ================================
 
 GDB can determine the "ABI" (Application Binary Interface) of your
 application automatically.  However, sometimes you need to override its
 conclusions.  Use these commands to manage GDB's view of the current
 ABI.
 
    One GDB configuration can debug binaries for multiple operating
@@ skipping 52 matching lines @@
      Show the C++ ABI currently in use.
 
 `set cp-abi'
      With no argument, show the list of supported C++ ABI's.
 
 `set cp-abi ABI'
 `set cp-abi auto'
      Set the current C++ ABI to ABI, or return to automatic detection.
 
 
-File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: ABI,  Up: Controlling GDB
-
-22.7 Optional Warnings and Messages
+File: gdb.info,  Node: Auto-loading,  Next: Messages/Warnings,  Prev: ABI,  Up: Controlling GDB
+
+22.7 Automatically loading associated files
+===========================================
+
+GDB sometimes reads files with commands and settings automatically,
+without being explicitly told so by the user.  We call this feature
+"auto-loading".  While auto-loading is useful for automatically adapting
+GDB to the needs of your project, it can sometimes produce unexpected
+results or introduce security risks (e.g., if the file comes from
+untrusted sources).
+
+   Note that loading of these associated files (including the local
+`.gdbinit' file) requires accordingly configured `auto-load safe-path'
+(*note Auto-loading safe path::).
+
+   For these reasons, GDB includes commands and options to let you
+control when to auto-load files and which files should be auto-loaded.
+
+`set auto-load off'
+     Globally disable loading of all auto-loaded files.  You may want
+     to use this command with the `-iex' option (*note Option
+     -init-eval-command::) such as:
+          $ gdb -iex "set auto-load off" untrusted-executable corefile
+
+     Be aware that system init file (*note System-wide configuration::)
+     and init files from your home directory (*note Home Directory Init
+     File::) still get read (as they come from generally trusted
+     directories).  To prevent GDB from auto-loading even those init
+     files, use the `-nx' option (*note Mode Options::), in addition to
+     `set auto-load no'.
+
+`show auto-load'
+     Show whether auto-loading of each specific `auto-load' file(s) is
+     enabled or disabled.
+
+          (gdb) show auto-load
+          gdb-scripts:  Auto-loading of canned sequences of commands scripts is on.
+          libthread-db:  Auto-loading of inferior specific libthread_db is on.
+          local-gdbinit:  Auto-loading of .gdbinit script from current directory
+                          is on.
+          python-scripts:  Auto-loading of Python scripts is on.
+          safe-path:  List of directories from which it is safe to auto-load files
+                      is $debugdir:$datadir/auto-load.
+          scripts-directory:  List of directories from which to load auto-loaded scripts
+                              is $debugdir:$datadir/auto-load.
+
+`info auto-load'
+     Print whether each specific `auto-load' file(s) have been
+     auto-loaded or not.
+
+          (gdb) info auto-load
+          gdb-scripts:
+          Loaded  Script
+          Yes     /home/user/gdb/gdb-gdb.gdb
+          libthread-db:  No auto-loaded libthread-db.
+          local-gdbinit:  Local .gdbinit file "/home/user/gdb/.gdbinit" has been
+                          loaded.
+          python-scripts:
+          Loaded  Script
+          Yes     /home/user/gdb/gdb-gdb.py
+
+   These are various kinds of files GDB can automatically load:
+
+   * *Note objfile-gdb.py file::, controlled by *Note set auto-load
+     python-scripts::.
+
+   * *Note objfile-gdb.gdb file::, controlled by *Note set auto-load
+     gdb-scripts::.
+
+   * *Note dotdebug_gdb_scripts section::, controlled by *Note set
+     auto-load python-scripts::.
+
+   * *Note Init File in the Current Directory::, controlled by *Note
+     set auto-load local-gdbinit::.
+
+   * *Note libthread_db.so.1 file::, controlled by *Note set auto-load
+     libthread-db::.
+
+   These are GDB control commands for the auto-loading:
+
+*Note set auto-load off::.           Disable auto-loading globally.
+*Note show auto-load::.              Show setting of all kinds of files.
+*Note info auto-load::.              Show state of all kinds of files.
+*Note set auto-load gdb-scripts::.   Control for GDB command scripts.
+*Note show auto-load gdb-scripts::.  Show setting of GDB command scripts.
+*Note info auto-load gdb-scripts::.  Show state of GDB command scripts.
+*Note set auto-load                  Control for GDB Python scripts.
+python-scripts::.                    
+*Note show auto-load                 Show setting of GDB Python scripts.
+python-scripts::.                    
+*Note info auto-load                 Show state of GDB Python scripts.
+python-scripts::.                    
+*Note set auto-load                  Control for GDB auto-loaded scripts
+scripts-directory::.                 location.
+*Note show auto-load                 Show GDB auto-loaded scripts
+scripts-directory::.                 location.
+*Note set auto-load local-gdbinit::. Control for init file in the
+                                     current directory.
+*Note show auto-load                 Show setting of init file in the
+local-gdbinit::.                     current directory.
+*Note info auto-load                 Show state of init file in the
+local-gdbinit::.                     current directory.
+*Note set auto-load libthread-db::.  Control for thread debugging
+                                     library.
+*Note show auto-load libthread-db::. Show setting of thread debugging
+                                     library.
+*Note info auto-load libthread-db::. Show state of thread debugging
+                                     library.
+*Note set auto-load safe-path::.     Control directories trusted for
+                                     automatic loading.
+*Note show auto-load safe-path::.    Show directories trusted for
+                                     automatic loading.
+*Note add-auto-load-safe-path::.     Add directory trusted for automatic
+                                     loading.
+
+* Menu:
+
+* Init File in the Current Directory:: `set/show/info auto-load local-gdbinit'
+* libthread_db.so.1 file::             `set/show/info auto-load libthread-db'
+* objfile-gdb.gdb file::               `set/show/info auto-load gdb-script'
+* Auto-loading safe path::             `set/show/info auto-load safe-path'
+* Auto-loading verbose mode::          `set/show debug auto-load'
+*Note Python Auto-loading::.
+
+
+File: gdb.info,  Node: Init File in the Current Directory,  Next: libthread_db.so.1 file,  Up: Auto-loading
+
+22.7.1 Automatically loading init file in the current directory
+---------------------------------------------------------------
+
+By default, GDB reads and executes the canned sequences of commands
+from init file (if any) in the current working directory, see *Note
+Init File in the Current Directory during Startup::.
+
+   Note that loading of this local `.gdbinit' file also requires
+accordingly configured `auto-load safe-path' (*note Auto-loading safe
+path::).
+
+`set auto-load local-gdbinit [on|off]'
+     Enable or disable the auto-loading of canned sequences of commands
+     (*note Sequences::) found in init file in the current directory.
+
+`show auto-load local-gdbinit'
+     Show whether auto-loading of canned sequences of commands from
+     init file in the current directory is enabled or disabled.
+
+`info auto-load local-gdbinit'
+     Print whether canned sequences of commands from init file in the
+     current directory have been auto-loaded.
+
+
+File: gdb.info,  Node: libthread_db.so.1 file,  Next: objfile-gdb.gdb file,  Prev: Init File in the Current Directory,  Up: Auto-loading
+
+22.7.2 Automatically loading thread debugging library
+-----------------------------------------------------
+
+This feature is currently present only on GNU/Linux native hosts.
+
+   GDB reads in some cases thread debugging library from places specific
+to the inferior (*note set libthread-db-search-path::).
+
+   The special `libthread-db-search-path' entry `$sdir' is processed
+without checking this `set auto-load libthread-db' switch as system
+libraries have to be trusted in general.  In all other cases of
+`libthread-db-search-path' entries GDB checks first if `set auto-load
+libthread-db' is enabled before trying to open such thread debugging
+library.
+
+   Note that loading of this debugging library also requires
+accordingly configured `auto-load safe-path' (*note Auto-loading safe
+path::).
+
+`set auto-load libthread-db [on|off]'
+     Enable or disable the auto-loading of inferior specific thread
+     debugging library.
+
+`show auto-load libthread-db'
+     Show whether auto-loading of inferior specific thread debugging
+     library is enabled or disabled.
+
+`info auto-load libthread-db'
+     Print the list of all loaded inferior specific thread debugging
+     libraries and for each such library print list of inferior PIDs
+     using it.
+
+
+File: gdb.info,  Node: objfile-gdb.gdb file,  Next: Auto-loading safe path,  Prev: libthread_db.so.1 file,  Up: Auto-loading
+
+22.7.3 The `OBJFILE-gdb.gdb' file
+---------------------------------
+
+GDB tries to load an `OBJFILE-gdb.gdb' file containing canned sequences
+of commands (*note Sequences::), as long as `set auto-load gdb-scripts'
+is set to `on'.
+
+   Note that loading of this script file also requires accordingly
+configured `auto-load safe-path' (*note Auto-loading safe path::).
+
+   For more background refer to the similar Python scripts auto-loading
+description (*note objfile-gdb.py file::).
+
+`set auto-load gdb-scripts [on|off]'
+     Enable or disable the auto-loading of canned sequences of commands
+     scripts.
+
+`show auto-load gdb-scripts'
+     Show whether auto-loading of canned sequences of commands scripts
+     is enabled or disabled.
+
+`info auto-load gdb-scripts [REGEXP]'
+     Print the list of all canned sequences of commands scripts that
+     GDB auto-loaded.
+
+   If REGEXP is supplied only canned sequences of commands scripts with
+matching names are printed.
+
+
+File: gdb.info,  Node: Auto-loading safe path,  Next: Auto-loading verbose mode,  Prev: objfile-gdb.gdb file,  Up: Auto-loading
+
+22.7.4 Security restriction for auto-loading
+--------------------------------------------
+
+As the files of inferior can come from untrusted source (such as
+submitted by an application user) GDB does not always load any files
+automatically.  GDB provides the `set auto-load safe-path' setting to
+list directories trusted for loading files not explicitly requested by
+user.  Each directory can also be a shell wildcard pattern.
+
+   If the path is not set properly you will see a warning and the file
+will not get loaded:
+
+     $ ./gdb -q ./gdb
+     Reading symbols from /home/user/gdb/gdb...done.
+     warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been
+              declined by your `auto-load safe-path' set
+              to "$debugdir:$datadir/auto-load".
+     warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been
+              declined by your `auto-load safe-path' set
+              to "$debugdir:$datadir/auto-load".
+
+   The list of trusted directories is controlled by the following
+commands:
+
+`set auto-load safe-path [DIRECTORIES]'
+     Set the list of directories (and their subdirectories) trusted for
+     automatic loading and execution of scripts.  You can also enter a
+     specific trusted file.  Each directory can also be a shell
+     wildcard pattern; wildcards do not match directory separator - see
+     `FNM_PATHNAME' for system function `fnmatch' (*note fnmatch:
+     (libc)Wildcard Matching.).  If you omit DIRECTORIES, `auto-load
+     safe-path' will be reset to its default value as specified during
+     GDB compilation.
+
+     The list of directories uses path separator (`:' on GNU and Unix
+     systems, `;' on MS-Windows and MS-DOS) to separate directories,
+     similarly to the `PATH' environment variable.
+
+`show auto-load safe-path'
+     Show the list of directories trusted for automatic loading and
+     execution of scripts.
+
+`add-auto-load-safe-path'
+     Add an entry (or list of entries) the list of directories trusted
+     for automatic loading and execution of scripts.  Multiple entries
+     may be delimited by the host platform path separator in use.
+
+   This variable defaults to what `--with-auto-load-dir' has been
+configured to (*note with-auto-load-dir::).  `$debugdir' and `$datadir'
+substitution applies the same as for *Note set auto-load
+scripts-directory::.  The default `set auto-load safe-path' value can
+be also overriden by GDB configuration option
+`--with-auto-load-safe-path'.
+
+   Setting this variable to `/' disables this security protection,
+corresponding GDB configuration option is
+`--without-auto-load-safe-path'.  This variable is supposed to be set
+to the system directories writable by the system superuser only.  Users
+can add their source directories in init files in their home
+directories (*note Home Directory Init File::).  See also deprecated
+init file in the current directory (*note Init File in the Current
+Directory during Startup::).
+
+   To force GDB to load the files it declined to load in the previous
+example, you could use one of the following ways:
+
+`~/.gdbinit': `add-auto-load-safe-path ~/src/gdb'
+     Specify this trusted directory (or a file) as additional component
+     of the list.  You have to specify also any existing directories
+     displayed by by `show auto-load safe-path' (such as `/usr:/bin' in
+     this example).
+
+`gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...'
+     Specify this directory as in the previous case but just for a
+     single GDB session.
+
+`gdb -iex "set auto-load safe-path /" ...'
+     Disable auto-loading safety for a single GDB session.  This
+     assumes all the files you debug during this GDB session will come
+     from trusted sources.
+
+`./configure --without-auto-load-safe-path'
+     During compilation of GDB you may disable any auto-loading safety.
+     This assumes all the files you will ever debug with this GDB come
+     from trusted sources.
+
+   On the other hand you can also explicitly forbid automatic files
+loading which also suppresses any such warning messages:
+
+`gdb -iex "set auto-load no" ...'
+     You can use GDB command-line option for a single GDB session.
+
+`~/.gdbinit': `set auto-load no'
+     Disable auto-loading globally for the user (*note Home Directory
+     Init File::).  While it is improbable, you could also use system
+     init file instead (*note System-wide configuration::).
+
+   This setting applies to the file names as entered by user.  If no
+entry matches GDB tries as a last resort to also resolve all the file
+names into their canonical form (typically resolving symbolic links)
+and compare the entries again.  GDB already canonicalizes most of the
+filenames on its own before starting the comparison so a canonical form
+of directories is recommended to be entered.
+
+
+File: gdb.info,  Node: Auto-loading verbose mode,  Prev: Auto-loading safe path,  Up: Auto-loading
+
+22.7.5 Displaying files tried for auto-load
+-------------------------------------------
+
+For better visibility of all the file locations where you can place
+scripts to be auto-loaded with inferior -- or to protect yourself
+against accidental execution of untrusted scripts -- GDB provides a
+feature for printing all the files attempted to be loaded.  Both
+existing and non-existing files may be printed.
+
+   For example the list of directories from which it is safe to
+auto-load files (*note Auto-loading safe path::) applies also to
+canonicalized filenames which may not be too obvious while setting it
+up.
+
+     (gdb) set debug auto-load on
+     (gdb) file ~/src/t/true
+     auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
+                for objfile "/tmp/true".
+     auto-load: Updating directories of "/usr:/opt".
+     auto-load: Using directory "/usr".
+     auto-load: Using directory "/opt".
+     warning: File "/tmp/true-gdb.gdb" auto-loading has been declined
+              by your `auto-load safe-path' set to "/usr:/opt".
+
+`set debug auto-load [on|off]'
+     Set whether to print the filenames attempted to be auto-loaded.
+
+`show debug auto-load'
+     Show whether printing of the filenames attempted to be auto-loaded
+     is turned on or off.
+
+
+File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: Auto-loading,  Up: Controlling GDB
+
+22.8 Optional Warnings and Messages
 ===================================
 
 By default, GDB is silent about its inner workings.  If you are running
 on a slow machine, you may want to use the `set verbose' command.  This
 makes GDB tell you when it does a lengthy internal operation, so you
 will not think it has crashed.
 
    Currently, the messages controlled by `set verbose' are those which
 announce that the symbol table for a source file is being read; see
 `symbol-file' in *Note Commands to Specify Files: Files.
@@ skipping 55 matching lines @@
 
 `set trace-commands off'
      Disable command tracing.
 
 `show trace-commands'
      Display the current state of command tracing.
 
 
 File: gdb.info,  Node: Debugging Output,  Next: Other Misc Settings,  Prev: Messages/Warnings,  Up: Controlling GDB
 
-22.8 Optional Messages about Internal Happenings
+22.9 Optional Messages about Internal Happenings
 ================================================
 
 GDB has commands that enable optional debugging messages from various
 GDB subsystems; normally these commands are of interest to GDB
 maintainers, or when reporting a bug.  This section documents those
 commands.
 
 `set exec-done-display'
      Turns on or off the notification of asynchronous commands'
      completion.  When on, GDB will print a message when an
@@ skipping 28 matching lines @@
 `show debug check-physname'
      Show the current state of "physname" checking.
 
 `set debug dwarf2-die'
      Dump DWARF2 DIEs after they are read in.  The value is the number
      of nesting levels to print.  A value of zero turns off the display.
 
 `show debug dwarf2-die'
      Show the current state of DWARF2 DIE debugging.
 
+`set debug dwarf2-read'
+     Turns on or off display of debugging messages related to reading
+     DWARF debug info.  The default is off.
+
+`show debug dwarf2-read'
+     Show the current state of DWARF2 reader debugging.
+
 `set debug displaced'
      Turns on or off display of GDB debugging info for the displaced
      stepping support.  The default is off.
 
 `show debug displaced'
      Displays the current state of displaying GDB debugging info
      related to displaced stepping.
 
 `set debug event'
      Turns on or off display of GDB event debugging info.  The default
@@ skipping 85 matching lines @@
 `show debug serial'
      Displays the current state of displaying GDB serial debugging info.
 
 `set debug solib-frv'
      Turns on or off debugging messages for FR-V shared-library code.
 
 `show debug solib-frv'
      Display the current state of FR-V shared-library code debugging
      messages.
 
+`set debug symtab-create'
+     Turns on or off display of debugging messages related to symbol
+     table creation.  The default is off.
+
+`show debug symtab-create'
+     Show the current state of symbol table creation debugging.
+
 `set debug target'
      Turns on or off display of GDB target debugging info. This info
      includes what is going on at the target level of GDB, as it
      happens. The default is 0.  Set it to 1 to track events, and to 2
      to also track the value of large memory transfers.  Changes to
      this flag do not take effect until the next time you connect to a
      target or use the `run' command.
 
 `show debug target'
      Displays the current state of displaying GDB target debugging info.
@@ skipping 17 matching lines @@
 
 `set debug xml'
      Turns on or off debugging messages for built-in XML parsers.
 
 `show debug xml'
      Displays the current state of XML debugging messages.
 
 
 File: gdb.info,  Node: Other Misc Settings,  Prev: Debugging Output,  Up: Controlling GDB
 
-22.9 Other Miscellaneous Settings
-=================================
+22.10 Other Miscellaneous Settings
+==================================
 
 `set interactive-mode'
      If `on', forces GDB to assume that GDB was started in a terminal.
      In practice, this means that GDB should wait for the user to
      answer queries generated by commands entered at the command
      prompt.  If `off', forces GDB to operate in the opposite mode, and
      it uses the default answers to all queries.  If `auto' (the
      default), GDB tries to determine whether its standard input is a
      terminal, and works in interactive-mode if it is,
      non-interactively otherwise.
@@ skipping 128 matching lines @@
      You may use the `document' command again to change the
      documentation of a command.  Redefining the command with `define'
      does not change the documentation.
 
 `dont-repeat'
      Used inside a user-defined command, this tells GDB that this
      command should not be repeated when the user hits <RET> (*note
      repeat last command: Command Syntax.).
 
 `help user-defined'
-     List all user-defined commands, with the first line of the
-     documentation (if any) for each.
+     List all user-defined commands and all python commands defined in
+     class COMAND_USER.  The first line of the documentation or
+     docstring is included (if any).
 
 `show user'
 `show user COMMANDNAME'
      Display the GDB commands used to define COMMANDNAME (but not its
      documentation).  If no COMMANDNAME is given, display the
-     definitions for all user-defined commands.
+     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.
+     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
@@ skipping 321 matching lines @@
    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.
-* Auto-loading::                Automatically loading Python code.
+* Python Auto-loading::         Automatically loading Python code.
 * Python modules::              Python modules provided by GDB.
 
 
 File: gdb.info,  Node: Python Commands,  Next: Python API,  Up: Python
 
 23.2.1 Python Commands
 ----------------------
 
 GDB provides one command for accessing the Python interpreter, and one
 related setting:
@@ skipping 35 matching lines @@
      The script name must end with `.py' and GDB must be configured to
      recognize the script language based on filename extension using
      the `script-extension' setting.  *Note Extending GDB: Extending
      GDB.
 
 `python execfile ("script-name")'
      This method is based on the `execfile' Python built-in function,
      and thus is always available.
 
 
-File: gdb.info,  Node: Python API,  Next: Auto-loading,  Prev: Python Commands,  Up: Python
+File: gdb.info,  Node: Python API,  Next: Python Auto-loading,  Prev: Python Commands,  Up: Python
 
 23.2.2 Python API
 -----------------
 
 At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to
 print using GDB's output-paging streams.  A Python program which
 outputs to one of these streams may have its output interrupted by the
 user (*note Screen Size::).  In this situation, a Python
 `KeyboardInterrupt' exception is thrown.
 
@@ skipping 11 matching lines @@
 * Threads In Python::           Accessing inferior threads from Python.
 * Commands In Python::          Implementing new commands in Python.
 * Parameters In Python::        Adding new GDB parameters.
 * Functions In Python::         Writing new convenience functions.
 * Progspaces In Python::        Program spaces.
 * Objfiles In Python::          Object files.
 * Frames In Python::            Accessing inferior stack frames from Python.
 * Blocks In Python::            Accessing frame blocks from Python.
 * Symbols In Python::           Python representation of symbols.
 * Symbol Tables In Python::     Python representation of symbol tables.
-* Lazy Strings In Python::      Python representation of lazy strings.
 * Breakpoints In Python::       Manipulating breakpoints using Python.
 * Finish Breakpoints in Python:: Setting Breakpoints on function return
                                 using Python.
+* Lazy Strings In Python::      Python representation of lazy strings.
 
 
 File: gdb.info,  Node: Basic Python,  Next: Exception Handling,  Up: Python API
 
 23.2.2.1 Basic Python
 .....................
 
 GDB introduces a new Python module, named `gdb'.  All methods and
 classes added by GDB are placed in this module.  GDB automatically
 `import's the `gdb' module for use in all scripts evaluated by the
@@ skipping 50 matching lines @@
      Parse EXPRESSION as an expression in the current language,
      evaluate it, and return the result as a `gdb.Value'.  EXPRESSION
      must be a string.
 
      This function can be useful when implementing a new command (*note
      Commands In Python::), as it provides a way to parse the command's
      argument as an expression.  It is also useful simply to compute
      values, for example, it is the only way to get the value of a
      convenience variable (*note Convenience Vars::) as a `gdb.Value'.
 
+ -- Function: gdb.find_pc_line (pc)
+     Return the `gdb.Symtab_and_line' object corresponding to the PC
+     value.  *Note Symbol Tables In Python::.  If an invalid value of
+     PC is passed as an argument, then the `symtab' and `line'
+     attributes of the returned `gdb.Symtab_and_line' object will be
+     `None' and 0 respectively.
+
  -- Function: gdb.post_event (event)
      Put EVENT, a callable object taking no arguments, into GDB's
      internal event queue.  This callable will be invoked at some later
      point, during GDB's event processing.  Events posted using
      `post_event' will be run in the order in which they were posted;
      however, there is no way to know when they will be processed
      relative to other events inside GDB.
 
      GDB is not thread-safe.  If your Python program uses multiple
      threads, you must be careful to only call GDB-specific functions
@@ skipping 145 matching lines @@
    When implementing GDB commands in Python via `gdb.Command', it is
 useful to be able to throw an exception that doesn't cause a traceback
 to be printed.  For example, the user may have invoked the command
 incorrectly.  Use the `gdb.GdbError' exception to handle this case.
 Example:
 
      (gdb) python
      >class HelloWorld (gdb.Command):
      >  """Greet the whole world."""
      >  def __init__ (self):
-     >    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+     >    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
 
@@ skipping 132 matching lines @@
                int *foo;
 
           then you can use the corresponding `gdb.Value' to access what
           `foo' points to like this:
 
                bar = foo.dereference ()
 
           The result `bar' will be a `gdb.Value' object holding the
           value pointed to by `foo'.
 
+          A similar function `Value.referenced_value' exists which also
+          returns `gdb.Value' objects corresonding to the values
+          pointed to by pointer values (and additionally, values
+          referenced by reference values).  However, the behavior of
+          `Value.dereference' differs from `Value.referenced_value' by
+          the fact that the behavior of `Value.dereference' is
+          identical to applying the C unary operator `*' on a given
+          value.  For example, consider a reference to a pointer
+          `ptrref', declared in your C++ program as
+
+               typedef int *intptr;
+               ...
+               int val = 10;
+               intptr ptr = &val;
+               intptr &ptrref = ptr;
+
+          Though `ptrref' is a reference value, one can apply the method
+          `Value.dereference' to the `gdb.Value' object corresponding
+          to it and obtain a `gdb.Value' which is identical to that
+          corresponding to `val'.  However, if you apply the method
+          `Value.referenced_value', the result would be a `gdb.Value'
+          object identical to that corresponding to `ptr'.
+
+               py_ptrref = gdb.parse_and_eval ("ptrref")
+               py_val = py_ptrref.dereference ()
+               py_ptr = py_ptrref.referenced_value ()
+
+          The `gdb.Value' object `py_val' is identical to that
+          corresponding to `val', and `py_ptr' is identical to that
+          corresponding to `ptr'.  In general, `Value.dereference' can
+          be applied whenever the C unary operator `*' can be applied
+          to the corresponding C value.  For those cases where applying
+          both `Value.dereference' and `Value.referenced_value' is
+          allowed, the results obtained need not be identical (as we
+          have seen in the above example).  The results are however
+          identical when applied on `gdb.Value' objects corresponding
+          to pointers (`gdb.Value' objects with type code
+          `TYPE_CODE_PTR') in a C/C++ program.
+
+      -- Function: Value.referenced_value ()
+          For pointer or reference data types, this method returns a new
+          `gdb.Value' object corresponding to the value referenced by
+          the pointer/reference value.  For pointer data types,
+          `Value.dereference' and `Value.referenced_value' produce
+          identical results.  The difference between these methods is
+          that `Value.dereference' cannot get the values referenced by
+          reference values.  For example, consider a reference to an
+          `int', declared in your C++ program as
+
+               int val = 10;
+               int &ref = val;
+
+          then applying `Value.dereference' to the `gdb.Value' object
+          corresponding to `ref' will result in an error, while applying
+          `Value.referenced_value' will result in a `gdb.Value' object
+          identical to that corresponding to `val'.
+
+               py_ref = gdb.parse_and_eval ("ref")
+               er_ref = py_ref.dereference ()       # Results in error
+               py_val = py_ref.referenced_value ()  # Returns the referenced value
+
+          The `gdb.Value' object `py_val' is identical to that
+          corresponding to `val'.
+
       -- Function: Value.dynamic_cast (type)
           Like `Value.cast', but works as if the C++ `dynamic_cast'
           operator were used.  Consult a C++ reference for details.
 
       -- Function: Value.reinterpret_cast (type)
           Like `Value.cast', but works as if the C++ `reinterpret_cast'
           operator were used.  Consult a C++ reference for details.
 
       -- Function: Value.string ([encoding[, errors[, length]]])
           If this `gdb.Value' represents a string, then this method
@@ skipping 492 matching lines @@
 printer can pretty-print, it will return a printer object.  If not, it
 returns `None'.
 
    We recommend that you put your core pretty-printers into a Python
 package.  If your pretty-printers are for use with a library, we
 further recommend embedding a version number into the package name.
 This practice will enable GDB to load multiple versions of your
 pretty-printers at the same time, because they will have different
 names.
 
-   You should write auto-loaded code (*note Auto-loading::) such that it
-can be evaluated multiple times without changing its meaning.  An ideal
-auto-load file will consist solely of `import's of your printer
-modules, followed by a call to a register pretty-printers with the
-current objfile.
+   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.
 
@@ skipping 127 matching lines @@
 
       -- Function: Inferior.threads ()
           This method returns a tuple holding all the threads which are
           valid when it is called.  If there are no valid threads, the
           method will return an empty tuple.
 
       -- Function: Inferior.read_memory (address, length)
           Read LENGTH bytes of memory from the inferior, starting at
           ADDRESS.  Returns a buffer object, which behaves much like an
           array or a string.  It can be modified and given to the
-          `gdb.write_memory' function.
+          `Inferior.write_memory' function.
 
       -- Function: Inferior.write_memory (address, buffer [, length])
           Write the contents of BUFFER to the inferior, starting at
           ADDRESS.  The BUFFER parameter must be a Python object which
           supports the buffer protocol, i.e., a string, an array or the
-          object returned from `gdb.read_memory'.  If given, LENGTH
+          object returned from `Inferior.read_memory'.  If given, LENGTH
           determines the number of bytes from BUFFER to be written.
 
       -- Function: Inferior.search_memory (address, length, pattern)
           Search a region of the inferior memory starting at ADDRESS
           with the given LENGTH using the search pattern supplied in
           PATTERN.  The PATTERN parameter must be a Python object which
           supports the buffer protocol, i.e., a string, an array or the
           object returned from `gdb.read_memory'.  Returns a Python
           `Long' containing the address where the pattern was found, or
           `None' if the pattern could not be found.
@@ skipping 339 matching lines @@
      `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
@@ skipping 22 matching lines @@
      This constant means that completion should be done using symbol
      names as the source.
 
    The following code snippet shows how a trivial CLI command can be
 implemented in Python:
 
      class HelloWorld (gdb.Command):
        """Greet the whole world."""
 
        def __init__ (self):
-         super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+         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.
 
@@ skipping 225 matching lines @@
 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 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'.
+     When auto-loading a Python script (*note Python Auto-loading::),
+     GDB sets the "current objfile" to the corresponding objfile.  This
+     function returns the current objfile.  If there is no current
+     objfile, this function returns `None'.
 
  -- Function: gdb.objfiles ()
      Return a sequence of all the objfiles current known to GDB.  *Note
      Objfiles In Python::.
 
    Each objfile is represented by an instance of the `gdb.Objfile'
 class.
 
  -- Variable: Objfile.filename
      The file name of the objfile as a string.
@@ skipping 180 matching lines @@
 23.2.2.17 Accessing frame blocks from Python.
 .............................................
 
 Within each frame, GDB maintains information on each block stored in
 that frame.  These blocks are organized hierarchically, and are
 represented individually in Python as a `gdb.Block'.  Please see *Note
 Frames In Python::, for a more in-depth discussion on frames.
 Furthermore, see *Note Examining the Stack: Stack, for more detailed
 technical information on GDB's book-keeping of the stack.
 
+   A `gdb.Block' is iterable.  The iterator returns the symbols (*note
+Symbols In Python::) local to the block.  Python programs should not
+assume that a specific block object will always contain a given symbol,
+since changes in GDB features and infrastructure may cause symbols move
+across blocks in a symbol table.
+
    The following block-related functions are available in the `gdb'
 module:
 
  -- Function: gdb.block_for_pc (pc)
      Return the `gdb.Block' containing the given PC value.  If the
      block cannot be found for the PC value specified, the function
      will return `None'.
 
    A `gdb.Block' object has the following methods:
 
       -- Function: Block.is_valid ()
           Returns `True' if the `gdb.Block' object is valid, `False' if
           not.  A block object can become invalid if the block it
           refers to doesn't exist anymore in the inferior.  All other
           `gdb.Block' methods will throw an exception if it is invalid
-          at the time the method is called.  This method is also made
-          available to the Python iterator object that `gdb.Block'
-          provides in an iteration context and via the Python `iter'
-          built-in function.
+          at the time the method is called.  The block's validity is
+          also checked during iteration over symbols of the block.
 
    A `gdb.Block' object has the following attributes:
 
       -- Variable: Block.start
           The start address of the block.  This attribute is not
           writable.
 
       -- Variable: Block.end
           The end address of the block.  This attribute is not writable.
 
@@ skipping 73 matching lines @@
       -- 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
@@ skipping 63 matching lines @@
      to be determined from the minimal symbol table whenever the
      variable is referenced.  
 
 `gdb.SYMBOL_LOC_OPTIMIZED_OUT'
      The value does not actually exist in the program.  
 
 `gdb.SYMBOL_LOC_COMPUTED'
      The value's address is a computed location.
 
 
-File: gdb.info,  Node: Symbol Tables In Python,  Next: Lazy Strings In Python,  Prev: Symbols In Python,  Up: Python API
+File: gdb.info,  Node: Symbol Tables In Python,  Next: Breakpoints In Python,  Prev: Symbols In Python,  Up: Python API
 
 23.2.2.19 Symbol table representation in Python.
 ................................................
 
 Access to symbol table data maintained by GDB on the inferior is
 exposed to Python via two objects: `gdb.Symtab_and_line' and
 `gdb.Symtab'.  Symbol table and line data for a frame is returned from
 the `find_sal' method in `gdb.Frame' object.  *Note Frames In Python::.
 
    For more information on GDB's symbol table management, see *Note
 Examining the Symbol Table: Symbols, for more information.
 
    A `gdb.Symtab_and_line' object has the following attributes:
 
       -- Variable: Symtab_and_line.symtab
           The symbol table object (`gdb.Symtab') for this frame.  This
           attribute is not writable.
 
       -- Variable: Symtab_and_line.pc
-          Indicates the current program counter address.  This
-          attribute is not writable.
+          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
@@ skipping 17 matching lines @@
       -- Function: Symtab.is_valid ()
           Returns `True' if the `gdb.Symtab' object is valid, `False'
           if not.  A `gdb.Symtab' object can become invalid if the
           symbol table it refers to does not exist in GDB any longer.
           All other `gdb.Symtab' methods will throw an exception if it
           is invalid at the time the method is called.
 
       -- Function: Symtab.fullname ()
           Return the symbol table's source absolute file name.
 
+      -- Function: Symtab.global_block ()
+          Return the global block of the underlying symbol table.
+          *Note Blocks In Python::.
+
+      -- Function: Symtab.static_block ()
+          Return the static block of the underlying symbol table.
+          *Note Blocks In Python::.
+
 
-File: gdb.info,  Node: Breakpoints In Python,  Next: Finish Breakpoints in Python,  Prev: Lazy Strings In Python,  Up: Python API
+File: gdb.info,  Node: Breakpoints In Python,  Next: Finish Breakpoints in Python,  Prev: Symbol Tables In Python,  Up: Python API
 
 23.2.2.20 Manipulating breakpoints using Python
 ...............................................
 
 Python code can manipulate breakpoints via the `gdb.Breakpoint' class.
 
  -- Function: Breakpoint.__init__ (spec [, type [, wp_class
           [,internal]]])
      Create a new breakpoint.  SPEC is a string naming the location of
      the breakpoint, or an expression that defines a watchpoint.  The
@@ skipping 149 matching lines @@
      by the user.  It is a string.  If there is no condition, this
      attribute's value is `None'.  This attribute is writable.
 
  -- Variable: Breakpoint.commands
      This attribute holds the commands attached to the breakpoint.  If
      there are commands, this attribute's value is a string holding all
      the commands, separated by newlines.  If there are no commands,
      this attribute is `None'.  This attribute is not writable.
 
 
-File: gdb.info,  Node: Finish Breakpoints in Python,  Prev: Breakpoints In Python,  Up: Python API
+File: gdb.info,  Node: Finish Breakpoints in Python,  Next: Lazy Strings In Python,  Prev: Breakpoints In Python,  Up: Python API
 
 23.2.2.21 Finish Breakpoints
 ............................
 
 A finish breakpoint is a temporary breakpoint set at the return address
 of a frame, based on the `finish' command.  `gdb.FinishBreakpoint'
 extends `gdb.Breakpoint'.  The underlying breakpoint will be disabled
 and deleted when the execution will run out of the breakpoint scope
 (i.e.  `Breakpoint.stop' or `FinishBreakpoint.out_of_scope' triggered).
 Finish breakpoints are thread specific and must be create with the right
@@ skipping 25 matching lines @@
 
  -- 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: Breakpoints In Python,  Prev: Symbol Tables In Python,  Up: Python API
+File: gdb.info,  Node: Lazy Strings In Python,  Prev: Finish Breakpoints in Python,  Up: Python API
 
 23.2.2.22 Python representation of lazy strings.
 ................................................
 
 A "lazy string" is a string whose contents is not retrieved or encoded
 until it is needed.
 
    A `gdb.LazyString' is represented in GDB as an `address' that points
 to a region of memory, an `encoding' that will be used to encode that
 region of memory, and a `length' to delimit the region of memory that
@@ skipping 29 matching lines @@
      is not writable.
 
  -- Variable: LazyString.type
      This attribute holds the type that is represented by the lazy
      string's type.  For a lazy string this will always be a pointer
      type.  To resolve this to the lazy string's character type, use
      the type's `target' method.  *Note Types In Python::.  This
      attribute is not writable.
 
 
-File: gdb.info,  Node: Auto-loading,  Next: Python modules,  Prev: Python API,  Up: Python
+File: gdb.info,  Node: Python Auto-loading,  Next: Python modules,  Prev: Python API,  Up: Python
 
-23.2.3 Auto-loading
--------------------
+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.
-
-* Menu:
-
-* objfile-gdb.py file::         The `OBJFILE-gdb.py' file
-* .debug_gdb_scripts section::  The `.debug_gdb_scripts' section
-* Which flavor to choose?::
+Python support scripts in several ways: `OBJFILE-gdb.py' (*note
+objfile-gdb.py file::) and `.debug_gdb_scripts' section (*note
+dotdebug_gdb_scripts section::).
 
    The auto-loading feature is useful for supplying application-specific
 debugging commands and scripts.
 
    Auto-loading can be enabled or disabled, and the list of auto-loaded
 scripts can be printed.
 
-`set auto-load-scripts [yes|no]'
+`set auto-load python-scripts [on|off]'
      Enable or disable the auto-loading of Python scripts.
 
-`show auto-load-scripts'
+`show auto-load python-scripts'
      Show whether auto-loading of Python scripts is enabled or disabled.
 
-`info auto-load-scripts [REGEXP]'
-     Print the list of all scripts that GDB auto-loaded.
+`info auto-load python-scripts [REGEXP]'
+     Print the list of all Python scripts that GDB auto-loaded.
 
-     Also printed is the list of scripts that were mentioned in the
-     `.debug_gdb_scripts' section and were not found (*note
-     .debug_gdb_scripts section::).  This is useful because their names
-     are not printed when GDB tries to load them and fails.  There may
-     be many of them, and printing an error message for each one is
-     problematic.
+     Also printed is the list of Python scripts that were mentioned in
+     the `.debug_gdb_scripts' section and were not found (*note
+     dotdebug_gdb_scripts section::).  This is useful because their
+     names are not printed when GDB tries to load them and fails.
+     There may be many of them, and printing an error message for each
+     one is problematic.
 
-     If REGEXP is supplied only scripts with matching names are printed.
+     If REGEXP is supplied only Python scripts with matching names are
+     printed.
 
      Example:
 
-          (gdb) info auto-load-scripts
-          Loaded  Script
-          Yes     py-section-script.py
-                  full name: /tmp/py-section-script.py
-          Missing my-foo-pretty-printers.py
+          (gdb) info auto-load python-scripts
+          Loaded Script
+          Yes    py-section-script.py
+                 full name: /tmp/py-section-script.py
+          No     my-foo-pretty-printers.py
 
    When reading an auto-loaded file, GDB sets the "current objfile".
 This is available via the `gdb.current_objfile' function (*note
 Objfiles In Python::).  This can be useful for registering
 objfile-specific pretty-printers.
 
-
-File: gdb.info,  Node: objfile-gdb.py file,  Next: .debug_gdb_scripts section,  Up: Auto-loading
-
-23.2.3.1 The `OBJFILE-gdb.py' file
-..................................
-
-When a new object file is read, GDB looks for a file named
-`OBJFILE-gdb.py', where OBJFILE is the object file's real name, formed
-by ensuring that the file name is absolute, following all symlinks, and
-resolving `.' and `..' components.  If this file exists and is
-readable, GDB will evaluate it as a Python script.
-
-   If this file does not exist, and if the parameter
-`debug-file-directory' is set (*note Separate Debug Files::), then GDB
-will look for REAL-NAME in all of the directories mentioned in the
-value of `debug-file-directory'.
-
-   Finally, if this file does not exist, then GDB will look for a file
-named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY
-is GDB's data directory (available via `show data-directory', *note
-Data Files::), and REAL-NAME is the object file's real name, as
-described above.
-
-   GDB does not track which files it has already auto-loaded this way.
-GDB will load the associated script every time the corresponding
-OBJFILE is opened.  So your `-gdb.py' file should be careful to avoid
-errors if it is evaluated more than once.
-
-
-File: gdb.info,  Node: .debug_gdb_scripts section,  Next: Which flavor to choose?,  Prev: objfile-gdb.py file,  Up: Auto-loading
-
-23.2.3.2 The `.debug_gdb_scripts' section
-.........................................
-
-For systems using file formats like ELF and COFF, when GDB loads a new
-object file it will look for a special section named
-`.debug_gdb_scripts'.  If this section exists, its contents is a list
-of names of scripts to load.
-
-   GDB will look for each specified script file first in the current
-directory and then along the source search path (*note Specifying
-Source Directories: Source Path.), except that `$cdir' is not searched,
-since the compilation directory is not relevant to scripts.
-
-   Entries can be placed in section `.debug_gdb_scripts' with, for
-example, this GCC macro:
-
-     /* Note: The "MS" section flags are to remove duplicates.  */
-     #define DEFINE_GDB_SCRIPT(script_name) \
-       asm("\
-     .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\
-     .byte 1\n\
-     .asciz \"" script_name "\"\n\
-     .popsection \n\
-     ");
-
-Then one can reference the macro in a header or source file like this:
-
-     DEFINE_GDB_SCRIPT ("my-app-scripts.py")
-
-   The script name may include directories if desired.
-
-   If the macro is put in a header, any application or library using
-this header will get a reference to the specified script.
-
-
-File: gdb.info,  Node: Which flavor to choose?,  Prev: .debug_gdb_scripts section,  Up: Auto-loading
-
-23.2.3.3 Which flavor to choose?
-................................
-
-Given the multiple ways of auto-loading Python scripts, it might not
-always be clear which one to choose.  This section provides some
-guidance.
-
-   Benefits of the `-gdb.py' way:
-
-   * Can be used with file formats that don't support multiple sections.
-
-   * Ease of finding scripts for public libraries.
-
-     Scripts specified in the `.debug_gdb_scripts' section are searched
-     for in the source search path.  For publicly installed libraries,
-     e.g., `libstdc++', there typically isn't a source directory in
-     which to find the script.
-
-   * Doesn't require source code additions.
-
-   Benefits of the `.debug_gdb_scripts' way:
-
-   * Works with static linking.
-
-     Scripts for libraries done the `-gdb.py' way require an objfile to
-     trigger their loading.  When an application is statically linked
-     the only objfile available is the executable, and it is cumbersome
-     to attach all the scripts from all the input libraries to the
-     executable's `-gdb.py' script.
-
-   * Works with classes that are entirely inlined.
-
-     Some classes can be entirely inlined, and thus there may not be an
-     associated shared library to attach a `-gdb.py' script to.
-
-   * Scripts needn't be copied out of the source tree.
-
-     In some circumstances, apps can be built out of large collections
-     of internal libraries, and the build infrastructure necessary to
-     install the `-gdb.py' scripts in a place where GDB can find them is
-     cumbersome.  It may be easier to specify the scripts in the
-     `.debug_gdb_scripts' section as relative paths, and add a path to
-     the top of the source tree to the source search path.
-
-
-File: gdb.info,  Node: Python modules,  Prev: 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.
+* objfile-gdb.py file::          The `OBJFILE-gdb.py' file
+* dotdebug_gdb_scripts section:: The `.debug_gdb_scripts' section
+* Which flavor to choose?::
 
-
-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.
-
-`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.Types' 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']}
-
-
-
-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,
-                             print arguments: \p{print frame-arguments}'')
-
-will return the string:
-
-
-          "frame: main, print arguments: scalars"
-
-
-File: gdb.info,  Node: Aliases,  Prev: Python,  Up: Extending GDB
-
-23.3 Creating new spellings of existing commands
-================================================
-
-It is often useful to define alternate spellings of existing commands.
-For example, if a new GDB command defined in Python has a long name to
-type, it is handy to have an abbreviated version of it that involves
-less typing.
-
-   GDB itself uses aliases.  For example `s' is an alias of the `step'
-command even though it is otherwise an ambiguous abbreviation of other
-commands like `set' and `show'.
-
-   Aliases are also used to provide shortened or more common versions
-of multi-word commands.  For example, GDB provides the `tty' alias of
-the `set inferior-tty' command.
-
-   You can define a new alias with the `alias' command.
-
-`alias [-a] [--] ALIAS = COMMAND'
-
-   ALIAS specifies the name of the new alias.  Each word of ALIAS must
-consist of letters, numbers, dashes and underscores.
-
-   COMMAND specifies the name of an existing command that is being
-aliased.
-
-   The `-a' option specifies that the new alias is an abbreviation of
-the command.  Abbreviations are not shown in command lists displayed by
-the `help' command.
-
-   The `--' option specifies the end of options, and is useful when
-ALIAS begins with a dash.
-
-   Here is a simple example showing how to make an abbreviation of a
-command so that there is less to type.  Suppose you were tired of
-typing `disas', the current shortest unambiguous abbreviation of the
-`disassemble' command and you wanted an even shorter version named `di'.
-The following will accomplish this.
-
-     (gdb) alias -a di = disas
-
-   Note that aliases are different from user-defined commands.  With a
-user-defined command, you also need to write documentation for it with
-the `document' command.  An alias automatically picks up the
-documentation of the existing command.
-
-   Here is an example where we make `elms' an abbreviation of
-`elements' in the `set print elements' command.  This is to show that
-you can make an abbreviation of any part of a command.
-
-     (gdb) alias -a set print elms = set print elements
-     (gdb) alias -a show print elms = show print elements
-     (gdb) set p elms 20
-     (gdb) show p elms
-     Limit on string chars or array elements to print is 200.
-
-   Note that if you are defining an alias of a `set' command, and you
-want to have an alias for the corresponding `show' command, then you
-need to define the latter separately.
-
-   Unambiguously abbreviated commands are allowed in COMMAND and ALIAS,
-just as they are normally.
-
-     (gdb) alias -a set pr elms = set p ele
-
-   Finally, here is an example showing the creation of a one word alias
-for a more complex command.  This creates alias `spe' of the command
-`set print elements'.
-
-     (gdb) alias spe = set print elements
-     (gdb) spe 20
-
-
-File: gdb.info,  Node: Interpreters,  Next: TUI,  Prev: Extending GDB,  Up: Top
-
-24 Command Interpreters
-***********************
-
-GDB supports multiple command interpreters, and some command
-infrastructure to allow users or user interface writers to switch
-between interpreters or run commands in other interpreters.
-
-   GDB currently supports two command interpreters, the console
-interpreter (sometimes called the command-line interpreter or CLI) and
-the machine interface interpreter (or GDB/MI).  This manual describes
-both of these interfaces in great detail.
-
-   By default, GDB will start with the console interpreter.  However,
-the user may choose to start GDB with another interpreter by specifying
-the `-i' or `--interpreter' startup options.  Defined interpreters
-include:
-
-`console'
-     The traditional console or command-line interpreter.  This is the
-     most often used interpreter with GDB. With no interpreter
-     specified at runtime, GDB will use this interpreter.
-
-`mi'
-     The newest GDB/MI interface (currently `mi2').  Used primarily by
-     programs wishing to use GDB as a backend for a debugger GUI or an
-     IDE.  For more information, see *Note The GDB/MI Interface: GDB/MI.
-
-`mi2'
-     The current GDB/MI interface.
-
-`mi1'
-     The GDB/MI interface included in GDB 5.1, 5.2, and 5.3.
-
-
-   The interpreter being used by GDB may not be dynamically switched at
-runtime.  Although possible, this could lead to a very precarious
-situation.  Consider an IDE using GDB/MI.  If a user enters the command
-"interpreter-set console" in a console view, GDB would switch to using
-the console interpreter, rendering the IDE inoperable!
-
-   Although you may only choose a single interpreter at startup, you
-may execute commands in any interpreter from the current interpreter
-using the appropriate command.  If you are running the console
-interpreter, simply use the `interpreter-exec' command:
-
-     interpreter-exec mi "-data-list-register-names"
-
-   GDB/MI has a similar command, although it is only available in
-versions of GDB which support GDB/MI version 2 (or greater).
-
-
-File: gdb.info,  Node: TUI,  Next: Emacs,  Prev: Interpreters,  Up: Top
-
-25 GDB Text User Interface
-**************************
-
-* Menu:
-
-* TUI Overview::                TUI overview
-* TUI Keys::                    TUI key bindings
-* TUI Single Key Mode::         TUI single key mode
-* TUI Commands::                TUI-specific commands
-* TUI Configuration::           TUI configuration variables
-
-   The GDB Text User Interface (TUI) is a terminal interface which uses
-the `curses' library to show the source file, the assembly output, the
-program registers and GDB commands in separate text windows.  The TUI
-mode is supported only on platforms where a suitable version of the
-`curses' library is available.
-
-   The TUI mode is enabled by default when you invoke GDB as either
-`gdbtui' or `gdb -tui'.  You can also switch in and out of TUI mode
-while GDB runs by using various TUI commands and key bindings, such as
-`C-x C-a'.  *Note TUI Key Bindings: TUI Keys.
-
-
-File: gdb.info,  Node: TUI Overview,  Next: TUI Keys,  Up: TUI
-
-25.1 TUI Overview
-=================
-
-In TUI mode, GDB can display several text windows:
-
-_command_
-     This window is the GDB command window with the GDB prompt and the
-     GDB output.  The GDB input is still managed using readline.
-
-_source_
-     The source window shows the source file of the program.  The
-     current line and active breakpoints are displayed in this window.
-
-_assembly_
-     The assembly window shows the disassembly output of the program.
-
-_register_
-     This window shows the processor registers.  Registers are
-     highlighted when their values change.
-
-   The source and assembly windows show the current program position by
-highlighting the current line and marking it with a `>' marker.
-Breakpoints are indicated with two markers.  The first marker indicates
-the breakpoint type:
-
-`B'
-     Breakpoint which was hit at least once.
-
-`b'
-     Breakpoint which was never hit.
-
-`H'
-     Hardware breakpoint which was hit at least once.
-
-`h'
-     Hardware breakpoint which was never hit.
-
-   The second marker indicates whether the breakpoint is enabled or not:
-
-`+'
-     Breakpoint is enabled.
-
-`-'
-     Breakpoint is disabled.
-
-   The source, assembly and register windows are updated when the
-current thread changes, when the frame changes, or when the program
-counter changes.
-
-   These windows are not all visible at the same time.  The command
-window is always visible.  The others can be arranged in several
-layouts:
-
-   * source only,
-
-   * assembly only,
-
-   * source and assembly,
-
-   * source and registers, or
-
-   * assembly and registers.
-
-   A status line above the command window shows the following
-information:
-
-_target_
-     Indicates the current GDB target.  (*note Specifying a Debugging
-     Target: Targets.).
-
-_process_
-     Gives the current process or thread number.  When no process is
-     being debugged, this field is set to `No process'.
-
-_function_
-     Gives the current function name for the selected frame.  The name
-     is demangled if demangling is turned on (*note Print Settings::).
-     When there is no symbol corresponding to the current program
-     counter, the string `??' is displayed.
-
-_line_
-     Indicates the current line number for the selected frame.  When
-     the current line number is not known, the string `??' is displayed.
-
-_pc_
-     Indicates the current program counter address.
-
-
-File: gdb.info,  Node: TUI Keys,  Next: TUI Single Key Mode,  Prev: TUI Overview,  Up: TUI
-
-25.2 TUI Key Bindings
-=====================
-
-The TUI installs several key bindings in the readline keymaps (*note
-Command Line Editing::).  The following key bindings are installed for
-both TUI mode and the GDB standard mode.
-
-`C-x C-a'
-`C-x a'
-`C-x A'
-     Enter or leave the TUI mode.  When leaving the TUI mode, the
-     curses window management stops and GDB operates using its standard
-     mode, writing on the terminal directly.  When reentering the TUI
-     mode, control is given back to the curses windows.  The screen is
-     then refreshed.
-
-`C-x 1'
-     Use a TUI layout with only one window.  The layout will either be
-     `source' or `assembly'.  When the TUI mode is not active, it will
-     switch to the TUI mode.
-
-     Think of this key binding as the Emacs `C-x 1' binding.
-
-`C-x 2'
-     Use a TUI layout with at least two windows.  When the current
-     layout already has two windows, the next layout with two windows
-     is used.  When a new layout is chosen, one window will always be
-     common to the previous layout and the new one.
-
-     Think of it as the Emacs `C-x 2' binding.
-
-`C-x o'
-     Change the active window.  The TUI associates several key bindings
-     (like scrolling and arrow keys) with the active window.  This
-     command gives the focus to the next TUI window.
-
-     Think of it as the Emacs `C-x o' binding.
-
-`C-x s'
-     Switch in and out of the TUI SingleKey mode that binds single keys
-     to GDB commands (*note TUI Single Key Mode::).
-
-   The following key bindings only work in the TUI mode:
-
-<PgUp>
-     Scroll the active window one page up.
-
-<PgDn>
-     Scroll the active window one page down.
-
-<Up>
-     Scroll the active window one line up.
-
-<Down>
-     Scroll the active window one line down.
-
-<Left>
-     Scroll the active window one column left.
-
-<Right>
-     Scroll the active window one column right.
-
-`C-L'
-     Refresh the screen.
-
-   Because the arrow keys scroll the active window in the TUI mode, they
-are not available for their normal use by readline unless the command
-window has the focus.  When another window is active, you must use
-other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to
-control the command window.
-
-
-File: gdb.info,  Node: TUI Single Key Mode,  Next: TUI Commands,  Prev: TUI Keys,  Up: TUI
-
-25.3 TUI Single Key Mode
-========================
-
-The TUI also provides a "SingleKey" mode, which binds several
-frequently used GDB commands to single keys.  Type `C-x s' to switch
-into this mode, where the following key bindings are used:
-
-`c'
-     continue
-
-`d'
-     down
-
-`f'
-     finish
-
-`n'
-     next
-
-`q'
-     exit the SingleKey mode.
-
-`r'
-     run
-
-`s'
-     step
-
-`u'
-     up
-
-`v'
-     info locals
-
-`w'
-     where
-
-   Other keys temporarily switch to the GDB command prompt.  The key
-that was pressed is inserted in the editing buffer so that it is
-possible to type most GDB commands without interaction with the TUI
-SingleKey mode.  Once the command is entered the TUI SingleKey mode is
-restored.  The only way to permanently leave this mode is by typing `q'
-or `C-x s'.
-
-
-File: gdb.info,  Node: TUI Commands,  Next: TUI Configuration,  Prev: TUI Single Key Mode,  Up: TUI
-
-25.4 TUI-specific Commands
-==========================
-
-The TUI has specific commands to control the text windows.  These
-commands are always available, even when GDB is not in the TUI mode.
-When GDB is in the standard mode, most of these commands will
-automatically switch to the TUI mode.
-
-   Note that if GDB's `stdout' is not connected to a terminal, or GDB
-has been started with the machine interface interpreter (*note The
-GDB/MI Interface: GDB/MI.), most of these commands will fail with an
-error, because it would not be possible or desirable to enable curses
-window management.
-
-`info win'
-     List and give the size of all displayed windows.
-
-`layout next'
-     Display the next layout.
-
-`layout prev'
-     Display the previous layout.
-
-`layout src'
-     Display the source window only.
-
-`layout asm'
-     Display the assembly window only.
-
-`layout split'
-     Display the source and assembly window.
-
-`layout regs'
-     Display the register window together with the source or assembly
-     window.
-
-`focus next'
-     Make the next window active for scrolling.
-
-`focus prev'
-     Make the previous window active for scrolling.
-
-`focus src'
-     Make the source window active for scrolling.
-
-`focus asm'
-     Make the assembly window active for scrolling.
-
-`focus regs'
-     Make the register window active for scrolling.
-
-`focus cmd'
-     Make the command window active for scrolling.
-
-`refresh'
-     Refresh the screen.  This is similar to typing `C-L'.
-
-`tui reg float'
-     Show the floating point registers in the register window.
-
-`tui reg general'
-     Show the general registers in the register window.
-
-`tui reg next'
-     Show the next register group.  The list of register groups as well
-     as their order is target specific.  The predefined register groups
-     are the following: `general', `float', `system', `vector', `all',
-     `save', `restore'.
-
-`tui reg system'
-     Show the system registers in the register window.
-
-`update'
-     Update the source window and the current execution point.
-
-`winheight NAME +COUNT'
-`winheight NAME -COUNT'
-     Change the height of the window NAME by COUNT lines.  Positive
-     counts increase the height, while negative counts decrease it.
-
-`tabset NCHARS'
-     Set the width of tab stops to be NCHARS characters.
-
-
-File: gdb.info,  Node: TUI Configuration,  Prev: TUI Commands,  Up: TUI
-
-25.5 TUI Configuration Variables
-================================
-
-Several configuration variables control the appearance of TUI windows.
-
-`set tui border-kind KIND'
-     Select the border appearance for the source, assembly and register
-     windows.  The possible values are the following:
-    `space'
-          Use a space character to draw the border.
-
-    `ascii'
-          Use ASCII characters `+', `-' and `|' to draw the border.
-
-    `acs'
-          Use the Alternate Character Set to draw the border.  The
-          border is drawn using character line graphics if the terminal
-          supports them.
-
-`set tui border-mode MODE'
-`set tui active-border-mode MODE'
-     Select the display attributes for the borders of the inactive
-     windows or the active window.  The MODE can be one of the
-     following:
-    `normal'
-          Use normal attributes to display the border.
-
-    `standout'
-          Use standout mode.
-
-    `reverse'
-          Use reverse video mode.
-
-    `half'
-          Use half bright mode.
-
-    `half-standout'
-          Use half bright and standout mode.
-
-    `bold'
-          Use extra bright or bold mode.
-
-    `bold-standout'
-          Use extra bright or bold and standout mode.
-
-
-File: gdb.info,  Node: Emacs,  Next: GDB/MI,  Prev: TUI,  Up: Top
-
-26 Using GDB under GNU Emacs
-****************************
-
-A special interface allows you to use GNU Emacs to view (and edit) the
-source files for the program you are debugging with GDB.
-
-   To use this interface, use the command `M-x gdb' in Emacs.  Give the
-executable file you want to debug as an argument.  This command starts
-GDB as a subprocess of Emacs, with input and output through a newly
-created Emacs buffer.
-
-   Running GDB under Emacs can be just like running GDB normally except
-for two things:
-
-   * All "terminal" input and output goes through an Emacs buffer,
-     called the GUD buffer.
-
-     This applies both to GDB commands and their output, and to the
-     input and output done by the program you are debugging.
-
-     This is useful because it means that you can copy the text of
-     previous commands and input them again; you can even use parts of
-     the output in this way.
-
-     All the facilities of Emacs' Shell mode are available for
-     interacting with your program.  In particular, you can send
-     signals the usual way--for example, `C-c C-c' for an interrupt,
-     `C-c C-z' for a stop.
-
-   * GDB displays source code through Emacs.
-
-     Each time GDB displays a stack frame, Emacs automatically finds the
-     source file for that frame and puts an arrow (`=>') at the left
-     margin of the current line.  Emacs uses a separate buffer for
-     source display, and splits the screen to show both your GDB session
-     and the source.
-
-     Explicit GDB `list' or search commands still produce output as
-     usual, but you probably have no reason to use them from Emacs.
-
-   We call this "text command mode".  Emacs 22.1, and later, also uses
-a graphical mode, enabled by default, which provides further buffers
-that can control the execution and describe the state of your program.
-*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface.
-
-   If you specify an absolute file name when prompted for the `M-x gdb'
-argument, then Emacs sets your current working directory to where your
-program resides.  If you only specify the file name, then Emacs sets
-your current working directory to the directory associated with the
-previous buffer.  In this case, GDB may find your program by searching
-your environment's `PATH' variable, but on some operating systems it
-might not find the source.  So, although the GDB input and output
-session proceeds normally, the auxiliary buffer does not display the
-current source and line of execution.
-
-   The initial working directory of GDB is printed on the top line of
-the GUD buffer and this serves as a default for the commands that
-specify files for GDB to operate on.  *Note Commands to Specify Files:
-Files.
-
-   By default, `M-x gdb' calls the program called `gdb'.  If you need
-to call GDB by a different name (for example, if you keep several
-configurations around, with different names) you can customize the
-Emacs variable `gud-gdb-command-name' to run the one you want.
-
-   In the GUD buffer, you can use these special Emacs commands in
-addition to the standard Shell mode commands:
-
-`C-h m'
-     Describe the features of Emacs' GUD Mode.
-
-`C-c C-s'
-     Execute to another source line, like the GDB `step' command; also
-     update the display window to show the current file and location.
-
-`C-c C-n'
-     Execute to next source line in this function, skipping all function
-     calls, like the GDB `next' command.  Then update the display window
-     to show the current file and location.
-
-`C-c C-i'
-     Execute one instruction, like the GDB `stepi' command; update
-     display window accordingly.
-
-`C-c C-f'
-     Execute until exit from the selected stack frame, like the GDB
-     `finish' command.
-
-`C-c C-r'
-     Continue execution of your program, like the GDB `continue'
-     command.
-
-`C-c <'
-     Go up the number of frames indicated by the numeric argument
-     (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
-     command.
-
-`C-c >'
-     Go down the number of frames indicated by the numeric argument,
-     like the GDB `down' command.
-
-   In any source file, the Emacs command `C-x <SPC>' (`gud-break')
-tells GDB to set a breakpoint on the source line point is on.
-
-   In text command mode, if you type `M-x speedbar', Emacs displays a
-separate frame which shows a backtrace when the GUD buffer is current.
-Move point to any frame in the stack and type <RET> to make it become
-the current frame and display the associated source in the source
-buffer.  Alternatively, click `Mouse-2' to make the selected frame
-become the current one.  In graphical mode, the speedbar displays watch
-expressions.
-
-   If you accidentally delete the source-display buffer, an easy way to
-get it back is to type the command `f' in the GDB buffer, to request a
-frame display; when you run under Emacs, this recreates the source
-buffer if necessary to show you the context of the current frame.
-
-   The source files displayed in Emacs are in ordinary Emacs buffers
-which are visiting the source files in the usual way.  You can edit the
-files with these buffers if you wish; but keep in mind that GDB
-communicates with Emacs in terms of line numbers.  If you add or delete
-lines from the text, the line numbers that GDB knows cease to
-correspond properly with the code.
-
-   A more detailed description of Emacs' interaction with GDB is given
-in the Emacs manual (*note Debuggers: (Emacs)Debuggers.).
-
-
-File: gdb.info,  Node: GDB/MI,  Next: Annotations,  Prev: Emacs,  Up: Top
-
-27 The GDB/MI Interface
-***********************
-
-Function and Purpose
-====================
-
-GDB/MI is a line based machine oriented text interface to GDB and is
-activated by specifying using the `--interpreter' command line option
-(*note Mode Options::).  It is specifically intended to support the
-development of systems which use the debugger as just one small
-component of a larger system.
-
-   This chapter is a specification of the GDB/MI interface.  It is
-written in the form of a reference manual.
-
-   Note that GDB/MI is still under construction, so some of the
-features described below are incomplete and subject to change (*note
-GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.).
-
-Notation and Terminology
-========================
-
-This chapter uses the following notation:
-
-   * `|' separates two alternatives.
-
-   * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
-     may not be given.
-
-   * `( GROUP )*' means that GROUP inside the parentheses may repeat
-     zero or more times.
-
-   * `( GROUP )+' means that GROUP inside the parentheses may repeat
-     one or more times.
-
-   * `"STRING"' means a literal STRING.
-
-* Menu:
-
-* GDB/MI General Design::
-* GDB/MI Command Syntax::
-* GDB/MI Compatibility with CLI::
-* GDB/MI Development and Front Ends::
-* GDB/MI Output Records::
-* GDB/MI Simple Examples::
-* GDB/MI Command Description Format::
-* GDB/MI Breakpoint Commands::
-* GDB/MI Program Context::
-* GDB/MI Thread Commands::
-* GDB/MI Ada Tasking Commands::
-* GDB/MI Program Execution::
-* GDB/MI Stack Manipulation::
-* GDB/MI Variable Objects::
-* GDB/MI Data Manipulation::
-* GDB/MI Tracepoint Commands::
-* GDB/MI Symbol Query::
-* GDB/MI File Commands::
-* GDB/MI Target Manipulation::
-* GDB/MI File Transfer Commands::
-* GDB/MI Miscellaneous Commands::
-
-
-File: gdb.info,  Node: GDB/MI General Design,  Next: GDB/MI Command Syntax,  Up: GDB/MI
-
-27.1 GDB/MI General Design
-==========================
-
-Interaction of a GDB/MI frontend with GDB involves three
-parts--commands sent to GDB, responses to those commands and
-notifications.  Each command results in exactly one response,
-indicating either successful completion of the command, or an error.
-For the commands that do not resume the target, the response contains
-the requested information.  For the commands that resume the target, the
-response only indicates whether the target was successfully resumed.
-Notifications is the mechanism for reporting changes in the state of the
-target, or in GDB state, that cannot conveniently be associated with a
-command and reported as part of that command response.
-
-   The important examples of notifications are:
-   * Exec notifications.  These are used to report changes in target
-     state--when a target is resumed, or stopped.  It would not be
-     feasible to include this information in response of resuming
-     commands, because one resume commands can result in multiple
-     events in different threads.  Also, quite some time may pass
-     before any event happens in the target, while a frontend needs to
-     know whether the resuming command itself was successfully executed.
-
-   * Console output, and status notifications.  Console output
-     notifications are used to report output of CLI commands, as well as
-     diagnostics for other commands.  Status notifications are used to
-     report the progress of a long-running operation.  Naturally,
-     including this information in command response would mean no
-     output is produced until the command is finished, which is
-     undesirable.
-
-   * General notifications.  Commands may have various side effects on
-     the GDB or target state beyond their official purpose.  For
-     example, a command may change the selected thread.  Although such
-     changes can be included in command response, using notification
-     allows for more orthogonal frontend design.
-
-
-   There's no guarantee that whenever an MI command reports an error,
-GDB or the target are in any specific state, and especially, the state
-is not reverted to the state before the MI command was processed.
-Therefore, whenever an MI command results in an error, we recommend
-that the frontend refreshes all the information shown in the user
-interface.
-
-* Menu:
-
-* Context management::
-* Asynchronous and non-stop modes::
-* Thread groups::
-
-
-File: gdb.info,  Node: Context management,  Next: Asynchronous and non-stop modes,  Up: GDB/MI General Design
-
-27.1.1 Context management
--------------------------
-
-In most cases when GDB accesses the target, this access is done in
-context of a specific thread and frame (*note Frames::).  Often, even
-when accessing global data, the target requires that a thread be
-specified.  The CLI interface maintains the selected thread and frame,
-and supplies them to target on each command.  This is convenient,
-because a command line user would not want to specify that information
-explicitly on each command, and because user interacts with GDB via a
-single terminal, so no confusion is possible as to what thread and
-frame are the current ones.
-
-   In the case of MI, the concept of selected thread and frame is less
-useful.  First, a frontend can easily remember this information itself.
-Second, a graphical frontend can have more than one window, each one
-used for debugging a different thread, and the frontend might want to
-access additional threads for internal purposes.  This increases the
-risk that by relying on implicitly selected thread, the frontend may be
-operating on a wrong one.  Therefore, each MI command should explicitly
-specify which thread and frame to operate on.  To make it possible,
-each MI command accepts the `--thread' and `--frame' options, the value
-to each is GDB identifier for thread and frame to operate on.
-
-   Usually, each top-level window in a frontend allows the user to
-select a thread and a frame, and remembers the user selection for
-further operations.  However, in some cases GDB may suggest that the
-current thread be changed.  For example, when stopping on a breakpoint
-it is reasonable to switch to the thread where breakpoint is hit.  For
-another example, if the user issues the CLI `thread' command via the
-frontend, it is desirable to change the frontend's selected thread to
-the one specified by user.  GDB communicates the suggestion to change
-current thread using the `=thread-selected' notification.  No such
-notification is available for the selected frame at the moment.
-
-   Note that historically, MI shares the selected thread with CLI, so
-frontends used the `-thread-select' to execute commands in the right
-context.  However, getting this to work right is cumbersome.  The
-simplest way is for frontend to emit `-thread-select' command before
-every command.  This doubles the number of commands that need to be
-sent.  The alternative approach is to suppress `-thread-select' if the
-selected thread in GDB is supposed to be identical to the thread the
-frontend wants to operate on.  However, getting this optimization right
-can be tricky.  In particular, if the frontend sends several commands
-to GDB, and one of the commands changes the selected thread, then the
-behaviour of subsequent commands will change.  So, a frontend should
-either wait for response from such problematic commands, or explicitly
-add `-thread-select' for all subsequent commands.  No frontend is known
-to do this exactly right, so it is suggested to just always pass the
-`--thread' and `--frame' options.
-
-
-File: gdb.info,  Node: Asynchronous and non-stop modes,  Next: Thread groups,  Prev: Context management,  Up: GDB/MI General Design
-
-27.1.2 Asynchronous command execution and non-stop mode
--------------------------------------------------------
-
-On some targets, GDB is capable of processing MI commands even while
-the target is running.  This is called "asynchronous command execution"
-(*note Background Execution::).  The frontend may specify a preferrence
-for asynchronous execution using the `-gdb-set target-async 1' command,
-which should be emitted before either running the executable or
-attaching to the target.  After the frontend has started the executable
-or attached to the target, it can find if asynchronous execution is
-enabled using the `-list-target-features' command.
-
-   Even if GDB can accept a command while target is running, many
-commands that access the target do not work when the target is running.
-Therefore, asynchronous command execution is most useful when combined
-with non-stop mode (*note Non-Stop Mode::).  Then, it is possible to
-examine the state of one thread, while other threads are running.
-
-   When a given thread is running, MI commands that try to access the
-target in the context of that thread may not work, or may work only on
-some targets.  In particular, commands that try to operate on thread's
-stack will not work, on any target.  Commands that read memory, or
-modify breakpoints, may work or not work, depending on the target.  Note
-that even commands that operate on global state, such as `print',
-`set', and breakpoint commands, still access the target in the context
-of a specific thread,  so frontend should try to find a stopped thread
-and perform the operation on that thread (using the `--thread' option).
-
-   Which commands will work in the context of a running thread is
-highly target dependent.  However, the two commands `-exec-interrupt',
-to stop a thread, and `-thread-info', to find the state of a thread,
-will always work.
-
-
-File: gdb.info,  Node: Thread groups,  Prev: Asynchronous and non-stop modes,  Up: GDB/MI General Design
-
-27.1.3 Thread groups
---------------------
-
-GDB may be used to debug several processes at the same time.  On some
-platfroms, GDB may support debugging of several hardware systems, each
-one having several cores with several different processes running on
-each core.  This section describes the MI mechanism to support such
-debugging scenarios.
-
-   The key observation is that regardless of the structure of the
-target, MI can have a global list of threads, because most commands that
-accept the `--thread' option do not need to know what process that
-thread belongs to.  Therefore, it is not necessary to introduce neither
-additional `--process' option, nor an notion of the current process in
-the MI interface.  The only strictly new feature that is required is
-the ability to find how the threads are grouped into processes.
-
-   To allow the user to discover such grouping, and to support arbitrary
-hierarchy of machines/cores/processes, MI introduces the concept of a
-"thread group".  Thread group is a collection of threads and other
-thread groups.  A thread group always has a string identifier, a type,
-and may have additional attributes specific to the type.  A new
-command, `-list-thread-groups', returns the list of top-level thread
-groups, which correspond to processes that GDB is debugging at the
-moment.  By passing an identifier of a thread group to the
-`-list-thread-groups' command, it is possible to obtain the members of
-specific thread group.
-
-   To allow the user to easily discover processes, and other objects, he
-wishes to debug, a concept of "available thread group" is introduced.
-Available thread group is an thread group that GDB is not debugging,
-but that can be attached to, using the `-target-attach' command.  The
-list of available top-level thread groups can be obtained using
-`-list-thread-groups --available'.  In general, the content of a thread
-group may be only retrieved only after attaching to that thread group.
-
-   Thread groups are related to inferiors (*note Inferiors and
-Programs::).  Each inferior corresponds to a thread group of a special
-type `process', and some additional operations are permitted on such
-thread groups.
-
-
-File: gdb.info,  Node: GDB/MI Command Syntax,  Next: GDB/MI Compatibility with CLI,  Prev: GDB/MI General Design,  Up: GDB/MI
-
-27.2 GDB/MI Command Syntax
-==========================
-
-* Menu:
-
-* GDB/MI Input Syntax::
-* GDB/MI Output Syntax::
-
-
-File: gdb.info,  Node: GDB/MI Input Syntax,  Next: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax
-
-27.2.1 GDB/MI Input Syntax
---------------------------
-
-`COMMAND ==>'
-     `CLI-COMMAND | MI-COMMAND'
-
-`CLI-COMMAND ==>'
-     `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
-     CLI command.
-
-`MI-COMMAND ==>'
-     `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
-     PARAMETER )* NL'
-
-`TOKEN ==>'
-     "any sequence of digits"
-
-`OPTION ==>'
-     `"-" PARAMETER [ " " PARAMETER ]'
-
-`PARAMETER ==>'
-     `NON-BLANK-SEQUENCE | C-STRING'
-
-`OPERATION ==>'
-     _any of the operations described in this chapter_
-
-`NON-BLANK-SEQUENCE ==>'
-     _anything, provided it doesn't contain special characters such as
-     "-", NL, """ and of course " "_
-
-`C-STRING ==>'
-     `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
-
-`NL ==>'
-     `CR | CR-LF'
-
-Notes:
-
-   * The CLI commands are still handled by the MI interpreter; their
-     output is described below.
-
-   * The `TOKEN', when present, is passed back when the command
-     finishes.
-
-   * Some MI commands accept optional arguments as part of the parameter
-     list.  Each option is identified by a leading `-' (dash) and may be
-     followed by an optional argument parameter.  Options occur first
-     in the parameter list and can be delimited from normal parameters
-     using `--' (this is useful when some parameters begin with a dash).
-
-   Pragmatics:
-
-   * We want easy access to the existing CLI syntax (for debugging).
-
-   * We want it to be easy to spot a MI operation.
-