| This is gdb.info, produced by makeinfo version 4.8 from |
| ../.././gdb/doc/gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Ninth Edition, of `Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB Version 6.6. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, |
| 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 |
| 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.1 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 Free Software Foundation's Back-Cover Text is: "You have |
| freedom to copy and modify this GNU Manual, like GNU software. Copies |
| published by the Free Software Foundation raise funds for GNU |
| development." |
| |
| |
| File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI |
| |
| 24.7 GDB/MI Breakpoint Commands |
| =============================== |
| |
| This section documents GDB/MI commands for manipulating breakpoints. |
| |
| The `-break-after' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-after NUMBER COUNT |
| |
| The breakpoint number NUMBER is not in effect until it has been hit |
| COUNT times. To see how this is reflected in the output of the |
| `-break-list' command, see the description of the `-break-list' command |
| below. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `ignore'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x000100d0",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",times="0"} |
| (gdb) |
| -break-after 1 3 |
| ~ |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0",ignore="3"}]} |
| (gdb) |
| |
| The `-break-condition' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-condition NUMBER EXPR |
| |
| Breakpoint NUMBER will stop the program only if the condition in |
| EXPR is true. The condition becomes part of the `-break-list' output |
| (see the description of the `-break-list' command below). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `condition'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-condition 1 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",cond="1",times="0",ignore="3"}]} |
| (gdb) |
| |
| The `-break-delete' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-delete ( BREAKPOINT )+ |
| |
| Delete the breakpoint(s) whose number(s) are specified in the |
| argument list. This is obviously reflected in the breakpoint list. |
| |
| GDB command |
| ........... |
| |
| The corresponding GDB command is `delete'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-delete 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The `-break-disable' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-disable ( BREAKPOINT )+ |
| |
| Disable the named BREAKPOINT(s). The field `enabled' in the break |
| list is now set to `n' for the named BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `disable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-disable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0"}]} |
| (gdb) |
| |
| The `-break-enable' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-enable ( BREAKPOINT )+ |
| |
| Enable (previously disabled) BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `enable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-enable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0"}]} |
| (gdb) |
| |
| The `-break-info' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-info BREAKPOINT |
| |
| Get information about a single breakpoint. |
| |
| GDB command |
| ........... |
| |
| The corresponding GDB command is `info break BREAKPOINT'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-break-insert' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-insert [ -t ] [ -h ] [ -r ] |
| [ -c CONDITION ] [ -i IGNORE-COUNT ] |
| [ -p THREAD ] [ LINE | ADDR ] |
| |
| If specified, LINE, can be one of: |
| |
| * function |
| |
| * filename:linenum |
| |
| * filename:function |
| |
| * *address |
| |
| The possible optional parameters of this command are: |
| |
| `-t' |
| Insert a temporary breakpoint. |
| |
| `-h' |
| Insert a hardware breakpoint. |
| |
| `-c CONDITION' |
| Make the breakpoint conditional on CONDITION. |
| |
| `-i IGNORE-COUNT' |
| Initialize the IGNORE-COUNT. |
| |
| `-r' |
| Insert a regular breakpoint in all the functions whose names match |
| the given regular expression. Other flags are not applicable to |
| regular expresson. |
| |
| Result |
| ...... |
| |
| The result is in the form: |
| |
| ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", |
| enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", |
| fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] |
| times="TIMES"} |
| |
| where NUMBER is the GDB number for this breakpoint, FUNCNAME is the |
| name of the function where the breakpoint was inserted, FILENAME is the |
| name of the source file which contains this function, LINENO is the |
| source line number within that file and TIMES the number of times that |
| the breakpoint has been hit (always 0 for -break-insert but may be |
| greater for -break-info or -break-list which use the same output). |
| |
| Note: this format is open to change. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `break', `tbreak', `hbreak', |
| `thbreak', and `rbreak'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="4",times="0"} |
| (gdb) |
| -break-insert -t foo |
| ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="11",times="0"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x0001072c", func="main",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,"line="4",times="0"}, |
| bkpt={number="2",type="breakpoint",disp="del",enabled="y", |
| addr="0x00010774",func="foo",file="recursive2.c", |
| fullname="/home/foo/recursive2.c",line="11",times="0"}]} |
| (gdb) |
| -break-insert -r foo.* |
| ~int foo(int, int); |
| ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, |
| "fullname="/home/foo/recursive2.c",line="11",times="0"} |
| (gdb) |
| |
| The `-break-list' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-list |
| |
| Displays the list of inserted breakpoints, showing the following |
| fields: |
| |
| `Number' |
| number of the breakpoint |
| |
| `Type' |
| type of the breakpoint: `breakpoint' or `watchpoint' |
| |
| `Disposition' |
| should the breakpoint be deleted or disabled when it is hit: `keep' |
| or `nokeep' |
| |
| `Enabled' |
| is the breakpoint enabled or no: `y' or `n' |
| |
| `Address' |
| memory location at which the breakpoint is set |
| |
| `What' |
| logical location of the breakpoint, expressed by function name, |
| file name, line number |
| |
| `Times' |
| number of times the breakpoint has been hit |
| |
| If there are no breakpoints or watchpoints, the `BreakpointTable' |
| `body' field is an empty list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info break'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, |
| bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", |
| line="13",times="0"}]} |
| (gdb) |
| |
| Here's an example of the result when there are no breakpoints: |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The `-break-watch' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-watch [ -a | -r ] |
| |
| Create a watchpoint. With the `-a' option it will create an |
| "access" watchpoint, i.e. a watchpoint that triggers either on a read |
| from or on a write to the memory location. With the `-r' option, the |
| watchpoint created is a "read" watchpoint, i.e. it will trigger only |
| when the memory location is accessed for reading. Without either of |
| the options, the watchpoint created is a regular watchpoint, i.e. it |
| will trigger when the memory location is accessed for writing. *Note |
| Setting watchpoints: Set Watchpoints. |
| |
| Note that `-break-list' will report a single list of watchpoints and |
| breakpoints inserted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `watch', `awatch', and `rwatch'. |
| |
| Example |
| ....... |
| |
| Setting a watchpoint on a variable in the `main' function: |
| |
| (gdb) |
| -break-watch x |
| ^done,wpt={number="2",exp="x"} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-trigger",wpt={number="2",exp="x"}, |
| value={old="-268439212",new="55"}, |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="5"} |
| (gdb) |
| |
| Setting a watchpoint on a variable local to a function. GDB will |
| stop the program execution twice: first for the variable changing |
| value, then for the watchpoint going out of scope. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="5",exp="C"} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-trigger", |
| wpt={number="5",exp="C"},value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-scope",wpnum="5", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| |
| Listing breakpoints and watchpoints, at different points in the |
| program execution. Note that once the watchpoint goes out of scope, it |
| is deleted. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="2",exp="C"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",times="0"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-trigger",wpt={number="2",exp="C"}, |
| value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",times="-5"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-scope",wpnum="2", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", |
| times="1"}]} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI |
| |
| 24.8 GDB/MI Program Context |
| ============================ |
| |
| The `-exec-arguments' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-arguments ARGS |
| |
| Set the inferior program arguments, to be used in the next |
| `-exec-run'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `set args'. |
| |
| Example |
| ....... |
| |
| Don't have one around. |
| |
| The `-exec-show-arguments' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-show-arguments |
| |
| Print the arguments of the program. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `show args'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-environment-cd' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-cd PATHDIR |
| |
| Set GDB's working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `cd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done |
| (gdb) |
| |
| The `-environment-directory' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-directory [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for source files. |
| If the `-r' option is used, the search path is reset to the default |
| search path. If directories PATHDIR are supplied in addition to the |
| `-r' option, the search path is first reset and then addition occurs as |
| normal. Multiple directories may be specified, separated by blanks. |
| Specifying multiple directories in a single command results in the |
| directories added to the beginning of the search path in the same order |
| they were presented in the command. If blanks are needed as part of a |
| directory name, double-quotes should be used around the name. In the |
| command output, the path will show up separated by the system |
| directory-separator character. The directory-seperator character must |
| not be used in any directory name. If no directories are specified, |
| the current search path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `dir'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory "" |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r /home/jjohnstn/src/gdb /usr/src |
| ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r |
| ^done,source-path="$cdir:$cwd" |
| (gdb) |
| |
| The `-environment-path' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-path [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for object files. |
| If the `-r' option is used, the search path is reset to the original |
| search path that existed at gdb start-up. If directories PATHDIR are |
| supplied in addition to the `-r' option, the search path is first reset |
| and then addition occurs as normal. Multiple directories may be |
| specified, separated by blanks. Specifying multiple directories in a |
| single command results in the directories added to the beginning of the |
| search path in the same order they were presented in the command. If |
| blanks are needed as part of a directory name, double-quotes should be |
| used around the name. In the command output, the path will show up |
| separated by the system directory-separator character. The |
| directory-seperator character must not be used in any directory name. |
| If no directories are specified, the current path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `path'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-path |
| ^done,path="/usr/bin" |
| (gdb) |
| -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin |
| ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" |
| (gdb) |
| -environment-path -r /usr/local/bin |
| ^done,path="/usr/local/bin:/usr/bin" |
| (gdb) |
| |
| The `-environment-pwd' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-pwd |
| |
| Show the current working directory. |
| |
| GDB command |
| ........... |
| |
| The corresponding GDB command is `pwd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-pwd |
| ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI |
| |
| 24.9 GDB/MI Thread Commands |
| =========================== |
| |
| The `-thread-info' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-info |
| |
| GDB command |
| ........... |
| |
| No equivalent. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-thread-list-all-threads' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-list-all-threads |
| |
| GDB Command |
| ........... |
| |
| The equivalent GDB command is `info threads'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-thread-list-ids' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -thread-list-ids |
| |
| Produces a list of the currently known GDB thread ids. At the end |
| of the list it also prints the total number of such threads. |
| |
| GDB Command |
| ........... |
| |
| Part of `info threads' supplies the same information. |
| |
| Example |
| ....... |
| |
| No threads present, besides the main process: |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={},number-of-threads="0" |
| (gdb) |
| |
| Several threads: |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| number-of-threads="3" |
| (gdb) |
| |
| The `-thread-select' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-select THREADNUM |
| |
| Make THREADNUM the current thread. It prints the number of the new |
| current thread, and the topmost frame for that thread. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `thread'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",thread-id="2",line="187", |
| file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" |
| (gdb) |
| -thread-list-ids |
| ^done, |
| thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| number-of-threads="3" |
| (gdb) |
| -thread-select 3 |
| ^done,new-thread-id="3", |
| frame={level="0",func="vprintf", |
| args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, |
| {name="arg",value="0x2"}],file="vprintf.c",line="31"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI |
| |
| 24.10 GDB/MI Program Execution |
| ============================== |
| |
| These are the asynchronous commands which generate the out-of-band |
| record `*stopped'. Currently GDB only really executes asynchronously |
| with remote targets and this interaction is mimicked in other cases. |
| |
| The `-exec-continue' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-continue |
| |
| Resumes the execution of the inferior program until a breakpoint is |
| encountered, or until the inferior exits. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB corresponding is `continue'. |
| |
| Example |
| ....... |
| |
| -exec-continue |
| ^running |
| (gdb) |
| @Hello world |
| *stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[], |
| file="hello.c",fullname="/home/foo/bar/hello.c",line="13"} |
| (gdb) |
| |
| The `-exec-finish' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-finish |
| |
| Resumes the execution of the inferior program until the current |
| function is exited. Displays the results returned by the function. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `finish'. |
| |
| Example |
| ....... |
| |
| Function returning `void'. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| @hello from foo |
| *stopped,reason="function-finished",frame={func="main",args=[], |
| file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} |
| (gdb) |
| |
| Function returning other than `void'. The name of the internal GDB |
| variable storing the result is printed, together with the value itself. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", |
| args=[{name="a",value="1"],{name="b",value="9"}}, |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| gdb-result-var="$1",return-value="0" |
| (gdb) |
| |
| The `-exec-interrupt' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-interrupt |
| |
| Interrupts the background execution of the target. Note how the |
| token associated with the stop message is the one for the execution |
| command that has been interrupted. The token for the interrupt itself |
| only appears in the `^done' output. If the user is trying to interrupt |
| a non-running program, an error message will be printed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `interrupt'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 111-exec-continue |
| 111^running |
| |
| (gdb) |
| 222-exec-interrupt |
| 222^done |
| (gdb) |
| 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", |
| frame={addr="0x00010140",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="13"} |
| (gdb) |
| |
| (gdb) |
| -exec-interrupt |
| ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." |
| (gdb) |
| |
| The `-exec-next' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `next'. |
| |
| Example |
| ....... |
| |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="8",file="hello.c" |
| (gdb) |
| |
| The `-exec-next-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next-instruction |
| |
| Executes one machine instruction. If the instruction is a function |
| call, continues until the function returns. If the program stops at an |
| instruction in the middle of a source line, the address will be printed |
| as well. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `nexti'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| addr="0x000100d4",line="5",file="hello.c" |
| (gdb) |
| |
| The `-exec-return' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-return |
| |
| Makes current function return immediately. Doesn't execute the |
| inferior. Displays the new current frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `return'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 200-break-insert callee4 |
| 200^done,bkpt={number="1",addr="0x00010734", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 000-exec-run |
| 000^running |
| (gdb) |
| 000*stopped,reason="breakpoint-hit",bkptno="1", |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 205-break-delete |
| 205^done |
| (gdb) |
| 111-exec-return |
| 111^done,frame={level="0",func="callee3", |
| args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| |
| The `-exec-run' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-run |
| |
| Starts execution of the inferior from the beginning. The inferior |
| executes until either a breakpoint is encountered or the program exits. |
| In the latter case the output will include an exit code, if the |
| program has exited exceptionally. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `run'. |
| |
| Examples |
| ........ |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",bkptno="1", |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="4"} |
| (gdb) |
| |
| Program exited normally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited-normally" |
| (gdb) |
| |
| Program exited exceptionally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited",exit-code="01" |
| (gdb) |
| |
| Another way the program can terminate is if it receives a signal |
| such as `SIGINT'. In this case, GDB/MI displays this: |
| |
| (gdb) |
| *stopped,reason="exited-signalled",signal-name="SIGINT", |
| signal-meaning="Interrupt" |
| |
| The `-exec-step' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached, if the next source line |
| is not a function call. If it is, stop at the first instruction of the |
| called function. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `step'. |
| |
| Example |
| ....... |
| |
| Stepping into a function: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[{name="a",value="10"}, |
| {name="b",value="0"}],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="11"} |
| (gdb) |
| |
| Regular stepping: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="14",file="recursive2.c" |
| (gdb) |
| |
| The `-exec-step-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step-instruction |
| |
| Resumes the inferior which executes one machine instruction. The |
| output, once GDB has stopped, will vary depending on whether we have |
| stopped in the middle of a source line or not. In the former case, the |
| address at which the program stopped will be printed as well. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `stepi'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10"} |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={addr="0x000100f4",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10"} |
| (gdb) |
| |
| The `-exec-until' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-until [ LOCATION ] |
| |
| Executes the inferior until the LOCATION specified in the argument |
| is reached. If there is no argument, the inferior executes until a |
| source line greater than the current one is reached. The reason for |
| stopping in this case will be `location-reached'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `until'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-until recursive2.c:6 |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="location-reached",frame={func="main",args=[], |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI |
| |
| 24.11 GDB/MI Stack Manipulation Commands |
| ======================================== |
| |
| The `-stack-info-frame' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-frame |
| |
| Get info on the selected frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info frame' or `frame' (without |
| arguments). |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-info-frame |
| ^done,frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} |
| (gdb) |
| |
| The `-stack-info-depth' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-depth [ MAX-DEPTH ] |
| |
| Return the depth of the stack. If the integer argument MAX-DEPTH is |
| specified, do not count beyond MAX-DEPTH frames. |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. |
| |
| Example |
| ....... |
| |
| For a stack with frame levels 0 through 11: |
| |
| (gdb) |
| -stack-info-depth |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 4 |
| ^done,depth="4" |
| (gdb) |
| -stack-info-depth 12 |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 11 |
| ^done,depth="11" |
| (gdb) |
| -stack-info-depth 13 |
| ^done,depth="12" |
| (gdb) |
| |
| The `-stack-list-arguments' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-arguments SHOW-VALUES |
| [ LOW-FRAME HIGH-FRAME ] |
| |
| Display a list of the arguments for the frames between LOW-FRAME and |
| HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, |
| list the arguments for the whole call stack. If the two arguments are |
| equal, show the single frame at the corresponding level. It is an |
| error if LOW-FRAME is larger than the actual number of frames. On the |
| other hand, HIGH-FRAME may be larger than the actual number of frames, |
| in which case only existing frames will be returned. |
| |
| The SHOW-VALUES argument must have a value of 0 or 1. A value of 0 |
| means that only the names of the arguments are listed, a value of 1 |
| means that both names and values of the arguments are printed. |
| |
| GDB Command |
| ........... |
| |
| GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' |
| command which partially overlaps with the functionality of |
| `-stack-list-arguments'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-frames |
| ^done, |
| stack=[ |
| frame={level="0",addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, |
| frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, |
| frame={level="2",addr="0x0001078c",func="callee2", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, |
| frame={level="3",addr="0x000107b4",func="callee1", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, |
| frame={level="4",addr="0x000107e0",func="main", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] |
| (gdb) |
| -stack-list-arguments 0 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1",args=[name="strarg"]}, |
| frame={level="2",args=[name="intarg",name="strarg"]}, |
| frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 1 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1", |
| args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, |
| frame={level="2",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}, |
| {frame={level="3",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}, |
| {name="fltarg",value="3.5"}]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 0 2 2 |
| ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] |
| (gdb) |
| -stack-list-arguments 1 2 2 |
| ^done,stack-args=[frame={level="2", |
| args=[{name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}] |
| (gdb) |
| |
| The `-stack-list-frames' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-frames [ LOW-FRAME HIGH-FRAME ] |
| |
| List the frames currently on the stack. For each frame it displays |
| the following info: |
| |
| `LEVEL' |
| The frame number, 0 being the topmost frame, i.e. the innermost |
| function. |
| |
| `ADDR' |
| The `$pc' value for that frame. |
| |
| `FUNC' |
| Function name. |
| |
| `FILE' |
| File name of the source file where the function lives. |
| |
| `LINE' |
| Line number corresponding to the `$pc'. |
| |
| If invoked without arguments, this command prints a backtrace for the |
| whole stack. If given two integer arguments, it shows the frames whose |
| levels are between the two arguments (inclusive). If the two arguments |
| are equal, it shows the single frame at the corresponding level. It is |
| an error if LOW-FRAME is larger than the actual number of frames. On |
| the other hand, HIGH-FRAME may be larger than the actual number of |
| frames, in which case only existing frames will be returned. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `backtrace' and `where'. |
| |
| Example |
| ....... |
| |
| Full stack backtrace: |
| |
| (gdb) |
| -stack-list-frames |
| ^done,stack= |
| [frame={level="0",addr="0x0001076c",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, |
| frame={level="1",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="2",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="6",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="7",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="8",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="9",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="10",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="11",addr="0x00010738",func="main", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] |
| (gdb) |
| |
| Show frames between LOW_FRAME and HIGH_FRAME: |
| |
| (gdb) |
| -stack-list-frames 3 5 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] |
| (gdb) |
| |
| Show a single frame: |
| |
| (gdb) |
| -stack-list-frames 3 3 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] |
| (gdb) |
| |
| The `-stack-list-locals' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-locals PRINT-VALUES |
| |
| Display the local variable names for the selected frame. If |
| PRINT-VALUES is 0 or `--no-values', print only the names of the |
| variables; if it is 1 or `--all-values', print also their values; and |
| if it is 2 or `--simple-values', print the name, type and value for |
| simple data types and the name and type for arrays, structures and |
| unions. In this last case, a frontend can immediately display the |
| value of simple data types and create variable objects for other data |
| types when the the user wishes to explore their values in more detail. |
| |
| GDB Command |
| ........... |
| |
| `info locals' in GDB, `gdb_get_locals' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-locals 0 |
| ^done,locals=[name="A",name="B",name="C"] |
| (gdb) |
| -stack-list-locals --all-values |
| ^done,locals=[{name="A",value="1"},{name="B",value="2"}, |
| {name="C",value="{1, 2, 3}"}] |
| -stack-list-locals --simple-values |
| ^done,locals=[{name="A",type="int",value="1"}, |
| {name="B",type="int",value="2"},{name="C",type="int [3]"}] |
| (gdb) |
| |
| The `-stack-select-frame' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-select-frame FRAMENUM |
| |
| Change the selected frame. Select a different frame FRAMENUM on the |
| stack. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `frame', `up', `down', |
| `select-frame', `up-silent', and `down-silent'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-select-frame 2 |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI |
| |
| 24.12 GDB/MI Variable Objects |
| ============================= |
| |
| Motivation for Variable Objects in GDB/MI |
| ----------------------------------------- |
| |
| For the implementation of a variable debugger window (locals, watched |
| expressions, etc.), we are proposing the adaptation of the existing code |
| used by `Insight'. |
| |
| The two main reasons for that are: |
| |
| 1. It has been proven in practice (it is already on its second |
| generation). |
| |
| 2. It will shorten development time (needless to say how important it |
| is now). |
| |
| The original interface was designed to be used by Tcl code, so it was |
| slightly changed so it could be used through GDB/MI. This section |
| describes the GDB/MI operations that will be available and gives some |
| hints about their use. |
| |
| _Note_: In addition to the set of operations described here, we |
| expect the GUI implementation of a variable window to require, at |
| least, the following operations: |
| |
| * `-gdb-show' `output-radix' |
| |
| * `-stack-list-arguments' |
| |
| * `-stack-list-locals' |
| |
| * `-stack-select-frame' |
| |
| Introduction to Variable Objects in GDB/MI |
| ------------------------------------------ |
| |
| The basic idea behind variable objects is the creation of a named object |
| to represent a variable, an expression, a memory location or even a CPU |
| register. For each object created, a set of operations is available for |
| examining or changing its properties. |
| |
| Furthermore, complex data types, such as C structures, are |
| represented in a tree format. For instance, the `struct' type variable |
| is the root and the children will represent the struct members. If a |
| child is itself of a complex type, it will also have children of its |
| own. Appropriate language differences are handled for C, C++ and Java. |
| |
| When returning the actual values of the objects, this facility allows |
| for the individual selection of the display format used in the result |
| creation. It can be chosen among: binary, decimal, hexadecimal, octal |
| and natural. Natural refers to a default format automatically chosen |
| based on the variable type (like decimal for an `int', hex for |
| pointers, etc.). |
| |
| The following is the complete set of GDB/MI operations defined to |
| access this functionality: |
| |
| *Operation* *Description* |
| `-var-create' create a variable object |
| `-var-delete' delete the variable object and its children |
| `-var-set-format' set the display format of this variable |
| `-var-show-format' show the display format of this variable |
| `-var-info-num-children' tells how many children this object has |
| `-var-list-children' return a list of the object's children |
| `-var-info-type' show the type of this variable object |
| `-var-info-expression' print what this variable object represents |
| `-var-show-attributes' is this variable editable? does it exist |
| here? |
| `-var-evaluate-expression' get the value of this variable |
| `-var-assign' set the value of this variable |
| `-var-update' update the variable and its children |
| |
| In the next subsection we describe each operation in detail and |
| suggest how it can be used. |
| |
| Description And Use of Operations on Variable Objects |
| ----------------------------------------------------- |
| |
| The `-var-create' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-create {NAME | "-"} |
| {FRAME-ADDR | "*"} EXPRESSION |
| |
| This operation creates a variable object, which allows the |
| monitoring of a variable, the result of an expression, a memory cell or |
| a CPU register. |
| |
| The NAME parameter is the string by which the object can be |
| referenced. It must be unique. If `-' is specified, the varobj system |
| will generate a string "varNNNNNN" automatically. It will be unique |
| provided that one does not specify NAME on that format. The command |
| fails if a duplicate name is found. |
| |
| The frame under which the expression should be evaluated can be |
| specified by FRAME-ADDR. A `*' indicates that the current frame should |
| be used. |
| |
| EXPRESSION is any expression valid on the current language set (must |
| not begin with a `*'), or one of the following: |
| |
| * `*ADDR', where ADDR is the address of a memory cell |
| |
| * `*ADDR-ADDR' -- a memory address range (TBD) |
| |
| * `$REGNAME' -- a CPU register name |
| |
| Result |
| ...... |
| |
| This operation returns the name, number of children and the type of the |
| object created. Type is returned as a string as the ones generated by |
| the GDB CLI: |
| |
| name="NAME",numchild="N",type="TYPE" |
| |
| The `-var-delete' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-delete NAME |
| |
| Deletes a previously created variable object and all of its children. |
| |
| Returns an error if the object NAME is not found. |
| |
| The `-var-set-format' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-format NAME FORMAT-SPEC |
| |
| Sets the output format for the value of the object NAME to be |
| FORMAT-SPEC. |
| |
| The syntax for the FORMAT-SPEC is as follows: |
| |
| FORMAT-SPEC ==> |
| {binary | decimal | hexadecimal | octal | natural} |
| |
| The `-var-show-format' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-show-format NAME |
| |
| Returns the format used to display the value of the object NAME. |
| |
| FORMAT ==> |
| FORMAT-SPEC |
| |
| The `-var-info-num-children' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-info-num-children NAME |
| |
| Returns the number of children of a variable object NAME: |
| |
| numchild=N |
| |
| The `-var-list-children' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-list-children [PRINT-VALUES] NAME |
| |
| Return a list of the children of the specified variable object and |
| create variable objects for them, if they do not already exist. With a |
| single argument or if PRINT-VALUES has a value for of 0 or |
| `--no-values', print only the names of the variables; if PRINT-VALUES |
| is 1 or `--all-values', also print their values; and if it is 2 or |
| `--simple-values' print the name and value for simple data types and |
| just the name for arrays, structures and unions. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-list-children n |
| ^done,numchild=N,children=[{name=NAME, |
| numchild=N,type=TYPE},(repeats N times)] |
| (gdb) |
| -var-list-children --all-values n |
| ^done,numchild=N,children=[{name=NAME, |
| numchild=N,value=VALUE,type=TYPE},(repeats N times)] |
| |
| The `-var-info-type' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-type NAME |
| |
| Returns the type of the specified variable NAME. The type is |
| returned as a string in the same format as it is output by the GDB CLI: |
| |
| type=TYPENAME |
| |
| The `-var-info-expression' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-expression NAME |
| |
| Returns what is represented by the variable object NAME: |
| |
| lang=LANG-SPEC,exp=EXPRESSION |
| |
| where LANG-SPEC is `{"C" | "C++" | "Java"}'. |
| |
| The `-var-show-attributes' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-show-attributes NAME |
| |
| List attributes of the specified variable object NAME: |
| |
| status=ATTR [ ( ,ATTR )* ] |
| |
| where ATTR is `{ { editable | noneditable } | TBD }'. |
| |
| The `-var-evaluate-expression' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-evaluate-expression NAME |
| |
| Evaluates the expression that is represented by the specified |
| variable object and returns its value as a string in the current format |
| specified for the object: |
| |
| value=VALUE |
| |
| Note that one must invoke `-var-list-children' for a variable before |
| the value of a child variable can be evaluated. |
| |
| The `-var-assign' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-assign NAME EXPRESSION |
| |
| Assigns the value of EXPRESSION to the variable object specified by |
| NAME. The object must be `editable'. If the variable's value is |
| altered by the assign, the variable will show up in any subsequent |
| `-var-update' list. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update * |
| ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] |
| (gdb) |
| |
| The `-var-update' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-update [PRINT-VALUES] {NAME | "*"} |
| |
| Update the value of the variable object NAME by evaluating its |
| expression after fetching all the new values from memory or registers. |
| A `*' causes all existing variable objects to be updated. The option |
| PRINT-VALUES determines whether names both and values, or just names |
| are printed in the manner described for `-var-list-children' (*note |
| -var-list-children::). |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update --all-values var1 |
| ^done,changelist=[{name="var1",value="3",in_scope="true", |
| type_changed="false"}] |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI |
| |
| 24.13 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 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 directely 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",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 |
| |
| 24.14 GDB/MI Tracepoint Commands |
| ================================ |
| |
| The tracepoint commands are not yet implemented. |
| |
| |
| File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI |
| |
| 24.15 GDB/MI Symbol Query Commands |
| ================================== |
| |
| The `-symbol-info-address' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-address SYMBOL |
| |
| Describe where SYMBOL is stored. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info address'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-file' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-file |
| |
| Show the file for the symbol. |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. `gdbtk' has `gdb_find_file'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-function' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-function |
| |
| Show which function the symbol lives in. |
| |
| GDB Command |
| ........... |
| |
| `gdb_get_function' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-line' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-line |
| |
| Show the core addresses of the code for a source line. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info line'. `gdbtk' has the |
| `gdb_get_line' and `gdb_get_file' commands. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-symbol' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-symbol ADDR |
| |
| Describe what symbol is at location ADDR. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info symbol'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-list-functions' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-functions |
| |
| List the functions in the executable. |
| |
| GDB Command |
| ........... |
| |
| `info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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) |
| |
| The `-symbol-list-types' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-types |
| |
| List all the type names. |
| |
| GDB Command |
| ........... |
| |
| The corresponding commands are `info types' in GDB, `gdb_search' in |
| `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-list-variables' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-variables |
| |
| List all the global and static variable names. |
| |
| GDB Command |
| ........... |
| |
| `info variables' in GDB, `gdb_search' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-locate' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-locate |
| |
| GDB Command |
| ........... |
| |
| `gdb_loc' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-type' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-type VARIABLE |
| |
| Show type of VARIABLE. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `ptype', `gdbtk' has |
| `gdb_obj_variable'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| |
| File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI |
| |
| 24.16 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-sections' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-exec-sections |
| |
| List the sections of the current executable file. |
| |
| GDB Command |
| ........... |
| |
| The GDB command `info file' shows, among the rest, the same information |
| as this command. `gdbtk' has a corresponding command `gdb_load_info'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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. |
| |
| 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" |
| (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-list-shared-libraries' Command |
| ----------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-shared-libraries |
| |
| List the shared libraries in the program. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info shared'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-file-list-symbol-files' Command |
| ------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-symbol-files |
| |
| List symbol files. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info file' (part of it). |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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 Miscellaneous Commands, Prev: GDB/MI File Commands, Up: GDB/MI |
| |
| 24.17 GDB/MI Target Manipulation Commands |
| ========================================= |
| |
| The `-target-attach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-attach PID | FILE |
| |
| Attach to a process PID or a file FILE outside of GDB. |
| |
| GDB command |
| ........... |
| |
| The corresponding GDB command is `attach'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-compare-sections' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-compare-sections [ SECTION ] |
| |
| Compare data of section SECTION on target to the exec file. Without |
| the argument, all sections are compared. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is `compare-sections'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-detach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-detach |
| |
| Detach from the remote target which normally resumes its execution. |
| 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) |
| |
| The `-target-exec-status' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-exec-status |
| |
| Provide information on the state of the target (whether it is |
| running or not, for instance). |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-list-available-targets' Command |
| -------------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-list-available-targets |
| |
| List the possible targets to connect to. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `help target'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-list-current-targets' Command |
| ------------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-list-current-targets |
| |
| Describe the current target. |
| |
| GDB Command |
| ........... |
| |
| The corresponding information is printed by `info file' (among other |
| things). |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-list-parameters' Command |
| ------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-list-parameters |
| |
| 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 `async', `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 async /dev/ttya |
| ^connected,addr="0xfe00a300",func="??",args=[] |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI |
| |
| 24.18 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 `-exec-abort' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-abort |
| |
| Kill the inferior running program. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `kill'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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 `-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) |
| |
| |
| File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top |
| |
| 25 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 superseeded by GDB/MI |
| (*note GDB/MI::). |
| |
| * Menu: |
| |
| * Annotations Overview:: What annotations are; the general syntax. |
| * 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: Prompting, Up: Annotations |
| |
| 25.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 anntations, |
| 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: Prompting, Next: Errors, Prev: Annotations Overview, Up: Annotations |
| |
| 25.2 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 |
| |
| 25.3 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 |
| |
| 25.4 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 |
| |
| 25.5 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 |
| |
| 25.6 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: GDB Bugs, Next: Formatting Documentation, Prev: GDB/MI, Up: Top |
| |
| 26 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 |
| |
| 26.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 |
| |
| 26.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 prefered 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: Formatting Documentation, Up: Top |
| |
| 27 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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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: Installing GDB, Prev: Command Line Editing, Up: Top |
| |
| 28 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 |
| |
| 28.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 |
| |
| 28.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 |
| |
| 28.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 |
| |
| 28.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: Command Line Editing, Prev: GDB Bugs, 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-6.6/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-6.6', in the case of version 6.6), 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 the `gdb' subdirectory of |
| the main source directory (for example, to `gdb-6.6/gdb') and type: |
| |
| make gdb.dvi |
| |
| Then give `gdb.dvi' to your DVI printing program. |
| |
| ---------- Footnotes ---------- |
| |
| (1) In `gdb-6.6/gdb/refcard.ps' of the version 6.6 release. |
| |
| |
| File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Using History Interactively, 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 |
| |
| |
| 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 currently only used to implement some remote-specific |
| features. |
| |
| |
| |
| 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 6.6 distribution is in the `gdb-6.6' |
| directory. That directory contains: |
| |
| `gdb-6.6/configure (and supporting files)' |
| script for configuring GDB and all its supporting libraries |
| |
| `gdb-6.6/gdb' |
| the source specific to GDB itself |
| |
| `gdb-6.6/bfd' |
| source for the Binary File Descriptor library |
| |
| `gdb-6.6/include' |
| GNU include files |
| |
| `gdb-6.6/libiberty' |
| source for the `-liberty' free software library |
| |
| `gdb-6.6/opcodes' |
| source for the library of opcode tables and disassemblers |
| |
| `gdb-6.6/readline' |
| source for the GNU command-line interface |
| |
| `gdb-6.6/glob' |
| source for the GNU filename pattern-matching subroutine |
| |
| `gdb-6.6/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-6.6' 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-6.6 |
| ./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-6.6' |
| source directory for version 6.6, `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 6.6, you can build GDB in a separate |
| directory for a Sun 4 like this: |
| |
| cd gdb-6.6 |
| mkdir ../gdb-sun4 |
| cd ../gdb-sun4 |
| ../gdb-6.6/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-6.6/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-6.6' (or in a separate configured directory configured with |
| `--srcdir=DIRNAME/gdb-6.6'), 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-6.6', for version 6.6). |
| |
| |
| File: gdb.info, Node: Configure Options, 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: 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' |
| Translate the given EXPRESSION into remote agent bytecodes. This |
| command is useful for debugging the Agent Expression mechanism |
| (*note Agent Expressions::). |
| |
| `maint info breakpoints' |
| Using the same format as `info breakpoints', display both the |
| breakpoints you've set explicitly, and those GDB is using for |
| internal purposes. Internal breakpoints are shown with negative |
| breakpoint numbers. The type column identifies what kind of |
| breakpoint is shown: |
| |
| `breakpoint' |
| Normal, explicitly set breakpoint. |
| |
| `watchpoint' |
| Normal, explicitly set watchpoint. |
| |
| `longjmp' |
| Internal breakpoint, used to handle correctly stepping through |
| `longjmp' calls. |
| |
| `longjmp resume' |
| Internal breakpoint at the target of a `longjmp'. |
| |
| `until' |
| Temporary internal breakpoint used by the GDB `until' command. |
| |
| `finish' |
| Temporary internal breakpoint used by the GDB `finish' |
| command. |
| |
| `shlib events' |
| Shared library events. |
| |
| |
| `maint 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 manled 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 `indernal-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 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 dummy-frames' |
| Prints the contents of GDB's internal dummy-frame stack. |
| |
| (gdb) b add |
| ... |
| (gdb) print add(2,3) |
| Breakpoint 2, add (a=2, b=3) at ... |
| 58 return (a + b); |
| The program being debugged stopped while in a function called from GDB. |
| ... |
| (gdb) maint print dummy-frames |
| 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 |
| top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} |
| call_lo=0x01014000 call_hi=0x01014001 |
| (gdb) |
| |
| Takes an optional file parameter. |
| |
| `maint print registers [FILE]' |
| `maint print raw-registers [FILE]' |
| `maint print cooked-registers [FILE]' |
| `maint print register-groups [FILE]' |
| Print GDB's internal register data structures. |
| |
| The command `maint print raw-registers' includes the contents of |
| the raw register cache; the command `maint print cooked-registers' |
| includes the (cooked) value of all registers; and the command |
| `maint print register-groups' includes the groups that each |
| register is a member of. *Note Registers: (gdbint)Registers. |
| |
| These commands take an optional parameter, a file name to which to |
| write the information. |
| |
| `maint print reggroups [FILE]' |
| Print GDB's internal register group data structures. The optional |
| argument FILE tells to what file to write the information. |
| |
| The register groups info looks like this: |
| |
| (gdb) maint print reggroups |
| Group Type |
| general user |
| float user |
| all user |
| vector user |
| system user |
| save internal |
| restore internal |
| |
| `flushregs' |
| This command forces GDB to flush its internal register cache. |
| |
| `maint print objfiles' |
| Print a dump of all known object files. For each object file, this |
| command prints its name, address in memory, and all of its psymtabs |
| and symtabs. |
| |
| `maint print statistics' |
| This command prints, for each object file in the program, various |
| data about that object file followed by the byte cache ("bcache") |
| statistics for the object file. The objfile data includes the |
| number of minimal, partical, full, and stabs symbols, the number |
| of types defined by the objfile, the number of as yet unexpanded |
| psym tables, the number of line tables and string tables, and the |
| amount of memory used by the various tables. The bcache |
| statistics include the counts, sizes, and counts of duplicates of |
| all and unique objects, max, average, and median entry size, total |
| memory used and its overhead and savings, and various measures of |
| the hash table size and chain lengths. |
| |
| `maint print type EXPR' |
| Print the type chain for a type specified by EXPR. The argument |
| can be either a type name or a symbol. If it is a symbol, the |
| type of that symbol is described. The type chain produced by this |
| command is a recursive definition of the data type as stored in |
| GDB's data structures, including its flags and contained types. |
| |
| `maint set dwarf2 max-cache-age' |
| `maint show dwarf2 max-cache-age' |
| Control the DWARF 2 compilation unit cache. |
| |
| In object files with inter-compilation-unit references, such as |
| those produced by the GCC option `-feliminate-dwarf2-dups', the |
| DWARF 2 reader needs to frequently refer to previously read |
| compilation units. This setting controls how long a compilation |
| unit will remain in the cache if it is not referenced. A higher |
| limit means that cached compilation units will be stored in memory |
| longer, and more total memory will be used. Setting it to zero |
| disables caching, which will slow down GDB startup, but reduce |
| memory consumption. |
| |
| `maint set profile' |
| `maint show profile' |
| Control profiling of GDB. |
| |
| Profiling will be disabled until you use the `maint set profile' |
| command to enable it. When you enable profiling, the system will |
| begin collecting timing and execution count data; when you disable |
| profiling or exit GDB, the results will be written to a log file. |
| Remember that if you use profiling, GDB will overwrite the |
| profiling log file (often called `gmon.out'). If you have a |
| record of important profiling data in a `gmon.out' file, be sure |
| to move it to a safe location. |
| |
| Configuring with `--enable-profiling' arranges for GDB to be |
| compiled with the `-pg' compiler option. |
| |
| `maint show-debug-regs' |
| Control whether to show variables that mirror the x86 hardware |
| debug registers. Use `ON' to enable, `OFF' to disable. If |
| enabled, the debug registers values are shown when GDB inserts or |
| removes a hardware breakpoint or watchpoint, and when the inferior |
| triggers a hardware-assisted breakpoint or watchpoint. |
| |
| `maint space' |
| Control whether to display memory usage for each command. If set |
| to a nonzero value, GDB will display how much memory each command |
| took, following the command's own output. This can also be |
| requested by invoking GDB with the `--statistics' command-line |
| switch (*note Mode Options::). |
| |
| `maint time' |
| Control whether to display the execution time for each command. If |
| set to a nonzero value, GDB will display how much time it took to |
| execute each command, following the command's own output. This |
| can also be requested by invoking GDB with the `--statistics' |
| command-line switch (*note Mode Options::). |
| |
| `maint translate-address [SECTION] ADDR' |
| Find the symbol stored at the location specified by the address |
| ADDR and an optional section name SECTION. If found, GDB prints |
| the name of the closest symbol and an offset from the symbol's |
| location to the specified address. This is similar to the `info |
| address' command (*note Symbols::), except that this command also |
| allows to find symbols in other sections. |
| |
| |
| The following command is useful for non-interactive invocations of |
| GDB, such as in the test suite. |
| |
| `set watchdog NSEC' |
| Set the maximum number of seconds GDB will wait for the target |
| operation to finish. If this time expires, GDB reports and error |
| and the command is aborted. |
| |
| `show watchdog' |
| Show the current setting of the target wait timeout. |
| |
| |
| File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top |
| |
| Appendix D GDB Remote Serial Protocol |
| ************************************* |
| |
| * Menu: |
| |
| * Overview:: |
| * Packets:: |
| * Stop Reply Packets:: |
| * General Query Packets:: |
| * Register Packet Format:: |
| * Tracepoint Packets:: |
| * Interrupts:: |
| * Examples:: |
| * File-I/O remote protocol extension:: |
| * Memory map format:: |
| |
| |
| File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol |
| |
| D.1 Overview |
| ============ |
| |
| There may be occasions when you need to know something about the |
| protocol--for example, if there is only one serial port to your target |
| machine, you might want your program to do something special if it |
| recognizes a packet meant for GDB. |
| |
| In the examples below, `->' and `<-' are used to indicate |
| transmitted and received data respectfully. |
| |
| All GDB commands and responses (other than acknowledgments) are sent |
| as a PACKET. A PACKET is introduced with the character `$', the actual |
| PACKET-DATA, and the terminating character `#' followed by a two-digit |
| CHECKSUM: |
| |
| `$'PACKET-DATA`#'CHECKSUM |
| The two-digit CHECKSUM is computed as the modulo 256 sum of all |
| characters between the leading `$' and the trailing `#' (an eight bit |
| unsigned checksum). |
| |
| Implementors should note that prior to GDB 5.0 the protocol |
| specification also included an optional two-digit SEQUENCE-ID: |
| |
| `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM |
| |
| That SEQUENCE-ID was appended to the acknowledgment. GDB has never |
| output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 |
| must not accept SEQUENCE-ID. |
| |
| When either the host or the target machine receives a packet, the |
| first response expected is an acknowledgment: either `+' (to indicate |
| the package was received correctly) or `-' (to request retransmission): |
| |
| -> `$'PACKET-DATA`#'CHECKSUM |
| <- `+' |
| The host (GDB) sends COMMANDs, and the target (the debugging stub |
| incorporated in your program) sends a RESPONSE. In the case of step |
| and continue COMMANDs, the response is only sent when the operation has |
| completed (the target has again stopped). |
| |
| PACKET-DATA consists of a sequence of characters with the exception |
| of `#' and `$' (see `X' packet for additional exceptions). |
| |
| Fields within the packet should be separated using `,' `;' or `:'. |
| Except where otherwise noted all numbers are represented in HEX with |
| leading zeros suppressed. |
| |
| Implementors should note that prior to GDB 5.0, the character `:' |
| could not appear as the third character in a packet (as it would |
| potentially conflict with the SEQUENCE-ID). |
| |
| Binary data in most packets is encoded either as two hexadecimal |
| digits per byte of binary data. This allowed the traditional remote |
| protocol to work over connections which were only seven-bit clean. |
| Some packets designed more recently assume an eight-bit clean |
| connection, and use a more efficient encoding to send and receive |
| binary data. |
| |
| The binary data representation uses `7d' (ASCII `}') as an escape |
| character. Any escaped byte is transmitted as the escape character |
| followed by the original character XORed with `0x20'. For example, the |
| byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The |
| bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}') |
| must always be escaped. Responses sent by the stub must also escape |
| `0x2a' (ASCII `*'), so that it is not interpreted as the start of a |
| run-length encoded sequence (described next). |
| |
| Response DATA can be run-length encoded to save space. A `*' means |
| that the next character is an ASCII encoding giving a repeat count |
| which stands for that many repetitions of the character preceding the |
| `*'. The encoding is `n+29', yielding a printable character where `n |
| >=3' (which is where rle starts to win). The printable characters `$', |
| `#', `+' and `-' or with a numeric value greater than 126 should not be |
| used. |
| |
| So: |
| "`0* '" |
| means the same as "0000". |
| |
| The error response returned for some packets includes a two character |
| error number. That number is not well defined. |
| |
| For any COMMAND not supported by the stub, an empty response |
| (`$#00') should be returned. That way it is possible to extend the |
| protocol. A newer GDB can tell if a packet is supported based on that |
| response. |
| |
| A stub is required to support the `g', `G', `m', `M', `c', and `s' |
| COMMANDs. All other COMMANDs are optional. |
| |
| |
| File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol |
| |
| D.2 Packets |
| =========== |
| |
| The following table provides a complete list of all currently defined |
| COMMANDs and their corresponding response DATA. *Note File-I/O remote |
| protocol extension::, for details about the File I/O extension of the |
| remote protocol. |
| |
| Each packet's description has a template showing the packet's overall |
| syntax, followed by an explanation of the packet's meaning. We include |
| spaces in some of the templates for clarity; these are not part of the |
| packet's syntax. No GDB packet uses spaces to separate its components. |
| For example, a template like `foo BAR BAZ' describes a packet |
| beginning with the three ASCII bytes `foo', followed by a BAR, followed |
| directly by a BAZ. GDB does not transmit a space character between the |
| `foo' and the BAR, or between the BAR and the BAZ. |
| |
| Note that all packet forms beginning with an upper- or lower-case |
| letter, other than those described here, are reserved for future use. |
| |
| Here are the packet descriptions. |
| |
| `!' |
| Enable extended mode. In extended mode, the remote server is made |
| persistent. The `R' packet is used to restart the program being |
| debugged. |
| |
| Reply: |
| `OK' |
| The remote target both supports and has enabled extended mode. |
| |
| `?' |
| Indicate the reason the target halted. The reply is the same as |
| for step and continue. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| `A ARGLEN,ARGNUM,ARG,...' |
| Initialized `argv[]' array passed into program. ARGLEN specifies |
| the number of bytes in the hex encoded byte stream ARG. See |
| `gdbserver' for more details. |
| |
| Reply: |
| `OK' |
| The arguments were set. |
| |
| `E NN' |
| An error occurred. |
| |
| `b BAUD' |
| (Don't use this packet; its behavior is not well-defined.) Change |
| the serial line speed to BAUD. |
| |
| JTC: _When does the transport layer state change? When it's |
| received, or after the ACK is transmitted. In either case, there |
| are problems if the command or the acknowledgment packet is |
| dropped._ |
| |
| Stan: _If people really wanted to add something like this, and get |
| it working for the first time, they ought to modify ser-unix.c to |
| send some kind of out-of-band message to a specially-setup stub |
| and have the switch happen "in between" packets, so that from |
| remote protocol's point of view, nothing actually happened._ |
| |
| `B ADDR,MODE' |
| Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. |
| |
| Don't use this packet. Use the `Z' and `z' packets instead (*note |
| insert breakpoint or watchpoint packet::). |
| |
| `c [ADDR]' |
| Continue. ADDR is address to resume. If ADDR is omitted, resume |
| at current address. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| `C SIG[;ADDR]' |
| Continue with signal SIG (hex signal number). If `;ADDR' is |
| omitted, resume at same address. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| `d' |
| Toggle debug flag. |
| |
| Don't use this packet; instead, define a general set packet (*note |
| General Query Packets::). |
| |
| `D' |
| Detach GDB from the remote system. Sent to the remote target |
| before GDB disconnects via the `detach' command. |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error |
| |
| `F RC,EE,CF;XX' |
| A reply from GDB to an `F' packet sent by the target. This is |
| part of the File-I/O protocol extension. *Note File-I/O remote |
| protocol extension::, for the specification. |
| |
| `g' |
| Read general registers. |
| |
| Reply: |
| `XX...' |
| Each byte of register data is described by two hex digits. |
| The bytes with the register are transmitted in target byte |
| order. The size of each register and their position within |
| the `g' packet are determined by the GDB internal macros |
| `DEPRECATED_REGISTER_RAW_SIZE' and `REGISTER_NAME' macros. |
| The specification of several standard `g' packets is |
| specified below. |
| |
| `E NN' |
| for an error. |
| |
| `G XX...' |
| Write general registers. *Note read registers packet::, for a |
| description of the XX... data. |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error |
| |
| `H C T' |
| Set thread for subsequent operations (`m', `M', `g', `G', et.al.). |
| C depends on the operation to be performed: it should be `c' for |
| step and continue operations, `g' for other operations. The |
| thread designator T may be `-1', meaning all the threads, a thread |
| number, or `0' which means pick any thread. |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error |
| |
| `i [ADDR[,NNN]]' |
| Step the remote target by a single clock cycle. If `,NNN' is |
| present, cycle step NNN cycles. If ADDR is present, cycle step |
| starting at that address. |
| |
| `I' |
| Signal, then cycle step. *Note step with signal packet::. *Note |
| cycle step packet::. |
| |
| `k' |
| Kill request. |
| |
| FIXME: _There is no description of how to operate when a specific |
| thread context has been selected (i.e. does 'k' kill only that |
| thread?)_. |
| |
| `m ADDR,LENGTH' |
| Read LENGTH bytes of memory starting at address ADDR. Note that |
| ADDR may not be aligned to any particular boundary. |
| |
| The stub need not use any particular size or alignment when |
| gathering data from memory for the response; even if ADDR is |
| word-aligned and LENGTH is a multiple of the word size, the stub |
| is free to use byte accesses, or not. For this reason, this |
| packet may not be suitable for accessing memory-mapped I/O devices. |
| |
| Reply: |
| `XX...' |
| Memory contents; each byte is transmitted as a two-digit |
| hexadecimal number. The reply may contain fewer bytes than |
| requested if the server was able to read only part of the |
| region of memory. |
| |
| `E NN' |
| NN is errno |
| |
| `M ADDR,LENGTH:XX...' |
| Write LENGTH bytes of memory starting at address ADDR. XX... is |
| the data; each byte is transmitted as a two-digit hexadecimal |
| number. |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error (this includes the case where only part of the |
| data was written). |
| |
| `p N' |
| Read the value of register N; N is in hex. *Note read registers |
| packet::, for a description of how the returned register value is |
| encoded. |
| |
| Reply: |
| `XX...' |
| the register's value |
| |
| `E NN' |
| for an error |
| |
| `' |
| Indicating an unrecognized QUERY. |
| |
| `P N...=R...' |
| Write register N... with value R.... The register number N is in |
| hexadecimal, and R... contains two hex digits for each byte in the |
| register (target byte order). |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error |
| |
| `q NAME PARAMS...' |
| `Q NAME PARAMS...' |
| General query (`q') and set (`Q'). These packets are described |
| fully in *Note General Query Packets::. |
| |
| `r' |
| Reset the entire system. |
| |
| Don't use this packet; use the `R' packet instead. |
| |
| `R XX' |
| Restart the program being debugged. XX, while needed, is ignored. |
| This packet is only available in extended mode. |
| |
| The `R' packet has no reply. |
| |
| `s [ADDR]' |
| Single step. ADDR is the address at which to resume. If ADDR is |
| omitted, resume at same address. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| `S SIG[;ADDR]' |
| Step with signal. This is analogous to the `C' packet, but |
| requests a single-step, rather than a normal resumption of |
| execution. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| `t ADDR:PP,MM' |
| Search backwards starting at address ADDR for a match with pattern |
| PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 |
| digits. |
| |
| `T XX' |
| Find out if the thread XX is alive. |
| |
| Reply: |
| `OK' |
| thread is still alive |
| |
| `E NN' |
| thread is dead |
| |
| `v' |
| Packets starting with `v' are identified by a multi-letter name, |
| up to the first `;' or `?' (or the end of the packet). |
| |
| `vCont[;ACTION[:TID]]...' |
| Resume the inferior, specifying different actions for each thread. |
| If an action is specified with no TID, then it is applied to any |
| threads that don't have a specific action specified; if no default |
| action is specified then other threads should remain stopped. |
| Specifying multiple default actions is an error; specifying no |
| actions is also an error. Thread IDs are specified in |
| hexadecimal. Currently supported actions are: |
| |
| `c' |
| Continue. |
| |
| `C SIG' |
| Continue with signal SIG. SIG should be two hex digits. |
| |
| `s' |
| Step. |
| |
| `S SIG' |
| Step with signal SIG. SIG should be two hex digits. |
| |
| The optional ADDR argument normally associated with these packets |
| is not supported in `vCont'. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| `vCont?' |
| Request a list of actions supporetd by the `vCont' packet. |
| |
| Reply: |
| `vCont[;ACTION...]' |
| The `vCont' packet is supported. Each ACTION is a supported |
| command in the `vCont' packet. |
| |
| `' |
| The `vCont' packet is not supported. |
| |
| `vFlashErase:ADDR,LENGTH' |
| Direct the stub to erase LENGTH bytes of flash starting at ADDR. |
| The region may enclose any number of flash blocks, but its start |
| and end must fall on block boundaries, as indicated by the flash |
| block size appearing in the memory map (*note Memory map |
| format::). GDB groups flash memory programming operations |
| together, and sends a `vFlashDone' request after each group; the |
| stub is allowed to delay erase operation until the `vFlashDone' |
| packet is received. |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error |
| |
| `vFlashWrite:ADDR:XX...' |
| Direct the stub to write data to flash address ADDR. The data is |
| passed in binary form using the same encoding as for the `X' |
| packet (*note Binary Data::). The memory ranges specified by |
| `vFlashWrite' packets preceding a `vFlashDone' packet must not |
| overlap, and must appear in order of increasing addresses |
| (although `vFlashErase' packets for higher addresses may already |
| have been received; the ordering is guaranteed only between |
| `vFlashWrite' packets). If a packet writes to an address that was |
| neither erased by a preceding `vFlashErase' packet nor by some |
| other target-specific method, the results are unpredictable. |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E.memtype' |
| for vFlashWrite addressing non-flash memory |
| |
| `E NN' |
| for an error |
| |
| `vFlashDone' |
| Indicate to the stub that flash programming operation is finished. |
| The stub is permitted to delay or batch the effects of a group of |
| `vFlashErase' and `vFlashWrite' packets until a `vFlashDone' |
| packet is received. The contents of the affected regions of flash |
| memory are unpredictable until the `vFlashDone' request is |
| completed. |
| |
| `X ADDR,LENGTH:XX...' |
| Write data to memory, where the data is transmitted in binary. |
| ADDR is address, LENGTH is number of bytes, `XX...' is binary data |
| (*note Binary Data::). |
| |
| Reply: |
| `OK' |
| for success |
| |
| `E NN' |
| for an error |
| |
| `z TYPE,ADDR,LENGTH' |
| `Z TYPE,ADDR,LENGTH' |
| Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint |
| starting at address ADDRESS and covering the next LENGTH bytes. |
| |
| Each breakpoint and watchpoint packet TYPE is documented |
| separately. |
| |
| _Implementation notes: A remote target shall return an empty string |
| for an unrecognized breakpoint or watchpoint packet TYPE. A |
| remote target shall support either both or neither of a given |
| `ZTYPE...' and `zTYPE...' packet pair. To avoid potential |
| problems with duplicate packets, the operations should be |
| implemented in an idempotent way._ |
| |
| `z0,ADDR,LENGTH' |
| `Z0,ADDR,LENGTH' |
| Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR |
| of size LENGTH. |
| |
| A memory breakpoint is implemented by replacing the instruction at |
| ADDR with a software breakpoint or trap instruction. The LENGTH |
| is used by targets that indicates the size of the breakpoint (in |
| bytes) that should be inserted (e.g., the ARM and MIPS can insert |
| either a 2 or 4 byte breakpoint). |
| |
| _Implementation note: It is possible for a target to copy or move |
| code that contains memory breakpoints (e.g., when implementing |
| overlays). The behavior of this packet, in the presence of such a |
| target, is not defined._ |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z1,ADDR,LENGTH' |
| `Z1,ADDR,LENGTH' |
| Insert (`Z1') or remove (`z1') a hardware breakpoint at address |
| ADDR of size LENGTH. |
| |
| A hardware breakpoint is implemented using a mechanism that is not |
| dependant on being able to modify the target's memory. |
| |
| _Implementation note: A hardware breakpoint is not affected by code |
| movement._ |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z2,ADDR,LENGTH' |
| `Z2,ADDR,LENGTH' |
| Insert (`Z2') or remove (`z2') a write watchpoint. |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z3,ADDR,LENGTH' |
| `Z3,ADDR,LENGTH' |
| Insert (`Z3') or remove (`z3') a read watchpoint. |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z4,ADDR,LENGTH' |
| `Z4,ADDR,LENGTH' |
| Insert (`Z4') or remove (`z4') an access watchpoint. |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| |
| |
| File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol |
| |
| D.3 Stop Reply Packets |
| ====================== |
| |
| The `C', `c', `S', `s' and `?' packets can receive any of the below as |
| a reply. In the case of the `C', `c', `S' and `s' packets, that reply |
| is only returned when the target halts. In the below the exact meaning |
| of "signal number" is poorly defined. In general one of the UNIX signal |
| numbering conventions is used. |
| |
| As in the description of request packets, we include spaces in the |
| reply templates for clarity; these are not part of the reply packet's |
| syntax. No GDB stop reply packet uses spaces to separate its |
| components. |
| |
| `S AA' |
| The program received signal number AA (a two-digit hexadecimal |
| number). This is equivalent to a `T' response with no N:R pairs. |
| |
| `T AA N1:R1;N2:R2;...' |
| The program received signal number AA (a two-digit hexadecimal |
| number). This is equivalent to an `S' response, except that the |
| `N:R' pairs can carry values of important registers and other |
| information directly in the stop reply packet, reducing round-trip |
| latency. Single-step and breakpoint traps are reported this way. |
| Each `N:R' pair is interpreted as follows: |
| 1. If N is a hexadecimal number, it is a register number, and the |
| corresponding R gives that register's value. R is a series |
| of bytes in target byte order, with each byte given by a |
| two-digit hex number. |
| |
| 2. If N is `thread', then R is the thread process ID, in hex. |
| |
| 3. If N is `watch', `rwatch', or `awatch', then the packet |
| indicates a watchpoint hit, and R is the data address, in hex. |
| |
| 4. Otherwise, GDB should ignore this `N:R' pair and go on to the |
| next; this allows us to extend the protocol in the future. |
| |
| `W AA' |
| The process exited, and AA is the exit status. This is only |
| applicable to certain targets. |
| |
| `X AA' |
| The process terminated with signal AA. |
| |
| `O XX...' |
| `XX...' is hex encoding of ASCII data, to be written as the |
| program's console output. This can happen at any time while the |
| program is running and the debugger should continue to wait for |
| `W', `T', etc. |
| |
| `F CALL-ID,PARAMETER...' |
| CALL-ID is the identifier which says which host system call should |
| be called. This is just the name of the function. Translation |
| into the correct system call is only applicable as it's defined in |
| GDB. *Note File-I/O remote protocol extension::, for a list of |
| implemented system calls. |
| |
| `PARAMETER...' is a list of parameters as defined for this very |
| system call. |
| |
| The target replies with this packet when it expects GDB to call a |
| host system call on behalf of the target. GDB replies with an |
| appropriate `F' packet and keeps up waiting for the next reply |
| packet from the target. The latest `C', `c', `S' or `s' action is |
| expected to be continued. *Note File-I/O remote protocol |
| extension::, for more details. |
| |
| |
| |
| File: gdb.info, Node: General Query Packets, Next: Register Packet Format, Prev: Stop Reply Packets, Up: Remote Protocol |
| |
| D.4 General Query Packets |
| ========================= |
| |
| Packets starting with `q' are "general query packets"; packets starting |
| with `Q' are "general set packets". General query and set packets are |
| a semi-unified form for retrieving and sending information to and from |
| the stub. |
| |
| The initial letter of a query or set packet is followed by a name |
| indicating what sort of thing the packet applies to. For example, GDB |
| may use a `qSymbol' packet to exchange symbol definitions with the |
| stub. These packet names follow some conventions: |
| |
| * The name must not contain commas, colons or semicolons. |
| |
| * Most GDB query and set packets have a leading upper case letter. |
| |
| * The names of custom vendor packets should use a company prefix, in |
| lower case, followed by a period. For example, packets designed at |
| the Acme Corporation might begin with `qacme.foo' (for querying |
| foos) or `Qacme.bar' (for setting bars). |
| |
| The name of a query or set packet should be separated from any |
| parameters by a `:'; the parameters themselves should be separated by |
| `,' or `;'. Stubs must be careful to match the full packet name, and |
| check for a separator or the end of the packet, in case two packet |
| names share a common prefix. New packets should not begin with `qC', |
| `qP', or `qL'(1). |
| |
| Like the descriptions of the other packets, each description here |
| has a template showing the packet's overall syntax, followed by an |
| explanation of the packet's meaning. We include spaces in some of the |
| templates for clarity; these are not part of the packet's syntax. No |
| GDB packet uses spaces to separate its components. |
| |
| Here are the currently defined query and set packets: |
| |
| `qC' |
| Return the current thread id. |
| |
| Reply: |
| `QC PID' |
| Where PID is an unsigned hexadecimal process id. |
| |
| `(anything else)' |
| Any other reply implies the old pid. |
| |
| `qCRC:ADDR,LENGTH' |
| Compute the CRC checksum of a block of memory. Reply: |
| `E NN' |
| An error (such as memory fault) |
| |
| `C CRC32' |
| The specified memory region's checksum is CRC32. |
| |
| `qfThreadInfo' |
| `qsThreadInfo' |
| Obtain a list of all active thread ids from the target (OS). |
| Since there may be too many active threads to fit into one reply |
| packet, this query works iteratively: it may require more than one |
| query/reply sequence to obtain the entire list of threads. The |
| first query of the sequence will be the `qfThreadInfo' query; |
| subsequent queries in the sequence will be the `qsThreadInfo' |
| query. |
| |
| NOTE: This packet replaces the `qL' query (see below). |
| |
| Reply: |
| `m ID' |
| A single thread id |
| |
| `m ID,ID...' |
| a comma-separated list of thread ids |
| |
| `l' |
| (lower case letter `L') denotes end of list. |
| |
| In response to each query, the target will reply with a list of |
| one or more thread ids, in big-endian unsigned hex, separated by |
| commas. GDB will respond to each reply with a request for more |
| thread ids (using the `qs' form of the query), until the target |
| responds with `l' (lower-case el, for "last"). |
| |
| `qGetTLSAddr:THREAD-ID,OFFSET,LM' |
| Fetch the address associated with thread local storage specified |
| by THREAD-ID, OFFSET, and LM. |
| |
| THREAD-ID is the (big endian, hex encoded) thread id associated |
| with the thread for which to fetch the TLS address. |
| |
| OFFSET is the (big endian, hex encoded) offset associated with the |
| thread local variable. (This offset is obtained from the debug |
| information associated with the variable.) |
| |
| LM is the (big endian, hex encoded) OS/ABI specific encoding of the |
| the load module associated with the thread local storage. For |
| example, a GNU/Linux system will pass the link map address of the |
| shared object associated with the thread local storage under |
| consideration. Other operating environments may choose to |
| represent the load module differently, so the precise meaning of |
| this parameter will vary. |
| |
| Reply: |
| `XX...' |
| Hex encoded (big endian) bytes representing the address of |
| the thread local storage requested. |
| |
| `E NN' |
| An error occurred. NN are hex digits. |
| |
| `' |
| An empty reply indicates that `qGetTLSAddr' is not supported |
| by the stub. |
| |
| `qL STARTFLAG THREADCOUNT NEXTTHREAD' |
| Obtain thread information from RTOS. Where: STARTFLAG (one hex |
| digit) is one to indicate the first query and zero to indicate a |
| subsequent query; THREADCOUNT (two hex digits) is the maximum |
| number of threads the response packet can contain; and NEXTTHREAD |
| (eight hex digits), for subsequent queries (STARTFLAG is zero), is |
| returned in the response as ARGTHREAD. |
| |
| Don't use this packet; use the `qfThreadInfo' query instead (see |
| above). |
| |
| Reply: |
| `qM COUNT DONE ARGTHREAD THREAD...' |
| Where: COUNT (two hex digits) is the number of threads being |
| returned; DONE (one hex digit) is zero to indicate more |
| threads and one indicates no further threads; ARGTHREADID |
| (eight hex digits) is NEXTTHREAD from the request packet; |
| THREAD... is a sequence of thread IDs from the target. |
| THREADID (eight hex digits). See |
| `remote.c:parse_threadlist_response()'. |
| |
| `qOffsets' |
| Get section offsets that the target used when re-locating the |
| downloaded image. _Note: while a `Bss' offset is included in the |
| response, GDB ignores this and instead applies the `Data' offset |
| to the `Bss' section._ |
| |
| Reply: |
| `Text=XXX;Data=YYY;Bss=ZZZ' |
| |
| `qP MODE THREADID' |
| Returns information on THREADID. Where: MODE is a hex encoded 32 |
| bit mode; THREADID is a hex encoded 64 bit thread ID. |
| |
| Don't use this packet; use the `qThreadExtraInfo' query instead |
| (see below). |
| |
| Reply: see `remote.c:remote_unpack_thread_info_response()'. |
| |
| `qRcmd,COMMAND' |
| COMMAND (hex encoded) is passed to the local interpreter for |
| execution. Invalid commands should be reported using the output |
| string. Before the final result packet, the target may also |
| respond with a number of intermediate `OOUTPUT' console output |
| packets. _Implementors should note that providing access to a |
| stubs's interpreter may have security implications_. |
| |
| Reply: |
| `OK' |
| A command response with no output. |
| |
| `OUTPUT' |
| A command response with the hex encoded output string OUTPUT. |
| |
| `E NN' |
| Indicate a badly formed request. |
| |
| `' |
| An empty reply indicates that `qRcmd' is not recognized. |
| |
| (Note that the `qRcmd' packet's name is separated from the command |
| by a `,', not a `:', contrary to the naming conventions above. |
| Please don't use this packet as a model for new packets.) |
| |
| `qSupported [:GDBFEATURE [;GDBFEATURE]... ]' |
| Tell the remote stub about features supported by GDB, and query |
| the stub for features it supports. This packet allows GDB and the |
| remote stub to take advantage of each others' features. |
| `qSupported' also consolidates multiple feature probes at startup, |
| to improve GDB performance--a single larger packet performs better |
| than multiple smaller probe packets on high-latency links. Some |
| features may enable behavior which must not be on by default, e.g. |
| because it would confuse older clients or stubs. Other features |
| may describe packets which could be automatically probed for, but |
| are not. These features must be reported before GDB will use |
| them. This "default unsupported" behavior is not appropriate for |
| all packets, but it helps to keep the initial connection time |
| under control with new versions of GDB which support increasing |
| numbers of packets. |
| |
| Reply: |
| `STUBFEATURE [;STUBFEATURE]...' |
| The stub supports or does not support each returned |
| STUBFEATURE, depending on the form of each STUBFEATURE (see |
| below for the possible forms). |
| |
| `' |
| An empty reply indicates that `qSupported' is not recognized, |
| or that no features needed to be reported to GDB. |
| |
| The allowed forms for each feature (either a GDBFEATURE in the |
| `qSupported' packet, or a STUBFEATURE in the response) are: |
| |
| `NAME=VALUE' |
| The remote protocol feature NAME is supported, and associated |
| with the specified VALUE. The format of VALUE depends on the |
| feature, but it must not include a semicolon. |
| |
| `NAME+' |
| The remote protocol feature NAME is supported, and does not |
| need an associated value. |
| |
| `NAME-' |
| The remote protocol feature NAME is not supported. |
| |
| `NAME?' |
| The remote protocol feature NAME may be supported, and GDB |
| should auto-detect support in some other way when it is |
| needed. This form will not be used for GDBFEATURE |
| notifications, but may be used for STUBFEATURE responses. |
| |
| Whenever the stub receives a `qSupported' request, the supplied |
| set of GDB features should override any previous request. This |
| allows GDB to put the stub in a known state, even if the stub had |
| previously been communicating with a different version of GDB. |
| |
| No values of GDBFEATURE (for the packet sent by GDB) are defined |
| yet. Stubs should ignore any unknown values for GDBFEATURE. Any |
| GDB which sends a `qSupported' packet supports receiving packets |
| of unlimited length (earlier versions of GDB may reject overly |
| long responses). Values for GDBFEATURE may be defined in the |
| future to let the stub take advantage of new features in GDB, e.g. |
| incompatible improvements in the remote protocol--support for |
| unlimited length responses would be a GDBFEATURE example, if it |
| were not implied by the `qSupported' query. The stub's reply |
| should be independent of the GDBFEATURE entries sent by GDB; first |
| GDB describes all the features it supports, and then the stub |
| replies with all the features it supports. |
| |
| Similarly, GDB will silently ignore unrecognized stub feature |
| responses, as long as each response uses one of the standard forms. |
| |
| Some features are flags. A stub which supports a flag feature |
| should respond with a `+' form response. Other features require |
| values, and the stub should respond with an `=' form response. |
| |
| Each feature has a default value, which GDB will use if |
| `qSupported' is not available or if the feature is not mentioned |
| in the `qSupported' response. The default values are fixed; a |
| stub is free to omit any feature responses that match the defaults. |
| |
| Not all features can be probed, but for those which can, the |
| probing mechanism is useful: in some cases, a stub's internal |
| architecture may not allow the protocol layer to know some |
| information about the underlying target in advance. This is |
| especially common in stubs which may be configured for multiple |
| targets. |
| |
| These are the currently defined stub features and their properties: |
| |
| Feature Name Value Default Probe Allowed |
| Required |
| `PacketSize' Yes `-' No |
| `qXfer:auxv:read' No `-' Yes |
| `qXfer:memory-map:read'No `-' Yes |
| |
| These are the currently defined stub features, in more detail: |
| |
| `PacketSize=BYTES' |
| The remote stub can accept packets up to at least BYTES in |
| length. GDB will send packets up to this size for bulk |
| transfers, and will never send larger packets. This is a |
| limit on the data characters in the packet, including the |
| frame and checksum. There is no trailing NUL byte in a |
| remote protocol packet; if the stub stores packets in a |
| NUL-terminated format, it should allow an extra byte in its |
| buffer for the NUL. If this stub feature is not supported, |
| GDB guesses based on the size of the `g' packet response. |
| |
| `qXfer:auxv:read' |
| The remote stub understands the `qXfer:auxv:read' packet |
| (*note qXfer auxiliary vector read::). |
| |
| |
| `qSymbol::' |
| Notify the target that GDB is prepared to serve symbol lookup |
| requests. Accept requests from the target for the values of |
| symbols. |
| |
| Reply: |
| `OK' |
| The target does not need to look up any (more) symbols. |
| |
| `qSymbol:SYM_NAME' |
| The target requests the value of symbol SYM_NAME (hex |
| encoded). GDB may provide the value by using the |
| `qSymbol:SYM_VALUE:SYM_NAME' message, described below. |
| |
| `qSymbol:SYM_VALUE:SYM_NAME' |
| Set the value of SYM_NAME to SYM_VALUE. |
| |
| SYM_NAME (hex encoded) is the name of a symbol whose value the |
| target has previously requested. |
| |
| SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot |
| supply a value for SYM_NAME, then this field will be empty. |
| |
| Reply: |
| `OK' |
| The target does not need to look up any (more) symbols. |
| |
| `qSymbol:SYM_NAME' |
| The target requests the value of a new symbol SYM_NAME (hex |
| encoded). GDB will continue to supply the values of symbols |
| (if available), until the target ceases to request them. |
| |
| `QTDP' |
| `QTFrame' |
| *Note Tracepoint Packets::. |
| |
| `qThreadExtraInfo,ID' |
| Obtain a printable string description of a thread's attributes from |
| the target OS. ID is a thread-id in big-endian hex. This string |
| may contain anything that the target OS thinks is interesting for |
| GDB to tell the user about the thread. The string is displayed in |
| GDB's `info threads' display. Some examples of possible thread |
| extra info strings are `Runnable', or `Blocked on Mutex'. |
| |
| Reply: |
| `XX...' |
| Where `XX...' is a hex encoding of ASCII data, comprising the |
| printable string containing the extra information about the |
| thread's attributes. |
| |
| (Note that the `qThreadExtraInfo' packet's name is separated from |
| the command by a `,', not a `:', contrary to the naming |
| conventions above. Please don't use this packet as a model for new |
| packets.) |
| |
| `QTStart' |
| `QTStop' |
| `QTinit' |
| `QTro' |
| `qTStatus' |
| *Note Tracepoint Packets::. |
| |
| `qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' |
| Read uninterpreted bytes from the target's special data area |
| identified by the keyword OBJECT. Request LENGTH bytes starting |
| at OFFSET bytes into the data. The content and encoding of ANNEX |
| is specific to the object; it can supply additional details about |
| what data to access. |
| |
| Here are the specific requests of this form defined so far. All |
| `qXfer:OBJECT:read:...' requests use the same reply formats, |
| listed below. |
| |
| `qXfer:auxv:read::OFFSET,LENGTH' |
| Access the target's "auxiliary vector". *Note auxiliary |
| vector: OS Information. Note ANNEX must be empty. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by suppling an appropriate `qSupported' response |
| (*note qSupported::). |
| |
| `qXfer:memory-map:read::OFFSET,LENGTH' |
| Access the target's "memory-map". *Note Memory map format::. |
| The annex part of the generic `qXfer' packet must be empty |
| (*note qXfer read::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate `qSupported' response |
| (*note qSupported::). |
| |
| Reply: |
| `m DATA' |
| Data DATA (*note Binary Data::) has been read from the |
| target. There may be more data at a higher address (although |
| it is permitted to return `m' even for the last valid block |
| of data, as long as at least one byte of data was read). |
| DATA may have fewer bytes than the LENGTH in the request. |
| |
| `l DATA' |
| Data DATA (*note Binary Data::) has been read from the target. |
| There is no more data to be read. DATA may have fewer bytes |
| than the LENGTH in the request. |
| |
| `l' |
| The OFFSET in the request is at the end of the data. There |
| is no more data to be read. |
| |
| `E00' |
| The request was malformed, or ANNEX was invalid. |
| |
| `E NN' |
| The offset was invalid, or there was an error encountered |
| reading the data. NN is a hex-encoded `errno' value. |
| |
| `' |
| An empty reply indicates the OBJECT string was not recognized |
| by the stub, or that the object does not support reading. |
| |
| `qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' |
| Write uninterpreted bytes into the target's special data area |
| identified by the keyword OBJECT, starting at OFFSET bytes into |
| the data. `DATA...' is the binary-encoded data (*note Binary |
| Data::) to be written. The content and encoding of ANNEX is |
| specific to the object; it can supply additional details about |
| what data to access. |
| |
| No requests of this form are presently in use. This specification |
| serves as a placeholder to document the common format that new |
| specific request specifications ought to use. |
| |
| Reply: |
| `NN' |
| NN (hex encoded) is the number of bytes written. This may be |
| fewer bytes than supplied in the request. |
| |
| `E00' |
| The request was malformed, or ANNEX was invalid. |
| |
| `E NN' |
| The offset was invalid, or there was an error encountered |
| writing the data. NN is a hex-encoded `errno' value. |
| |
| `' |
| An empty reply indicates the OBJECT string was not recognized |
| by the stub, or that the object does not support writing. |
| |
| `qXfer:OBJECT:OPERATION:...' |
| Requests of this form may be added in the future. When a stub does |
| not recognize the OBJECT keyword, or its support for OBJECT does |
| not recognize the OPERATION keyword, the stub must respond with an |
| empty packet. |
| |
| |
| ---------- Footnotes ---------- |
| |
| (1) The `qP' and `qL' packets predate these conventions, and have |
| arguments without any terminator for the packet name; we suspect they |
| are in widespread use in places that are difficult to upgrade. The |
| `qC' packet has no arguments, but some existing stubs (e.g. RedBoot) |
| are known to not check for the end of the packet. |
| |
| |
| File: gdb.info, Node: Register Packet Format, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol |
| |
| D.5 Register Packet Format |
| ========================== |
| |
| The following `g'/`G' packets have previously been defined. In the |
| below, some thirty-two bit registers are transferred as sixty-four |
| bits. Those registers should be zero/sign extended (which?) to fill |
| the space allocated. Register bytes are transferred in target byte |
| order. The two nibbles within a register byte are transferred |
| most-significant - least-significant. |
| |
| MIPS32 |
| All registers are transferred as thirty-two bit quantities in the |
| order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 |
| floating-point registers; fsr; fir; fp. |
| |
| MIPS64 |
| All registers are transferred as sixty-four bit quantities |
| (including thirty-two bit registers such as `sr'). The ordering |
| is the same as `MIPS32'. |
| |
| |
| |
| File: gdb.info, Node: Tracepoint Packets, Next: Interrupts, Prev: Register Packet Format, Up: Remote Protocol |
| |
| D.6 Tracepoint Packets |
| ====================== |
| |
| Here we describe the packets GDB uses to implement tracepoints (*note |
| Tracepoints::). |
| |
| `QTDP:N:ADDR:ENA:STEP:PASS[-]' |
| Create a new tracepoint, number N, at ADDR. If ENA is `E', then |
| the tracepoint is enabled; if it is `D', then the tracepoint is |
| disabled. STEP is the tracepoint's step count, and PASS is its |
| pass count. If the trailing `-' is present, further `QTDP' |
| packets will follow to specify this tracepoint's actions. |
| |
| Replies: |
| `OK' |
| The packet was understood and carried out. |
| |
| `' |
| The packet was not recognized. |
| |
| `QTDP:-N:ADDR:[S]ACTION...[-]' |
| Define actions to be taken when a tracepoint is hit. N and ADDR |
| must be the same as in the initial `QTDP' packet for this |
| tracepoint. This packet may only be sent immediately after |
| another `QTDP' packet that ended with a `-'. If the trailing `-' |
| is present, further `QTDP' packets will follow, specifying more |
| actions for this tracepoint. |
| |
| In the series of action packets for a given tracepoint, at most one |
| can have an `S' before its first ACTION. If such a packet is |
| sent, it and the following packets define "while-stepping" |
| actions. Any prior packets define ordinary actions -- that is, |
| those taken when the tracepoint is first hit. If no action packet |
| has an `S', then all the packets in the series specify ordinary |
| tracepoint actions. |
| |
| The `ACTION...' portion of the packet is a series of actions, |
| concatenated without separators. Each action has one of the |
| following forms: |
| |
| `R MASK' |
| Collect the registers whose bits are set in MASK. MASK is a |
| hexadecimal number whose I'th bit is set if register number I |
| should be collected. (The least significant bit is numbered |
| zero.) Note that MASK may be any number of digits long; it |
| may not fit in a 32-bit word. |
| |
| `M BASEREG,OFFSET,LEN' |
| Collect LEN bytes of memory starting at the address in |
| register number BASEREG, plus OFFSET. If BASEREG is `-1', |
| then the range has a fixed address: OFFSET is the address of |
| the lowest byte to collect. The BASEREG, OFFSET, and LEN |
| parameters are all unsigned hexadecimal values (the `-1' |
| value for BASEREG is a special case). |
| |
| `X LEN,EXPR' |
| Evaluate EXPR, whose length is LEN, and collect memory as it |
| directs. EXPR is an agent expression, as described in *Note |
| Agent Expressions::. Each byte of the expression is encoded |
| as a two-digit hex number in the packet; LEN is the number of |
| bytes in the expression (and thus one-half the number of hex |
| digits in the packet). |
| |
| |
| Any number of actions may be packed together in a single `QTDP' |
| packet, as long as the packet does not exceed the maximum packet |
| length (400 bytes, for many stubs). There may be only one `R' |
| action per tracepoint, and it must precede any `M' or `X' actions. |
| Any registers referred to by `M' and `X' actions must be |
| collected by a preceding `R' action. (The "while-stepping" |
| actions are treated as if they were attached to a separate |
| tracepoint, as far as these restrictions are concerned.) |
| |
| Replies: |
| `OK' |
| The packet was understood and carried out. |
| |
| `' |
| The packet was not recognized. |
| |
| `QTFrame:N' |
| Select the N'th tracepoint frame from the buffer, and use the |
| register and memory contents recorded there to answer subsequent |
| request packets from GDB. |
| |
| A successful reply from the stub indicates that the stub has found |
| the requested frame. The response is a series of parts, |
| concatenated without separators, describing the frame we selected. |
| Each part has one of the following forms: |
| |
| `F F' |
| The selected frame is number N in the trace frame buffer; F |
| is a hexadecimal number. If F is `-1', then there was no |
| frame matching the criteria in the request packet. |
| |
| `T T' |
| The selected trace frame records a hit of tracepoint number T; |
| T is a hexadecimal number. |
| |
| |
| `QTFrame:pc:ADDR' |
| Like `QTFrame:N', but select the first tracepoint frame after the |
| currently selected frame whose PC is ADDR; ADDR is a hexadecimal |
| number. |
| |
| `QTFrame:tdp:T' |
| Like `QTFrame:N', but select the first tracepoint frame after the |
| currently selected frame that is a hit of tracepoint T; T is a |
| hexadecimal number. |
| |
| `QTFrame:range:START:END' |
| Like `QTFrame:N', but select the first tracepoint frame after the |
| currently selected frame whose PC is between START (inclusive) and |
| END (exclusive); START and END are hexadecimal numbers. |
| |
| `QTFrame:outside:START:END' |
| Like `QTFrame:range:START:END', but select the first frame |
| _outside_ the given range of addresses. |
| |
| `QTStart' |
| Begin the tracepoint experiment. Begin collecting data from |
| tracepoint hits in the trace frame buffer. |
| |
| `QTStop' |
| End the tracepoint experiment. Stop collecting trace frames. |
| |
| `QTinit' |
| Clear the table of tracepoints, and empty the trace frame buffer. |
| |
| `QTro:START1,END1:START2,END2:...' |
| Establish the given ranges of memory as "transparent". The stub |
| will answer requests for these ranges from memory's current |
| contents, if they were not collected as part of the tracepoint hit. |
| |
| GDB uses this to mark read-only regions of memory, like those |
| containing program code. Since these areas never change, they |
| should still have the same contents they did when the tracepoint |
| was hit, so there's no reason for the stub to refuse to provide |
| their contents. |
| |
| `qTStatus' |
| Ask the stub if there is a trace experiment running right now. |
| |
| Replies: |
| `T0' |
| There is no trace experiment running. |
| |
| `T1' |
| There is a trace experiment running. |
| |
| |
| |
| File: gdb.info, Node: Interrupts, Next: Examples, Prev: Tracepoint Packets, Up: Remote Protocol |
| |
| D.7 Interrupts |
| ============== |
| |
| When a program on the remote target is running, GDB may attempt to |
| interrupt it by sending a `Ctrl-C' or a `BREAK', control of which is |
| specified via GDB's `remotebreak' setting (*note set remotebreak::). |
| |
| The precise meaning of `BREAK' is defined by the transport mechanism |
| and may, in fact, be undefined. GDB does not currently define a |
| `BREAK' mechanism for any of the network interfaces. |
| |
| `Ctrl-C', on the other hand, is defined and implemented for all |
| transport mechanisms. It is represented by sending the single byte |
| `0x03' without any of the usual packet overhead described in the |
| Overview section (*note Overview::). When a `0x03' byte is transmitted |
| as part of a packet, it is considered to be packet data and does _not_ |
| represent an interrupt. E.g., an `X' packet (*note X packet::), used |
| for binary downloads, may include an unescaped `0x03' as part of its |
| packet. |
| |
| Stubs are not required to recognize these interrupt mechanisms and |
| the precise meaning associated with receipt of the interrupt is |
| implementation defined. If the stub is successful at interrupting the |
| running program, it is expected that it will send one of the Stop Reply |
| Packets (*note Stop Reply Packets::) to GDB as a result of successfully |
| stopping the program. Interrupts received while the program is stopped |
| will be discarded. |
| |
| |
| File: gdb.info, Node: Examples, Next: File-I/O remote protocol extension, Prev: Interrupts, Up: Remote Protocol |
| |
| D.8 Examples |
| ============ |
| |
| Example sequence of a target being re-started. Notice how the restart |
| does not get any direct output: |
| |
| -> `R00' |
| <- `+' |
| _target restarts_ |
| -> `?' |
| <- `+' |
| <- `T001:1234123412341234' |
| -> `+' |
| |
| Example sequence of a target being stepped by a single instruction: |
| |
| -> `G1445...' |
| <- `+' |
| -> `s' |
| <- `+' |
| _time passes_ |
| <- `T001:1234123412341234' |
| -> `+' |
| -> `g' |
| <- `+' |
| <- `1455...' |
| -> `+' |
| |
| |
| File: gdb.info, Node: File-I/O remote protocol extension, Next: Memory map format, Prev: Examples, Up: Remote Protocol |
| |
| D.9 File-I/O remote protocol extension |
| ====================================== |
| |
| * Menu: |
| |
| * File-I/O Overview:: |
| * Protocol basics:: |
| * The F request packet:: |
| * The F reply packet:: |
| * The Ctrl-C message:: |
| * Console I/O:: |
| * List of supported calls:: |
| * Protocol specific representation of datatypes:: |
| * Constants:: |
| * File-I/O Examples:: |
| |
| |
| File: gdb.info, Node: File-I/O Overview, Next: Protocol basics, Up: File-I/O remote protocol extension |
| |
| D.9.1 File-I/O Overview |
| ----------------------- |
| |
| The "File I/O remote protocol extension" (short: File-I/O) allows the |
| target to use the host's file system and console I/O to perform various |
| system calls. System calls on the target system are translated into a |
| remote protocol packet to the host system, which then performs the |
| needed actions and returns a response packet to the target system. |
| This simulates file system operations even on targets that lack file |
| systems. |
| |
| The protocol is defined to be independent of both the host and |
| target systems. It uses its own internal representation of datatypes |
| and values. Both GDB and the target's GDB stub are responsible for |
| translating the system-dependent value representations into the internal |
| protocol representations when data is transmitted. |
| |
| The communication is synchronous. A system call is possible only |
| when GDB is waiting for a response from the `C', `c', `S' or `s' |
| packets. While GDB handles the request for a system call, the target |
| is stopped to allow deterministic access to the target's memory. |
| Therefore File-I/O is not interruptible by target signals. On the |
| other hand, it is possible to interrupt File-I/O by a user interrupt |
| (`Ctrl-C') within GDB. |
| |
| The target's request to perform a host system call does not finish |
| the latest `C', `c', `S' or `s' action. That means, after finishing |
| the system call, the target returns to continuing the previous activity |
| (continue, step). No additional continue or step request from GDB is |
| required. |
| |
| (gdb) continue |
| <- target requests 'system call X' |
| target is stopped, GDB executes system call |
| -> GDB returns result |
| ... target continues, GDB returns to wait for the target |
| <- target hits breakpoint and sends a Txx packet |
| |
| The protocol only supports I/O on the console and to regular files on |
| the host file system. Character or block special devices, pipes, named |
| pipes, sockets or any other communication method on the host system are |
| not supported by this protocol. |
| |
| |
| File: gdb.info, Node: Protocol basics, Next: The F request packet, Prev: File-I/O Overview, Up: File-I/O remote protocol extension |
| |
| D.9.2 Protocol basics |
| --------------------- |
| |
| The File-I/O protocol uses the `F' packet as the request as well as |
| reply packet. Since a File-I/O system call can only occur when GDB is |
| waiting for a response from the continuing or stepping target, the |
| File-I/O request is a reply that GDB has to expect as a result of a |
| previous `C', `c', `S' or `s' packet. This `F' packet contains all |
| information needed to allow GDB to call the appropriate host system |
| call: |
| |
| * A unique identifier for the requested system call. |
| |
| * All parameters to the system call. Pointers are given as addresses |
| in the target memory address space. Pointers to strings are given |
| as pointer/length pair. Numerical values are given as they are. |
| Numerical control flags are given in a protocol specific |
| representation. |
| |
| |
| At this point, GDB has to perform the following actions. |
| |
| * If the parameters include pointer values to data needed as input |
| to a system call, GDB requests this data from the target with a |
| standard `m' packet request. This additional communication has to |
| be expected by the target implementation and is handled as any |
| other `m' packet. |
| |
| * GDB translates all value from protocol representation to host |
| representation as needed. Datatypes are coerced into the host |
| types. |
| |
| * GDB calls the system call. |
| |
| * It then coerces datatypes back to protocol representation. |
| |
| * If the system call is expected to return data in buffer space |
| specified by pointer parameters to the call, the data is |
| transmitted to the target using a `M' or `X' packet. This packet |
| has to be expected by the target implementation and is handled as |
| any other `M' or `X' packet. |
| |
| |
| Eventually GDB replies with another `F' packet which contains all |
| necessary information for the target to continue. This at least |
| contains |
| |
| * Return value. |
| |
| * `errno', if has been changed by the system call. |
| |
| * "Ctrl-C" flag. |
| |
| |
| After having done the needed type and value coercion, the target |
| continues the latest continue or step action. |
| |
| |
| File: gdb.info, Node: The F request packet, Next: The F reply packet, Prev: Protocol basics, Up: File-I/O remote protocol extension |
| |
| D.9.3 The `F' request packet |
| ---------------------------- |
| |
| The `F' request packet has the following format: |
| |
| `FCALL-ID,PARAMETER...' |
| CALL-ID is the identifier to indicate the host system call to be |
| called. This is just the name of the function. |
| |
| PARAMETER... are the parameters to the system call. Parameters |
| are hexadecimal integer values, either the actual values in case |
| of scalar datatypes, pointers to target buffer space in case of |
| compound datatypes and unspecified memory areas, or pointer/length |
| pairs in case of string parameters. These are appended to the |
| CALL-ID as a comma-delimited list. All values are transmitted in |
| ASCII string representation, pointer/length pairs separated by a |
| slash. |
| |
| |
| |
| File: gdb.info, Node: The F reply packet, Next: The Ctrl-C message, Prev: The F request packet, Up: File-I/O remote protocol extension |
| |
| D.9.4 The `F' reply packet |
| -------------------------- |
| |
| The `F' reply packet has the following format: |
| |
| `FRETCODE,ERRNO,CTRL-C FLAG;CALL SPECIFIC ATTACHMENT' |
| RETCODE is the return code of the system call as hexadecimal value. |
| |
| ERRNO is the `errno' set by the call, in protocol specific |
| representation. This parameter can be omitted if the call was |
| successful. |
| |
| CTRL-C FLAG is only sent if the user requested a break. In this |
| case, ERRNO must be sent as well, even if the call was successful. |
| The CTRL-C FLAG itself consists of the character `C': |
| |
| F0,0,C |
| |
| or, if the call was interrupted before the host call has been |
| performed: |
| |
| F-1,4,C |
| |
| assuming 4 is the protocol specific representation of `EINTR'. |
| |
| |
| |
| File: gdb.info, Node: The Ctrl-C message, Next: Console I/O, Prev: The F reply packet, Up: File-I/O remote protocol extension |
| |
| D.9.5 The `Ctrl-C' message |
| -------------------------- |
| |
| If the `Ctrl-C' flag is set in the GDB reply packet (*note The F reply |
| packet::), the target should behave as if it had gotten a break |
| message. The meaning for the target is "system call interrupted by |
| `SIGINT'". Consequentially, the target should actually stop (as with a |
| break message) and return to GDB with a `T02' packet. |
| |
| It's important for the target to know in which state the system call |
| was interrupted. There are two possible cases: |
| |
| * The system call hasn't been performed on the host yet. |
| |
| * The system call on the host has been finished. |
| |
| |
| These two states can be distinguished by the target by the value of |
| the returned `errno'. If it's the protocol representation of `EINTR', |
| the system call hasn't been performed. This is equivalent to the |
| `EINTR' handling on POSIX systems. In any other case, the target may |
| presume that the system call has been finished -- successfully or not |
| -- and should behave as if the break message arrived right after the |
| system call. |
| |
| GDB must behave reliably. If the system call has not been called |
| yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno' |
| in the packet. If the system call on the host has been finished before |
| the user requests a break, the full action must be finished by GDB. |
| This requires sending `M' or `X' packets as necessary. The `F' packet |
| may only be sent when either nothing has happened or the full action |
| has been completed. |
| |
| |
| File: gdb.info, Node: Console I/O, Next: List of supported calls, Prev: The Ctrl-C message, Up: File-I/O remote protocol extension |
| |
| D.9.6 Console I/O |
| ----------------- |
| |
| By default and if not explicitely closed by the target system, the file |
| descriptors 0, 1 and 2 are connected to the GDB console. Output on the |
| GDB console is handled as any other file output operation (`write(1, |
| ...)' or `write(2, ...)'). Console input is handled by GDB so that |
| after the target read request from file descriptor 0 all following |
| typing is buffered until either one of the following conditions is met: |
| |
| * The user types `Ctrl-c'. The behaviour is as explained above, and |
| the `read' system call is treated as finished. |
| |
| * The user presses <RET>. This is treated as end of input with a |
| trailing newline. |
| |
| * The user types `Ctrl-d'. This is treated as end of input. No |
| trailing character (neither newline nor `Ctrl-D') is appended to |
| the input. |
| |
| |
| If the user has typed more characters than fit in the buffer given to |
| the `read' call, the trailing characters are buffered in GDB until |
| either another `read(0, ...)' is requested by the target, or debugging |
| is stopped at the user's request. |
| |
| |
| File: gdb.info, Node: List of supported calls, Next: Protocol specific representation of datatypes, Prev: Console I/O, Up: File-I/O remote protocol extension |
| |
| D.9.7 List of supported calls |
| ----------------------------- |
| |
| * Menu: |
| |
| * open:: |
| * close:: |
| * read:: |
| * write:: |
| * lseek:: |
| * rename:: |
| * unlink:: |
| * stat/fstat:: |
| * gettimeofday:: |
| * isatty:: |
| * system:: |
| |
| |
| File: gdb.info, Node: open, Next: close, Up: List of supported calls |
| |
| open |
| .... |
| |
| Synopsis: |
| int open(const char *pathname, int flags); |
| int open(const char *pathname, int flags, mode_t mode); |
| |
| Request: |
| `Fopen,PATHPTR/LEN,FLAGS,MODE' |
| |
| FLAGS is the bitwise `OR' of the following values: |
| |
| `O_CREAT' |
| If the file does not exist it will be created. The host |
| rules apply as far as file ownership and time stamps are |
| concerned. |
| |
| `O_EXCL' |
| When used with `O_CREAT', if the file already exists it is an |
| error and open() fails. |
| |
| `O_TRUNC' |
| If the file already exists and the open mode allows writing |
| (`O_RDWR' or `O_WRONLY' is given) it will be truncated to |
| zero length. |
| |
| `O_APPEND' |
| The file is opened in append mode. |
| |
| `O_RDONLY' |
| The file is opened for reading only. |
| |
| `O_WRONLY' |
| The file is opened for writing only. |
| |
| `O_RDWR' |
| The file is opened for reading and writing. |
| |
| Other bits are silently ignored. |
| |
| MODE is the bitwise `OR' of the following values: |
| |
| `S_IRUSR' |
| User has read permission. |
| |
| `S_IWUSR' |
| User has write permission. |
| |
| `S_IRGRP' |
| Group has read permission. |
| |
| `S_IWGRP' |
| Group has write permission. |
| |
| `S_IROTH' |
| Others have read permission. |
| |
| `S_IWOTH' |
| Others have write permission. |
| |
| Other bits are silently ignored. |
| |
| Return value: |
| `open' returns the new file descriptor or -1 if an error occurred. |
| |
| Errors: |
| |
| `EEXIST' |
| PATHNAME already exists and `O_CREAT' and `O_EXCL' were used. |
| |
| `EISDIR' |
| PATHNAME refers to a directory. |
| |
| `EACCES' |
| The requested access is not allowed. |
| |
| `ENAMETOOLONG' |
| PATHNAME was too long. |
| |
| `ENOENT' |
| A directory component in PATHNAME does not exist. |
| |
| `ENODEV' |
| PATHNAME refers to a device, pipe, named pipe or socket. |
| |
| `EROFS' |
| PATHNAME refers to a file on a read-only filesystem and write |
| access was requested. |
| |
| `EFAULT' |
| PATHNAME is an invalid pointer value. |
| |
| `ENOSPC' |
| No space on device to create the file. |
| |
| `EMFILE' |
| The process already has the maximum number of files open. |
| |
| `ENFILE' |
| The limit on the total number of files open on the system has |
| been reached. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: close, Next: read, Prev: open, Up: List of supported calls |
| |
| close |
| ..... |
| |
| Synopsis: |
| int close(int fd); |
| |
| Request: |
| `Fclose,FD' |
| |
| Return value: |
| `close' returns zero on success, or -1 if an error occurred. |
| |
| Errors: |
| |
| `EBADF' |
| FD isn't a valid open file descriptor. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: read, Next: write, Prev: close, Up: List of supported calls |
| |
| read |
| .... |
| |
| Synopsis: |
| int read(int fd, void *buf, unsigned int count); |
| |
| Request: |
| `Fread,FD,BUFPTR,COUNT' |
| |
| Return value: |
| On success, the number of bytes read is returned. Zero indicates |
| end of file. If count is zero, read returns zero as well. On |
| error, -1 is returned. |
| |
| Errors: |
| |
| `EBADF' |
| FD is not a valid file descriptor or is not open for reading. |
| |
| `EFAULT' |
| BUFPTR is an invalid pointer value. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of supported calls |
| |
| write |
| ..... |
| |
| Synopsis: |
| int write(int fd, const void *buf, unsigned int count); |
| |
| Request: |
| `Fwrite,FD,BUFPTR,COUNT' |
| |
| Return value: |
| On success, the number of bytes written are returned. Zero |
| indicates nothing was written. On error, -1 is returned. |
| |
| Errors: |
| |
| `EBADF' |
| FD is not a valid file descriptor or is not open for writing. |
| |
| `EFAULT' |
| BUFPTR is an invalid pointer value. |
| |
| `EFBIG' |
| An attempt was made to write a file that exceeds the host |
| specific maximum file size allowed. |
| |
| `ENOSPC' |
| No space on device to write the data. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of supported calls |
| |
| lseek |
| ..... |
| |
| Synopsis: |
| long lseek (int fd, long offset, int flag); |
| |
| Request: |
| `Flseek,FD,OFFSET,FLAG' |
| |
| FLAG is one of: |
| |
| `SEEK_SET' |
| The offset is set to OFFSET bytes. |
| |
| `SEEK_CUR' |
| The offset is set to its current location plus OFFSET bytes. |
| |
| `SEEK_END' |
| The offset is set to the size of the file plus OFFSET bytes. |
| |
| Return value: |
| On success, the resulting unsigned offset in bytes from the |
| beginning of the file is returned. Otherwise, a value of -1 is |
| returned. |
| |
| Errors: |
| |
| `EBADF' |
| FD is not a valid open file descriptor. |
| |
| `ESPIPE' |
| FD is associated with the GDB console. |
| |
| `EINVAL' |
| FLAG is not a proper value. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of supported calls |
| |
| rename |
| ...... |
| |
| Synopsis: |
| int rename(const char *oldpath, const char *newpath); |
| |
| Request: |
| `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' |
| |
| Return value: |
| On success, zero is returned. On error, -1 is returned. |
| |
| Errors: |
| |
| `EISDIR' |
| NEWPATH is an existing directory, but OLDPATH is not a |
| directory. |
| |
| `EEXIST' |
| NEWPATH is a non-empty directory. |
| |
| `EBUSY' |
| OLDPATH or NEWPATH is a directory that is in use by some |
| process. |
| |
| `EINVAL' |
| An attempt was made to make a directory a subdirectory of |
| itself. |
| |
| `ENOTDIR' |
| A component used as a directory in OLDPATH or new path is |
| not a directory. Or OLDPATH is a directory and NEWPATH |
| exists but is not a directory. |
| |
| `EFAULT' |
| OLDPATHPTR or NEWPATHPTR are invalid pointer values. |
| |
| `EACCES' |
| No access to the file or the path of the file. |
| |
| `ENAMETOOLONG' |
| OLDPATH or NEWPATH was too long. |
| |
| `ENOENT' |
| A directory component in OLDPATH or NEWPATH does not exist. |
| |
| `EROFS' |
| The file is on a read-only filesystem. |
| |
| `ENOSPC' |
| The device containing the file has no room for the new |
| directory entry. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of supported calls |
| |
| unlink |
| ...... |
| |
| Synopsis: |
| int unlink(const char *pathname); |
| |
| Request: |
| `Funlink,PATHNAMEPTR/LEN' |
| |
| Return value: |
| On success, zero is returned. On error, -1 is returned. |
| |
| Errors: |
| |
| `EACCES' |
| No access to the file or the path of the file. |
| |
| `EPERM' |
| The system does not allow unlinking of directories. |
| |
| `EBUSY' |
| The file PATHNAME cannot be unlinked because it's being used |
| by another process. |
| |
| `EFAULT' |
| PATHNAMEPTR is an invalid pointer value. |
| |
| `ENAMETOOLONG' |
| PATHNAME was too long. |
| |
| `ENOENT' |
| A directory component in PATHNAME does not exist. |
| |
| `ENOTDIR' |
| A component of the path is not a directory. |
| |
| `EROFS' |
| The file is on a read-only filesystem. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of supported calls |
| |
| stat/fstat |
| .......... |
| |
| Synopsis: |
| int stat(const char *pathname, struct stat *buf); |
| int fstat(int fd, struct stat *buf); |
| |
| Request: |
| `Fstat,PATHNAMEPTR/LEN,BUFPTR' |
| `Ffstat,FD,BUFPTR' |
| |
| Return value: |
| On success, zero is returned. On error, -1 is returned. |
| |
| Errors: |
| |
| `EBADF' |
| FD is not a valid open file. |
| |
| `ENOENT' |
| A directory component in PATHNAME does not exist or the path |
| is an empty string. |
| |
| `ENOTDIR' |
| A component of the path is not a directory. |
| |
| `EFAULT' |
| PATHNAMEPTR is an invalid pointer value. |
| |
| `EACCES' |
| No access to the file or the path of the file. |
| |
| `ENAMETOOLONG' |
| PATHNAME was too long. |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| |
| File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of supported calls |
| |
| gettimeofday |
| ............ |
| |
| Synopsis: |
| int gettimeofday(struct timeval *tv, void *tz); |
| |
| Request: |
| `Fgettimeofday,TVPTR,TZPTR' |
| |
| Return value: |
| On success, 0 is returned, -1 otherwise. |
| |
| Errors: |
| |
| `EINVAL' |
| TZ is a non-NULL pointer. |
| |
| `EFAULT' |
| TVPTR and/or TZPTR is an invalid pointer value. |
| |
| |
| |
| File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of supported calls |
| |
| isatty |
| ...... |
| |
| Synopsis: |
| int isatty(int fd); |
| |
| Request: |
| `Fisatty,FD' |
| |
| Return value: |
| Returns 1 if FD refers to the GDB console, 0 otherwise. |
| |
| Errors: |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| Note that the `isatty' call is treated as a special case: it returns |
| 1 to the target if the file descriptor is attached to the GDB console, |
| 0 otherwise. Implementing through system calls would require |
| implementing `ioctl' and would be more complex than needed. |
| |
| |
| File: gdb.info, Node: system, Prev: isatty, Up: List of supported calls |
| |
| system |
| ...... |
| |
| Synopsis: |
| int system(const char *command); |
| |
| Request: |
| `Fsystem,COMMANDPTR/LEN' |
| |
| Return value: |
| If LEN is zero, the return value indicates whether a shell is |
| available. A zero return value indicates a shell is not available. |
| For non-zero LEN, the value returned is -1 on error and the return |
| status of the command otherwise. Only the exit status of the |
| command is returned, which is extracted from the host's `system' |
| return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh' |
| could not be executed, 127 is returned. |
| |
| Errors: |
| |
| `EINTR' |
| The call was interrupted by the user. |
| |
| |
| GDB takes over the full task of calling the necessary host calls to |
| perform the `system' call. The return value of `system' on the host is |
| simplified before it's returned to the target. Any termination signal |
| information from the child process is discarded, and the return value |
| consists entirely of the exit status of the called command. |
| |
| Due to security concerns, the `system' call is by default refused by |
| GDB. The user has to allow this call explicitly with the `set remote |
| system-call-allowed 1' command. |
| |
| `set remote system-call-allowed' |
| Control whether to allow the `system' calls in the File I/O |
| protocol for the remote target. The default is zero (disabled). |
| |
| `show remote system-call-allowed' |
| Show whether the `system' calls are allowed in the File I/O |
| protocol. |
| |
| |
| File: gdb.info, Node: Protocol specific representation of datatypes, Next: Constants, Prev: List of supported calls, Up: File-I/O remote protocol extension |
| |
| D.9.8 Protocol specific representation of datatypes |
| --------------------------------------------------- |
| |
| * Menu: |
| |
| * Integral datatypes:: |
| * Pointer values:: |
| * Memory transfer:: |
| * struct stat:: |
| * struct timeval:: |
| |
| |
| File: gdb.info, Node: Integral datatypes, Next: Pointer values, Up: Protocol specific representation of datatypes |
| |
| Integral datatypes |
| .................. |
| |
| The integral datatypes used in the system calls are `int', `unsigned |
| int', `long', `unsigned long', `mode_t', and `time_t'. |
| |
| `int', `unsigned int', `mode_t' and `time_t' are implemented as 32 |
| bit values in this protocol. |
| |
| `long' and `unsigned long' are implemented as 64 bit types. |
| |
| *Note Limits::, for corresponding MIN and MAX values (similar to |
| those in `limits.h') to allow range checking on host and target. |
| |
| `time_t' datatypes are defined as seconds since the Epoch. |
| |
| All integral datatypes transferred as part of a memory read or write |
| of a structured datatype e.g. a `struct stat' have to be given in big |
| endian byte order. |
| |
| |
| File: gdb.info, Node: Pointer values, Next: Memory transfer, Prev: Integral datatypes, Up: Protocol specific representation of datatypes |
| |
| Pointer values |
| .............. |
| |
| Pointers to target data are transmitted as they are. An exception is |
| made for pointers to buffers for which the length isn't transmitted as |
| part of the function call, namely strings. Strings are transmitted as |
| a pointer/length pair, both as hex values, e.g. |
| |
| `1aaf/12' |
| |
| which is a pointer to data of length 18 bytes at position 0x1aaf. The |
| length is defined as the full string length in bytes, including the |
| trailing null byte. For example, the string `"hello world"' at address |
| 0x123456 is transmitted as |
| |
| `123456/d' |
| |
| |
| File: gdb.info, Node: Memory transfer, Next: struct stat, Prev: Pointer values, Up: Protocol specific representation of datatypes |
| |
| Memory transfer |
| ............... |
| |
| Structured data which is transferred using a memory read or write (for |
| example, a `struct stat') is expected to be in a protocol specific |
| format with all scalar multibyte datatypes being big endian. |
| Translation to this representation needs to be done both by the target |
| before the `F' packet is sent, and by GDB before it transfers memory to |
| the target. Transferred pointers to structured data should point to |
| the already-coerced data at any time. |
| |
| |
| File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory transfer, Up: Protocol specific representation of datatypes |
| |
| struct stat |
| ........... |
| |
| The buffer of type `struct stat' used by the target and GDB is defined |
| as follows: |
| |
| struct stat { |
| unsigned int st_dev; /* device */ |
| unsigned int st_ino; /* inode */ |
| mode_t st_mode; /* protection */ |
| unsigned int st_nlink; /* number of hard links */ |
| unsigned int st_uid; /* user ID of owner */ |
| unsigned int st_gid; /* group ID of owner */ |
| unsigned int st_rdev; /* device type (if inode device) */ |
| unsigned long st_size; /* total size, in bytes */ |
| unsigned long st_blksize; /* blocksize for filesystem I/O */ |
| unsigned long st_blocks; /* number of blocks allocated */ |
| time_t st_atime; /* time of last access */ |
| time_t st_mtime; /* time of last modification */ |
| time_t st_ctime; /* time of last change */ |
| }; |
| |
| The integral datatypes conform to the definitions given in the |
| appropriate section (see *Note Integral datatypes::, for details) so |
| this structure is of size 64 bytes. |
| |
| The values of several fields have a restricted meaning and/or range |
| of values. |
| |
| `st_dev' |
| A value of 0 represents a file, 1 the console. |
| |
| `st_ino' |
| No valid meaning for the target. Transmitted unchanged. |
| |
| `st_mode' |
| Valid mode bits are described in *Note Constants::. Any other |
| bits have currently no meaning for the target. |
| |
| `st_uid' |
| `st_gid' |
| `st_rdev' |
| No valid meaning for the target. Transmitted unchanged. |
| |
| `st_atime' |
| `st_mtime' |
| `st_ctime' |
| These values have a host and file system dependent accuracy. |
| Especially on Windows hosts, the file system may not support exact |
| timing values. |
| |
| The target gets a `struct stat' of the above representation and is |
| responsible for coercing it to the target representation before |
| continuing. |
| |
| Note that due to size differences between the host, target, and |
| protocol representations of `struct stat' members, these members could |
| eventually get truncated on the target. |
| |
| |
| File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol specific representation of datatypes |
| |
| struct timeval |
| .............. |
| |
| The buffer of type `struct timeval' used by the File-I/O protocol is |
| defined as follows: |
| |
| struct timeval { |
| time_t tv_sec; /* second */ |
| long tv_usec; /* microsecond */ |
| }; |
| |
| The integral datatypes conform to the definitions given in the |
| appropriate section (see *Note Integral datatypes::, for details) so |
| this structure is of size 8 bytes. |
| |
| |
| File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol specific representation of datatypes, Up: File-I/O remote protocol extension |
| |
| D.9.9 Constants |
| --------------- |
| |
| The following values are used for the constants inside of the protocol. |
| GDB and target are responsible for translating these values before and |
| after the call as needed. |
| |
| * Menu: |
| |
| * Open flags:: |
| * mode_t values:: |
| * Errno values:: |
| * Lseek flags:: |
| * Limits:: |
| |
| |
| File: gdb.info, Node: Open flags, Next: mode_t values, Up: Constants |
| |
| Open flags |
| .......... |
| |
| All values are given in hexadecimal representation. |
| |
| O_RDONLY 0x0 |
| O_WRONLY 0x1 |
| O_RDWR 0x2 |
| O_APPEND 0x8 |
| O_CREAT 0x200 |
| O_TRUNC 0x400 |
| O_EXCL 0x800 |
| |
| |
| File: gdb.info, Node: mode_t values, Next: Errno values, Prev: Open flags, Up: Constants |
| |
| mode_t values |
| ............. |
| |
| All values are given in octal representation. |
| |
| S_IFREG 0100000 |
| S_IFDIR 040000 |
| S_IRUSR 0400 |
| S_IWUSR 0200 |
| S_IXUSR 0100 |
| S_IRGRP 040 |
| S_IWGRP 020 |
| S_IXGRP 010 |
| S_IROTH 04 |
| S_IWOTH 02 |
| S_IXOTH 01 |
| |
| |
| File: gdb.info, Node: Errno values, Next: Lseek flags, Prev: mode_t values, Up: Constants |
| |
| Errno values |
| ............ |
| |
| All values are given in decimal representation. |
| |
| EPERM 1 |
| ENOENT 2 |
| EINTR 4 |
| EBADF 9 |
| EACCES 13 |
| EFAULT 14 |
| EBUSY 16 |
| EEXIST 17 |
| ENODEV 19 |
| ENOTDIR 20 |
| EISDIR 21 |
| EINVAL 22 |
| ENFILE 23 |
| EMFILE 24 |
| EFBIG 27 |
| ENOSPC 28 |
| ESPIPE 29 |
| EROFS 30 |
| ENAMETOOLONG 91 |
| EUNKNOWN 9999 |
| |
| `EUNKNOWN' is used as a fallback error value if a host system returns |
| any error value not in the list of supported error numbers. |
| |
| |
| File: gdb.info, Node: Lseek flags, Next: Limits, Prev: Errno values, Up: Constants |
| |
| Lseek flags |
| ........... |
| |
| SEEK_SET 0 |
| SEEK_CUR 1 |
| SEEK_END 2 |
| |
| |
| File: gdb.info, Node: Limits, Prev: Lseek flags, Up: Constants |
| |
| Limits |
| ...... |
| |
| All values are given in decimal representation. |
| |
| INT_MIN -2147483648 |
| INT_MAX 2147483647 |
| UINT_MAX 4294967295 |
| LONG_MIN -9223372036854775808 |
| LONG_MAX 9223372036854775807 |
| ULONG_MAX 18446744073709551615 |
| |
| |
| File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O remote protocol extension |
| |
| D.9.10 File-I/O Examples |
| ------------------------ |
| |
| Example sequence of a write call, file descriptor 3, buffer is at target |
| address 0x1234, 6 bytes should be written: |
| |
| <- `Fwrite,3,1234,6' |
| _request memory read from target_ |
| -> `m1234,6' |
| <- XXXXXX |
| _return "6 bytes written"_ |
| -> `F6' |
| |
| Example sequence of a read call, file descriptor 3, buffer is at |
| target address 0x1234, 6 bytes should be read: |
| |
| <- `Fread,3,1234,6' |
| _request memory write to target_ |
| -> `X1234,6:XXXXXX' |
| _return "6 bytes read"_ |
| -> `F6' |
| |
| Example sequence of a read call, call fails on the host due to |
| invalid file descriptor (`EBADF'): |
| |
| <- `Fread,3,1234,6' |
| -> `F-1,9' |
| |
| Example sequence of a read call, user presses `Ctrl-c' before |
| syscall on host is called: |
| |
| <- `Fread,3,1234,6' |
| -> `F-1,4,C' |
| <- `T02' |
| |
| Example sequence of a read call, user presses `Ctrl-c' after syscall |
| on host is called: |
| |
| <- `Fread,3,1234,6' |
| -> `X1234,6:XXXXXX' |
| <- `T02' |
| |
| |
| File: gdb.info, Node: Memory map format, Prev: File-I/O remote protocol extension, Up: Remote Protocol |
| |
| D.10 Memory map format |
| ====================== |
| |
| To be able to write into flash memory, GDB needs to obtain a memory map |
| from the target. This section describes the format of the memory map. |
| |
| The memory map is obtained using the `qXfer:memory-map:read' (*note |
| qXfer memory map read::) packet and is an XML document that lists |
| memory regions. The top-level structure of the document is shown below: |
| |
| <?xml version="1.0"?> |
| <!DOCTYPE memory-map |
| PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" |
| "http://sourceware.org/gdb/gdb-memory-map.dtd"> |
| <memory-map> |
| region... |
| </memory-map> |
| |
| Each region can be either: |
| |
| * A region of RAM starting at ADDR and extending for LENGTH bytes |
| from there: |
| |
| <memory type="ram" start="ADDR" length="LENGTH"/> |
| |
| * A region of read-only memory: |
| |
| <memory type="rom" start="ADDR" length="LENGTH"/> |
| |
| * A region of flash memory, with erasure blocks BLOCKSIZE bytes in |
| length: |
| |
| <memory type="flash" start="ADDR" length="LENGTH"> |
| <property name="blocksize">BLOCKSIZE</property> |
| </memory> |
| |
| |
| Regions must not overlap. GDB assumes that areas of memory not |
| covered by the memory map are RAM, and uses the ordinary `M' and `X' |
| packets to write to addresses in such ranges. |
| |
| The formal DTD for memory map format is given below: |
| |
| <!-- ................................................... --> |
| <!-- Memory Map XML DTD ................................ --> |
| <!-- File: memory-map.dtd .............................. --> |
| <!-- .................................... .............. --> |
| <!-- memory-map.dtd --> |
| <!-- memory-map: Root element with versioning --> |
| <!ELEMENT memory-map (memory | property)> |
| <!ATTLIST memory-map version CDATA #FIXED "1.0.0"> |
| <!ELEMENT memory (property)> |
| <!-- memory: Specifies a memory region, |
| and its type, or device. --> |
| <!ATTLIST memory type CDATA #REQUIRED |
| start CDATA #REQUIRED |
| length CDATA #REQUIRED |
| device CDATA #IMPLIED> |
| <!-- property: Generic attribute tag --> |
| <!ELEMENT property (#PCDATA | property)*> |
| <!ATTLIST property name CDATA #REQUIRED> |
| |
| |
| File: gdb.info, Node: Agent Expressions, Next: Copying, Prev: Remote Protocol, Up: Top |
| |
| Appendix E The GDB Agent Expression Mechanism |
| ********************************************* |
| |
| In some applications, it is not feasable for the debugger to interrupt |
| the program's execution long enough for the developer to learn anything |
| helpful about its behavior. If the program's correctness depends on its |
| real-time behavior, delays introduced by a debugger might cause the |
| program to fail, even when the code itself is correct. It is useful to |
| be able to observe the program's behavior without interrupting it. |
| |
| Using GDB's `trace' and `collect' commands, the user can specify |
| locations in the program, and arbitrary expressions to evaluate when |
| those locations are reached. Later, using the `tfind' command, she can |
| examine the values those expressions had when the program hit the trace |
| points. The expressions may also denote objects in memory -- |
| structures or arrays, for example -- whose values GDB should record; |
| while visiting a particular tracepoint, the user may inspect those |
| objects as if they were in memory at that moment. However, because GDB |
| records these values without interacting with the user, it can do so |
| quickly and unobtrusively, hopefully not disturbing the program's |
| behavior. |
| |
| When GDB is debugging a remote target, the GDB "agent" code running |
| on the target computes the values of the expressions itself. To avoid |
| having a full symbolic expression evaluator on the agent, GDB translates |
| expressions in the source language into a simpler bytecode language, and |
| then sends the bytecode to the agent; the agent then executes the |
| bytecode, and records the values for GDB to retrieve later. |
| |
| The bytecode language is simple; there are forty-odd opcodes, the |
| bulk of which are the usual vocabulary of C operands (addition, |
| subtraction, shifts, and so on) and various sizes of literals and |
| memory reference operations. The bytecode interpreter operates |
| strictly on machine-level values -- various sizes of integers and |
| floating point numbers -- and requires no information about types or |
| symbols; thus, the interpreter's internal data structures are simple, |
| and each bytecode requires only a few native machine instructions to |
| implement it. The interpreter is small, and strict limits on the |
| memory and time required to evaluate an expression are easy to |
| determine, making it suitable for use by the debugging agent in |
| real-time applications. |
| |
| * Menu: |
| |
| * General Bytecode Design:: Overview of the interpreter. |
| * Bytecode Descriptions:: What each one does. |
| * Using Agent Expressions:: How agent expressions fit into the big picture. |
| * Varying Target Capabilities:: How to discover what the target can do. |
| * Tracing on Symmetrix:: Special info for implementation on EMC's |
| boxes. |
| * Rationale:: Why we did it this way. |
| |
| |
| File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions |
| |
| E.1 General Bytecode Design |
| =========================== |
| |
| The agent represents bytecode expressions as an array of bytes. Each |
| instruction is one byte long (thus the term "bytecode"). Some |
| instructions are followed by operand bytes; for example, the `goto' |
| instruction is followed by a destination for the jump. |
| |
| The bytecode interpreter is a stack-based machine; most instructions |
| pop their operands off the stack, perform some operation, and push the |
| result back on the stack for the next instruction to consume. Each |
| element of the stack may contain either a integer or a floating point |
| value; these values are as many bits wide as the largest integer that |
| can be directly manipulated in the source language. Stack elements |
| carry no record of their type; bytecode could push a value as an |
| integer, then pop it as a floating point value. However, GDB will not |
| generate code which does this. In C, one might define the type of a |
| stack element as follows: |
| union agent_val { |
| LONGEST l; |
| DOUBLEST d; |
| }; |
| where `LONGEST' and `DOUBLEST' are `typedef' names for the largest |
| integer and floating point types on the machine. |
| |
| By the time the bytecode interpreter reaches the end of the |
| expression, the value of the expression should be the only value left |
| on the stack. For tracing applications, `trace' bytecodes in the |
| expression will have recorded the necessary data, and the value on the |
| stack may be discarded. For other applications, like conditional |
| breakpoints, the value may be useful. |
| |
| Separate from the stack, the interpreter has two registers: |
| `pc' |
| The address of the next bytecode to execute. |
| |
| `start' |
| The address of the start of the bytecode expression, necessary for |
| interpreting the `goto' and `if_goto' instructions. |
| |
| Neither of these registers is directly visible to the bytecode |
| language itself, but they are useful for defining the meanings of the |
| bytecode operations. |
| |
| There are no instructions to perform side effects on the running |
| program, or call the program's functions; we assume that these |
| expressions are only used for unobtrusive debugging, not for patching |
| the running code. |
| |
| Most bytecode instructions do not distinguish between the various |
| sizes of values, and operate on full-width values; the upper bits of the |
| values are simply ignored, since they do not usually make a difference |
| to the value computed. The exceptions to this rule are: |
| memory reference instructions (`ref'N) |
| There are distinct instructions to fetch different word sizes from |
| memory. Once on the stack, however, the values are treated as |
| full-size integers. They may need to be sign-extended; the `ext' |
| instruction exists for this purpose. |
| |
| the sign-extension instruction (`ext' N) |
| These clearly need to know which portion of their operand is to be |
| extended to occupy the full length of the word. |
| |
| |
| If the interpreter is unable to evaluate an expression completely for |
| some reason (a memory location is inaccessible, or a divisor is zero, |
| for example), we say that interpretation "terminates with an error". |
| This means that the problem is reported back to the interpreter's caller |
| in some helpful way. In general, code using agent expressions should |
| assume that they may attempt to divide by zero, fetch arbitrary memory |
| locations, and misbehave in other ways. |
| |
| Even complicated C expressions compile to a few bytecode |
| instructions; for example, the expression `x + y * z' would typically |
| produce code like the following, assuming that `x' and `y' live in |
| registers, and `z' is a global variable holding a 32-bit `int': |
| reg 1 |
| reg 2 |
| const32 address of z |
| ref32 |
| ext 32 |
| mul |
| add |
| end |
| |
| In detail, these mean: |
| `reg 1' |
| Push the value of register 1 (presumably holding `x') onto the |
| stack. |
| |
| `reg 2' |
| Push the value of register 2 (holding `y'). |
| |
| `const32 address of z' |
| Push the address of `z' onto the stack. |
| |
| `ref32' |
| Fetch a 32-bit word from the address at the top of the stack; |
| replace the address on the stack with the value. Thus, we replace |
| the address of `z' with `z''s value. |
| |
| `ext 32' |
| Sign-extend the value on the top of the stack from 32 bits to full |
| length. This is necessary because `z' is a signed integer. |
| |
| `mul' |
| Pop the top two numbers on the stack, multiply them, and push their |
| product. Now the top of the stack contains the value of the |
| expression `y * z'. |
| |
| `add' |
| Pop the top two numbers, add them, and push the sum. Now the top |
| of the stack contains the value of `x + y * z'. |
| |
| `end' |
| Stop executing; the value left on the stack top is the value to be |
| recorded. |
| |
| |
| |
| File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions |
| |
| E.2 Bytecode Descriptions |
| ========================= |
| |
| Each bytecode description has the following form: |
| |
| `add' (0x02): A B => A+B |
| Pop the top two stack items, A and B, as integers; push their sum, |
| as an integer. |
| |
| |
| In this example, `add' is the name of the bytecode, and `(0x02)' is |
| the one-byte value used to encode the bytecode, in hexidecimal. The |
| phrase "A B => A+B" shows the stack before and after the bytecode |
| executes. Beforehand, the stack must contain at least two values, A |
| and B; since the top of the stack is to the right, B is on the top of |
| the stack, and A is underneath it. After execution, the bytecode will |
| have popped A and B from the stack, and replaced them with a single |
| value, A+B. There may be other values on the stack below those shown, |
| but the bytecode affects only those shown. |
| |
| Here is another example: |
| |
| `const8' (0x22) N: => N |
| Push the 8-bit integer constant N on the stack, without sign |
| extension. |
| |
| |
| In this example, the bytecode `const8' takes an operand N directly |
| from the bytecode stream; the operand follows the `const8' bytecode |
| itself. We write any such operands immediately after the name of the |
| bytecode, before the colon, and describe the exact encoding of the |
| operand in the bytecode stream in the body of the bytecode description. |
| |
| For the `const8' bytecode, there are no stack items given before the |
| =>; this simply means that the bytecode consumes no values from the |
| stack. If a bytecode consumes no values, or produces no values, the |
| list on either side of the => may be empty. |
| |
| If a value is written as A, B, or N, then the bytecode treats it as |
| an integer. If a value is written is ADDR, then the bytecode treats it |
| as an address. |
| |
| We do not fully describe the floating point operations here; although |
| this design can be extended in a clean way to handle floating point |
| values, they are not of immediate interest to the customer, so we avoid |
| describing them, to save time. |
| |
| `float' (0x01): => |
| Prefix for floating-point bytecodes. Not implemented yet. |
| |
| `add' (0x02): A B => A+B |
| Pop two integers from the stack, and push their sum, as an integer. |
| |
| `sub' (0x03): A B => A-B |
| Pop two integers from the stack, subtract the top value from the |
| next-to-top value, and push the difference. |
| |
| `mul' (0x04): A B => A*B |
| Pop two integers from the stack, multiply them, and push the |
| product on the stack. Note that, when one multiplies two N-bit |
| numbers yielding another N-bit number, it is irrelevant whether the |
| numbers are signed or not; the results are the same. |
| |
| `div_signed' (0x05): A B => A/B |
| Pop two signed integers from the stack; divide the next-to-top |
| value by the top value, and push the quotient. If the divisor is |
| zero, terminate with an error. |
| |
| `div_unsigned' (0x06): A B => A/B |
| Pop two unsigned integers from the stack; divide the next-to-top |
| value by the top value, and push the quotient. If the divisor is |
| zero, terminate with an error. |
| |
| `rem_signed' (0x07): A B => A MODULO B |
| Pop two signed integers from the stack; divide the next-to-top |
| value by the top value, and push the remainder. If the divisor is |
| zero, terminate with an error. |
| |
| `rem_unsigned' (0x08): A B => A MODULO B |
| Pop two unsigned integers from the stack; divide the next-to-top |
| value by the top value, and push the remainder. If the divisor is |
| zero, terminate with an error. |
| |
| `lsh' (0x09): A B => A<<B |
| Pop two integers from the stack; let A be the next-to-top value, |
| and B be the top value. Shift A left by B bits, and push the |
| result. |
| |
| `rsh_signed' (0x0a): A B => `(signed)'A>>B |
| Pop two integers from the stack; let A be the next-to-top value, |
| and B be the top value. Shift A right by B bits, inserting copies |
| of the top bit at the high end, and push the result. |
| |
| `rsh_unsigned' (0x0b): A B => A>>B |
| Pop two integers from the stack; let A be the next-to-top value, |
| and B be the top value. Shift A right by B bits, inserting zero |
| bits at the high end, and push the result. |
| |
| `log_not' (0x0e): A => !A |
| Pop an integer from the stack; if it is zero, push the value one; |
| otherwise, push the value zero. |
| |
| `bit_and' (0x0f): A B => A&B |
| Pop two integers from the stack, and push their bitwise `and'. |
| |
| `bit_or' (0x10): A B => A|B |
| Pop two integers from the stack, and push their bitwise `or'. |
| |
| `bit_xor' (0x11): A B => A^B |
| Pop two integers from the stack, and push their bitwise |
| exclusive-`or'. |
| |
| `bit_not' (0x12): A => ~A |
| Pop an integer from the stack, and push its bitwise complement. |
| |
| `equal' (0x13): A B => A=B |
| Pop two integers from the stack; if they are equal, push the value |
| one; otherwise, push the value zero. |
| |
| `less_signed' (0x14): A B => A<B |
| Pop two signed integers from the stack; if the next-to-top value |
| is less than the top value, push the value one; otherwise, push |
| the value zero. |
| |
| `less_unsigned' (0x15): A B => A<B |
| Pop two unsigned integers from the stack; if the next-to-top value |
| is less than the top value, push the value one; otherwise, push |
| the value zero. |
| |
| `ext' (0x16) N: A => A, sign-extended from N bits |
| Pop an unsigned value from the stack; treating it as an N-bit |
| twos-complement value, extend it to full length. This means that |
| all bits to the left of bit N-1 (where the least significant bit |
| is bit 0) are set to the value of bit N-1. Note that N may be |
| larger than or equal to the width of the stack elements of the |
| bytecode engine; in this case, the bytecode should have no effect. |
| |
| The number of source bits to preserve, N, is encoded as a single |
| byte unsigned integer following the `ext' bytecode. |
| |
| `zero_ext' (0x2a) N: A => A, zero-extended from N bits |
| Pop an unsigned value from the stack; zero all but the bottom N |
| bits. This means that all bits to the left of bit N-1 (where the |
| least significant bit is bit 0) are set to the value of bit N-1. |
| |
| The number of source bits to preserve, N, is encoded as a single |
| byte unsigned integer following the `zero_ext' bytecode. |
| |
| `ref8' (0x17): ADDR => A |
| `ref16' (0x18): ADDR => A |
| `ref32' (0x19): ADDR => A |
| `ref64' (0x1a): ADDR => A |
| Pop an address ADDR from the stack. For bytecode `ref'N, fetch an |
| N-bit value from ADDR, using the natural target endianness. Push |
| the fetched value as an unsigned integer. |
| |
| Note that ADDR may not be aligned in any particular way; the |
| `refN' bytecodes should operate correctly for any address. |
| |
| If attempting to access memory at ADDR would cause a processor |
| exception of some sort, terminate with an error. |
| |
| `ref_float' (0x1b): ADDR => D |
| `ref_double' (0x1c): ADDR => D |
| `ref_long_double' (0x1d): ADDR => D |
| `l_to_d' (0x1e): A => D |
| `d_to_l' (0x1f): D => A |
| Not implemented yet. |
| |
| `dup' (0x28): A => A A |
| Push another copy of the stack's top element. |
| |
| `swap' (0x2b): A B => B A |
| Exchange the top two items on the stack. |
| |
| `pop' (0x29): A => |
| Discard the top value on the stack. |
| |
| `if_goto' (0x20) OFFSET: A => |
| Pop an integer off the stack; if it is non-zero, branch to the |
| given offset in the bytecode string. Otherwise, continue to the |
| next instruction in the bytecode stream. In other words, if A is |
| non-zero, set the `pc' register to `start' + OFFSET. Thus, an |
| offset of zero denotes the beginning of the expression. |
| |
| The OFFSET is stored as a sixteen-bit unsigned value, stored |
| immediately following the `if_goto' bytecode. It is always stored |
| most significant byte first, regardless of the target's normal |
| endianness. The offset is not guaranteed to fall at any particular |
| alignment within the bytecode stream; thus, on machines where |
| fetching a 16-bit on an unaligned address raises an exception, you |
| should fetch the offset one byte at a time. |
| |
| `goto' (0x21) OFFSET: => |
| Branch unconditionally to OFFSET; in other words, set the `pc' |
| register to `start' + OFFSET. |
| |
| The offset is stored in the same way as for the `if_goto' bytecode. |
| |
| `const8' (0x22) N: => N |
| `const16' (0x23) N: => N |
| `const32' (0x24) N: => N |
| `const64' (0x25) N: => N |
| Push the integer constant N on the stack, without sign extension. |
| To produce a small negative value, push a small twos-complement |
| value, and then sign-extend it using the `ext' bytecode. |
| |
| The constant N is stored in the appropriate number of bytes |
| following the `const'B bytecode. The constant N is always stored |
| most significant byte first, regardless of the target's normal |
| endianness. The constant is not guaranteed to fall at any |
| particular alignment within the bytecode stream; thus, on machines |
| where fetching a 16-bit on an unaligned address raises an |
| exception, you should fetch N one byte at a time. |
| |
| `reg' (0x26) N: => A |
| Push the value of register number N, without sign extension. The |
| registers are numbered following GDB's conventions. |
| |
| The register number N is encoded as a 16-bit unsigned integer |
| immediately following the `reg' bytecode. It is always stored most |
| significant byte first, regardless of the target's normal |
| endianness. The register number is not guaranteed to fall at any |
| particular alignment within the bytecode stream; thus, on machines |
| where fetching a 16-bit on an unaligned address raises an |
| exception, you should fetch the register number one byte at a time. |
| |
| `trace' (0x0c): ADDR SIZE => |
| Record the contents of the SIZE bytes at ADDR in a trace buffer, |
| for later retrieval by GDB. |
| |
| `trace_quick' (0x0d) SIZE: ADDR => ADDR |
| Record the contents of the SIZE bytes at ADDR in a trace buffer, |
| for later retrieval by GDB. SIZE is a single byte unsigned |
| integer following the `trace' opcode. |
| |
| This bytecode is equivalent to the sequence `dup const8 SIZE |
| trace', but we provide it anyway to save space in bytecode strings. |
| |
| `trace16' (0x30) SIZE: ADDR => ADDR |
| Identical to trace_quick, except that SIZE is a 16-bit big-endian |
| unsigned integer, not a single byte. This should probably have |
| been named `trace_quick16', for consistency. |
| |
| `end' (0x27): => |
| Stop executing bytecode; the result should be the top element of |
| the stack. If the purpose of the expression was to compute an |
| lvalue or a range of memory, then the next-to-top of the stack is |
| the lvalue's address, and the top of the stack is the lvalue's |
| size, in bytes. |
| |
| |
| |
| File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions |
| |
| E.3 Using Agent Expressions |
| =========================== |
| |
| Here is a sketch of a full non-stop debugging cycle, showing how agent |
| expressions fit into the process. |
| |
| * The user selects trace points in the program's code at which GDB |
| should collect data. |
| |
| * The user specifies expressions to evaluate at each trace point. |
| These expressions may denote objects in memory, in which case |
| those objects' contents are recorded as the program runs, or |
| computed values, in which case the values themselves are recorded. |
| |
| * GDB transmits the tracepoints and their associated expressions to |
| the GDB agent, running on the debugging target. |
| |
| * The agent arranges to be notified when a trace point is hit. Note |
| that, on some systems, the target operating system is completely |
| responsible for collecting the data; see *Note Tracing on |
| Symmetrix::. |
| |
| * When execution on the target reaches a trace point, the agent |
| evaluates the expressions associated with that trace point, and |
| records the resulting values and memory ranges. |
| |
| * Later, when the user selects a given trace event and inspects the |
| objects and expression values recorded, GDB talks to the agent to |
| retrieve recorded data as necessary to meet the user's requests. |
| If the user asks to see an object whose contents have not been |
| recorded, GDB reports an error. |
| |
| |
| |
| File: gdb.info, Node: Varying Target Capabilities, Next: Tracing on Symmetrix, Prev: Using Agent Expressions, Up: Agent Expressions |
| |
| E.4 Varying Target Capabilities |
| =============================== |
| |
| Some targets don't support floating-point, and some would rather not |
| have to deal with `long long' operations. Also, different targets will |
| have different stack sizes, and different bytecode buffer lengths. |
| |
| Thus, GDB needs a way to ask the target about itself. We haven't |
| worked out the details yet, but in general, GDB should be able to send |
| the target a packet asking it to describe itself. The reply should be a |
| packet whose length is explicit, so we can add new information to the |
| packet in future revisions of the agent, without confusing old versions |
| of GDB, and it should contain a version number. It should contain at |
| least the following information: |
| |
| * whether floating point is supported |
| |
| * whether `long long' is supported |
| |
| * maximum acceptable size of bytecode stack |
| |
| * maximum acceptable length of bytecode expressions |
| |
| * which registers are actually available for collection |
| |
| * whether the target supports disabled tracepoints |
| |
| |
| |
| File: gdb.info, Node: Tracing on Symmetrix, Next: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions |
| |
| E.5 Tracing on Symmetrix |
| ======================== |
| |
| This section documents the API used by the GDB agent to collect data on |
| Symmetrix systems. |
| |
| Cygnus originally implemented these tracing features to help EMC |
| Corporation debug their Symmetrix high-availability disk drives. The |
| Symmetrix application code already includes substantial tracing |
| facilities; the GDB agent for the Symmetrix system uses those facilities |
| for its own data collection, via the API described here. |
| |
| -- Function: DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *FRAME, |
| char *ADDRESS, char **BUFFER, unsigned int *SIZE) |
| Search the trace frame FRAME for memory saved from ADDRESS. If |
| the memory is available, provide the address of the buffer holding |
| it; otherwise, provide the address of the next saved area. |
| |
| * If the memory at ADDRESS was saved in FRAME, set `*BUFFER' to |
| point to the buffer in which that memory was saved, set |
| `*SIZE' to the number of bytes from ADDRESS that are saved at |
| `*BUFFER', and return `OK_TARGET_RESPONSE'. (Clearly, in |
| this case, the function will always set `*SIZE' to a value |
| greater than zero.) |
| |
| * If FRAME does not record any memory at ADDRESS, set `*SIZE' |
| to the distance from ADDRESS to the start of the saved region |
| with the lowest address higher than ADDRESS. If there is no |
| memory saved from any higher address, set `*SIZE' to zero. |
| Return `NOT_FOUND_TARGET_RESPONSE'. |
| |
| These two possibilities allow the caller to either retrieve the |
| data, or walk the address space to the next saved area. |
| |
| This function allows the GDB agent to map the regions of memory |
| saved in a particular frame, and retrieve their contents efficiently. |
| |
| This function also provides a clean interface between the GDB agent |
| and the Symmetrix tracing structures, making it easier to adapt the GDB |
| agent to future versions of the Symmetrix system, and vice versa. This |
| function searches all data saved in FRAME, whether the data is there at |
| the request of a bytecode expression, or because it falls in one of the |
| format's memory ranges, or because it was saved from the top of the |
| stack. EMC can arbitrarily change and enhance the tracing mechanism, |
| but as long as this function works properly, all collected memory is |
| visible to GDB. |
| |
| The function itself is straightforward to implement. A single pass |
| over the trace frame's stack area, memory ranges, and expression blocks |
| can yield the address of the buffer (if the requested address was |
| saved), and also note the address of the next higher range of memory, |
| to be returned when the search fails. |
| |
| As an example, suppose the trace frame `f' has saved sixteen bytes |
| from address `0x8000' in a buffer at `0x1000', and thirty-two bytes |
| from address `0xc000' in a buffer at `0x1010'. Here are some sample |
| calls, and the effect each would have: |
| |
| `adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)' |
| This would set `buffer' to `0x1000', set `size' to sixteen, and |
| return `OK_TARGET_RESPONSE', since `f' saves sixteen bytes from |
| `0x8000' at `0x1000'. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)' |
| This would set `buffer' to `0x1004', set `size' to twelve, and |
| return `OK_TARGET_RESPONSE', since `f' saves the twelve bytes from |
| `0x8004' starting four bytes into the buffer at `0x1000'. This |
| shows that request addresses may fall in the middle of saved |
| areas; the function should return the address and size of the |
| remainder of the buffer. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)' |
| This would set `size' to `0x3f00' and return |
| `NOT_FOUND_TARGET_RESPONSE', since there is no memory saved in `f' |
| from the address `0x8100', and the next memory available is at |
| `0x8100 + 0x3f00', or `0xc000'. This shows that request addresses |
| may fall outside of all saved memory ranges; the function should |
| indicate the next saved area, if any. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)' |
| This would set `size' to `0x1000' and return |
| `NOT_FOUND_TARGET_RESPONSE', since the next saved memory is at |
| `0x7000 + 0x1000', or `0x8000'. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)' |
| This would set `size' to zero, and return |
| `NOT_FOUND_TARGET_RESPONSE'. This shows how the function tells the |
| caller that no further memory ranges have been saved. |
| |
| |
| As another example, here is a function which will print out the |
| addresses of all memory saved in the trace frame `frame' on the |
| Symmetrix INLINES console: |
| void |
| print_frame_addresses (FRAME_DEF *frame) |
| { |
| char *addr; |
| char *buffer; |
| unsigned long size; |
| |
| addr = 0; |
| for (;;) |
| { |
| /* Either find out how much memory we have here, or discover |
| where the next saved region is. */ |
| if (adbg_find_memory_in_frame (frame, addr, &buffer, &size) |
| == OK_TARGET_RESPONSE) |
| printp ("saved %x to %x\n", addr, addr + size); |
| if (size == 0) |
| break; |
| addr += size; |
| } |
| } |
| |
| Note that there is not necessarily any connection between the order |
| in which the data is saved in the trace frame, and the order in which |
| `adbg_find_memory_in_frame' will return those memory ranges. The code |
| above will always print the saved memory regions in order of increasing |
| address, while the underlying frame structure might store the data in a |
| random order. |
| |
| [[This section should cover the rest of the Symmetrix functions the |
| stub relies upon, too.]] |
| |
| |
| File: gdb.info, Node: Rationale, Prev: Tracing on Symmetrix, Up: Agent Expressions |
| |
| E.6 Rationale |
| ============= |
| |
| Some of the design decisions apparent above are arguable. |
| |
| What about stack overflow/underflow? |
| GDB should be able to query the target to discover its stack size. |
| Given that information, GDB can determine at translation time |
| whether a given expression will overflow the stack. But this spec |
| isn't about what kinds of error-checking GDB ought to do. |
| |
| Why are you doing everything in LONGEST? |
| Speed isn't important, but agent code size is; using LONGEST |
| brings in a bunch of support code to do things like division, etc. |
| So this is a serious concern. |
| |
| First, note that you don't need different bytecodes for different |
| operand sizes. You can generate code without _knowing_ how big the |
| stack elements actually are on the target. If the target only |
| supports 32-bit ints, and you don't send any 64-bit bytecodes, |
| everything just works. The observation here is that the MIPS and |
| the Alpha have only fixed-size registers, and you can still get |
| C's semantics even though most instructions only operate on |
| full-sized words. You just need to make sure everything is |
| properly sign-extended at the right times. So there is no need |
| for 32- and 64-bit variants of the bytecodes. Just implement |
| everything using the largest size you support. |
| |
| GDB should certainly check to see what sizes the target supports, |
| so the user can get an error earlier, rather than later. But this |
| information is not necessary for correctness. |
| |
| Why don't you have `>' or `<=' operators? |
| I want to keep the interpreter small, and we don't need them. We |
| can combine the `less_' opcodes with `log_not', and swap the order |
| of the operands, yielding all four asymmetrical comparison |
| operators. For example, `(x <= y)' is `! (x > y)', which is `! (y |
| < x)'. |
| |
| Why do you have `log_not'? |
| Why do you have `ext'? |
| Why do you have `zero_ext'? |
| These are all easily synthesized from other instructions, but I |
| expect them to be used frequently, and they're simple, so I |
| include them to keep bytecode strings short. |
| |
| `log_not' is equivalent to `const8 0 equal'; it's used in half the |
| relational operators. |
| |
| `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed', |
| where S is the size of the stack elements; it follows `refM' and |
| REG bytecodes when the value should be signed. See the next |
| bulleted item. |
| |
| `zero_ext N' is equivalent to `constM MASK log_and'; it's used |
| whenever we push the value of a register, because we can't assume |
| the upper bits of the register aren't garbage. |
| |
| Why not have sign-extending variants of the `ref' operators? |
| Because that would double the number of `ref' operators, and we |
| need the `ext' bytecode anyway for accessing bitfields. |
| |
| Why not have constant-address variants of the `ref' operators? |
| Because that would double the number of `ref' operators again, and |
| `const32 ADDRESS ref32' is only one byte longer. |
| |
| Why do the `refN' operators have to support unaligned fetches? |
| GDB will generate bytecode that fetches multi-byte values at |
| unaligned addresses whenever the executable's debugging |
| information tells it to. Furthermore, GDB does not know the value |
| the pointer will have when GDB generates the bytecode, so it |
| cannot determine whether a particular fetch will be aligned or not. |
| |
| In particular, structure bitfields may be several bytes long, but |
| follow no alignment rules; members of packed structures are not |
| necessarily aligned either. |
| |
| In general, there are many cases where unaligned references occur |
| in correct C code, either at the programmer's explicit request, or |
| at the compiler's discretion. Thus, it is simpler to make the GDB |
| agent bytecodes work correctly in all circumstances than to make |
| GDB guess in each case whether the compiler did the usual thing. |
| |
| Why are there no side-effecting operators? |
| Because our current client doesn't want them? That's a cheap |
| answer. I think the real answer is that I'm afraid of |
| implementing function calls. We should re-visit this issue after |
| the present contract is delivered. |
| |
| Why aren't the `goto' ops PC-relative? |
| The interpreter has the base address around anyway for PC bounds |
| checking, and it seemed simpler. |
| |
| Why is there only one offset size for the `goto' ops? |
| Offsets are currently sixteen bits. I'm not happy with this |
| situation either: |
| |
| Suppose we have multiple branch ops with different offset sizes. |
| As I generate code left-to-right, all my jumps are forward jumps |
| (there are no loops in expressions), so I never know the target |
| when I emit the jump opcode. Thus, I have to either always assume |
| the largest offset size, or do jump relaxation on the code after I |
| generate it, which seems like a big waste of time. |
| |
| I can imagine a reasonable expression being longer than 256 bytes. |
| I can't imagine one being longer than 64k. Thus, we need 16-bit |
| offsets. This kind of reasoning is so bogus, but relaxation is |
| pathetic. |
| |
| The other approach would be to generate code right-to-left. Then |
| I'd always know my offset size. That might be fun. |
| |
| Where is the function call bytecode? |
| When we add side-effects, we should add this. |
| |
| Why does the `reg' bytecode take a 16-bit register number? |
| Intel's IA-64 architecture has 128 general-purpose registers, and |
| 128 floating-point registers, and I'm sure it has some random |
| control registers. |
| |
| Why do we need `trace' and `trace_quick'? |
| Because GDB needs to record all the memory contents and registers |
| an expression touches. If the user wants to evaluate an expression |
| `x->y->z', the agent must record the values of `x' and `x->y' as |
| well as the value of `x->y->z'. |
| |
| Don't the `trace' bytecodes make the interpreter less general? |
| They do mean that the interpreter contains special-purpose code, |
| but that doesn't mean the interpreter can only be used for that |
| purpose. If an expression doesn't use the `trace' bytecodes, they |
| don't get in its way. |
| |
| Why doesn't `trace_quick' consume its arguments the way everything else does? |
| In general, you do want your operators to consume their arguments; |
| it's consistent, and generally reduces the amount of stack |
| rearrangement necessary. However, `trace_quick' is a kludge to |
| save space; it only exists so we needn't write `dup const8 SIZE |
| trace' before every memory reference. Therefore, it's okay for it |
| not to consume its arguments; it's meant for a specific context in |
| which we know exactly what it should do with the stack. If we're |
| going to have a kludge, it should be an effective kludge. |
| |
| Why does `trace16' exist? |
| That opcode was added by the customer that contracted Cygnus for |
| the data tracing work. I personally think it is unnecessary; |
| objects that large will be quite rare, so it is okay to use `dup |
| const16 SIZE trace' in those cases. |
| |
| Whatever we decide to do with `trace16', we should at least leave |
| opcode 0x30 reserved, to remain compatible with the customer who |
| added it. |
| |
| |