Google Git
Sign in
gfiber / toolchains / bruno / 19994c9c273f47d3b6ae05c4b15fd4c531f28229 / . / share / info / gdb.info-4
blob: bacc8e259e054d432ffbf411a50841f57df53c56 [file] [log] [blame]
This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* Gdb: (gdb). The GNU debugger.
END-INFO-DIR-ENTRY
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs Free
Documentation", with the Front-Cover Texts being "A GNU Manual," and
with the Back-Cover Texts as in (a) below.
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom."
This file documents the GNU debugger GDB.
This is the Ninth Edition, of `Debugging with GDB: the GNU
Source-Level Debugger' for GDB (GDB) Version 7.2.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs Free
Documentation", with the Front-Cover Texts being "A GNU Manual," and
with the Back-Cover Texts as in (a) below.
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom."

File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
27.14 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) or 1 (meaning mixed source
and disassembly).
Result
......
The output for each instruction is composed of four fields:
* Address
* Func-name
* Offset
* Instruction
Note that whatever included in the instruction field, is not
manipulated directly by GDB/MI, i.e., it is not possible to adjust its
format.
GDB Command
...........
There's no direct mapping from this command to the CLI.
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="/kwikemart/marge/ezannoni/flathead-dev/devo/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="/kwikemart/marge/ezannoni/flathead-dev/devo/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
---------------------------------------
Synopsis
........
-data-evaluate-expression EXPR
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.
GDB Command
...........
The corresponding GDB commands are `print', `output', and `call'. In
`gdbtk' only, there's a corresponding `gdb_eval' command.
Example
.......
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.
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)
The `-data-list-changed-registers' Command
------------------------------------------
Synopsis
........
-data-list-changed-registers
Display a list of the registers that have changed.
GDB Command
...........
GDB doesn't have a direct analog for this command; `gdbtk' has the
corresponding command `gdb_changed_register_list'.
Example
.......
On a PPC MBX board:
(gdb)
-exec-continue
^running
(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)
The `-data-list-register-names' Command
---------------------------------------
Synopsis
........
-data-list-register-names [ ( REGNO )+ ]
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.
GDB Command
...........
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 FMT [ ( REGNO )*]
Display the registers' contents. FMT is the format according to
which the registers' contents are to be returned, 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.
Allowed formats for FMT are:
`x'
Hexadecimal
`o'
Octal
`t'
Binary
`d'
Decimal
`r'
Raw
`N'
Natural
GDB Command
...........
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
-------------------------------
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
...........
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)

File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
27.15 GDB/MI Tracepoint Commands
================================
The commands defined in this section implement MI support for
tracepoints. For detailed introduction, see *Note Tracepoints::.
The `-trace-find' Command
-------------------------
Synopsis
........
-trace-find MODE [PARAMETERS...]
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::.
`none'
No parameters are required. Stops examining trace frames.
`frame-number'
An integer is required as parameter. Selects tracepoint frame with
that index.
`tracepoint-number'
An integer is required as parameter. Finds next trace frame that
corresponds to tracepoint with the specified number.
`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.
`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.
`line'
Line specification is required as parameter. *Note Specify
Location::. Finds next trace frame that corresponds to a
tracepoint at the specified location.
If `none' was passed as MODE, the response does not have fields.
Otherwise, the response may have the following fields:
`found'
This field has either `0' or `1' as the value, depending on
whether a matching tracepoint was found.
`traceframe'
The index of the found traceframe. This field is present iff the
`found' field has value of `1'.
`tracepoint'
The index of the found tracepoint. This field is present iff the
`found' field has value of `1'.
`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.
GDB Command
...........
The corresponding GDB command is `tfind'.
-trace-define-variable
----------------------
Synopsis
........
-trace-define-variable NAME [ VALUE ]
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.
GDB Command
...........
The corresponding GDB command is `tvariable'.
-trace-list-variables
---------------------
Synopsis
........
-trace-list-variables
Return a table of all defined trace variables. Each element of the
table has the following fields:
`name'
The name of the trace variable. This field is always present.
`initial'
The initial value. This is a 64-bit signed integer. This field
is always present.
`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.
GDB Command
...........
The corresponding GDB command is `tvariables'.
Example
.......
(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)
-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.
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'.

File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
27.16 GDB/MI Symbol Query Commands
==================================
The `-symbol-list-lines' Command
--------------------------------
Synopsis
........
-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.
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)

