-This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
+This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo.
-INFO-DIR-SECTION Software development
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
-
- Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010 2011, 2012 Free Software Foundation, Inc.
+Copyright (C) 1988-2015 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
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom."
+INFO-DIR-SECTION Software development
+START-INFO-DIR-ENTRY
+* Gdb: (gdb). The GNU debugger.
+* gdbserver: (gdb) Server. The GNU debugging server.
+END-INFO-DIR-ENTRY
This file documents the GNU debugger GDB.
- This is the Tenth Edition, of `Debugging with GDB: the GNU
-Source-Level Debugger' for GDB (GDB) Version 7.5.
+ This is the Tenth Edition, of 'Debugging with GDB: the GNU
+Source-Level Debugger' for GDB (GDB) Version 7.9.
- Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010 2011, 2012 Free Software Foundation, Inc.
+ Copyright (C) 1988-2015 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
developing GNU and promoting software freedom."
\1f
-File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
-
-C.2 Invoking the GDB `configure' Script
-=======================================
+File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI
-GDB comes with a `configure' script that automates the process of
-preparing GDB for installation; you can then use `make' to build the
-`gdb' program.
+27.3 GDB/MI Compatibility with CLI
+==================================
- The GDB distribution includes all the source code you need for GDB
-in a single directory, whose name is usually composed by appending the
-version number to `gdb'.
+For the developers convenience CLI commands can be entered directly, but
+there may be some unexpected behaviour. For example, commands that
+query the user will behave as if the user replied yes, breakpoint
+command lists are not executed and some CLI commands, such as 'if',
+'when' and 'define', prompt for further input with '>', which is not
+valid MI output.
- For example, the GDB version 7.5 distribution is in the `gdb-7.5'
-directory. That directory contains:
+ This feature may be removed at some stage in the future and it is
+recommended that front ends use the '-interpreter-exec' command (*note
+-interpreter-exec::).
-`gdb-7.5/configure (and supporting files)'
- script for configuring GDB and all its supporting libraries
+\1f
+File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
-`gdb-7.5/gdb'
- the source specific to GDB itself
+27.4 GDB/MI Development and Front Ends
+======================================
-`gdb-7.5/bfd'
- source for the Binary File Descriptor library
+The application which takes the MI output and presents the state of the
+program being debugged to the user is called a "front end".
-`gdb-7.5/include'
- GNU include files
+ Although GDB/MI is still incomplete, it is currently being used by a
+variety of front ends to GDB. This makes it difficult to introduce new
+functionality without breaking existing usage. This section tries to
+minimize the problems by describing how the protocol might change.
-`gdb-7.5/libiberty'
- source for the `-liberty' free software library
+ Some changes in MI need not break a carefully designed front end, and
+for these the MI version will remain unchanged. The following is a list
+of changes that may occur within one level, so front ends should parse
+MI output in a way that can handle them:
-`gdb-7.5/opcodes'
- source for the library of opcode tables and disassemblers
+ * New MI commands may be added.
-`gdb-7.5/readline'
- source for the GNU command-line interface
+ * New fields may be added to the output of any MI command.
-`gdb-7.5/glob'
- source for the GNU filename pattern-matching subroutine
+ * The range of values for fields with specified values, e.g.,
+ 'in_scope' (*note -var-update::) may be extended.
-`gdb-7.5/mmalloc'
- source for the GNU memory-mapped malloc package
+ If the changes are likely to break front ends, the MI version level
+will be increased by one. This will allow the front end to parse the
+output according to the MI version. Apart from mi0, new versions of GDB
+will not support old versions of MI and it will be the responsibility of
+the front end to work with the new one.
- The simplest way to configure and build GDB is to run `configure'
-from the `gdb-VERSION-NUMBER' source directory, which in this example
-is the `gdb-7.5' directory.
+ The best way to avoid unexpected changes in MI that might break your
+front end is to make your project known to GDB developers and follow
+development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>.
- First switch to the `gdb-VERSION-NUMBER' source directory if you are
-not already in it; then run `configure'. Pass the identifier for the
-platform on which GDB will run as an argument.
+\1f
+File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI
- For example:
+27.5 GDB/MI Output Records
+==========================
- cd gdb-7.5
- ./configure HOST
- make
+* Menu:
-where HOST is an identifier such as `sun4' or `decstation', that
-identifies the platform where GDB will run. (You can often leave off
-HOST; `configure' tries to guess the correct value by examining your
-system.)
+* GDB/MI Result Records::
+* GDB/MI Stream Records::
+* GDB/MI Async Records::
+* GDB/MI Breakpoint Information::
+* GDB/MI Frame Information::
+* GDB/MI Thread Information::
+* GDB/MI Ada Exception Information::
- Running `configure HOST' and then running `make' builds the `bfd',
-`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
-The configured source files, and the binaries, are left in the
-corresponding source directories.
+\1f
+File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
- `configure' is a Bourne-shell (`/bin/sh') script; if your system
-does not recognize this automatically when you run a different shell,
-you may need to run `sh' on it explicitly:
+27.5.1 GDB/MI Result Records
+----------------------------
- sh configure HOST
+In addition to a number of out-of-band notifications, the response to a
+GDB/MI command includes one of the following result indications:
- If you run `configure' from a directory that contains source
-directories for multiple libraries or programs, such as the `gdb-7.5'
-source directory for version 7.5, `configure' creates configuration
-files for every directory level underneath (unless you tell it not to,
-with the `--norecursion' option).
-
- You should run the `configure' script from the top directory in the
-source tree, the `gdb-VERSION-NUMBER' directory. If you run
-`configure' from one of the subdirectories, you will configure only
-that subdirectory. That is usually not what you want. In particular,
-if you run the first `configure' from the `gdb' subdirectory of the
-`gdb-VERSION-NUMBER' directory, you will omit the configuration of
-`bfd', `readline', and other sibling directories of the `gdb'
-subdirectory. This leads to build errors about missing include files
-such as `bfd/bfd.h'.
+'"^done" [ "," RESULTS ]'
+ The synchronous operation was successful, 'RESULTS' are the return
+ values.
- You can install `gdb' anywhere; it has no hardwired paths. However,
-you should make sure that the shell on your path (named by the `SHELL'
-environment variable) is publicly readable. Remember that GDB uses the
-shell to start your program--some systems refuse to let GDB debug child
-processes whose programs are not readable.
+'"^running"'
+ This result record is equivalent to '^done'. Historically, it was
+ output instead of '^done' if the command has resumed the target.
+ This behaviour is maintained for backward compatibility, but all
+ frontends should treat '^done' and '^running' identically and rely
+ on the '*running' output record to determine which threads are
+ resumed.
-\1f
-File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
+'"^connected"'
+ GDB has connected to a remote target.
-C.3 Compiling GDB in Another Directory
-======================================
+'"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]'
+ The operation failed. The 'msg=C-STRING' variable contains the
+ corresponding error message.
-If you want to run GDB versions for several host or target machines,
-you need a different `gdb' compiled for each combination of host and
-target. `configure' is designed to make this easy by allowing you to
-generate each configuration in a separate subdirectory, rather than in
-the source directory. If your `make' program handles the `VPATH'
-feature (GNU `make' does), running `make' in each of these directories
-builds the `gdb' program specified there.
-
- To build `gdb' in a separate directory, run `configure' with the
-`--srcdir' option to specify where to find the source. (You also need
-to specify a path to find `configure' itself from your working
-directory. If the path to `configure' would be the same as the
-argument to `--srcdir', you can leave out the `--srcdir' option; it is
-assumed.)
-
- For example, with version 7.5, you can build GDB in a separate
-directory for a Sun 4 like this:
+ If present, the 'code=C-STRING' variable provides an error code on
+ which consumers can rely on to detect the corresponding error
+ condition. At present, only one error code is defined:
- cd gdb-7.5
- mkdir ../gdb-sun4
- cd ../gdb-sun4
- ../gdb-7.5/configure sun4
- make
+ '"undefined-command"'
+ Indicates that the command causing the error does not exist.
- When `configure' builds a configuration using a remote source
-directory, it creates a tree for the binaries with the same structure
-(and using the same names) as the tree under the source directory. In
-the example, you'd find the Sun 4 library `libiberty.a' in the
-directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
+'"^exit"'
+ GDB has terminated.
- Make sure that your path to the `configure' script has just one
-instance of `gdb' in it. If your path to `configure' looks like
-`../gdb-7.5/gdb/configure', you are configuring only one subdirectory
-of GDB, not the whole package. This leads to build errors about
-missing include files such as `bfd/bfd.h'.
+\1f
+File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
+
+27.5.2 GDB/MI Stream Records
+----------------------------
+
+GDB internally maintains a number of output streams: the console, the
+target, and the log. The output intended for each of these streams is
+funneled through the GDB/MI interface using "stream records".
+
+ Each stream record begins with a unique "prefix character" which
+identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
+Syntax.). In addition to the prefix, each stream record contains a
+'STRING-OUTPUT'. This is either raw text (with an implicit new line) or
+a quoted C string (which does not contain an implicit newline).
+
+'"~" STRING-OUTPUT'
+ The console output stream contains text that should be displayed in
+ the CLI console window. It contains the textual responses to CLI
+ commands.
+
+'"@" STRING-OUTPUT'
+ The target output stream contains any textual output from the
+ running target. This is only present when GDB's event loop is
+ truly asynchronous, which is currently only the case for remote
+ targets.
- One popular reason to build several GDB configurations in separate
-directories is to configure GDB for cross-compiling (where GDB runs on
-one machine--the "host"--while debugging programs that run on another
-machine--the "target"). You specify a cross-debugging target by giving
-the `--target=TARGET' option to `configure'.
+'"&" STRING-OUTPUT'
+ The log stream contains debugging messages being produced by GDB's
+ internals.
- When you run `make' to build a program or library, you must run it
-in a configured directory--whatever directory you were in when you
-called `configure' (or one of its subdirectories).
+\1f
+File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
- The `Makefile' that `configure' generates in each source directory
-also runs recursively. If you type `make' in a source directory such
-as `gdb-7.5' (or in a separate configured directory configured with
-`--srcdir=DIRNAME/gdb-7.5'), you will build all the required libraries,
-and then build GDB.
+27.5.3 GDB/MI Async Records
+---------------------------
- When you have multiple hosts or targets configured in separate
-directories, you can run `make' on them in parallel (for example, if
-they are NFS-mounted on each of the hosts); they will not interfere
-with each other.
+"Async" records are used to notify the GDB/MI client of additional
+changes that have occurred. Those changes can either be a consequence
+of GDB/MI commands (e.g., a breakpoint modified) or a result of target
+activity (e.g., target stopped).
+
+ The following is the list of possible async records:
+
+'*running,thread-id="THREAD"'
+ The target is now running. The THREAD field tells which specific
+ thread is now running, and can be 'all' if all threads are running.
+ The frontend should assume that no interaction with a running
+ thread is possible after this notification is produced. The
+ frontend should not assume that this notification is output only
+ once for any command. GDB may emit this notification several
+ times, either for different threads, because it cannot resume all
+ threads together, or even for a single thread, if the thread must
+ be stepped though some code before letting it run freely.
+
+'*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"'
+ The target has stopped. The REASON field can have one of the
+ following values:
+
+ 'breakpoint-hit'
+ A breakpoint was reached.
+ 'watchpoint-trigger'
+ A watchpoint was triggered.
+ 'read-watchpoint-trigger'
+ A read watchpoint was triggered.
+ 'access-watchpoint-trigger'
+ An access watchpoint was triggered.
+ 'function-finished'
+ An -exec-finish or similar CLI command was accomplished.
+ 'location-reached'
+ An -exec-until or similar CLI command was accomplished.
+ 'watchpoint-scope'
+ A watchpoint has gone out of scope.
+ 'end-stepping-range'
+ An -exec-next, -exec-next-instruction, -exec-step,
+ -exec-step-instruction or similar CLI command was
+ accomplished.
+ 'exited-signalled'
+ The inferior exited because of a signal.
+ 'exited'
+ The inferior exited.
+ 'exited-normally'
+ The inferior exited normally.
+ 'signal-received'
+ A signal was received by the inferior.
+ 'solib-event'
+ The inferior has stopped due to a library being loaded or
+ unloaded. This can happen when 'stop-on-solib-events' (*note
+ Files::) is set or when a 'catch load' or 'catch unload'
+ catchpoint is in use (*note Set Catchpoints::).
+ 'fork'
+ The inferior has forked. This is reported when 'catch fork'
+ (*note Set Catchpoints::) has been used.
+ 'vfork'
+ The inferior has vforked. This is reported in when 'catch
+ vfork' (*note Set Catchpoints::) has been used.
+ 'syscall-entry'
+ The inferior entered a system call. This is reported when
+ 'catch syscall' (*note Set Catchpoints::) has been used.
+ 'syscall-entry'
+ The inferior returned from a system call. This is reported
+ when 'catch syscall' (*note Set Catchpoints::) has been used.
+ 'exec'
+ The inferior called 'exec'. This is reported when 'catch
+ exec' (*note Set Catchpoints::) has been used.
+
+ The ID field identifies the thread that directly caused the stop -
+ for example by hitting a breakpoint. Depending on whether all-stop
+ mode is in effect (*note All-Stop Mode::), GDB may either stop all
+ threads, or only the thread that directly triggered the stop. If
+ all threads are stopped, the STOPPED field will have the value of
+ '"all"'. Otherwise, the value of the STOPPED field will be a list
+ of thread identifiers. Presently, this list will always include a
+ single thread, but frontend should be prepared to see several
+ threads in the list. The CORE field reports the processor core on
+ which the stop event has happened. This field may be absent if
+ such information is not available.
+
+'=thread-group-added,id="ID"'
+'=thread-group-removed,id="ID"'
+ A thread group was either added or removed. The ID field contains
+ the GDB identifier of the thread group. When a thread group is
+ added, it generally might not be associated with a running process.
+ When a thread group is removed, its id becomes invalid and cannot
+ be used in any way.
+
+'=thread-group-started,id="ID",pid="PID"'
+ A thread group became associated with a running program, either
+ because the program was just started or the thread group was
+ attached to a program. The ID field contains the GDB identifier of
+ the thread group. The PID field contains process identifier,
+ specific to the operating system.
+
+'=thread-group-exited,id="ID"[,exit-code="CODE"]'
+ A thread group is no longer associated with a running program,
+ either because the program has exited, or because it was detached
+ from. The ID field contains the GDB identifier of the thread
+ group. The CODE field is the exit code of the inferior; it exists
+ only when the inferior exited with some code.
+
+'=thread-created,id="ID",group-id="GID"'
+'=thread-exited,id="ID",group-id="GID"'
+ A thread either was created, or has exited. The ID field contains
+ the GDB identifier of the thread. The GID field identifies the
+ thread group this thread belongs to.
+
+'=thread-selected,id="ID"'
+ Informs that the selected thread was changed as result of the last
+ command. This notification is not emitted as result of
+ '-thread-select' command but is emitted whenever an MI command that
+ is not documented to change the selected thread actually changes
+ it. In particular, invoking, directly or indirectly (via
+ user-defined command), the CLI 'thread' command, will generate this
+ notification.
+
+ We suggest that in response to this notification, front ends
+ highlight the selected thread and cause subsequent commands to
+ apply to that thread.
+
+'=library-loaded,...'
+ Reports that a new library file was loaded by the program. This
+ notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and
+ SYMBOLS-LOADED. The ID field is an opaque identifier of the
+ library. For remote debugging case, TARGET-NAME and HOST-NAME
+ fields give the name of the library file on the target, and on the
+ host respectively. For native debugging, both those fields have
+ the same value. The SYMBOLS-LOADED field is emitted only for
+ backward compatibility and should not be relied on to convey any
+ useful information. The THREAD-GROUP field, if present, specifies
+ the id of the thread group in whose context the library was loaded.
+ If the field is absent, it means the library was loaded in the
+ context of all present thread groups.
+
+'=library-unloaded,...'
+ Reports that a library was unloaded by the program. This
+ notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the
+ same meaning as for the '=library-loaded' notification. The
+ THREAD-GROUP field, if present, specifies the id of the thread
+ group in whose context the library was unloaded. If the field is
+ absent, it means the library was unloaded in the context of all
+ present thread groups.
+
+'=traceframe-changed,num=TFNUM,tracepoint=TPNUM'
+'=traceframe-changed,end'
+ Reports that the trace frame was changed and its new number is
+ TFNUM. The number of the tracepoint associated with this trace
+ frame is TPNUM.
+
+'=tsv-created,name=NAME,initial=INITIAL'
+ Reports that the new trace state variable NAME is created with
+ initial value INITIAL.
+
+'=tsv-deleted,name=NAME'
+'=tsv-deleted'
+ Reports that the trace state variable NAME is deleted or all trace
+ state variables are deleted.
+
+'=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]'
+ Reports that the trace state variable NAME is modified with the
+ initial value INITIAL. The current value CURRENT of trace state
+ variable is optional and is reported if the current value of trace
+ state variable is known.
+
+'=breakpoint-created,bkpt={...}'
+'=breakpoint-modified,bkpt={...}'
+'=breakpoint-deleted,id=NUMBER'
+ Reports that a breakpoint was created, modified, or deleted,
+ respectively. Only user-visible breakpoints are reported to the MI
+ user.
+
+ The BKPT argument is of the same form as returned by the various
+ breakpoint commands; *Note GDB/MI Breakpoint Commands::. The
+ NUMBER is the ordinal number of the breakpoint.
+
+ Note that if a breakpoint is emitted in the result record of a
+ command, then it will not also be emitted in an async record.
+
+'=record-started,thread-group="ID"'
+'=record-stopped,thread-group="ID"'
+ Execution log recording was either started or stopped on an
+ inferior. The ID is the GDB identifier of the thread group
+ corresponding to the affected inferior.
+
+'=cmd-param-changed,param=PARAM,value=VALUE'
+ Reports that a parameter of the command 'set PARAM' is changed to
+ VALUE. In the multi-word 'set' command, the PARAM is the whole
+ parameter list to 'set' command. For example, In command 'set
+ check type on', PARAM is 'check type' and VALUE is 'on'.
+
+'=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]'
+ Reports that bytes from ADDR to DATA + LEN were written in an
+ inferior. The ID is the identifier of the thread group
+ corresponding to the affected inferior. The optional 'type="code"'
+ part is reported if the memory written to holds executable code.
\1f
-File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
+File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
-C.4 Specifying Names for Hosts and Targets
-==========================================
+27.5.4 GDB/MI Breakpoint Information
+------------------------------------
-The specifications used for hosts and targets in the `configure' script
-are based on a three-part naming scheme, but some short predefined
-aliases are also supported. The full naming scheme encodes three pieces
-of information in the following pattern:
+When GDB reports information about a breakpoint, a tracepoint, a
+watchpoint, or a catchpoint, it uses a tuple with the following fields:
- ARCHITECTURE-VENDOR-OS
+'number'
+ The breakpoint number. For a breakpoint that represents one
+ location of a multi-location breakpoint, this will be a dotted
+ pair, like '1.2'.
- For example, you can use the alias `sun4' as a HOST argument, or as
-the value for TARGET in a `--target=TARGET' option. The equivalent
-full name is `sparc-sun-sunos4'.
+'type'
+ The type of the breakpoint. For ordinary breakpoints this will be
+ 'breakpoint', but many values are possible.
- The `configure' script accompanying GDB does not provide any query
-facility to list all supported host and target names or aliases.
-`configure' calls the Bourne shell script `config.sub' to map
-abbreviations to full names; you can read the script, if you wish, or
-you can use it to test your guesses on abbreviations--for example:
+'catch-type'
+ If the type of the breakpoint is 'catchpoint', then this indicates
+ the exact type of catchpoint.
- % sh config.sub i386-linux
- i386-pc-linux-gnu
- % sh config.sub alpha-linux
- alpha-unknown-linux-gnu
- % sh config.sub hp9k700
- hppa1.1-hp-hpux
- % sh config.sub sun4
- sparc-sun-sunos4.1.1
- % sh config.sub sun3
- m68k-sun-sunos4.1.1
- % sh config.sub i986v
- Invalid configuration `i986v': machine `i986v' not recognized
+'disp'
+ This is the breakpoint disposition--either 'del', meaning that the
+ breakpoint will be deleted at the next stop, or 'keep', meaning
+ that the breakpoint will not be deleted.
-`config.sub' is also distributed in the GDB source directory
-(`gdb-7.5', for version 7.5).
+'enabled'
+ This indicates whether the breakpoint is enabled, in which case the
+ value is 'y', or disabled, in which case the value is 'n'. Note
+ that this is not the same as the field 'enable'.
-\1f
-File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
+'addr'
+ The address of the breakpoint. This may be a hexidecimal number,
+ giving the address; or the string '<PENDING>', for a pending
+ breakpoint; or the string '<MULTIPLE>', for a breakpoint with
+ multiple locations. This field will not be present if no address
+ can be determined. For example, a watchpoint does not have an
+ address.
-C.5 `configure' Options
-=======================
+'func'
+ If known, the function in which the breakpoint appears. If not
+ known, this field is not present.
-Here is a summary of the `configure' options and arguments that are
-most often useful for building GDB. `configure' also has several other
-options not listed here. *note (configure.info)What Configure Does::,
-for a full explanation of `configure'.
+'filename'
+ The name of the source file which contains this function, if known.
+ If not known, this field is not present.
- configure [--help]
- [--prefix=DIR]
- [--exec-prefix=DIR]
- [--srcdir=DIRNAME]
- [--norecursion] [--rm]
- [--target=TARGET]
- HOST
+'fullname'
+ The full file name of the source file which contains this function,
+ if known. If not known, this field is not present.
-You may introduce options with a single `-' rather than `--' if you
-prefer; but you may abbreviate option names if you use `--'.
+'line'
+ The line number at which this breakpoint appears, if known. If not
+ known, this field is not present.
-`--help'
- Display a quick summary of how to invoke `configure'.
+'at'
+ If the source file is not known, this field may be provided. If
+ provided, this holds the address of the breakpoint, possibly
+ followed by a symbol name.
-`--prefix=DIR'
- Configure the source to install programs and files under directory
- `DIR'.
-
-`--exec-prefix=DIR'
- Configure the source to install programs under directory `DIR'.
-
-`--srcdir=DIRNAME'
- *Warning: using this option requires GNU `make', or another `make'
- that implements the `VPATH' feature.*
- Use this option to make configurations in directories separate
- from the GDB source directories. Among other things, you can use
- this to build (or maintain) several configurations simultaneously,
- in separate directories. `configure' writes
- configuration-specific files in the current directory, but
- arranges for them to use the source in the directory DIRNAME.
- `configure' creates directories under the working directory in
- parallel to the source directories below DIRNAME.
-
-`--norecursion'
- Configure only the directory level where `configure' is executed;
- do not propagate configuration to subdirectories.
+'pending'
+ If this breakpoint is pending, this field is present and holds the
+ text used to set the breakpoint, as entered by the user.
-`--target=TARGET'
- Configure GDB for cross-debugging programs running on the specified
- TARGET. Without this option, GDB is configured to debug programs
- that run on the same machine (HOST) as GDB itself.
+'evaluated-by'
+ Where this breakpoint's condition is evaluated, either 'host' or
+ 'target'.
- There is no convenient way to generate a list of all available
- targets.
+'thread'
+ If this is a thread-specific breakpoint, then this identifies the
+ thread in which the breakpoint can trigger.
-`HOST ...'
- Configure GDB to run on the specified HOST.
+'task'
+ If this breakpoint is restricted to a particular Ada task, then
+ this field will hold the task identifier.
- There is no convenient way to generate a list of all available
- hosts.
+'cond'
+ If the breakpoint is conditional, this is the condition expression.
- There are many other options available as well, but they are
-generally needed for special purposes only.
+'ignore'
+ The ignore count of the breakpoint.
-\1f
-File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
+'enable'
+ The enable count of the breakpoint.
-C.6 System-wide configuration and settings
-==========================================
+'traceframe-usage'
+ FIXME.
-GDB can be configured to have a system-wide init file; this file will
-be read and executed at startup (*note What GDB does during startup:
-Startup.).
+'static-tracepoint-marker-string-id'
+ For a static tracepoint, the name of the static tracepoint marker.
- Here is the corresponding configure option:
+'mask'
+ For a masked watchpoint, this is the mask.
-`--with-system-gdbinit=FILE'
- Specify that the default location of the system-wide init file is
- FILE.
+'pass'
+ A tracepoint's pass count.
- If GDB has been configured with the option `--prefix=$prefix', it
-may be subject to relocation. Two possible cases:
+'original-location'
+ The location of the breakpoint as originally specified by the user.
+ This field is optional.
- * If the default location of this init file contains `$prefix', it
- will be subject to relocation. Suppose that the configure options
- are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
- if GDB is moved from `$prefix' to `$install', the system init file
- is looked for as `$install/etc/gdbinit' instead of
- `$prefix/etc/gdbinit'.
+'times'
+ The number of times the breakpoint has been hit.
- * By contrast, if the default location does not contain the prefix,
- it will not be relocated. E.g. if GDB has been configured with
- `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
- then GDB will always look for `/usr/share/gdb/gdbinit', wherever
- GDB is installed.
+'installed'
+ This field is only given for tracepoints. This is either 'y',
+ meaning that the tracepoint is installed, or 'n', meaning that it
+ is not.
+
+'what'
+ Some extra data, the exact contents of which are type-dependent.
+
+ For example, here is what the output of '-break-insert' (*note GDB/MI
+Breakpoint Commands::) might be:
+
+ -> -break-insert main
+ <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
+ enabled="y",addr="0x08048564",func="main",file="myprog.c",
+ fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
+ times="0"}
+ <- (gdb)
\1f
-File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
+File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records
-Appendix D Maintenance Commands
-*******************************
+27.5.5 GDB/MI Frame Information
+-------------------------------
-In addition to commands intended for GDB users, GDB includes a number
-of commands intended for GDB developers, that are not documented
-elsewhere in this manual. These commands are provided here for
-reference. (For commands that turn on debugging messages, see *Note
-Debugging Output::.)
+Response from many MI commands includes an information about stack
+frame. This information is a tuple that may have the following fields:
-`maint agent [-at LOCATION,] EXPRESSION'
-`maint agent-eval [-at LOCATION,] EXPRESSION'
- Translate the given EXPRESSION into remote agent bytecodes. This
- command is useful for debugging the Agent Expression mechanism
- (*note Agent Expressions::). The `agent' version produces an
- expression useful for data collection, such as by tracepoints,
- while `maint agent-eval' produces an expression that evaluates
- directly to a result. For instance, a collection expression for
- `globa + globb' will include bytecodes to record four bytes of
- memory at each of the addresses of `globa' and `globb', while
- discarding the result of the addition, while an evaluation
- expression will do the addition and return the sum. If `-at' is
- given, generate remote agent bytecode for LOCATION. If not,
- generate remote agent bytecode for current frame PC address.
+'level'
+ The level of the stack frame. The innermost frame has the level of
+ zero. This field is always present.
-`maint agent-printf FORMAT,EXPR,...'
- Translate the given format string and list of argument expressions
- into remote agent bytecodes and display them as a disassembled
- list. This command is useful for debugging the agent version of
- dynamic printf (*note Dynamic Printf::.
+'func'
+ The name of the function corresponding to the frame. This field
+ may be absent if GDB is unable to determine the function name.
-`maint info breakpoints'
- Using the same format as `info breakpoints', display both the
- breakpoints you've set explicitly, and those GDB is using for
- internal purposes. Internal breakpoints are shown with negative
- breakpoint numbers. The type column identifies what kind of
- breakpoint is shown:
+'addr'
+ The code address for the frame. This field is always present.
- `breakpoint'
- Normal, explicitly set breakpoint.
+'file'
+ The name of the source files that correspond to the frame's code
+ address. This field may be absent.
- `watchpoint'
- Normal, explicitly set watchpoint.
+'line'
+ The source line corresponding to the frames' code address. This
+ field may be absent.
- `longjmp'
- Internal breakpoint, used to handle correctly stepping through
- `longjmp' calls.
+'from'
+ The name of the binary file (either executable or shared library)
+ the corresponds to the frame's code address. This field may be
+ absent.
- `longjmp resume'
- Internal breakpoint at the target of a `longjmp'.
+\1f
+File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records
- `until'
- Temporary internal breakpoint used by the GDB `until' command.
+27.5.6 GDB/MI Thread Information
+--------------------------------
- `finish'
- Temporary internal breakpoint used by the GDB `finish'
- command.
+Whenever GDB has to report an information about a thread, it uses a
+tuple with the following fields:
- `shlib events'
- Shared library events.
+'id'
+ The numeric id assigned to the thread by GDB. This field is always
+ present.
+'target-id'
+ Target-specific string identifying the thread. This field is
+ always present.
-`set displaced-stepping'
-`show displaced-stepping'
- Control whether or not GDB will do "displaced stepping" if the
- target supports it. Displaced stepping is a way to single-step
- over breakpoints without removing them from the inferior, by
- executing an out-of-line copy of the instruction that was
- originally at the breakpoint location. It is also known as
- out-of-line single-stepping.
+'details'
+ Additional information about the thread provided by the target. It
+ is supposed to be human-readable and not interpreted by the
+ frontend. This field is optional.
- `set displaced-stepping on'
- If the target architecture supports it, GDB will use
- displaced stepping to step over breakpoints.
+'state'
+ Either 'stopped' or 'running', depending on whether the thread is
+ presently running. This field is always present.
- `set displaced-stepping off'
- GDB will not use displaced stepping to step over breakpoints,
- even if such is supported by the target architecture.
+'core'
+ The value of this field is an integer number of the processor core
+ the thread was last seen on. This field is optional.
- `set displaced-stepping auto'
- This is the default mode. GDB will use displaced stepping
- only if non-stop mode is active (*note Non-Stop Mode::) and
- the target architecture supports displaced stepping.
+\1f
+File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records
-`maint check-symtabs'
- Check the consistency of psymtabs and symtabs.
+27.5.7 GDB/MI Ada Exception Information
+---------------------------------------
-`maint cplus first_component NAME'
- Print the first C++ class/namespace component of NAME.
+Whenever a '*stopped' record is emitted because the program stopped
+after hitting an exception catchpoint (*note Set Catchpoints::), GDB
+provides the name of the exception that was raised via the
+'exception-name' field.
-`maint cplus namespace'
- Print the list of possible C++ namespaces.
+\1f
+File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI
-`maint demangle NAME'
- Demangle a C++ or Objective-C mangled NAME.
+27.6 Simple Examples of GDB/MI Interaction
+==========================================
-`maint deprecate COMMAND [REPLACEMENT]'
-`maint undeprecate COMMAND'
- Deprecate or undeprecate the named COMMAND. Deprecated commands
- cause GDB to issue a warning when you use them. The optional
- argument REPLACEMENT says which newer command should be used in
- favor of the deprecated one; if it is given, GDB will mention the
- replacement as part of the warning.
+This subsection presents several simple examples of interaction using
+the GDB/MI interface. In these examples, '->' means that the following
+line is passed to GDB/MI as input, while '<-' means the output received
+from GDB/MI.
+
+ Note the line breaks shown in the examples are here only for
+readability, they don't appear in the real output.
+
+Setting a Breakpoint
+--------------------
+
+Setting a breakpoint generates synchronous output which contains
+detailed information of the breakpoint.
+
+ -> -break-insert main
+ <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
+ enabled="y",addr="0x08048564",func="main",file="myprog.c",
+ fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
+ times="0"}
+ <- (gdb)
+
+Program Execution
+-----------------
+
+Program execution generates asynchronous records and MI gives the reason
+that execution stopped.
+
+ -> -exec-run
+ <- ^running
+ <- (gdb)
+ <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
+ frame={addr="0x08048564",func="main",
+ args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],
+ file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"}
+ <- (gdb)
+ -> -exec-continue
+ <- ^running
+ <- (gdb)
+ <- *stopped,reason="exited-normally"
+ <- (gdb)
+
+Quitting GDB
+------------
-`maint dump-me'
- Cause a fatal signal in the debugger and force it to dump its core.
- This is supported only on systems which support aborting a program
- with the `SIGQUIT' signal.
+Quitting GDB just prints the result class '^exit'.
-`maint internal-error [MESSAGE-TEXT]'
-`maint internal-warning [MESSAGE-TEXT]'
- Cause GDB to call the internal function `internal_error' or
- `internal_warning' and hence behave as though an internal error or
- internal warning has been detected. In addition to reporting the
- internal problem, these functions give the user the opportunity to
- either quit GDB or create a core file of the current GDB session.
+ -> (gdb)
+ <- -gdb-exit
+ <- ^exit
- These commands take an optional parameter MESSAGE-TEXT that is
- used as the text of the error or warning message.
+ Please note that '^exit' is printed immediately, but it might take
+some time for GDB to actually exit. During that time, GDB performs
+necessary cleanups, including killing programs being debugged or
+disconnecting from debug hardware, so the frontend should wait till GDB
+exits and should only forcibly kill GDB if it fails to exit in
+reasonable time.
- Here's an example of using `internal-error':
+A Bad Command
+-------------
- (gdb) maint internal-error testing, 1, 2
- .../maint.c:121: internal-error: testing, 1, 2
- A problem internal to GDB has been detected. Further
- debugging may prove unreliable.
- Quit this debugging session? (y or n) n
- Create a core file? (y or n) n
- (gdb)
+Here's what happens if you pass a non-existent command:
-`maint set internal-error ACTION [ask|yes|no]'
-`maint show internal-error ACTION'
-`maint set internal-warning ACTION [ask|yes|no]'
-`maint show internal-warning ACTION'
- When GDB reports an internal problem (error or warning) it gives
- the user the opportunity to both quit GDB and create a core file
- of the current GDB session. These commands let you override the
- default behaviour for each particular ACTION, described in the
- table below.
+ -> -rubbish
+ <- ^error,msg="Undefined MI command: rubbish"
+ <- (gdb)
- `quit'
- You can specify that GDB should always (yes) or never (no)
- quit. The default is to ask the user what to do.
+\1f
+File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
- `corefile'
- You can specify that GDB should always (yes) or never (no)
- create a core file. The default is to ask the user what to
- do.
+27.7 GDB/MI Command Description Format
+======================================
-`maint packet TEXT'
- If GDB is talking to an inferior via the serial protocol, then
- this command sends the string TEXT to the inferior, and displays
- the response packet. GDB supplies the initial `$' character, the
- terminating `#' character, and the checksum.
+The remaining sections describe blocks of commands. Each block of
+commands is laid out in a fashion similar to this section.
-`maint print architecture [FILE]'
- Print the entire architecture configuration. The optional argument
- FILE names the file where the output goes.
+Motivation
+----------
-`maint print c-tdesc'
- Print the current target description (*note Target Descriptions::)
- as a C source file. The created source file can be used in GDB
- when an XML parser is not available to parse the description.
+The motivation for this collection of commands.
-`maint print dummy-frames'
- Prints the contents of GDB's internal dummy-frame stack.
+Introduction
+------------
- (gdb) b add
- ...
- (gdb) print add(2,3)
- Breakpoint 2, add (a=2, b=3) at ...
- 58 return (a + b);
- The program being debugged stopped while in a function called from GDB.
- ...
- (gdb) maint print dummy-frames
- 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
- top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
- call_lo=0x01014000 call_hi=0x01014001
- (gdb)
+A brief introduction to this collection of commands as a whole.
- Takes an optional file parameter.
+Commands
+--------
-`maint print registers [FILE]'
-`maint print raw-registers [FILE]'
-`maint print cooked-registers [FILE]'
-`maint print register-groups [FILE]'
-`maint print remote-registers [FILE]'
- Print GDB's internal register data structures.
+For each command in the block, the following is described:
- The command `maint print raw-registers' includes the contents of
- the raw register cache; the command `maint print cooked-registers'
- includes the (cooked) value of all registers, including registers
- which aren't available on the target nor visible to user; the
- command `maint print register-groups' includes the groups that
- each register is a member of; and the command `maint print
- remote-registers' includes the remote target's register numbers
- and offsets in the `G' packets. *Note Registers:
- (gdbint)Registers.
+Synopsis
+........
- These commands take an optional parameter, a file name to which to
- write the information.
+ -command ARGS...
-`maint print reggroups [FILE]'
- Print GDB's internal register group data structures. The optional
- argument FILE tells to what file to write the information.
+Result
+......
- The register groups info looks like this:
+GDB Command
+...........
- (gdb) maint print reggroups
- Group Type
- general user
- float user
- all user
- vector user
- system user
- save internal
- restore internal
+The corresponding GDB CLI command(s), if any.
-`flushregs'
- This command forces GDB to flush its internal register cache.
+Example
+.......
-`maint print objfiles'
- Print a dump of all known object files. For each object file, this
- command prints its name, address in memory, and all of its psymtabs
- and symtabs.
+Example(s) formatted for readability. Some of the described commands
+have not been implemented yet and these are labeled N.A. (not
+available).
-`maint print section-scripts [REGEXP]'
- Print a dump of scripts specified in the `.debug_gdb_section'
- section. If REGEXP is specified, only print scripts loaded by
- object files matching REGEXP. For each script, this command
- prints its name as specified in the objfile, and the full path if
- known. *Note dotdebug_gdb_scripts section::.
+\1f
+File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI
-`maint print statistics'
- This command prints, for each object file in the program, various
- data about that object file followed by the byte cache ("bcache")
- statistics for the object file. The objfile data includes the
- number of minimal, partial, full, and stabs symbols, the number of
- types defined by the objfile, the number of as yet unexpanded psym
- tables, the number of line tables and string tables, and the
- amount of memory used by the various tables. The bcache
- statistics include the counts, sizes, and counts of duplicates of
- all and unique objects, max, average, and median entry size, total
- memory used and its overhead and savings, and various measures of
- the hash table size and chain lengths.
-
-`maint print target-stack'
- A "target" is an interface between the debugger and a particular
- kind of file or process. Targets can be stacked in "strata", so
- that more than one target can potentially respond to a request.
- In particular, memory accesses will walk down the stack of targets
- until they find a target that is interested in handling that
- particular address.
+27.8 GDB/MI Breakpoint Commands
+===============================
- This command prints a short description of each layer that was
- pushed on the "target stack", starting from the top layer down to
- the bottom one.
+This section documents GDB/MI commands for manipulating breakpoints.
-`maint print type EXPR'
- Print the type chain for a type specified by EXPR. The argument
- can be either a type name or a symbol. If it is a symbol, the
- type of that symbol is described. The type chain produced by this
- command is a recursive definition of the data type as stored in
- GDB's data structures, including its flags and contained types.
+The '-break-after' Command
+--------------------------
-`maint set dwarf2 always-disassemble'
+Synopsis
+........
-`maint show dwarf2 always-disassemble'
- Control the behavior of `info address' when using DWARF debugging
- information.
+ -break-after NUMBER COUNT
- The default is `off', which means that GDB should try to describe
- a variable's location in an easily readable format. When `on',
- GDB will instead display the DWARF location expression in an
- assembly-like format. Note that some locations are too complex
- for GDB to describe simply; in this case you will always see the
- disassembly form.
+ The breakpoint number NUMBER is not in effect until it has been hit
+COUNT times. To see how this is reflected in the output of the
+'-break-list' command, see the description of the '-break-list' command
+below.
- Here is an example of the resulting disassembly:
+GDB Command
+...........
- (gdb) info addr argc
- Symbol "argc" is a complex DWARF expression:
- 1: DW_OP_fbreg 0
+The corresponding GDB command is 'ignore'.
+
+Example
+.......
+
+ (gdb)
+ -break-insert main
+ ^done,bkpt={number="1",type="breakpoint",disp="keep",
+ enabled="y",addr="0x000100d0",func="main",file="hello.c",
+ fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
+ times="0"}
+ (gdb)
+ -break-after 1 3
+ ~
+ ^done
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="1",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+ line="5",thread-groups=["i1"],times="0",ignore="3"}]}
+ (gdb)
+
+The '-break-commands' Command
+-----------------------------
- For more information on these expressions, see the DWARF standard
- (http://www.dwarfstd.org/).
+Synopsis
+........
-`maint set dwarf2 max-cache-age'
-`maint show dwarf2 max-cache-age'
- Control the DWARF 2 compilation unit cache.
+ -break-commands NUMBER [ COMMAND1 ... COMMANDN ]
- In object files with inter-compilation-unit references, such as
- those produced by the GCC option `-feliminate-dwarf2-dups', the
- DWARF 2 reader needs to frequently refer to previously read
- compilation units. This setting controls how long a compilation
- unit will remain in the cache if it is not referenced. A higher
- limit means that cached compilation units will be stored in memory
- longer, and more total memory will be used. Setting it to zero
- disables caching, which will slow down GDB startup, but reduce
- memory consumption.
+ Specifies the CLI commands that should be executed when breakpoint
+NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands.
+If no command is specified, any previously-set commands are cleared.
+*Note Break Commands::. Typical use of this functionality is tracing a
+program, that is, printing of values of some variables whenever
+breakpoint is hit and then continuing.
-`maint set profile'
-`maint show profile'
- Control profiling of GDB.
+GDB Command
+...........
- Profiling will be disabled until you use the `maint set profile'
- command to enable it. When you enable profiling, the system will
- begin collecting timing and execution count data; when you disable
- profiling or exit GDB, the results will be written to a log file.
- Remember that if you use profiling, GDB will overwrite the
- profiling log file (often called `gmon.out'). If you have a
- record of important profiling data in a `gmon.out' file, be sure
- to move it to a safe location.
+The corresponding GDB command is 'commands'.
- Configuring with `--enable-profiling' arranges for GDB to be
- compiled with the `-pg' compiler option.
+Example
+.......
-`maint set show-debug-regs'
-`maint show show-debug-regs'
- Control whether to show variables that mirror the hardware debug
- registers. Use `ON' to enable, `OFF' to disable. If enabled, the
- debug registers values are shown when GDB inserts or removes a
- hardware breakpoint or watchpoint, and when the inferior triggers
- a hardware-assisted breakpoint or watchpoint.
+ (gdb)
+ -break-insert main
+ ^done,bkpt={number="1",type="breakpoint",disp="keep",
+ enabled="y",addr="0x000100d0",func="main",file="hello.c",
+ fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
+ times="0"}
+ (gdb)
+ -break-commands 1 "print v" "continue"
+ ^done
+ (gdb)
-`maint set show-all-tib'
-`maint show show-all-tib'
- Control whether to show all non zero areas within a 1k block
- starting at thread local base, when using the `info w32
- thread-information-block' command.
+The '-break-condition' Command
+------------------------------
-`maint space'
- Control whether to display memory usage for each command. If set
- to a nonzero value, GDB will display how much memory each command
- took, following the command's own output. This can also be
- requested by invoking GDB with the `--statistics' command-line
- switch (*note Mode Options::).
-
-`maint time'
- Control whether to display the execution time of GDB for each
- command. If set to a nonzero value, GDB will display how much
- time it took to execute each command, following the command's own
- output. Both CPU time and wallclock time are printed. Printing
- both is useful when trying to determine whether the cost is CPU
- or, e.g., disk/network, latency. Note that the CPU time printed
- is for GDB only, it does not include the execution time of the
- inferior because there's no mechanism currently to compute how
- much time was spent by GDB and how much time was spent by the
- program been debugged. This can also be requested by invoking GDB
- with the `--statistics' command-line switch (*note Mode Options::).
-
-`maint translate-address [SECTION] ADDR'
- Find the symbol stored at the location specified by the address
- ADDR and an optional section name SECTION. If found, GDB prints
- the name of the closest symbol and an offset from the symbol's
- location to the specified address. This is similar to the `info
- address' command (*note Symbols::), except that this command also
- allows to find symbols in other sections.
+Synopsis
+........
- If section was not specified, the section in which the symbol was
- found is also printed. For dynamically linked executables, the
- name of executable or shared library containing the symbol is
- printed as well.
+ -break-condition NUMBER EXPR
+ Breakpoint NUMBER will stop the program only if the condition in EXPR
+is true. The condition becomes part of the '-break-list' output (see
+the description of the '-break-list' command below).
- The following command is useful for non-interactive invocations of
-GDB, such as in the test suite.
+GDB Command
+...........
-`set watchdog NSEC'
- Set the maximum number of seconds GDB will wait for the target
- operation to finish. If this time expires, GDB reports and error
- and the command is aborted.
+The corresponding GDB command is 'condition'.
+
+Example
+.......
+
+ (gdb)
+ -break-condition 1 1
+ ^done
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="1",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+ line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]}
+ (gdb)
+
+The '-break-delete' Command
+---------------------------
-`show watchdog'
- Show the current setting of the target wait timeout.
+Synopsis
+........
-\1f
-File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
+ -break-delete ( BREAKPOINT )+
-Appendix E GDB Remote Serial Protocol
-*************************************
+ Delete the breakpoint(s) whose number(s) are specified in the
+argument list. This is obviously reflected in the breakpoint list.
-* Menu:
+GDB Command
+...........
-* Overview::
-* Packets::
-* Stop Reply Packets::
-* General Query Packets::
-* Architecture-Specific Protocol Details::
-* Tracepoint Packets::
-* Host I/O Packets::
-* Interrupts::
-* Notification Packets::
-* Remote Non-Stop::
-* Packet Acknowledgment::
-* Examples::
-* File-I/O Remote Protocol Extension::
-* Library List Format::
-* Library List Format for SVR4 Targets::
-* Memory Map Format::
-* Thread List Format::
-* Traceframe Info Format::
+The corresponding GDB command is 'delete'.
-\1f
-File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
-
-E.1 Overview
-============
-
-There may be occasions when you need to know something about the
-protocol--for example, if there is only one serial port to your target
-machine, you might want your program to do something special if it
-recognizes a packet meant for GDB.
-
- In the examples below, `->' and `<-' are used to indicate
-transmitted and received data, respectively.
-
- All GDB commands and responses (other than acknowledgments and
-notifications, see *Note Notification Packets::) are sent as a PACKET.
-A PACKET is introduced with the character `$', the actual PACKET-DATA,
-and the terminating character `#' followed by a two-digit CHECKSUM:
-
- `$'PACKET-DATA`#'CHECKSUM
- The two-digit CHECKSUM is computed as the modulo 256 sum of all
-characters between the leading `$' and the trailing `#' (an eight bit
-unsigned checksum).
-
- Implementors should note that prior to GDB 5.0 the protocol
-specification also included an optional two-digit SEQUENCE-ID:
-
- `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
-
-That SEQUENCE-ID was appended to the acknowledgment. GDB has never
-output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
-must not accept SEQUENCE-ID.
-
- When either the host or the target machine receives a packet, the
-first response expected is an acknowledgment: either `+' (to indicate
-the package was received correctly) or `-' (to request retransmission):
-
- -> `$'PACKET-DATA`#'CHECKSUM
- <- `+'
- The `+'/`-' acknowledgments can be disabled once a connection is
-established. *Note Packet Acknowledgment::, for details.
-
- The host (GDB) sends COMMANDs, and the target (the debugging stub
-incorporated in your program) sends a RESPONSE. In the case of step
-and continue COMMANDs, the response is only sent when the operation has
-completed, and the target has again stopped all threads in all attached
-processes. This is the default all-stop mode behavior, but the remote
-protocol also supports GDB's non-stop execution mode; see *Note Remote
-Non-Stop::, for details.
-
- PACKET-DATA consists of a sequence of characters with the exception
-of `#' and `$' (see `X' packet for additional exceptions).
-
- Fields within the packet should be separated using `,' `;' or `:'.
-Except where otherwise noted all numbers are represented in HEX with
-leading zeros suppressed.
-
- Implementors should note that prior to GDB 5.0, the character `:'
-could not appear as the third character in a packet (as it would
-potentially conflict with the SEQUENCE-ID).
-
- Binary data in most packets is encoded either as two hexadecimal
-digits per byte of binary data. This allowed the traditional remote
-protocol to work over connections which were only seven-bit clean.
-Some packets designed more recently assume an eight-bit clean
-connection, and use a more efficient encoding to send and receive
-binary data.
-
- The binary data representation uses `7d' (ASCII `}') as an escape
-character. Any escaped byte is transmitted as the escape character
-followed by the original character XORed with `0x20'. For example, the
-byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
-bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
-must always be escaped. Responses sent by the stub must also escape
-`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
-run-length encoded sequence (described next).
-
- Response DATA can be run-length encoded to save space. Run-length
-encoding replaces runs of identical characters with one instance of the
-repeated character, followed by a `*' and a repeat count. The repeat
-count is itself sent encoded, to avoid binary characters in DATA: a
-value of N is sent as `N+29'. For a repeat count greater or equal to
-3, this produces a printable ASCII character, e.g. a space (ASCII code
-32) for a repeat count of 3. (This is because run-length encoding
-starts to win for counts 3 or more.) Thus, for example, `0* ' is a
-run-length encoding of "0000": the space character after `*' means
-repeat the leading `0' `32 - 29 = 3' more times.
-
- The printable characters `#' and `$' or with a numeric value greater
-than 126 must not be used. Runs of six repeats (`#') or seven repeats
-(`$') can be expanded using a repeat count of only five (`"'). For
-example, `00000000' can be encoded as `0*"00'.
-
- The error response returned for some packets includes a two character
-error number. That number is not well defined.
-
- For any COMMAND not supported by the stub, an empty response
-(`$#00') should be returned. That way it is possible to extend the
-protocol. A newer GDB can tell if a packet is supported based on that
-response.
-
- At a minimum, a stub is required to support the `g' and `G' commands
-for register access, and the `m' and `M' commands for memory access.
-Stubs that only control single-threaded targets can implement run
-control with the `c' (continue), and `s' (step) commands. Stubs that
-support multi-threading targets should support the `vCont' command.
-All other commands are optional.
+Example
+.......
-\1f
-File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
+ (gdb)
+ -break-delete 1
+ ^done
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="0",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[]}
+ (gdb)
-E.2 Packets
-===========
+The '-break-disable' Command
+----------------------------
-The following table provides a complete list of all currently defined
-COMMANDs and their corresponding response DATA. *Note File-I/O Remote
-Protocol Extension::, for details about the File I/O extension of the
-remote protocol.
-
- Each packet's description has a template showing the packet's overall
-syntax, followed by an explanation of the packet's meaning. We include
-spaces in some of the templates for clarity; these are not part of the
-packet's syntax. No GDB packet uses spaces to separate its components.
-For example, a template like `foo BAR BAZ' describes a packet
-beginning with the three ASCII bytes `foo', followed by a BAR, followed
-directly by a BAZ. GDB does not transmit a space character between the
-`foo' and the BAR, or between the BAR and the BAZ.
-
- Several packets and replies include a THREAD-ID field to identify a
-thread. Normally these are positive numbers with a target-specific
-interpretation, formatted as big-endian hex strings. A THREAD-ID can
-also be a literal `-1' to indicate all threads, or `0' to pick any
-thread.
-
- In addition, the remote protocol supports a multiprocess feature in
-which the THREAD-ID syntax is extended to optionally include both
-process and thread ID fields, as `pPID.TID'. The PID (process) and TID
-(thread) components each have the format described above: a positive
-number with target-specific interpretation formatted as a big-endian
-hex string, literal `-1' to indicate all processes or threads
-(respectively), or `0' to indicate an arbitrary process or thread.
-Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It
-is an error to specify all processes but a specific thread, such as
-`p-1.TID'. Note that the `p' prefix is _not_ used for those packets
-and replies explicitly documented to include a process ID, rather than
-a THREAD-ID.
+Synopsis
+........
- The multiprocess THREAD-ID syntax extensions are only used if both
-GDB and the stub report support for the `multiprocess' feature using
-`qSupported'. *Note multiprocess extensions::, for more information.
-
- Note that all packet forms beginning with an upper- or lower-case
-letter, other than those described here, are reserved for future use.
-
- Here are the packet descriptions.
+ -break-disable ( BREAKPOINT )+
-`!'
- Enable extended mode. In extended mode, the remote server is made
- persistent. The `R' packet is used to restart the program being
- debugged.
-
- Reply:
- `OK'
- The remote target both supports and has enabled extended mode.
-
-`?'
- Indicate the reason the target halted. The reply is the same as
- for step and continue. This packet has a special interpretation
- when the target is in non-stop mode; see *Note Remote Non-Stop::.
-
- Reply: *Note Stop Reply Packets::, for the reply specifications.
-
-`A ARGLEN,ARGNUM,ARG,...'
- Initialized `argv[]' array passed into program. ARGLEN specifies
- the number of bytes in the hex encoded byte stream ARG. See
- `gdbserver' for more details.
-
- Reply:
- `OK'
- The arguments were set.
-
- `E NN'
- An error occurred.
-
-`b BAUD'
- (Don't use this packet; its behavior is not well-defined.) Change
- the serial line speed to BAUD.
-
- JTC: _When does the transport layer state change? When it's
- received, or after the ACK is transmitted. In either case, there
- are problems if the command or the acknowledgment packet is
- dropped._
-
- Stan: _If people really wanted to add something like this, and get
- it working for the first time, they ought to modify ser-unix.c to
- send some kind of out-of-band message to a specially-setup stub
- and have the switch happen "in between" packets, so that from
- remote protocol's point of view, nothing actually happened._
-
-`B ADDR,MODE'
- Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
-
- Don't use this packet. Use the `Z' and `z' packets instead (*note
- insert breakpoint or watchpoint packet::).
-
-`bc'
- Backward continue. Execute the target system in reverse. No
- parameter. *Note Reverse Execution::, for more information.
-
- Reply: *Note Stop Reply Packets::, for the reply specifications.
-
-`bs'
- Backward single step. Execute one instruction in reverse. No
- parameter. *Note Reverse Execution::, for more information.
-
- Reply: *Note Stop Reply Packets::, for the reply specifications.
-
-`c [ADDR]'
- Continue. ADDR is address to resume. If ADDR is omitted, resume
- at current address.
-
- This packet is deprecated for multi-threading support. *Note
- vCont packet::.
+ Disable the named BREAKPOINT(s). The field 'enabled' in the break
+list is now set to 'n' for the named BREAKPOINT(s).
- Reply: *Note Stop Reply Packets::, for the reply specifications.
+GDB Command
+...........
-`C SIG[;ADDR]'
- Continue with signal SIG (hex signal number). If `;ADDR' is
- omitted, resume at same address.
+The corresponding GDB command is 'disable'.
+
+Example
+.......
+
+ (gdb)
+ -break-disable 2
+ ^done
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="1",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
+ addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+ line="5",thread-groups=["i1"],times="0"}]}
+ (gdb)
+
+The '-break-enable' Command
+---------------------------
- This packet is deprecated for multi-threading support. *Note
- vCont packet::.
+Synopsis
+........
- Reply: *Note Stop Reply Packets::, for the reply specifications.
+ -break-enable ( BREAKPOINT )+
-`d'
- Toggle debug flag.
+ Enable (previously disabled) BREAKPOINT(s).
- Don't use this packet; instead, define a general set packet (*note
- General Query Packets::).
+GDB Command
+...........
-`D'
-`D;PID'
- The first form of the packet is used to detach GDB from the remote
- system. It is sent to the remote target before GDB disconnects
- via the `detach' command.
+The corresponding GDB command is 'enable'.
+
+Example
+.......
+
+ (gdb)
+ -break-enable 2
+ ^done
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="1",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
+ addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+ line="5",thread-groups=["i1"],times="0"}]}
+ (gdb)
+
+The '-break-info' Command
+-------------------------
- The second form, including a process ID, is used when multiprocess
- protocol extensions are enabled (*note multiprocess extensions::),
- to detach only a specific process. The PID is specified as a
- big-endian hex string.
+Synopsis
+........
- Reply:
- `OK'
- for success
+ -break-info BREAKPOINT
- `E NN'
- for an error
+ Get information about a single breakpoint.
-`F RC,EE,CF;XX'
- A reply from GDB to an `F' packet sent by the target. This is
- part of the File-I/O protocol extension. *Note File-I/O Remote
- Protocol Extension::, for the specification.
-
-`g'
- Read general registers.
-
- Reply:
- `XX...'
- Each byte of register data is described by two hex digits.
- The bytes with the register are transmitted in target byte
- order. The size of each register and their position within
- the `g' packet are determined by the GDB internal gdbarch
- functions `DEPRECATED_REGISTER_RAW_SIZE' and
- `gdbarch_register_name'. The specification of several
- standard `g' packets is specified below.
-
- When reading registers from a trace frame (*note Using the
- Collected Data: Analyze Collected Data.), the stub may also
- return a string of literal `x''s in place of the register
- data digits, to indicate that the corresponding register has
- not been collected, thus its value is unavailable. For
- example, for an architecture with 4 registers of 4 bytes
- each, the following reply indicates to GDB that registers 0
- and 2 have not been collected, while registers 1 and 3 have
- been collected, and both have zero value:
-
- -> `g'
- <- `xxxxxxxx00000000xxxxxxxx00000000'
-
- `E NN'
- for an error.
-
-`G XX...'
- Write general registers. *Note read registers packet::, for a
- description of the XX... data.
-
- Reply:
- `OK'
- for success
-
- `E NN'
- for an error
+ The result is a table of breakpoints. *Note GDB/MI Breakpoint
+Information::, for details on the format of each breakpoint in the
+table.
-`H OP THREAD-ID'
- Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
- OP depends on the operation to be performed: it should be `c' for
- step and continue operations (note that this is deprecated,
- supporting the `vCont' command is a better option), `g' for other
- operations. The thread designator THREAD-ID has the format and
- interpretation described in *Note thread-id syntax::.
+GDB Command
+...........
- Reply:
- `OK'
- for success
+The corresponding GDB command is 'info break BREAKPOINT'.
- `E NN'
- for an error
+Example
+.......
-`i [ADDR[,NNN]]'
- Step the remote target by a single clock cycle. If `,NNN' is
- present, cycle step NNN cycles. If ADDR is present, cycle step
- starting at that address.
-
-`I'
- Signal, then cycle step. *Note step with signal packet::. *Note
- cycle step packet::.
-
-`k'
- Kill request.
-
- FIXME: _There is no description of how to operate when a specific
- thread context has been selected (i.e. does 'k' kill only that
- thread?)_.
-
-`m ADDR,LENGTH'
- Read LENGTH bytes of memory starting at address ADDR. Note that
- ADDR may not be aligned to any particular boundary.
-
- The stub need not use any particular size or alignment when
- gathering data from memory for the response; even if ADDR is
- word-aligned and LENGTH is a multiple of the word size, the stub
- is free to use byte accesses, or not. For this reason, this
- packet may not be suitable for accessing memory-mapped I/O devices.
-
- Reply:
- `XX...'
- Memory contents; each byte is transmitted as a two-digit
- hexadecimal number. The reply may contain fewer bytes than
- requested if the server was able to read only part of the
- region of memory.
-
- `E NN'
- NN is errno
-
-`M ADDR,LENGTH:XX...'
- Write LENGTH bytes of memory starting at address ADDR. XX... is
- the data; each byte is transmitted as a two-digit hexadecimal
- number.
-
- Reply:
- `OK'
- for success
-
- `E NN'
- for an error (this includes the case where only part of the
- data was written).
-
-`p N'
- Read the value of register N; N is in hex. *Note read registers
- packet::, for a description of how the returned register value is
- encoded.
-
- Reply:
- `XX...'
- the register's value
-
- `E NN'
- for an error
+N.A.
- `'
- Indicating an unrecognized QUERY.
+The '-break-insert' Command
+---------------------------
-`P N...=R...'
- Write register N... with value R.... The register number N is in
- hexadecimal, and R... contains two hex digits for each byte in the
- register (target byte order).
+Synopsis
+........
+
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
+ [ -c CONDITION ] [ -i IGNORE-COUNT ]
+ [ -p THREAD-ID ] [ LOCATION ]
+
+If specified, LOCATION, can be one of:
+
+ * function
+ * filename:linenum
+ * filename:function
+ * *address
+
+ The possible optional parameters of this command are:
+
+'-t'
+ Insert a temporary breakpoint.
+'-h'
+ Insert a hardware breakpoint.
+'-f'
+ If LOCATION cannot be parsed (for example if it refers to unknown
+ files or functions), create a pending breakpoint. Without this
+ flag, GDB will report an error, and won't create a breakpoint, if
+ LOCATION cannot be parsed.
+'-d'
+ Create a disabled breakpoint.
+'-a'
+ Create a tracepoint. *Note Tracepoints::. When this parameter is
+ used together with '-h', a fast tracepoint is created.
+'-c CONDITION'
+ Make the breakpoint conditional on CONDITION.
+'-i IGNORE-COUNT'
+ Initialize the IGNORE-COUNT.
+'-p THREAD-ID'
+ Restrict the breakpoint to the specified THREAD-ID.
+
+Result
+......
- Reply:
- `OK'
- for success
+*Note GDB/MI Breakpoint Information::, for details on the format of the
+resulting breakpoint.
- `E NN'
- for an error
+ Note: this format is open to change.
-`q NAME PARAMS...'
-`Q NAME PARAMS...'
- General query (`q') and set (`Q'). These packets are described
- fully in *Note General Query Packets::.
+GDB Command
+...........
-`r'
- Reset the entire system.
+The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and
+'thbreak'.
+
+Example
+.......
+
+ (gdb)
+ -break-insert main
+ ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
+ fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
+ times="0"}
+ (gdb)
+ -break-insert -t foo
+ ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
+ fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
+ times="0"}
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="2",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x0001072c", func="main",file="recursive2.c",
+ fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
+ times="0"},
+ bkpt={number="2",type="breakpoint",disp="del",enabled="y",
+ addr="0x00010774",func="foo",file="recursive2.c",
+ fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
+ times="0"}]}
+ (gdb)
+
+The '-dprintf-insert' Command
+-----------------------------
- Don't use this packet; use the `R' packet instead.
+Synopsis
+........
+
+ -dprintf-insert [ -t ] [ -f ] [ -d ]
+ [ -c CONDITION ] [ -i IGNORE-COUNT ]
+ [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ]
+ [ ARGUMENT ]
+
+If specified, LOCATION, can be one of:
+
+ * FUNCTION
+ * FILENAME:LINENUM
+ * FILENAME:function
+ * *ADDRESS
+
+ The possible optional parameters of this command are:
+
+'-t'
+ Insert a temporary breakpoint.
+'-f'
+ If LOCATION cannot be parsed (for example, if it refers to unknown
+ files or functions), create a pending breakpoint. Without this
+ flag, GDB will report an error, and won't create a breakpoint, if
+ LOCATION cannot be parsed.
+'-d'
+ Create a disabled breakpoint.
+'-c CONDITION'
+ Make the breakpoint conditional on CONDITION.
+'-i IGNORE-COUNT'
+ Set the ignore count of the breakpoint (*note ignore count:
+ Conditions.) to IGNORE-COUNT.
+'-p THREAD-ID'
+ Restrict the breakpoint to the specified THREAD-ID.
+
+Result
+......
-`R XX'
- Restart the program being debugged. XX, while needed, is ignored.
- This packet is only available in extended mode (*note extended
- mode::).
+*Note GDB/MI Breakpoint Information::, for details on the format of the
+resulting breakpoint.
- The `R' packet has no reply.
+GDB Command
+...........
-`s [ADDR]'
- Single step. ADDR is the address at which to resume. If ADDR is
- omitted, resume at same address.
+The corresponding GDB command is 'dprintf'.
+
+Example
+.......
+
+ (gdb)
+ 4-dprintf-insert foo "At foo entry\n"
+ 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y",
+ addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
+ fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
+ times="0",script={"printf \"At foo entry\\n\"","continue"},
+ original-location="foo"}
+ (gdb)
+ 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
+ 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y",
+ addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
+ fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
+ times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"},
+ original-location="mi-dprintf.c:26"}
+ (gdb)
+
+The '-break-list' Command
+-------------------------
- This packet is deprecated for multi-threading support. *Note
- vCont packet::.
+Synopsis
+........
+
+ -break-list
+
+ Displays the list of inserted breakpoints, showing the following
+fields:
+
+'Number'
+ number of the breakpoint
+'Type'
+ type of the breakpoint: 'breakpoint' or 'watchpoint'
+'Disposition'
+ should the breakpoint be deleted or disabled when it is hit: 'keep'
+ or 'nokeep'
+'Enabled'
+ is the breakpoint enabled or no: 'y' or 'n'
+'Address'
+ memory location at which the breakpoint is set
+'What'
+ logical location of the breakpoint, expressed by function name,
+ file name, line number
+'Thread-groups'
+ list of thread groups to which this breakpoint applies
+'Times'
+ number of times the breakpoint has been hit
+
+ If there are no breakpoints or watchpoints, the 'BreakpointTable'
+'body' field is an empty list.
+
+GDB Command
+...........
- Reply: *Note Stop Reply Packets::, for the reply specifications.
+The corresponding GDB command is 'info break'.
+
+Example
+.......
+
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="2",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
+ times="0"},
+ bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
+ addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
+ line="13",thread-groups=["i1"],times="0"}]}
+ (gdb)
+
+ Here's an example of the result when there are no breakpoints:
+
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="0",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[]}
+ (gdb)
+
+The '-break-passcount' Command
+------------------------------
-`S SIG[;ADDR]'
- Step with signal. This is analogous to the `C' packet, but
- requests a single-step, rather than a normal resumption of
- execution.
+Synopsis
+........
- This packet is deprecated for multi-threading support. *Note
- vCont packet::.
+ -break-passcount TRACEPOINT-NUMBER PASSCOUNT
- Reply: *Note Stop Reply Packets::, for the reply specifications.
+ Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If
+the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint,
+error is emitted. This corresponds to CLI command 'passcount'.
-`t ADDR:PP,MM'
- Search backwards starting at address ADDR for a match with pattern
- PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
- digits.
+The '-break-watch' Command
+--------------------------
-`T THREAD-ID'
- Find out if the thread THREAD-ID is alive. *Note thread-id
- syntax::.
+Synopsis
+........
- Reply:
- `OK'
- thread is still alive
+ -break-watch [ -a | -r ]
- `E NN'
- thread is dead
+ Create a watchpoint. With the '-a' option it will create an "access"
+watchpoint, i.e., a watchpoint that triggers either on a read from or on
+a write to the memory location. With the '-r' option, the watchpoint
+created is a "read" watchpoint, i.e., it will trigger only when the
+memory location is accessed for reading. Without either of the options,
+the watchpoint created is a regular watchpoint, i.e., it will trigger
+when the memory location is accessed for writing. *Note Setting
+Watchpoints: Set Watchpoints.
-`v'
- Packets starting with `v' are identified by a multi-letter name,
- up to the first `;' or `?' (or the end of the packet).
+ Note that '-break-list' will report a single list of watchpoints and
+breakpoints inserted.
-`vAttach;PID'
- Attach to a new process with the specified process ID PID. The
- process ID is a hexadecimal integer identifying the process. In
- all-stop mode, all threads in the attached process are stopped; in
- non-stop mode, it may be attached without being stopped if that is
- supported by the target.
+GDB Command
+...........
- This packet is only available in extended mode (*note extended
- mode::).
+The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'.
+
+Example
+.......
+
+Setting a watchpoint on a variable in the 'main' function:
+
+ (gdb)
+ -break-watch x
+ ^done,wpt={number="2",exp="x"}
+ (gdb)
+ -exec-continue
+ ^running
+ (gdb)
+ *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
+ value={old="-268439212",new="55"},
+ frame={func="main",args=[],file="recursive2.c",
+ fullname="/home/foo/bar/recursive2.c",line="5"}
+ (gdb)
+
+ Setting a watchpoint on a variable local to a function. GDB will
+stop the program execution twice: first for the variable changing value,
+then for the watchpoint going out of scope.
+
+ (gdb)
+ -break-watch C
+ ^done,wpt={number="5",exp="C"}
+ (gdb)
+ -exec-continue
+ ^running
+ (gdb)
+ *stopped,reason="watchpoint-trigger",
+ wpt={number="5",exp="C"},value={old="-276895068",new="3"},
+ frame={func="callee4",args=[],
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
+ (gdb)
+ -exec-continue
+ ^running
+ (gdb)
+ *stopped,reason="watchpoint-scope",wpnum="5",
+ frame={func="callee3",args=[{name="strarg",
+ value="0x11940 \"A string argument.\""}],
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
+ (gdb)
+
+ Listing breakpoints and watchpoints, at different points in the
+program execution. Note that once the watchpoint goes out of scope, it
+is deleted.
+
+ (gdb)
+ -break-watch C
+ ^done,wpt={number="2",exp="C"}
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="2",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x00010734",func="callee4",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
+ times="1"},
+ bkpt={number="2",type="watchpoint",disp="keep",
+ enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]}
+ (gdb)
+ -exec-continue
+ ^running
+ (gdb)
+ *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
+ value={old="-276895068",new="3"},
+ frame={func="callee4",args=[],
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="2",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x00010734",func="callee4",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
+ times="1"},
+ bkpt={number="2",type="watchpoint",disp="keep",
+ enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]}
+ (gdb)
+ -exec-continue
+ ^running
+ ^done,reason="watchpoint-scope",wpnum="2",
+ frame={func="callee3",args=[{name="strarg",
+ value="0x11940 \"A string argument.\""}],
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
+ (gdb)
+ -break-list
+ ^done,BreakpointTable={nr_rows="1",nr_cols="6",
+ hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
+ {width="14",alignment="-1",col_name="type",colhdr="Type"},
+ {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
+ {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
+ {width="10",alignment="-1",col_name="addr",colhdr="Address"},
+ {width="40",alignment="2",col_name="what",colhdr="What"}],
+ body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x00010734",func="callee4",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
+ thread-groups=["i1"],times="1"}]}
+ (gdb)
- Reply:
- `E NN'
- for an error
+\1f
+File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
- `Any stop packet'
- for success in all-stop mode (*note Stop Reply Packets::)
-
- `OK'
- for success in non-stop mode (*note Remote Non-Stop::)
-
-`vCont[;ACTION[:THREAD-ID]]...'
- Resume the inferior, specifying different actions for each thread.
- If an action is specified with no THREAD-ID, then it is applied to
- any threads that don't have a specific action specified; if no
- default action is specified then other threads should remain
- stopped in all-stop mode and in their current state in non-stop
- mode. Specifying multiple default actions is an error; specifying
- no actions is also an error. Thread IDs are specified using the
- syntax described in *Note thread-id syntax::.
-
- Currently supported actions are:
-
- `c'
- Continue.
-
- `C SIG'
- Continue with signal SIG. The signal SIG should be two hex
- digits.
-
- `s'
- Step.
-
- `S SIG'
- Step with signal SIG. The signal SIG should be two hex
- digits.
-
- `t'
- Stop.
-
- The optional argument ADDR normally associated with the `c', `C',
- `s', and `S' packets is not supported in `vCont'.
-
- The `t' action is only relevant in non-stop mode (*note Remote
- Non-Stop::) and may be ignored by the stub otherwise. A stop
- reply should be generated for any affected thread not already
- stopped. When a thread is stopped by means of a `t' action, the
- corresponding stop reply should indicate that the thread has
- stopped with signal `0', regardless of whether the target uses
- some other signal as an implementation detail.
-
- The stub must support `vCont' if it reports support for
- multiprocess extensions (*note multiprocess extensions::). Note
- that in this case `vCont' actions can be specified to apply to all
- threads in a process by using the `pPID.-1' form of the THREAD-ID.
-
- Reply: *Note Stop Reply Packets::, for the reply specifications.
-
-`vCont?'
- Request a list of actions supported by the `vCont' packet.
-
- Reply:
- `vCont[;ACTION...]'
- The `vCont' packet is supported. Each ACTION is a supported
- command in the `vCont' packet.
-
- `'
- The `vCont' packet is not supported.
-
-`vFile:OPERATION:PARAMETER...'
- Perform a file operation on the target system. For details, see
- *Note Host I/O Packets::.
-
-`vFlashErase:ADDR,LENGTH'
- Direct the stub to erase LENGTH bytes of flash starting at ADDR.
- The region may enclose any number of flash blocks, but its start
- and end must fall on block boundaries, as indicated by the flash
- block size appearing in the memory map (*note Memory Map
- Format::). GDB groups flash memory programming operations
- together, and sends a `vFlashDone' request after each group; the
- stub is allowed to delay erase operation until the `vFlashDone'
- packet is received.
-
- Reply:
- `OK'
- for success
-
- `E NN'
- for an error
+27.9 GDB/MI Catchpoint Commands
+===============================
-`vFlashWrite:ADDR:XX...'
- Direct the stub to write data to flash address ADDR. The data is
- passed in binary form using the same encoding as for the `X'
- packet (*note Binary Data::). The memory ranges specified by
- `vFlashWrite' packets preceding a `vFlashDone' packet must not
- overlap, and must appear in order of increasing addresses
- (although `vFlashErase' packets for higher addresses may already
- have been received; the ordering is guaranteed only between
- `vFlashWrite' packets). If a packet writes to an address that was
- neither erased by a preceding `vFlashErase' packet nor by some
- other target-specific method, the results are unpredictable.
-
- Reply:
- `OK'
- for success
-
- `E.memtype'
- for vFlashWrite addressing non-flash memory
-
- `E NN'
- for an error
+This section documents GDB/MI commands for manipulating catchpoints.
-`vFlashDone'
- Indicate to the stub that flash programming operation is finished.
- The stub is permitted to delay or batch the effects of a group of
- `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
- packet is received. The contents of the affected regions of flash
- memory are unpredictable until the `vFlashDone' request is
- completed.
-
-`vKill;PID'
- Kill the process with the specified process ID. PID is a
- hexadecimal integer identifying the process. This packet is used
- in preference to `k' when multiprocess protocol extensions are
- supported; see *Note multiprocess extensions::.
-
- Reply:
- `E NN'
- for an error
+* Menu:
- `OK'
- for success
+* Shared Library GDB/MI Catchpoint Commands::
+* Ada Exception GDB/MI Catchpoint Commands::
-`vRun;FILENAME[;ARGUMENT]...'
- Run the program FILENAME, passing it each ARGUMENT on its command
- line. The file and arguments are hex-encoded strings. If
- FILENAME is an empty string, the stub may use a default program
- (e.g. the last program run). The program is created in the stopped
- state.
+\1f
+File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
- This packet is only available in extended mode (*note extended
- mode::).
+27.9.1 Shared Library GDB/MI Catchpoints
+----------------------------------------
- Reply:
- `E NN'
- for an error
+The '-catch-load' Command
+-------------------------
- `Any stop packet'
- for success (*note Stop Reply Packets::)
+Synopsis
+........
-`vStopped'
- In non-stop mode (*note Remote Non-Stop::), acknowledge a previous
- stop reply and prompt for the stub to report another one.
+ -catch-load [ -t ] [ -d ] REGEXP
- Reply:
- `Any stop packet'
- if there is another unreported stop event (*note Stop Reply
- Packets::)
+ Add a catchpoint for library load events. If the '-t' option is
+used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
+Breaks.). If the '-d' option is used, the catchpoint is created in a
+disabled state. The 'regexp' argument is a regular expression used to
+match the name of the loaded library.
- `OK'
- if there are no unreported stop events
+GDB Command
+...........
-`X ADDR,LENGTH:XX...'
- Write data to memory, where the data is transmitted in binary.
- ADDR is address, LENGTH is number of bytes, `XX...' is binary data
- (*note Binary Data::).
+The corresponding GDB command is 'catch load'.
- Reply:
- `OK'
- for success
+Example
+.......
- `E NN'
- for an error
+ -catch-load -t foo.so
+ ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y",
+ what="load of library matching foo.so",catch-type="load",times="0"}
+ (gdb)
-`z TYPE,ADDR,KIND'
-`Z TYPE,ADDR,KIND'
- Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
- starting at address ADDRESS of kind KIND.
-
- Each breakpoint and watchpoint packet TYPE is documented
- separately.
-
- _Implementation notes: A remote target shall return an empty string
- for an unrecognized breakpoint or watchpoint packet TYPE. A
- remote target shall support either both or neither of a given
- `ZTYPE...' and `zTYPE...' packet pair. To avoid potential
- problems with duplicate packets, the operations should be
- implemented in an idempotent way._
-
-`z0,ADDR,KIND'
-`Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
- Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
- of type KIND.
-
- A memory breakpoint is implemented by replacing the instruction at
- ADDR with a software breakpoint or trap instruction. The KIND is
- target-specific and typically indicates the size of the breakpoint
- in bytes that should be inserted. E.g., the ARM and MIPS can
- insert either a 2 or 4 byte breakpoint. Some architectures have
- additional meanings for KIND; COND_LIST is an optional list of
- conditional expressions in bytecode form that should be evaluated
- on the target's side. These are the conditions that should be
- taken into consideration when deciding if the breakpoint trigger
- should be reported back to GDBN.
-
- The COND_LIST parameter is comprised of a series of expressions,
- concatenated without separators. Each expression has the following
- form:
-
- `X LEN,EXPR'
- LEN is the length of the bytecode expression and EXPR is the
- actual conditional expression in bytecode form.
-
-
- The optional CMD_LIST parameter introduces commands that may be
- run on the target, rather than being reported back to GDB. The
- parameter starts with a numeric flag PERSIST; if the flag is
- nonzero, then the breakpoint may remain active and the commands
- continue to be run even when GDB disconnects from the target.
- Following this flag is a series of expressions concatenated with no
- separators. Each expression has the following form:
-
- `X LEN,EXPR'
- LEN is the length of the bytecode expression and EXPR is the
- actual conditional expression in bytecode form.
-
-
- see *Note Architecture-Specific Protocol Details::.
-
- _Implementation note: It is possible for a target to copy or move
- code that contains memory breakpoints (e.g., when implementing
- overlays). The behavior of this packet, in the presence of such a
- target, is not defined._
-
- Reply:
- `OK'
- success
-
- `'
- not supported
-
- `E NN'
- for an error
+The '-catch-unload' Command
+---------------------------
-`z1,ADDR,KIND'
-`Z1,ADDR,KIND[;COND_LIST...]'
- Insert (`Z1') or remove (`z1') a hardware breakpoint at address
- ADDR.
+Synopsis
+........
- A hardware breakpoint is implemented using a mechanism that is not
- dependant on being able to modify the target's memory. KIND and
- COND_LIST have the same meaning as in `Z0' packets.
+ -catch-unload [ -t ] [ -d ] REGEXP
- _Implementation note: A hardware breakpoint is not affected by code
- movement._
+ Add a catchpoint for library unload events. If the '-t' option is
+used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
+Breaks.). If the '-d' option is used, the catchpoint is created in a
+disabled state. The 'regexp' argument is a regular expression used to
+match the name of the unloaded library.
- Reply:
- `OK'
- success
+GDB Command
+...........
- `'
- not supported
+The corresponding GDB command is 'catch unload'.
- `E NN'
- for an error
+Example
+.......
-`z2,ADDR,KIND'
-`Z2,ADDR,KIND'
- Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND
- is interpreted as the number of bytes to watch.
+ -catch-unload -d bar.so
+ ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n",
+ what="load of library matching bar.so",catch-type="unload",times="0"}
+ (gdb)
- Reply:
- `OK'
- success
+\1f
+File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
- `'
- not supported
+27.9.2 Ada Exception GDB/MI Catchpoints
+---------------------------------------
- `E NN'
- for an error
+The following GDB/MI commands can be used to create catchpoints that
+stop the execution when Ada exceptions are being raised.
-`z3,ADDR,KIND'
-`Z3,ADDR,KIND'
- Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is
- interpreted as the number of bytes to watch.
+The '-catch-assert' Command
+---------------------------
- Reply:
- `OK'
- success
+Synopsis
+........
- `'
- not supported
+ -catch-assert [ -c CONDITION] [ -d ] [ -t ]
- `E NN'
- for an error
+ Add a catchpoint for failed Ada assertions.
-`z4,ADDR,KIND'
-`Z4,ADDR,KIND'
- Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND
- is interpreted as the number of bytes to watch.
+ The possible optional parameters for this command are:
- Reply:
- `OK'
- success
+'-c CONDITION'
+ Make the catchpoint conditional on CONDITION.
+'-d'
+ Create a disabled catchpoint.
+'-t'
+ Create a temporary catchpoint.
- `'
- not supported
+GDB Command
+...........
- `E NN'
- for an error
+The corresponding GDB command is 'catch assert'.
+Example
+.......
-\1f
-File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
+ -catch-assert
+ ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep",
+ enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
+ thread-groups=["i1"],times="0",
+ original-location="__gnat_debug_raise_assert_failure"}
+ (gdb)
-E.3 Stop Reply Packets
-======================
+The '-catch-exception' Command
+------------------------------
-The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
-packets can receive any of the below as a reply. Except for `?' and
-`vStopped', that reply is only returned when the target halts. In the
-below the exact meaning of "signal number" is defined by the header
-`include/gdb/signals.h' in the GDB source code.
-
- As in the description of request packets, we include spaces in the
-reply templates for clarity; these are not part of the reply packet's
-syntax. No GDB stop reply packet uses spaces to separate its
-components.
-
-`S AA'
- The program received signal number AA (a two-digit hexadecimal
- number). This is equivalent to a `T' response with no N:R pairs.
-
-`T AA N1:R1;N2:R2;...'
- The program received signal number AA (a two-digit hexadecimal
- number). This is equivalent to an `S' response, except that the
- `N:R' pairs can carry values of important registers and other
- information directly in the stop reply packet, reducing round-trip
- latency. Single-step and breakpoint traps are reported this way.
- Each `N:R' pair is interpreted as follows:
-
- * If N is a hexadecimal number, it is a register number, and the
- corresponding R gives that register's value. R is a series
- of bytes in target byte order, with each byte given by a
- two-digit hex number.
-
- * If N is `thread', then R is the THREAD-ID of the stopped
- thread, as specified in *Note thread-id syntax::.
-
- * If N is `core', then R is the hexadecimal number of the core
- on which the stop event was detected.
-
- * If N is a recognized "stop reason", it describes a more
- specific event that stopped the target. The currently
- defined stop reasons are listed below. AA should be `05',
- the trap signal. At most one stop reason should be present.
-
- * Otherwise, GDB should ignore this `N:R' pair and go on to the
- next; this allows us to extend the protocol in the future.
-
- The currently defined stop reasons are:
-
- `watch'
- `rwatch'
- `awatch'
- The packet indicates a watchpoint hit, and R is the data
- address, in hex.
-
- `library'
- The packet indicates that the loaded libraries have changed.
- GDB should use `qXfer:libraries:read' to fetch a new list of
- loaded libraries. R is ignored.
-
- `replaylog'
- The packet indicates that the target cannot continue replaying
- logged execution events, because it has reached the end (or
- the beginning when executing backward) of the log. The value
- of R will be either `begin' or `end'. *Note Reverse
- Execution::, for more information.
-
-`W AA'
-`W AA ; process:PID'
- The process exited, and AA is the exit status. This is only
- applicable to certain targets.
-
- The second form of the response, including the process ID of the
- exited process, can be used only when GDB has reported support for
- multiprocess protocol extensions; see *Note multiprocess
- extensions::. The PID is formatted as a big-endian hex string.
-
-`X AA'
-`X AA ; process:PID'
- The process terminated with signal AA.
-
- The second form of the response, including the process ID of the
- terminated process, can be used only when GDB has reported support
- for multiprocess protocol extensions; see *Note multiprocess
- extensions::. The PID is formatted as a big-endian hex string.
-
-`O XX...'
- `XX...' is hex encoding of ASCII data, to be written as the
- program's console output. This can happen at any time while the
- program is running and the debugger should continue to wait for
- `W', `T', etc. This reply is not permitted in non-stop mode.
-
-`F CALL-ID,PARAMETER...'
- CALL-ID is the identifier which says which host system call should
- be called. This is just the name of the function. Translation
- into the correct system call is only applicable as it's defined in
- GDB. *Note File-I/O Remote Protocol Extension::, for a list of
- implemented system calls.
-
- `PARAMETER...' is a list of parameters as defined for this very
- system call.
-
- The target replies with this packet when it expects GDB to call a
- host system call on behalf of the target. GDB replies with an
- appropriate `F' packet and keeps up waiting for the next reply
- packet from the target. The latest `C', `c', `S' or `s' action is
- expected to be continued. *Note File-I/O Remote Protocol
- Extension::, for more details.
+Synopsis
+........
+
+ -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ]
+ [ -t ] [ -u ]
+
+ Add a catchpoint stopping when Ada exceptions are raised. By
+default, the command stops the program when any Ada exception gets
+raised. But it is also possible, by using some of the optional
+parameters described below, to create more selective catchpoints.
+
+ The possible optional parameters for this command are:
+
+'-c CONDITION'
+ Make the catchpoint conditional on CONDITION.
+'-d'
+ Create a disabled catchpoint.
+'-e EXCEPTION-NAME'
+ Only stop when EXCEPTION-NAME is raised. This option cannot be
+ used combined with '-u'.
+'-t'
+ Create a temporary catchpoint.
+'-u'
+ Stop only when an unhandled exception gets raised. This option
+ cannot be used combined with '-e'.
+
+GDB Command
+...........
+The corresponding GDB commands are 'catch exception' and 'catch
+exception unhandled'.
-\1f
-File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol
+Example
+.......
-E.4 General Query Packets
-=========================
+ -catch-exception -e Program_Error
+ ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep",
+ enabled="y",addr="0x0000000000404874",
+ what="`Program_Error' Ada exception", thread-groups=["i1"],
+ times="0",original-location="__gnat_debug_raise_exception"}
+ (gdb)
-Packets starting with `q' are "general query packets"; packets starting
-with `Q' are "general set packets". General query and set packets are
-a semi-unified form for retrieving and sending information to and from
-the stub.
-
- The initial letter of a query or set packet is followed by a name
-indicating what sort of thing the packet applies to. For example, GDB
-may use a `qSymbol' packet to exchange symbol definitions with the
-stub. These packet names follow some conventions:
-
- * The name must not contain commas, colons or semicolons.
-
- * Most GDB query and set packets have a leading upper case letter.
-
- * The names of custom vendor packets should use a company prefix, in
- lower case, followed by a period. For example, packets designed at
- the Acme Corporation might begin with `qacme.foo' (for querying
- foos) or `Qacme.bar' (for setting bars).
-
- The name of a query or set packet should be separated from any
-parameters by a `:'; the parameters themselves should be separated by
-`,' or `;'. Stubs must be careful to match the full packet name, and
-check for a separator or the end of the packet, in case two packet
-names share a common prefix. New packets should not begin with `qC',
-`qP', or `qL'(1).
-
- Like the descriptions of the other packets, each description here
-has a template showing the packet's overall syntax, followed by an
-explanation of the packet's meaning. We include spaces in some of the
-templates for clarity; these are not part of the packet's syntax. No
-GDB packet uses spaces to separate its components.
-
- Here are the currently defined query and set packets:
-
-`QAgent:1'
-
-`QAgent:0'
- Turn on or off the agent as a helper to perform some debugging
- operations delegated from GDB (*note Control Agent::).
-
-`QAllow:OP:VAL...'
- Specify which operations GDB expects to request of the target, as
- a semicolon-separated list of operation name and value pairs.
- Possible values for OP include `WriteReg', `WriteMem',
- `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL
- is either 0, indicating that GDB will not request the operation,
- or 1, indicating that it may. (The target can then use this to
- set up its own internals optimally, for instance if the debugger
- never expects to insert breakpoints, it may not need to install
- its own trap handler.)
-
-`qC'
- Return the current thread ID.
-
- Reply:
- `QC THREAD-ID'
- Where THREAD-ID is a thread ID as documented in *Note
- thread-id syntax::.
-
- `(anything else)'
- Any other reply implies the old thread ID.
-
-`qCRC:ADDR,LENGTH'
- Compute the CRC checksum of a block of memory using CRC-32 defined
- in IEEE 802.3. The CRC is computed byte at a time, taking the most
- significant bit of each byte first. The initial pattern code
- `0xffffffff' is used to ensure leading zeros affect the CRC.
-
- _Note:_ This is the same CRC used in validating separate debug
- files (*note Debugging Information in Separate Files: Separate
- Debug Files.). However the algorithm is slightly different. When
- validating separate debug files, the CRC is computed taking the
- _least_ significant bit of each byte first, and the final result
- is inverted to detect trailing zeros.
-
- Reply:
- `E NN'
- An error (such as memory fault)
-
- `C CRC32'
- The specified memory region's checksum is CRC32.
-
-`QDisableRandomization:VALUE'
- Some target operating systems will randomize the virtual address
- space of the inferior process as a security feature, but provide a
- feature to disable such randomization, e.g. to allow for a more
- deterministic debugging experience. On such systems, this packet
- with a VALUE of 1 directs the target to disable address space
- randomization for processes subsequently started via `vRun'
- packets, while a packet with a VALUE of 0 tells the target to
- enable address space randomization.
-
- This packet is only available in extended mode (*note extended
- mode::).
-
- Reply:
- `OK'
- The request succeeded.
-
- `E NN'
- An error occurred. NN are hex digits.
-
- `'
- An empty reply indicates that `QDisableRandomization' is not
- supported by the stub.
-
- This packet is not probed by default; the remote stub must request
- it, by supplying an appropriate `qSupported' response (*note
- qSupported::). This should only be done on targets that actually
- support disabling address space randomization.
-
-`qfThreadInfo'
-`qsThreadInfo'
- Obtain a list of all active thread IDs from the target (OS).
- Since there may be too many active threads to fit into one reply
- packet, this query works iteratively: it may require more than one
- query/reply sequence to obtain the entire list of threads. The
- first query of the sequence will be the `qfThreadInfo' query;
- subsequent queries in the sequence will be the `qsThreadInfo'
- query.
-
- NOTE: This packet replaces the `qL' query (see below).
-
- Reply:
- `m THREAD-ID'
- A single thread ID
-
- `m THREAD-ID,THREAD-ID...'
- a comma-separated list of thread IDs
-
- `l'
- (lower case letter `L') denotes end of list.
-
- In response to each query, the target will reply with a list of
- one or more thread IDs, separated by commas. GDB will respond to
- each reply with a request for more thread ids (using the `qs' form
- of the query), until the target responds with `l' (lower-case ell,
- for "last"). Refer to *Note thread-id syntax::, for the format of
- the THREAD-ID fields.
-
-`qGetTLSAddr:THREAD-ID,OFFSET,LM'
- Fetch the address associated with thread local storage specified
- by THREAD-ID, OFFSET, and LM.
-
- THREAD-ID is the thread ID associated with the thread for which to
- fetch the TLS address. *Note thread-id syntax::.
-
- OFFSET is the (big endian, hex encoded) offset associated with the
- thread local variable. (This offset is obtained from the debug
- information associated with the variable.)
-
- LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
- load module associated with the thread local storage. For example,
- a GNU/Linux system will pass the link map address of the shared
- object associated with the thread local storage under
- consideration. Other operating environments may choose to
- represent the load module differently, so the precise meaning of
- this parameter will vary.
-
- Reply:
- `XX...'
- Hex encoded (big endian) bytes representing the address of
- the thread local storage requested.
-
- `E NN'
- An error occurred. NN are hex digits.
-
- `'
- An empty reply indicates that `qGetTLSAddr' is not supported
- by the stub.
-
-`qGetTIBAddr:THREAD-ID'
- Fetch address of the Windows OS specific Thread Information Block.
-
- THREAD-ID is the thread ID associated with the thread.
-
- Reply:
- `XX...'
- Hex encoded (big endian) bytes representing the linear
- address of the thread information block.
-
- `E NN'
- An error occured. This means that either the thread was not
- found, or the address could not be retrieved.
-
- `'
- An empty reply indicates that `qGetTIBAddr' is not supported
- by the stub.
-
-`qL STARTFLAG THREADCOUNT NEXTTHREAD'
- Obtain thread information from RTOS. Where: STARTFLAG (one hex
- digit) is one to indicate the first query and zero to indicate a
- subsequent query; THREADCOUNT (two hex digits) is the maximum
- number of threads the response packet can contain; and NEXTTHREAD
- (eight hex digits), for subsequent queries (STARTFLAG is zero), is
- returned in the response as ARGTHREAD.
-
- Don't use this packet; use the `qfThreadInfo' query instead (see
- above).
-
- Reply:
- `qM COUNT DONE ARGTHREAD THREAD...'
- Where: COUNT (two hex digits) is the number of threads being
- returned; DONE (one hex digit) is zero to indicate more
- threads and one indicates no further threads; ARGTHREADID
- (eight hex digits) is NEXTTHREAD from the request packet;
- THREAD... is a sequence of thread IDs from the target.
- THREADID (eight hex digits). See
- `remote.c:parse_threadlist_response()'.
-
-`qOffsets'
- Get section offsets that the target used when relocating the
- downloaded image.
-
- Reply:
- `Text=XXX;Data=YYY[;Bss=ZZZ]'
- Relocate the `Text' section by XXX from its original address.
- Relocate the `Data' section by YYY from its original address.
- If the object file format provides segment information (e.g.
- ELF `PT_LOAD' program headers), GDB will relocate entire
- segments by the supplied offsets.
-
- _Note: while a `Bss' offset may be included in the response,
- GDB ignores this and instead applies the `Data' offset to the
- `Bss' section._
-
- `TextSeg=XXX[;DataSeg=YYY]'
- Relocate the first segment of the object file, which
- conventionally contains program code, to a starting address
- of XXX. If `DataSeg' is specified, relocate the second
- segment, which conventionally contains modifiable data, to a
- starting address of YYY. GDB will report an error if the
- object file does not contain segment information, or does not
- contain at least as many segments as mentioned in the reply.
- Extra segments are kept at fixed offsets relative to the last
- relocated segment.
-
-`qP MODE THREAD-ID'
- Returns information on THREAD-ID. Where: MODE is a hex encoded 32
- bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
-
- Don't use this packet; use the `qThreadExtraInfo' query instead
- (see below).
-
- Reply: see `remote.c:remote_unpack_thread_info_response()'.
-
-`QNonStop:1'
-
-`QNonStop:0'
- Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode.
- *Note Remote Non-Stop::, for more information.
-
- Reply:
- `OK'
- The request succeeded.
-
- `E NN'
- An error occurred. NN are hex digits.
-
- `'
- An empty reply indicates that `QNonStop' is not supported by
- the stub.
-
- This packet is not probed by default; the remote stub must request
- it, by supplying an appropriate `qSupported' response (*note
- qSupported::). Use of this packet is controlled by the `set
- non-stop' command; *note Non-Stop Mode::.
-
-`QPassSignals: SIGNAL [;SIGNAL]...'
- Each listed SIGNAL should be passed directly to the inferior
- process. Signals are numbered identically to continue packets and
- stop replies (*note Stop Reply Packets::). Each SIGNAL list item
- should be strictly greater than the previous item. These signals
- do not need to stop the inferior, or be reported to GDB. All
- other signals should be reported to GDB. Multiple `QPassSignals'
- packets do not combine; any earlier `QPassSignals' list is
- completely replaced by the new list. This packet improves
- performance when using `handle SIGNAL nostop noprint pass'.
-
- Reply:
- `OK'
- The request succeeded.
-
- `E NN'
- An error occurred. NN are hex digits.
-
- `'
- An empty reply indicates that `QPassSignals' is not supported
- by the stub.
-
- Use of this packet is controlled by the `set remote pass-signals'
- command (*note set remote pass-signals: Remote Configuration.).
- This packet is not probed by default; the remote stub must request
- it, by supplying an appropriate `qSupported' response (*note
- qSupported::).
-
-`QProgramSignals: SIGNAL [;SIGNAL]...'
- Each listed SIGNAL may be delivered to the inferior process.
- Others should be silently discarded.
-
- In some cases, the remote stub may need to decide whether to
- deliver a signal to the program or not without GDB involvement.
- One example of that is while detaching -- the program's threads
- may have stopped for signals that haven't yet had a chance of
- being reported to GDB, and so the remote stub can use the signal
- list specified by this packet to know whether to deliver or ignore
- those pending signals.
-
- This does not influence whether to deliver a signal as requested
- by a resumption packet (*note vCont packet::).
-
- Signals are numbered identically to continue packets and stop
- replies (*note Stop Reply Packets::). Each SIGNAL list item
- should be strictly greater than the previous item. Multiple
- `QProgramSignals' packets do not combine; any earlier
- `QProgramSignals' list is completely replaced by the new list.
-
- Reply:
- `OK'
- The request succeeded.
-
- `E NN'
- An error occurred. NN are hex digits.
-
- `'
- An empty reply indicates that `QProgramSignals' is not
- supported by the stub.
-
- Use of this packet is controlled by the `set remote
- program-signals' command (*note set remote program-signals: Remote
- Configuration.). This packet is not probed by default; the remote
- stub must request it, by supplying an appropriate `qSupported'
- response (*note qSupported::).
-
-`qRcmd,COMMAND'
- COMMAND (hex encoded) is passed to the local interpreter for
- execution. Invalid commands should be reported using the output
- string. Before the final result packet, the target may also
- respond with a number of intermediate `OOUTPUT' console output
- packets. _Implementors should note that providing access to a
- stubs's interpreter may have security implications_.
-
- Reply:
- `OK'
- A command response with no output.
-
- `OUTPUT'
- A command response with the hex encoded output string OUTPUT.
-
- `E NN'
- Indicate a badly formed request.
-
- `'
- An empty reply indicates that `qRcmd' is not recognized.
-
- (Note that the `qRcmd' packet's name is separated from the command
- by a `,', not a `:', contrary to the naming conventions above.
- Please don't use this packet as a model for new packets.)
-
-`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
- Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and
- LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes,
- hex encoded.
-
- Reply:
- `0'
- The pattern was not found.
-
- `1,address'
- The pattern was found at ADDRESS.
-
- `E NN'
- A badly formed request or an error was encountered while
- searching memory.
-
- `'
- An empty reply indicates that `qSearch:memory' is not
- recognized.
-
-`QStartNoAckMode'
- Request that the remote stub disable the normal `+'/`-' protocol
- acknowledgments (*note Packet Acknowledgment::).
-
- Reply:
- `OK'
- The stub has switched to no-acknowledgment mode. GDB
- acknowledges this reponse, but neither the stub nor GDB shall
- send or expect further `+'/`-' acknowledgments in the current
- connection.
-
- `'
- An empty reply indicates that the stub does not support
- no-acknowledgment mode.
-
-`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
- Tell the remote stub about features supported by GDB, and query
- the stub for features it supports. This packet allows GDB and the
- remote stub to take advantage of each others' features.
- `qSupported' also consolidates multiple feature probes at startup,
- to improve GDB performance--a single larger packet performs better
- than multiple smaller probe packets on high-latency links. Some
- features may enable behavior which must not be on by default, e.g.
- because it would confuse older clients or stubs. Other features
- may describe packets which could be automatically probed for, but
- are not. These features must be reported before GDB will use
- them. This "default unsupported" behavior is not appropriate for
- all packets, but it helps to keep the initial connection time
- under control with new versions of GDB which support increasing
- numbers of packets.
-
- Reply:
- `STUBFEATURE [;STUBFEATURE]...'
- The stub supports or does not support each returned
- STUBFEATURE, depending on the form of each STUBFEATURE (see
- below for the possible forms).
-
- `'
- An empty reply indicates that `qSupported' is not recognized,
- or that no features needed to be reported to GDB.
-
- The allowed forms for each feature (either a GDBFEATURE in the
- `qSupported' packet, or a STUBFEATURE in the response) are:
-
- `NAME=VALUE'
- The remote protocol feature NAME is supported, and associated
- with the specified VALUE. The format of VALUE depends on the
- feature, but it must not include a semicolon.
-
- `NAME+'
- The remote protocol feature NAME is supported, and does not
- need an associated value.
-
- `NAME-'
- The remote protocol feature NAME is not supported.
-
- `NAME?'
- The remote protocol feature NAME may be supported, and GDB
- should auto-detect support in some other way when it is
- needed. This form will not be used for GDBFEATURE
- notifications, but may be used for STUBFEATURE responses.
-
- Whenever the stub receives a `qSupported' request, the supplied
- set of GDB features should override any previous request. This
- allows GDB to put the stub in a known state, even if the stub had
- previously been communicating with a different version of GDB.
-
- The following values of GDBFEATURE (for the packet sent by GDB)
- are defined:
-
- `multiprocess'
- This feature indicates whether GDB supports multiprocess
- extensions to the remote protocol. GDB does not use such
- extensions unless the stub also reports that it supports them
- by including `multiprocess+' in its `qSupported' reply.
- *Note multiprocess extensions::, for details.
-
- `xmlRegisters'
- This feature indicates that GDB supports the XML target
- description. If the stub sees `xmlRegisters=' with target
- specific strings separated by a comma, it will report register
- description.
-
- `qRelocInsn'
- This feature indicates whether GDB supports the `qRelocInsn'
- packet (*note Relocate instruction reply packet: Tracepoint
- Packets.).
-
- Stubs should ignore any unknown values for GDBFEATURE. Any GDB
- which sends a `qSupported' packet supports receiving packets of
- unlimited length (earlier versions of GDB may reject overly long
- responses). Additional values for GDBFEATURE may be defined in
- the future to let the stub take advantage of new features in GDB,
- e.g. incompatible improvements in the remote protocol--the
- `multiprocess' feature is an example of such a feature. The
- stub's reply should be independent of the GDBFEATURE entries sent
- by GDB; first GDB describes all the features it supports, and then
- the stub replies with all the features it supports.
-
- Similarly, GDB will silently ignore unrecognized stub feature
- responses, as long as each response uses one of the standard forms.
-
- Some features are flags. A stub which supports a flag feature
- should respond with a `+' form response. Other features require
- values, and the stub should respond with an `=' form response.
-
- Each feature has a default value, which GDB will use if
- `qSupported' is not available or if the feature is not mentioned
- in the `qSupported' response. The default values are fixed; a
- stub is free to omit any feature responses that match the defaults.
-
- Not all features can be probed, but for those which can, the
- probing mechanism is useful: in some cases, a stub's internal
- architecture may not allow the protocol layer to know some
- information about the underlying target in advance. This is
- especially common in stubs which may be configured for multiple
- targets.
+\1f
+File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI
- These are the currently defined stub features and their properties:
-
- Feature Name Value Default Probe Allowed
- Required
- `PacketSize' Yes `-' No
- `qXfer:auxv:read' No `-' Yes
- `qXfer:features:read' No `-' Yes
- `qXfer:libraries:read' No `-' Yes
- `qXfer:memory-map:read' No `-' Yes
- `qXfer:sdata:read' No `-' Yes
- `qXfer:spu:read' No `-' Yes
- `qXfer:spu:write' No `-' Yes
- `qXfer:siginfo:read' No `-' Yes
- `qXfer:siginfo:write' No `-' Yes
- `qXfer:threads:read' No `-' Yes
- `qXfer:traceframe-info:read'No `-' Yes
- `qXfer:uib:read' No `-' Yes
- `qXfer:fdpic:read' No `-' Yes
- `QNonStop' No `-' Yes
- `QPassSignals' No `-' Yes
- `QStartNoAckMode' No `-' Yes
- `multiprocess' No `-' No
- `ConditionalBreakpoints'No `-' No
- `ConditionalTracepoints'No `-' No
- `ReverseContinue' No `-' No
- `ReverseStep' No `-' No
- `TracepointSource' No `-' No
- `QAgent' No `-' No
- `QAllow' No `-' No
- `QDisableRandomization' No `-' No
- `EnableDisableTracepoints'No `-' No
- `tracenz' No `-' No
- `BreakpointCommands' No `-' No
-
- These are the currently defined stub features, in more detail:
-
- `PacketSize=BYTES'
- The remote stub can accept packets up to at least BYTES in
- length. GDB will send packets up to this size for bulk
- transfers, and will never send larger packets. This is a
- limit on the data characters in the packet, including the
- frame and checksum. There is no trailing NUL byte in a
- remote protocol packet; if the stub stores packets in a
- NUL-terminated format, it should allow an extra byte in its
- buffer for the NUL. If this stub feature is not supported,
- GDB guesses based on the size of the `g' packet response.
-
- `qXfer:auxv:read'
- The remote stub understands the `qXfer:auxv:read' packet
- (*note qXfer auxiliary vector read::).
-
- `qXfer:features:read'
- The remote stub understands the `qXfer:features:read' packet
- (*note qXfer target description read::).
-
- `qXfer:libraries:read'
- The remote stub understands the `qXfer:libraries:read' packet
- (*note qXfer library list read::).
-
- `qXfer:libraries-svr4:read'
- The remote stub understands the `qXfer:libraries-svr4:read'
- packet (*note qXfer svr4 library list read::).
-
- `qXfer:memory-map:read'
- The remote stub understands the `qXfer:memory-map:read' packet
- (*note qXfer memory map read::).
-
- `qXfer:sdata:read'
- The remote stub understands the `qXfer:sdata:read' packet
- (*note qXfer sdata read::).
-
- `qXfer:spu:read'
- The remote stub understands the `qXfer:spu:read' packet
- (*note qXfer spu read::).
-
- `qXfer:spu:write'
- The remote stub understands the `qXfer:spu:write' packet
- (*note qXfer spu write::).
-
- `qXfer:siginfo:read'
- The remote stub understands the `qXfer:siginfo:read' packet
- (*note qXfer siginfo read::).
-
- `qXfer:siginfo:write'
- The remote stub understands the `qXfer:siginfo:write' packet
- (*note qXfer siginfo write::).
-
- `qXfer:threads:read'
- The remote stub understands the `qXfer:threads:read' packet
- (*note qXfer threads read::).
-
- `qXfer:traceframe-info:read'
- The remote stub understands the `qXfer:traceframe-info:read'
- packet (*note qXfer traceframe info read::).
-
- `qXfer:uib:read'
- The remote stub understands the `qXfer:uib:read' packet
- (*note qXfer unwind info block::).
-
- `qXfer:fdpic:read'
- The remote stub understands the `qXfer:fdpic:read' packet
- (*note qXfer fdpic loadmap read::).
-
- `QNonStop'
- The remote stub understands the `QNonStop' packet (*note
- QNonStop::).
-
- `QPassSignals'
- The remote stub understands the `QPassSignals' packet (*note
- QPassSignals::).
-
- `QStartNoAckMode'
- The remote stub understands the `QStartNoAckMode' packet and
- prefers to operate in no-acknowledgment mode. *Note Packet
- Acknowledgment::.
-
- `multiprocess'
- The remote stub understands the multiprocess extensions to
- the remote protocol syntax. The multiprocess extensions
- affect the syntax of thread IDs in both packets and replies
- (*note thread-id syntax::), and add process IDs to the `D'
- packet and `W' and `X' replies. Note that reporting this
- feature indicates support for the syntactic extensions only,
- not that the stub necessarily supports debugging of more than
- one process at a time. The stub must not use multiprocess
- extensions in packet replies unless GDB has also indicated it
- supports them in its `qSupported' request.
-
- `qXfer:osdata:read'
- The remote stub understands the `qXfer:osdata:read' packet
- ((*note qXfer osdata read::).
-
- `ConditionalBreakpoints'
- The target accepts and implements evaluation of conditional
- expressions defined for breakpoints. The target will only
- report breakpoint triggers when such conditions are true
- (*note Break Conditions: Conditions.).
-
- `ConditionalTracepoints'
- The remote stub accepts and implements conditional
- expressions defined for tracepoints (*note Tracepoint
- Conditions::).
-
- `ReverseContinue'
- The remote stub accepts and implements the reverse continue
- packet (*note bc::).
-
- `ReverseStep'
- The remote stub accepts and implements the reverse step packet
- (*note bs::).
-
- `TracepointSource'
- The remote stub understands the `QTDPsrc' packet that supplies
- the source form of tracepoint definitions.
-
- `QAgent'
- The remote stub understands the `QAgent' packet.
-
- `QAllow'
- The remote stub understands the `QAllow' packet.
-
- `QDisableRandomization'
- The remote stub understands the `QDisableRandomization'
- packet.
-
- `StaticTracepoint'
- The remote stub supports static tracepoints.
-
- `InstallInTrace'
- The remote stub supports installing tracepoint in tracing.
-
- `EnableDisableTracepoints'
- The remote stub supports the `QTEnable' (*note QTEnable::) and
- `QTDisable' (*note QTDisable::) packets that allow tracepoints
- to be enabled and disabled while a trace experiment is
- running.
-
- `tracenz'
- The remote stub supports the `tracenz' bytecode for
- collecting strings. See *Note Bytecode Descriptions:: for
- details about the bytecode.
-
- `BreakpointCommands'
- The remote stub supports running a breakpoint's command list
- itself, rather than reporting the hit to GDB.
-
-
-`qSymbol::'
- Notify the target that GDB is prepared to serve symbol lookup
- requests. Accept requests from the target for the values of
- symbols.
-
- Reply:
- `OK'
- The target does not need to look up any (more) symbols.
-
- `qSymbol:SYM_NAME'
- The target requests the value of symbol SYM_NAME (hex
- encoded). GDB may provide the value by using the
- `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
-
-`qSymbol:SYM_VALUE:SYM_NAME'
- Set the value of SYM_NAME to SYM_VALUE.
-
- SYM_NAME (hex encoded) is the name of a symbol whose value the
- target has previously requested.
-
- SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
- supply a value for SYM_NAME, then this field will be empty.
-
- Reply:
- `OK'
- The target does not need to look up any (more) symbols.
-
- `qSymbol:SYM_NAME'
- The target requests the value of a new symbol SYM_NAME (hex
- encoded). GDB will continue to supply the values of symbols
- (if available), until the target ceases to request them.
-
-`qTBuffer'
-
-`QTBuffer'
-
-`QTDisconnected'
-`QTDP'
-`QTDPsrc'
-`QTDV'
-`qTfP'
-`qTfV'
-`QTFrame'
-`qTMinFTPILen'
- *Note Tracepoint Packets::.
-
-`qThreadExtraInfo,THREAD-ID'
- Obtain a printable string description of a thread's attributes from
- the target OS. THREAD-ID is a thread ID; see *Note thread-id
- syntax::. This string may contain anything that the target OS
- thinks is interesting for GDB to tell the user about the thread.
- The string is displayed in GDB's `info threads' display. Some
- examples of possible thread extra info strings are `Runnable', or
- `Blocked on Mutex'.
-
- Reply:
- `XX...'
- Where `XX...' is a hex encoding of ASCII data, comprising the
- printable string containing the extra information about the
- thread's attributes.
-
- (Note that the `qThreadExtraInfo' packet's name is separated from
- the command by a `,', not a `:', contrary to the naming
- conventions above. Please don't use this packet as a model for new
- packets.)
-
-`QTNotes'
-
-`qTP'
-
-`QTSave'
-
-`qTsP'
-
-`qTsV'
-`QTStart'
-`QTStop'
-`QTEnable'
-`QTDisable'
-`QTinit'
-`QTro'
-`qTStatus'
-`qTV'
-`qTfSTM'
-`qTsSTM'
-`qTSTMat'
- *Note Tracepoint Packets::.
-
-`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
- Read uninterpreted bytes from the target's special data area
- identified by the keyword OBJECT. Request LENGTH bytes starting
- at OFFSET bytes into the data. The content and encoding of ANNEX
- is specific to OBJECT; it can supply additional details about what
- data to access.
-
- Here are the specific requests of this form defined so far. All
- `qXfer:OBJECT:read:...' requests use the same reply formats,
- listed below.
-
- `qXfer:auxv:read::OFFSET,LENGTH'
- Access the target's "auxiliary vector". *Note auxiliary
- vector: OS Information. Note ANNEX must be empty.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:features:read:ANNEX:OFFSET,LENGTH'
- Access the "target description". *Note Target
- Descriptions::. The annex specifies which XML document to
- access. The main description is always loaded from the
- `target.xml' annex.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
- Access the target's list of loaded libraries. *Note Library
- List Format::. The annex part of the generic `qXfer' packet
- must be empty (*note qXfer read::).
-
- Targets which maintain a list of libraries in the program's
- memory do not need to implement this packet; it is designed
- for platforms where the operating system manages the list of
- loaded libraries.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH'
- Access the target's list of loaded libraries when the target
- is an SVR4 platform. *Note Library List Format for SVR4
- Targets::. The annex part of the generic `qXfer' packet must
- be empty (*note qXfer read::).
-
- This packet is optional for better performance on SVR4
- targets. GDB uses memory read packets to read the SVR4
- library list otherwise.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:memory-map:read::OFFSET,LENGTH'
- Access the target's "memory-map". *Note Memory Map Format::.
- The annex part of the generic `qXfer' packet must be empty
- (*note qXfer read::).
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:sdata:read::OFFSET,LENGTH'
- Read contents of the extra collected static tracepoint marker
- information. The annex part of the generic `qXfer' packet
- must be empty (*note qXfer read::). *Note Tracepoint Action
- Lists: Tracepoint Actions.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:siginfo:read::OFFSET,LENGTH'
- Read contents of the extra signal information on the target
- system. The annex part of the generic `qXfer' packet must be
- empty (*note qXfer read::).
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
- Read contents of an `spufs' file on the target system. The
- annex specifies which file to read; it must be of the form
- `ID/NAME', where ID specifies an SPU context ID in the target
- process, and NAME identifes the `spufs' file in that context
- to be accessed.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:threads:read::OFFSET,LENGTH'
- Access the list of threads on target. *Note Thread List
- Format::. The annex part of the generic `qXfer' packet must
- be empty (*note qXfer read::).
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:traceframe-info:read::OFFSET,LENGTH'
- Return a description of the current traceframe's contents.
- *Note Traceframe Info Format::. The annex part of the generic
- `qXfer' packet must be empty (*note qXfer read::).
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:uib:read:PC:OFFSET,LENGTH'
- Return the unwind information block for PC. This packet is
- used on OpenVMS/ia64 to ask the kernel unwind information.
-
- This packet is not probed by default.
-
- `qXfer:fdpic:read:ANNEX:OFFSET,LENGTH'
- Read contents of `loadmap's on the target system. The annex,
- either `exec' or `interp', specifies which `loadmap',
- executable `loadmap' or interpreter `loadmap' to read.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:osdata:read::OFFSET,LENGTH'
- Access the target's "operating system information". *Note
- Operating System Information::.
-
-
- Reply:
- `m DATA'
- Data DATA (*note Binary Data::) has been read from the
- target. There may be more data at a higher address (although
- it is permitted to return `m' even for the last valid block
- of data, as long as at least one byte of data was read).
- DATA may have fewer bytes than the LENGTH in the request.
-
- `l DATA'
- Data DATA (*note Binary Data::) has been read from the target.
- There is no more data to be read. DATA may have fewer bytes
- than the LENGTH in the request.
-
- `l'
- The OFFSET in the request is at the end of the data. There
- is no more data to be read.
-
- `E00'
- The request was malformed, or ANNEX was invalid.
-
- `E NN'
- The offset was invalid, or there was an error encountered
- reading the data. NN is a hex-encoded `errno' value.
-
- `'
- An empty reply indicates the OBJECT string was not recognized
- by the stub, or that the object does not support reading.
-
-`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
- Write uninterpreted bytes into the target's special data area
- identified by the keyword OBJECT, starting at OFFSET bytes into
- the data. DATA... is the binary-encoded data (*note Binary
- Data::) to be written. The content and encoding of ANNEX is
- specific to OBJECT; it can supply additional details about what
- data to access.
-
- Here are the specific requests of this form defined so far. All
- `qXfer:OBJECT:write:...' requests use the same reply formats,
- listed below.
-
- `qXfer:siginfo:write::OFFSET:DATA...'
- Write DATA to the extra signal information on the target
- system. The annex part of the generic `qXfer' packet must be
- empty (*note qXfer write::).
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- `qXfer:spu:write:ANNEX:OFFSET:DATA...'
- Write DATA to an `spufs' file on the target system. The
- annex specifies which file to write; it must be of the form
- `ID/NAME', where ID specifies an SPU context ID in the target
- process, and NAME identifes the `spufs' file in that context
- to be accessed.
-
- This packet is not probed by default; the remote stub must
- request it, by supplying an appropriate `qSupported' response
- (*note qSupported::).
-
- Reply:
- `NN'
- NN (hex encoded) is the number of bytes written. This may be
- fewer bytes than supplied in the request.
-
- `E00'
- The request was malformed, or ANNEX was invalid.
-
- `E NN'
- The offset was invalid, or there was an error encountered
- writing the data. NN is a hex-encoded `errno' value.
-
- `'
- An empty reply indicates the OBJECT string was not recognized
- by the stub, or that the object does not support writing.
-
-`qXfer:OBJECT:OPERATION:...'
- Requests of this form may be added in the future. When a stub does
- not recognize the OBJECT keyword, or its support for OBJECT does
- not recognize the OPERATION keyword, the stub must respond with an
- empty packet.
-
-`qAttached:PID'
- Return an indication of whether the remote server attached to an
- existing process or created a new process. When the multiprocess
- protocol extensions are supported (*note multiprocess
- extensions::), PID is an integer in hexadecimal format identifying
- the target process. Otherwise, GDB will omit the PID field and
- the query packet will be simplified as `qAttached'.
-
- This query is used, for example, to know whether the remote process
- should be detached or killed when a GDB session is ended with the
- `quit' command.
-
- Reply:
- `1'
- The remote server attached to an existing process.
-
- `0'
- The remote server created a new process.
-
- `E NN'
- A badly formed request or an error was encountered.
+27.10 GDB/MI Program Context
+============================
+The '-exec-arguments' Command
+-----------------------------
- ---------- Footnotes ----------
+Synopsis
+........
- (1) The `qP' and `qL' packets predate these conventions, and have
-arguments without any terminator for the packet name; we suspect they
-are in widespread use in places that are difficult to upgrade. The
-`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
-are known to not check for the end of the packet.
+ -exec-arguments ARGS
-\1f
-File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
+ Set the inferior program arguments, to be used in the next
+'-exec-run'.
-E.5 Architecture-Specific Protocol Details
-==========================================
+GDB Command
+...........
-This section describes how the remote protocol is applied to specific
-target architectures. Also see *Note Standard Target Features::, for
-details of XML target descriptions for each architecture.
+The corresponding GDB command is 'set args'.
-* Menu:
+Example
+.......
-* ARM-Specific Protocol Details::
-* MIPS-Specific Protocol Details::
+ (gdb)
+ -exec-arguments -v word
+ ^done
+ (gdb)
-\1f
-File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details
+The '-environment-cd' Command
+-----------------------------
-E.5.1 ARM-specific Protocol Details
------------------------------------
+Synopsis
+........
-* Menu:
+ -environment-cd PATHDIR
-* ARM Breakpoint Kinds::
+ Set GDB's working directory.
-\1f
-File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details
+GDB Command
+...........
+
+The corresponding GDB command is 'cd'.
-E.5.1.1 ARM Breakpoint Kinds
-............................
+Example
+.......
-These breakpoint kinds are defined for the `Z0' and `Z1' packets.
+ (gdb)
+ -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+ ^done
+ (gdb)
-2
- 16-bit Thumb mode breakpoint.
+The '-environment-directory' Command
+------------------------------------
-3
- 32-bit Thumb mode (Thumb-2) breakpoint.
+Synopsis
+........
+
+ -environment-directory [ -r ] [ PATHDIR ]+
+
+ Add directories PATHDIR to beginning of search path for source files.
+If the '-r' option is used, the search path is reset to the default
+search path. If directories PATHDIR are supplied in addition to the
+'-r' option, the search path is first reset and then addition occurs as
+normal. Multiple directories may be specified, separated by blanks.
+Specifying multiple directories in a single command results in the
+directories added to the beginning of the search path in the same order
+they were presented in the command. If blanks are needed as part of a
+directory name, double-quotes should be used around the name. In the
+command output, the path will show up separated by the system
+directory-separator character. The directory-separator character must
+not be used in any directory name. If no directories are specified, the
+current search path is displayed.
+
+GDB Command
+...........
-4
- 32-bit ARM mode breakpoint.
+The corresponding GDB command is 'dir'.
+
+Example
+.......
+
+ (gdb)
+ -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+ ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+ (gdb)
+ -environment-directory ""
+ ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+ (gdb)
+ -environment-directory -r /home/jjohnstn/src/gdb /usr/src
+ ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
+ (gdb)
+ -environment-directory -r
+ ^done,source-path="$cdir:$cwd"
+ (gdb)
+
+The '-environment-path' Command
+-------------------------------
+
+Synopsis
+........
+
+ -environment-path [ -r ] [ PATHDIR ]+
+
+ Add directories PATHDIR to beginning of search path for object files.
+If the '-r' option is used, the search path is reset to the original
+search path that existed at gdb start-up. If directories PATHDIR are
+supplied in addition to the '-r' option, the search path is first reset
+and then addition occurs as normal. Multiple directories may be
+specified, separated by blanks. Specifying multiple directories in a
+single command results in the directories added to the beginning of the
+search path in the same order they were presented in the command. If
+blanks are needed as part of a directory name, double-quotes should be
+used around the name. In the command output, the path will show up
+separated by the system directory-separator character. The
+directory-separator character must not be used in any directory name.
+If no directories are specified, the current path is displayed.
+
+GDB Command
+...........
+The corresponding GDB command is 'path'.
-\1f
-File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details
+Example
+.......
-E.5.2 MIPS-specific Protocol Details
-------------------------------------
+ (gdb)
+ -environment-path
+ ^done,path="/usr/bin"
+ (gdb)
+ -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
+ ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
+ (gdb)
+ -environment-path -r /usr/local/bin
+ ^done,path="/usr/local/bin:/usr/bin"
+ (gdb)
-* Menu:
+The '-environment-pwd' Command
+------------------------------
-* MIPS Register packet Format::
-* MIPS Breakpoint Kinds::
+Synopsis
+........
-\1f
-File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details
+ -environment-pwd
-E.5.2.1 MIPS Register Packet Format
-...................................
+ Show the current working directory.
-The following `g'/`G' packets have previously been defined. In the
-below, some thirty-two bit registers are transferred as sixty-four
-bits. Those registers should be zero/sign extended (which?) to fill
-the space allocated. Register bytes are transferred in target byte
-order. The two nibbles within a register byte are transferred
-most-significant - least-significant.
+GDB Command
+...........
-MIPS32
- All registers are transferred as thirty-two bit quantities in the
- order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
- floating-point registers; fsr; fir; fp.
+The corresponding GDB command is 'pwd'.
-MIPS64
- All registers are transferred as sixty-four bit quantities
- (including thirty-two bit registers such as `sr'). The ordering
- is the same as `MIPS32'.
+Example
+.......
+ (gdb)
+ -environment-pwd
+ ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
+ (gdb)
\1f
-File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details
+File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI
-E.5.2.2 MIPS Breakpoint Kinds
-.............................
+27.11 GDB/MI Thread Commands
+============================
-These breakpoint kinds are defined for the `Z0' and `Z1' packets.
+The '-thread-info' Command
+--------------------------
-2
- 16-bit MIPS16 mode breakpoint.
+Synopsis
+........
-3
- 16-bit microMIPS mode breakpoint.
+ -thread-info [ THREAD-ID ]
-4
- 32-bit standard MIPS mode breakpoint.
+ Reports information about either a specific thread, if the THREAD-ID
+parameter is present, or about all threads. When printing information
+about all threads, also reports the current thread.
-5
- 32-bit microMIPS mode breakpoint.
+GDB Command
+...........
+The 'info thread' command prints the same information about all threads.
-\1f
-File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
+Result
+......
-E.6 Tracepoint Packets
-======================
+The result is a list of threads. The following attributes are defined
+for a given thread:
+
+'current'
+ This field exists only for the current thread. It has the value
+ '*'.
+
+'id'
+ The identifier that GDB uses to refer to the thread.
+
+'target-id'
+ The identifier that the target uses to refer to the thread.
+
+'details'
+ Extra information about the thread, in a target-specific format.
+ This field is optional.
+
+'name'
+ The name of the thread. If the user specified a name using the
+ 'thread name' command, then this name is given. Otherwise, if GDB
+ can extract the thread name from the target, then that name is
+ given. If GDB cannot find the thread name, then this field is
+ omitted.
+
+'frame'
+ The stack frame currently executing in the thread.
+
+'state'
+ The thread's state. The 'state' field may have the following
+ values:
+
+ 'stopped'
+ The thread is stopped. Frame information is available for
+ stopped threads.
+
+ 'running'
+ The thread is running. There's no frame information for
+ running threads.
+
+'core'
+ If GDB can find the CPU core on which this thread is running, then
+ this field is the core identifier. This field is optional.
+
+Example
+.......
+
+ -thread-info
+ ^done,threads=[
+ {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",
+ args=[]},state="running"},
+ {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+ frame={level="0",addr="0x0804891f",func="foo",
+ args=[{name="i",value="10"}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"},
+ state="running"}],
+ current-thread-id="1"
+ (gdb)
+
+The '-thread-list-ids' Command
+------------------------------
-Here we describe the packets GDB uses to implement tracepoints (*note
-Tracepoints::).
-
-`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
- Create a new tracepoint, number N, at ADDR. If ENA is `E', then
- the tracepoint is enabled; if it is `D', then the tracepoint is
- disabled. STEP is the tracepoint's step count, and PASS is its
- pass count. If an `F' is present, then the tracepoint is to be a
- fast tracepoint, and the FLEN is the number of bytes that the
- target should copy elsewhere to make room for the tracepoint. If
- an `X' is present, it introduces a tracepoint condition, which
- consists of a hexadecimal length, followed by a comma and
- hex-encoded bytes, in a manner similar to action encodings as
- described below. If the trailing `-' is present, further `QTDP'
- packets will follow to specify this tracepoint's actions.
+Synopsis
+........
- Replies:
- `OK'
- The packet was understood and carried out.
-
- `qRelocInsn'
- *Note Relocate instruction reply packet: Tracepoint Packets.
-
- `'
- The packet was not recognized.
-
-`QTDP:-N:ADDR:[S]ACTION...[-]'
- Define actions to be taken when a tracepoint is hit. N and ADDR
- must be the same as in the initial `QTDP' packet for this
- tracepoint. This packet may only be sent immediately after
- another `QTDP' packet that ended with a `-'. If the trailing `-'
- is present, further `QTDP' packets will follow, specifying more
- actions for this tracepoint.
-
- In the series of action packets for a given tracepoint, at most one
- can have an `S' before its first ACTION. If such a packet is
- sent, it and the following packets define "while-stepping"
- actions. Any prior packets define ordinary actions -- that is,
- those taken when the tracepoint is first hit. If no action packet
- has an `S', then all the packets in the series specify ordinary
- tracepoint actions.
-
- The `ACTION...' portion of the packet is a series of actions,
- concatenated without separators. Each action has one of the
- following forms:
-
- `R MASK'
- Collect the registers whose bits are set in MASK. MASK is a
- hexadecimal number whose I'th bit is set if register number I
- should be collected. (The least significant bit is numbered
- zero.) Note that MASK may be any number of digits long; it
- may not fit in a 32-bit word.
-
- `M BASEREG,OFFSET,LEN'
- Collect LEN bytes of memory starting at the address in
- register number BASEREG, plus OFFSET. If BASEREG is `-1',
- then the range has a fixed address: OFFSET is the address of
- the lowest byte to collect. The BASEREG, OFFSET, and LEN
- parameters are all unsigned hexadecimal values (the `-1'
- value for BASEREG is a special case).
-
- `X LEN,EXPR'
- Evaluate EXPR, whose length is LEN, and collect memory as it
- directs. EXPR is an agent expression, as described in *Note
- Agent Expressions::. Each byte of the expression is encoded
- as a two-digit hex number in the packet; LEN is the number of
- bytes in the expression (and thus one-half the number of hex
- digits in the packet).
-
-
- Any number of actions may be packed together in a single `QTDP'
- packet, as long as the packet does not exceed the maximum packet
- length (400 bytes, for many stubs). There may be only one `R'
- action per tracepoint, and it must precede any `M' or `X' actions.
- Any registers referred to by `M' and `X' actions must be
- collected by a preceding `R' action. (The "while-stepping"
- actions are treated as if they were attached to a separate
- tracepoint, as far as these restrictions are concerned.)
+ -thread-list-ids
- Replies:
- `OK'
- The packet was understood and carried out.
-
- `qRelocInsn'
- *Note Relocate instruction reply packet: Tracepoint Packets.
-
- `'
- The packet was not recognized.
-
-`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
- Specify a source string of tracepoint N at address ADDR. This is
- useful to get accurate reproduction of the tracepoints originally
- downloaded at the beginning of the trace run. TYPE is the name of
- the tracepoint part, such as `cond' for the tracepoint's
- conditional expression (see below for a list of types), while
- BYTES is the string, encoded in hexadecimal.
-
- START is the offset of the BYTES within the overall source string,
- while SLEN is the total length of the source string. This is
- intended for handling source strings that are longer than will fit
- in a single packet.
-
- The available string types are `at' for the location, `cond' for
- the conditional, and `cmd' for an action command. GDB sends a
- separate packet for each command in the action list, in the same
- order in which the commands are stored in the list.
-
- The target does not need to do anything with source strings except
- report them back as part of the replies to the `qTfP'/`qTsP' query
- packets.
-
- Although this packet is optional, and GDB will only send it if the
- target replies with `TracepointSource' *Note General Query
- Packets::, it makes both disconnected tracing and trace files much
- easier to use. Otherwise the user must be careful that the
- tracepoints in effect while looking at trace frames are identical
- to the ones in effect during the trace run; even a small
- discrepancy could cause `tdump' not to work, or a particular trace
- frame not be found.
-
-`QTDV:N:VALUE'
- Create a new trace state variable, number N, with an initial value
- of VALUE, which is a 64-bit signed integer. Both N and VALUE are
- encoded as hexadecimal values. GDB has the option of not using
- this packet for initial values of zero; the target should simply
- create the trace state variables as they are mentioned in
- expressions.
-
-`QTFrame:N'
- Select the N'th tracepoint frame from the buffer, and use the
- register and memory contents recorded there to answer subsequent
- request packets from GDB.
-
- A successful reply from the stub indicates that the stub has found
- the requested frame. The response is a series of parts,
- concatenated without separators, describing the frame we selected.
- Each part has one of the following forms:
-
- `F F'
- The selected frame is number N in the trace frame buffer; F
- is a hexadecimal number. If F is `-1', then there was no
- frame matching the criteria in the request packet.
-
- `T T'
- The selected trace frame records a hit of tracepoint number T;
- T is a hexadecimal number.
-
-
-`QTFrame:pc:ADDR'
- Like `QTFrame:N', but select the first tracepoint frame after the
- currently selected frame whose PC is ADDR; ADDR is a hexadecimal
- number.
-
-`QTFrame:tdp:T'
- Like `QTFrame:N', but select the first tracepoint frame after the
- currently selected frame that is a hit of tracepoint T; T is a
- hexadecimal number.
-
-`QTFrame:range:START:END'
- Like `QTFrame:N', but select the first tracepoint frame after the
- currently selected frame whose PC is between START (inclusive) and
- END (inclusive); START and END are hexadecimal numbers.
-
-`QTFrame:outside:START:END'
- Like `QTFrame:range:START:END', but select the first frame
- _outside_ the given range of addresses (exclusive).
-
-`qTMinFTPILen'
- This packet requests the minimum length of instruction at which a
- fast tracepoint (*note Set Tracepoints::) may be placed. For
- instance, on the 32-bit x86 architecture, it is possible to use a
- 4-byte jump, but it depends on the target system being able to
- create trampolines in the first 64K of memory, which might or
- might not be possible for that system. So the reply to this
- packet will be 4 if it is able to arrange for that.
+ Produces a list of the currently known GDB thread ids. At the end of
+the list it also prints the total number of such threads.
- Replies:
+ This command is retained for historical reasons, the '-thread-info'
+command should be used instead.
+
+GDB Command
+...........
- `0'
- The minimum instruction length is currently unknown.
+Part of 'info threads' supplies the same information.
- `LENGTH'
- The minimum instruction length is LENGTH, where LENGTH is
- greater or equal to 1. LENGTH is a hexadecimal number. A
- reply of 1 means that a fast tracepoint may be placed on any
- instruction regardless of size.
+Example
+.......
- `E'
- An error has occurred.
+ (gdb)
+ -thread-list-ids
+ ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
+ current-thread-id="1",number-of-threads="3"
+ (gdb)
- `'
- An empty reply indicates that the request is not supported by
- the stub.
+The '-thread-select' Command
+----------------------------
-`QTStart'
- Begin the tracepoint experiment. Begin collecting data from
- tracepoint hits in the trace frame buffer. This packet supports
- the `qRelocInsn' reply (*note Relocate instruction reply packet:
- Tracepoint Packets.).
+Synopsis
+........
-`QTStop'
- End the tracepoint experiment. Stop collecting trace frames.
+ -thread-select THREADNUM
-`QTEnable:N:ADDR'
- Enable tracepoint N at address ADDR in a started tracepoint
- experiment. If the tracepoint was previously disabled, then
- collection of data from it will resume.
+ Make THREADNUM the current thread. It prints the number of the new
+current thread, and the topmost frame for that thread.
-`QTDisable:N:ADDR'
- Disable tracepoint N at address ADDR in a started tracepoint
- experiment. No more data will be collected from the tracepoint
- unless `QTEnable:N:ADDR' is subsequently issued.
+ This command is deprecated in favor of explicitly using the
+'--thread' option to each command.
-`QTinit'
- Clear the table of tracepoints, and empty the trace frame buffer.
+GDB Command
+...........
-`QTro:START1,END1:START2,END2:...'
- Establish the given ranges of memory as "transparent". The stub
- will answer requests for these ranges from memory's current
- contents, if they were not collected as part of the tracepoint hit.
+The corresponding GDB command is 'thread'.
+
+Example
+.......
+
+ (gdb)
+ -exec-next
+ ^running
+ (gdb)
+ *stopped,reason="end-stepping-range",thread-id="2",line="187",
+ file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
+ (gdb)
+ -thread-list-ids
+ ^done,
+ thread-ids={thread-id="3",thread-id="2",thread-id="1"},
+ number-of-threads="3"
+ (gdb)
+ -thread-select 3
+ ^done,new-thread-id="3",
+ frame={level="0",func="vprintf",
+ args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
+ {name="arg",value="0x2"}],file="vprintf.c",line="31"}
+ (gdb)
- GDB uses this to mark read-only regions of memory, like those
- containing program code. Since these areas never change, they
- should still have the same contents they did when the tracepoint
- was hit, so there's no reason for the stub to refuse to provide
- their contents.
+\1f
+File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI
-`QTDisconnected:VALUE'
- Set the choice to what to do with the tracing run when GDB
- disconnects from the target. A VALUE of 1 directs the target to
- continue the tracing run, while 0 tells the target to stop tracing
- if GDB is no longer in the picture.
+27.12 GDB/MI Ada Tasking Commands
+=================================
-`qTStatus'
- Ask the stub if there is a trace experiment running right now.
+The '-ada-task-info' Command
+----------------------------
- The reply has the form:
+Synopsis
+........
- `TRUNNING[;FIELD]...'
- RUNNING is a single digit `1' if the trace is presently
- running, or `0' if not. It is followed by semicolon-separated
- optional fields that an agent may use to report additional
- status.
+ -ada-task-info [ TASK-ID ]
+ Reports information about either a specific Ada task, if the TASK-ID
+parameter is present, or about all Ada tasks.
- If the trace is not running, the agent may report any of several
- explanations as one of the optional fields:
+GDB Command
+...........
- `tnotrun:0'
- No trace has been run yet.
+The 'info tasks' command prints the same information about all Ada tasks
+(*note Ada Tasks::).
- `tstop[:TEXT]:0'
- The trace was stopped by a user-originated stop command. The
- optional TEXT field is a user-supplied string supplied as
- part of the stop command (for instance, an explanation of why
- the trace was stopped manually). It is hex-encoded.
+Result
+......
- `tfull:0'
- The trace stopped because the trace buffer filled up.
+The result is a table of Ada tasks. The following columns are defined
+for each Ada task:
- `tdisconnected:0'
- The trace stopped because GDB disconnected from the target.
+'current'
+ This field exists only for the current thread. It has the value
+ '*'.
- `tpasscount:TPNUM'
- The trace stopped because tracepoint TPNUM exceeded its pass
- count.
+'id'
+ The identifier that GDB uses to refer to the Ada task.
- `terror:TEXT:TPNUM'
- The trace stopped because tracepoint TPNUM had an error. The
- string TEXT is available to describe the nature of the error
- (for instance, a divide by zero in the condition expression).
- TEXT is hex encoded.
+'task-id'
+ The identifier that the target uses to refer to the Ada task.
- `tunknown:0'
- The trace stopped for some other reason.
+'thread-id'
+ The identifier of the thread corresponding to the Ada task.
+ This field should always exist, as Ada tasks are always implemented
+ on top of a thread. But if GDB cannot find this corresponding
+ thread for any reason, the field is omitted.
- Additional optional fields supply statistical and other
- information. Although not required, they are extremely useful for
- users monitoring the progress of a trace run. If a trace has
- stopped, and these numbers are reported, they must reflect the
- state of the just-stopped trace.
+'parent-id'
+ This field exists only when the task was created by another task.
+ In this case, it provides the ID of the parent task.
- `tframes:N'
- The number of trace frames in the buffer.
+'priority'
+ The base priority of the task.
- `tcreated:N'
- The total number of trace frames created during the run. This
- may be larger than the trace frame count, if the buffer is
- circular.
+'state'
+ The current state of the task. For a detailed description of the
+ possible states, see *note Ada Tasks::.
- `tsize:N'
- The total size of the trace buffer, in bytes.
+'name'
+ The name of the task.
- `tfree:N'
- The number of bytes still unused in the buffer.
+Example
+.......
- `circular:N'
- The value of the circular trace buffer flag. `1' means that
- the trace buffer is circular and old trace frames will be
- discarded if necessary to make room, `0' means that the trace
- buffer is linear and may fill up.
+ -ada-task-info
+ ^done,tasks={nr_rows="3",nr_cols="8",
+ hdr=[{width="1",alignment="-1",col_name="current",colhdr=""},
+ {width="3",alignment="1",col_name="id",colhdr="ID"},
+ {width="9",alignment="1",col_name="task-id",colhdr="TID"},
+ {width="4",alignment="1",col_name="thread-id",colhdr=""},
+ {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"},
+ {width="3",alignment="1",col_name="priority",colhdr="Pri"},
+ {width="22",alignment="-1",col_name="state",colhdr="State"},
+ {width="1",alignment="2",col_name="name",colhdr="Name"}],
+ body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48",
+ state="Child Termination Wait",name="main_task"}]}
+ (gdb)
- `disconn:N'
- The value of the disconnected tracing flag. `1' means that
- tracing will continue after GDB disconnects, `0' means that
- the trace run will stop.
+\1f
+File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI
+
+27.13 GDB/MI Program Execution
+==============================
+
+These are the asynchronous commands which generate the out-of-band
+record '*stopped'. Currently GDB only really executes asynchronously
+with remote targets and this interaction is mimicked in other cases.
+
+The '-exec-continue' Command
+----------------------------
+
+Synopsis
+........
+
+ -exec-continue [--reverse] [--all|--thread-group N]
+
+ Resumes the execution of the inferior program, which will continue to
+execute until it reaches a debugger stop event. If the '--reverse'
+option is specified, execution resumes in reverse until it reaches a
+stop event. Stop events may include
+ * breakpoints or watchpoints
+ * signals or exceptions
+ * the end of the process (or its beginning under '--reverse')
+ * the end or beginning of a replay log if one is being used.
+ In all-stop mode (*note All-Stop Mode::), may resume only one thread,
+or all threads, depending on the value of the 'scheduler-locking'
+variable. If '--all' is specified, all threads (in all inferiors) will
+be resumed. The '--all' option is ignored in all-stop mode. If the
+'--thread-group' options is specified, then all threads in that thread
+group are resumed.
+
+GDB Command
+...........
+The corresponding GDB corresponding is 'continue'.
-`qTP:TP:ADDR'
- Ask the stub for the current state of tracepoint number TP at
- address ADDR.
+Example
+.......
- Replies:
- `VHITS:USAGE'
- The tracepoint has been hit HITS times so far during the trace
- run, and accounts for USAGE in the trace buffer. Note that
- `while-stepping' steps are not counted as separate hits, but
- the steps' space consumption is added into the usage number.
+ -exec-continue
+ ^running
+ (gdb)
+ @Hello world
+ *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={
+ func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
+ line="13"}
+ (gdb)
+The '-exec-finish' Command
+--------------------------
-`qTV:VAR'
- Ask the stub for the value of the trace state variable number VAR.
+Synopsis
+........
- Replies:
- `VVALUE'
- The value of the variable is VALUE. This will be the current
- value of the variable if the user is examining a running
- target, or a saved value if the variable was collected in the
- trace frame that the user is looking at. Note that multiple
- requests may result in different reply values, such as when
- requesting values while the program is running.
-
- `U'
- The value of the variable is unknown. This would occur, for
- example, if the user is examining a trace frame in which the
- requested variable was not collected.
-
-`qTfP'
-`qTsP'
- These packets request data about tracepoints that are being used by
- the target. GDB sends `qTfP' to get the first piece of data, and
- multiple `qTsP' to get additional pieces. Replies to these
- packets generally take the form of the `QTDP' packets that define
- tracepoints. (FIXME add detailed syntax)
-
-`qTfV'
-`qTsV'
- These packets request data about trace state variables that are on
- the target. GDB sends `qTfV' to get the first vari of data, and
- multiple `qTsV' to get additional variables. Replies to these
- packets follow the syntax of the `QTDV' packets that define trace
- state variables.
-
-`qTfSTM'
-`qTsSTM'
- These packets request data about static tracepoint markers that
- exist in the target program. GDB sends `qTfSTM' to get the first
- piece of data, and multiple `qTsSTM' to get additional pieces.
- Replies to these packets take the following form:
-
- Reply:
- `m ADDRESS:ID:EXTRA'
- A single marker
-
- `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
- a comma-separated list of markers
-
- `l'
- (lower case letter `L') denotes end of list.
-
- `E NN'
- An error occurred. NN are hex digits.
-
- `'
- An empty reply indicates that the request is not supported by
- the stub.
-
- ADDRESS is encoded in hex. ID and EXTRA are strings encoded in
- hex.
-
- In response to each query, the target will reply with a list of
- one or more markers, separated by commas. GDB will respond to each
- reply with a request for more markers (using the `qs' form of the
- query), until the target responds with `l' (lower-case ell, for
- "last").
-
-`qTSTMat:ADDRESS'
- This packets requests data about static tracepoint markers in the
- target program at ADDRESS. Replies to this packet follow the
- syntax of the `qTfSTM' and `qTsSTM' packets that list static
- tracepoint markers.
-
-`QTSave:FILENAME'
- This packet directs the target to save trace data to the file name
- FILENAME in the target's filesystem. FILENAME is encoded as a hex
- string; the interpretation of the file name (relative vs absolute,
- wild cards, etc) is up to the target.
-
-`qTBuffer:OFFSET,LEN'
- Return up to LEN bytes of the current contents of trace buffer,
- starting at OFFSET. The trace buffer is treated as if it were a
- contiguous collection of traceframes, as per the trace file format.
- The reply consists as many hex-encoded bytes as the target can
- deliver in a packet; it is not an error to return fewer than were
- asked for. A reply consisting of just `l' indicates that no bytes
- are available.
-
-`QTBuffer:circular:VALUE'
- This packet directs the target to use a circular trace buffer if
- VALUE is 1, or a linear buffer if the value is 0.
-
-`QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'
- This packet adds optional textual notes to the trace run.
- Allowable types include `user', `notes', and `tstop', the TEXT
- fields are arbitrary strings, hex-encoded.
-
-
-E.6.1 Relocate instruction reply packet
----------------------------------------
+ -exec-finish [--reverse]
-When installing fast tracepoints in memory, the target may need to
-relocate the instruction currently at the tracepoint address to a
-different address in memory. For most instructions, a simple copy is
-enough, but, for example, call instructions that implicitly push the
-return address on the stack, and relative branches or other PC-relative
-instructions require offset adjustment, so that the effect of executing
-the instruction at a different address is the same as if it had
-executed in the original location.
-
- In response to several of the tracepoint packets, the target may also
-respond with a number of intermediate `qRelocInsn' request packets
-before the final result packet, to have GDB handle this relocation
-operation. If a packet supports this mechanism, its documentation will
-explicitly say so. See for example the above descriptions for the
-`QTStart' and `QTDP' packets. The format of the request is:
-
-`qRelocInsn:FROM;TO'
- This requests GDB to copy instruction at address FROM to address
- TO, possibly adjusted so that executing the instruction at TO has
- the same effect as executing it at FROM. GDB writes the adjusted
- instruction to target memory starting at TO.
-
- Replies:
-`qRelocInsn:ADJUSTED_SIZE'
- Informs the stub the relocation is complete. ADJUSTED_SIZE is the
- length in bytes of resulting relocated instruction sequence.
-
-`E NN'
- A badly formed request was detected, or an error was encountered
- while relocating the instruction.
+ Resumes the execution of the inferior program until the current
+function is exited. Displays the results returned by the function. If
+the '--reverse' option is specified, resumes the reverse execution of
+the inferior program until the point where current function was called.
-\1f
-File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
-
-E.7 Host I/O Packets
-====================
-
-The "Host I/O" packets allow GDB to perform I/O operations on the far
-side of a remote link. For example, Host I/O is used to upload and
-download files to a remote target with its own filesystem. Host I/O
-uses the same constant values and data structure layout as the
-target-initiated File-I/O protocol. However, the Host I/O packets are
-structured differently. The target-initiated protocol relies on target
-memory to store parameters and buffers. Host I/O requests are
-initiated by GDB, and the target's memory is not involved. *Note
-File-I/O Remote Protocol Extension::, for more details on the
-target-initiated protocol.
-
- The Host I/O request packets all encode a single operation along with
-its arguments. They have this format:
-
-`vFile:OPERATION: PARAMETER...'
- OPERATION is the name of the particular request; the target should
- compare the entire packet name up to the second colon when checking
- for a supported operation. The format of PARAMETER depends on the
- operation. Numbers are always passed in hexadecimal. Negative
- numbers have an explicit minus sign (i.e. two's complement is not
- used). Strings (e.g. filenames) are encoded as a series of
- hexadecimal bytes. The last argument to a system call may be a
- buffer of escaped binary data (*note Binary Data::).
-
-
- The valid responses to Host I/O packets are:
-
-`F RESULT [, ERRNO] [; ATTACHMENT]'
- RESULT is the integer value returned by this operation, usually
- non-negative for success and -1 for errors. If an error has
- occured, ERRNO will be included in the result. ERRNO will have a
- value defined by the File-I/O protocol (*note Errno Values::). For
- operations which return data, ATTACHMENT supplies the data as a
- binary buffer. Binary buffers in response packets are escaped in
- the normal way (*note Binary Data::). See the individual packet
- documentation for the interpretation of RESULT and ATTACHMENT.
-
-`'
- An empty response indicates that this operation is not recognized.
-
-
- These are the supported Host I/O operations:
-
-`vFile:open: PATHNAME, FLAGS, MODE'
- Open a file at PATHNAME and return a file descriptor for it, or
- return -1 if an error occurs. PATHNAME is a string, FLAGS is an
- integer indicating a mask of open flags (*note Open Flags::), and
- MODE is an integer indicating a mask of mode bits to use if the
- file is created (*note mode_t Values::). *Note open::, for
- details of the open flags and mode values.
-
-`vFile:close: FD'
- Close the open file corresponding to FD and return 0, or -1 if an
- error occurs.
-
-`vFile:pread: FD, COUNT, OFFSET'
- Read data from the open file corresponding to FD. Up to COUNT
- bytes will be read from the file, starting at OFFSET relative to
- the start of the file. The target may read fewer bytes; common
- reasons include packet size limits and an end-of-file condition.
- The number of bytes read is returned. Zero should only be
- returned for a successful read at the end of the file, or if COUNT
- was zero.
-
- The data read should be returned as a binary attachment on success.
- If zero bytes were read, the response should include an empty
- binary attachment (i.e. a trailing semicolon). The return value
- is the number of target bytes read; the binary attachment may be
- longer if some characters were escaped.
-
-`vFile:pwrite: FD, OFFSET, DATA'
- Write DATA (a binary buffer) to the open file corresponding to FD.
- Start the write at OFFSET from the start of the file. Unlike
- many `write' system calls, there is no separate COUNT argument;
- the length of DATA in the packet is used. `vFile:write' returns
- the number of bytes written, which may be shorter than the length
- of DATA, or -1 if an error occurred.
-
-`vFile:unlink: PATHNAME'
- Delete the file at PATHNAME on the target. Return 0, or -1 if an
- error occurs. PATHNAME is a string.
-
-`vFile:readlink: FILENAME'
- Read value of symbolic link FILENAME on the target. Return the
- number of bytes read, or -1 if an error occurs.
-
- The data read should be returned as a binary attachment on success.
- If zero bytes were read, the response should include an empty
- binary attachment (i.e. a trailing semicolon). The return value
- is the number of target bytes read; the binary attachment may be
- longer if some characters were escaped.
+GDB Command
+...........
+The corresponding GDB command is 'finish'.
-\1f
-File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
-
-E.8 Interrupts
-==============
-
-When a program on the remote target is running, GDB may attempt to
-interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by
-`g', control of which is specified via GDB's `interrupt-sequence'.
-
- The precise meaning of `BREAK' is defined by the transport mechanism
-and may, in fact, be undefined. GDB does not currently define a
-`BREAK' mechanism for any of the network interfaces except for TCP, in
-which case GDB sends the `telnet' BREAK sequence.
-
- `Ctrl-C', on the other hand, is defined and implemented for all
-transport mechanisms. It is represented by sending the single byte
-`0x03' without any of the usual packet overhead described in the
-Overview section (*note Overview::). When a `0x03' byte is transmitted
-as part of a packet, it is considered to be packet data and does _not_
-represent an interrupt. E.g., an `X' packet (*note X packet::), used
-for binary downloads, may include an unescaped `0x03' as part of its
-packet.
-
- `BREAK' followed by `g' is also known as Magic SysRq g. When Linux
-kernel receives this sequence from serial port, it stops execution and
-connects to gdb.
-
- Stubs are not required to recognize these interrupt mechanisms and
-the precise meaning associated with receipt of the interrupt is
-implementation defined. If the target supports debugging of multiple
-threads and/or processes, it should attempt to interrupt all
-currently-executing threads and processes. If the stub is successful
-at interrupting the running program, it should send one of the stop
-reply packets (*note Stop Reply Packets::) to GDB as a result of
-successfully stopping the program in all-stop mode, and a stop reply
-for each stopped thread in non-stop mode. Interrupts received while the
-program is stopped are discarded.
+Example
+.......
-\1f
-File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
+Function returning 'void'.
-E.9 Notification Packets
-========================
+ -exec-finish
+ ^running
+ (gdb)
+ @hello from foo
+ *stopped,reason="function-finished",frame={func="main",args=[],
+ file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
+ (gdb)
-The GDB remote serial protocol includes "notifications", packets that
-require no acknowledgment. Both the GDB and the stub may send
-notifications (although the only notifications defined at present are
-sent by the stub). Notifications carry information without incurring
-the round-trip latency of an acknowledgment, and so are useful for
-low-impact communications where occasional packet loss is not a problem.
-
- A notification packet has the form `% DATA # CHECKSUM', where DATA
-is the content of the notification, and CHECKSUM is a checksum of DATA,
-computed and formatted as for ordinary GDB packets. A notification's
-DATA never contains `$', `%' or `#' characters. Upon receiving a
-notification, the recipient sends no `+' or `-' to acknowledge the
-notification's receipt or to report its corruption.
-
- Every notification's DATA begins with a name, which contains no
-colon characters, followed by a colon character.
-
- Recipients should silently ignore corrupted notifications and
-notifications they do not understand. Recipients should restart
-timeout periods on receipt of a well-formed notification, whether or
-not they understand it.
-
- Senders should only send the notifications described here when this
-protocol description specifies that they are permitted. In the future,
-we may extend the protocol to permit existing notifications in new
-contexts; this rule helps older senders avoid confusing newer
-recipients.
-
- (Older versions of GDB ignore bytes received until they see the `$'
-byte that begins an ordinary packet, so new stubs may transmit
-notifications without fear of confusing older clients. There are no
-notifications defined for GDB to send at the moment, but we assume that
-most older stubs would ignore them, as well.)
-
- The following notification packets from the stub to GDB are defined:
-
-`Stop: REPLY'
- Report an asynchronous stop event in non-stop mode. The REPLY has
- the form of a stop reply, as described in *Note Stop Reply
- Packets::. Refer to *Note Remote Non-Stop::, for information on
- how these notifications are acknowledged by GDB.
+ Function returning other than 'void'. The name of the internal GDB
+variable storing the result is printed, together with the value itself.
-\1f
-File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
-
-E.10 Remote Protocol Support for Non-Stop Mode
-==============================================
-
-GDB's remote protocol supports non-stop debugging of multi-threaded
-programs, as described in *Note Non-Stop Mode::. If the stub supports
-non-stop mode, it should report that to GDB by including `QNonStop+' in
-its `qSupported' response (*note qSupported::).
-
- GDB typically sends a `QNonStop' packet only when establishing a new
-connection with the stub. Entering non-stop mode does not alter the
-state of any currently-running threads, but targets must stop all
-threads in any already-attached processes when entering all-stop mode.
-GDB uses the `?' packet as necessary to probe the target state after a
-mode change.
-
- In non-stop mode, when an attached process encounters an event that
-would otherwise be reported with a stop reply, it uses the asynchronous
-notification mechanism (*note Notification Packets::) to inform GDB.
-In contrast to all-stop mode, where all threads in all processes are
-stopped when a stop reply is sent, in non-stop mode only the thread
-reporting the stop event is stopped. That is, when reporting a `S' or
-`T' response to indicate completion of a step operation, hitting a
-breakpoint, or a fault, only the affected thread is stopped; any other
-still-running threads continue to run. When reporting a `W' or `X'
-response, all running threads belonging to other attached processes
-continue to run.
-
- Only one stop reply notification at a time may be pending; if
-additional stop events occur before GDB has acknowledged the previous
-notification, they must be queued by the stub for later synchronous
-transmission in response to `vStopped' packets from GDB. Because the
-notification mechanism is unreliable, the stub is permitted to resend a
-stop reply notification if it believes GDB may not have received it.
-GDB ignores additional stop reply notifications received before it has
-finished processing a previous notification and the stub has completed
-sending any queued stop events.
-
- Otherwise, GDB must be prepared to receive a stop reply notification
-at any time. Specifically, they may appear when GDB is not otherwise
-reading input from the stub, or when GDB is expecting to read a normal
-synchronous response or a `+'/`-' acknowledgment to a packet it has
-sent. Notification packets are distinct from any other communication
-from the stub so there is no ambiguity.
-
- After receiving a stop reply notification, GDB shall acknowledge it
-by sending a `vStopped' packet (*note vStopped packet::) as a regular,
-synchronous request to the stub. Such acknowledgment is not required
-to happen immediately, as GDB is permitted to send other, unrelated
-packets to the stub first, which the stub should process normally.
-
- Upon receiving a `vStopped' packet, if the stub has other queued
-stop events to report to GDB, it shall respond by sending a normal stop
-reply response. GDB shall then send another `vStopped' packet to
-solicit further responses; again, it is permitted to send other,
-unrelated packets as well which the stub should process normally.
-
- If the stub receives a `vStopped' packet and there are no additional
-stop events to report, the stub shall return an `OK' response. At this
-point, if further stop events occur, the stub shall send a new stop
-reply notification, GDB shall accept the notification, and the process
-shall be repeated.
-
- In non-stop mode, the target shall respond to the `?' packet as
-follows. First, any incomplete stop reply notification/`vStopped'
-sequence in progress is abandoned. The target must begin a new
-sequence reporting stop events for all stopped threads, whether or not
-it has previously reported those events to GDB. The first stop reply
-is sent as a synchronous reply to the `?' packet, and subsequent stop
-replies are sent as responses to `vStopped' packets using the mechanism
-described above. The target must not send asynchronous stop reply
-notifications until the sequence is complete. If all threads are
-running when the target receives the `?' packet, or if the target is
-not attached to any process, it shall respond `OK'.
+ -exec-finish
+ ^running
+ (gdb)
+ *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
+ args=[{name="a",value="1"],{name="b",value="9"}},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ gdb-result-var="$1",return-value="0"
+ (gdb)
-\1f
-File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
+The '-exec-interrupt' Command
+-----------------------------
-E.11 Packet Acknowledgment
-==========================
+Synopsis
+........
-By default, when either the host or the target machine receives a
-packet, the first response expected is an acknowledgment: either `+'
-(to indicate the package was received correctly) or `-' (to request
-retransmission). This mechanism allows the GDB remote protocol to
-operate over unreliable transport mechanisms, such as a serial line.
-
- In cases where the transport mechanism is itself reliable (such as a
-pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It
-may be desirable to disable them in that case to reduce communication
-overhead, or for other reasons. This can be accomplished by means of
-the `QStartNoAckMode' packet; *note QStartNoAckMode::.
-
- When in no-acknowledgment mode, neither the stub nor GDB shall send
-or expect `+'/`-' protocol acknowledgments. The packet and response
-format still includes the normal checksum, as described in *Note
-Overview::, but the checksum may be ignored by the receiver.
-
- If the stub supports `QStartNoAckMode' and prefers to operate in
-no-acknowledgment mode, it should report that to GDB by including
-`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::.
-If GDB also supports `QStartNoAckMode' and it has not been disabled via
-the `set remote noack-packet off' command (*note Remote
-Configuration::), GDB may then send a `QStartNoAckMode' packet to the
-stub. Only then may the stub actually turn off packet acknowledgments.
-GDB sends a final `+' acknowledgment of the stub's `OK' response, which
-can be safely ignored by the stub.
-
- Note that `set remote noack-packet' command only affects negotiation
-between GDB and the stub when subsequent connections are made; it does
-not affect the protocol acknowledgment state for any current connection.
-Since `+'/`-' acknowledgments are enabled by default when a new
-connection is established, there is also no protocol request to
-re-enable the acknowledgments for the current connection, once disabled.
+ -exec-interrupt [--all|--thread-group N]
-\1f
-File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
-
-E.12 Examples
-=============
-
-Example sequence of a target being re-started. Notice how the restart
-does not get any direct output:
-
- -> `R00'
- <- `+'
- _target restarts_
- -> `?'
- <- `+'
- <- `T001:1234123412341234'
- -> `+'
-
- Example sequence of a target being stepped by a single instruction:
-
- -> `G1445...'
- <- `+'
- -> `s'
- <- `+'
- _time passes_
- <- `T001:1234123412341234'
- -> `+'
- -> `g'
- <- `+'
- <- `1455...'
- -> `+'
+ Interrupts the background execution of the target. Note how the
+token associated with the stop message is the one for the execution
+command that has been interrupted. The token for the interrupt itself
+only appears in the '^done' output. If the user is trying to interrupt
+a non-running program, an error message will be printed.
-\1f
-File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
+ Note that when asynchronous execution is enabled, this command is
+asynchronous just like other execution commands. That is, first the
+'^done' response will be printed, and the target stop will be reported
+after that using the '*stopped' notification.
-E.13 File-I/O Remote Protocol Extension
-=======================================
+ In non-stop mode, only the context thread is interrupted by default.
+All threads (in all inferiors) will be interrupted if the '--all' option
+is specified. If the '--thread-group' option is specified, all threads
+in that group will be interrupted.
-* Menu:
+GDB Command
+...........
-* File-I/O Overview::
-* Protocol Basics::
-* The F Request Packet::
-* The F Reply Packet::
-* The Ctrl-C Message::
-* Console I/O::
-* List of Supported Calls::
-* Protocol-specific Representation of Datatypes::
-* Constants::
-* File-I/O Examples::
+The corresponding GDB command is 'interrupt'.
-\1f
-File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
+Example
+.......
-E.13.1 File-I/O Overview
-------------------------
+ (gdb)
+ 111-exec-continue
+ 111^running
-The "File I/O remote protocol extension" (short: File-I/O) allows the
-target to use the host's file system and console I/O to perform various
-system calls. System calls on the target system are translated into a
-remote protocol packet to the host system, which then performs the
-needed actions and returns a response packet to the target system.
-This simulates file system operations even on targets that lack file
-systems.
-
- The protocol is defined to be independent of both the host and
-target systems. It uses its own internal representation of datatypes
-and values. Both GDB and the target's GDB stub are responsible for
-translating the system-dependent value representations into the internal
-protocol representations when data is transmitted.
-
- The communication is synchronous. A system call is possible only
-when GDB is waiting for a response from the `C', `c', `S' or `s'
-packets. While GDB handles the request for a system call, the target
-is stopped to allow deterministic access to the target's memory.
-Therefore File-I/O is not interruptible by target signals. On the
-other hand, it is possible to interrupt File-I/O by a user interrupt
-(`Ctrl-C') within GDB.
-
- The target's request to perform a host system call does not finish
-the latest `C', `c', `S' or `s' action. That means, after finishing
-the system call, the target returns to continuing the previous activity
-(continue, step). No additional continue or step request from GDB is
-required.
-
- (gdb) continue
- <- target requests 'system call X'
- target is stopped, GDB executes system call
- -> GDB returns result
- ... target continues, GDB returns to wait for the target
- <- target hits breakpoint and sends a Txx packet
-
- The protocol only supports I/O on the console and to regular files on
-the host file system. Character or block special devices, pipes, named
-pipes, sockets or any other communication method on the host system are
-not supported by this protocol.
-
- File I/O is not supported in non-stop mode.
+ (gdb)
+ 222-exec-interrupt
+ 222^done
+ (gdb)
+ 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
+ frame={addr="0x00010140",func="foo",args=[],file="try.c",
+ fullname="/home/foo/bar/try.c",line="13"}
+ (gdb)
-\1f
-File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
+ (gdb)
+ -exec-interrupt
+ ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
+ (gdb)
-E.13.2 Protocol Basics
-----------------------
+The '-exec-jump' Command
+------------------------
-The File-I/O protocol uses the `F' packet as the request as well as
-reply packet. Since a File-I/O system call can only occur when GDB is
-waiting for a response from the continuing or stepping target, the
-File-I/O request is a reply that GDB has to expect as a result of a
-previous `C', `c', `S' or `s' packet. This `F' packet contains all
-information needed to allow GDB to call the appropriate host system
-call:
+Synopsis
+........
- * A unique identifier for the requested system call.
+ -exec-jump LOCATION
- * All parameters to the system call. Pointers are given as addresses
- in the target memory address space. Pointers to strings are given
- as pointer/length pair. Numerical values are given as they are.
- Numerical control flags are given in a protocol-specific
- representation.
+ Resumes execution of the inferior program at the location specified
+by parameter. *Note Specify Location::, for a description of the
+different forms of LOCATION.
+GDB Command
+...........
- At this point, GDB has to perform the following actions.
+The corresponding GDB command is 'jump'.
- * If the parameters include pointer values to data needed as input
- to a system call, GDB requests this data from the target with a
- standard `m' packet request. This additional communication has to
- be expected by the target implementation and is handled as any
- other `m' packet.
+Example
+.......
- * GDB translates all value from protocol representation to host
- representation as needed. Datatypes are coerced into the host
- types.
+ -exec-jump foo.c:10
+ *running,thread-id="all"
+ ^running
- * GDB calls the system call.
+The '-exec-next' Command
+------------------------
- * It then coerces datatypes back to protocol representation.
+Synopsis
+........
- * If the system call is expected to return data in buffer space
- specified by pointer parameters to the call, the data is
- transmitted to the target using a `M' or `X' packet. This packet
- has to be expected by the target implementation and is handled as
- any other `M' or `X' packet.
+ -exec-next [--reverse]
+ Resumes execution of the inferior program, stopping when the
+beginning of the next source line is reached.
- Eventually GDB replies with another `F' packet which contains all
-necessary information for the target to continue. This at least
-contains
+ If the '--reverse' option is specified, resumes reverse execution of
+the inferior program, stopping at the beginning of the previous source
+line. If you issue this command on the first line of a function, it
+will take you back to the caller of that function, to the source line
+where the function was called.
- * Return value.
+GDB Command
+...........
- * `errno', if has been changed by the system call.
+The corresponding GDB command is 'next'.
- * "Ctrl-C" flag.
+Example
+.......
+ -exec-next
+ ^running
+ (gdb)
+ *stopped,reason="end-stepping-range",line="8",file="hello.c"
+ (gdb)
- After having done the needed type and value coercion, the target
-continues the latest continue or step action.
+The '-exec-next-instruction' Command
+------------------------------------
-\1f
-File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
+Synopsis
+........
-E.13.3 The `F' Request Packet
------------------------------
+ -exec-next-instruction [--reverse]
-The `F' request packet has the following format:
+ Executes one machine instruction. If the instruction is a function
+call, continues until the function returns. If the program stops at an
+instruction in the middle of a source line, the address will be printed
+as well.
-`FCALL-ID,PARAMETER...'
- CALL-ID is the identifier to indicate the host system call to be
- called. This is just the name of the function.
+ If the '--reverse' option is specified, resumes reverse execution of
+the inferior program, stopping at the previous instruction. If the
+previously executed instruction was a return from another function, it
+will continue to execute in reverse until the call to that function
+(from the current stack frame) is reached.
- PARAMETER... are the parameters to the system call. Parameters
- are hexadecimal integer values, either the actual values in case
- of scalar datatypes, pointers to target buffer space in case of
- compound datatypes and unspecified memory areas, or pointer/length
- pairs in case of string parameters. These are appended to the
- CALL-ID as a comma-delimited list. All values are transmitted in
- ASCII string representation, pointer/length pairs separated by a
- slash.
+GDB Command
+...........
+The corresponding GDB command is 'nexti'.
-\1f
-File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
+Example
+.......
-E.13.4 The `F' Reply Packet
----------------------------
+ (gdb)
+ -exec-next-instruction
+ ^running
-The `F' reply packet has the following format:
+ (gdb)
+ *stopped,reason="end-stepping-range",
+ addr="0x000100d4",line="5",file="hello.c"
+ (gdb)
-`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
- RETCODE is the return code of the system call as hexadecimal value.
+The '-exec-return' Command
+--------------------------
- ERRNO is the `errno' set by the call, in protocol-specific
- representation. This parameter can be omitted if the call was
- successful.
+Synopsis
+........
- CTRL-C FLAG is only sent if the user requested a break. In this
- case, ERRNO must be sent as well, even if the call was successful.
- The CTRL-C FLAG itself consists of the character `C':
+ -exec-return
- F0,0,C
+ Makes current function return immediately. Doesn't execute the
+inferior. Displays the new current frame.
- or, if the call was interrupted before the host call has been
- performed:
+GDB Command
+...........
- F-1,4,C
+The corresponding GDB command is 'return'.
+
+Example
+.......
+
+ (gdb)
+ 200-break-insert callee4
+ 200^done,bkpt={number="1",addr="0x00010734",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
+ (gdb)
+ 000-exec-run
+ 000^running
+ (gdb)
+ 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
+ frame={func="callee4",args=[],
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
+ (gdb)
+ 205-break-delete
+ 205^done
+ (gdb)
+ 111-exec-return
+ 111^done,frame={level="0",func="callee3",
+ args=[{name="strarg",
+ value="0x11940 \"A string argument.\""}],
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
+ (gdb)
+
+The '-exec-run' Command
+-----------------------
+
+Synopsis
+........
+
+ -exec-run [ --all | --thread-group N ] [ --start ]
+
+ Starts execution of the inferior from the beginning. The inferior
+executes until either a breakpoint is encountered or the program exits.
+In the latter case the output will include an exit code, if the program
+has exited exceptionally.
+
+ When neither the '--all' nor the '--thread-group' option is
+specified, the current inferior is started. If the '--thread-group'
+option is specified, it should refer to a thread group of type
+'process', and that thread group will be started. If the '--all' option
+is specified, then all inferiors will be started.
+
+ Using the '--start' option instructs the debugger to stop the
+execution at the start of the inferior's main subprogram, following the
+same behavior as the 'start' command (*note Starting::).
+
+GDB Command
+...........
- assuming 4 is the protocol-specific representation of `EINTR'.
+The corresponding GDB command is 'run'.
+
+Examples
+........
+
+ (gdb)
+ -break-insert main
+ ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
+ (gdb)
+ -exec-run
+ ^running
+ (gdb)
+ *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
+ frame={func="main",args=[],file="recursive2.c",
+ fullname="/home/foo/bar/recursive2.c",line="4"}
+ (gdb)
+
+Program exited normally:
+
+ (gdb)
+ -exec-run
+ ^running
+ (gdb)
+ x = 55
+ *stopped,reason="exited-normally"
+ (gdb)
+
+Program exited exceptionally:
+
+ (gdb)
+ -exec-run
+ ^running
+ (gdb)
+ x = 55
+ *stopped,reason="exited",exit-code="01"
+ (gdb)
+
+ Another way the program can terminate is if it receives a signal such
+as 'SIGINT'. In this case, GDB/MI displays this:
+
+ (gdb)
+ *stopped,reason="exited-signalled",signal-name="SIGINT",
+ signal-meaning="Interrupt"
+
+The '-exec-step' Command
+------------------------
+Synopsis
+........
-\1f
-File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
+ -exec-step [--reverse]
-E.13.5 The `Ctrl-C' Message
----------------------------
+ Resumes execution of the inferior program, stopping when the
+beginning of the next source line is reached, if the next source line is
+not a function call. If it is, stop at the first instruction of the
+called function. If the '--reverse' option is specified, resumes
+reverse execution of the inferior program, stopping at the beginning of
+the previously executed source line.
-If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
-Packet::), the target should behave as if it had gotten a break
-message. The meaning for the target is "system call interrupted by
-`SIGINT'". Consequentially, the target should actually stop (as with a
-break message) and return to GDB with a `T02' packet.
+GDB Command
+...........
- It's important for the target to know in which state the system call
-was interrupted. There are two possible cases:
+The corresponding GDB command is 'step'.
- * The system call hasn't been performed on the host yet.
+Example
+.......
- * The system call on the host has been finished.
+Stepping into a function:
+ -exec-step
+ ^running
+ (gdb)
+ *stopped,reason="end-stepping-range",
+ frame={func="foo",args=[{name="a",value="10"},
+ {name="b",value="0"}],file="recursive2.c",
+ fullname="/home/foo/bar/recursive2.c",line="11"}
+ (gdb)
- These two states can be distinguished by the target by the value of
-the returned `errno'. If it's the protocol representation of `EINTR',
-the system call hasn't been performed. This is equivalent to the
-`EINTR' handling on POSIX systems. In any other case, the target may
-presume that the system call has been finished -- successfully or not
--- and should behave as if the break message arrived right after the
-system call.
+ Regular stepping:
- GDB must behave reliably. If the system call has not been called
-yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
-in the packet. If the system call on the host has been finished before
-the user requests a break, the full action must be finished by GDB.
-This requires sending `M' or `X' packets as necessary. The `F' packet
-may only be sent when either nothing has happened or the full action
-has been completed.
+ -exec-step
+ ^running
+ (gdb)
+ *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
+ (gdb)
-\1f
-File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
+The '-exec-step-instruction' Command
+------------------------------------
-E.13.6 Console I/O
-------------------
+Synopsis
+........
-By default and if not explicitly closed by the target system, the file
-descriptors 0, 1 and 2 are connected to the GDB console. Output on the
-GDB console is handled as any other file output operation (`write(1,
-...)' or `write(2, ...)'). Console input is handled by GDB so that
-after the target read request from file descriptor 0 all following
-typing is buffered until either one of the following conditions is met:
+ -exec-step-instruction [--reverse]
- * The user types `Ctrl-c'. The behaviour is as explained above, and
- the `read' system call is treated as finished.
+ Resumes the inferior which executes one machine instruction. If the
+'--reverse' option is specified, resumes reverse execution of the
+inferior program, stopping at the previously executed instruction. The
+output, once GDB has stopped, will vary depending on whether we have
+stopped in the middle of a source line or not. In the former case, the
+address at which the program stopped will be printed as well.
- * The user presses <RET>. This is treated as end of input with a
- trailing newline.
+GDB Command
+...........
- * The user types `Ctrl-d'. This is treated as end of input. No
- trailing character (neither newline nor `Ctrl-D') is appended to
- the input.
+The corresponding GDB command is 'stepi'.
+Example
+.......
- If the user has typed more characters than fit in the buffer given to
-the `read' call, the trailing characters are buffered in GDB until
-either another `read(0, ...)' is requested by the target, or debugging
-is stopped at the user's request.
+ (gdb)
+ -exec-step-instruction
+ ^running
-\1f
-File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
+ (gdb)
+ *stopped,reason="end-stepping-range",
+ frame={func="foo",args=[],file="try.c",
+ fullname="/home/foo/bar/try.c",line="10"}
+ (gdb)
+ -exec-step-instruction
+ ^running
-E.13.7 List of Supported Calls
-------------------------------
+ (gdb)
+ *stopped,reason="end-stepping-range",
+ frame={addr="0x000100f4",func="foo",args=[],file="try.c",
+ fullname="/home/foo/bar/try.c",line="10"}
+ (gdb)
-* Menu:
+The '-exec-until' Command
+-------------------------
-* open::
-* close::
-* read::
-* write::
-* lseek::
-* rename::
-* unlink::
-* stat/fstat::
-* gettimeofday::
-* isatty::
-* system::
+Synopsis
+........
-\1f
-File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
+ -exec-until [ LOCATION ]
-open
-....
+ Executes the inferior until the LOCATION specified in the argument is
+reached. If there is no argument, the inferior executes until a source
+line greater than the current one is reached. The reason for stopping
+in this case will be 'location-reached'.
-Synopsis:
- int open(const char *pathname, int flags);
- int open(const char *pathname, int flags, mode_t mode);
+GDB Command
+...........
-Request:
- `Fopen,PATHPTR/LEN,FLAGS,MODE'
+The corresponding GDB command is 'until'.
- FLAGS is the bitwise `OR' of the following values:
+Example
+.......
- `O_CREAT'
- If the file does not exist it will be created. The host
- rules apply as far as file ownership and time stamps are
- concerned.
+ (gdb)
+ -exec-until recursive2.c:6
+ ^running
+ (gdb)
+ x = 55
+ *stopped,reason="location-reached",frame={func="main",args=[],
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
+ (gdb)
- `O_EXCL'
- When used with `O_CREAT', if the file already exists it is an
- error and open() fails.
+\1f
+File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
- `O_TRUNC'
- If the file already exists and the open mode allows writing
- (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
- zero length.
+27.14 GDB/MI Stack Manipulation Commands
+========================================
- `O_APPEND'
- The file is opened in append mode.
+The '-enable-frame-filters' Command
+-----------------------------------
- `O_RDONLY'
- The file is opened for reading only.
+ -enable-frame-filters
- `O_WRONLY'
- The file is opened for writing only.
+ GDB allows Python-based frame filters to affect the output of the MI
+commands relating to stack traces. As there is no way to implement this
+in a fully backward-compatible way, a front end must request that this
+functionality be enabled.
- `O_RDWR'
- The file is opened for reading and writing.
+ Once enabled, this feature cannot be disabled.
- Other bits are silently ignored.
+ Note that if Python support has not been compiled into GDB, this
+command will still succeed (and do nothing).
- MODE is the bitwise `OR' of the following values:
+The '-stack-info-frame' Command
+-------------------------------
- `S_IRUSR'
- User has read permission.
+Synopsis
+........
- `S_IWUSR'
- User has write permission.
+ -stack-info-frame
- `S_IRGRP'
- Group has read permission.
+ Get info on the selected frame.
- `S_IWGRP'
- Group has write permission.
+GDB Command
+...........
- `S_IROTH'
- Others have read permission.
+The corresponding GDB command is 'info frame' or 'frame' (without
+arguments).
- `S_IWOTH'
- Others have write permission.
+Example
+.......
- Other bits are silently ignored.
+ (gdb)
+ -stack-info-frame
+ ^done,frame={level="1",addr="0x0001076c",func="callee3",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
+ (gdb)
-Return value:
- `open' returns the new file descriptor or -1 if an error occurred.
+The '-stack-info-depth' Command
+-------------------------------
-Errors:
+Synopsis
+........
- `EEXIST'
- PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
+ -stack-info-depth [ MAX-DEPTH ]
- `EISDIR'
- PATHNAME refers to a directory.
+ Return the depth of the stack. If the integer argument MAX-DEPTH is
+specified, do not count beyond MAX-DEPTH frames.
- `EACCES'
- The requested access is not allowed.
+GDB Command
+...........
- `ENAMETOOLONG'
- PATHNAME was too long.
+There's no equivalent GDB command.
+
+Example
+.......
+
+For a stack with frame levels 0 through 11:
+
+ (gdb)
+ -stack-info-depth
+ ^done,depth="12"
+ (gdb)
+ -stack-info-depth 4
+ ^done,depth="4"
+ (gdb)
+ -stack-info-depth 12
+ ^done,depth="12"
+ (gdb)
+ -stack-info-depth 11
+ ^done,depth="11"
+ (gdb)
+ -stack-info-depth 13
+ ^done,depth="12"
+ (gdb)
+
+The '-stack-list-arguments' Command
+-----------------------------------
- `ENOENT'
- A directory component in PATHNAME does not exist.
+Synopsis
+........
- `ENODEV'
- PATHNAME refers to a device, pipe, named pipe or socket.
+ -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
+ [ LOW-FRAME HIGH-FRAME ]
- `EROFS'
- PATHNAME refers to a file on a read-only filesystem and write
- access was requested.
+ Display a list of the arguments for the frames between LOW-FRAME and
+HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
+list the arguments for the whole call stack. If the two arguments are
+equal, show the single frame at the corresponding level. It is an error
+if LOW-FRAME is larger than the actual number of frames. On the other
+hand, HIGH-FRAME may be larger than the actual number of frames, in
+which case only existing frames will be returned.
- `EFAULT'
- PATHNAME is an invalid pointer value.
+ If PRINT-VALUES is 0 or '--no-values', print only the names of the
+variables; if it is 1 or '--all-values', print also their values; and if
+it is 2 or '--simple-values', print the name, type and value for simple
+data types, and the name and type for arrays, structures and unions. If
+the option '--no-frame-filters' is supplied, then Python frame filters
+will not be executed.
- `ENOSPC'
- No space on device to create the file.
+ If the '--skip-unavailable' option is specified, arguments that are
+not available are not listed. Partially available arguments are still
+displayed, however.
- `EMFILE'
- The process already has the maximum number of files open.
+ Use of this command to obtain arguments in a single frame is
+deprecated in favor of the '-stack-list-variables' command.
- `ENFILE'
- The limit on the total number of files open on the system has
- been reached.
+GDB Command
+...........
- `EINTR'
- The call was interrupted by the user.
+GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args'
+command which partially overlaps with the functionality of
+'-stack-list-arguments'.
+
+Example
+.......
+
+ (gdb)
+ -stack-list-frames
+ ^done,
+ stack=[
+ frame={level="0",addr="0x00010734",func="callee4",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
+ frame={level="1",addr="0x0001076c",func="callee3",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
+ frame={level="2",addr="0x0001078c",func="callee2",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
+ frame={level="3",addr="0x000107b4",func="callee1",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
+ frame={level="4",addr="0x000107e0",func="main",
+ file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
+ (gdb)
+ -stack-list-arguments 0
+ ^done,
+ stack-args=[
+ frame={level="0",args=[]},
+ frame={level="1",args=[name="strarg"]},
+ frame={level="2",args=[name="intarg",name="strarg"]},
+ frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
+ frame={level="4",args=[]}]
+ (gdb)
+ -stack-list-arguments 1
+ ^done,
+ stack-args=[
+ frame={level="0",args=[]},
+ frame={level="1",
+ args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
+ frame={level="2",args=[
+ {name="intarg",value="2"},
+ {name="strarg",value="0x11940 \"A string argument.\""}]},
+ {frame={level="3",args=[
+ {name="intarg",value="2"},
+ {name="strarg",value="0x11940 \"A string argument.\""},
+ {name="fltarg",value="3.5"}]},
+ frame={level="4",args=[]}]
+ (gdb)
+ -stack-list-arguments 0 2 2
+ ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
+ (gdb)
+ -stack-list-arguments 1 2 2
+ ^done,stack-args=[frame={level="2",
+ args=[{name="intarg",value="2"},
+ {name="strarg",value="0x11940 \"A string argument.\""}]}]
+ (gdb)
+
+The '-stack-list-frames' Command
+--------------------------------
+
+Synopsis
+........
+
+ -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ]
+
+ List the frames currently on the stack. For each frame it displays
+the following info:
+
+'LEVEL'
+ The frame number, 0 being the topmost frame, i.e., the innermost
+ function.
+'ADDR'
+ The '$pc' value for that frame.
+'FUNC'
+ Function name.
+'FILE'
+ File name of the source file where the function lives.
+'FULLNAME'
+ The full file name of the source file where the function lives.
+'LINE'
+ Line number corresponding to the '$pc'.
+'FROM'
+ The shared library where this function is defined. This is only
+ given if the frame's function is not known.
+
+ If invoked without arguments, this command prints a backtrace for the
+whole stack. If given two integer arguments, it shows the frames whose
+levels are between the two arguments (inclusive). If the two arguments
+are equal, it shows the single frame at the corresponding level. It is
+an error if LOW-FRAME is larger than the actual number of frames. On
+the other hand, HIGH-FRAME may be larger than the actual number of
+frames, in which case only existing frames will be returned. If the
+option '--no-frame-filters' is supplied, then Python frame filters will
+not be executed.
+
+GDB Command
+...........
+The corresponding GDB commands are 'backtrace' and 'where'.
+
+Example
+.......
+
+Full stack backtrace:
+
+ (gdb)
+ -stack-list-frames
+ ^done,stack=
+ [frame={level="0",addr="0x0001076c",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
+ frame={level="1",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="2",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="6",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="7",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="8",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="9",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="10",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="11",addr="0x00010738",func="main",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
+ (gdb)
+
+ Show frames between LOW_FRAME and HIGH_FRAME:
+
+ (gdb)
+ -stack-list-frames 3 5
+ ^done,stack=
+ [frame={level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
+ frame={level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
+ (gdb)
+
+ Show a single frame:
+
+ (gdb)
+ -stack-list-frames 3 3
+ ^done,stack=
+ [frame={level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
+ (gdb)
+
+The '-stack-list-locals' Command
+--------------------------------
+
+Synopsis
+........
+
+ -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
+
+ Display the local variable names for the selected frame. If
+PRINT-VALUES is 0 or '--no-values', print only the names of the
+variables; if it is 1 or '--all-values', print also their values; and if
+it is 2 or '--simple-values', print the name, type and value for simple
+data types, and the name and type for arrays, structures and unions. In
+this last case, a frontend can immediately display the value of simple
+data types and create variable objects for other data types when the
+user wishes to explore their values in more detail. If the option
+'--no-frame-filters' is supplied, then Python frame filters will not be
+executed.
+
+ If the '--skip-unavailable' option is specified, local variables that
+are not available are not listed. Partially available local variables
+are still displayed, however.
+
+ This command is deprecated in favor of the '-stack-list-variables'
+command.
+
+GDB Command
+...........
-\1f
-File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
+'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'.
-close
-.....
+Example
+.......
-Synopsis:
- int close(int fd);
+ (gdb)
+ -stack-list-locals 0
+ ^done,locals=[name="A",name="B",name="C"]
+ (gdb)
+ -stack-list-locals --all-values
+ ^done,locals=[{name="A",value="1"},{name="B",value="2"},
+ {name="C",value="{1, 2, 3}"}]
+ -stack-list-locals --simple-values
+ ^done,locals=[{name="A",type="int",value="1"},
+ {name="B",type="int",value="2"},{name="C",type="int [3]"}]
+ (gdb)
-Request:
- `Fclose,FD'
+The '-stack-list-variables' Command
+-----------------------------------
-Return value:
- `close' returns zero on success, or -1 if an error occurred.
+Synopsis
+........
-Errors:
+ -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
- `EBADF'
- FD isn't a valid open file descriptor.
+ Display the names of local variables and function arguments for the
+selected frame. If PRINT-VALUES is 0 or '--no-values', print only the
+names of the variables; if it is 1 or '--all-values', print also their
+values; and if it is 2 or '--simple-values', print the name, type and
+value for simple data types, and the name and type for arrays,
+structures and unions. If the option '--no-frame-filters' is supplied,
+then Python frame filters will not be executed.
- `EINTR'
- The call was interrupted by the user.
+ If the '--skip-unavailable' option is specified, local variables and
+arguments that are not available are not listed. Partially available
+arguments and local variables are still displayed, however.
+Example
+.......
-\1f
-File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
+ (gdb)
+ -stack-list-variables --thread 1 --frame 0 --all-values
+ ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}]
+ (gdb)
-read
-....
+The '-stack-select-frame' Command
+---------------------------------
-Synopsis:
- int read(int fd, void *buf, unsigned int count);
+Synopsis
+........
-Request:
- `Fread,FD,BUFPTR,COUNT'
+ -stack-select-frame FRAMENUM
-Return value:
- On success, the number of bytes read is returned. Zero indicates
- end of file. If count is zero, read returns zero as well. On
- error, -1 is returned.
+ Change the selected frame. Select a different frame FRAMENUM on the
+stack.
-Errors:
+ This command in deprecated in favor of passing the '--frame' option
+to every command.
- `EBADF'
- FD is not a valid file descriptor or is not open for reading.
+GDB Command
+...........
- `EFAULT'
- BUFPTR is an invalid pointer value.
+The corresponding GDB commands are 'frame', 'up', 'down',
+'select-frame', 'up-silent', and 'down-silent'.
- `EINTR'
- The call was interrupted by the user.
+Example
+.......
+ (gdb)
+ -stack-select-frame 2
+ ^done
+ (gdb)
\1f
-File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
+File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
-write
-.....
+27.15 GDB/MI Variable Objects
+=============================
-Synopsis:
- int write(int fd, const void *buf, unsigned int count);
+Introduction to Variable Objects
+--------------------------------
+
+Variable objects are "object-oriented" MI interface for examining and
+changing values of expressions. Unlike some other MI interfaces that
+work with expressions, variable objects are specifically designed for
+simple and efficient presentation in the frontend. A variable object is
+identified by string name. When a variable object is created, the
+frontend specifies the expression for that variable object. The
+expression can be a simple variable, or it can be an arbitrary complex
+expression, and can even involve CPU registers. After creating a
+variable object, the frontend can invoke other variable object
+operations--for example to obtain or change the value of a variable
+object, or to change display format.
+
+ Variable objects have hierarchical tree structure. Any variable
+object that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure. A child variable object can itself have
+children, recursively. Recursion ends when we reach leaf variable
+objects, which always have built-in types. Child variable objects are
+created only by explicit request, so if a frontend is not interested in
+the children of a particular variable object, no child will be created.
+
+ For a leaf variable object it is possible to obtain its value as a
+string, or set the value from a string. String value can be also
+obtained for a non-leaf variable object, but it's generally a string
+that only indicates the type of the object, and does not list its
+contents. Assignment to a non-leaf variable object is not allowed.
+
+ A frontend does not need to read the values of all variable objects
+each time the program stops. Instead, MI provides an update command
+that lists all variable objects whose values has changed since the last
+update operation. This considerably reduces the amount of data that
+must be transferred to the frontend. As noted above, children variable
+objects are created on demand, and only leaf variable objects have a
+real value. As result, gdb will read target memory only for leaf
+variables that frontend has created.
+
+ The automatic update is not always desirable. For example, a
+frontend might want to keep a value of some expression for future
+reference, and never update it. For another example, fetching memory is
+relatively slow for embedded targets, so a frontend might want to
+disable automatic update for the variables that are either not visible
+on the screen, or "closed". This is possible using so called "frozen
+variable objects". Such variable objects are never implicitly updated.
+
+ Variable objects can be either "fixed" or "floating". For the fixed
+variable object, the expression is parsed when the variable object is
+created, including associating identifiers to specific variables. The
+meaning of expression never changes. For a floating variable object the
+values of variables whose names appear in the expressions are
+re-evaluated every time in the context of the current frame. Consider
+this example:
+
+ void do_work(...)
+ {
+ struct work_state state;
+
+ if (...)
+ do_work(...);
+ }
+
+ If a fixed variable object for the 'state' variable is created in
+this function, and we enter the recursive call, the variable object will
+report the value of 'state' in the top-level 'do_work' invocation. On
+the other hand, a floating variable object will report the value of
+'state' in the current frame.
+
+ If an expression specified when creating a fixed variable object
+refers to a local variable, the variable object becomes bound to the
+thread and frame in which the variable object is created. When such
+variable object is updated, GDB makes sure that the thread/frame
+combination the variable object is bound to still exists, and
+re-evaluates the variable object in context of that thread/frame.
+
+ The following is the complete set of GDB/MI operations defined to
+access this functionality:
+
+*Operation* *Description*
+
+'-enable-pretty-printing' enable Python-based pretty-printing
+'-var-create' create a variable object
+'-var-delete' delete the variable object and/or its
+ children
+'-var-set-format' set the display format of this variable
+'-var-show-format' show the display format of this variable
+'-var-info-num-children' tells how many children this object has
+'-var-list-children' return a list of the object's children
+'-var-info-type' show the type of this variable object
+'-var-info-expression' print parent-relative expression that
+ this variable object represents
+'-var-info-path-expression' print full expression that this variable
+ object represents
+'-var-show-attributes' is this variable editable? does it exist
+ here?
+'-var-evaluate-expression' get the value of this variable
+'-var-assign' set the value of this variable
+'-var-update' update the variable and its children
+'-var-set-frozen' set frozeness attribute
+'-var-set-update-range' set range of children to display on
+ update
+
+ In the next subsection we describe each operation in detail and
+suggest how it can be used.
+
+Description And Use of Operations on Variable Objects
+-----------------------------------------------------
+
+The '-enable-pretty-printing' Command
+-------------------------------------
+
+ -enable-pretty-printing
+
+ GDB allows Python-based visualizers to affect the output of the MI
+variable object commands. However, because there was no way to
+implement this in a fully backward-compatible way, a front end must
+request that this functionality be enabled.
+
+ Once enabled, this feature cannot be disabled.
+
+ Note that if Python support has not been compiled into GDB, this
+command will still succeed (and do nothing).
+
+ This feature is currently (as of GDB 7.0) experimental, and may work
+differently in future versions of GDB.
+
+The '-var-create' Command
+-------------------------
-Request:
- `Fwrite,FD,BUFPTR,COUNT'
+Synopsis
+........
-Return value:
- On success, the number of bytes written are returned. Zero
- indicates nothing was written. On error, -1 is returned.
+ -var-create {NAME | "-"}
+ {FRAME-ADDR | "*" | "@"} EXPRESSION
-Errors:
+ This operation creates a variable object, which allows the monitoring
+of a variable, the result of an expression, a memory cell or a CPU
+register.
- `EBADF'
- FD is not a valid file descriptor or is not open for writing.
+ The NAME parameter is the string by which the object can be
+referenced. It must be unique. If '-' is specified, the varobj system
+will generate a string "varNNNNNN" automatically. It will be unique
+provided that one does not specify NAME of that format. The command
+fails if a duplicate name is found.
- `EFAULT'
- BUFPTR is an invalid pointer value.
+ The frame under which the expression should be evaluated can be
+specified by FRAME-ADDR. A '*' indicates that the current frame should
+be used. A '@' indicates that a floating variable object must be
+created.
- `EFBIG'
- An attempt was made to write a file that exceeds the
- host-specific maximum file size allowed.
+ EXPRESSION is any expression valid on the current language set (must
+not begin with a '*'), or one of the following:
- `ENOSPC'
- No space on device to write the data.
+ * '*ADDR', where ADDR is the address of a memory cell
- `EINTR'
- The call was interrupted by the user.
+ * '*ADDR-ADDR' -- a memory address range (TBD)
+ * '$REGNAME' -- a CPU register name
-\1f
-File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
+ A varobj's contents may be provided by a Python-based pretty-printer.
+In this case the varobj is known as a "dynamic varobj". Dynamic varobjs
+have slightly different semantics in some cases. If the
+'-enable-pretty-printing' command is not sent, then GDB will never
+create a dynamic varobj. This ensures backward compatibility for
+existing clients.
-lseek
-.....
+Result
+......
-Synopsis:
- long lseek (int fd, long offset, int flag);
+This operation returns attributes of the newly-created varobj. These
+are:
-Request:
- `Flseek,FD,OFFSET,FLAG'
+'name'
+ The name of the varobj.
- FLAG is one of:
+'numchild'
+ The number of children of the varobj. This number is not
+ necessarily reliable for a dynamic varobj. Instead, you must
+ examine the 'has_more' attribute.
- `SEEK_SET'
- The offset is set to OFFSET bytes.
+'value'
+ The varobj's scalar value. For a varobj whose type is some sort of
+ aggregate (e.g., a 'struct'), or for a dynamic varobj, this value
+ will not be interesting.
- `SEEK_CUR'
- The offset is set to its current location plus OFFSET bytes.
+'type'
+ The varobj's type. This is a string representation of the type, as
+ would be printed by the GDB CLI. If 'print object' (*note set print
+ object: Print Settings.) is set to 'on', the _actual_ (derived)
+ type of the object is shown rather than the _declared_ one.
- `SEEK_END'
- The offset is set to the size of the file plus OFFSET bytes.
+'thread-id'
+ If a variable object is bound to a specific thread, then this is
+ the thread's identifier.
-Return value:
- On success, the resulting unsigned offset in bytes from the
- beginning of the file is returned. Otherwise, a value of -1 is
- returned.
+'has_more'
+ For a dynamic varobj, this indicates whether there appear to be any
+ children available. For a non-dynamic varobj, this will be 0.
-Errors:
+'dynamic'
+ This attribute will be present and have the value '1' if the varobj
+ is a dynamic varobj. If the varobj is not a dynamic varobj, then
+ this attribute will not be present.
- `EBADF'
- FD is not a valid open file descriptor.
+'displayhint'
+ A dynamic varobj can supply a display hint to the front end. The
+ value comes directly from the Python pretty-printer object's
+ 'display_hint' method. *Note Pretty Printing API::.
- `ESPIPE'
- FD is associated with the GDB console.
+ Typical output will look like this:
- `EINVAL'
- FLAG is not a proper value.
+ name="NAME",numchild="N",type="TYPE",thread-id="M",
+ has_more="HAS_MORE"
- `EINTR'
- The call was interrupted by the user.
+The '-var-delete' Command
+-------------------------
+Synopsis
+........
-\1f
-File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
+ -var-delete [ -c ] NAME
-rename
-......
+ Deletes a previously created variable object and all of its children.
+With the '-c' option, just deletes the children.
-Synopsis:
- int rename(const char *oldpath, const char *newpath);
+ Returns an error if the object NAME is not found.
-Request:
- `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
+The '-var-set-format' Command
+-----------------------------
-Return value:
- On success, zero is returned. On error, -1 is returned.
+Synopsis
+........
-Errors:
+ -var-set-format NAME FORMAT-SPEC
- `EISDIR'
- NEWPATH is an existing directory, but OLDPATH is not a
- directory.
+ Sets the output format for the value of the object NAME to be
+FORMAT-SPEC.
- `EEXIST'
- NEWPATH is a non-empty directory.
+ The syntax for the FORMAT-SPEC is as follows:
- `EBUSY'
- OLDPATH or NEWPATH is a directory that is in use by some
- process.
+ FORMAT-SPEC ==>
+ {binary | decimal | hexadecimal | octal | natural}
- `EINVAL'
- An attempt was made to make a directory a subdirectory of
- itself.
+ The natural format is the default format choosen automatically based
+on the variable type (like decimal for an 'int', hex for pointers,
+etc.).
- `ENOTDIR'
- A component used as a directory in OLDPATH or new path is
- not a directory. Or OLDPATH is a directory and NEWPATH
- exists but is not a directory.
+ For a variable with children, the format is set only on the variable
+itself, and the children are not affected.
- `EFAULT'
- OLDPATHPTR or NEWPATHPTR are invalid pointer values.
+The '-var-show-format' Command
+------------------------------
- `EACCES'
- No access to the file or the path of the file.
+Synopsis
+........
- `ENAMETOOLONG'
- OLDPATH or NEWPATH was too long.
+ -var-show-format NAME
- `ENOENT'
- A directory component in OLDPATH or NEWPATH does not exist.
+ Returns the format used to display the value of the object NAME.
- `EROFS'
- The file is on a read-only filesystem.
+ FORMAT ==>
+ FORMAT-SPEC
- `ENOSPC'
- The device containing the file has no room for the new
- directory entry.
+The '-var-info-num-children' Command
+------------------------------------
- `EINTR'
- The call was interrupted by the user.
+Synopsis
+........
+ -var-info-num-children NAME
-\1f
-File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
+ Returns the number of children of a variable object NAME:
-unlink
-......
+ numchild=N
-Synopsis:
- int unlink(const char *pathname);
+ Note that this number is not completely reliable for a dynamic
+varobj. It will return the current number of children, but more
+children may be available.
-Request:
- `Funlink,PATHNAMEPTR/LEN'
+The '-var-list-children' Command
+--------------------------------
-Return value:
- On success, zero is returned. On error, -1 is returned.
+Synopsis
+........
-Errors:
+ -var-list-children [PRINT-VALUES] NAME [FROM TO]
- `EACCES'
- No access to the file or the path of the file.
+ Return a list of the children of the specified variable object and
+create variable objects for them, if they do not already exist. With a
+single argument or if PRINT-VALUES has a value of 0 or '--no-values',
+print only the names of the variables; if PRINT-VALUES is 1 or
+'--all-values', also print their values; and if it is 2 or
+'--simple-values' print the name and value for simple data types and
+just the name for arrays, structures and unions.
- `EPERM'
- The system does not allow unlinking of directories.
+ FROM and TO, if specified, indicate the range of children to report.
+If FROM or TO is less than zero, the range is reset and all children
+will be reported. Otherwise, children starting at FROM (zero-based) and
+up to and excluding TO will be reported.
- `EBUSY'
- The file PATHNAME cannot be unlinked because it's being used
- by another process.
+ If a child range is requested, it will only affect the current call
+to '-var-list-children', but not future calls to '-var-update'. For
+this, you must instead use '-var-set-update-range'. The intent of this
+approach is to enable a front end to implement any update approach it
+likes; for example, scrolling a view may cause the front end to request
+more children with '-var-list-children', and then the front end could
+call '-var-set-update-range' with a different range to ensure that
+future updates are restricted to just the visible items.
- `EFAULT'
- PATHNAMEPTR is an invalid pointer value.
+ For each child the following results are returned:
- `ENAMETOOLONG'
- PATHNAME was too long.
+NAME
+ Name of the variable object created for this child.
- `ENOENT'
- A directory component in PATHNAME does not exist.
+EXP
+ The expression to be shown to the user by the front end to
+ designate this child. For example this may be the name of a
+ structure member.
- `ENOTDIR'
- A component of the path is not a directory.
+ For a dynamic varobj, this value cannot be used to form an
+ expression. There is no way to do this at all with a dynamic
+ varobj.
- `EROFS'
- The file is on a read-only filesystem.
+ For C/C++ structures there are several pseudo children returned to
+ designate access qualifiers. For these pseudo children EXP is
+ 'public', 'private', or 'protected'. In this case the type and
+ value are not present.
- `EINTR'
- The call was interrupted by the user.
+ A dynamic varobj will not report the access qualifying
+ pseudo-children, regardless of the language. This information is
+ not available at all with a dynamic varobj.
+NUMCHILD
+ Number of children this child has. For a dynamic varobj, this will
+ be 0.
-\1f
-File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
+TYPE
+ The type of the child. If 'print object' (*note set print object:
+ Print Settings.) is set to 'on', the _actual_ (derived) type of the
+ object is shown rather than the _declared_ one.
-stat/fstat
-..........
+VALUE
+ If values were requested, this is the value.
-Synopsis:
- int stat(const char *pathname, struct stat *buf);
- int fstat(int fd, struct stat *buf);
+THREAD-ID
+ If this variable object is associated with a thread, this is the
+ thread id. Otherwise this result is not present.
-Request:
- `Fstat,PATHNAMEPTR/LEN,BUFPTR'
- `Ffstat,FD,BUFPTR'
+FROZEN
+ If the variable object is frozen, this variable will be present
+ with a value of 1.
-Return value:
- On success, zero is returned. On error, -1 is returned.
+DISPLAYHINT
+ A dynamic varobj can supply a display hint to the front end. The
+ value comes directly from the Python pretty-printer object's
+ 'display_hint' method. *Note Pretty Printing API::.
-Errors:
+DYNAMIC
+ This attribute will be present and have the value '1' if the varobj
+ is a dynamic varobj. If the varobj is not a dynamic varobj, then
+ this attribute will not be present.
- `EBADF'
- FD is not a valid open file.
+ The result may have its own attributes:
- `ENOENT'
- A directory component in PATHNAME does not exist or the path
- is an empty string.
+'displayhint'
+ A dynamic varobj can supply a display hint to the front end. The
+ value comes directly from the Python pretty-printer object's
+ 'display_hint' method. *Note Pretty Printing API::.
- `ENOTDIR'
- A component of the path is not a directory.
+'has_more'
+ This is an integer attribute which is nonzero if there are children
+ remaining after the end of the selected range.
- `EFAULT'
- PATHNAMEPTR is an invalid pointer value.
+Example
+.......
- `EACCES'
- No access to the file or the path of the file.
+ (gdb)
+ -var-list-children n
+ ^done,numchild=N,children=[child={name=NAME,exp=EXP,
+ numchild=N,type=TYPE},(repeats N times)]
+ (gdb)
+ -var-list-children --all-values n
+ ^done,numchild=N,children=[child={name=NAME,exp=EXP,
+ numchild=N,value=VALUE,type=TYPE},(repeats N times)]
- `ENAMETOOLONG'
- PATHNAME was too long.
+The '-var-info-type' Command
+----------------------------
- `EINTR'
- The call was interrupted by the user.
+Synopsis
+........
+ -var-info-type NAME
-\1f
-File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
+ Returns the type of the specified variable NAME. The type is
+returned as a string in the same format as it is output by the GDB CLI:
-gettimeofday
-............
+ type=TYPENAME
-Synopsis:
- int gettimeofday(struct timeval *tv, void *tz);
+The '-var-info-expression' Command
+----------------------------------
-Request:
- `Fgettimeofday,TVPTR,TZPTR'
+Synopsis
+........
-Return value:
- On success, 0 is returned, -1 otherwise.
+ -var-info-expression NAME
-Errors:
+ Returns a string that is suitable for presenting this variable object
+in user interface. The string is generally not valid expression in the
+current language, and cannot be evaluated.
- `EINVAL'
- TZ is a non-NULL pointer.
+ For example, if 'a' is an array, and variable object 'A' was created
+for 'a', then we'll get this output:
- `EFAULT'
- TVPTR and/or TZPTR is an invalid pointer value.
+ (gdb) -var-info-expression A.1
+ ^done,lang="C",exp="1"
+Here, the value of 'lang' is the language name, which can be found in
+*note Supported Languages::.
-\1f
-File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
+ Note that the output of the '-var-list-children' command also
+includes those expressions, so the '-var-info-expression' command is of
+limited use.
-isatty
-......
+The '-var-info-path-expression' Command
+---------------------------------------
-Synopsis:
- int isatty(int fd);
+Synopsis
+........
-Request:
- `Fisatty,FD'
+ -var-info-path-expression NAME
-Return value:
- Returns 1 if FD refers to the GDB console, 0 otherwise.
+ Returns an expression that can be evaluated in the current context
+and will yield the same value that a variable object has. Compare this
+with the '-var-info-expression' command, which result can be used only
+for UI presentation. Typical use of the '-var-info-path-expression'
+command is creating a watchpoint from a variable object.
-Errors:
+ This command is currently not valid for children of a dynamic varobj,
+and will give an error when invoked on one.
- `EINTR'
- The call was interrupted by the user.
+ For example, suppose 'C' is a C++ class, derived from class 'Base',
+and that the 'Base' class has a member called 'm_size'. Assume a
+variable 'c' is has the type of 'C' and a variable object 'C' was
+created for variable 'c'. Then, we'll get this output:
+ (gdb) -var-info-path-expression C.Base.public.m_size
+ ^done,path_expr=((Base)c).m_size)
+The '-var-show-attributes' Command
+----------------------------------
- Note that the `isatty' call is treated as a special case: it returns
-1 to the target if the file descriptor is attached to the GDB console,
-0 otherwise. Implementing through system calls would require
-implementing `ioctl' and would be more complex than needed.
+Synopsis
+........
-\1f
-File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
+ -var-show-attributes NAME
-system
-......
+ List attributes of the specified variable object NAME:
-Synopsis:
- int system(const char *command);
+ status=ATTR [ ( ,ATTR )* ]
-Request:
- `Fsystem,COMMANDPTR/LEN'
+where ATTR is '{ { editable | noneditable } | TBD }'.
-Return value:
- If LEN is zero, the return value indicates whether a shell is
- available. A zero return value indicates a shell is not available.
- For non-zero LEN, the value returned is -1 on error and the return
- status of the command otherwise. Only the exit status of the
- command is returned, which is extracted from the host's `system'
- return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh'
- could not be executed, 127 is returned.
+The '-var-evaluate-expression' Command
+--------------------------------------
-Errors:
+Synopsis
+........
- `EINTR'
- The call was interrupted by the user.
+ -var-evaluate-expression [-f FORMAT-SPEC] NAME
+ Evaluates the expression that is represented by the specified
+variable object and returns its value as a string. The format of the
+string can be specified with the '-f' option. The possible values of
+this option are the same as for '-var-set-format' (*note
+-var-set-format::). If the '-f' option is not specified, the current
+display format will be used. The current display format can be changed
+using the '-var-set-format' command.
- GDB takes over the full task of calling the necessary host calls to
-perform the `system' call. The return value of `system' on the host is
-simplified before it's returned to the target. Any termination signal
-information from the child process is discarded, and the return value
-consists entirely of the exit status of the called command.
+ value=VALUE
- Due to security concerns, the `system' call is by default refused by
-GDB. The user has to allow this call explicitly with the `set remote
-system-call-allowed 1' command.
+ Note that one must invoke '-var-list-children' for a variable before
+the value of a child variable can be evaluated.
-`set remote system-call-allowed'
- Control whether to allow the `system' calls in the File I/O
- protocol for the remote target. The default is zero (disabled).
+The '-var-assign' Command
+-------------------------
-`show remote system-call-allowed'
- Show whether the `system' calls are allowed in the File I/O
- protocol.
+Synopsis
+........
-\1f
-File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
+ -var-assign NAME EXPRESSION
-E.13.8 Protocol-specific Representation of Datatypes
-----------------------------------------------------
+ Assigns the value of EXPRESSION to the variable object specified by
+NAME. The object must be 'editable'. If the variable's value is
+altered by the assign, the variable will show up in any subsequent
+'-var-update' list.
-* Menu:
+Example
+.......
-* Integral Datatypes::
-* Pointer Values::
-* Memory Transfer::
-* struct stat::
-* struct timeval::
+ (gdb)
+ -var-assign var1 3
+ ^done,value="3"
+ (gdb)
+ -var-update *
+ ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
+ (gdb)
-\1f
-File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
+The '-var-update' Command
+-------------------------
-Integral Datatypes
-..................
+Synopsis
+........
+
+ -var-update [PRINT-VALUES] {NAME | "*"}
+
+ Reevaluate the expressions corresponding to the variable object NAME
+and all its direct and indirect children, and return the list of
+variable objects whose values have changed; NAME must be a root variable
+object. Here, "changed" means that the result of
+'-var-evaluate-expression' before and after the '-var-update' is
+different. If '*' is used as the variable object names, all existing
+variable objects are updated, except for frozen ones (*note
+-var-set-frozen::). The option PRINT-VALUES determines whether both
+names and values, or just names are printed. The possible values of
+this option are the same as for '-var-list-children' (*note
+-var-list-children::). It is recommended to use the '--all-values'
+option, to reduce the number of MI commands needed on each program stop.
+
+ With the '*' parameter, if a variable object is bound to a currently
+running thread, it will not be updated, without any diagnostic.
+
+ If '-var-set-update-range' was previously used on a varobj, then only
+the selected range of children will be reported.
+
+ '-var-update' reports all the changed varobjs in a tuple named
+'changelist'.
+
+ Each item in the change list is itself a tuple holding:
+
+'name'
+ The name of the varobj.
+
+'value'
+ If values were requested for this update, then this field will be
+ present and will hold the value of the varobj.
+
+'in_scope'
+ This field is a string which may take one of three values:
+
+ '"true"'
+ The variable object's current value is valid.
+
+ '"false"'
+ The variable object does not currently hold a valid value but
+ it may hold one in the future if its associated expression
+ comes back into scope.
+
+ '"invalid"'
+ The variable object no longer holds a valid value. This can
+ occur when the executable file being debugged has changed,
+ either through recompilation or by using the GDB 'file'
+ command. The front end should normally choose to delete these
+ variable objects.
+
+ In the future new values may be added to this list so the front
+ should be prepared for this possibility. *Note GDB/MI Development
+ and Front Ends: GDB/MI Development and Front Ends.
+
+'type_changed'
+ This is only present if the varobj is still valid. If the type
+ changed, then this will be the string 'true'; otherwise it will be
+ 'false'.
+
+ When a varobj's type changes, its children are also likely to have
+ become incorrect. Therefore, the varobj's children are
+ automatically deleted when this attribute is 'true'. Also, the
+ varobj's update range, when set using the '-var-set-update-range'
+ command, is unset.
+
+'new_type'
+ If the varobj's type changed, then this field will be present and
+ will hold the new type.
+
+'new_num_children'
+ For a dynamic varobj, if the number of children changed, or if the
+ type changed, this will be the new number of children.
+
+ The 'numchild' field in other varobj responses is generally not
+ valid for a dynamic varobj - it will show the number of children
+ that GDB knows about, but because dynamic varobjs lazily
+ instantiate their children, this will not reflect the number of
+ children which may be available.
+
+ The 'new_num_children' attribute only reports changes to the number
+ of children known by GDB. This is the only way to detect whether
+ an update has removed children (which necessarily can only happen
+ at the end of the update range).
+
+'displayhint'
+ The display hint, if any.
+
+'has_more'
+ This is an integer value, which will be 1 if there are more
+ children available outside the varobj's update range.
+
+'dynamic'
+ This attribute will be present and have the value '1' if the varobj
+ is a dynamic varobj. If the varobj is not a dynamic varobj, then
+ this attribute will not be present.
+
+'new_children'
+ If new children were added to a dynamic varobj within the selected
+ update range (as set by '-var-set-update-range'), then they will be
+ listed in this attribute.
+
+Example
+.......
+
+ (gdb)
+ -var-assign var1 3
+ ^done,value="3"
+ (gdb)
+ -var-update --all-values var1
+ ^done,changelist=[{name="var1",value="3",in_scope="true",
+ type_changed="false"}]
+ (gdb)
+
+The '-var-set-frozen' Command
+-----------------------------
-The integral datatypes used in the system calls are `int', `unsigned
-int', `long', `unsigned long', `mode_t', and `time_t'.
+Synopsis
+........
- `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
-bit values in this protocol.
+ -var-set-frozen NAME FLAG
- `long' and `unsigned long' are implemented as 64 bit types.
+ Set the frozenness flag on the variable object NAME. The FLAG
+parameter should be either '1' to make the variable frozen or '0' to
+make it unfrozen. If a variable object is frozen, then neither itself,
+nor any of its children, are implicitly updated by '-var-update' of a
+parent variable or by '-var-update *'. Only '-var-update' of the
+variable itself will update its value and values of its children. After
+a variable object is unfrozen, it is implicitly updated by all
+subsequent '-var-update' operations. Unfreezing a variable does not
+update it, only subsequent '-var-update' does.
- *Note Limits::, for corresponding MIN and MAX values (similar to
-those in `limits.h') to allow range checking on host and target.
+Example
+.......
- `time_t' datatypes are defined as seconds since the Epoch.
+ (gdb)
+ -var-set-frozen V 1
+ ^done
+ (gdb)
- All integral datatypes transferred as part of a memory read or write
-of a structured datatype e.g. a `struct stat' have to be given in big
-endian byte order.
+The '-var-set-update-range' command
+-----------------------------------
-\1f
-File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
+Synopsis
+........
-Pointer Values
-..............
+ -var-set-update-range NAME FROM TO
-Pointers to target data are transmitted as they are. An exception is
-made for pointers to buffers for which the length isn't transmitted as
-part of the function call, namely strings. Strings are transmitted as
-a pointer/length pair, both as hex values, e.g.
+ Set the range of children to be returned by future invocations of
+'-var-update'.
- `1aaf/12'
+ FROM and TO indicate the range of children to report. If FROM or TO
+is less than zero, the range is reset and all children will be reported.
+Otherwise, children starting at FROM (zero-based) and up to and
+excluding TO will be reported.
-which is a pointer to data of length 18 bytes at position 0x1aaf. The
-length is defined as the full string length in bytes, including the
-trailing null byte. For example, the string `"hello world"' at address
-0x123456 is transmitted as
+Example
+.......
- `123456/d'
+ (gdb)
+ -var-set-update-range V 1 2
+ ^done
-\1f
-File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
+The '-var-set-visualizer' command
+---------------------------------
-Memory Transfer
-...............
+Synopsis
+........
-Structured data which is transferred using a memory read or write (for
-example, a `struct stat') is expected to be in a protocol-specific
-format with all scalar multibyte datatypes being big endian.
-Translation to this representation needs to be done both by the target
-before the `F' packet is sent, and by GDB before it transfers memory to
-the target. Transferred pointers to structured data should point to
-the already-coerced data at any time.
+ -var-set-visualizer NAME VISUALIZER
-\1f
-File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
+ Set a visualizer for the variable object NAME.
-struct stat
-...........
+ VISUALIZER is the visualizer to use. The special value 'None' means
+to disable any visualizer in use.
-The buffer of type `struct stat' used by the target and GDB is defined
-as follows:
-
- struct stat {
- unsigned int st_dev; /* device */
- unsigned int st_ino; /* inode */
- mode_t st_mode; /* protection */
- unsigned int st_nlink; /* number of hard links */
- unsigned int st_uid; /* user ID of owner */
- unsigned int st_gid; /* group ID of owner */
- unsigned int st_rdev; /* device type (if inode device) */
- unsigned long st_size; /* total size, in bytes */
- unsigned long st_blksize; /* blocksize for filesystem I/O */
- unsigned long st_blocks; /* number of blocks allocated */
- time_t st_atime; /* time of last access */
- time_t st_mtime; /* time of last modification */
- time_t st_ctime; /* time of last change */
- };
+ If not 'None', VISUALIZER must be a Python expression. This
+expression must evaluate to a callable object which accepts a single
+argument. GDB will call this object with the value of the varobj NAME
+as an argument (this is done so that the same Python pretty-printing
+code can be used for both the CLI and MI). When called, this object must
+return an object which conforms to the pretty-printing interface (*note
+Pretty Printing API::).
- The integral datatypes conform to the definitions given in the
-appropriate section (see *Note Integral Datatypes::, for details) so
-this structure is of size 64 bytes.
+ The pre-defined function 'gdb.default_visualizer' may be used to
+select a visualizer by following the built-in process (*note Selecting
+Pretty-Printers::). This is done automatically when a varobj is
+created, and so ordinarily is not needed.
- The values of several fields have a restricted meaning and/or range
-of values.
+ This feature is only available if Python support is enabled. The MI
+command '-list-features' (*note GDB/MI Support Commands::) can be used
+to check this.
-`st_dev'
- A value of 0 represents a file, 1 the console.
+Example
+.......
-`st_ino'
- No valid meaning for the target. Transmitted unchanged.
+Resetting the visualizer:
-`st_mode'
- Valid mode bits are described in *Note Constants::. Any other
- bits have currently no meaning for the target.
+ (gdb)
+ -var-set-visualizer V None
+ ^done
-`st_uid'
-`st_gid'
-`st_rdev'
- No valid meaning for the target. Transmitted unchanged.
+ Reselecting the default (type-based) visualizer:
-`st_atime'
-`st_mtime'
-`st_ctime'
- These values have a host and file system dependent accuracy.
- Especially on Windows hosts, the file system may not support exact
- timing values.
+ (gdb)
+ -var-set-visualizer V gdb.default_visualizer
+ ^done
- The target gets a `struct stat' of the above representation and is
-responsible for coercing it to the target representation before
-continuing.
+ Suppose 'SomeClass' is a visualizer class. A lambda expression can
+be used to instantiate this class for a varobj:
- Note that due to size differences between the host, target, and
-protocol representations of `struct stat' members, these members could
-eventually get truncated on the target.
+ (gdb)
+ -var-set-visualizer V "lambda val: SomeClass()"
+ ^done
\1f
-File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
+File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
+
+27.16 GDB/MI Data Manipulation
+==============================
+
+This section describes the GDB/MI commands that manipulate data: examine
+memory and registers, evaluate expressions, etc.
+
+The '-data-disassemble' Command
+-------------------------------
+
+Synopsis
+........
+
+ -data-disassemble
+ [ -s START-ADDR -e END-ADDR ]
+ | [ -f FILENAME -l LINENUM [ -n LINES ] ]
+ -- MODE
+
+Where:
+
+'START-ADDR'
+ is the beginning address (or '$pc')
+'END-ADDR'
+ is the end address
+'FILENAME'
+ is the name of the file to disassemble
+'LINENUM'
+ is the line number to disassemble around
+'LINES'
+ is the number of disassembly lines to be produced. If it is -1,
+ the whole function will be disassembled, in case no END-ADDR is
+ specified. If END-ADDR is specified as a non-zero value, and LINES
+ is lower than the number of disassembly lines between START-ADDR
+ and END-ADDR, only LINES lines are displayed; if LINES is higher
+ than the number of lines between START-ADDR and END-ADDR, only the
+ lines up to END-ADDR are displayed.
+'MODE'
+ is either 0 (meaning only disassembly), 1 (meaning mixed source and
+ disassembly), 2 (meaning disassembly with raw opcodes), or 3
+ (meaning mixed source and disassembly with raw opcodes).
+
+Result
+......
-struct timeval
-..............
+The result of the '-data-disassemble' command will be a list named
+'asm_insns', the contents of this list depend on the MODE used with the
+'-data-disassemble' command.
-The buffer of type `struct timeval' used by the File-I/O protocol is
-defined as follows:
+ For modes 0 and 2 the 'asm_insns' list contains tuples with the
+following fields:
- struct timeval {
- time_t tv_sec; /* second */
- long tv_usec; /* microsecond */
- };
+'address'
+ The address at which this instruction was disassembled.
- The integral datatypes conform to the definitions given in the
-appropriate section (see *Note Integral Datatypes::, for details) so
-this structure is of size 8 bytes.
+'func-name'
+ The name of the function this instruction is within.
-\1f
-File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
+'offset'
+ The decimal offset in bytes from the start of 'func-name'.
-E.13.9 Constants
-----------------
+'inst'
+ The text disassembly for this 'address'.
-The following values are used for the constants inside of the protocol.
-GDB and target are responsible for translating these values before and
-after the call as needed.
+'opcodes'
+ This field is only present for mode 2. This contains the raw
+ opcode bytes for the 'inst' field.
-* Menu:
+ For modes 1 and 3 the 'asm_insns' list contains tuples named
+'src_and_asm_line', each of which has the following fields:
-* Open Flags::
-* mode_t Values::
-* Errno Values::
-* Lseek Flags::
-* Limits::
+'line'
+ The line number within 'file'.
-\1f
-File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
+'file'
+ The file name from the compilation unit. This might be an absolute
+ file name or a relative file name depending on the compile command
+ used.
-Open Flags
-..........
+'fullname'
+ Absolute file name of 'file'. It is converted to a canonical form
+ using the source file search path (*note Specifying Source
+ Directories: Source Path.) and after resolving all the symbolic
+ links.
-All values are given in hexadecimal representation.
+ If the source file is not found this field will contain the path as
+ present in the debug information.
- O_RDONLY 0x0
- O_WRONLY 0x1
- O_RDWR 0x2
- O_APPEND 0x8
- O_CREAT 0x200
- O_TRUNC 0x400
- O_EXCL 0x800
+'line_asm_insn'
+ This is a list of tuples containing the disassembly for 'line' in
+ 'file'. The fields of each tuple are the same as for
+ '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name',
+ 'offset', 'inst', and optionally 'opcodes'.
-\1f
-File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
+ Note that whatever included in the 'inst' field, is not manipulated
+directly by GDB/MI, i.e., it is not possible to adjust its format.
-mode_t Values
-.............
+GDB Command
+...........
-All values are given in octal representation.
+The corresponding GDB command is 'disassemble'.
+
+Example
+.......
+
+Disassemble from the current value of '$pc' to '$pc + 20':
+
+ (gdb)
+ -data-disassemble -s $pc -e "$pc + 20" -- 0
+ ^done,
+ asm_insns=[
+ {address="0x000107c0",func-name="main",offset="4",
+ inst="mov 2, %o0"},
+ {address="0x000107c4",func-name="main",offset="8",
+ inst="sethi %hi(0x11800), %o2"},
+ {address="0x000107c8",func-name="main",offset="12",
+ inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
+ {address="0x000107cc",func-name="main",offset="16",
+ inst="sethi %hi(0x11800), %o2"},
+ {address="0x000107d0",func-name="main",offset="20",
+ inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
+ (gdb)
+
+ Disassemble the whole 'main' function. Line 32 is part of 'main'.
+
+ -data-disassemble -f basics.c -l 32 -- 0
+ ^done,asm_insns=[
+ {address="0x000107bc",func-name="main",offset="0",
+ inst="save %sp, -112, %sp"},
+ {address="0x000107c0",func-name="main",offset="4",
+ inst="mov 2, %o0"},
+ {address="0x000107c4",func-name="main",offset="8",
+ inst="sethi %hi(0x11800), %o2"},
+ [...]
+ {address="0x0001081c",func-name="main",offset="96",inst="ret "},
+ {address="0x00010820",func-name="main",offset="100",inst="restore "}]
+ (gdb)
+
+ Disassemble 3 instructions from the start of 'main':
+
+ (gdb)
+ -data-disassemble -f basics.c -l 32 -n 3 -- 0
+ ^done,asm_insns=[
+ {address="0x000107bc",func-name="main",offset="0",
+ inst="save %sp, -112, %sp"},
+ {address="0x000107c0",func-name="main",offset="4",
+ inst="mov 2, %o0"},
+ {address="0x000107c4",func-name="main",offset="8",
+ inst="sethi %hi(0x11800), %o2"}]
+ (gdb)
+
+ Disassemble 3 instructions from the start of 'main' in mixed mode:
+
+ (gdb)
+ -data-disassemble -f basics.c -l 32 -n 3 -- 1
+ ^done,asm_insns=[
+ src_and_asm_line={line="31",
+ file="../../../src/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
+ line_asm_insn=[{address="0x000107bc",
+ func-name="main",offset="0",inst="save %sp, -112, %sp"}]},
+ src_and_asm_line={line="32",
+ file="../../../src/gdb/testsuite/gdb.mi/basics.c",
+ fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
+ line_asm_insn=[{address="0x000107c0",
+ func-name="main",offset="4",inst="mov 2, %o0"},
+ {address="0x000107c4",func-name="main",offset="8",
+ inst="sethi %hi(0x11800), %o2"}]}]
+ (gdb)
+
+The '-data-evaluate-expression' Command
+---------------------------------------
- S_IFREG 0100000
- S_IFDIR 040000
- S_IRUSR 0400
- S_IWUSR 0200
- S_IXUSR 0100
- S_IRGRP 040
- S_IWGRP 020
- S_IXGRP 010
- S_IROTH 04
- S_IWOTH 02
- S_IXOTH 01
+Synopsis
+........
-\1f
-File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
-
-Errno Values
-............
-
-All values are given in decimal representation.
-
- EPERM 1
- ENOENT 2
- EINTR 4
- EBADF 9
- EACCES 13
- EFAULT 14
- EBUSY 16
- EEXIST 17
- ENODEV 19
- ENOTDIR 20
- EISDIR 21
- EINVAL 22
- ENFILE 23
- EMFILE 24
- EFBIG 27
- ENOSPC 28
- ESPIPE 29
- EROFS 30
- ENAMETOOLONG 91
- EUNKNOWN 9999
-
- `EUNKNOWN' is used as a fallback error value if a host system returns
- any error value not in the list of supported error numbers.
+ -data-evaluate-expression EXPR
-\1f
-File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
+ Evaluate EXPR as an expression. The expression could contain an
+inferior function call. The function call will execute synchronously.
+If the expression contains spaces, it must be enclosed in double quotes.
-Lseek Flags
+GDB Command
...........
- SEEK_SET 0
- SEEK_CUR 1
- SEEK_END 2
+The corresponding GDB commands are 'print', 'output', and 'call'. In
+'gdbtk' only, there's a corresponding 'gdb_eval' command.
-\1f
-File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
+Example
+.......
-Limits
-......
+In the following example, the numbers that precede the commands are the
+"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command
+Syntax. Notice how GDB/MI returns the same tokens in its output.
-All values are given in decimal representation.
+ 211-data-evaluate-expression A
+ 211^done,value="1"
+ (gdb)
+ 311-data-evaluate-expression &A
+ 311^done,value="0xefffeb7c"
+ (gdb)
+ 411-data-evaluate-expression A+3
+ 411^done,value="4"
+ (gdb)
+ 511-data-evaluate-expression "A + 3"
+ 511^done,value="4"
+ (gdb)
- INT_MIN -2147483648
- INT_MAX 2147483647
- UINT_MAX 4294967295
- LONG_MIN -9223372036854775808
- LONG_MAX 9223372036854775807
- ULONG_MAX 18446744073709551615
+The '-data-list-changed-registers' Command
+------------------------------------------
-\1f
-File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
+Synopsis
+........
-E.13.10 File-I/O Examples
--------------------------
+ -data-list-changed-registers
-Example sequence of a write call, file descriptor 3, buffer is at target
-address 0x1234, 6 bytes should be written:
+ Display a list of the registers that have changed.
- <- `Fwrite,3,1234,6'
- _request memory read from target_
- -> `m1234,6'
- <- XXXXXX
- _return "6 bytes written"_
- -> `F6'
+GDB Command
+...........
- Example sequence of a read call, file descriptor 3, buffer is at
-target address 0x1234, 6 bytes should be read:
+GDB doesn't have a direct analog for this command; 'gdbtk' has the
+corresponding command 'gdb_changed_register_list'.
- <- `Fread,3,1234,6'
- _request memory write to target_
- -> `X1234,6:XXXXXX'
- _return "6 bytes read"_
- -> `F6'
+Example
+.......
- Example sequence of a read call, call fails on the host due to
-invalid file descriptor (`EBADF'):
+On a PPC MBX board:
- <- `Fread,3,1234,6'
- -> `F-1,9'
+ (gdb)
+ -exec-continue
+ ^running
- Example sequence of a read call, user presses `Ctrl-c' before
-syscall on host is called:
+ (gdb)
+ *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={
+ func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
+ line="5"}
+ (gdb)
+ -data-list-changed-registers
+ ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
+ "10","11","13","14","15","16","17","18","19","20","21","22","23",
+ "24","25","26","27","28","30","31","64","65","66","67","69"]
+ (gdb)
- <- `Fread,3,1234,6'
- -> `F-1,4,C'
- <- `T02'
+The '-data-list-register-names' Command
+---------------------------------------
- Example sequence of a read call, user presses `Ctrl-c' after syscall
-on host is called:
+Synopsis
+........
- <- `Fread,3,1234,6'
- -> `X1234,6:XXXXXX'
- <- `T02'
+ -data-list-register-names [ ( REGNO )+ ]
-\1f
-File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
+ Show a list of register names for the current target. If no
+arguments are given, it shows a list of the names of all the registers.
+If integer numbers are given as arguments, it will print a list of the
+names of the registers corresponding to the arguments. To ensure
+consistency between a register name and its number, the output list may
+include empty register names.
-E.14 Library List Format
-========================
+GDB Command
+...........
-On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
-process as your application to manage libraries. In this case, GDB can
-use the loader's symbol table and normal memory operations to maintain
-a list of shared libraries. On other platforms, the operating system
-manages loaded libraries. GDB can not retrieve the list of currently
-loaded libraries through memory operations, so it uses the
-`qXfer:libraries:read' packet (*note qXfer library list read::)
-instead. The remote stub queries the target's operating system and
-reports which libraries are loaded.
-
- The `qXfer:libraries:read' packet returns an XML document which
-lists loaded libraries and their offsets. Each library has an
-associated name and one or more segment or section base addresses,
-which report where the library was loaded in memory.
-
- For the common case of libraries that are fully linked binaries, the
-library should have a list of segments. If the target supports dynamic
-linking of a relocatable object file, its library XML element should
-instead include a list of allocated sections. The segment or section
-bases are start addresses, not relocation offsets; they do not depend
-on the library's link-time base addresses.
-
- GDB must be linked with the Expat library to support XML library
-lists. *Note Expat::.
-
- A simple memory map, with one loaded library relocated by a single
-offset, looks like this:
-
- <library-list>
- <library name="/lib/libc.so.6">
- <segment address="0x10000000"/>
- </library>
- </library-list>
-
- Another simple memory map, with one loaded library with three
-allocated sections (.text, .data, .bss), looks like this:
-
- <library-list>
- <library name="sharedlib.o">
- <section address="0x10000000"/>
- <section address="0x20000000"/>
- <section address="0x30000000"/>
- </library>
- </library-list>
-
- The format of a library list is described by this DTD:
-
- <!-- library-list: Root element with versioning -->
- <!ELEMENT library-list (library)*>
- <!ATTLIST library-list version CDATA #FIXED "1.0">
- <!ELEMENT library (segment*, section*)>
- <!ATTLIST library name CDATA #REQUIRED>
- <!ELEMENT segment EMPTY>
- <!ATTLIST segment address CDATA #REQUIRED>
- <!ELEMENT section EMPTY>
- <!ATTLIST section address CDATA #REQUIRED>
-
- In addition, segments and section descriptors cannot be mixed within
-a single library element, and you must supply at least one segment or
-section for each library.
+GDB does not have a command which corresponds to
+'-data-list-register-names'. In 'gdbtk' there is a corresponding
+command 'gdb_regnames'.
+
+Example
+.......
+
+For the PPC MBX board:
+ (gdb)
+ -data-list-register-names
+ ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
+ "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
+ "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
+ "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
+ "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
+ "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
+ "", "pc","ps","cr","lr","ctr","xer"]
+ (gdb)
+ -data-list-register-names 1 2 3
+ ^done,register-names=["r1","r2","r3"]
+ (gdb)
+
+The '-data-list-register-values' Command
+----------------------------------------
+
+Synopsis
+........
+
+ -data-list-register-values
+ [ --skip-unavailable ] FMT [ ( REGNO )*]
+
+ Display the registers' contents. The format according to which the
+registers' contents are to be returned is given by FMT, followed by an
+optional list of numbers specifying the registers to display. A missing
+list of numbers indicates that the contents of all the registers must be
+returned. The '--skip-unavailable' option indicates that only the
+available registers are to be returned.
+
+ Allowed formats for FMT are:
+
+'x'
+ Hexadecimal
+'o'
+ Octal
+'t'
+ Binary
+'d'
+ Decimal
+'r'
+ Raw
+'N'
+ Natural
+
+GDB Command
+...........
-\1f
-File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
+The corresponding GDB commands are 'info reg', 'info all-reg', and (in
+'gdbtk') 'gdb_fetch_registers'.
+
+Example
+.......
+
+For a PPC MBX board (note: line breaks are for readability only, they
+don't appear in the actual output):
+
+ (gdb)
+ -data-list-register-values r 64 65
+ ^done,register-values=[{number="64",value="0xfe00a300"},
+ {number="65",value="0x00029002"}]
+ (gdb)
+ -data-list-register-values x
+ ^done,register-values=[{number="0",value="0xfe0043c8"},
+ {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
+ {number="3",value="0x0"},{number="4",value="0xa"},
+ {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
+ {number="7",value="0xfe011e98"},{number="8",value="0x2"},
+ {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
+ {number="11",value="0x1"},{number="12",value="0x0"},
+ {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
+ {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
+ {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
+ {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
+ {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
+ {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
+ {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
+ {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
+ {number="29",value="0x0"},{number="30",value="0xfe010000"},
+ {number="31",value="0x0"},{number="32",value="0x0"},
+ {number="33",value="0x0"},{number="34",value="0x0"},
+ {number="35",value="0x0"},{number="36",value="0x0"},
+ {number="37",value="0x0"},{number="38",value="0x0"},
+ {number="39",value="0x0"},{number="40",value="0x0"},
+ {number="41",value="0x0"},{number="42",value="0x0"},
+ {number="43",value="0x0"},{number="44",value="0x0"},
+ {number="45",value="0x0"},{number="46",value="0x0"},
+ {number="47",value="0x0"},{number="48",value="0x0"},
+ {number="49",value="0x0"},{number="50",value="0x0"},
+ {number="51",value="0x0"},{number="52",value="0x0"},
+ {number="53",value="0x0"},{number="54",value="0x0"},
+ {number="55",value="0x0"},{number="56",value="0x0"},
+ {number="57",value="0x0"},{number="58",value="0x0"},
+ {number="59",value="0x0"},{number="60",value="0x0"},
+ {number="61",value="0x0"},{number="62",value="0x0"},
+ {number="63",value="0x0"},{number="64",value="0xfe00a300"},
+ {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
+ {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
+ {number="69",value="0x20002b03"}]
+ (gdb)
+
+The '-data-read-memory' Command
+-------------------------------
+
+This command is deprecated, use '-data-read-memory-bytes' instead.
+
+Synopsis
+........
+
+ -data-read-memory [ -o BYTE-OFFSET ]
+ ADDRESS WORD-FORMAT WORD-SIZE
+ NR-ROWS NR-COLS [ ASCHAR ]
+
+where:
+
+'ADDRESS'
+ An expression specifying the address of the first memory word to be
+ read. Complex expressions containing embedded white space should
+ be quoted using the C convention.
+
+'WORD-FORMAT'
+ The format to be used to print the memory words. The notation is
+ the same as for GDB's 'print' command (*note Output Formats: Output
+ Formats.).
+
+'WORD-SIZE'
+ The size of each memory word in bytes.
+
+'NR-ROWS'
+ The number of rows in the output table.
+
+'NR-COLS'
+ The number of columns in the output table.
+
+'ASCHAR'
+ If present, indicates that each row should include an ASCII dump.
+ The value of ASCHAR is used as a padding character when a byte is
+ not a member of the printable ASCII character set (printable ASCII
+ characters are those whose code is between 32 and 126,
+ inclusively).
+
+'BYTE-OFFSET'
+ An offset to add to the ADDRESS before fetching memory.
+
+ This command displays memory contents as a table of NR-ROWS by
+NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS *
+NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should
+less than the requested number of bytes be returned by the target, the
+missing words are identified using 'N/A'. The number of bytes read from
+the target is returned in 'nr-bytes' and the starting address used to
+read memory in 'addr'.
+
+ The address of the next/previous row or page is available in
+'next-row' and 'prev-row', 'next-page' and 'prev-page'.
+
+GDB Command
+...........
-E.15 Library List Format for SVR4 Targets
-=========================================
+The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory
+read command.
+
+Example
+.......
+
+Read six bytes of memory starting at 'bytes+6' but then offset by '-6'
+bytes. Format as three rows of two columns. One byte per word.
+Display each word in hex.
+
+ (gdb)
+ 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
+ 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
+ next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
+ prev-page="0x0000138a",memory=[
+ {addr="0x00001390",data=["0x00","0x01"]},
+ {addr="0x00001392",data=["0x02","0x03"]},
+ {addr="0x00001394",data=["0x04","0x05"]}]
+ (gdb)
+
+ Read two bytes of memory starting at address 'shorts + 64' and
+display as a single word formatted in decimal.
+
+ (gdb)
+ 5-data-read-memory shorts+64 d 2 1 1
+ 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
+ next-row="0x00001512",prev-row="0x0000150e",
+ next-page="0x00001512",prev-page="0x0000150e",memory=[
+ {addr="0x00001510",data=["128"]}]
+ (gdb)
+
+ Read thirty two bytes of memory starting at 'bytes+16' and format as
+eight rows of four columns. Include a string encoding with 'x' used as
+the non-printable character.
+
+ (gdb)
+ 4-data-read-memory bytes+16 x 1 8 4 x
+ 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
+ next-row="0x000013c0",prev-row="0x0000139c",
+ next-page="0x000013c0",prev-page="0x00001380",memory=[
+ {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
+ {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
+ {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
+ {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
+ {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
+ {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
+ {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
+ {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
+ (gdb)
+
+The '-data-read-memory-bytes' Command
+-------------------------------------
+
+Synopsis
+........
+
+ -data-read-memory-bytes [ -o BYTE-OFFSET ]
+ ADDRESS COUNT
+
+where:
+
+'ADDRESS'
+ An expression specifying the address of the first memory word to be
+ read. Complex expressions containing embedded white space should
+ be quoted using the C convention.
+
+'COUNT'
+ The number of bytes to read. This should be an integer literal.
+
+'BYTE-OFFSET'
+ The offsets in bytes relative to ADDRESS at which to start reading.
+ This should be an integer literal. This option is provided so that
+ a frontend is not required to first evaluate address and then
+ perform address arithmetics itself.
+
+ This command attempts to read all accessible memory regions in the
+specified range. First, all regions marked as unreadable in the memory
+map (if one is defined) will be skipped. *Note Memory Region
+Attributes::. Second, GDB will attempt to read the remaining regions.
+For each one, if reading full region results in an errors, GDB will try
+to read a subset of the region.
+
+ In general, every single byte in the region may be readable or not,
+and the only way to read every readable byte is to try a read at every
+address, which is not practical. Therefore, GDB will attempt to read
+all accessible bytes at either beginning or the end of the region, using
+a binary division scheme. This heuristic works well for reading accross
+a memory map boundary. Note that if a region has a readable range that
+is neither at the beginning or the end, GDB will not read it.
+
+ The result record (*note GDB/MI Result Records::) that is output of
+the command includes a field named 'memory' whose content is a list of
+tuples. Each tuple represent a successfully read memory block and has
+the following fields:
+
+'begin'
+ The start address of the memory block, as hexadecimal literal.
+
+'end'
+ The end address of the memory block, as hexadecimal literal.
+
+'offset'
+ The offset of the memory block, as hexadecimal literal, relative to
+ the start address passed to '-data-read-memory-bytes'.
+
+'contents'
+ The contents of the memory block, in hex.
+
+GDB Command
+...........
-On SVR4 platforms GDB can use the symbol table of a dynamic loader
-(e.g. `ld.so') and normal memory operations to maintain a list of
-shared libraries. Still a special library list provided by this packet
-is more efficient for the GDB remote protocol.
+The corresponding GDB command is 'x'.
- The `qXfer:libraries-svr4:read' packet returns an XML document which
-lists loaded libraries and their SVR4 linker parameters. For each
-library on SVR4 target, the following parameters are reported:
+Example
+.......
- - `name', the absolute file name from the `l_name' field of `struct
- link_map'.
+ (gdb)
+ -data-read-memory-bytes &a 10
+ ^done,memory=[{begin="0xbffff154",offset="0x00000000",
+ end="0xbffff15e",
+ contents="01000000020000000300"}]
+ (gdb)
- - `lm' with address of `struct link_map' used for TLS (Thread Local
- Storage) access.
+The '-data-write-memory-bytes' Command
+--------------------------------------
- - `l_addr', the displacement as read from the field `l_addr' of
- `struct link_map'. For prelinked libraries this is not an absolute
- memory address. It is a displacement of absolute memory address
- against address the file was prelinked to during the library load.
+Synopsis
+........
- - `l_ld', which is memory address of the `PT_DYNAMIC' segment
+ -data-write-memory-bytes ADDRESS CONTENTS
+ -data-write-memory-bytes ADDRESS CONTENTS [COUNT]
- Additionally the single `main-lm' attribute specifies address of
-`struct link_map' used for the main executable. This parameter is used
-for TLS access and its presence is optional.
+where:
- GDB must be linked with the Expat library to support XML SVR4
-library lists. *Note Expat::.
+'ADDRESS'
+ An expression specifying the address of the first memory word to be
+ read. Complex expressions containing embedded white space should
+ be quoted using the C convention.
- A simple memory map, with two loaded libraries (which do not use
-prelink), looks like this:
+'CONTENTS'
+ The hex-encoded bytes to write.
- <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
- <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
- l_ld="0xe4eefc"/>
- <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
- l_ld="0x152350"/>
- </library-list-svr>
+'COUNT'
+ Optional argument indicating the number of bytes to be written. If
+ COUNT is greater than CONTENTS' length, GDB will repeatedly write
+ CONTENTS until it fills COUNT bytes.
- The format of an SVR4 library list is described by this DTD:
+GDB Command
+...........
- <!-- library-list-svr4: Root element with versioning -->
- <!ELEMENT library-list-svr4 (library)*>
- <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
- <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
- <!ELEMENT library EMPTY>
- <!ATTLIST library name CDATA #REQUIRED>
- <!ATTLIST library lm CDATA #REQUIRED>
- <!ATTLIST library l_addr CDATA #REQUIRED>
- <!ATTLIST library l_ld CDATA #REQUIRED>
+There's no corresponding GDB command.
-\1f
-File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol
+Example
+.......
-E.16 Memory Map Format
-======================
+ (gdb)
+ -data-write-memory-bytes &a "aabbccdd"
+ ^done
+ (gdb)
-To be able to write into flash memory, GDB needs to obtain a memory map
-from the target. This section describes the format of the memory map.
+ (gdb)
+ -data-write-memory-bytes &a "aabbccdd" 16e
+ ^done
+ (gdb)
- The memory map is obtained using the `qXfer:memory-map:read' (*note
-qXfer memory map read::) packet and is an XML document that lists
-memory regions.
+\1f
+File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
- GDB must be linked with the Expat library to support XML memory
-maps. *Note Expat::.
+27.17 GDB/MI Tracepoint Commands
+================================
- The top-level structure of the document is shown below:
+The commands defined in this section implement MI support for
+tracepoints. For detailed introduction, see *note Tracepoints::.
- <?xml version="1.0"?>
- <!DOCTYPE memory-map
- PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
- "http://sourceware.org/gdb/gdb-memory-map.dtd">
- <memory-map>
- region...
- </memory-map>
+The '-trace-find' Command
+-------------------------
- Each region can be either:
+Synopsis
+........
- * A region of RAM starting at ADDR and extending for LENGTH bytes
- from there:
+ -trace-find MODE [PARAMETERS...]
- <memory type="ram" start="ADDR" length="LENGTH"/>
+ Find a trace frame using criteria defined by MODE and PARAMETERS.
+The following table lists permissible modes and their parameters. For
+details of operation, see *note tfind::.
- * A region of read-only memory:
+'none'
+ No parameters are required. Stops examining trace frames.
- <memory type="rom" start="ADDR" length="LENGTH"/>
+'frame-number'
+ An integer is required as parameter. Selects tracepoint frame with
+ that index.
- * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
- length:
+'tracepoint-number'
+ An integer is required as parameter. Finds next trace frame that
+ corresponds to tracepoint with the specified number.
- <memory type="flash" start="ADDR" length="LENGTH">
- <property name="blocksize">BLOCKSIZE</property>
- </memory>
+'pc'
+ An address is required as parameter. Finds next trace frame that
+ corresponds to any tracepoint at the specified address.
+'pc-inside-range'
+ Two addresses are required as parameters. Finds next trace frame
+ that corresponds to a tracepoint at an address inside the specified
+ range. Both bounds are considered to be inside the range.
- Regions must not overlap. GDB assumes that areas of memory not
-covered by the memory map are RAM, and uses the ordinary `M' and `X'
-packets to write to addresses in such ranges.
+'pc-outside-range'
+ Two addresses are required as parameters. Finds next trace frame
+ that corresponds to a tracepoint at an address outside the
+ specified range. Both bounds are considered to be inside the
+ range.
- The formal DTD for memory map format is given below:
+'line'
+ Line specification is required as parameter. *Note Specify
+ Location::. Finds next trace frame that corresponds to a
+ tracepoint at the specified location.
- <!-- ................................................... -->
- <!-- Memory Map XML DTD ................................ -->
- <!-- File: memory-map.dtd .............................. -->
- <!-- .................................... .............. -->
- <!-- memory-map.dtd -->
- <!-- memory-map: Root element with versioning -->
- <!ELEMENT memory-map (memory | property)>
- <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
- <!ELEMENT memory (property)>
- <!-- memory: Specifies a memory region,
- and its type, or device. -->
- <!ATTLIST memory type CDATA #REQUIRED
- start CDATA #REQUIRED
- length CDATA #REQUIRED
- device CDATA #IMPLIED>
- <!-- property: Generic attribute tag -->
- <!ELEMENT property (#PCDATA | property)*>
- <!ATTLIST property name CDATA #REQUIRED>
+ If 'none' was passed as MODE, the response does not have fields.
+Otherwise, the response may have the following fields:
-\1f
-File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol
+'found'
+ This field has either '0' or '1' as the value, depending on whether
+ a matching tracepoint was found.
-E.17 Thread List Format
-=======================
+'traceframe'
+ The index of the found traceframe. This field is present iff the
+ 'found' field has value of '1'.
-To efficiently update the list of threads and their attributes, GDB
-issues the `qXfer:threads:read' packet (*note qXfer threads read::) and
-obtains the XML document with the following structure:
+'tracepoint'
+ The index of the found tracepoint. This field is present iff the
+ 'found' field has value of '1'.
- <?xml version="1.0"?>
- <threads>
- <thread id="id" core="0">
- ... description ...
- </thread>
- </threads>
+'frame'
+ The information about the frame corresponding to the found trace
+ frame. This field is present only if a trace frame was found.
+ *Note GDB/MI Frame Information::, for description of this field.
- Each `thread' element must have the `id' attribute that identifies
-the thread (*note thread-id syntax::). The `core' attribute, if
-present, specifies which processor core the thread was last executing
-on. The content of the of `thread' element is interpreted as
-human-readable auxilliary information.
+GDB Command
+...........
-\1f
-File: gdb.info, Node: Traceframe Info Format, Prev: Thread List Format, Up: Remote Protocol
+The corresponding GDB command is 'tfind'.
-E.18 Traceframe Info Format
-===========================
+-trace-define-variable
+----------------------
-To be able to know which objects in the inferior can be examined when
-inspecting a tracepoint hit, GDB needs to obtain the list of memory
-ranges, registers and trace state variables that have been collected in
-a traceframe.
+Synopsis
+........
- This list is obtained using the `qXfer:traceframe-info:read' (*note
-qXfer traceframe info read::) packet and is an XML document.
+ -trace-define-variable NAME [ VALUE ]
- GDB must be linked with the Expat library to support XML traceframe
-info discovery. *Note Expat::.
+ Create trace variable NAME if it does not exist. If VALUE is
+specified, sets the initial value of the specified trace variable to
+that value. Note that the NAME should start with the '$' character.
- The top-level structure of the document is shown below:
+GDB Command
+...........
- <?xml version="1.0"?>
- <!DOCTYPE traceframe-info
- PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
- "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
- <traceframe-info>
- block...
- </traceframe-info>
+The corresponding GDB command is 'tvariable'.
- Each traceframe block can be either:
+The '-trace-frame-collected' Command
+------------------------------------
- * A region of collected memory starting at ADDR and extending for
- LENGTH bytes from there:
+Synopsis
+........
+
+ -trace-frame-collected
+ [--var-print-values VAR_PVAL]
+ [--comp-print-values COMP_PVAL]
+ [--registers-format REGFORMAT]
+ [--memory-contents]
+
+ This command returns the set of collected objects, register names,
+trace state variable names, memory ranges and computed expressions that
+have been collected at a particular trace frame. The optional
+parameters to the command affect the output format in different ways.
+See the output description table below for more details.
+
+ The reported names can be used in the normal manner to create varobjs
+and inspect the objects themselves. The items returned by this command
+are categorized so that it is clear which is a variable, which is a
+register, which is a trace state variable, which is a memory range and
+which is a computed expression.
+
+ For instance, if the actions were
+ collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
+ collect *(int*)0xaf02bef0@40
+
+the object collected in its entirety would be 'myVar'. The object
+'myArray' would be partially collected, because only the element at
+index 'myIndex' would be collected. The remaining objects would be
+computed expressions.
+
+ An example output would be:
+
+ (gdb)
+ -trace-frame-collected
+ ^done,
+ explicit-variables=[{name="myVar",value="1"}],
+ computed-expressions=[{name="myArray[myIndex]",value="0"},
+ {name="myObj.field",value="0"},
+ {name="myPtr->field",value="1"},
+ {name="myCount + 2",value="3"},
+ {name="$tvar1 + 1",value="43970027"}],
+ registers=[{number="0",value="0x7fe2c6e79ec8"},
+ {number="1",value="0x0"},
+ {number="2",value="0x4"},
+ ...
+ {number="125",value="0x0"}],
+ tvars=[{name="$tvar1",current="43970026"}],
+ memory=[{address="0x0000000000602264",length="4"},
+ {address="0x0000000000615bc0",length="4"}]
+ (gdb)
+
+ Where:
+
+'explicit-variables'
+ The set of objects that have been collected in their entirety (as
+ opposed to collecting just a few elements of an array or a few
+ struct members). For each object, its name and value are printed.
+ The '--var-print-values' option affects how or whether the value
+ field is output. If VAR_PVAL is 0, then print only the names; if
+ it is 1, print also their values; and if it is 2, print the name,
+ type and value for simple data types, and the name and type for
+ arrays, structures and unions.
+
+'computed-expressions'
+ The set of computed expressions that have been collected at the
+ current trace frame. The '--comp-print-values' option affects this
+ set like the '--var-print-values' option affects the
+ 'explicit-variables' set. See above.
+
+'registers'
+ The registers that have been collected at the current trace frame.
+ For each register collected, the name and current value are
+ returned. The value is formatted according to the
+ '--registers-format' option. See the '-data-list-register-values'
+ command for a list of the allowed formats. The default is 'x'.
+
+'tvars'
+ The trace state variables that have been collected at the current
+ trace frame. For each trace state variable collected, the name and
+ current value are returned.
+
+'memory'
+ The set of memory ranges that have been collected at the current
+ trace frame. Its content is a list of tuples. Each tuple
+ represents a collected memory range and has the following fields:
+
+ 'address'
+ The start address of the memory range, as hexadecimal literal.
+
+ 'length'
+ The length of the memory range, as decimal literal.
+
+ 'contents'
+ The contents of the memory block, in hex. This field is only
+ present if the '--memory-contents' option is specified.
+
+GDB Command
+...........
- <memory start="ADDR" length="LENGTH"/>
+There is no corresponding GDB command.
+Example
+.......
- The formal DTD for the traceframe info format is given below:
+-trace-list-variables
+---------------------
- <!ELEMENT traceframe-info (memory)* >
- <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
+Synopsis
+........
- <!ELEMENT memory EMPTY>
- <!ATTLIST memory start CDATA #REQUIRED
- length CDATA #REQUIRED>
+ -trace-list-variables
-\1f
-File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
+ Return a table of all defined trace variables. Each element of the
+table has the following fields:
-Appendix F The GDB Agent Expression Mechanism
-*********************************************
+'name'
+ The name of the trace variable. This field is always present.
-In some applications, it is not feasible for the debugger to interrupt
-the program's execution long enough for the developer to learn anything
-helpful about its behavior. If the program's correctness depends on its
-real-time behavior, delays introduced by a debugger might cause the
-program to fail, even when the code itself is correct. It is useful to
-be able to observe the program's behavior without interrupting it.
+'initial'
+ The initial value. This is a 64-bit signed integer. This field is
+ always present.
- Using GDB's `trace' and `collect' commands, the user can specify
-locations in the program, and arbitrary expressions to evaluate when
-those locations are reached. Later, using the `tfind' command, she can
-examine the values those expressions had when the program hit the trace
-points. The expressions may also denote objects in memory --
-structures or arrays, for example -- whose values GDB should record;
-while visiting a particular tracepoint, the user may inspect those
-objects as if they were in memory at that moment. However, because GDB
-records these values without interacting with the user, it can do so
-quickly and unobtrusively, hopefully not disturbing the program's
-behavior.
-
- When GDB is debugging a remote target, the GDB "agent" code running
-on the target computes the values of the expressions itself. To avoid
-having a full symbolic expression evaluator on the agent, GDB translates
-expressions in the source language into a simpler bytecode language, and
-then sends the bytecode to the agent; the agent then executes the
-bytecode, and records the values for GDB to retrieve later.
-
- The bytecode language is simple; there are forty-odd opcodes, the
-bulk of which are the usual vocabulary of C operands (addition,
-subtraction, shifts, and so on) and various sizes of literals and
-memory reference operations. The bytecode interpreter operates
-strictly on machine-level values -- various sizes of integers and
-floating point numbers -- and requires no information about types or
-symbols; thus, the interpreter's internal data structures are simple,
-and each bytecode requires only a few native machine instructions to
-implement it. The interpreter is small, and strict limits on the
-memory and time required to evaluate an expression are easy to
-determine, making it suitable for use by the debugging agent in
-real-time applications.
+'current'
+ The value the trace variable has at the moment. This is a 64-bit
+ signed integer. This field is absent iff current value is not
+ defined, for example if the trace was never run, or is presently
+ running.
-* Menu:
+GDB Command
+...........
-* General Bytecode Design:: Overview of the interpreter.
-* Bytecode Descriptions:: What each one does.
-* Using Agent Expressions:: How agent expressions fit into the big picture.
-* Varying Target Capabilities:: How to discover what the target can do.
-* Rationale:: Why we did it this way.
+The corresponding GDB command is 'tvariables'.
-\1f
-File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
+Example
+.......
-F.1 General Bytecode Design
-===========================
+ (gdb)
+ -trace-list-variables
+ ^done,trace-variables={nr_rows="1",nr_cols="3",
+ hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"},
+ {width="11",alignment="-1",col_name="initial",colhdr="Initial"},
+ {width="11",alignment="-1",col_name="current",colhdr="Current"}],
+ body=[variable={name="$trace_timestamp",initial="0"}
+ variable={name="$foo",initial="10",current="15"}]}
+ (gdb)
-The agent represents bytecode expressions as an array of bytes. Each
-instruction is one byte long (thus the term "bytecode"). Some
-instructions are followed by operand bytes; for example, the `goto'
-instruction is followed by a destination for the jump.
-
- The bytecode interpreter is a stack-based machine; most instructions
-pop their operands off the stack, perform some operation, and push the
-result back on the stack for the next instruction to consume. Each
-element of the stack may contain either a integer or a floating point
-value; these values are as many bits wide as the largest integer that
-can be directly manipulated in the source language. Stack elements
-carry no record of their type; bytecode could push a value as an
-integer, then pop it as a floating point value. However, GDB will not
-generate code which does this. In C, one might define the type of a
-stack element as follows:
- union agent_val {
- LONGEST l;
- DOUBLEST d;
- };
- where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
-integer and floating point types on the machine.
-
- By the time the bytecode interpreter reaches the end of the
-expression, the value of the expression should be the only value left
-on the stack. For tracing applications, `trace' bytecodes in the
-expression will have recorded the necessary data, and the value on the
-stack may be discarded. For other applications, like conditional
-breakpoints, the value may be useful.
-
- Separate from the stack, the interpreter has two registers:
-`pc'
- The address of the next bytecode to execute.
-
-`start'
- The address of the start of the bytecode expression, necessary for
- interpreting the `goto' and `if_goto' instructions.
-
- Neither of these registers is directly visible to the bytecode
-language itself, but they are useful for defining the meanings of the
-bytecode operations.
-
- There are no instructions to perform side effects on the running
-program, or call the program's functions; we assume that these
-expressions are only used for unobtrusive debugging, not for patching
-the running code.
-
- Most bytecode instructions do not distinguish between the various
-sizes of values, and operate on full-width values; the upper bits of the
-values are simply ignored, since they do not usually make a difference
-to the value computed. The exceptions to this rule are:
-memory reference instructions (`ref'N)
- There are distinct instructions to fetch different word sizes from
- memory. Once on the stack, however, the values are treated as
- full-size integers. They may need to be sign-extended; the `ext'
- instruction exists for this purpose.
-
-the sign-extension instruction (`ext' N)
- These clearly need to know which portion of their operand is to be
- extended to occupy the full length of the word.
-
-
- If the interpreter is unable to evaluate an expression completely for
-some reason (a memory location is inaccessible, or a divisor is zero,
-for example), we say that interpretation "terminates with an error".
-This means that the problem is reported back to the interpreter's caller
-in some helpful way. In general, code using agent expressions should
-assume that they may attempt to divide by zero, fetch arbitrary memory
-locations, and misbehave in other ways.
-
- Even complicated C expressions compile to a few bytecode
-instructions; for example, the expression `x + y * z' would typically
-produce code like the following, assuming that `x' and `y' live in
-registers, and `z' is a global variable holding a 32-bit `int':
- reg 1
- reg 2
- const32 address of z
- ref32
- ext 32
- mul
- add
- end
-
- In detail, these mean:
-`reg 1'
- Push the value of register 1 (presumably holding `x') onto the
- stack.
-
-`reg 2'
- Push the value of register 2 (holding `y').
-
-`const32 address of z'
- Push the address of `z' onto the stack.
-
-`ref32'
- Fetch a 32-bit word from the address at the top of the stack;
- replace the address on the stack with the value. Thus, we replace
- the address of `z' with `z''s value.
-
-`ext 32'
- Sign-extend the value on the top of the stack from 32 bits to full
- length. This is necessary because `z' is a signed integer.
-
-`mul'
- Pop the top two numbers on the stack, multiply them, and push their
- product. Now the top of the stack contains the value of the
- expression `y * z'.
-
-`add'
- Pop the top two numbers, add them, and push the sum. Now the top
- of the stack contains the value of `x + y * z'.
-
-`end'
- Stop executing; the value left on the stack top is the value to be
- recorded.
+-trace-save
+-----------
+
+Synopsis
+........
+
+ -trace-save [-r ] FILENAME
+
+ Saves the collected trace data to FILENAME. Without the '-r' option,
+the data is downloaded from the target and saved in a local file. With
+the '-r' option the target is asked to perform the save.
+
+GDB Command
+...........
+
+The corresponding GDB command is 'tsave'.
+
+-trace-start
+------------
+
+Synopsis
+........
+
+ -trace-start
+
+ Starts a tracing experiments. The result of this command does not
+have any fields.
+
+GDB Command
+...........
+
+The corresponding GDB command is 'tstart'.
+
+-trace-status
+-------------
+
+Synopsis
+........
+
+ -trace-status
+
+ Obtains the status of a tracing experiment. The result may include
+the following fields:
+
+'supported'
+ May have a value of either '0', when no tracing operations are
+ supported, '1', when all tracing operations are supported, or
+ 'file' when examining trace file. In the latter case, examining of
+ trace frame is possible but new tracing experiement cannot be
+ started. This field is always present.
+
+'running'
+ May have a value of either '0' or '1' depending on whether tracing
+ experiement is in progress on target. This field is present if
+ 'supported' field is not '0'.
+
+'stop-reason'
+ Report the reason why the tracing was stopped last time. This
+ field may be absent iff tracing was never stopped on target yet.
+ The value of 'request' means the tracing was stopped as result of
+ the '-trace-stop' command. The value of 'overflow' means the
+ tracing buffer is full. The value of 'disconnection' means tracing
+ was automatically stopped when GDB has disconnected. The value of
+ 'passcount' means tracing was stopped when a tracepoint was passed
+ a maximal number of times for that tracepoint. This field is
+ present if 'supported' field is not '0'.
+
+'stopping-tracepoint'
+ The number of tracepoint whose passcount as exceeded. This field
+ is present iff the 'stop-reason' field has the value of
+ 'passcount'.
+
+'frames'
+'frames-created'
+ The 'frames' field is a count of the total number of trace frames
+ in the trace buffer, while 'frames-created' is the total created
+ during the run, including ones that were discarded, such as when a
+ circular trace buffer filled up. Both fields are optional.
+
+'buffer-size'
+'buffer-free'
+ These fields tell the current size of the tracing buffer and the
+ remaining space. These fields are optional.
+
+'circular'
+ The value of the circular trace buffer flag. '1' means that the
+ trace buffer is circular and old trace frames will be discarded if
+ necessary to make room, '0' means that the trace buffer is linear
+ and may fill up.
+
+'disconnected'
+ The value of the disconnected tracing flag. '1' means that tracing
+ will continue after GDB disconnects, '0' means that the trace run
+ will stop.
+
+'trace-file'
+ The filename of the trace file being examined. This field is
+ optional, and only present when examining a trace file.
+
+GDB Command
+...........
+
+The corresponding GDB command is 'tstatus'.
+
+-trace-stop
+-----------
+
+Synopsis
+........
+
+ -trace-stop
+
+ Stops a tracing experiment. The result of this command has the same
+fields as '-trace-status', except that the 'supported' and 'running'
+fields are not output.
+GDB Command
+...........
+
+The corresponding GDB command is 'tstop'.
\1f
-File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
+File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
-F.2 Bytecode Descriptions
-=========================
+27.18 GDB/MI Symbol Query Commands
+==================================
+
+The '-symbol-list-lines' Command
+--------------------------------
-Each bytecode description has the following form:
+Synopsis
+........
-`add' (0x02): A B => A+B
- Pop the top two stack items, A and B, as integers; push their sum,
- as an integer.
+ -symbol-list-lines FILENAME
+ Print the list of lines that contain code and their associated
+program addresses for the given source filename. The entries are sorted
+in ascending PC order.
- In this example, `add' is the name of the bytecode, and `(0x02)' is
-the one-byte value used to encode the bytecode, in hexadecimal. The
-phrase "A B => A+B" shows the stack before and after the bytecode
-executes. Beforehand, the stack must contain at least two values, A
-and B; since the top of the stack is to the right, B is on the top of
-the stack, and A is underneath it. After execution, the bytecode will
-have popped A and B from the stack, and replaced them with a single
-value, A+B. There may be other values on the stack below those shown,
-but the bytecode affects only those shown.
-
- Here is another example:
-
-`const8' (0x22) N: => N
- Push the 8-bit integer constant N on the stack, without sign
- extension.
-
-
- In this example, the bytecode `const8' takes an operand N directly
-from the bytecode stream; the operand follows the `const8' bytecode
-itself. We write any such operands immediately after the name of the
-bytecode, before the colon, and describe the exact encoding of the
-operand in the bytecode stream in the body of the bytecode description.
-
- For the `const8' bytecode, there are no stack items given before the
-=>; this simply means that the bytecode consumes no values from the
-stack. If a bytecode consumes no values, or produces no values, the
-list on either side of the => may be empty.
-
- If a value is written as A, B, or N, then the bytecode treats it as
-an integer. If a value is written is ADDR, then the bytecode treats it
-as an address.
-
- We do not fully describe the floating point operations here; although
-this design can be extended in a clean way to handle floating point
-values, they are not of immediate interest to the customer, so we avoid
-describing them, to save time.
-
-`float' (0x01): =>
- Prefix for floating-point bytecodes. Not implemented yet.
-
-`add' (0x02): A B => A+B
- Pop two integers from the stack, and push their sum, as an integer.
-
-`sub' (0x03): A B => A-B
- Pop two integers from the stack, subtract the top value from the
- next-to-top value, and push the difference.
-
-`mul' (0x04): A B => A*B
- Pop two integers from the stack, multiply them, and push the
- product on the stack. Note that, when one multiplies two N-bit
- numbers yielding another N-bit number, it is irrelevant whether the
- numbers are signed or not; the results are the same.
-
-`div_signed' (0x05): A B => A/B
- Pop two signed integers from the stack; divide the next-to-top
- value by the top value, and push the quotient. If the divisor is
- zero, terminate with an error.
-
-`div_unsigned' (0x06): A B => A/B
- Pop two unsigned integers from the stack; divide the next-to-top
- value by the top value, and push the quotient. If the divisor is
- zero, terminate with an error.
-
-`rem_signed' (0x07): A B => A MODULO B
- Pop two signed integers from the stack; divide the next-to-top
- value by the top value, and push the remainder. If the divisor is
- zero, terminate with an error.
-
-`rem_unsigned' (0x08): A B => A MODULO B
- Pop two unsigned integers from the stack; divide the next-to-top
- value by the top value, and push the remainder. If the divisor is
- zero, terminate with an error.
-
-`lsh' (0x09): A B => A<<B
- Pop two integers from the stack; let A be the next-to-top value,
- and B be the top value. Shift A left by B bits, and push the
- result.
-
-`rsh_signed' (0x0a): A B => `(signed)'A>>B
- Pop two integers from the stack; let A be the next-to-top value,
- and B be the top value. Shift A right by B bits, inserting copies
- of the top bit at the high end, and push the result.
-
-`rsh_unsigned' (0x0b): A B => A>>B
- Pop two integers from the stack; let A be the next-to-top value,
- and B be the top value. Shift A right by B bits, inserting zero
- bits at the high end, and push the result.
-
-`log_not' (0x0e): A => !A
- Pop an integer from the stack; if it is zero, push the value one;
- otherwise, push the value zero.
-
-`bit_and' (0x0f): A B => A&B
- Pop two integers from the stack, and push their bitwise `and'.
-
-`bit_or' (0x10): A B => A|B
- Pop two integers from the stack, and push their bitwise `or'.
-
-`bit_xor' (0x11): A B => A^B
- Pop two integers from the stack, and push their bitwise
- exclusive-`or'.
-
-`bit_not' (0x12): A => ~A
- Pop an integer from the stack, and push its bitwise complement.
-
-`equal' (0x13): A B => A=B
- Pop two integers from the stack; if they are equal, push the value
- one; otherwise, push the value zero.
-
-`less_signed' (0x14): A B => A<B
- Pop two signed integers from the stack; if the next-to-top value
- is less than the top value, push the value one; otherwise, push
- the value zero.
-
-`less_unsigned' (0x15): A B => A<B
- Pop two unsigned integers from the stack; if the next-to-top value
- is less than the top value, push the value one; otherwise, push
- the value zero.
-
-`ext' (0x16) N: A => A, sign-extended from N bits
- Pop an unsigned value from the stack; treating it as an N-bit
- twos-complement value, extend it to full length. This means that
- all bits to the left of bit N-1 (where the least significant bit
- is bit 0) are set to the value of bit N-1. Note that N may be
- larger than or equal to the width of the stack elements of the
- bytecode engine; in this case, the bytecode should have no effect.
-
- The number of source bits to preserve, N, is encoded as a single
- byte unsigned integer following the `ext' bytecode.
-
-`zero_ext' (0x2a) N: A => A, zero-extended from N bits
- Pop an unsigned value from the stack; zero all but the bottom N
- bits. This means that all bits to the left of bit N-1 (where the
- least significant bit is bit 0) are set to the value of bit N-1.
-
- The number of source bits to preserve, N, is encoded as a single
- byte unsigned integer following the `zero_ext' bytecode.
-
-`ref8' (0x17): ADDR => A
-`ref16' (0x18): ADDR => A
-`ref32' (0x19): ADDR => A
-`ref64' (0x1a): ADDR => A
- Pop an address ADDR from the stack. For bytecode `ref'N, fetch an
- N-bit value from ADDR, using the natural target endianness. Push
- the fetched value as an unsigned integer.
-
- Note that ADDR may not be aligned in any particular way; the
- `refN' bytecodes should operate correctly for any address.
-
- If attempting to access memory at ADDR would cause a processor
- exception of some sort, terminate with an error.
-
-`ref_float' (0x1b): ADDR => D
-`ref_double' (0x1c): ADDR => D
-`ref_long_double' (0x1d): ADDR => D
-`l_to_d' (0x1e): A => D
-`d_to_l' (0x1f): D => A
- Not implemented yet.
-
-`dup' (0x28): A => A A
- Push another copy of the stack's top element.
-
-`swap' (0x2b): A B => B A
- Exchange the top two items on the stack.
-
-`pop' (0x29): A =>
- Discard the top value on the stack.
-
-`pick' (0x32) N: A ... B => A ... B A
- Duplicate an item from the stack and push it on the top of the
- stack. N, a single byte, indicates the stack item to copy. If N
- is zero, this is the same as `dup'; if N is one, it copies the
- item under the top item, etc. If N exceeds the number of items on
- the stack, terminate with an error.
-
-`rot' (0x33): A B C => C B A
- Rotate the top three items on the stack.
-
-`if_goto' (0x20) OFFSET: A =>
- Pop an integer off the stack; if it is non-zero, branch to the
- given offset in the bytecode string. Otherwise, continue to the
- next instruction in the bytecode stream. In other words, if A is
- non-zero, set the `pc' register to `start' + OFFSET. Thus, an
- offset of zero denotes the beginning of the expression.
-
- The OFFSET is stored as a sixteen-bit unsigned value, stored
- immediately following the `if_goto' bytecode. It is always stored
- most significant byte first, regardless of the target's normal
- endianness. The offset is not guaranteed to fall at any particular
- alignment within the bytecode stream; thus, on machines where
- fetching a 16-bit on an unaligned address raises an exception, you
- should fetch the offset one byte at a time.
-
-`goto' (0x21) OFFSET: =>
- Branch unconditionally to OFFSET; in other words, set the `pc'
- register to `start' + OFFSET.
-
- The offset is stored in the same way as for the `if_goto' bytecode.
-
-`const8' (0x22) N: => N
-`const16' (0x23) N: => N
-`const32' (0x24) N: => N
-`const64' (0x25) N: => N
- Push the integer constant N on the stack, without sign extension.
- To produce a small negative value, push a small twos-complement
- value, and then sign-extend it using the `ext' bytecode.
-
- The constant N is stored in the appropriate number of bytes
- following the `const'B bytecode. The constant N is always stored
- most significant byte first, regardless of the target's normal
- endianness. The constant is not guaranteed to fall at any
- particular alignment within the bytecode stream; thus, on machines
- where fetching a 16-bit on an unaligned address raises an
- exception, you should fetch N one byte at a time.
-
-`reg' (0x26) N: => A
- Push the value of register number N, without sign extension. The
- registers are numbered following GDB's conventions.
-
- The register number N is encoded as a 16-bit unsigned integer
- immediately following the `reg' bytecode. It is always stored most
- significant byte first, regardless of the target's normal
- endianness. The register number is not guaranteed to fall at any
- particular alignment within the bytecode stream; thus, on machines
- where fetching a 16-bit on an unaligned address raises an
- exception, you should fetch the register number one byte at a time.
-
-`getv' (0x2c) N: => V
- Push the value of trace state variable number N, without sign
- extension.
-
- The variable number N is encoded as a 16-bit unsigned integer
- immediately following the `getv' bytecode. It is always stored
- most significant byte first, regardless of the target's normal
- endianness. The variable number is not guaranteed to fall at any
- particular alignment within the bytecode stream; thus, on machines
- where fetching a 16-bit on an unaligned address raises an
- exception, you should fetch the register number one byte at a time.
-
-`setv' (0x2d) N: => V
- Set trace state variable number N to the value found on the top of
- the stack. The stack is unchanged, so that the value is readily
- available if the assignment is part of a larger expression. The
- handling of N is as described for `getv'.
-
-`trace' (0x0c): ADDR SIZE =>
- Record the contents of the SIZE bytes at ADDR in a trace buffer,
- for later retrieval by GDB.
-
-`trace_quick' (0x0d) SIZE: ADDR => ADDR
- Record the contents of the SIZE bytes at ADDR in a trace buffer,
- for later retrieval by GDB. SIZE is a single byte unsigned
- integer following the `trace' opcode.
-
- This bytecode is equivalent to the sequence `dup const8 SIZE
- trace', but we provide it anyway to save space in bytecode strings.
-
-`trace16' (0x30) SIZE: ADDR => ADDR
- Identical to trace_quick, except that SIZE is a 16-bit big-endian
- unsigned integer, not a single byte. This should probably have
- been named `trace_quick16', for consistency.
-
-`tracev' (0x2e) N: => A
- Record the value of trace state variable number N in the trace
- buffer. The handling of N is as described for `getv'.
-
-`tracenz' (0x2f) ADDR SIZE =>
- Record the bytes at ADDR in a trace buffer, for later retrieval by
- GDB. Stop at either the first zero byte, or when SIZE bytes have
- been recorded, whichever occurs first.
-
-`printf' (0x34) NUMARGS STRING =>
- Do a formatted print, in the style of the C function `printf').
- The value of NUMARGS is the number of arguments to expect on the
- stack, while STRING is the format string, prefixed with a two-byte
- length. The last byte of the string must be zero, and is included
- in the length. The format string includes escaped sequences just
- as it appears in C source, so for instance the format string
- `"\t%d\n"' is six characters long, and the output will consist of
- a tab character, a decimal number, and a newline. At the top of
- the stack, above the values to be printed, this bytecode will pop a
- "function" and "channel". If the function is nonzero, then the
- target may treat it as a function and call it, passing the channel
- as a first argument, as with the C function `fprintf'. If the
- function is zero, then the target may simply call a standard
- formatted print function of its choice. In all, this bytecode
- pops 2 + NUMARGS stack elements, and pushes nothing.
-
-`end' (0x27): =>
- Stop executing bytecode; the result should be the top element of
- the stack. If the purpose of the expression was to compute an
- lvalue or a range of memory, then the next-to-top of the stack is
- the lvalue's address, and the top of the stack is the lvalue's
- size, in bytes.
+GDB Command
+...........
+
+There is no corresponding GDB command.
+Example
+.......
+
+ (gdb)
+ -symbol-list-lines basics.c
+ ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
+ (gdb)
\1f
-File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
+File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
-F.3 Using Agent Expressions
-===========================
+27.19 GDB/MI File Commands
+==========================
+
+This section describes the GDB/MI commands to specify executable file
+names and to read in and obtain symbol table information.
+
+The '-file-exec-and-symbols' Command
+------------------------------------
-Agent expressions can be used in several different ways by GDB, and the
-debugger can generate different bytecode sequences as appropriate.
+Synopsis
+........
- One possibility is to do expression evaluation on the target rather
-than the host, such as for the conditional of a conditional tracepoint.
-In such a case, GDB compiles the source expression into a bytecode
-sequence that simply gets values from registers or memory, does
-arithmetic, and returns a result.
+ -file-exec-and-symbols FILE
- Another way to use agent expressions is for tracepoint data
-collection. GDB generates a different bytecode sequence for
-collection; in addition to bytecodes that do the calculation, GDB adds
-`trace' bytecodes to save the pieces of memory that were used.
+ Specify the executable file to be debugged. This file is the one
+from which the symbol table is also read. If no file is specified, the
+command clears the executable and symbol information. If breakpoints
+are set when using this command with no arguments, GDB will produce
+error messages. Otherwise, no output is produced, except a completion
+notification.
- * The user selects trace points in the program's code at which GDB
- should collect data.
+GDB Command
+...........
- * The user specifies expressions to evaluate at each trace point.
- These expressions may denote objects in memory, in which case
- those objects' contents are recorded as the program runs, or
- computed values, in which case the values themselves are recorded.
+The corresponding GDB command is 'file'.
- * GDB transmits the tracepoints and their associated expressions to
- the GDB agent, running on the debugging target.
+Example
+.......
- * The agent arranges to be notified when a trace point is hit.
+ (gdb)
+ -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+ ^done
+ (gdb)
- * When execution on the target reaches a trace point, the agent
- evaluates the expressions associated with that trace point, and
- records the resulting values and memory ranges.
+The '-file-exec-file' Command
+-----------------------------
- * Later, when the user selects a given trace event and inspects the
- objects and expression values recorded, GDB talks to the agent to
- retrieve recorded data as necessary to meet the user's requests.
- If the user asks to see an object whose contents have not been
- recorded, GDB reports an error.
+Synopsis
+........
+ -file-exec-file FILE
-\1f
-File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions
+ Specify the executable file to be debugged. Unlike
+'-file-exec-and-symbols', the symbol table is _not_ read from this file.
+If used without argument, GDB clears the information about the
+executable file. No output is produced, except a completion
+notification.
-F.4 Varying Target Capabilities
-===============================
+GDB Command
+...........
-Some targets don't support floating-point, and some would rather not
-have to deal with `long long' operations. Also, different targets will
-have different stack sizes, and different bytecode buffer lengths.
+The corresponding GDB command is 'exec-file'.
- Thus, GDB needs a way to ask the target about itself. We haven't
-worked out the details yet, but in general, GDB should be able to send
-the target a packet asking it to describe itself. The reply should be a
-packet whose length is explicit, so we can add new information to the
-packet in future revisions of the agent, without confusing old versions
-of GDB, and it should contain a version number. It should contain at
-least the following information:
+Example
+.......
- * whether floating point is supported
+ (gdb)
+ -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+ ^done
+ (gdb)
- * whether `long long' is supported
+The '-file-list-exec-source-file' Command
+-----------------------------------------
- * maximum acceptable size of bytecode stack
+Synopsis
+........
- * maximum acceptable length of bytecode expressions
+ -file-list-exec-source-file
- * which registers are actually available for collection
+ List the line number, the current source file, and the absolute path
+to the current source file for the current executable. The macro
+information field has a value of '1' or '0' depending on whether or not
+the file includes preprocessor macro information.
- * whether the target supports disabled tracepoints
+GDB Command
+...........
+The GDB equivalent is 'info source'
-\1f
-File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
-
-F.5 Rationale
-=============
-
-Some of the design decisions apparent above are arguable.
-
-What about stack overflow/underflow?
- GDB should be able to query the target to discover its stack size.
- Given that information, GDB can determine at translation time
- whether a given expression will overflow the stack. But this spec
- isn't about what kinds of error-checking GDB ought to do.
-
-Why are you doing everything in LONGEST?
- Speed isn't important, but agent code size is; using LONGEST
- brings in a bunch of support code to do things like division, etc.
- So this is a serious concern.
-
- First, note that you don't need different bytecodes for different
- operand sizes. You can generate code without _knowing_ how big the
- stack elements actually are on the target. If the target only
- supports 32-bit ints, and you don't send any 64-bit bytecodes,
- everything just works. The observation here is that the MIPS and
- the Alpha have only fixed-size registers, and you can still get
- C's semantics even though most instructions only operate on
- full-sized words. You just need to make sure everything is
- properly sign-extended at the right times. So there is no need
- for 32- and 64-bit variants of the bytecodes. Just implement
- everything using the largest size you support.
-
- GDB should certainly check to see what sizes the target supports,
- so the user can get an error earlier, rather than later. But this
- information is not necessary for correctness.
-
-Why don't you have `>' or `<=' operators?
- I want to keep the interpreter small, and we don't need them. We
- can combine the `less_' opcodes with `log_not', and swap the order
- of the operands, yielding all four asymmetrical comparison
- operators. For example, `(x <= y)' is `! (x > y)', which is `! (y
- < x)'.
-
-Why do you have `log_not'?
-Why do you have `ext'?
-Why do you have `zero_ext'?
- These are all easily synthesized from other instructions, but I
- expect them to be used frequently, and they're simple, so I
- include them to keep bytecode strings short.
-
- `log_not' is equivalent to `const8 0 equal'; it's used in half the
- relational operators.
-
- `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed',
- where S is the size of the stack elements; it follows `refM' and
- REG bytecodes when the value should be signed. See the next
- bulleted item.
-
- `zero_ext N' is equivalent to `constM MASK log_and'; it's used
- whenever we push the value of a register, because we can't assume
- the upper bits of the register aren't garbage.
-
-Why not have sign-extending variants of the `ref' operators?
- Because that would double the number of `ref' operators, and we
- need the `ext' bytecode anyway for accessing bitfields.
-
-Why not have constant-address variants of the `ref' operators?
- Because that would double the number of `ref' operators again, and
- `const32 ADDRESS ref32' is only one byte longer.
-
-Why do the `refN' operators have to support unaligned fetches?
- GDB will generate bytecode that fetches multi-byte values at
- unaligned addresses whenever the executable's debugging
- information tells it to. Furthermore, GDB does not know the value
- the pointer will have when GDB generates the bytecode, so it
- cannot determine whether a particular fetch will be aligned or not.
-
- In particular, structure bitfields may be several bytes long, but
- follow no alignment rules; members of packed structures are not
- necessarily aligned either.
-
- In general, there are many cases where unaligned references occur
- in correct C code, either at the programmer's explicit request, or
- at the compiler's discretion. Thus, it is simpler to make the GDB
- agent bytecodes work correctly in all circumstances than to make
- GDB guess in each case whether the compiler did the usual thing.
-
-Why are there no side-effecting operators?
- Because our current client doesn't want them? That's a cheap
- answer. I think the real answer is that I'm afraid of
- implementing function calls. We should re-visit this issue after
- the present contract is delivered.
-
-Why aren't the `goto' ops PC-relative?
- The interpreter has the base address around anyway for PC bounds
- checking, and it seemed simpler.
-
-Why is there only one offset size for the `goto' ops?
- Offsets are currently sixteen bits. I'm not happy with this
- situation either:
-
- Suppose we have multiple branch ops with different offset sizes.
- As I generate code left-to-right, all my jumps are forward jumps
- (there are no loops in expressions), so I never know the target
- when I emit the jump opcode. Thus, I have to either always assume
- the largest offset size, or do jump relaxation on the code after I
- generate it, which seems like a big waste of time.
-
- I can imagine a reasonable expression being longer than 256 bytes.
- I can't imagine one being longer than 64k. Thus, we need 16-bit
- offsets. This kind of reasoning is so bogus, but relaxation is
- pathetic.
-
- The other approach would be to generate code right-to-left. Then
- I'd always know my offset size. That might be fun.
-
-Where is the function call bytecode?
- When we add side-effects, we should add this.
-
-Why does the `reg' bytecode take a 16-bit register number?
- Intel's IA-64 architecture has 128 general-purpose registers, and
- 128 floating-point registers, and I'm sure it has some random
- control registers.
-
-Why do we need `trace' and `trace_quick'?
- Because GDB needs to record all the memory contents and registers
- an expression touches. If the user wants to evaluate an expression
- `x->y->z', the agent must record the values of `x' and `x->y' as
- well as the value of `x->y->z'.
-
-Don't the `trace' bytecodes make the interpreter less general?
- They do mean that the interpreter contains special-purpose code,
- but that doesn't mean the interpreter can only be used for that
- purpose. If an expression doesn't use the `trace' bytecodes, they
- don't get in its way.
-
-Why doesn't `trace_quick' consume its arguments the way everything else does?
- In general, you do want your operators to consume their arguments;
- it's consistent, and generally reduces the amount of stack
- rearrangement necessary. However, `trace_quick' is a kludge to
- save space; it only exists so we needn't write `dup const8 SIZE
- trace' before every memory reference. Therefore, it's okay for it
- not to consume its arguments; it's meant for a specific context in
- which we know exactly what it should do with the stack. If we're
- going to have a kludge, it should be an effective kludge.
-
-Why does `trace16' exist?
- That opcode was added by the customer that contracted Cygnus for
- the data tracing work. I personally think it is unnecessary;
- objects that large will be quite rare, so it is okay to use `dup
- const16 SIZE trace' in those cases.
-
- Whatever we decide to do with `trace16', we should at least leave
- opcode 0x30 reserved, to remain compatible with the customer who
- added it.
+Example
+.......
+ (gdb)
+ 123-file-list-exec-source-file
+ 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
+ (gdb)
-\1f
-File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top
+The '-file-list-exec-source-files' Command
+------------------------------------------
-Appendix G Target Descriptions
-******************************
+Synopsis
+........
-One of the challenges of using GDB to debug embedded systems is that
-there are so many minor variants of each processor architecture in use.
-It is common practice for vendors to start with a standard processor
-core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
-adapt it to a particular market niche. Some architectures have
-hundreds of variants, available from dozens of vendors. This leads to
-a number of problems:
+ -file-list-exec-source-files
- * With so many different customized processors, it is difficult for
- the GDB maintainers to keep up with the changes.
+ List the source files for the current executable.
- * Since individual variants may have short lifetimes or limited
- audiences, it may not be worthwhile to carry information about
- every variant in the GDB source tree.
+ It will always output both the filename and fullname (absolute file
+name) of a source file.
- * When GDB does support the architecture of the embedded system at
- hand, the task of finding the correct architecture name to give the
- `set architecture' command can be error-prone.
+GDB Command
+...........
- To address these problems, the GDB remote protocol allows a target
-system to not only identify itself to GDB, but to actually describe its
-own features. This lets GDB support processor variants it has never
-seen before -- to the extent that the descriptions are accurate, and
-that GDB understands them.
+The GDB equivalent is 'info sources'. 'gdbtk' has an analogous command
+'gdb_listfiles'.
- GDB must be linked with the Expat library to support XML target
-descriptions. *Note Expat::.
+Example
+.......
-* Menu:
+ (gdb)
+ -file-list-exec-source-files
+ ^done,files=[
+ {file=foo.c,fullname=/home/foo.c},
+ {file=/home/bar.c,fullname=/home/bar.c},
+ {file=gdb_could_not_find_fullpath.c}]
+ (gdb)
-* Retrieving Descriptions:: How descriptions are fetched from a target.
-* Target Description Format:: The contents of a target description.
-* Predefined Target Types:: Standard types available for target
- descriptions.
-* Standard Target Features:: Features GDB knows about.
+The '-file-symbol-file' Command
+-------------------------------
-\1f
-File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
+Synopsis
+........
-G.1 Retrieving Descriptions
-===========================
+ -file-symbol-file FILE
-Target descriptions can be read from the target automatically, or
-specified by the user manually. The default behavior is to read the
-description from the target. GDB retrieves it via the remote protocol
-using `qXfer' requests (*note qXfer: General Query Packets.). The
-ANNEX in the `qXfer' packet will be `target.xml'. The contents of the
-`target.xml' annex are an XML document, of the form described in *Note
-Target Description Format::.
+ Read symbol table info from the specified FILE argument. When used
+without arguments, clears GDB's symbol table info. No output is
+produced, except for a completion notification.
- Alternatively, you can specify a file to read for the target
-description. If a file is set, the target will not be queried. The
-commands to specify a file are:
+GDB Command
+...........
-`set tdesc filename PATH'
- Read the target description from PATH.
+The corresponding GDB command is 'symbol-file'.
-`unset tdesc filename'
- Do not read the XML target description from a file. GDB will use
- the description supplied by the current target.
+Example
+.......
-`show tdesc filename'
- Show the filename to read for a target description, if any.
+ (gdb)
+ -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+ ^done
+ (gdb)
\1f
-File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
+File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
-G.2 Target Description Format
-=============================
+27.20 GDB/MI Target Manipulation Commands
+=========================================
-A target description annex is an XML (http://www.w3.org/XML/) document
-which complies with the Document Type Definition provided in the GDB
-sources in `gdb/features/gdb-target.dtd'. This means you can use
-generally available tools like `xmllint' to check that your feature
-descriptions are well-formed and valid. However, to help people
-unfamiliar with XML write descriptions for their targets, we also
-describe the grammar here.
-
- Target descriptions can identify the architecture of the remote
-target and (for some architectures) provide information about custom
-register sets. They can also identify the OS ABI of the remote target.
-GDB can use this information to autoconfigure for your target, or to
-warn you if you connect to an unsupported target.
-
- Here is a simple target description:
-
- <target version="1.0">
- <architecture>i386:x86-64</architecture>
- </target>
-
-This minimal description only says that the target uses the x86-64
-architecture.
-
- A target description has the following overall form, with [ ] marking
-optional elements and ... marking repeatable elements. The elements
-are explained further below.
-
- <?xml version="1.0"?>
- <!DOCTYPE target SYSTEM "gdb-target.dtd">
- <target version="1.0">
- [ARCHITECTURE]
- [OSABI]
- [COMPATIBLE]
- [FEATURE...]
- </target>
-
-The description is generally insensitive to whitespace and line breaks,
-under the usual common-sense rules. The XML version declaration and
-document type declaration can generally be omitted (GDB does not
-require them), but specifying them may be useful for XML validation
-tools. The `version' attribute for `<target>' may also be omitted, but
-we recommend including it; if future versions of GDB use an incompatible
-revision of `gdb-target.dtd', they will detect and report the version
-mismatch.
-
-G.2.1 Inclusion
----------------
-
-It can sometimes be valuable to split a target description up into
-several different annexes, either for organizational purposes, or to
-share files between different possible target descriptions. You can
-divide a description into multiple files by replacing any element of
-the target description with an inclusion directive of the form:
-
- <xi:include href="DOCUMENT"/>
-
-When GDB encounters an element of this form, it will retrieve the named
-XML DOCUMENT, and replace the inclusion directive with the contents of
-that document. If the current description was read using `qXfer', then
-so will be the included document; DOCUMENT will be interpreted as the
-name of an annex. If the current description was read from a file, GDB
-will look for DOCUMENT as a file in the same directory where it found
-the original description.
-
-G.2.2 Architecture
-------------------
-
-An `<architecture>' element has this form:
-
- <architecture>ARCH</architecture>
-
- ARCH is one of the architectures from the set accepted by `set
-architecture' (*note Specifying a Debugging Target: Targets.).
-
-G.2.3 OS ABI
-------------
+The '-target-attach' Command
+----------------------------
-This optional field was introduced in GDB version 7.0. Previous
-versions of GDB ignore it.
+Synopsis
+........
- An `<osabi>' element has this form:
+ -target-attach PID | GID | FILE
- <osabi>ABI-NAME</osabi>
+ Attach to a process PID or a file FILE outside of GDB, or a thread
+group GID. If attaching to a thread group, the id previously returned
+by '-list-thread-groups --available' must be used.
- ABI-NAME is an OS ABI name from the same selection accepted by
-`set osabi' (*note Configuring the Current ABI: ABI.).
+GDB Command
+...........
-G.2.4 Compatible Architecture
------------------------------
+The corresponding GDB command is 'attach'.
-This optional field was introduced in GDB version 7.0. Previous
-versions of GDB ignore it.
+Example
+.......
- A `<compatible>' element has this form:
+ (gdb)
+ -target-attach 34
+ =thread-created,id="1"
+ *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}
+ ^done
+ (gdb)
- <compatible>ARCH</compatible>
+The '-target-detach' Command
+----------------------------
- ARCH is one of the architectures from the set accepted by `set
-architecture' (*note Specifying a Debugging Target: Targets.).
+Synopsis
+........
- A `<compatible>' element is used to specify that the target is able
-to run binaries in some other than the main target architecture given
-by the `<architecture>' element. For example, on the Cell Broadband
-Engine, the main architecture is `powerpc:common' or
-`powerpc:common64', but the system is able to run binaries in the `spu'
-architecture as well. The way to describe this capability with
-`<compatible>' is as follows:
+ -target-detach [ PID | GID ]
- <architecture>powerpc:common</architecture>
- <compatible>spu</compatible>
+ Detach from the remote target which normally resumes its execution.
+If either PID or GID is specified, detaches from either the specified
+process, or specified thread group. There's no output.
-G.2.5 Features
---------------
+GDB Command
+...........
-Each `<feature>' describes some logical portion of the target system.
-Features are currently used to describe available CPU registers and the
-types of their contents. A `<feature>' element has this form:
+The corresponding GDB command is 'detach'.
- <feature name="NAME">
- [TYPE...]
- REG...
- </feature>
+Example
+.......
-Each feature's name should be unique within the description. The name
-of a feature does not matter unless GDB has some special knowledge of
-the contents of that feature; if it does, the feature should have its
-standard name. *Note Standard Target Features::.
+ (gdb)
+ -target-detach
+ ^done
+ (gdb)
-G.2.6 Types
------------
+The '-target-disconnect' Command
+--------------------------------
-Any register's value is a collection of bits which GDB must interpret.
-The default interpretation is a two's complement integer, but other
-types can be requested by name in the register description. Some
-predefined types are provided by GDB (*note Predefined Target Types::),
-and the description can define additional composite types.
-
- Each type element must have an `id' attribute, which gives a unique
-(within the containing `<feature>') name to the type. Types must be
-defined before they are used.
-
- Some targets offer vector registers, which can be treated as arrays
-of scalar elements. These types are written as `<vector>' elements,
-specifying the array element type, TYPE, and the number of elements,
-COUNT:
-
- <vector id="ID" type="TYPE" count="COUNT"/>
-
- If a register's value is usefully viewed in multiple ways, define it
-with a union type containing the useful representations. The `<union>'
-element contains one or more `<field>' elements, each of which has a
-NAME and a TYPE:
-
- <union id="ID">
- <field name="NAME" type="TYPE"/>
- ...
- </union>
-
- If a register's value is composed from several separate values,
-define it with a structure type. There are two forms of the `<struct>'
-element; a `<struct>' element must either contain only bitfields or
-contain no bitfields. If the structure contains only bitfields, its
-total size in bytes must be specified, each bitfield must have an
-explicit start and end, and bitfields are automatically assigned an
-integer type. The field's START should be less than or equal to its
-END, and zero represents the least significant bit.
-
- <struct id="ID" size="SIZE">
- <field name="NAME" start="START" end="END"/>
- ...
- </struct>
-
- If the structure contains no bitfields, then each field has an
-explicit type, and no implicit padding is added.
-
- <struct id="ID">
- <field name="NAME" type="TYPE"/>
- ...
- </struct>
-
- If a register's value is a series of single-bit flags, define it with
-a flags type. The `<flags>' element has an explicit SIZE and contains
-one or more `<field>' elements. Each field has a NAME, a START, and an
-END. Only single-bit flags are supported.
-
- <flags id="ID" size="SIZE">
- <field name="NAME" start="START" end="END"/>
- ...
- </flags>
-
-G.2.7 Registers
----------------
-
-Each register is represented as an element with this form:
-
- <reg name="NAME"
- bitsize="SIZE"
- [regnum="NUM"]
- [save-restore="SAVE-RESTORE"]
- [type="TYPE"]
- [group="GROUP"]/>
-
-The components are as follows:
+Synopsis
+........
-NAME
- The register's name; it must be unique within the target
- description.
-
-BITSIZE
- The register's size, in bits.
-
-REGNUM
- The register's number. If omitted, a register's number is one
- greater than that of the previous register (either in the current
- feature or in a preceding feature); the first register in the
- target description defaults to zero. This register number is used
- to read or write the register; e.g. it is used in the remote `p'
- and `P' packets, and registers appear in the `g' and `G' packets
- in order of increasing register number.
-
-SAVE-RESTORE
- Whether the register should be preserved across inferior function
- calls; this must be either `yes' or `no'. The default is `yes',
- which is appropriate for most registers except for some system
- control registers; this is not related to the target's ABI.
+ -target-disconnect
-TYPE
- The type of the register. TYPE may be a predefined type, a type
- defined in the current feature, or one of the special types `int'
- and `float'. `int' is an integer type of the correct size for
- BITSIZE, and `float' is a floating point type (in the
- architecture's normal floating point format) of the correct size
- for BITSIZE. The default is `int'.
+ Disconnect from the remote target. There's no output and the target
+is generally not resumed.
-GROUP
- The register group to which this register belongs. GROUP must be
- either `general', `float', or `vector'. If no GROUP is specified,
- GDB will not display the register in `info registers'.
+GDB Command
+...........
+The corresponding GDB command is 'disconnect'.
-\1f
-File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
+Example
+.......
-G.3 Predefined Target Types
-===========================
+ (gdb)
+ -target-disconnect
+ ^done
+ (gdb)
-Type definitions in the self-description can build up composite types
-from basic building blocks, but can not define fundamental types.
-Instead, standard identifiers are provided by GDB for the fundamental
-types. The currently supported types are:
+The '-target-download' Command
+------------------------------
-`int8'
-`int16'
-`int32'
-`int64'
-`int128'
- Signed integer types holding the specified number of bits.
+Synopsis
+........
-`uint8'
-`uint16'
-`uint32'
-`uint64'
-`uint128'
- Unsigned integer types holding the specified number of bits.
+ -target-download
-`code_ptr'
-`data_ptr'
- Pointers to unspecified code and data. The program counter and
- any dedicated return address register may be marked as code
- pointers; printing a code pointer converts it into a symbolic
- address. The stack pointer and any dedicated address registers
- may be marked as data pointers.
+ Loads the executable onto the remote target. It prints out an update
+message every half second, which includes the fields:
-`ieee_single'
- Single precision IEEE floating point.
+'section'
+ The name of the section.
+'section-sent'
+ The size of what has been sent so far for that section.
+'section-size'
+ The size of the section.
+'total-sent'
+ The total size of what was sent so far (the current and the
+ previous sections).
+'total-size'
+ The size of the overall executable to download.
-`ieee_double'
- Double precision IEEE floating point.
+Each message is sent as status record (*note GDB/MI Output Syntax:
+GDB/MI Output Syntax.).
-`arm_fpa_ext'
- The 12-byte extended precision format used by ARM FPA registers.
+ In addition, it prints the name and size of the sections, as they are
+downloaded. These messages include the following fields:
-`i387_ext'
- The 10-byte extended precision format used by x87 registers.
+'section'
+ The name of the section.
+'section-size'
+ The size of the section.
+'total-size'
+ The size of the overall executable to download.
-`i386_eflags'
- 32bit EFLAGS register used by x86.
+At the end, a summary is printed.
-`i386_mxcsr'
- 32bit MXCSR register used by x86.
+GDB Command
+...........
+The corresponding GDB command is 'load'.
+
+Example
+.......
+
+Note: each status message appears on a single line. Here the messages
+have been broken down so that they can fit onto a page.
+
+ (gdb)
+ -target-download
+ +download,{section=".text",section-size="6668",total-size="9880"}
+ +download,{section=".text",section-sent="512",section-size="6668",
+ total-sent="512",total-size="9880"}
+ +download,{section=".text",section-sent="1024",section-size="6668",
+ total-sent="1024",total-size="9880"}
+ +download,{section=".text",section-sent="1536",section-size="6668",
+ total-sent="1536",total-size="9880"}
+ +download,{section=".text",section-sent="2048",section-size="6668",
+ total-sent="2048",total-size="9880"}
+ +download,{section=".text",section-sent="2560",section-size="6668",
+ total-sent="2560",total-size="9880"}
+ +download,{section=".text",section-sent="3072",section-size="6668",
+ total-sent="3072",total-size="9880"}
+ +download,{section=".text",section-sent="3584",section-size="6668",
+ total-sent="3584",total-size="9880"}
+ +download,{section=".text",section-sent="4096",section-size="6668",
+ total-sent="4096",total-size="9880"}
+ +download,{section=".text",section-sent="4608",section-size="6668",
+ total-sent="4608",total-size="9880"}
+ +download,{section=".text",section-sent="5120",section-size="6668",
+ total-sent="5120",total-size="9880"}
+ +download,{section=".text",section-sent="5632",section-size="6668",
+ total-sent="5632",total-size="9880"}
+ +download,{section=".text",section-sent="6144",section-size="6668",
+ total-sent="6144",total-size="9880"}
+ +download,{section=".text",section-sent="6656",section-size="6668",
+ total-sent="6656",total-size="9880"}
+ +download,{section=".init",section-size="28",total-size="9880"}
+ +download,{section=".fini",section-size="28",total-size="9880"}
+ +download,{section=".data",section-size="3156",total-size="9880"}
+ +download,{section=".data",section-sent="512",section-size="3156",
+ total-sent="7236",total-size="9880"}
+ +download,{section=".data",section-sent="1024",section-size="3156",
+ total-sent="7748",total-size="9880"}
+ +download,{section=".data",section-sent="1536",section-size="3156",
+ total-sent="8260",total-size="9880"}
+ +download,{section=".data",section-sent="2048",section-size="3156",
+ total-sent="8772",total-size="9880"}
+ +download,{section=".data",section-sent="2560",section-size="3156",
+ total-sent="9284",total-size="9880"}
+ +download,{section=".data",section-sent="3072",section-size="3156",
+ total-sent="9796",total-size="9880"}
+ ^done,address="0x10004",load-size="9880",transfer-rate="6586",
+ write-rate="429"
+ (gdb)
+
+GDB Command
+...........
-\1f
-File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
+No equivalent.
-G.4 Standard Target Features
-============================
+Example
+.......
-A target description must contain either no registers or all the
-target's registers. If the description contains no registers, then GDB
-will assume a default register layout, selected based on the
-architecture. If the description contains any registers, the default
-layout will not be used; the standard registers must be described in
-the target description, in such a way that GDB can recognize them.
-
- This is accomplished by giving specific names to feature elements
-which contain standard registers. GDB will look for features with
-those names and verify that they contain the expected registers; if any
-known feature is missing required registers, or if any required feature
-is missing, GDB will reject the target description. You can add
-additional registers to any of the standard features -- GDB will
-display them just as if they were added to an unrecognized feature.
-
- This section lists the known features and their expected contents.
-Sample XML documents for these features are included in the GDB source
-tree, in the directory `gdb/features'.
-
- Names recognized by GDB should include the name of the company or
-organization which selected the name, and the overall architecture to
-which the feature applies; so e.g. the feature containing ARM core
-registers is named `org.gnu.gdb.arm.core'.
-
- The names of registers are not case sensitive for the purpose of
-recognizing standard features, but GDB will only display registers
-using the capitalization used in the description.
+N.A.
-* Menu:
+The '-target-select' Command
+----------------------------
-* ARM Features::
-* i386 Features::
-* MIPS Features::
-* M68K Features::
-* PowerPC Features::
-* TIC6x Features::
+Synopsis
+........
-\1f
-File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features
+ -target-select TYPE PARAMETERS ...
+
+ Connect GDB to the remote target. This command takes two args:
-G.4.1 ARM Features
-------------------
+'TYPE'
+ The type of target, for instance 'remote', etc.
+'PARAMETERS'
+ Device names, host names and the like. *Note Commands for Managing
+ Targets: Target Commands, for more details.
-The `org.gnu.gdb.arm.core' feature is required for non-M-profile ARM
-targets. It should contain registers `r0' through `r13', `sp', `lr',
-`pc', and `cpsr'.
+ The output is a connection notification, followed by the address at
+which the target program is, in the following form:
- For M-profile targets (e.g. Cortex-M3), the `org.gnu.gdb.arm.core'
-feature is replaced by `org.gnu.gdb.arm.m-profile'. It should contain
-registers `r0' through `r13', `sp', `lr', `pc', and `xpsr'.
+ ^connected,addr="ADDRESS",func="FUNCTION NAME",
+ args=[ARG LIST]
- The `org.gnu.gdb.arm.fpa' feature is optional. If present, it
-should contain registers `f0' through `f7' and `fps'.
+GDB Command
+...........
- The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
-should contain at least registers `wR0' through `wR15' and `wCGR0'
-through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers
-are optional.
+The corresponding GDB command is 'target'.
- The `org.gnu.gdb.arm.vfp' feature is optional. If present, it
-should contain at least registers `d0' through `d15'. If they are
-present, `d16' through `d31' should also be included. GDB will
-synthesize the single-precision registers from halves of the
-double-precision registers.
+Example
+.......
- The `org.gnu.gdb.arm.neon' feature is optional. It does not need to
-contain registers; it instructs GDB to display the VFP double-precision
-registers as vectors and to synthesize the quad-precision registers
-from pairs of double-precision registers. If this feature is present,
-`org.gnu.gdb.arm.vfp' must also be present and include 32
-double-precision registers.
+ (gdb)
+ -target-select remote /dev/ttya
+ ^connected,addr="0xfe00a300",func="??",args=[]
+ (gdb)
\1f
-File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features
+File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
+
+27.21 GDB/MI File Transfer Commands
+===================================
+
+The '-target-file-put' Command
+------------------------------
+
+Synopsis
+........
+
+ -target-file-put HOSTFILE TARGETFILE
-G.4.2 i386 Features
--------------------
+ Copy file HOSTFILE from the host system (the machine running GDB) to
+TARGETFILE on the target system.
-The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
-It should describe the following registers:
+GDB Command
+...........
+
+The corresponding GDB command is 'remote put'.
+
+Example
+.......
+
+ (gdb)
+ -target-file-put localfile remotefile
+ ^done
+ (gdb)
- - `eax' through `edi' plus `eip' for i386
+The '-target-file-get' Command
+------------------------------
+
+Synopsis
+........
- - `rax' through `r15' plus `rip' for amd64
+ -target-file-get TARGETFILE HOSTFILE
- - `eflags', `cs', `ss', `ds', `es', `fs', `gs'
+ Copy file TARGETFILE from the target system to HOSTFILE on the host
+system.
+
+GDB Command
+...........
- - `st0' through `st7'
+The corresponding GDB command is 'remote get'.
- - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and
- `fop'
+Example
+.......
- The register sets may be different, depending on the target.
+ (gdb)
+ -target-file-get remotefile localfile
+ ^done
+ (gdb)
- The `org.gnu.gdb.i386.sse' feature is optional. It should describe
-registers:
+The '-target-file-delete' Command
+---------------------------------
- - `xmm0' through `xmm7' for i386
+Synopsis
+........
- - `xmm0' through `xmm15' for amd64
+ -target-file-delete TARGETFILE
- - `mxcsr'
+ Delete TARGETFILE from the target system.
- The `org.gnu.gdb.i386.avx' feature is optional and requires the
-`org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits
-of YMM registers:
+GDB Command
+...........
- - `ymm0h' through `ymm7h' for i386
+The corresponding GDB command is 'remote delete'.
- - `ymm0h' through `ymm15h' for amd64
+Example
+.......
- The `org.gnu.gdb.i386.linux' feature is optional. It should
-describe a single register, `orig_eax'.
+ (gdb)
+ -target-file-delete remotefile
+ ^done
+ (gdb)
\1f
-File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features
+File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
+
+27.22 Ada Exceptions GDB/MI Commands
+====================================
+
+The '-info-ada-exceptions' Command
+----------------------------------
+
+Synopsis
+........
+
+ -info-ada-exceptions [ REGEXP]
+
+ List all Ada exceptions defined within the program being debugged.
+With a regular expression REGEXP, only those exceptions whose names
+match REGEXP are listed.
+
+GDB Command
+...........
-G.4.3 MIPS Features
--------------------
+The corresponding GDB command is 'info exceptions'.
-The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
-should contain registers `r0' through `r31', `lo', `hi', and `pc'.
-They may be 32-bit or 64-bit depending on the target.
+Result
+......
+
+The result is a table of Ada exceptions. The following columns are
+defined for each exception:
+
+'name'
+ The name of the exception.
+
+'address'
+ The address of the exception.
- The `org.gnu.gdb.mips.cp0' feature is also required. It should
-contain at least the `status', `badvaddr', and `cause' registers. They
-may be 32-bit or 64-bit depending on the target.
+Example
+.......
- The `org.gnu.gdb.mips.fpu' feature is currently required, though it
-may be optional in a future version of GDB. It should contain
-registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or
-64-bit depending on the target.
+ -info-ada-exceptions aint
+ ^done,ada-exceptions={nr_rows="2",nr_cols="2",
+ hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"},
+ {width="1",alignment="-1",col_name="address",colhdr="Address"}],
+ body=[{name="constraint_error",address="0x0000000000613da0"},
+ {name="const.aint_global_e",address="0x0000000000613b00"}]}
- The `org.gnu.gdb.mips.dsp' feature is optional. It should contain
-registers `hi1' through `hi3', `lo1' through `lo3', and `dspctl'. The
-`dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit
-depending on the target.
+Catching Ada Exceptions
+-----------------------
- The `org.gnu.gdb.mips.linux' feature is optional. It should contain
-a single register, `restart', which is used by the Linux kernel to
-control restartable syscalls.
+The commands describing how to ask GDB to stop when a program raises an
+exception are described at *note Ada Exception GDB/MI Catchpoint
+Commands::.
\1f
-File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features
+File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI
+
+27.23 GDB/MI Support Commands
+=============================
+
+Since new commands and features get regularly added to GDB/MI, some
+commands are available to help front-ends query the debugger about
+support for these capabilities. Similarly, it is also possible to query
+GDB about target support of certain features.
+
+The '-info-gdb-mi-command' Command
+----------------------------------
-G.4.4 M68K Features
--------------------
+Synopsis
+........
-``org.gnu.gdb.m68k.core''
-``org.gnu.gdb.coldfire.core''
-``org.gnu.gdb.fido.core''
- One of those features must be always present. The feature that is
- present determines which flavor of m68k is used. The feature that
- is present should contain registers `d0' through `d7', `a0'
- through `a5', `fp', `sp', `ps' and `pc'.
+ -info-gdb-mi-command CMD_NAME
-``org.gnu.gdb.coldfire.fp''
- This feature is optional. If present, it should contain registers
- `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'.
+ Query support for the GDB/MI command named CMD_NAME.
+
+ Note that the dash ('-') starting all GDB/MI commands is technically
+not part of the command name (*note GDB/MI Input Syntax::), and thus
+should be omitted in CMD_NAME. However, for ease of use, this command
+also accepts the form with the leading dash.
+
+GDB Command
+...........
+
+There is no corresponding GDB command.
+
+Result
+......
+
+The result is a tuple. There is currently only one field:
+
+'exists'
+ This field is equal to '"true"' if the GDB/MI command exists,
+ '"false"' otherwise.
+
+Example
+.......
+
+Here is an example where the GDB/MI command does not exist:
+
+ -info-gdb-mi-command unsupported-command
+ ^done,command={exists="false"}
+
+And here is an example where the GDB/MI command is known to the
+debugger:
+
+ -info-gdb-mi-command symbol-list-lines
+ ^done,command={exists="true"}
+
+The '-list-features' Command
+----------------------------
+
+Returns a list of particular features of the MI protocol that this
+version of gdb implements. A feature can be a command, or a new field
+in an output of some command, or even an important bugfix. While a
+frontend can sometimes detect presence of a feature at runtime, it is
+easier to perform detection at debugger startup.
+
+ The command returns a list of strings, with each string naming an
+available feature. Each returned string is just a name, it does not
+have any internal structure. The list of possible feature names is
+given below.
+
+ Example output:
+
+ (gdb) -list-features
+ ^done,result=["feature1","feature2"]
+
+ The current list of features is:
+
+'frozen-varobjs'
+ Indicates support for the '-var-set-frozen' command, as well as
+ possible presense of the 'frozen' field in the output of
+ '-varobj-create'.
+'pending-breakpoints'
+ Indicates support for the '-f' option to the '-break-insert'
+ command.
+'python'
+ Indicates Python scripting support, Python-based pretty-printing
+ commands, and possible presence of the 'display_hint' field in the
+ output of '-var-list-children'
+'thread-info'
+ Indicates support for the '-thread-info' command.
+'data-read-memory-bytes'
+ Indicates support for the '-data-read-memory-bytes' and the
+ '-data-write-memory-bytes' commands.
+'breakpoint-notifications'
+ Indicates that changes to breakpoints and breakpoints created via
+ the CLI will be announced via async records.
+'ada-task-info'
+ Indicates support for the '-ada-task-info' command.
+'language-option'
+ Indicates that all GDB/MI commands accept the '--language' option
+ (*note Context management::).
+'info-gdb-mi-command'
+ Indicates support for the '-info-gdb-mi-command' command.
+'undefined-command-error-code'
+ Indicates support for the "undefined-command" error code in error
+ result records, produced when trying to execute an undefined GDB/MI
+ command (*note GDB/MI Result Records::).
+'exec-run-start-option'
+ Indicates that the '-exec-run' command supports the '--start'
+ option (*note GDB/MI Program Execution::).
+
+The '-list-target-features' Command
+-----------------------------------
+
+Returns a list of particular features that are supported by the target.
+Those features affect the permitted MI commands, but unlike the features
+reported by the '-list-features' command, the features depend on which
+target GDB is using at the moment. Whenever a target can change, due to
+commands such as '-target-select', '-target-attach' or '-exec-run', the
+list of target features may change, and the frontend should obtain it
+again. Example output:
+
+ (gdb) -list-target-features
+ ^done,result=["async"]
+
+ The current list of features is:
+
+'async'
+ Indicates that the target is capable of asynchronous command
+ execution, which means that GDB will accept further commands while
+ the target is running.
+
+'reverse'
+ Indicates that the target is capable of reverse execution. *Note
+ Reverse Execution::, for more information.
\1f
-File: gdb.info, Node: PowerPC Features, Next: TIC6x Features, Prev: M68K Features, Up: Standard Target Features
+File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI
+
+27.24 Miscellaneous GDB/MI Commands
+===================================
+
+The '-gdb-exit' Command
+-----------------------
+
+Synopsis
+........
-G.4.5 PowerPC Features
+ -gdb-exit
+
+ Exit GDB immediately.
+
+GDB Command
+...........
+
+Approximately corresponds to 'quit'.
+
+Example
+.......
+
+ (gdb)
+ -gdb-exit
+ ^exit
+
+The '-gdb-set' Command
----------------------
-The `org.gnu.gdb.power.core' feature is required for PowerPC targets.
-It should contain registers `r0' through `r31', `pc', `msr', `cr',
-`lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the
+Synopsis
+........
+
+ -gdb-set
+
+ Set an internal GDB variable.
+
+GDB Command
+...........
+
+The corresponding GDB command is 'set'.
+
+Example
+.......
+
+ (gdb)
+ -gdb-set $foo=3
+ ^done
+ (gdb)
+
+The '-gdb-show' Command
+-----------------------
+
+Synopsis
+........
+
+ -gdb-show
+
+ Show the current value of a GDB variable.
+
+GDB Command
+...........
+
+The corresponding GDB command is 'show'.
+
+Example
+.......
+
+ (gdb)
+ -gdb-show annotate
+ ^done,value="0"
+ (gdb)
+
+The '-gdb-version' Command
+--------------------------
+
+Synopsis
+........
+
+ -gdb-version
+
+ Show version information for GDB. Used mostly in testing.
+
+GDB Command
+...........
+
+The GDB equivalent is 'show version'. GDB by default shows this
+information when you start an interactive session.
+
+Example
+.......
+
+ (gdb)
+ -gdb-version
+ ~GNU gdb 5.2.1
+ ~Copyright 2000 Free Software Foundation, Inc.
+ ~GDB is free software, covered by the GNU General Public License, and
+ ~you are welcome to change it and/or distribute copies of it under
+ ~ certain conditions.
+ ~Type "show copying" to see the conditions.
+ ~There is absolutely no warranty for GDB. Type "show warranty" for
+ ~ details.
+ ~This GDB was configured as
+ "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
+ ^done
+ (gdb)
+
+The '-list-thread-groups' Command
+---------------------------------
+
+Synopsis
+--------
+
+ -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
+
+ Lists thread groups (*note Thread groups::). When a single thread
+group is passed as the argument, lists the children of that group. When
+several thread group are passed, lists information about those thread
+groups. Without any parameters, lists information about all top-level
+thread groups.
+
+ Normally, thread groups that are being debugged are reported. With
+the '--available' option, GDB reports thread groups available on the
target.
- The `org.gnu.gdb.power.fpu' feature is optional. It should contain
-registers `f0' through `f31' and `fpscr'.
+ The output of this command may have either a 'threads' result or a
+'groups' result. The 'thread' result has a list of tuples as value,
+with each tuple describing a thread (*note GDB/MI Thread Information::).
+The 'groups' result has a list of tuples as value, each tuple describing
+a thread group. If top-level groups are requested (that is, no
+parameter is passed), or when several groups are passed, the output
+always has a 'groups' result. The format of the 'group' result is
+described below.
+
+ To reduce the number of roundtrips it's possible to list thread
+groups together with their children, by passing the '--recurse' option
+and the recursion depth. Presently, only recursion depth of 1 is
+permitted. If this option is present, then every reported thread group
+will also include its children, either as 'group' or 'threads' field.
+
+ In general, any combination of option and parameters is permitted,
+with the following caveats:
+
+ * When a single thread group is passed, the output will typically be
+ the 'threads' result. Because threads may not contain anything,
+ the 'recurse' option will be ignored.
+
+ * When the '--available' option is passed, limited information may be
+ available. In particular, the list of threads of a process might
+ be inaccessible. Further, specifying specific thread groups might
+ not give any performance advantage over listing all thread groups.
+ The frontend should assume that '-list-thread-groups --available'
+ is always an expensive operation and cache the results.
+
+ The 'groups' result is a list of tuples, where each tuple may have
+the following fields:
+
+'id'
+ Identifier of the thread group. This field is always present. The
+ identifier is an opaque string; frontends should not try to convert
+ it to an integer, even though it might look like one.
+
+'type'
+ The type of the thread group. At present, only 'process' is a
+ valid type.
+
+'pid'
+ The target-specific process identifier. This field is only present
+ for thread groups of type 'process' and only if the process exists.
+
+'exit-code'
+ The exit code of this group's last exited thread, formatted in
+ octal. This field is only present for thread groups of type
+ 'process' and only if the process is not running.
+
+'num_children'
+ The number of children this thread group has. This field may be
+ absent for an available thread group.
+
+'threads'
+ This field has a list of tuples as value, each tuple describing a
+ thread. It may be present if the '--recurse' option is specified,
+ and it's actually possible to obtain the threads.
+
+'cores'
+ This field is a list of integers, each identifying a core that one
+ thread of the group is running on. This field may be absent if
+ such information is not available.
+
+'executable'
+ The name of the executable file that corresponds to this thread
+ group. The field is only present for thread groups of type
+ 'process', and only if there is a corresponding executable file.
+
+Example
+-------
+
+ gdb
+ -list-thread-groups
+ ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
+ -list-thread-groups 17
+ ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
+ {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+ frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
+ -list-thread-groups --available
+ ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
+ -list-thread-groups --available --recurse 1
+ ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
+ threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
+ {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
+ -list-thread-groups --available --recurse 1 17 18
+ ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
+ threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
+ {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
+
+The '-info-os' Command
+----------------------
- The `org.gnu.gdb.power.altivec' feature is optional. It should
-contain registers `vr0' through `vr31', `vscr', and `vrsave'.
+Synopsis
+........
- The `org.gnu.gdb.power.vsx' feature is optional. It should contain
-registers `vs0h' through `vs31h'. GDB will combine these registers
-with the floating point registers (`f0' through `f31') and the altivec
-registers (`vr0' through `vr31') to present the 128-bit wide registers
-`vs0' through `vs63', the set of vector registers for POWER7.
+ -info-os [ TYPE ]
- The `org.gnu.gdb.power.spe' feature is optional. It should contain
-registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets
-should provide 32-bit registers in `org.gnu.gdb.power.core' and provide
-the upper halves in `ev0h' through `ev31h'. GDB will combine these to
-present registers `ev0' through `ev31' to the user.
+ If no argument is supplied, the command returns a table of available
+operating-system-specific information types. If one of these types is
+supplied as an argument TYPE, then the command returns a table of data
+of that type.
-\1f
-File: gdb.info, Node: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features
+ The types of information available depend on the target operating
+system.
-G.4.6 TMS320C6x Features
-------------------------
+GDB Command
+...........
+
+The corresponding GDB command is 'info os'.
+
+Example
+.......
+
+When run on a GNU/Linux system, the output will look something like
+this:
+
+ gdb
+ -info-os
+ ^done,OSDataTable={nr_rows="9",nr_cols="3",
+ hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"},
+ {width="10",alignment="-1",col_name="col1",colhdr="Description"},
+ {width="10",alignment="-1",col_name="col2",colhdr="Title"}],
+ body=[item={col0="processes",col1="Listing of all processes",
+ col2="Processes"},
+ item={col0="procgroups",col1="Listing of all process groups",
+ col2="Process groups"},
+ item={col0="threads",col1="Listing of all threads",
+ col2="Threads"},
+ item={col0="files",col1="Listing of all file descriptors",
+ col2="File descriptors"},
+ item={col0="sockets",col1="Listing of all internet-domain sockets",
+ col2="Sockets"},
+ item={col0="shm",col1="Listing of all shared-memory regions",
+ col2="Shared-memory regions"},
+ item={col0="semaphores",col1="Listing of all semaphores",
+ col2="Semaphores"},
+ item={col0="msg",col1="Listing of all message queues",
+ col2="Message queues"},
+ item={col0="modules",col1="Listing of all loaded kernel modules",
+ col2="Kernel modules"}]}
+ gdb
+ -info-os processes
+ ^done,OSDataTable={nr_rows="190",nr_cols="4",
+ hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"},
+ {width="10",alignment="-1",col_name="col1",colhdr="user"},
+ {width="10",alignment="-1",col_name="col2",colhdr="command"},
+ {width="10",alignment="-1",col_name="col3",colhdr="cores"}],
+ body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"},
+ item={col0="2",col1="root",col2="[kthreadd]",col3="1"},
+ item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"},
+ ...
+ item={col0="26446",col1="stan",col2="bash",col3="0"},
+ item={col0="28152",col1="stan",col2="bash",col3="1"}]}
+ (gdb)
+
+ (Note that the MI output here includes a '"Title"' column that does
+not appear in command-line 'info os'; this column is useful for MI
+clients that want to enumerate the types of data, such as in a popup
+menu, but is needless clutter on the command line, and 'info os' omits
+it.)
+
+The '-add-inferior' Command
+---------------------------
+
+Synopsis
+--------
+
+ -add-inferior
+
+ Creates a new inferior (*note Inferiors and Programs::). The created
+inferior is not associated with any executable. Such association may be
+established with the '-file-exec-and-symbols' command (*note GDB/MI File
+Commands::). The command response has a single field, 'inferior', whose
+value is the identifier of the thread group corresponding to the new
+inferior.
+
+Example
+-------
+
+ gdb
+ -add-inferior
+ ^done,inferior="i3"
+
+The '-interpreter-exec' Command
+-------------------------------
+
+Synopsis
+--------
+
+ -interpreter-exec INTERPRETER COMMAND
+
+ Execute the specified COMMAND in the given INTERPRETER.
+
+GDB Command
+-----------
+
+The corresponding GDB command is 'interpreter-exec'.
+
+Example
+-------
+
+ (gdb)
+ -interpreter-exec console "break main"
+ &"During symbol reading, couldn't parse type; debugger out of date?.\n"
+ &"During symbol reading, bad structure-type format.\n"
+ ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
+ ^done
+ (gdb)
+
+The '-inferior-tty-set' Command
+-------------------------------
+
+Synopsis
+--------
+
+ -inferior-tty-set /dev/pts/1
+
+ Set terminal for future runs of the program being debugged.
+
+GDB Command
+-----------
+
+The corresponding GDB command is 'set inferior-tty' /dev/pts/1.
+
+Example
+-------
+
+ (gdb)
+ -inferior-tty-set /dev/pts/1
+ ^done
+ (gdb)
+
+The '-inferior-tty-show' Command
+--------------------------------
+
+Synopsis
+--------
+
+ -inferior-tty-show
+
+ Show terminal for future runs of program being debugged.
+
+GDB Command
+-----------
+
+The corresponding GDB command is 'show inferior-tty'.
+
+Example
+-------
+
+ (gdb)
+ -inferior-tty-set /dev/pts/1
+ ^done
+ (gdb)
+ -inferior-tty-show
+ ^done,inferior_tty_terminal="/dev/pts/1"
+ (gdb)
+
+The '-enable-timings' Command
+-----------------------------
+
+Synopsis
+--------
+
+ -enable-timings [yes | no]
-The `org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets.
-It should contain registers `A0' through `A15', registers `B0' through
-`B15', `CSR' and `PC'.
+ Toggle the printing of the wallclock, user and system times for an MI
+command as a field in its output. This command is to help frontend
+developers optimize the performance of their code. No argument is
+equivalent to 'yes'.
- The `org.gnu.gdb.tic6x.gp' feature is optional. It should contain
-registers `A16' through `A31' and `B16' through `B31'.
+GDB Command
+-----------
- The `org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain
-registers `TSR', `ILC' and `RILC'.
+No equivalent.
+
+Example
+-------
+
+ (gdb)
+ -enable-timings
+ ^done
+ (gdb)
+ -break-insert main
+ ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
+ addr="0x080484ed",func="main",file="myprog.c",
+ fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
+ times="0"},
+ time={wallclock="0.05185",user="0.00800",system="0.00000"}
+ (gdb)
+ -enable-timings no
+ ^done
+ (gdb)
+ -exec-run
+ ^running
+ (gdb)
+ *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
+ frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
+ {name="argv",value="0xbfb60364"}],file="myprog.c",
+ fullname="/home/nickrob/myprog.c",line="73"}
+ (gdb)
\1f
-File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top
+File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
+
+28 GDB Annotations
+******************
-Appendix H Operating System Information
-***************************************
+This chapter describes annotations in GDB. Annotations were designed to
+interface GDB to graphical user interfaces or other similar programs
+which want to interact with GDB at a relatively high level.
+
+ The annotation mechanism has largely been superseded by GDB/MI (*note
+GDB/MI::).
* Menu:
-* Process list::
+* Annotations Overview:: What annotations are; the general syntax.
+* Server Prefix:: Issuing a command without affecting user state.
+* Prompting:: Annotations marking GDB's need for input.
+* Errors:: Annotations for error messages.
+* Invalidation:: Some annotations describe things now invalid.
+* Annotations for Running::
+ Whether the program is running, how it stopped, etc.
+* Source Annotations:: Annotations describing source code.
+
+\1f
+File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
- Users of GDB often wish to obtain information about the state of the
-operating system running on the target--for example the list of
-processes, or the list of open files. This section describes the
-mechanism that makes it possible. This mechanism is similar to the
-target features mechanism (*note Target Descriptions::), but focuses on
-a different aspect of target.
+28.1 What is an Annotation?
+===========================
- Operating system information is retrived from the target via the
-remote protocol, using `qXfer' requests (*note qXfer osdata read::).
-The object name in the request should be `osdata', and the ANNEX
-identifies the data to be fetched.
+Annotations start with a newline character, two 'control-z' characters,
+and the name of the annotation. If there is no additional information
+associated with this annotation, the name of the annotation is followed
+immediately by a newline. If there is additional information, the name
+of the annotation is followed by a space, the additional information,
+and a newline. The additional information cannot contain newline
+characters.
+
+ Any output not beginning with a newline and two 'control-z'
+characters denotes literal output from GDB. Currently there is no need
+for GDB to output a newline followed by two 'control-z' characters, but
+if there was such a need, the annotations could be extended with an
+'escape' annotation which means those three characters as output.
+
+ The annotation LEVEL, which is specified using the '--annotate'
+command line option (*note Mode Options::), controls how much
+information GDB prints together with its prompt, values of expressions,
+source lines, and other types of output. Level 0 is for no annotations,
+level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3
+is the maximum annotation suitable for programs that control GDB, and
+level 2 annotations have been made obsolete (*note Limitations of the
+Annotation Interface: (annotate)Limitations.).
+
+'set annotate LEVEL'
+ The GDB command 'set annotate' sets the level of annotations to the
+ specified LEVEL.
+
+'show annotate'
+ Show the current annotation level.
+
+ This chapter describes level 3 annotations.
+
+ A simple example of starting up GDB with annotations is:
+
+ $ gdb --annotate=3
+ GNU gdb 6.0
+ Copyright 2003 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License,
+ and you are welcome to change it and/or distribute copies of it
+ under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty"
+ for details.
+ This GDB was configured as "i386-pc-linux-gnu"
+
+ ^Z^Zpre-prompt
+ (gdb)
+ ^Z^Zprompt
+ quit
+
+ ^Z^Zpost-prompt
+ $
+
+ Here 'quit' is input to GDB; the rest is output from GDB. The three
+lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are
+annotations; the rest is output from GDB.
\1f
-File: gdb.info, Node: Process list, Up: Operating System Information
-
-H.1 Process list
-================
-
-When requesting the process list, the ANNEX field in the `qXfer'
-request should be `processes'. The returned data is an XML document.
-The formal syntax of this document is defined in
-`gdb/features/osdata.dtd'.
-
- An example document is:
-
- <?xml version="1.0"?>
- <!DOCTYPE target SYSTEM "osdata.dtd">
- <osdata type="processes">
- <item>
- <column name="pid">1</column>
- <column name="user">root</column>
- <column name="command">/sbin/init</column>
- <column name="cores">1,2,3</column>
- </item>
- </osdata>
-
- Each item should include a column whose name is `pid'. The value of
-that column should identify the process on the target. The `user' and
-`command' columns are optional, and will be displayed by GDB. The
-`cores' column, if present, should contain a comma-separated list of
-cores that this process is running on. Target may provide additional
-columns, which GDB currently ignores.
+File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
+
+28.2 The Server Prefix
+======================
+
+If you prefix a command with 'server ' then it will not affect the
+command history, nor will it affect GDB's notion of which command to
+repeat if <RET> is pressed on a line by itself. This means that
+commands can be run behind a user's back by a front-end in a transparent
+manner.
+
+ The 'server ' prefix does not affect the recording of values into the
+value history; to print a value without recording it into the value
+history, use the 'output' command instead of the 'print' command.
+
+ Using this prefix also disables confirmation requests (*note
+confirmation requests::).
\1f
-File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top
+File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
-Appendix I Trace File Format
-****************************
+28.3 Annotation for GDB Input
+=============================
+
+When GDB prompts for input, it annotates this fact so it is possible to
+know when to send output, when the output from a given command is over,
+etc.
+
+ Different kinds of input each have a different "input type". Each
+input type has three annotations: a 'pre-' annotation, which denotes the
+beginning of any prompt which is being output, a plain annotation, which
+denotes the end of the prompt, and then a 'post-' annotation which
+denotes the end of any echo which may (or may not) be associated with
+the input. For example, the 'prompt' input type features the following
+annotations:
+
+ ^Z^Zpre-prompt
+ ^Z^Zprompt
+ ^Z^Zpost-prompt
+
+ The input types are
+
+'prompt'
+ When GDB is prompting for a command (the main GDB prompt).
+
+'commands'
+ When GDB prompts for a set of commands, like in the 'commands'
+ command. The annotations are repeated for each command which is
+ input.
+
+'overload-choice'
+ When GDB wants the user to select between various overloaded
+ functions.
+
+'query'
+ When GDB wants the user to confirm a potentially dangerous
+ operation.
+
+'prompt-for-continue'
+ When GDB is asking the user to press return to continue. Note:
+ Don't expect this to work well; instead use 'set height 0' to
+ disable prompting. This is because the counting of lines is buggy
+ in the presence of annotations.
+
+\1f
+File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
-The trace file comes in three parts: a header, a textual description
-section, and a trace frame section with binary data.
+28.4 Errors
+===========
+
+ ^Z^Zquit
- The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so
-as to indicate that the file contains binary data, while the `0' is a
-version number that may have different values in the future.
+ This annotation occurs right before GDB responds to an interrupt.
- The description section consists of multiple lines of ASCII text
-separated by newline characters (`0xa'). The lines may include a
-variety of optional descriptive or context-setting information, such as
-tracepoint definitions or register set size. GDB will ignore any line
-that it does not recognize. An empty line marks the end of this
-section.
+ ^Z^Zerror
- The trace frame section consists of a number of consecutive frames.
-Each frame begins with a two-byte tracepoint number, followed by a
-four-byte size giving the amount of data in the frame. The data in the
-frame consists of a number of blocks, each introduced by a character
-indicating its type (at least register, memory, and trace state
-variable). The data in this section is raw binary, not a hexadecimal
-or other encoding; its endianness matches the target's endianness.
+ This annotation occurs right before GDB responds to an error.
-`R BYTES'
- Register block. The number and ordering of bytes matches that of a
- `g' packet in the remote protocol. Note that these are the actual
- bytes, in target order and GDB register order, not a hexadecimal
- encoding.
+ Quit and error annotations indicate that any annotations which GDB
+was in the middle of may end abruptly. For example, if a
+'value-history-begin' annotation is followed by a 'error', one cannot
+expect to receive the matching 'value-history-end'. One cannot expect
+not to receive it either, however; an error annotation does not
+necessarily mean that GDB is immediately returning all the way to the
+top level.
-`M ADDRESS LENGTH BYTES...'
- Memory block. This is a contiguous block of memory, at the 8-byte
- address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
- bytes.
+ A quit or error annotation may be preceded by
-`V NUMBER VALUE'
- Trace state variable block. This records the 8-byte signed value
- VALUE of trace state variable numbered NUMBER.
+ ^Z^Zerror-begin
+ Any output between that and the quit or error annotation is the error
+message.
- Future enhancements of the trace file format may include additional
-types of blocks.
+ Warning messages are not yet annotated.
\1f
-File: gdb.info, Node: Index Section Format, Next: Copying, Prev: Trace File Format, Up: Top
+File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
+
+28.5 Invalidation Notices
+=========================
-Appendix J `.gdb_index' section format
-**************************************
+The following annotations say that certain pieces of state may have
+changed.
-This section documents the index section that is created by `save
-gdb-index' (*note Index Files::). The index section is DWARF-specific;
-some knowledge of DWARF is assumed in this description.
+'^Z^Zframes-invalid'
- The mapped index file format is designed to be directly `mmap'able
-on any architecture. In most cases, a datum is represented using a
-little-endian 32-bit integer value, called an `offset_type'. Big
-endian machines must byte-swap the values before using them.
-Exceptions to this rule are noted. The data is laid out such that
-alignment is always respected.
+ The frames (for example, output from the 'backtrace' command) may
+ have changed.
+
+'^Z^Zbreakpoints-invalid'
+
+ The breakpoints may have changed. For example, the user just added
+ or deleted a breakpoint.
+
+\1f
+File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
- A mapped index consists of several areas, laid out in order.
+28.6 Running the Program
+========================
- 1. The file header. This is a sequence of values, of `offset_type'
- unless otherwise noted:
+When the program starts executing due to a GDB command such as 'step' or
+'continue',
- 1. The version number, currently 7. Versions 1, 2 and 3 are
- obsolete. Version 4 uses a different hashing function from
- versions 5 and 6. Version 6 includes symbols for inlined
- functions, whereas versions 4 and 5 do not. Version 7 adds
- attributes to the CU indices in the symbol table. GDB will
- only read version 4, 5, or 6 indices by specifying `set
- use-deprecated-index-sections on'.
+ ^Z^Zstarting
- 2. The offset, from the start of the file, of the CU list.
+ is output. When the program stops,
- 3. The offset, from the start of the file, of the types CU list.
- Note that this area can be empty, in which case this offset
- will be equal to the next offset.
+ ^Z^Zstopped
- 4. The offset, from the start of the file, of the address area.
+ is output. Before the 'stopped' annotation, a variety of annotations
+describe how the program stopped.
- 5. The offset, from the start of the file, of the symbol table.
+'^Z^Zexited EXIT-STATUS'
+ The program exited, and EXIT-STATUS is the exit status (zero for
+ successful exit, otherwise nonzero).
- 6. The offset, from the start of the file, of the constant pool.
+'^Z^Zsignalled'
+ The program exited with a signal. After the '^Z^Zsignalled', the
+ annotation continues:
- 2. The CU list. This is a sequence of pairs of 64-bit little-endian
- values, sorted by the CU offset. The first element in each pair is
- the offset of a CU in the `.debug_info' section. The second
- element in each pair is the length of that CU. References to a CU
- elsewhere in the map are done using a CU index, which is just the
- 0-based index into this table. Note that if there are type CUs,
- then conceptually CUs and type CUs form a single list for the
- purposes of CU indices.
+ INTRO-TEXT
+ ^Z^Zsignal-name
+ NAME
+ ^Z^Zsignal-name-end
+ MIDDLE-TEXT
+ ^Z^Zsignal-string
+ STRING
+ ^Z^Zsignal-string-end
+ END-TEXT
- 3. The types CU list. This is a sequence of triplets of 64-bit
- little-endian values. In a triplet, the first value is the CU
- offset, the second value is the type offset in the CU, and the
- third value is the type signature. The types CU list is not
- sorted.
+ where NAME is the name of the signal, such as 'SIGILL' or
+ 'SIGSEGV', and STRING is the explanation of the signal, such as
+ 'Illegal Instruction' or 'Segmentation fault'. The arguments
+ INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit
+ and have no particular format.
- 4. The address area. The address area consists of a sequence of
- address entries. Each address entry has three elements:
+'^Z^Zsignal'
+ The syntax of this annotation is just like 'signalled', but GDB is
+ just saying that the program received the signal, not that it was
+ terminated with it.
- 1. The low address. This is a 64-bit little-endian value.
+'^Z^Zbreakpoint NUMBER'
+ The program hit breakpoint number NUMBER.
- 2. The high address. This is a 64-bit little-endian value. Like
- `DW_AT_high_pc', the value is one byte beyond the end.
+'^Z^Zwatchpoint NUMBER'
+ The program hit watchpoint number NUMBER.
- 3. The CU index. This is an `offset_type' value.
+\1f
+File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
- 5. The symbol table. This is an open-addressed hash table. The size
- of the hash table is always a power of 2.
+28.7 Displaying Source
+======================
- Each slot in the hash table consists of a pair of `offset_type'
- values. The first value is the offset of the symbol's name in the
- constant pool. The second value is the offset of the CU vector in
- the constant pool.
+The following annotation is used instead of displaying source code:
- If both values are 0, then this slot in the hash table is empty.
- This is ok because while 0 is a valid constant pool index, it
- cannot be a valid index for both a string and a CU vector.
+ ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
- The hash value for a table entry is computed by applying an
- iterative hash function to the symbol's name. Starting with an
- initial value of `r = 0', each (unsigned) character `c' in the
- string is incorporated into the hash using the formula depending
- on the index version:
-
- Version 4
- The formula is `r = r * 67 + c - 113'.
-
- Versions 5 to 7
- The formula is `r = r * 67 + tolower (c) - 113'.
-
- The terminating `\0' is not incorporated into the hash.
-
- The step size used in the hash table is computed via `((hash * 17)
- & (size - 1)) | 1', where `hash' is the hash value, and `size' is
- the size of the hash table. The step size is used to find the
- next candidate slot when handling a hash collision.
-
- The names of C++ symbols in the hash table are canonicalized. We
- don't currently have a simple description of the canonicalization
- algorithm; if you intend to create new index sections, you must
- read the code.
-
- 6. The constant pool. This is simply a bunch of bytes. It is
- organized so that alignment is correct: CU vectors are stored
- first, followed by strings.
-
- A CU vector in the constant pool is a sequence of `offset_type'
- values. The first value is the number of CU indices in the vector.
- Each subsequent value is the index and symbol attributes of a CU in
- the CU list. This element in the hash table is used to indicate
- which CUs define the symbol and how the symbol is used. See below
- for the format of each CU index+attributes entry.
-
- A string in the constant pool is zero-terminated.
-
- Attributes were added to CU index values in `.gdb_index' version 7.
-If a symbol has multiple uses within a CU then there is one CU
-index+attributes value for each use.
-
- The format of each CU index+attributes entry is as follows (bit 0 =
-LSB):
-
-Bits 0-23
- This is the index of the CU in the CU list.
-
-Bits 24-27
- These bits are reserved for future purposes and must be zero.
-
-Bits 28-30
- The kind of the symbol in the CU.
-
- 0
- This value is reserved and should not be used. By reserving
- zero the full `offset_type' value is backwards compatible
- with previous versions of the index.
-
- 1
- The symbol is a type.
-
- 2
- The symbol is a variable or an enum value.
-
- 3
- The symbol is a function.
-
- 4
- Any other kind of symbol.
-
- 5,6,7
- These values are reserved.
-
-Bit 31
- This bit is zero if the value is global and one if it is static.
-
- The determination of whether a symbol is global or static is
- complicated. The authorative reference is the file `dwarf2read.c'
- in GDB sources.
-
-
- This pseudo-code describes the computation of a symbol's kind and
-global/static attributes in the index.
-
- is_external = get_attribute (die, DW_AT_external);
- language = get_attribute (cu_die, DW_AT_language);
- switch (die->tag)
- {
- case DW_TAG_typedef:
- case DW_TAG_base_type:
- case DW_TAG_subrange_type:
- kind = TYPE;
- is_static = 1;
- break;
- case DW_TAG_enumerator:
- kind = VARIABLE;
- is_static = (language != CPLUS && language != JAVA);
- break;
- case DW_TAG_subprogram:
- kind = FUNCTION;
- is_static = ! (is_external || language == ADA);
- break;
- case DW_TAG_constant:
- kind = VARIABLE;
- is_static = ! is_external;
- break;
- case DW_TAG_variable:
- kind = VARIABLE;
- is_static = ! is_external;
- break;
- case DW_TAG_namespace:
- kind = TYPE;
- is_static = 0;
- break;
- case DW_TAG_class_type:
- case DW_TAG_interface_type:
- case DW_TAG_structure_type:
- case DW_TAG_union_type:
- case DW_TAG_enumeration_type:
- kind = TYPE;
- is_static = (language != CPLUS && language != JAVA);
- break;
- default:
- assert (0);
- }
+ where FILENAME is an absolute file name indicating which source file,
+LINE is the line number within that file (where 1 is the first line in
+the file), CHARACTER is the character position within the file (where 0
+is the first character in the file) (for most debug formats this will
+necessarily point to the beginning of a line), MIDDLE is 'middle' if
+ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning
+of the line, and ADDR is the address in the target program associated
+with the source which is being displayed. The ADDR is in the form '0x'
+followed by one or more lowercase hex digits (note that this does not
+depend on the language).
\1f
-File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Index Section Format, Up: Top
-
-Appendix K GNU GENERAL PUBLIC LICENSE
-*************************************
-
- Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
-
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
-
-Preamble
-========
-
-The GNU General Public License is a free, copyleft license for software
-and other kinds of works.
-
- The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works. By contrast,
-the GNU General Public License is intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains
-free software for all its users. We, the Free Software Foundation, use
-the GNU General Public License for most of our software; it applies
-also to any other work released this way by its authors. You can apply
-it to your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
- To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights. Therefore, you
-have certain responsibilities if you distribute copies of the software,
-or if you modify it: responsibilities to respect the freedom of others.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received. You must make sure that they, too, receive
-or can get the source code. And you must show them these terms so they
-know their rights.
-
- Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
-
- For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software. For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
- Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the
-manufacturer can do so. This is fundamentally incompatible with the
-aim of protecting users' freedom to change the software. The
-systematic pattern of such abuse occurs in the area of products for
-individuals to use, which is precisely where it is most unacceptable.
-Therefore, we have designed this version of the GPL to prohibit the
-practice for those products. If such problems arise substantially in
-other domains, we stand ready to extend this provision to those domains
-in future versions of the GPL, as needed to protect the freedom of
-users.
-
- Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish to
-avoid the special danger that patents applied to a free program could
-make it effectively proprietary. To prevent this, the GPL assures that
-patents cannot be used to render the program non-free.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
-TERMS AND CONDITIONS
-====================
-
- 0. Definitions.
-
- "This License" refers to version 3 of the GNU General Public
- License.
-
- "Copyright" also means copyright-like laws that apply to other
- kinds of works, such as semiconductor masks.
-
- "The Program" refers to any copyrightable work licensed under this
- License. Each licensee is addressed as "you". "Licensees" and
- "recipients" may be individuals or organizations.
-
- To "modify" a work means to copy from or adapt all or part of the
- work in a fashion requiring copyright permission, other than the
- making of an exact copy. The resulting work is called a "modified
- version" of the earlier work or a work "based on" the earlier work.
-
- A "covered work" means either the unmodified Program or a work
- based on the Program.
-
- To "propagate" a work means to do anything with it that, without
- permission, would make you directly or secondarily liable for
- infringement under applicable copyright law, except executing it
- on a computer or modifying a private copy. Propagation includes
- copying, distribution (with or without modification), making
- available to the public, and in some countries other activities as
- well.
-
- To "convey" a work means any kind of propagation that enables other
- parties to make or receive copies. Mere interaction with a user
- through a computer network, with no transfer of a copy, is not
- conveying.
-
- An interactive user interface displays "Appropriate Legal Notices"
- to the extent that it includes a convenient and prominently visible
- feature that (1) displays an appropriate copyright notice, and (2)
- tells the user that there is no warranty for the work (except to
- the extent that warranties are provided), that licensees may
- convey the work under this License, and how to view a copy of this
- License. If the interface presents a list of user commands or
- options, such as a menu, a prominent item in the list meets this
- criterion.
-
- 1. Source Code.
-
- The "source code" for a work means the preferred form of the work
- for making modifications to it. "Object code" means any
- non-source form of a work.
-
- A "Standard Interface" means an interface that either is an
- official standard defined by a recognized standards body, or, in
- the case of interfaces specified for a particular programming
- language, one that is widely used among developers working in that
- language.
-
- The "System Libraries" of an executable work include anything,
- other than the work as a whole, that (a) is included in the normal
- form of packaging a Major Component, but which is not part of that
- Major Component, and (b) serves only to enable use of the work
- with that Major Component, or to implement a Standard Interface
- for which an implementation is available to the public in source
- code form. A "Major Component", in this context, means a major
- essential component (kernel, window system, and so on) of the
- specific operating system (if any) on which the executable work
- runs, or a compiler used to produce the work, or an object code
- interpreter used to run it.
-
- The "Corresponding Source" for a work in object code form means all
- the source code needed to generate, install, and (for an executable
- work) run the object code and to modify the work, including
- scripts to control those activities. However, it does not include
- the work's System Libraries, or general-purpose tools or generally
- available free programs which are used unmodified in performing
- those activities but which are not part of the work. For example,
- Corresponding Source includes interface definition files
- associated with source files for the work, and the source code for
- shared libraries and dynamically linked subprograms that the work
- is specifically designed to require, such as by intimate data
- communication or control flow between those subprograms and other
- parts of the work.
-
- The Corresponding Source need not include anything that users can
- regenerate automatically from other parts of the Corresponding
- Source.
-
- The Corresponding Source for a work in source code form is that
- same work.
-
- 2. Basic Permissions.
-
- All rights granted under this License are granted for the term of
- copyright on the Program, and are irrevocable provided the stated
- conditions are met. This License explicitly affirms your unlimited
- permission to run the unmodified Program. The output from running
- a covered work is covered by this License only if the output,
- given its content, constitutes a covered work. This License
- acknowledges your rights of fair use or other equivalent, as
- provided by copyright law.
-
- You may make, run and propagate covered works that you do not
- convey, without conditions so long as your license otherwise
- remains in force. You may convey covered works to others for the
- sole purpose of having them make modifications exclusively for
- you, or provide you with facilities for running those works,
- provided that you comply with the terms of this License in
- conveying all material for which you do not control copyright.
- Those thus making or running the covered works for you must do so
- exclusively on your behalf, under your direction and control, on
- terms that prohibit them from making any copies of your
- copyrighted material outside their relationship with you.
-
- Conveying under any other circumstances is permitted solely under
- the conditions stated below. Sublicensing is not allowed; section
- 10 makes it unnecessary.
-
- 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
- No covered work shall be deemed part of an effective technological
- measure under any applicable law fulfilling obligations under
- article 11 of the WIPO copyright treaty adopted on 20 December
- 1996, or similar laws prohibiting or restricting circumvention of
- such measures.
-
- When you convey a covered work, you waive any legal power to forbid
- circumvention of technological measures to the extent such
- circumvention is effected by exercising rights under this License
- with respect to the covered work, and you disclaim any intention
- to limit operation or modification of the work as a means of
- enforcing, against the work's users, your or third parties' legal
- rights to forbid circumvention of technological measures.
-
- 4. Conveying Verbatim Copies.
-
- You may convey verbatim copies of the Program's source code as you
- receive it, in any medium, provided that you conspicuously and
- appropriately publish on each copy an appropriate copyright notice;
- keep intact all notices stating that this License and any
- non-permissive terms added in accord with section 7 apply to the
- code; keep intact all notices of the absence of any warranty; and
- give all recipients a copy of this License along with the Program.
-
- You may charge any price or no price for each copy that you convey,
- and you may offer support or warranty protection for a fee.
-
- 5. Conveying Modified Source Versions.
-
- You may convey a work based on the Program, or the modifications to
- produce it from the Program, in the form of source code under the
- terms of section 4, provided that you also meet all of these
- conditions:
-
- a. The work must carry prominent notices stating that you
- modified it, and giving a relevant date.
-
- b. The work must carry prominent notices stating that it is
- released under this License and any conditions added under
- section 7. This requirement modifies the requirement in
- section 4 to "keep intact all notices".
-
- c. You must license the entire work, as a whole, under this
- License to anyone who comes into possession of a copy. This
- License will therefore apply, along with any applicable
- section 7 additional terms, to the whole of the work, and all
- its parts, regardless of how they are packaged. This License
- gives no permission to license the work in any other way, but
- it does not invalidate such permission if you have separately
- received it.
-
- d. If the work has interactive user interfaces, each must display
- Appropriate Legal Notices; however, if the Program has
- interactive interfaces that do not display Appropriate Legal
- Notices, your work need not make them do so.
-
- A compilation of a covered work with other separate and independent
- works, which are not by their nature extensions of the covered
- work, and which are not combined with it such as to form a larger
- program, in or on a volume of a storage or distribution medium, is
- called an "aggregate" if the compilation and its resulting
- copyright are not used to limit the access or legal rights of the
- compilation's users beyond what the individual works permit.
- Inclusion of a covered work in an aggregate does not cause this
- License to apply to the other parts of the aggregate.
-
- 6. Conveying Non-Source Forms.
-
- You may convey a covered work in object code form under the terms
- of sections 4 and 5, provided that you also convey the
- machine-readable Corresponding Source under the terms of this
- License, in one of these ways:
-
- a. Convey the object code in, or embodied in, a physical product
- (including a physical distribution medium), accompanied by the
- Corresponding Source fixed on a durable physical medium
- customarily used for software interchange.
-
- b. Convey the object code in, or embodied in, a physical product
- (including a physical distribution medium), accompanied by a
- written offer, valid for at least three years and valid for
- as long as you offer spare parts or customer support for that
- product model, to give anyone who possesses the object code
- either (1) a copy of the Corresponding Source for all the
- software in the product that is covered by this License, on a
- durable physical medium customarily used for software
- interchange, for a price no more than your reasonable cost of
- physically performing this conveying of source, or (2) access
- to copy the Corresponding Source from a network server at no
- charge.
-
- c. Convey individual copies of the object code with a copy of
- the written offer to provide the Corresponding Source. This
- alternative is allowed only occasionally and noncommercially,
- and only if you received the object code with such an offer,
- in accord with subsection 6b.
-
- d. Convey the object code by offering access from a designated
- place (gratis or for a charge), and offer equivalent access
- to the Corresponding Source in the same way through the same
- place at no further charge. You need not require recipients
- to copy the Corresponding Source along with the object code.
- If the place to copy the object code is a network server, the
- Corresponding Source may be on a different server (operated
- by you or a third party) that supports equivalent copying
- facilities, provided you maintain clear directions next to
- the object code saying where to find the Corresponding Source.
- Regardless of what server hosts the Corresponding Source, you
- remain obligated to ensure that it is available for as long
- as needed to satisfy these requirements.
-
- e. Convey the object code using peer-to-peer transmission,
- provided you inform other peers where the object code and
- Corresponding Source of the work are being offered to the
- general public at no charge under subsection 6d.
-
-
- A separable portion of the object code, whose source code is
- excluded from the Corresponding Source as a System Library, need
- not be included in conveying the object code work.
-
- A "User Product" is either (1) a "consumer product", which means
- any tangible personal property which is normally used for personal,
- family, or household purposes, or (2) anything designed or sold for
- incorporation into a dwelling. In determining whether a product
- is a consumer product, doubtful cases shall be resolved in favor of
- coverage. For a particular product received by a particular user,
- "normally used" refers to a typical or common use of that class of
- product, regardless of the status of the particular user or of the
- way in which the particular user actually uses, or expects or is
- expected to use, the product. A product is a consumer product
- regardless of whether the product has substantial commercial,
- industrial or non-consumer uses, unless such uses represent the
- only significant mode of use of the product.
-
- "Installation Information" for a User Product means any methods,
- procedures, authorization keys, or other information required to
- install and execute modified versions of a covered work in that
- User Product from a modified version of its Corresponding Source.
- The information must suffice to ensure that the continued
- functioning of the modified object code is in no case prevented or
- interfered with solely because modification has been made.
-
- If you convey an object code work under this section in, or with,
- or specifically for use in, a User Product, and the conveying
- occurs as part of a transaction in which the right of possession
- and use of the User Product is transferred to the recipient in
- perpetuity or for a fixed term (regardless of how the transaction
- is characterized), the Corresponding Source conveyed under this
- section must be accompanied by the Installation Information. But
- this requirement does not apply if neither you nor any third party
- retains the ability to install modified object code on the User
- Product (for example, the work has been installed in ROM).
-
- The requirement to provide Installation Information does not
- include a requirement to continue to provide support service,
- warranty, or updates for a work that has been modified or
- installed by the recipient, or for the User Product in which it
- has been modified or installed. Access to a network may be denied
- when the modification itself materially and adversely affects the
- operation of the network or violates the rules and protocols for
- communication across the network.
-
- Corresponding Source conveyed, and Installation Information
- provided, in accord with this section must be in a format that is
- publicly documented (and with an implementation available to the
- public in source code form), and must require no special password
- or key for unpacking, reading or copying.
-
- 7. Additional Terms.
-
- "Additional permissions" are terms that supplement the terms of
- this License by making exceptions from one or more of its
- conditions. Additional permissions that are applicable to the
- entire Program shall be treated as though they were included in
- this License, to the extent that they are valid under applicable
- law. If additional permissions apply only to part of the Program,
- that part may be used separately under those permissions, but the
- entire Program remains governed by this License without regard to
- the additional permissions.
-
- When you convey a copy of a covered work, you may at your option
- remove any additional permissions from that copy, or from any part
- of it. (Additional permissions may be written to require their own
- removal in certain cases when you modify the work.) You may place
- additional permissions on material, added by you to a covered work,
- for which you have or can give appropriate copyright permission.
-
- Notwithstanding any other provision of this License, for material
- you add to a covered work, you may (if authorized by the copyright
- holders of that material) supplement the terms of this License
- with terms:
-
- a. Disclaiming warranty or limiting liability differently from
- the terms of sections 15 and 16 of this License; or
-
- b. Requiring preservation of specified reasonable legal notices
- or author attributions in that material or in the Appropriate
- Legal Notices displayed by works containing it; or
-
- c. Prohibiting misrepresentation of the origin of that material,
- or requiring that modified versions of such material be
- marked in reasonable ways as different from the original
- version; or
-
- d. Limiting the use for publicity purposes of names of licensors
- or authors of the material; or
-
- e. Declining to grant rights under trademark law for use of some
- trade names, trademarks, or service marks; or
-
- f. Requiring indemnification of licensors and authors of that
- material by anyone who conveys the material (or modified
- versions of it) with contractual assumptions of liability to
- the recipient, for any liability that these contractual
- assumptions directly impose on those licensors and authors.
-
- All other non-permissive additional terms are considered "further
- restrictions" within the meaning of section 10. If the Program as
- you received it, or any part of it, contains a notice stating that
- it is governed by this License along with a term that is a further
- restriction, you may remove that term. If a license document
- contains a further restriction but permits relicensing or
- conveying under this License, you may add to a covered work
- material governed by the terms of that license document, provided
- that the further restriction does not survive such relicensing or
- conveying.
-
- If you add terms to a covered work in accord with this section, you
- must place, in the relevant source files, a statement of the
- additional terms that apply to those files, or a notice indicating
- where to find the applicable terms.
-
- Additional terms, permissive or non-permissive, may be stated in
- the form of a separately written license, or stated as exceptions;
- the above requirements apply either way.
-
- 8. Termination.
-
- You may not propagate or modify a covered work except as expressly
- provided under this License. Any attempt otherwise to propagate or
- modify it is void, and will automatically terminate your rights
- under this License (including any patent licenses granted under
- the third paragraph of section 11).
-
- However, if you cease all violation of this License, then your
- license from a particular copyright holder is reinstated (a)
- provisionally, unless and until the copyright holder explicitly
- and finally terminates your license, and (b) permanently, if the
- copyright holder fails to notify you of the violation by some
- reasonable means prior to 60 days after the cessation.
-
- Moreover, your license from a particular copyright holder is
- reinstated permanently if the copyright holder notifies you of the
- violation by some reasonable means, this is the first time you have
- received notice of violation of this License (for any work) from
- that copyright holder, and you cure the violation prior to 30 days
- after your receipt of the notice.
-
- Termination of your rights under this section does not terminate
- the licenses of parties who have received copies or rights from
- you under this License. If your rights have been terminated and
- not permanently reinstated, you do not qualify to receive new
- licenses for the same material under section 10.
-
- 9. Acceptance Not Required for Having Copies.
-
- You are not required to accept this License in order to receive or
- run a copy of the Program. Ancillary propagation of a covered work
- occurring solely as a consequence of using peer-to-peer
- transmission to receive a copy likewise does not require
- acceptance. However, nothing other than this License grants you
- permission to propagate or modify any covered work. These actions
- infringe copyright if you do not accept this License. Therefore,
- by modifying or propagating a covered work, you indicate your
- acceptance of this License to do so.
-
- 10. Automatic Licensing of Downstream Recipients.
-
- Each time you convey a covered work, the recipient automatically
- receives a license from the original licensors, to run, modify and
- propagate that work, subject to this License. You are not
- responsible for enforcing compliance by third parties with this
- License.
-
- An "entity transaction" is a transaction transferring control of an
- organization, or substantially all assets of one, or subdividing an
- organization, or merging organizations. If propagation of a
- covered work results from an entity transaction, each party to that
- transaction who receives a copy of the work also receives whatever
- licenses to the work the party's predecessor in interest had or
- could give under the previous paragraph, plus a right to
- possession of the Corresponding Source of the work from the
- predecessor in interest, if the predecessor has it or can get it
- with reasonable efforts.
-
- You may not impose any further restrictions on the exercise of the
- rights granted or affirmed under this License. For example, you
- may not impose a license fee, royalty, or other charge for
- exercise of rights granted under this License, and you may not
- initiate litigation (including a cross-claim or counterclaim in a
- lawsuit) alleging that any patent claim is infringed by making,
- using, selling, offering for sale, or importing the Program or any
- portion of it.
-
- 11. Patents.
-
- A "contributor" is a copyright holder who authorizes use under this
- License of the Program or a work on which the Program is based.
- The work thus licensed is called the contributor's "contributor
- version".
-
- A contributor's "essential patent claims" are all patent claims
- owned or controlled by the contributor, whether already acquired or
- hereafter acquired, that would be infringed by some manner,
- permitted by this License, of making, using, or selling its
- contributor version, but do not include claims that would be
- infringed only as a consequence of further modification of the
- contributor version. For purposes of this definition, "control"
- includes the right to grant patent sublicenses in a manner
- consistent with the requirements of this License.
-
- Each contributor grants you a non-exclusive, worldwide,
- royalty-free patent license under the contributor's essential
- patent claims, to make, use, sell, offer for sale, import and
- otherwise run, modify and propagate the contents of its
- contributor version.
-
- In the following three paragraphs, a "patent license" is any
- express agreement or commitment, however denominated, not to
- enforce a patent (such as an express permission to practice a
- patent or covenant not to sue for patent infringement). To
- "grant" such a patent license to a party means to make such an
- agreement or commitment not to enforce a patent against the party.
-
- If you convey a covered work, knowingly relying on a patent
- license, and the Corresponding Source of the work is not available
- for anyone to copy, free of charge and under the terms of this
- License, through a publicly available network server or other
- readily accessible means, then you must either (1) cause the
- Corresponding Source to be so available, or (2) arrange to deprive
- yourself of the benefit of the patent license for this particular
- work, or (3) arrange, in a manner consistent with the requirements
- of this License, to extend the patent license to downstream
- recipients. "Knowingly relying" means you have actual knowledge
- that, but for the patent license, your conveying the covered work
- in a country, or your recipient's use of the covered work in a
- country, would infringe one or more identifiable patents in that
- country that you have reason to believe are valid.
-
- If, pursuant to or in connection with a single transaction or
- arrangement, you convey, or propagate by procuring conveyance of, a
- covered work, and grant a patent license to some of the parties
- receiving the covered work authorizing them to use, propagate,
- modify or convey a specific copy of the covered work, then the
- patent license you grant is automatically extended to all
- recipients of the covered work and works based on it.
-
- A patent license is "discriminatory" if it does not include within
- the scope of its coverage, prohibits the exercise of, or is
- conditioned on the non-exercise of one or more of the rights that
- are specifically granted under this License. You may not convey a
- covered work if you are a party to an arrangement with a third
- party that is in the business of distributing software, under
- which you make payment to the third party based on the extent of
- your activity of conveying the work, and under which the third
- party grants, to any of the parties who would receive the covered
- work from you, a discriminatory patent license (a) in connection
- with copies of the covered work conveyed by you (or copies made
- from those copies), or (b) primarily for and in connection with
- specific products or compilations that contain the covered work,
- unless you entered into that arrangement, or that patent license
- was granted, prior to 28 March 2007.
-
- Nothing in this License shall be construed as excluding or limiting
- any implied license or other defenses to infringement that may
- otherwise be available to you under applicable patent law.
-
- 12. No Surrender of Others' Freedom.
-
- If conditions are imposed on you (whether by court order,
- agreement or otherwise) that contradict the conditions of this
- License, they do not excuse you from the conditions of this
- License. If you cannot convey a covered work so as to satisfy
- simultaneously your obligations under this License and any other
- pertinent obligations, then as a consequence you may not convey it
- at all. For example, if you agree to terms that obligate you to
- collect a royalty for further conveying from those to whom you
- convey the Program, the only way you could satisfy both those
- terms and this License would be to refrain entirely from conveying
- the Program.
-
- 13. Use with the GNU Affero General Public License.
-
- Notwithstanding any other provision of this License, you have
- permission to link or combine any covered work with a work licensed
- under version 3 of the GNU Affero General Public License into a
- single combined work, and to convey the resulting work. The terms
- of this License will continue to apply to the part which is the
- covered work, but the special requirements of the GNU Affero
- General Public License, section 13, concerning interaction through
- a network will apply to the combination as such.
-
- 14. Revised Versions of this License.
-
- The Free Software Foundation may publish revised and/or new
- versions of the GNU General Public License from time to time.
- Such new versions will be similar in spirit to the present
- version, but may differ in detail to address new problems or
- concerns.
-
- Each version is given a distinguishing version number. If the
- Program specifies that a certain numbered version of the GNU
- General Public License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that numbered version or of any later version published by the
- Free Software Foundation. If the Program does not specify a
- version number of the GNU General Public License, you may choose
- any version ever published by the Free Software Foundation.
-
- If the Program specifies that a proxy can decide which future
- versions of the GNU General Public License can be used, that
- proxy's public statement of acceptance of a version permanently
- authorizes you to choose that version for the Program.
-
- Later license versions may give you additional or different
- permissions. However, no additional obligations are imposed on any
- author or copyright holder as a result of your choosing to follow a
- later version.
-
- 15. Disclaimer of Warranty.
-
- THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
- APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
- COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
- WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
- INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
- RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
- SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
- NECESSARY SERVICING, REPAIR OR CORRECTION.
-
- 16. Limitation of Liability.
-
- IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
- WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
- AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
- FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
- CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
- THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
- BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
- PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
- THE POSSIBILITY OF SUCH DAMAGES.
-
- 17. Interpretation of Sections 15 and 16.
-
- If the disclaimer of warranty and limitation of liability provided
- above cannot be given local legal effect according to their terms,
- reviewing courts shall apply local law that most closely
- approximates an absolute waiver of all civil liability in
- connection with the Program, unless a warranty or assumption of
- liability accompanies a copy of the Program in return for a fee.
-
-
-END OF TERMS AND CONDITIONS
-===========================
+File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top
+
+29 JIT Compilation Interface
+****************************
+
+This chapter documents GDB's "just-in-time" (JIT) compilation interface.
+A JIT compiler is a program or library that generates native executable
+code at runtime and executes it, usually in order to achieve good
+performance while maintaining platform independence.
+
+ Programs that use JIT compilation are normally difficult to debug
+because portions of their code are generated at runtime, instead of
+being loaded from object files, which is where GDB normally finds the
+program's symbols and debug information. In order to debug programs
+that use JIT compilation, GDB has an interface that allows the program
+to register in-memory symbol files with GDB at runtime.
+
+ If you are using GDB to debug a program that uses this interface,
+then it should work transparently so long as you have not stripped the
+binary. If you are developing a JIT compiler, then the interface is
+documented in the rest of this chapter. At this time, the only known
+client of this interface is the LLVM JIT.
+
+ Broadly speaking, the JIT interface mirrors the dynamic loader
+interface. The JIT compiler communicates with GDB by writing data into
+a global variable and calling a fuction at a well-known symbol. When
+GDB attaches, it reads a linked list of symbol files from the global
+variable to find existing code, and puts a breakpoint in the function so
+that it can find out about additional code.
+
+* Menu:
+
+* Declarations:: Relevant C struct declarations
+* Registering Code:: Steps to register code
+* Unregistering Code:: Steps to unregister code
+* Custom Debug Info:: Emit debug information in a custom format
+
+\1f
+File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface
+
+29.1 JIT Declarations
+=====================
+
+These are the relevant struct declarations that a C program should
+include to implement the interface:
+
+ typedef enum
+ {
+ JIT_NOACTION = 0,
+ JIT_REGISTER_FN,
+ JIT_UNREGISTER_FN
+ } jit_actions_t;
+
+ struct jit_code_entry
+ {
+ struct jit_code_entry *next_entry;
+ struct jit_code_entry *prev_entry;
+ const char *symfile_addr;
+ uint64_t symfile_size;
+ };
+
+ struct jit_descriptor
+ {
+ uint32_t version;
+ /* This type should be jit_actions_t, but we use uint32_t
+ to be explicit about the bitwidth. */
+ uint32_t action_flag;
+ struct jit_code_entry *relevant_entry;
+ struct jit_code_entry *first_entry;
+ };
+
+ /* GDB puts a breakpoint in this function. */
+ void __attribute__((noinline)) __jit_debug_register_code() { };
+
+ /* Make sure to specify the version statically, because the
+ debugger may check the version before we can set it. */
+ struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
+
+ If the JIT is multi-threaded, then it is important that the JIT
+synchronize any modifications to this global data properly, which can
+easily be done by putting a global mutex around modifications to these
+structures.
+
+\1f
+File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface
+
+29.2 Registering Code
+=====================
+
+To register code with GDB, the JIT should follow this protocol:
+
+ * Generate an object file in memory with symbols and other desired
+ debug information. The file must include the virtual addresses of
+ the sections.
+
+ * Create a code entry for the file, which gives the start and size of
+ the symbol file.
-How to Apply These Terms to Your New Programs
-=============================================
-
-If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these
-terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least the
-"copyright" line and a pointer to where the full notice is found.
-
- ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
- Copyright (C) YEAR NAME OF AUTHOR
-
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation, either version 3 of the License, or (at
- your option) any later version.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program. If not, see `http://www.gnu.org/licenses/'.
-
- Also add information on how to contact you by electronic and paper
-mail.
-
- If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
- PROGRAM Copyright (C) YEAR NAME OF AUTHOR
- This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
-
- The hypothetical commands `show w' and `show c' should show the
-appropriate parts of the General Public License. Of course, your
-program's commands might be different; for a GUI interface, you would
-use an "about box".
-
- You should also get your employer (if you work as a programmer) or
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary. For more information on this, and how to apply and follow
-the GNU GPL, see `http://www.gnu.org/licenses/'.
-
- The GNU General Public License does not permit incorporating your
-program into proprietary programs. If your program is a subroutine
-library, you may consider it more useful to permit linking proprietary
-applications with the library. If this is what you want to do, use the
-GNU Lesser General Public License instead of this License. But first,
-please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.
+ * Add it to the linked list in the JIT descriptor.
+
+ * Point the relevant_entry field of the descriptor at the entry.
+
+ * Set 'action_flag' to 'JIT_REGISTER' and call
+ '__jit_debug_register_code'.
+
+ When GDB is attached and the breakpoint fires, GDB uses the
+'relevant_entry' pointer so it doesn't have to walk the list looking for
+new code. However, the linked list must still be maintained in order to
+allow GDB to attach to a running process and still find the symbol
+files.
+
+\1f
+File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface
+
+29.3 Unregistering Code
+=======================
+
+If code is freed, then the JIT should use the following protocol:
+
+ * Remove the code entry corresponding to the code from the linked
+ list.
+
+ * Point the 'relevant_entry' field of the descriptor at the code
+ entry.
+
+ * Set 'action_flag' to 'JIT_UNREGISTER' and call
+ '__jit_debug_register_code'.
+
+ If the JIT frees or recompiles code without unregistering it, then
+GDB and the JIT will leak the memory used for the associated symbol
+files.
+
+\1f
+File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface
+
+29.4 Custom Debug Info
+======================
+
+Generating debug information in platform-native file formats (like ELF
+or COFF) may be an overkill for JIT compilers; especially if all the
+debug info is used for is displaying a meaningful backtrace. The issue
+can be resolved by having the JIT writers decide on a debug info format
+and also provide a reader that parses the debug info generated by the
+JIT compiler. This section gives a brief overview on writing such a
+parser. More specific details can be found in the source file
+'gdb/jit-reader.in', which is also installed as a header at
+'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion.
+
+ The reader is implemented as a shared object (so this functionality
+is not available on platforms which don't allow loading shared objects
+at runtime). Two GDB commands, 'jit-reader-load' and
+'jit-reader-unload' are provided, to be used to load and unload the
+readers from a preconfigured directory. Once loaded, the shared object
+is used the parse the debug information emitted by the JIT compiler.
+
+* Menu:
+
+* Using JIT Debug Info Readers:: How to use supplied readers correctly
+* Writing JIT Debug Info Readers:: Creating a debug-info reader
+
+\1f
+File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info
+
+29.4.1 Using JIT Debug Info Readers
+-----------------------------------
+
+Readers can be loaded and unloaded using the 'jit-reader-load' and
+'jit-reader-unload' commands.
+
+'jit-reader-load READER'
+ Load the JIT reader named READER, which is a shared object
+ specified as either an absolute or a relative file name. In the
+ latter case, GDB will try to load the reader from a pre-configured
+ directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is
+ the system library directory, often '/usr/local/lib').
+
+ Only one reader can be active at a time; trying to load a second
+ reader when one is already loaded will result in GDB reporting an
+ error. A new JIT reader can be loaded by first unloading the
+ current one using 'jit-reader-unload' and then invoking
+ 'jit-reader-load'.
+
+'jit-reader-unload'
+ Unload the currently loaded JIT reader.
+
+\1f
+File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info
+
+29.4.2 Writing JIT Debug Info Readers
+-------------------------------------
+
+As mentioned, a reader is essentially a shared object conforming to a
+certain ABI. This ABI is described in 'jit-reader.h'.
+
+ 'jit-reader.h' defines the structures, macros and functions required
+to write a reader. It is installed (along with GDB), in
+'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory.
+
+ Readers need to be released under a GPL compatible license. A reader
+can be declared as released under such a license by placing the macro
+'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file.
+
+ The entry point for readers is the symbol 'gdb_init_reader', which is
+expected to be a function with the prototype
+
+ extern struct gdb_reader_funcs *gdb_init_reader (void);
+
+ 'struct gdb_reader_funcs' contains a set of pointers to callback
+functions. These functions are executed to read the debug info
+generated by the JIT compiler ('read'), to unwind stack frames
+('unwind') and to create canonical frame IDs ('get_Frame_id'). It also
+has a callback that is called when the reader is being unloaded
+('destroy'). The struct looks like this
+
+ struct gdb_reader_funcs
+ {
+ /* Must be set to GDB_READER_INTERFACE_VERSION. */
+ int reader_version;
+
+ /* For use by the reader. */
+ void *priv_data;
+
+ gdb_read_debug_info *read;
+ gdb_unwind_frame *unwind;
+ gdb_get_frame_id *get_frame_id;
+ gdb_destroy_reader *destroy;
+ };
+
+ The callbacks are provided with another set of callbacks by GDB to do
+their job. For 'read', these callbacks are passed in a 'struct
+gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct
+gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to
+create new object files and new symbol tables inside those object files.
+'struct gdb_unwind_callbacks' has callbacks to read registers off the
+current frame and to write out the values of the registers in the
+previous frame. Both have a callback ('target_read') to read bytes off
+the target's address space.
+
+\1f
+File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top
+
+30 In-Process Agent
+*******************
+
+The traditional debugging model is conceptually low-speed, but works
+fine, because most bugs can be reproduced in debugging-mode execution.
+However, as multi-core or many-core processors are becoming mainstream,
+and multi-threaded programs become more and more popular, there should
+be more and more bugs that only manifest themselves at normal-mode
+execution, for example, thread races, because debugger's interference
+with the program's timing may conceal the bugs. On the other hand, in
+some applications, it is not feasible for the debugger to interrupt the
+program's execution long enough for the developer to learn anything
+helpful about its behavior. If the program's correctness depends on its
+real-time behavior, delays introduced by a debugger might cause the
+program to fail, even when the code itself is correct. It is useful to
+be able to observe the program's behavior without interrupting it.
+
+ Therefore, traditional debugging model is too intrusive to reproduce
+some bugs. In order to reduce the interference with the program, we can
+reduce the number of operations performed by debugger. The "In-Process
+Agent", a shared library, is running within the same process with
+inferior, and is able to perform some debugging operations itself. As a
+result, debugger is only involved when necessary, and performance of
+debugging can be improved accordingly. Note that interference with
+program can be reduced but can't be removed completely, because the
+in-process agent will still stop or slow down the program.
+
+ The in-process agent can interpret and execute Agent Expressions
+(*note Agent Expressions::) during performing debugging operations. The
+agent expressions can be used for different purposes, such as collecting
+data in tracepoints, and condition evaluation in breakpoints.
+
+ You can control whether the in-process agent is used as an aid for
+debugging with the following commands:
+
+'set agent on'
+ Causes the in-process agent to perform some operations on behalf of
+ the debugger. Just which operations requested by the user will be
+ done by the in-process agent depends on the its capabilities. For
+ example, if you request to evaluate breakpoint conditions in the
+ in-process agent, and the in-process agent has such capability as
+ well, then breakpoint conditions will be evaluated in the
+ in-process agent.
+
+'set agent off'
+ Disables execution of debugging operations by the in-process agent.
+ All of the operations will be performed by GDB.
+
+'show agent'
+ Display the current setting of execution of debugging operations by
+ the in-process agent.
+
+* Menu:
+
+* In-Process Agent Protocol::
+
+\1f
+File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent
+
+30.1 In-Process Agent Protocol
+==============================
+
+The in-process agent is able to communicate with both GDB and GDBserver
+(*note In-Process Agent::). This section documents the protocol used
+for communications between GDB or GDBserver and the IPA. In general, GDB
+or GDBserver sends commands (*note IPA Protocol Commands::) and data to
+in-process agent, and then in-process agent replies back with the return
+result of the command, or some other information. The data sent to
+in-process agent is composed of primitive data types, such as 4-byte or
+8-byte type, and composite types, which are called objects (*note IPA
+Protocol Objects::).
+
+* Menu:
+
+* IPA Protocol Objects::
+* IPA Protocol Commands::
+
+\1f
+File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol
+
+30.1.1 IPA Protocol Objects
+---------------------------
+
+The commands sent to and results received from agent may contain some
+complex data types called "objects".
+
+ The in-process agent is running on the same machine with GDB or
+GDBserver, so it doesn't have to handle as much differences between two
+ends as remote protocol (*note Remote Protocol::) tries to handle.
+However, there are still some differences of two ends in two processes:
+
+ 1. word size. On some 64-bit machines, GDB or GDBserver can be
+ compiled as a 64-bit executable, while in-process agent is a 32-bit
+ one.
+ 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver
+ is compiled with one, and in-process agent is compiled with the
+ other one.
+
+ Here are the IPA Protocol Objects:
+
+ 1. agent expression object. It represents an agent expression (*note
+ Agent Expressions::).
+ 2. tracepoint action object. It represents a tracepoint action (*note
+ Tracepoint Action Lists: Tracepoint Actions.) to collect registers,
+ memory, static trace data and to evaluate expression.
+ 3. tracepoint object. It represents a tracepoint (*note
+ Tracepoints::).
+
+ The following table describes important attributes of each IPA
+protocol object:
+
+Name Size Description
+---------------------------------------------------------------------------
+_agent expression
+object_
+length 4 length of bytes code
+byte code LENGTH contents of byte code
+_tracepoint action
+for collecting
+memory_
+'M' 1 type of tracepoint action
+addr 8 if BASEREG is '-1', ADDR is the
+ address of the lowest byte to
+ collect, otherwise ADDR is the
+ offset of BASEREG for memory
+ collecting.
+len 8 length of memory for collecting
+basereg 4 the register number containing the
+ starting memory address for
+ collecting.
+_tracepoint action
+for collecting
+registers_
+'R' 1 type of tracepoint action
+_tracepoint action
+for collecting
+static trace data_
+'L' 1 type of tracepoint action
+_tracepoint action
+for expression
+evaluation_
+'X' 1 type of tracepoint action
+agent expression length of *note agent expression object::
+_tracepoint object_
+number 4 number of tracepoint
+address 8 address of tracepoint inserted on
+type 4 type of tracepoint
+enabled 1 enable or disable of tracepoint
+step_count 8 step
+pass_count 8 pass
+numactions 4 number of tracepoint actions
+hit count 8 hit count
+trace frame usage 8 trace frame usage
+compiled_cond 8 compiled condition
+orig_size 8 orig size
+condition 4 if zero if condition is NULL,
+ condition is otherwise is *note agent
+ NULL expression object::
+ otherwise
+ length of
+ *note agent
+ expression
+ object::
+actions variable numactions number of *note
+ tracepoint action object::
+
+\1f
+File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol
+
+30.1.2 IPA Protocol Commands
+----------------------------
+
+The spaces in each command are delimiters to ease reading this commands
+specification. They don't exist in real commands.
+
+'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'
+ Installs a new fast tracepoint described by TRACEPOINT_OBJECT
+ (*note tracepoint object::). The GDB_JUMP_PAD_HEAD, 8-byte long,
+ is the head of "jumppad", which is used to jump to data collection
+ routine in IPA finally.
+
+ Replies:
+ 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'
+ TARGET_ADDRESS is address of tracepoint in the inferior. The
+ GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of
+ TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. The
+ FJUMP contains a sequence of instructions jump to jumppad
+ entry. The FJUMP_SIZE, 4-byte long, is the size of FJUMP.
+ 'E NN'
+ for an error
+
+'close'
+ Closes the in-process agent. This command is sent when GDB or
+ GDBserver is about to kill inferiors.
+
+'qTfSTM'
+ *Note qTfSTM::.
+'qTsSTM'
+ *Note qTsSTM::.
+'qTSTMat'
+ *Note qTSTMat::.
+'probe_marker_at:ADDRESS'
+ Asks in-process agent to probe the marker at ADDRESS.
+
+ Replies:
+ 'E NN'
+ for an error
+'unprobe_marker_at:ADDRESS'
+ Asks in-process agent to unprobe the marker at ADDRESS.
+
+\1f
+File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top
+
+31 Reporting Bugs in GDB
+************************
+
+Your bug reports play an essential role in making GDB reliable.
+
+ Reporting a bug may help you by bringing a solution to your problem,
+or it may not. But in any case the principal function of a bug report
+is to help the entire community by making the next version of GDB work
+better. Bug reports are your contribution to the maintenance of GDB.
+
+ In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+* Menu:
+
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+
+\1f
+File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
+
+31.1 Have You Found a Bug?
+==========================
+
+If you are not sure whether you have found a bug, here are some
+guidelines:
+
+ * If the debugger gets a fatal signal, for any input whatever, that
+ is a GDB bug. Reliable debuggers never crash.
+
+ * If GDB produces an error message for valid input, that is a bug.
+ (Note that if you're cross debugging, the problem may also be
+ somewhere in the connection to the target.)
+
+ * If GDB does not produce an error message for invalid input, that is
+ a bug. However, you should note that your idea of "invalid input"
+ might be our idea of "an extension" or "support for traditional
+ practice".
+
+ * If you are an experienced user of debugging tools, your suggestions
+ for improvement of GDB are welcome in any case.
+
+\1f
+File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
+
+31.2 How to Report Bugs
+=======================
+
+A number of companies and individuals offer support for GNU products.
+If you obtained GDB from a support organization, we recommend you
+contact that organization first.
+
+ You can find contact information for many support companies and
+individuals in the file 'etc/SERVICE' in the GNU Emacs distribution.
+
+ In any event, we also recommend that you submit bug reports for GDB.
+The preferred method is to submit them directly using GDB's Bugs web
+page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the e-mail
+gateway <bug-gdb@gnu.org> can be used.
+
+ *Do not send bug reports to 'info-gdb', or to 'help-gdb', or to any
+newsgroups.* Most users of GDB do not want to receive bug reports.
+Those that do have arranged to receive 'bug-gdb'.
+
+ The mailing list 'bug-gdb' has a newsgroup 'gnu.gdb.bug' which serves
+as a repeater. The mailing list and the newsgroup carry exactly the
+same messages. Often people think of posting bug reports to the
+newsgroup instead of mailing them. This appears to work, but it has one
+problem which can be crucial: a newsgroup posting often lacks a mail
+path back to the sender. Thus, if we need to ask for more information,
+we may be unable to reach you. For this reason, it is better to send
+bug reports to the mailing list.
+
+ The fundamental principle of reporting bugs usefully is this: *report
+all the facts*. If you are not sure whether to state a fact or leave it
+out, state it!
+
+ Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter. Thus, you might
+assume that the name of the variable you use in an example does not
+matter. Well, probably it does not, but one cannot be sure. Perhaps
+the bug is a stray memory reference which happens to fetch from the
+location where that name is stored in memory; perhaps, if the name were
+different, the contents of that location would fool the debugger into
+doing the right thing despite the bug. Play it safe and give a
+specific, complete example. That is the easiest thing for you to do,
+and the most helpful.
+
+ Keep in mind that the purpose of a bug report is to enable us to fix
+the bug. It may be that the bug has been reported previously, but
+neither you nor we can know that unless your bug report is complete and
+self-contained.
+
+ Sometimes people give a few sketchy facts and ask, "Does this ring a
+bell?" Those bug reports are useless, and we urge everyone to _refuse
+to respond to them_ except to chide the sender to report bugs properly.
+
+ To enable us to fix the bug, you should include all these things:
+
+ * The version of GDB. GDB announces it if you start with no
+ arguments; you can also print it at any time using 'show version'.
+
+ Without this, we will not know whether there is any point in
+ looking for the bug in the current version of GDB.
+
+ * The type of machine you are using, and the operating system name
+ and version number.
+
+ * The details of the GDB build-time configuration. GDB shows these
+ details if you invoke it with the '--configuration' command-line
+ option, or if you type 'show configuration' at GDB's prompt.
+
+ * What compiler (and its version) was used to compile GDB--e.g.
+ "gcc-2.8.1".
+
+ * What compiler (and its version) was used to compile the program you
+ are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C
+ Compiler". For GCC, you can say 'gcc --version' to get this
+ information; for other compilers, see the documentation for those
+ compilers.
+
+ * The command arguments you gave the compiler to compile your example
+ and observe the bug. For example, did you use '-O'? To guarantee
+ you will not omit something important, list them all. A copy of
+ the Makefile (or the output from make) is sufficient.
+
+ If we were to try to guess the arguments, we would probably guess
+ wrong and then we might not encounter the bug.
+
+ * A complete input script, and all necessary source files, that will
+ reproduce the bug.
+
+ * A description of what behavior you observe that you believe is
+ incorrect. For example, "It gets a fatal signal."
+
+ Of course, if the bug is that GDB gets a fatal signal, then we will
+ certainly notice it. But if the bug is incorrect output, we might
+ not notice unless it is glaringly wrong. You might as well not
+ give us a chance to make a mistake.
+
+ Even if the problem you experience is a fatal signal, you should
+ still say so explicitly. Suppose something strange is going on,
+ such as, your copy of GDB is out of synch, or you have encountered
+ a bug in the C library on your system. (This has happened!) Your
+ copy might crash and ours would not. If you told us to expect a
+ crash, then when ours fails to crash, we would know that the bug
+ was not happening for us. If you had not told us to expect a
+ crash, then we would not be able to draw any conclusion from our
+ observations.
+
+ To collect all this information, you can use a session recording
+ program such as 'script', which is available on many Unix systems.
+ Just run your GDB session inside 'script' and then include the
+ 'typescript' file with your bug report.
+
+ Another way to record a GDB session is to run GDB inside Emacs and
+ then save the entire buffer to a file.
+
+ * If you wish to suggest changes to the GDB source, send us context
+ diffs. If you even discuss something in the GDB source, refer to
+ it by context, not by line number.
+
+ The line numbers in our development sources will not match those in
+ your sources. Your line numbers would convey no useful information
+ to us.
+
+ Here are some things that are not necessary:
+
+ * A description of the envelope of the bug.
+
+ Often people who encounter a bug spend a lot of time investigating
+ which changes to the input file will make the bug go away and which
+ changes will not affect it.
+
+ This is often time consuming and not very useful, because the way
+ we will find the bug is by running a single example under the
+ debugger with breakpoints, not by pure deduction from a series of
+ examples. We recommend that you save your time for something else.
+
+ Of course, if you can find a simpler example to report _instead_ of
+ the original one, that is a convenience for us. Errors in the
+ output will be easier to spot, running under the debugger will take
+ less time, and so on.
+
+ However, simplification is not vital; if you do not want to do
+ this, report the bug anyway and send us the entire test case you
+ used.
+
+ * A patch for the bug.
+
+ A patch for the bug does help us if it is a good one. But do not
+ omit the necessary information, such as the test case, on the
+ assumption that a patch is all we need. We might see problems with
+ your patch and decide to fix the problem another way, or we might
+ not understand it at all.
+
+ Sometimes with a program as complicated as GDB it is very hard to
+ construct an example that will make the program follow a certain
+ path through the code. If you do not send us the example, we will
+ not be able to construct one, so we will not be able to verify that
+ the bug is fixed.
+
+ And if we cannot understand what bug you are trying to fix, or why
+ your patch should be an improvement, we will not install it. A
+ test case will help us to understand.
+
+ * A guess about what the bug is or what it depends on.
+
+ Such guesses are usually wrong. Even we cannot guess right about
+ such things without first using the debugger to find the facts.
+
+\1f
+File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
+
+32 Command Line Editing
+***********************
+
+This chapter describes the basic features of the GNU command line
+editing interface.
+
+* Menu:
+
+* Introduction and Notation:: Notation used in this text.
+* Readline Interaction:: The minimum set of commands for editing a line.
+* Readline Init File:: Customizing Readline from a user's view.
+* Bindable Readline Commands:: A description of most of the Readline commands
+ available for binding
+* Readline vi Mode:: A short description of how to make Readline
+ behave like the vi editor.
+
+\1f
+File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
+
+32.1 Introduction to Line Editing
+=================================
+
+The following paragraphs describe the notation used to represent
+keystrokes.
+
+ The text 'C-k' is read as 'Control-K' and describes the character
+produced when the <k> key is pressed while the Control key is depressed.
+
+ The text 'M-k' is read as 'Meta-K' and describes the character
+produced when the Meta key (if you have one) is depressed, and the <k>
+key is pressed. The Meta key is labeled <ALT> on many keyboards. On
+keyboards with two keys labeled <ALT> (usually to either side of the
+space bar), the <ALT> on the left side is generally set to work as a
+Meta key. The <ALT> key on the right may also be configured to work as
+a Meta key or may be configured as some other modifier, such as a
+Compose key for typing accented characters.
+
+ If you do not have a Meta or <ALT> key, or another key working as a
+Meta key, the identical keystroke can be generated by typing <ESC>
+_first_, and then typing <k>. Either process is known as "metafying"
+the <k> key.
+
+ The text 'M-C-k' is read as 'Meta-Control-k' and describes the
+character produced by "metafying" 'C-k'.
+
+ In addition, several keys have their own names. Specifically, <DEL>,
+<ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen
+in this text, or in an init file (*note Readline Init File::). If your
+keyboard lacks a <LFD> key, typing <C-j> will produce the desired
+character. The <RET> key may be labeled <Return> or <Enter> on some
+keyboards.
+
+\1f
+File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
+
+32.2 Readline Interaction
+=========================
+
+Often during an interactive session you type in a long line of text,
+only to notice that the first word on the line is misspelled. The
+Readline library gives you a set of commands for manipulating the text
+as you type it in, allowing you to just fix your typo, and not forcing
+you to retype the majority of the line. Using these editing commands,
+you move the cursor to the place that needs correction, and delete or
+insert the text of the corrections. Then, when you are satisfied with
+the line, you simply press <RET>. You do not have to be at the end of
+the line to press <RET>; the entire line is accepted regardless of the
+location of the cursor within the line.
+
+* Menu:
+
+* Readline Bare Essentials:: The least you need to know about Readline.
+* Readline Movement Commands:: Moving about the input line.
+* Readline Killing Commands:: How to delete text, and how to get it back!
+* Readline Arguments:: Giving numeric arguments to commands.
+* Searching:: Searching through previous lines.
+
+\1f
+File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
+
+32.2.1 Readline Bare Essentials
+-------------------------------
+
+In order to enter characters into the line, simply type them. The typed
+character appears where the cursor was, and then the cursor moves one
+space to the right. If you mistype a character, you can use your erase
+character to back up and delete the mistyped character.
+
+ Sometimes you may mistype a character, and not notice the error until
+you have typed several other characters. In that case, you can type
+'C-b' to move the cursor to the left, and then correct your mistake.
+Afterwards, you can move the cursor to the right with 'C-f'.
+
+ When you add text in the middle of a line, you will notice that
+characters to the right of the cursor are 'pushed over' to make room for
+the text that you have inserted. Likewise, when you delete text behind
+the cursor, characters to the right of the cursor are 'pulled back' to
+fill in the blank space created by the removal of the text. A list of
+the bare essentials for editing the text of an input line follows.
+
+'C-b'
+ Move back one character.
+'C-f'
+ Move forward one character.
+<DEL> or <Backspace>
+ Delete the character to the left of the cursor.
+'C-d'
+ Delete the character underneath the cursor.
+Printing characters
+ Insert the character into the line at the cursor.
+'C-_' or 'C-x C-u'
+ Undo the last editing command. You can undo all the way back to an
+ empty line.
+
+(Depending on your configuration, the <Backspace> key be set to delete
+the character to the left of the cursor and the <DEL> key set to delete
+the character underneath the cursor, like 'C-d', rather than the
+character to the left of the cursor.)
+
+\1f
+File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
+
+32.2.2 Readline Movement Commands
+---------------------------------
+
+The above table describes the most basic keystrokes that you need in
+order to do editing of the input line. For your convenience, many other
+commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>.
+Here are some commands for moving more rapidly about the line.
+
+'C-a'
+ Move to the start of the line.
+'C-e'
+ Move to the end of the line.
+'M-f'
+ Move forward a word, where a word is composed of letters and
+ digits.
+'M-b'
+ Move backward a word.
+'C-l'
+ Clear the screen, reprinting the current line at the top.
+
+ Notice how 'C-f' moves forward a character, while 'M-f' moves forward
+a word. It is a loose convention that control keystrokes operate on
+characters while meta keystrokes operate on words.
+
+\1f
+File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
+
+32.2.3 Readline Killing Commands
+--------------------------------
+
+"Killing" text means to delete the text from the line, but to save it
+away for later use, usually by "yanking" (re-inserting) it back into the
+line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.)
+
+ If the description for a command says that it 'kills' text, then you
+can be sure that you can get the text back in a different (or the same)
+place later.
+
+ When you use a kill command, the text is saved in a "kill-ring". Any
+number of consecutive kills save all of the killed text together, so
+that when you yank it back, you get it all. The kill ring is not line
+specific; the text that you killed on a previously typed line is
+available to be yanked back later, when you are typing another line.
+
+ Here is the list of commands for killing text.
+
+'C-k'
+ Kill the text from the current cursor position to the end of the
+ line.
+
+'M-d'
+ Kill from the cursor to the end of the current word, or, if between
+ words, to the end of the next word. Word boundaries are the same
+ as those used by 'M-f'.
+
+'M-<DEL>'
+ Kill from the cursor the start of the current word, or, if between
+ words, to the start of the previous word. Word boundaries are the
+ same as those used by 'M-b'.
+
+'C-w'
+ Kill from the cursor to the previous whitespace. This is different
+ than 'M-<DEL>' because the word boundaries differ.
+
+ Here is how to "yank" the text back into the line. Yanking means to
+copy the most-recently-killed text from the kill buffer.
+
+'C-y'
+ Yank the most recently killed text back into the buffer at the
+ cursor.
+
+'M-y'
+ Rotate the kill-ring, and yank the new top. You can only do this
+ if the prior command is 'C-y' or 'M-y'.
+
+\1f
+File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
+
+32.2.4 Readline Arguments
+-------------------------
+
+You can pass numeric arguments to Readline commands. Sometimes the
+argument acts as a repeat count, other times it is the sign of the
+argument that is significant. If you pass a negative argument to a
+command which normally acts in a forward direction, that command will
+act in a backward direction. For example, to kill text back to the
+start of the line, you might type 'M-- C-k'.
+
+ The general way to pass numeric arguments to a command is to type
+meta digits before the command. If the first 'digit' typed is a minus
+sign ('-'), then the sign of the argument will be negative. Once you
+have typed one meta digit to get the argument started, you can type the
+remainder of the digits, and then the command. For example, to give the
+'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will
+delete the next ten characters on the input line.
+
+\1f
+File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
+
+32.2.5 Searching for Commands in the History
+--------------------------------------------
+
+Readline provides commands for searching through the command history for
+lines containing a specified string. There are two search modes:
+"incremental" and "non-incremental".
+
+ Incremental searches begin before the user has finished typing the
+search string. As each character of the search string is typed,
+Readline displays the next entry from the history matching the string
+typed so far. An incremental search requires only as many characters as
+needed to find the desired history entry. To search backward in the
+history for a particular string, type 'C-r'. Typing 'C-s' searches
+forward through the history. The characters present in the value of the
+'isearch-terminators' variable are used to terminate an incremental
+search. If that variable has not been assigned a value, the <ESC> and
+'C-J' characters will terminate an incremental search. 'C-g' will abort
+an incremental search and restore the original line. When the search is
+terminated, the history entry containing the search string becomes the
+current line.
+
+ To find other matching entries in the history list, type 'C-r' or
+'C-s' as appropriate. This will search backward or forward in the
+history for the next entry matching the search string typed so far. Any
+other key sequence bound to a Readline command will terminate the search
+and execute that command. For instance, a <RET> will terminate the
+search and accept the line, thereby executing the command from the
+history list. A movement command will terminate the search, make the
+last line found the current line, and begin editing.
+
+ Readline remembers the last incremental search string. If two 'C-r's
+are typed without any intervening characters defining a new search
+string, any remembered search string is used.
+
+ Non-incremental searches read the entire search string before
+starting to search for matching history lines. The search string may be
+typed by the user or be part of the contents of the current line.
+
+\1f
+File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
+
+32.3 Readline Init File
+=======================
+
+Although the Readline library comes with a set of Emacs-like keybindings
+installed by default, it is possible to use a different set of
+keybindings. Any user can customize programs that use Readline by
+putting commands in an "inputrc" file, conventionally in his home
+directory. The name of this file is taken from the value of the
+environment variable 'INPUTRC'. If that variable is unset, the default
+is '~/.inputrc'. If that file does not exist or cannot be read, the
+ultimate default is '/etc/inputrc'.
+
+ When a program which uses the Readline library starts up, the init
+file is read, and the key bindings are set.
+
+ In addition, the 'C-x C-r' command re-reads this init file, thus
+incorporating any changes that you might have made to it.
+
+* Menu:
+
+* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
+
+* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
+
+* Sample Init File:: An example inputrc file.
+
+\1f
+File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
+
+32.3.1 Readline Init File Syntax
+--------------------------------
+
+There are only a few basic constructs allowed in the Readline init file.
+Blank lines are ignored. Lines beginning with a '#' are comments.
+Lines beginning with a '$' indicate conditional constructs (*note
+Conditional Init Constructs::). Other lines denote variable settings
+and key bindings.
+
+Variable Settings
+ You can modify the run-time behavior of Readline by altering the
+ values of variables in Readline using the 'set' command within the
+ init file. The syntax is simple:
+
+ set VARIABLE VALUE
+
+ Here, for example, is how to change from the default Emacs-like key
+ binding to use 'vi' line editing commands:
+
+ set editing-mode vi
+
+ Variable names and values, where appropriate, are recognized
+ without regard to case. Unrecognized variable names are ignored.
+
+ Boolean variables (those that can be set to on or off) are set to
+ on if the value is null or empty, ON (case-insensitive), or 1. Any
+ other value results in the variable being set to off.
+
+ A great deal of run-time behavior is changeable with the following
+ variables.
+
+ 'bell-style'
+ Controls what happens when Readline wants to ring the terminal
+ bell. If set to 'none', Readline never rings the bell. If
+ set to 'visible', Readline uses a visible bell if one is
+ available. If set to 'audible' (the default), Readline
+ attempts to ring the terminal's bell.
+
+ 'bind-tty-special-chars'
+ If set to 'on', Readline attempts to bind the control
+ characters treated specially by the kernel's terminal driver
+ to their Readline equivalents.
+
+ 'comment-begin'
+ The string to insert at the beginning of the line when the
+ 'insert-comment' command is executed. The default value is
+ '"#"'.
+
+ 'completion-display-width'
+ The number of screen columns used to display possible matches
+ when performing completion. The value is ignored if it is
+ less than 0 or greater than the terminal screen width. A
+ value of 0 will cause matches to be displayed one per line.
+ The default value is -1.
+
+ 'completion-ignore-case'
+ If set to 'on', Readline performs filename matching and
+ completion in a case-insensitive fashion. The default value
+ is 'off'.
+
+ 'completion-map-case'
+ If set to 'on', and COMPLETION-IGNORE-CASE is enabled,
+ Readline treats hyphens ('-') and underscores ('_') as
+ equivalent when performing case-insensitive filename matching
+ and completion.
+
+ 'completion-prefix-display-length'
+ The length in characters of the common prefix of a list of
+ possible completions that is displayed without modification.
+ When set to a value greater than zero, common prefixes longer
+ than this value are replaced with an ellipsis when displaying
+ possible completions.
+
+ 'completion-query-items'
+ The number of possible completions that determines when the
+ user is asked whether the list of possibilities should be
+ displayed. If the number of possible completions is greater
+ than this value, Readline will ask the user whether or not he
+ wishes to view them; otherwise, they are simply listed. This
+ variable must be set to an integer value greater than or equal
+ to 0. A negative value means Readline should never ask. The
+ default limit is '100'.
+
+ 'convert-meta'
+ If set to 'on', Readline will convert characters with the
+ eighth bit set to an ASCII key sequence by stripping the
+ eighth bit and prefixing an <ESC> character, converting them
+ to a meta-prefixed key sequence. The default value is 'on'.
+
+ 'disable-completion'
+ If set to 'On', Readline will inhibit word completion.
+ Completion characters will be inserted into the line as if
+ they had been mapped to 'self-insert'. The default is 'off'.
+
+ 'editing-mode'
+ The 'editing-mode' variable controls which default set of key
+ bindings is used. By default, Readline starts up in Emacs
+ editing mode, where the keystrokes are most similar to Emacs.
+ This variable can be set to either 'emacs' or 'vi'.
+
+ 'echo-control-characters'
+ When set to 'on', on operating systems that indicate they
+ support it, readline echoes a character corresponding to a
+ signal generated from the keyboard. The default is 'on'.
+
+ 'enable-keypad'
+ When set to 'on', Readline will try to enable the application
+ keypad when it is called. Some systems need this to enable
+ the arrow keys. The default is 'off'.
+
+ 'enable-meta-key'
+ When set to 'on', Readline will try to enable any meta
+ modifier key the terminal claims to support when it is called.
+ On many terminals, the meta key is used to send eight-bit
+ characters. The default is 'on'.
+
+ 'expand-tilde'
+ If set to 'on', tilde expansion is performed when Readline
+ attempts word completion. The default is 'off'.
+
+ 'history-preserve-point'
+ If set to 'on', the history code attempts to place the point
+ (the current cursor position) at the same location on each
+ history line retrieved with 'previous-history' or
+ 'next-history'. The default is 'off'.
+
+ 'history-size'
+ Set the maximum number of history entries saved in the history
+ list. If set to zero, the number of entries in the history
+ list is not limited.
+
+ 'horizontal-scroll-mode'
+ This variable can be set to either 'on' or 'off'. Setting it
+ to 'on' means that the text of the lines being edited will
+ scroll horizontally on a single screen line when they are
+ longer than the width of the screen, instead of wrapping onto
+ a new screen line. By default, this variable is set to 'off'.
+
+ 'input-meta'
+ If set to 'on', Readline will enable eight-bit input (it will
+ not clear the eighth bit in the characters it reads),
+ regardless of what the terminal claims it can support. The
+ default value is 'off'. The name 'meta-flag' is a synonym for
+ this variable.
+
+ 'isearch-terminators'
+ The string of characters that should terminate an incremental
+ search without subsequently executing the character as a
+ command (*note Searching::). If this variable has not been
+ given a value, the characters <ESC> and 'C-J' will terminate
+ an incremental search.
+
+ 'keymap'
+ Sets Readline's idea of the current keymap for key binding
+ commands. Acceptable 'keymap' names are 'emacs',
+ 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',
+ 'vi-command', and 'vi-insert'. 'vi' is equivalent to
+ 'vi-command'; 'emacs' is equivalent to 'emacs-standard'. The
+ default value is 'emacs'. The value of the 'editing-mode'
+ variable also affects the default keymap.
+
+ 'mark-directories'
+ If set to 'on', completed directory names have a slash
+ appended. The default is 'on'.
+
+ 'mark-modified-lines'
+ This variable, when set to 'on', causes Readline to display an
+ asterisk ('*') at the start of history lines which have been
+ modified. This variable is 'off' by default.
+
+ 'mark-symlinked-directories'
+ If set to 'on', completed names which are symbolic links to
+ directories have a slash appended (subject to the value of
+ 'mark-directories'). The default is 'off'.
+
+ 'match-hidden-files'
+ This variable, when set to 'on', causes Readline to match
+ files whose names begin with a '.' (hidden files) when
+ performing filename completion. If set to 'off', the leading
+ '.' must be supplied by the user in the filename to be
+ completed. This variable is 'on' by default.
+
+ 'menu-complete-display-prefix'
+ If set to 'on', menu completion displays the common prefix of
+ the list of possible completions (which may be empty) before
+ cycling through the list. The default is 'off'.
+
+ 'output-meta'
+ If set to 'on', Readline will display characters with the
+ eighth bit set directly rather than as a meta-prefixed escape
+ sequence. The default is 'off'.
+
+ 'page-completions'
+ If set to 'on', Readline uses an internal 'more'-like pager to
+ display a screenful of possible completions at a time. This
+ variable is 'on' by default.
+
+ 'print-completions-horizontally'
+ If set to 'on', Readline will display completions with matches
+ sorted horizontally in alphabetical order, rather than down
+ the screen. The default is 'off'.
+
+ 'revert-all-at-newline'
+ If set to 'on', Readline will undo all changes to history
+ lines before returning when 'accept-line' is executed. By
+ default, history lines may be modified and retain individual
+ undo lists across calls to 'readline'. The default is 'off'.
+
+ 'show-all-if-ambiguous'
+ This alters the default behavior of the completion functions.
+ If set to 'on', words which have more than one possible
+ completion cause the matches to be listed immediately instead
+ of ringing the bell. The default value is 'off'.
+
+ 'show-all-if-unmodified'
+ This alters the default behavior of the completion functions
+ in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
+ 'on', words which have more than one possible completion
+ without any possible partial completion (the possible
+ completions don't share a common prefix) cause the matches to
+ be listed immediately instead of ringing the bell. The
+ default value is 'off'.
+
+ 'skip-completed-text'
+ If set to 'on', this alters the default completion behavior
+ when inserting a single match into the line. It's only active
+ when performing completion in the middle of a word. If
+ enabled, readline does not insert characters from the
+ completion that match characters after point in the word being
+ completed, so portions of the word following the cursor are
+ not duplicated. For instance, if this is enabled, attempting
+ completion when the cursor is after the 'e' in 'Makefile' will
+ result in 'Makefile' rather than 'Makefilefile', assuming
+ there is a single possible completion. The default value is
+ 'off'.
+
+ 'visible-stats'
+ If set to 'on', a character denoting a file's type is appended
+ to the filename when listing possible completions. The
+ default is 'off'.
+
+Key Bindings
+ The syntax for controlling key bindings in the init file is simple.
+ First you need to find the name of the command that you want to
+ change. The following sections contain tables of the command name,
+ the default keybinding, if any, and a short description of what the
+ command does.
+
+ Once you know the name of the command, simply place on a line in
+ the init file the name of the key you wish to bind the command to,
+ a colon, and then the name of the command. There can be no space
+ between the key name and the colon - that will be interpreted as
+ part of the key name. The name of the key can be expressed in
+ different ways, depending on what you find most comfortable.
+
+ In addition to command names, readline allows keys to be bound to a
+ string that is inserted when the key is pressed (a MACRO).
+
+ KEYNAME: FUNCTION-NAME or MACRO
+ KEYNAME is the name of a key spelled out in English. For
+ example:
+ Control-u: universal-argument
+ Meta-Rubout: backward-kill-word
+ Control-o: "> output"
+
+ In the above example, 'C-u' is bound to the function
+ 'universal-argument', 'M-DEL' is bound to the function
+ 'backward-kill-word', and 'C-o' is bound to run the macro
+ expressed on the right hand side (that is, to insert the text
+ '> output' into the line).
+
+ A number of symbolic character names are recognized while
+ processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
+ NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
+
+ "KEYSEQ": FUNCTION-NAME or MACRO
+ KEYSEQ differs from KEYNAME above in that strings denoting an
+ entire key sequence can be specified, by placing the key
+ sequence in double quotes. Some GNU Emacs style key escapes
+ can be used, as in the following example, but the special
+ character names are not recognized.
+
+ "\C-u": universal-argument
+ "\C-x\C-r": re-read-init-file
+ "\e[11~": "Function Key 1"
+
+ In the above example, 'C-u' is again bound to the function
+ 'universal-argument' (just as it was in the first example),
+ ''C-x' 'C-r'' is bound to the function 're-read-init-file',
+ and '<ESC> <[> <1> <1> <~>' is bound to insert the text
+ 'Function Key 1'.
+
+ The following GNU Emacs style escape sequences are available when
+ specifying key sequences:
+
+ '\C-'
+ control prefix
+ '\M-'
+ meta prefix
+ '\e'
+ an escape character
+ '\\'
+ backslash
+ '\"'
+ <">, a double quotation mark
+ '\''
+ <'>, a single quote or apostrophe
+
+ In addition to the GNU Emacs style escape sequences, a second set
+ of backslash escapes is available:
+
+ '\a'
+ alert (bell)
+ '\b'
+ backspace
+ '\d'
+ delete
+ '\f'
+ form feed
+ '\n'
+ newline
+ '\r'
+ carriage return
+ '\t'
+ horizontal tab
+ '\v'
+ vertical tab
+ '\NNN'
+ the eight-bit character whose value is the octal value NNN
+ (one to three digits)
+ '\xHH'
+ the eight-bit character whose value is the hexadecimal value
+ HH (one or two hex digits)
+
+ When entering the text of a macro, single or double quotes must be
+ used to indicate a macro definition. Unquoted text is assumed to
+ be a function name. In the macro body, the backslash escapes
+ described above are expanded. Backslash will quote any other
+ character in the macro text, including '"' and '''. For example,
+ the following binding will make ''C-x' \' insert a single '\' into
+ the line:
+ "\C-x\\": "\\"
+
+\1f
+File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
+
+32.3.2 Conditional Init Constructs
+----------------------------------
+
+Readline implements a facility similar in spirit to the conditional
+compilation features of the C preprocessor which allows key bindings and
+variable settings to be performed as the result of tests. There are
+four parser directives used.
+
+'$if'
+ The '$if' construct allows bindings to be made based on the editing
+ mode, the terminal being used, or the application using Readline.
+ The text of the test extends to the end of the line; no characters
+ are required to isolate it.
+
+ 'mode'
+ The 'mode=' form of the '$if' directive is used to test
+ whether Readline is in 'emacs' or 'vi' mode. This may be used
+ in conjunction with the 'set keymap' command, for instance, to
+ set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps
+ only if Readline is starting out in 'emacs' mode.
+
+ 'term'
+ The 'term=' form may be used to include terminal-specific key
+ bindings, perhaps to bind the key sequences output by the
+ terminal's function keys. The word on the right side of the
+ '=' is tested against both the full name of the terminal and
+ the portion of the terminal name before the first '-'. This
+ allows 'sun' to match both 'sun' and 'sun-cmd', for instance.
+
+ 'application'
+ The APPLICATION construct is used to include
+ application-specific settings. Each program using the
+ Readline library sets the APPLICATION NAME, and you can test
+ for a particular value. This could be used to bind key
+ sequences to functions useful for a specific program. For
+ instance, the following command adds a key sequence that
+ quotes the current or previous word in Bash:
+ $if Bash
+ # Quote the current or previous word
+ "\C-xq": "\eb\"\ef\""
+ $endif
+
+'$endif'
+ This command, as seen in the previous example, terminates an '$if'
+ command.
+
+'$else'
+ Commands in this branch of the '$if' directive are executed if the
+ test fails.
+
+'$include'
+ This directive takes a single filename as an argument and reads
+ commands and bindings from that file. For example, the following
+ directive reads from '/etc/inputrc':
+ $include /etc/inputrc
+
+\1f
+File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
+
+32.3.3 Sample Init File
+-----------------------
+
+Here is an example of an INPUTRC file. This illustrates key binding,
+variable assignment, and conditional syntax.
+
+ # This file controls the behaviour of line input editing for
+ # programs that use the GNU Readline library. Existing
+ # programs include FTP, Bash, and GDB.
+ #
+ # You can re-read the inputrc file with C-x C-r.
+ # Lines beginning with '#' are comments.
+ #
+ # First, include any systemwide bindings and variable
+ # assignments from /etc/Inputrc
+ $include /etc/Inputrc
+
+ #
+ # Set various bindings for emacs mode.
+
+ set editing-mode emacs
+
+ $if mode=emacs
+
+ Meta-Control-h: backward-kill-word Text after the function name is ignored
+
+ #
+ # Arrow keys in keypad mode
+ #
+ #"\M-OD": backward-char
+ #"\M-OC": forward-char
+ #"\M-OA": previous-history
+ #"\M-OB": next-history
+ #
+ # Arrow keys in ANSI mode
+ #
+ "\M-[D": backward-char
+ "\M-[C": forward-char
+ "\M-[A": previous-history
+ "\M-[B": next-history
+ #
+ # Arrow keys in 8 bit keypad mode
+ #
+ #"\M-\C-OD": backward-char
+ #"\M-\C-OC": forward-char
+ #"\M-\C-OA": previous-history
+ #"\M-\C-OB": next-history
+ #
+ # Arrow keys in 8 bit ANSI mode
+ #
+ #"\M-\C-[D": backward-char
+ #"\M-\C-[C": forward-char
+ #"\M-\C-[A": previous-history
+ #"\M-\C-[B": next-history
+
+ C-q: quoted-insert
+
+ $endif
+
+ # An old-style binding. This happens to be the default.
+ TAB: complete
+
+ # Macros that are convenient for shell interaction
+ $if Bash
+ # edit the path
+ "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
+ # prepare to type a quoted word --
+ # insert open and close double quotes
+ # and move to just after the open quote
+ "\C-x\"": "\"\"\C-b"
+ # insert a backslash (testing backslash escapes
+ # in sequences and macros)
+ "\C-x\\": "\\"
+ # Quote the current or previous word
+ "\C-xq": "\eb\"\ef\""
+ # Add a binding to refresh the line, which is unbound
+ "\C-xr": redraw-current-line
+ # Edit variable on current line.
+ "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
+ $endif
+
+ # use a visible bell if one is available
+ set bell-style visible
+
+ # don't strip characters to 7 bits when reading
+ set input-meta on
+
+ # allow iso-latin1 characters to be inserted rather
+ # than converted to prefix-meta sequences
+ set convert-meta off
+
+ # display characters with the eighth bit set directly
+ # rather than as meta-prefixed characters
+ set output-meta on
+
+ # if there are more than 150 possible completions for
+ # a word, ask the user if he wants to see all of them
+ set completion-query-items 150
+
+ # For FTP
+ $if Ftp
+ "\C-xg": "get \M-?"
+ "\C-xt": "put \M-?"
+ "\M-.": yank-last-arg
+ $endif
+
+\1f
+File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
+
+32.4 Bindable Readline Commands
+===============================
+
+* Menu:
+
+* Commands For Moving:: Moving about the line.
+* Commands For History:: Getting at previous lines.
+* Commands For Text:: Commands for changing text.
+* Commands For Killing:: Commands for killing and yanking.
+* Numeric Arguments:: Specifying numeric arguments, repeat counts.
+* Commands For Completion:: Getting Readline to do the typing for you.
+* Keyboard Macros:: Saving and re-executing typed characters
+* Miscellaneous Commands:: Other miscellaneous commands.
+
+This section describes Readline commands that may be bound to key
+sequences. Command names without an accompanying key sequence are
+unbound by default.
+
+ In the following descriptions, "point" refers to the current cursor
+position, and "mark" refers to a cursor position saved by the 'set-mark'
+command. The text between the point and mark is referred to as the
+"region".
+
+\1f
+File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
+
+32.4.1 Commands For Moving
+--------------------------
+
+'beginning-of-line (C-a)'
+ Move to the start of the current line.
+
+'end-of-line (C-e)'
+ Move to the end of the line.
+
+'forward-char (C-f)'
+ Move forward a character.
+
+'backward-char (C-b)'
+ Move back a character.
+
+'forward-word (M-f)'
+ Move forward to the end of the next word. Words are composed of
+ letters and digits.
+
+'backward-word (M-b)'
+ Move back to the start of the current or previous word. Words are
+ composed of letters and digits.
+
+'clear-screen (C-l)'
+ Clear the screen and redraw the current line, leaving the current
+ line at the top of the screen.
+
+'redraw-current-line ()'
+ Refresh the current line. By default, this is unbound.
+
+\1f
+File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
+
+32.4.2 Commands For Manipulating The History
+--------------------------------------------
+
+'accept-line (Newline or Return)'
+ Accept the line regardless of where the cursor is. If this line is
+ non-empty, it may be added to the history list for future recall
+ with 'add_history()'. If this line is a modified history line, the
+ history line is restored to its original state.
+
+'previous-history (C-p)'
+ Move 'back' through the history list, fetching the previous
+ command.
+
+'next-history (C-n)'
+ Move 'forward' through the history list, fetching the next command.
+
+'beginning-of-history (M-<)'
+ Move to the first line in the history.
+
+'end-of-history (M->)'
+ Move to the end of the input history, i.e., the line currently
+ being entered.
+
+'reverse-search-history (C-r)'
+ Search backward starting at the current line and moving 'up'
+ through the history as necessary. This is an incremental search.
+
+'forward-search-history (C-s)'
+ Search forward starting at the current line and moving 'down'
+ through the the history as necessary. This is an incremental
+ search.
+
+'non-incremental-reverse-search-history (M-p)'
+ Search backward starting at the current line and moving 'up'
+ through the history as necessary using a non-incremental search for
+ a string supplied by the user.
+
+'non-incremental-forward-search-history (M-n)'
+ Search forward starting at the current line and moving 'down'
+ through the the history as necessary using a non-incremental search
+ for a string supplied by the user.
+
+'history-search-forward ()'
+ Search forward through the history for the string of characters
+ between the start of the current line and the point. This is a
+ non-incremental search. By default, this command is unbound.
+
+'history-search-backward ()'
+ Search backward through the history for the string of characters
+ between the start of the current line and the point. This is a
+ non-incremental search. By default, this command is unbound.
+
+'yank-nth-arg (M-C-y)'
+ Insert the first argument to the previous command (usually the
+ second word on the previous line) at point. With an argument N,
+ insert the Nth word from the previous command (the words in the
+ previous command begin with word 0). A negative argument inserts
+ the Nth word from the end of the previous command. Once the
+ argument N is computed, the argument is extracted as if the '!N'
+ history expansion had been specified.
+
+'yank-last-arg (M-. or M-_)'
+ Insert last argument to the previous command (the last word of the
+ previous history entry). With a numeric argument, behave exactly
+ like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back
+ through the history list, inserting the last word (or the word
+ specified by the argument to the first call) of each line in turn.
+ Any numeric argument supplied to these successive calls determines
+ the direction to move through the history. A negative argument
+ switches the direction through the history (back or forward). The
+ history expansion facilities are used to extract the last argument,
+ as if the '!$' history expansion had been specified.
+
+\1f
+File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
+
+32.4.3 Commands For Changing Text
+---------------------------------
+
+'delete-char (C-d)'
+ Delete the character at point. If point is at the beginning of the
+ line, there are no characters in the line, and the last character
+ typed was not bound to 'delete-char', then return EOF.
+
+'backward-delete-char (Rubout)'
+ Delete the character behind the cursor. A numeric argument means
+ to kill the characters instead of deleting them.
+
+'forward-backward-delete-char ()'
+ Delete the character under the cursor, unless the cursor is at the
+ end of the line, in which case the character behind the cursor is
+ deleted. By default, this is not bound to a key.
+
+'quoted-insert (C-q or C-v)'
+ Add the next character typed to the line verbatim. This is how to
+ insert key sequences like 'C-q', for example.
+
+'tab-insert (M-<TAB>)'
+ Insert a tab character.
+
+'self-insert (a, b, A, 1, !, ...)'
+ Insert yourself.
+
+'transpose-chars (C-t)'
+ Drag the character before the cursor forward over the character at
+ the cursor, moving the cursor forward as well. If the insertion
+ point is at the end of the line, then this transposes the last two
+ characters of the line. Negative arguments have no effect.
+
+'transpose-words (M-t)'
+ Drag the word before point past the word after point, moving point
+ past that word as well. If the insertion point is at the end of
+ the line, this transposes the last two words on the line.
+
+'upcase-word (M-u)'
+ Uppercase the current (or following) word. With a negative
+ argument, uppercase the previous word, but do not move the cursor.
+
+'downcase-word (M-l)'
+ Lowercase the current (or following) word. With a negative
+ argument, lowercase the previous word, but do not move the cursor.
+
+'capitalize-word (M-c)'
+ Capitalize the current (or following) word. With a negative
+ argument, capitalize the previous word, but do not move the cursor.
+
+'overwrite-mode ()'
+ Toggle overwrite mode. With an explicit positive numeric argument,
+ switches to overwrite mode. With an explicit non-positive numeric
+ argument, switches to insert mode. This command affects only
+ 'emacs' mode; 'vi' mode does overwrite differently. Each call to
+ 'readline()' starts in insert mode.
+
+ In overwrite mode, characters bound to 'self-insert' replace the
+ text at point rather than pushing the text to the right.
+ Characters bound to 'backward-delete-char' replace the character
+ before point with a space.
+
+ By default, this command is unbound.
+
+\1f
+File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
+
+32.4.4 Killing And Yanking
+--------------------------
+
+'kill-line (C-k)'
+ Kill the text from point to the end of the line.
+
+'backward-kill-line (C-x Rubout)'
+ Kill backward to the beginning of the line.
+
+'unix-line-discard (C-u)'
+ Kill backward from the cursor to the beginning of the current line.
+
+'kill-whole-line ()'
+ Kill all characters on the current line, no matter where point is.
+ By default, this is unbound.
+
+'kill-word (M-d)'
+ Kill from point to the end of the current word, or if between
+ words, to the end of the next word. Word boundaries are the same
+ as 'forward-word'.
+
+'backward-kill-word (M-<DEL>)'
+ Kill the word behind point. Word boundaries are the same as
+ 'backward-word'.
+
+'unix-word-rubout (C-w)'
+ Kill the word behind point, using white space as a word boundary.
+ The killed text is saved on the kill-ring.
+
+'unix-filename-rubout ()'
+ Kill the word behind point, using white space and the slash
+ character as the word boundaries. The killed text is saved on the
+ kill-ring.
+
+'delete-horizontal-space ()'
+ Delete all spaces and tabs around point. By default, this is
+ unbound.
+
+'kill-region ()'
+ Kill the text in the current region. By default, this command is
+ unbound.
+
+'copy-region-as-kill ()'
+ Copy the text in the region to the kill buffer, so it can be yanked
+ right away. By default, this command is unbound.
+
+'copy-backward-word ()'
+ Copy the word before point to the kill buffer. The word boundaries
+ are the same as 'backward-word'. By default, this command is
+ unbound.
+
+'copy-forward-word ()'
+ Copy the word following point to the kill buffer. The word
+ boundaries are the same as 'forward-word'. By default, this
+ command is unbound.
+
+'yank (C-y)'
+ Yank the top of the kill ring into the buffer at point.
+
+'yank-pop (M-y)'
+ Rotate the kill-ring, and yank the new top. You can only do this
+ if the prior command is 'yank' or 'yank-pop'.
+
+\1f
+File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
+
+32.4.5 Specifying Numeric Arguments
+-----------------------------------
+
+'digit-argument (M-0, M-1, ... M--)'
+ Add this digit to the argument already accumulating, or start a new
+ argument. 'M--' starts a negative argument.
+
+'universal-argument ()'
+ This is another way to specify an argument. If this command is
+ followed by one or more digits, optionally with a leading minus
+ sign, those digits define the argument. If the command is followed
+ by digits, executing 'universal-argument' again ends the numeric
+ argument, but is otherwise ignored. As a special case, if this
+ command is immediately followed by a character that is neither a
+ digit or minus sign, the argument count for the next command is
+ multiplied by four. The argument count is initially one, so
+ executing this function the first time makes the argument count
+ four, a second time makes the argument count sixteen, and so on.
+ By default, this is not bound to a key.
+
+\1f
+File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
+
+32.4.6 Letting Readline Type For You
+------------------------------------
+
+'complete (<TAB>)'
+ Attempt to perform completion on the text before point. The actual
+ completion performed is application-specific. The default is
+ filename completion.
+
+'possible-completions (M-?)'
+ List the possible completions of the text before point. When
+ displaying completions, Readline sets the number of columns used
+ for display to the value of 'completion-display-width', the value
+ of the environment variable 'COLUMNS', or the screen width, in that
+ order.
+
+'insert-completions (M-*)'
+ Insert all completions of the text before point that would have
+ been generated by 'possible-completions'.
+
+'menu-complete ()'
+ Similar to 'complete', but replaces the word to be completed with a
+ single match from the list of possible completions. Repeated
+ execution of 'menu-complete' steps through the list of possible
+ completions, inserting each match in turn. At the end of the list
+ of completions, the bell is rung (subject to the setting of
+ 'bell-style') and the original text is restored. An argument of N
+ moves N positions forward in the list of matches; a negative
+ argument may be used to move backward through the list. This
+ command is intended to be bound to <TAB>, but is unbound by
+ default.
+
+'menu-complete-backward ()'
+ Identical to 'menu-complete', but moves backward through the list
+ of possible completions, as if 'menu-complete' had been given a
+ negative argument.
+
+'delete-char-or-list ()'
+ Deletes the character under the cursor if not at the beginning or
+ end of the line (like 'delete-char'). If at the end of the line,
+ behaves identically to 'possible-completions'. This command is
+ unbound by default.
+
+\1f
+File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
+
+32.4.7 Keyboard Macros
+----------------------
+
+'start-kbd-macro (C-x ()'
+ Begin saving the characters typed into the current keyboard macro.
+
+'end-kbd-macro (C-x ))'
+ Stop saving the characters typed into the current keyboard macro
+ and save the definition.
+
+'call-last-kbd-macro (C-x e)'
+ Re-execute the last keyboard macro defined, by making the
+ characters in the macro appear as if typed at the keyboard.
+
+\1f
+File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
+
+32.4.8 Some Miscellaneous Commands
+----------------------------------
+
+'re-read-init-file (C-x C-r)'
+ Read in the contents of the INPUTRC file, and incorporate any
+ bindings or variable assignments found there.
+
+'abort (C-g)'
+ Abort the current editing command and ring the terminal's bell
+ (subject to the setting of 'bell-style').
+
+'do-uppercase-version (M-a, M-b, M-X, ...)'
+ If the metafied character X is lowercase, run the command that is
+ bound to the corresponding uppercase character.
+
+'prefix-meta (<ESC>)'
+ Metafy the next character typed. This is for keyboards without a
+ meta key. Typing '<ESC> f' is equivalent to typing 'M-f'.
+
+'undo (C-_ or C-x C-u)'
+ Incremental undo, separately remembered for each line.
+
+'revert-line (M-r)'
+ Undo all changes made to this line. This is like executing the
+ 'undo' command enough times to get back to the beginning.
+
+'tilde-expand (M-~)'
+ Perform tilde expansion on the current word.
+
+'set-mark (C-@)'
+ Set the mark to the point. If a numeric argument is supplied, the
+ mark is set to that position.
+
+'exchange-point-and-mark (C-x C-x)'
+ Swap the point with the mark. The current cursor position is set
+ to the saved position, and the old cursor position is saved as the
+ mark.
+
+'character-search (C-])'
+ A character is read and point is moved to the next occurrence of
+ that character. A negative count searches for previous
+ occurrences.
+
+'character-search-backward (M-C-])'
+ A character is read and point is moved to the previous occurrence
+ of that character. A negative count searches for subsequent
+ occurrences.
+
+'skip-csi-sequence ()'
+ Read enough characters to consume a multi-key sequence such as
+ those defined for keys like Home and End. Such sequences begin
+ with a Control Sequence Indicator (CSI), usually ESC-[. If this
+ sequence is bound to "\e[", keys producing such sequences will have
+ no effect unless explicitly bound to a readline command, instead of
+ inserting stray characters into the editing buffer. This is
+ unbound by default, but usually bound to ESC-[.
+
+'insert-comment (M-#)'
+ Without a numeric argument, the value of the 'comment-begin'
+ variable is inserted at the beginning of the current line. If a
+ numeric argument is supplied, this command acts as a toggle: if the
+ characters at the beginning of the line do not match the value of
+ 'comment-begin', the value is inserted, otherwise the characters in
+ 'comment-begin' are deleted from the beginning of the line. In
+ either case, the line is accepted as if a newline had been typed.
+
+'dump-functions ()'
+ Print all of the functions and their key bindings to the Readline
+ output stream. If a numeric argument is supplied, the output is
+ formatted in such a way that it can be made part of an INPUTRC
+ file. This command is unbound by default.
+
+'dump-variables ()'
+ Print all of the settable variables and their values to the
+ Readline output stream. If a numeric argument is supplied, the
+ output is formatted in such a way that it can be made part of an
+ INPUTRC file. This command is unbound by default.
+
+'dump-macros ()'
+ Print all of the Readline key sequences bound to macros and the
+ strings they output. If a numeric argument is supplied, the output
+ is formatted in such a way that it can be made part of an INPUTRC
+ file. This command is unbound by default.
+
+'emacs-editing-mode (C-e)'
+ When in 'vi' command mode, this causes a switch to 'emacs' editing
+ mode.
+
+'vi-editing-mode (M-C-j)'
+ When in 'emacs' editing mode, this causes a switch to 'vi' editing
+ mode.
+
+\1f
+File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
+
+32.5 Readline vi Mode
+=====================
+
+While the Readline library does not have a full set of 'vi' editing
+functions, it does contain enough to allow simple editing of the line.
+The Readline 'vi' mode behaves as specified in the POSIX standard.
+
+ In order to switch interactively between 'emacs' and 'vi' editing
+modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi'
+mode and to vi-editing-mode in 'emacs' mode). The Readline default is
+'emacs' mode.
+
+ When you enter a line in 'vi' mode, you are already placed in
+'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches
+you into 'command' mode, where you can edit the text of the line with
+the standard 'vi' movement keys, move to previous history lines with 'k'
+and subsequent lines with 'j', and so forth.
+
+\1f
+File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top
+
+33 Using History Interactively
+******************************
+
+This chapter describes how to use the GNU History Library interactively,
+from a user's standpoint. It should be considered a user's guide. For
+information on using the GNU History Library in your own programs, *note
+(history)Programming with GNU History::.
+
+* Menu:
+
+* History Interaction:: What it feels like using History as a user.
+
+\1f
+File: gdb.info, Node: History Interaction, Up: Using History Interactively
+
+33.1 History Expansion
+======================
+
+The History library provides a history expansion feature that is similar
+to the history expansion provided by 'csh'. This section describes the
+syntax used to manipulate the history information.
+
+ History expansions introduce words from the history list into the
+input stream, making it easy to repeat commands, insert the arguments to
+a previous command into the current input line, or fix errors in
+previous commands quickly.
+
+ History expansion takes place in two parts. The first is to
+determine which line from the history list should be used during
+substitution. The second is to select portions of that line for
+inclusion into the current one. The line selected from the history is
+called the "event", and the portions of that line that are acted upon
+are called "words". Various "modifiers" are available to manipulate the
+selected words. The line is broken into words in the same fashion that
+Bash does, so that several words surrounded by quotes are considered one
+word. History expansions are introduced by the appearance of the
+history expansion character, which is '!' by default.
+
+* Menu:
+
+* Event Designators:: How to specify which history line to use.
+* Word Designators:: Specifying which words are of interest.
+* Modifiers:: Modifying the results of substitution.
+
+\1f
+File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
+
+33.1.1 Event Designators
+------------------------
+
+An event designator is a reference to a command line entry in the
+history list. Unless the reference is absolute, events are relative to
+the current position in the history list.
+
+'!'
+ Start a history substitution, except when followed by a space, tab,
+ the end of the line, or '='.
+
+'!N'
+ Refer to command line N.
+
+'!-N'
+ Refer to the command N lines back.
+
+'!!'
+ Refer to the previous command. This is a synonym for '!-1'.
+
+'!STRING'
+ Refer to the most recent command preceding the current position in
+ the history list starting with STRING.
+
+'!?STRING[?]'
+ Refer to the most recent command preceding the current position in
+ the history list containing STRING. The trailing '?' may be
+ omitted if the STRING is followed immediately by a newline.
+
+'^STRING1^STRING2^'
+ Quick Substitution. Repeat the last command, replacing STRING1
+ with STRING2. Equivalent to '!!:s/STRING1/STRING2/'.
+
+'!#'
+ The entire command line typed so far.
+
+\1f
+File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
+
+33.1.2 Word Designators
+-----------------------
+
+Word designators are used to select desired words from the event. A ':'
+separates the event specification from the word designator. It may be
+omitted if the word designator begins with a '^', '$', '*', '-', or '%'.
+Words are numbered from the beginning of the line, with the first word
+being denoted by 0 (zero). Words are inserted into the current line
+separated by single spaces.
+
+ For example,
+
+'!!'
+ designates the preceding command. When you type this, the
+ preceding command is repeated in toto.
+
+'!!:$'
+ designates the last argument of the preceding command. This may be
+ shortened to '!$'.
+
+'!fi:2'
+ designates the second argument of the most recent command starting
+ with the letters 'fi'.
+
+ Here are the word designators:
+
+'0 (zero)'
+ The '0'th word. For many applications, this is the command word.
+
+'N'
+ The Nth word.
+
+'^'
+ The first argument; that is, word 1.
+
+'$'
+ The last argument.
+
+'%'
+ The word matched by the most recent '?STRING?' search.
+
+'X-Y'
+ A range of words; '-Y' abbreviates '0-Y'.
+
+'*'
+ All of the words, except the '0'th. This is a synonym for '1-$'.
+ It is not an error to use '*' if there is just one word in the
+ event; the empty string is returned in that case.
+
+'X*'
+ Abbreviates 'X-$'
+
+'X-'
+ Abbreviates 'X-$' like 'X*', but omits the last word.
+
+ If a word designator is supplied without an event specification, the
+previous command is used as the event.
+
+\1f
+File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
+
+33.1.3 Modifiers
+----------------
+
+After the optional word designator, you can add a sequence of one or
+more of the following modifiers, each preceded by a ':'.
+
+'h'
+ Remove a trailing pathname component, leaving only the head.
+
+'t'
+ Remove all leading pathname components, leaving the tail.
+
+'r'
+ Remove a trailing suffix of the form '.SUFFIX', leaving the
+ basename.
+
+'e'
+ Remove all but the trailing suffix.
+
+'p'
+ Print the new command but do not execute it.
+
+'s/OLD/NEW/'
+ Substitute NEW for the first occurrence of OLD in the event line.
+ Any delimiter may be used in place of '/'. The delimiter may be
+ quoted in OLD and NEW with a single backslash. If '&' appears in
+ NEW, it is replaced by OLD. A single backslash will quote the '&'.
+ The final delimiter is optional if it is the last character on the
+ input line.
+
+'&'
+ Repeat the previous substitution.
+
+'g'
+'a'
+ Cause changes to be applied over the entire event line. Used in
+ conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.
+
+'G'
+ Apply the following 's' modifier once to each word in the event.
+
+\1f
+File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top
+
+Appendix A In Memoriam
+**********************
+
+The GDB project mourns the loss of the following long-time contributors:
+
+'Fred Fish'
+ Fred was a long-standing contributor to GDB (1991-2006), and to
+ Free Software in general. Outside of GDB, he was known in the
+ Amiga world for his series of Fish Disks, and the GeekGadget
+ project.
+
+'Michael Snyder'
+ Michael was one of the Global Maintainers of the GDB project, with
+ contributions recorded as early as 1996, until 2011. In addition
+ to his day to day participation, he was a large driving force
+ behind adding Reverse Debugging to GDB.
+
+ Beyond their technical contributions to the project, they were also
+enjoyable members of the Free Software Community. We will miss them.
+
+\1f
+File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top
+
+Appendix B Formatting Documentation
+***********************************
+
+The GDB 4 release includes an already-formatted reference card, ready
+for printing with PostScript or Ghostscript, in the 'gdb' subdirectory
+of the main source directory(1). If you can use PostScript or
+Ghostscript with your printer, you can print the reference card
+immediately with 'refcard.ps'.
+
+ The release also includes the source for the reference card. You can
+format it, using TeX, by typing:
+
+ make refcard.dvi
+
+ The GDB reference card is designed to print in "landscape" mode on US
+"letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
+high. You will need to specify this form of printing as an option to
+your DVI output program.
+
+ All the documentation for GDB comes as part of the machine-readable
+distribution. The documentation is written in Texinfo format, which is
+a documentation system that uses a single source file to produce both
+on-line information and a printed manual. You can use one of the Info
+formatting commands to create the on-line version of the documentation
+and TeX (or 'texi2roff') to typeset the printed version.
+
+ GDB includes an already formatted copy of the on-line Info version of
+this manual in the 'gdb' subdirectory. The main Info file is
+'gdb-7.9/gdb/gdb.info', and it refers to subordinate files matching
+'gdb.info*' in the same directory. If necessary, you can print out
+these files, or read them with any editor; but they are easier to read
+using the 'info' subsystem in GNU Emacs or the standalone 'info'
+program, available as part of the GNU Texinfo distribution.
+
+ If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'.
+
+ If you have 'makeinfo' installed, and are in the top level GDB source
+directory ('gdb-7.9', in the case of version 7.9), you can make the Info
+file by typing:
+
+ cd gdb
+ make gdb.info
+
+ If you want to typeset and print copies of this manual, you need TeX,
+a program to print its DVI output files, and 'texinfo.tex', the Texinfo
+definitions file.
+
+ TeX is a typesetting program; it does not print files directly, but
+produces output files called DVI files. To print a typeset document,
+you need a program to print DVI files. If your system has TeX
+installed, chances are it has such a program. The precise command to
+use depends on your system; 'lpr -d' is common; another (for PostScript
+devices) is 'dvips'. The DVI print command may require a file name
+without any extension or a '.dvi' extension.
+
+ TeX also requires a macro definitions file called 'texinfo.tex'.
+This file tells TeX how to typeset a document written in Texinfo format.
+On its own, TeX cannot either read or typeset a Texinfo file.
+'texinfo.tex' is distributed with GDB and is located in the
+'gdb-VERSION-NUMBER/texinfo' directory.
+
+ If you have TeX and a DVI printer program installed, you can typeset
+and print this manual. First switch to the 'gdb' subdirectory of the
+main source directory (for example, to 'gdb-7.9/gdb') and type:
+
+ make gdb.dvi
+
+ Then give 'gdb.dvi' to your DVI printing program.
+
+ ---------- Footnotes ----------
+
+ (1) In 'gdb-7.9/gdb/refcard.ps' of the version 7.9 release.
+
+\1f
+File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
+
+Appendix C Installing GDB
+*************************
+
+* Menu:
+
+* Requirements:: Requirements for building GDB
+* Running Configure:: Invoking the GDB 'configure' script
+* Separate Objdir:: Compiling GDB in another directory
+* Config Names:: Specifying names for hosts and targets
+* Configure Options:: Summary of options for configure
+* System-wide configuration:: Having a system-wide init file
+
+\1f
+File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
+
+C.1 Requirements for Building GDB
+=================================
+
+Building GDB requires various tools and packages to be available. Other
+packages will be used only if they are found.
+
+Tools/Packages Necessary for Building GDB
+=========================================
+
+ISO C90 compiler
+ GDB is written in ISO C90. It should be buildable with any working
+ C90 compiler, e.g. GCC.
+
+Tools/Packages Optional for Building GDB
+========================================
+
+Expat
+ GDB can use the Expat XML parsing library. This library may be
+ included with your operating system distribution; if it is not, you
+ can get the latest version from <http://expat.sourceforge.net>.
+ The 'configure' script will search for this library in several
+ standard locations; if it is installed in an unusual path, you can
+ use the '--with-libexpat-prefix' option to specify its location.
+
+ Expat is used for:
+
+ * Remote protocol memory maps (*note Memory Map Format::)
+ * Target descriptions (*note Target Descriptions::)
+ * Remote shared library lists (*Note Library List Format::, or
+ alternatively *note Library List Format for SVR4 Targets::)
+ * MS-Windows shared libraries (*note Shared Libraries::)
+ * Traceframe info (*note Traceframe Info Format::)
+ * Branch trace (*note Branch Trace Format::)
+
+zlib
+ GDB will use the 'zlib' library, if available, to read compressed
+ debug sections. Some linkers, such as GNU gold, are capable of
+ producing binaries with compressed debug sections. If GDB is
+ compiled with 'zlib', it will be able to read the debug information
+ in such binaries.
+
+ The 'zlib' library is likely included with your operating system
+ distribution; if it is not, you can get the latest version from
+ <http://zlib.net>.
+
+iconv
+ GDB's features related to character sets (*note Character Sets::)
+ require a functioning 'iconv' implementation. If you are on a GNU
+ system, then this is provided by the GNU C Library. Some other
+ systems also provide a working 'iconv'.
+
+ If GDB is using the 'iconv' program which is installed in a
+ non-standard place, you will need to tell GDB where to find it.
+ This is done with '--with-iconv-bin' which specifies the directory
+ that contains the 'iconv' program.
+
+ On systems without 'iconv', you can install GNU Libiconv. If you
+ have previously installed Libiconv, you can use the
+ '--with-libiconv-prefix' option to configure.
+
+ GDB's top-level 'configure' and 'Makefile' will arrange to build
+ Libiconv if a directory named 'libiconv' appears in the top-most
+ source directory. If Libiconv is built this way, and if the
+ operating system does not provide a suitable 'iconv'
+ implementation, then the just-built library will automatically be
+ used by GDB. One easy way to set this up is to download GNU
+ Libiconv, unpack it, and then rename the directory holding the
+ Libiconv source code to 'libiconv'.
+
+\1f
+File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
+
+C.2 Invoking the GDB 'configure' Script
+=======================================
+
+GDB comes with a 'configure' script that automates the process of
+preparing GDB for installation; you can then use 'make' to build the
+'gdb' program.
+
+ The GDB distribution includes all the source code you need for GDB in
+a single directory, whose name is usually composed by appending the
+version number to 'gdb'.
+
+ For example, the GDB version 7.9 distribution is in the 'gdb-7.9'
+directory. That directory contains:
+
+'gdb-7.9/configure (and supporting files)'
+ script for configuring GDB and all its supporting libraries
+
+'gdb-7.9/gdb'
+ the source specific to GDB itself
+
+'gdb-7.9/bfd'
+ source for the Binary File Descriptor library
+
+'gdb-7.9/include'
+ GNU include files
+
+'gdb-7.9/libiberty'
+ source for the '-liberty' free software library
+
+'gdb-7.9/opcodes'
+ source for the library of opcode tables and disassemblers
+
+'gdb-7.9/readline'
+ source for the GNU command-line interface
+
+'gdb-7.9/glob'
+ source for the GNU filename pattern-matching subroutine
+
+'gdb-7.9/mmalloc'
+ source for the GNU memory-mapped malloc package
+
+ The simplest way to configure and build GDB is to run 'configure'
+from the 'gdb-VERSION-NUMBER' source directory, which in this example is
+the 'gdb-7.9' directory.
+
+ First switch to the 'gdb-VERSION-NUMBER' source directory if you are
+not already in it; then run 'configure'. Pass the identifier for the
+platform on which GDB will run as an argument.
+
+ For example:
+
+ cd gdb-7.9
+ ./configure HOST
+ make
+
+where HOST is an identifier such as 'sun4' or 'decstation', that
+identifies the platform where GDB will run. (You can often leave off
+HOST; 'configure' tries to guess the correct value by examining your
+system.)
+
+ Running 'configure HOST' and then running 'make' builds the 'bfd',
+'readline', 'mmalloc', and 'libiberty' libraries, then 'gdb' itself.
+The configured source files, and the binaries, are left in the
+corresponding source directories.
+
+ 'configure' is a Bourne-shell ('/bin/sh') script; if your system does
+not recognize this automatically when you run a different shell, you may
+need to run 'sh' on it explicitly:
+
+ sh configure HOST
+
+ If you run 'configure' from a directory that contains source
+directories for multiple libraries or programs, such as the 'gdb-7.9'
+source directory for version 7.9, 'configure' creates configuration
+files for every directory level underneath (unless you tell it not to,
+with the '--norecursion' option).
+
+ You should run the 'configure' script from the top directory in the
+source tree, the 'gdb-VERSION-NUMBER' directory. If you run 'configure'
+from one of the subdirectories, you will configure only that
+subdirectory. That is usually not what you want. In particular, if you
+run the first 'configure' from the 'gdb' subdirectory of the
+'gdb-VERSION-NUMBER' directory, you will omit the configuration of
+'bfd', 'readline', and other sibling directories of the 'gdb'
+subdirectory. This leads to build errors about missing include files
+such as 'bfd/bfd.h'.
+
+ You can install 'gdb' anywhere; it has no hardwired paths. However,
+you should make sure that the shell on your path (named by the 'SHELL'
+environment variable) is publicly readable. Remember that GDB uses the
+shell to start your program--some systems refuse to let GDB debug child
+processes whose programs are not readable.
+
+\1f
+File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
+
+C.3 Compiling GDB in Another Directory
+======================================
+
+If you want to run GDB versions for several host or target machines, you
+need a different 'gdb' compiled for each combination of host and target.
+'configure' is designed to make this easy by allowing you to generate
+each configuration in a separate subdirectory, rather than in the source
+directory. If your 'make' program handles the 'VPATH' feature (GNU
+'make' does), running 'make' in each of these directories builds the
+'gdb' program specified there.
+
+ To build 'gdb' in a separate directory, run 'configure' with the
+'--srcdir' option to specify where to find the source. (You also need
+to specify a path to find 'configure' itself from your working
+directory. If the path to 'configure' would be the same as the argument
+to '--srcdir', you can leave out the '--srcdir' option; it is assumed.)
+
+ For example, with version 7.9, you can build GDB in a separate
+directory for a Sun 4 like this:
+
+ cd gdb-7.9
+ mkdir ../gdb-sun4
+ cd ../gdb-sun4
+ ../gdb-7.9/configure sun4
+ make
+
+ When 'configure' builds a configuration using a remote source
+directory, it creates a tree for the binaries with the same structure
+(and using the same names) as the tree under the source directory. In
+the example, you'd find the Sun 4 library 'libiberty.a' in the directory
+'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'.
+
+ Make sure that your path to the 'configure' script has just one
+instance of 'gdb' in it. If your path to 'configure' looks like
+'../gdb-7.9/gdb/configure', you are configuring only one subdirectory of
+GDB, not the whole package. This leads to build errors about missing
+include files such as 'bfd/bfd.h'.
+
+ One popular reason to build several GDB configurations in separate
+directories is to configure GDB for cross-compiling (where GDB runs on
+one machine--the "host"--while debugging programs that run on another
+machine--the "target"). You specify a cross-debugging target by giving
+the '--target=TARGET' option to 'configure'.
+
+ When you run 'make' to build a program or library, you must run it in
+a configured directory--whatever directory you were in when you called
+'configure' (or one of its subdirectories).
+
+ The 'Makefile' that 'configure' generates in each source directory
+also runs recursively. If you type 'make' in a source directory such as
+'gdb-7.9' (or in a separate configured directory configured with
+'--srcdir=DIRNAME/gdb-7.9'), you will build all the required libraries,
+and then build GDB.
+
+ When you have multiple hosts or targets configured in separate
+directories, you can run 'make' on them in parallel (for example, if
+they are NFS-mounted on each of the hosts); they will not interfere with
+each other.
+
+\1f
+File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
+
+C.4 Specifying Names for Hosts and Targets
+==========================================
+
+The specifications used for hosts and targets in the 'configure' script
+are based on a three-part naming scheme, but some short predefined
+aliases are also supported. The full naming scheme encodes three pieces
+of information in the following pattern:
+
+ ARCHITECTURE-VENDOR-OS
+
+ For example, you can use the alias 'sun4' as a HOST argument, or as
+the value for TARGET in a '--target=TARGET' option. The equivalent full
+name is 'sparc-sun-sunos4'.
+
+ The 'configure' script accompanying GDB does not provide any query
+facility to list all supported host and target names or aliases.
+'configure' calls the Bourne shell script 'config.sub' to map
+abbreviations to full names; you can read the script, if you wish, or
+you can use it to test your guesses on abbreviations--for example:
+
+ % sh config.sub i386-linux
+ i386-pc-linux-gnu
+ % sh config.sub alpha-linux
+ alpha-unknown-linux-gnu
+ % sh config.sub hp9k700
+ hppa1.1-hp-hpux
+ % sh config.sub sun4
+ sparc-sun-sunos4.1.1
+ % sh config.sub sun3
+ m68k-sun-sunos4.1.1
+ % sh config.sub i986v
+ Invalid configuration `i986v': machine `i986v' not recognized
+
+'config.sub' is also distributed in the GDB source directory ('gdb-7.9',
+for version 7.9).
+
+\1f
+File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
+
+C.5 'configure' Options
+=======================
+
+Here is a summary of the 'configure' options and arguments that are most
+often useful for building GDB. 'configure' also has several other
+options not listed here. *note (configure.info)What Configure Does::,
+for a full explanation of 'configure'.
+
+ configure [--help]
+ [--prefix=DIR]
+ [--exec-prefix=DIR]
+ [--srcdir=DIRNAME]
+ [--norecursion] [--rm]
+ [--target=TARGET]
+ HOST
+
+You may introduce options with a single '-' rather than '--' if you
+prefer; but you may abbreviate option names if you use '--'.
+
+'--help'
+ Display a quick summary of how to invoke 'configure'.
+
+'--prefix=DIR'
+ Configure the source to install programs and files under directory
+ 'DIR'.
+
+'--exec-prefix=DIR'
+ Configure the source to install programs under directory 'DIR'.
+
+'--srcdir=DIRNAME'
+ *Warning: using this option requires GNU 'make', or another 'make'
+ that implements the 'VPATH' feature.*
+ Use this option to make configurations in directories separate from
+ the GDB source directories. Among other things, you can use this
+ to build (or maintain) several configurations simultaneously, in
+ separate directories. 'configure' writes configuration-specific
+ files in the current directory, but arranges for them to use the
+ source in the directory DIRNAME. 'configure' creates directories
+ under the working directory in parallel to the source directories
+ below DIRNAME.
+
+'--norecursion'
+ Configure only the directory level where 'configure' is executed;
+ do not propagate configuration to subdirectories.
+
+'--target=TARGET'
+ Configure GDB for cross-debugging programs running on the specified
+ TARGET. Without this option, GDB is configured to debug programs
+ that run on the same machine (HOST) as GDB itself.
+
+ There is no convenient way to generate a list of all available
+ targets.
+
+'HOST ...'
+ Configure GDB to run on the specified HOST.
+
+ There is no convenient way to generate a list of all available
+ hosts.
+
+ There are many other options available as well, but they are
+generally needed for special purposes only.
+
+\1f
+File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
+
+C.6 System-wide configuration and settings
+==========================================
+
+GDB can be configured to have a system-wide init file; this file will be
+read and executed at startup (*note What GDB does during startup:
+Startup.).
+
+ Here is the corresponding configure option:
+
+'--with-system-gdbinit=FILE'
+ Specify that the default location of the system-wide init file is
+ FILE.
+
+ If GDB has been configured with the option '--prefix=$prefix', it may
+be subject to relocation. Two possible cases:
+
+ * If the default location of this init file contains '$prefix', it
+ will be subject to relocation. Suppose that the configure options
+ are '--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
+ if GDB is moved from '$prefix' to '$install', the system init file
+ is looked for as '$install/etc/gdbinit' instead of
+ '$prefix/etc/gdbinit'.
+
+ * By contrast, if the default location does not contain the prefix,
+ it will not be relocated. E.g. if GDB has been configured with
+ '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
+ then GDB will always look for '/usr/share/gdb/gdbinit', wherever
+ GDB is installed.
+
+ If the configured location of the system-wide init file (as given by
+the '--with-system-gdbinit' option at configure time) is in the
+data-directory (as specified by '--with-gdb-datadir' at configure time)
+or in one of its subdirectories, then GDB will look for the system-wide
+init file in the directory specified by the '--data-directory'
+command-line option. Note that the system-wide init file is only read
+once, during GDB initialization. If the data-directory is changed after
+GDB has started with the 'set data-directory' command, the file will not
+be reread.
+
+* Menu:
+
+* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
+
+\1f
+File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration
+
+C.6.1 Installed System-wide Configuration Scripts
+-------------------------------------------------
+
+The 'system-gdbinit' directory, located inside the data-directory (as
+specified by '--with-gdb-datadir' at configure time) contains a number
+of scripts which can be used as system-wide init files. To
+automatically source those scripts at startup, GDB should be configured
+with '--with-system-gdbinit'. Otherwise, any user should be able to
+source them by hand as needed.
+
+ The following scripts are currently available:
+
+ * 'elinos.py' This script is useful when debugging a program on an
+ ELinOS target. It takes advantage of the environment variables
+ defined in a standard ELinOS environment in order to determine the
+ location of the system shared libraries, and then sets the
+ 'solib-absolute-prefix' and 'solib-search-path' variables
+ appropriately.
+
+ * 'wrs-linux.py' This script is useful when debugging a program on a
+ target running Wind River Linux. It expects the 'ENV_PREFIX' to be
+ set to the host-side sysroot used by the target system.
+
+\1f
+File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
+
+Appendix D Maintenance Commands
+*******************************
+
+In addition to commands intended for GDB users, GDB includes a number of
+commands intended for GDB developers, that are not documented elsewhere
+in this manual. These commands are provided here for reference. (For
+commands that turn on debugging messages, see *note Debugging Output::.)
+
+'maint agent [-at LOCATION,] EXPRESSION'
+'maint agent-eval [-at LOCATION,] EXPRESSION'
+ Translate the given EXPRESSION into remote agent bytecodes. This
+ command is useful for debugging the Agent Expression mechanism
+ (*note Agent Expressions::). The 'agent' version produces an
+ expression useful for data collection, such as by tracepoints,
+ while 'maint agent-eval' produces an expression that evaluates
+ directly to a result. For instance, a collection expression for
+ 'globa + globb' will include bytecodes to record four bytes of
+ memory at each of the addresses of 'globa' and 'globb', while
+ discarding the result of the addition, while an evaluation
+ expression will do the addition and return the sum. If '-at' is
+ given, generate remote agent bytecode for LOCATION. If not,
+ generate remote agent bytecode for current frame PC address.
+
+'maint agent-printf FORMAT,EXPR,...'
+ Translate the given format string and list of argument expressions
+ into remote agent bytecodes and display them as a disassembled
+ list. This command is useful for debugging the agent version of
+ dynamic printf (*note Dynamic Printf::).
+
+'maint info breakpoints'
+ Using the same format as 'info breakpoints', display both the
+ breakpoints you've set explicitly, and those GDB is using for
+ internal purposes. Internal breakpoints are shown with negative
+ breakpoint numbers. The type column identifies what kind of
+ breakpoint is shown:
+
+ 'breakpoint'
+ Normal, explicitly set breakpoint.
+
+ 'watchpoint'
+ Normal, explicitly set watchpoint.
+
+ 'longjmp'
+ Internal breakpoint, used to handle correctly stepping through
+ 'longjmp' calls.
+
+ 'longjmp resume'
+ Internal breakpoint at the target of a 'longjmp'.
+
+ 'until'
+ Temporary internal breakpoint used by the GDB 'until' command.
+
+ 'finish'
+ Temporary internal breakpoint used by the GDB 'finish'
+ command.
+
+ 'shlib events'
+ Shared library events.
+
+'maint info bfds'
+ This prints information about each 'bfd' object that is known to
+ GDB. *Note BFD: (bfd)Top.
+
+'set displaced-stepping'
+'show displaced-stepping'
+ Control whether or not GDB will do "displaced stepping" if the
+ target supports it. Displaced stepping is a way to single-step
+ over breakpoints without removing them from the inferior, by
+ executing an out-of-line copy of the instruction that was
+ originally at the breakpoint location. It is also known as
+ out-of-line single-stepping.
+
+ 'set displaced-stepping on'
+ If the target architecture supports it, GDB will use displaced
+ stepping to step over breakpoints.
+
+ 'set displaced-stepping off'
+ GDB will not use displaced stepping to step over breakpoints,
+ even if such is supported by the target architecture.
+
+ 'set displaced-stepping auto'
+ This is the default mode. GDB will use displaced stepping
+ only if non-stop mode is active (*note Non-Stop Mode::) and
+ the target architecture supports displaced stepping.
+
+'maint check-psymtabs'
+ Check the consistency of currently expanded psymtabs versus
+ symtabs. Use this to check, for example, whether a symbol is in
+ one but not the other.
+
+'maint check-symtabs'
+ Check the consistency of currently expanded symtabs.
+
+'maint expand-symtabs [REGEXP]'
+ Expand symbol tables. If REGEXP is specified, only expand symbol
+ tables for file names matching REGEXP.
+
+'maint set catch-demangler-crashes [on|off]'
+'maint show catch-demangler-crashes'
+ Control whether GDB should attempt to catch crashes in the symbol
+ name demangler. The default is to attempt to catch crashes. If
+ enabled, the first time a crash is caught, a core file is created,
+ the offending symbol is displayed and the user is presented with
+ the option to terminate the current session.
+
+'maint cplus first_component NAME'
+ Print the first C++ class/namespace component of NAME.
+
+'maint cplus namespace'
+ Print the list of possible C++ namespaces.
+
+'maint deprecate COMMAND [REPLACEMENT]'
+'maint undeprecate COMMAND'
+ Deprecate or undeprecate the named COMMAND. Deprecated commands
+ cause GDB to issue a warning when you use them. The optional
+ argument REPLACEMENT says which newer command should be used in
+ favor of the deprecated one; if it is given, GDB will mention the
+ replacement as part of the warning.
+
+'maint dump-me'
+ Cause a fatal signal in the debugger and force it to dump its core.
+ This is supported only on systems which support aborting a program
+ with the 'SIGQUIT' signal.
+
+'maint internal-error [MESSAGE-TEXT]'
+'maint internal-warning [MESSAGE-TEXT]'
+'maint demangler-warning [MESSAGE-TEXT]'
+
+ Cause GDB to call the internal function 'internal_error',
+ 'internal_warning' or 'demangler_warning' and hence behave as
+ though an internal problam has been detected. In addition to
+ reporting the internal problem, these functions give the user the
+ opportunity to either quit GDB or (for 'internal_error' and
+ 'internal_warning') create a core file of the current GDB session.
+
+ These commands take an optional parameter MESSAGE-TEXT that is used
+ as the text of the error or warning message.
+
+ Here's an example of using 'internal-error':
+
+ (gdb) maint internal-error testing, 1, 2
+ .../maint.c:121: internal-error: testing, 1, 2
+ A problem internal to GDB has been detected. Further
+ debugging may prove unreliable.
+ Quit this debugging session? (y or n) n
+ Create a core file? (y or n) n
+ (gdb)
+
+'maint set internal-error ACTION [ask|yes|no]'
+'maint show internal-error ACTION'
+'maint set internal-warning ACTION [ask|yes|no]'
+'maint show internal-warning ACTION'
+'maint set demangler-warning ACTION [ask|yes|no]'
+'maint show demangler-warning ACTION'
+ When GDB reports an internal problem (error or warning) it gives
+ the user the opportunity to both quit GDB and create a core file of
+ the current GDB session. These commands let you override the
+ default behaviour for each particular ACTION, described in the
+ table below.
+
+ 'quit'
+ You can specify that GDB should always (yes) or never (no)
+ quit. The default is to ask the user what to do.
+
+ 'corefile'
+ You can specify that GDB should always (yes) or never (no)
+ create a core file. The default is to ask the user what to
+ do. Note that there is no 'corefile' option for
+ 'demangler-warning': demangler warnings always create a core
+ file and this cannot be disabled.
+
+'maint packet TEXT'
+ If GDB is talking to an inferior via the serial protocol, then this
+ command sends the string TEXT to the inferior, and displays the
+ response packet. GDB supplies the initial '$' character, the
+ terminating '#' character, and the checksum.
+
+'maint print architecture [FILE]'
+ Print the entire architecture configuration. The optional argument
+ FILE names the file where the output goes.
+
+'maint print c-tdesc'
+ Print the current target description (*note Target Descriptions::)
+ as a C source file. The created source file can be used in GDB
+ when an XML parser is not available to parse the description.
+
+'maint print dummy-frames'
+ Prints the contents of GDB's internal dummy-frame stack.
+
+ (gdb) b add
+ ...
+ (gdb) print add(2,3)
+ Breakpoint 2, add (a=2, b=3) at ...
+ 58 return (a + b);
+ The program being debugged stopped while in a function called from GDB.
+ ...
+ (gdb) maint print dummy-frames
+ 0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353
+ (gdb)
+
+ Takes an optional file parameter.
+
+'maint print registers [FILE]'
+'maint print raw-registers [FILE]'
+'maint print cooked-registers [FILE]'
+'maint print register-groups [FILE]'
+'maint print remote-registers [FILE]'
+ Print GDB's internal register data structures.
+
+ The command 'maint print raw-registers' includes the contents of
+ the raw register cache; the command 'maint print cooked-registers'
+ includes the (cooked) value of all registers, including registers
+ which aren't available on the target nor visible to user; the
+ command 'maint print register-groups' includes the groups that each
+ register is a member of; and the command 'maint print
+ remote-registers' includes the remote target's register numbers and
+ offsets in the 'G' packets.
+
+ These commands take an optional parameter, a file name to which to
+ write the information.
+
+'maint print reggroups [FILE]'
+ Print GDB's internal register group data structures. The optional
+ argument FILE tells to what file to write the information.
+
+ The register groups info looks like this:
+
+ (gdb) maint print reggroups
+ Group Type
+ general user
+ float user
+ all user
+ vector user
+ system user
+ save internal
+ restore internal
+
+'flushregs'
+ This command forces GDB to flush its internal register cache.
+
+'maint print objfiles [REGEXP]'
+ Print a dump of all known object files. If REGEXP is specified,
+ only print object files whose names match REGEXP. For each object
+ file, this command prints its name, address in memory, and all of
+ its psymtabs and symtabs.
+
+'maint print user-registers'
+ List all currently available "user registers". User registers
+ typically provide alternate names for actual hardware registers.
+ They include the four "standard" registers '$fp', '$pc', '$sp', and
+ '$ps'. *Note standard registers::. User registers can be used in
+ expressions in the same way as the canonical register names, but
+ only the latter are listed by the 'info registers' and 'maint print
+ registers' commands.
+
+'maint print section-scripts [REGEXP]'
+ Print a dump of scripts specified in the '.debug_gdb_section'
+ section. If REGEXP is specified, only print scripts loaded by
+ object files matching REGEXP. For each script, this command prints
+ its name as specified in the objfile, and the full path if known.
+ *Note dotdebug_gdb_scripts section::.
+
+'maint print statistics'
+ This command prints, for each object file in the program, various
+ data about that object file followed by the byte cache ("bcache")
+ statistics for the object file. The objfile data includes the
+ number of minimal, partial, full, and stabs symbols, the number of
+ types defined by the objfile, the number of as yet unexpanded psym
+ tables, the number of line tables and string tables, and the amount
+ of memory used by the various tables. The bcache statistics
+ include the counts, sizes, and counts of duplicates of all and
+ unique objects, max, average, and median entry size, total memory
+ used and its overhead and savings, and various measures of the hash
+ table size and chain lengths.
+
+'maint print target-stack'
+ A "target" is an interface between the debugger and a particular
+ kind of file or process. Targets can be stacked in "strata", so
+ that more than one target can potentially respond to a request. In
+ particular, memory accesses will walk down the stack of targets
+ until they find a target that is interested in handling that
+ particular address.
+
+ This command prints a short description of each layer that was
+ pushed on the "target stack", starting from the top layer down to
+ the bottom one.
+
+'maint print type EXPR'
+ Print the type chain for a type specified by EXPR. The argument
+ can be either a type name or a symbol. If it is a symbol, the type
+ of that symbol is described. The type chain produced by this
+ command is a recursive definition of the data type as stored in
+ GDB's data structures, including its flags and contained types.
+
+'maint set dwarf2 always-disassemble'
+'maint show dwarf2 always-disassemble'
+ Control the behavior of 'info address' when using DWARF debugging
+ information.
+
+ The default is 'off', which means that GDB should try to describe a
+ variable's location in an easily readable format. When 'on', GDB
+ will instead display the DWARF location expression in an
+ assembly-like format. Note that some locations are too complex for
+ GDB to describe simply; in this case you will always see the
+ disassembly form.
+
+ Here is an example of the resulting disassembly:
+
+ (gdb) info addr argc
+ Symbol "argc" is a complex DWARF expression:
+ 1: DW_OP_fbreg 0
+
+ For more information on these expressions, see the DWARF standard
+ (http://www.dwarfstd.org/).
+
+'maint set dwarf2 max-cache-age'
+'maint show dwarf2 max-cache-age'
+ Control the DWARF 2 compilation unit cache.
+
+ In object files with inter-compilation-unit references, such as
+ those produced by the GCC option '-feliminate-dwarf2-dups', the
+ DWARF 2 reader needs to frequently refer to previously read
+ compilation units. This setting controls how long a compilation
+ unit will remain in the cache if it is not referenced. A higher
+ limit means that cached compilation units will be stored in memory
+ longer, and more total memory will be used. Setting it to zero
+ disables caching, which will slow down GDB startup, but reduce
+ memory consumption.
+
+'maint set profile'
+'maint show profile'
+ Control profiling of GDB.
+
+ Profiling will be disabled until you use the 'maint set profile'
+ command to enable it. When you enable profiling, the system will
+ begin collecting timing and execution count data; when you disable
+ profiling or exit GDB, the results will be written to a log file.
+ Remember that if you use profiling, GDB will overwrite the
+ profiling log file (often called 'gmon.out'). If you have a record
+ of important profiling data in a 'gmon.out' file, be sure to move
+ it to a safe location.
+
+ Configuring with '--enable-profiling' arranges for GDB to be
+ compiled with the '-pg' compiler option.
+
+'maint set show-debug-regs'
+'maint show show-debug-regs'
+ Control whether to show variables that mirror the hardware debug
+ registers. Use 'on' to enable, 'off' to disable. If enabled, the
+ debug registers values are shown when GDB inserts or removes a
+ hardware breakpoint or watchpoint, and when the inferior triggers a
+ hardware-assisted breakpoint or watchpoint.
+
+'maint set show-all-tib'
+'maint show show-all-tib'
+ Control whether to show all non zero areas within a 1k block
+ starting at thread local base, when using the 'info w32
+ thread-information-block' command.
+
+'maint set target-async'
+'maint show target-async'
+ This controls whether GDB targets operate in synchronous or
+ asynchronous mode (*note Background Execution::). Normally the
+ default is asynchronous, if it is available; but this can be
+ changed to more easily debug problems occurring only in synchronous
+ mode.
+
+'maint set per-command'
+'maint show per-command'
+
+ GDB can display the resources used by each command. This is useful
+ in debugging performance problems.
+
+ 'maint set per-command space [on|off]'
+ 'maint show per-command space'
+ Enable or disable the printing of the memory used by GDB for
+ each command. If enabled, GDB will display how much memory
+ each command took, following the command's own output. This
+ can also be requested by invoking GDB with the '--statistics'
+ command-line switch (*note Mode Options::).
+
+ 'maint set per-command time [on|off]'
+ 'maint show per-command time'
+ Enable or disable the printing of the execution time of GDB
+ for each command. If enabled, GDB will display how much time
+ it took to execute each command, following the command's own
+ output. Both CPU time and wallclock time are printed.
+ Printing both is useful when trying to determine whether the
+ cost is CPU or, e.g., disk/network latency. Note that the CPU
+ time printed is for GDB only, it does not include the
+ execution time of the inferior because there's no mechanism
+ currently to compute how much time was spent by GDB and how
+ much time was spent by the program been debugged. This can
+ also be requested by invoking GDB with the '--statistics'
+ command-line switch (*note Mode Options::).
+
+ 'maint set per-command symtab [on|off]'
+ 'maint show per-command symtab'
+ Enable or disable the printing of basic symbol table
+ statistics for each command. If enabled, GDB will display the
+ following information:
+
+ a. number of symbol tables
+ b. number of primary symbol tables
+ c. number of blocks in the blockvector
+
+'maint space VALUE'
+ An alias for 'maint set per-command space'. A non-zero value
+ enables it, zero disables it.
+
+'maint time VALUE'
+ An alias for 'maint set per-command time'. A non-zero value
+ enables it, zero disables it.
+
+'maint translate-address [SECTION] ADDR'
+ Find the symbol stored at the location specified by the address
+ ADDR and an optional section name SECTION. If found, GDB prints
+ the name of the closest symbol and an offset from the symbol's
+ location to the specified address. This is similar to the 'info
+ address' command (*note Symbols::), except that this command also
+ allows to find symbols in other sections.
+
+ If section was not specified, the section in which the symbol was
+ found is also printed. For dynamically linked executables, the
+ name of executable or shared library containing the symbol is
+ printed as well.
+
+ The following command is useful for non-interactive invocations of
+GDB, such as in the test suite.
+
+'set watchdog NSEC'
+ Set the maximum number of seconds GDB will wait for the target
+ operation to finish. If this time expires, GDB reports and error
+ and the command is aborted.
+
+'show watchdog'
+ Show the current setting of the target wait timeout.
projects / platform / upstream / gdb.git / blobdiff