File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
27.17 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
------------------------------------
Synopsis
........
-file-exec-and-symbols FILE
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.
GDB Command
...........
The corresponding GDB command is `file'.
Example
.......
(gdb)
-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)
The `-file-exec-file' Command
-----------------------------
Synopsis
........
-file-exec-file FILE
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.
GDB Command
...........
The corresponding GDB command is `exec-file'.
Example
.......
(gdb)
-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)
The `-file-list-exec-source-file' Command
-----------------------------------------
Synopsis
........
-file-list-exec-source-file
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.
GDB Command
...........
The GDB equivalent is `info source'
Example
.......
(gdb)
123-file-list-exec-source-file
123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
(gdb)
The `-file-list-exec-source-files' Command
------------------------------------------
Synopsis
........
-file-list-exec-source-files
List the source files for the current executable.
It will always output the filename, but only when GDB can find the
absolute file name of a source file, will it output the fullname.
GDB Command
...........
The GDB equivalent is `info sources'. `gdbtk' has an analogous command
`gdb_listfiles'.
Example
.......
(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)
The `-file-symbol-file' Command
-------------------------------
Synopsis
........
-file-symbol-file FILE
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.
GDB Command
...........
The corresponding GDB command is `symbol-file'.
Example
.......
(gdb)
-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)

File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
27.18 GDB/MI Target Manipulation Commands
=========================================
The `-target-attach' Command
----------------------------
Synopsis
........
-target-attach PID | GID | FILE
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.
GDB Command
...........
The corresponding GDB command is `attach'.
Example
.......
(gdb)
-target-attach 34
=thread-created,id="1"
*stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}
^done
(gdb)
The `-target-detach' Command
----------------------------
Synopsis
........
-target-detach [ PID | GID ]
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.
GDB Command
...........
The corresponding GDB command is `detach'.
Example
.......
(gdb)
-target-detach
^done
(gdb)
The `-target-disconnect' Command
--------------------------------
Synopsis
........
-target-disconnect
Disconnect from the remote target. There's no output and the target
is generally not resumed.
GDB Command
...........
The corresponding GDB command is `disconnect'.
Example
.......
(gdb)
-target-disconnect
^done
(gdb)
The `-target-download' Command
------------------------------
Synopsis
........
-target-download
Loads the executable onto the remote target. It prints out an
update message every half second, which includes the fields:
`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.
Each message is sent as status record (*note GDB/MI Output Syntax:
GDB/MI Output Syntax.).
In addition, it prints the name and size of the sections, as they are
downloaded. These messages include the following fields:
`section'
The name of the section.
`section-size'
The size of the section.
`total-size'
The size of the overall executable to download.
At the end, a summary is printed.
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
...........
No equivalent.
Example
.......
N.A.
The `-target-select' Command
----------------------------
Synopsis
........
-target-select TYPE PARAMETERS ...
Connect GDB to the remote target. This command takes two args:
`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 output is a connection notification, followed by the address at
which the target program is, in the following form:
^connected,addr="ADDRESS",func="FUNCTION NAME",
args=[ARG LIST]
GDB Command
...........
The corresponding GDB command is `target'.
Example
.......
(gdb)
-target-select remote /dev/ttya
^connected,addr="0xfe00a300",func="??",args=[]
(gdb)

File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
27.19 GDB/MI File Transfer Commands
===================================
The `-target-file-put' Command
------------------------------
Synopsis
........
-target-file-put HOSTFILE TARGETFILE
Copy file HOSTFILE from the host system (the machine running GDB) to
TARGETFILE on the target system.
GDB Command
...........
The corresponding GDB command is `remote put'.
Example
.......
(gdb)
-target-file-put localfile remotefile
^done
(gdb)
The `-target-file-get' Command
------------------------------
Synopsis
........
-target-file-get TARGETFILE HOSTFILE
Copy file TARGETFILE from the target system to HOSTFILE on the host
system.
GDB Command
...........
The corresponding GDB command is `remote get'.
Example
.......
(gdb)
-target-file-get remotefile localfile
^done
(gdb)
The `-target-file-delete' Command
---------------------------------
Synopsis
........
-target-file-delete TARGETFILE
Delete TARGETFILE from the target system.
GDB Command
...........
The corresponding GDB command is `remote delete'.
Example
.......
(gdb)
-target-file-delete remotefile
^done
(gdb)

File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
27.20 Miscellaneous GDB/MI Commands
===================================
The `-gdb-exit' Command
-----------------------
Synopsis
........
-gdb-exit
Exit GDB immediately.
GDB Command
...........
Approximately corresponds to `quit'.
Example
.......
(gdb)
-gdb-exit
^exit
The `-gdb-set' Command
----------------------
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-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 presence of the `-var-set-frozen' command, as well as
possible presense of the `frozen' field in the output of
`-varobj-create'.
`pending-breakpoints'
Indicates presence of the `-f' option to the `-break-insert'
command.
`python'
Indicates presence of 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 presence of the `-thread-info' command.
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-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.
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 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.
`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 `-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,
`thread-group', whose value is the identifier of the thread group
corresponding to the new inferior.
Example
-------
gdb
-add-inferior
^done,thread-group="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]
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'.
GDB Command
-----------
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",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)

File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
28 GDB Annotations
******************
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:
* 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.

File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
28.1 What is an Annotation?
===========================
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.

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::).

File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
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.

File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
28.4 Errors
===========
^Z^Zquit
This annotation occurs right before GDB responds to an interrupt.
^Z^Zerror
This annotation occurs right before GDB responds to an error.
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.
A quit or error annotation may be preceded by
^Z^Zerror-begin
Any output between that and the quit or error annotation is the error
message.
Warning messages are not yet annotated.

File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
28.5 Invalidation Notices
=========================
The following annotations say that certain pieces of state may have
changed.
`^Z^Zframes-invalid'
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.

File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
28.6 Running the Program
========================
When the program starts executing due to a GDB command such as `step'
or `continue',
^Z^Zstarting
is output. When the program stops,
^Z^Zstopped
is output. Before the `stopped' annotation, a variety of
annotations describe how the program stopped.
`^Z^Zexited EXIT-STATUS'
The program exited, and EXIT-STATUS is the exit status (zero for
successful exit, otherwise nonzero).
`^Z^Zsignalled'
The program exited with a signal. After the `^Z^Zsignalled', the
annotation continues:
INTRO-TEXT
^Z^Zsignal-name
NAME
^Z^Zsignal-name-end
MIDDLE-TEXT
^Z^Zsignal-string
STRING
^Z^Zsignal-string-end
END-TEXT
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'. INTRO-TEXT,
MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
particular format.
`^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.
`^Z^Zbreakpoint NUMBER'
The program hit breakpoint number NUMBER.
`^Z^Zwatchpoint NUMBER'
The program hit watchpoint number NUMBER.

File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
28.7 Displaying Source
======================
The following annotation is used instead of displaying source code:
^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
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. ADDR is
in the form `0x' followed by one or more lowercase hex digits (note
that this does not depend on the language).

File: gdb.info, Node: JIT Interface, Next: GDB Bugs, 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

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.

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.
* 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.

File: gdb.info, Node: Unregistering Code, 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.

File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top
30 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

File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
30.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.

File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
30.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.
* 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.

File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
31 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.

File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
31.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.

File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
31.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.

File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
31.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.)

File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
31.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.

File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
31.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'.

File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
31.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.

File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
31.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.

File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
31.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'.
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.

File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
31.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-ignore-case'
If set to `on', Readline performs filename matching and
completion in a case-insensitive fashion. The default value
is `off'.
`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'.
`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'.
`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 point at
the same location on each history line retrieved with
`previous-history' or `next-history'. The default is `off'.
`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, unless the leading `.' is
supplied by the user in the filename to be completed. This
variable is `on' by default.
`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'.
`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'.
`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. 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\\": "\\"

File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
31.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

File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
31.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

File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
31.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".

File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
31.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.

File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
31.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 an argument, behave exactly like
`yank-nth-arg'. Successive calls to `yank-last-arg' move back
through the history list, inserting the last argument of each line
in turn. The history expansion facilities are used to extract the
last argument, as if the `!$' history expansion had been specified.

File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
31.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.

File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
31.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'.

File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
31.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.

File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
31.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.
`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.
`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.

File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
31.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.

File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
31.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.
`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.

File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
31.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 1003.2
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.

File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top
32 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 other programs, see the
GNU Readline Library Manual.
* Menu:
* History Interaction:: What it feels like using History as a user.

File: gdb.info, Node: History Interaction, Up: Using History Interactively
32.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.

File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
32.1.1 Event Designators
------------------------
An event designator is a reference to a command line entry 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 starting with STRING.
`!?STRING[?]'
Refer to the most recent command 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.

File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
32.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.

File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
32.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.

File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top
Appendix A 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.2/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.2', in the case of version 7.2), 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.2/gdb') and type:
make gdb.dvi
Then give `gdb.dvi' to your DVI printing program.
---------- Footnotes ----------
(1) In `gdb-7.2/gdb/refcard.ps' of the version 7.2 release.

File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
Appendix B 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

File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
B.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::)
* MS-Windows shared libraries (*note Shared Libraries::)
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'.
On systems with `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'.

File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
B.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.2 distribution is in the `gdb-7.2'
directory. That directory contains:
`gdb-7.2/configure (and supporting files)'
script for configuring GDB and all its supporting libraries
`gdb-7.2/gdb'
the source specific to GDB itself
`gdb-7.2/bfd'
source for the Binary File Descriptor library
`gdb-7.2/include'
GNU include files
`gdb-7.2/libiberty'
source for the `-liberty' free software library
`gdb-7.2/opcodes'
source for the library of opcode tables and disassemblers
`gdb-7.2/readline'
source for the GNU command-line interface
`gdb-7.2/glob'
source for the GNU filename pattern-matching subroutine
`gdb-7.2/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.2' 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.2
./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.2'
source directory for version 7.2, `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.

File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
B.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.2, you can build GDB in a separate
directory for a Sun 4 like this:
cd gdb-7.2
mkdir ../gdb-sun4
cd ../gdb-sun4
../gdb-7.2/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.2/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.2' (or in a separate configured directory configured with
`--srcdir=DIRNAME/gdb-7.2'), 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.

File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
B.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.2', for version 7.2).

File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
B.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.

File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
B.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.

File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
Appendix C 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 EXPRESSION'
`maint agent-eval 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.
`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.
`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-symtabs'
Check the consistency of psymtabs and symtabs.
`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 demangle NAME'
Demangle a C++ or Objective-C mangled NAME.
`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]'
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.
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'
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.
`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