| This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo. |
| |
| Copyright (C) 1988-2020 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| * gdbserver: (gdb) Server. The GNU debugging server. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Tenth Edition, of 'Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 9.1. |
| |
| Copyright (C) 1988-2020 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI |
| |
| 27.17 GDB/MI Tracepoint Commands |
| ================================ |
| |
| The commands defined in this section implement MI support for |
| tracepoints. For detailed introduction, see *note Tracepoints::. |
| |
| The '-trace-find' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-find MODE [PARAMETERS...] |
| |
| Find a trace frame using criteria defined by MODE and PARAMETERS. |
| The following table lists permissible modes and their parameters. For |
| details of operation, see *note tfind::. |
| |
| 'none' |
| No parameters are required. Stops examining trace frames. |
| |
| 'frame-number' |
| An integer is required as parameter. Selects tracepoint frame with |
| that index. |
| |
| 'tracepoint-number' |
| An integer is required as parameter. Finds next trace frame that |
| corresponds to tracepoint with the specified number. |
| |
| 'pc' |
| An address is required as parameter. Finds next trace frame that |
| corresponds to any tracepoint at the specified address. |
| |
| 'pc-inside-range' |
| Two addresses are required as parameters. Finds next trace frame |
| that corresponds to a tracepoint at an address inside the specified |
| range. Both bounds are considered to be inside the range. |
| |
| 'pc-outside-range' |
| Two addresses are required as parameters. Finds next trace frame |
| that corresponds to a tracepoint at an address outside the |
| specified range. Both bounds are considered to be inside the |
| range. |
| |
| 'line' |
| Line specification is required as parameter. *Note Specify |
| Location::. Finds next trace frame that corresponds to a |
| tracepoint at the specified location. |
| |
| If 'none' was passed as MODE, the response does not have fields. |
| Otherwise, the response may have the following fields: |
| |
| 'found' |
| This field has either '0' or '1' as the value, depending on whether |
| a matching tracepoint was found. |
| |
| 'traceframe' |
| The index of the found traceframe. This field is present iff the |
| 'found' field has value of '1'. |
| |
| 'tracepoint' |
| The index of the found tracepoint. This field is present iff the |
| 'found' field has value of '1'. |
| |
| 'frame' |
| The information about the frame corresponding to the found trace |
| frame. This field is present only if a trace frame was found. |
| *Note GDB/MI Frame Information::, for description of this field. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tfind'. |
| |
| -trace-define-variable |
| ---------------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-define-variable NAME [ VALUE ] |
| |
| Create trace variable NAME if it does not exist. If VALUE is |
| specified, sets the initial value of the specified trace variable to |
| that value. Note that the NAME should start with the '$' character. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tvariable'. |
| |
| The '-trace-frame-collected' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -trace-frame-collected |
| [--var-print-values VAR_PVAL] |
| [--comp-print-values COMP_PVAL] |
| [--registers-format REGFORMAT] |
| [--memory-contents] |
| |
| This command returns the set of collected objects, register names, |
| trace state variable names, memory ranges and computed expressions that |
| have been collected at a particular trace frame. The optional |
| parameters to the command affect the output format in different ways. |
| See the output description table below for more details. |
| |
| The reported names can be used in the normal manner to create varobjs |
| and inspect the objects themselves. The items returned by this command |
| are categorized so that it is clear which is a variable, which is a |
| register, which is a trace state variable, which is a memory range and |
| which is a computed expression. |
| |
| For instance, if the actions were |
| collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 |
| collect *(int*)0xaf02bef0@40 |
| |
| the object collected in its entirety would be 'myVar'. The object |
| 'myArray' would be partially collected, because only the element at |
| index 'myIndex' would be collected. The remaining objects would be |
| computed expressions. |
| |
| An example output would be: |
| |
| (gdb) |
| -trace-frame-collected |
| ^done, |
| explicit-variables=[{name="myVar",value="1"}], |
| computed-expressions=[{name="myArray[myIndex]",value="0"}, |
| {name="myObj.field",value="0"}, |
| {name="myPtr->field",value="1"}, |
| {name="myCount + 2",value="3"}, |
| {name="$tvar1 + 1",value="43970027"}], |
| registers=[{number="0",value="0x7fe2c6e79ec8"}, |
| {number="1",value="0x0"}, |
| {number="2",value="0x4"}, |
| ... |
| {number="125",value="0x0"}], |
| tvars=[{name="$tvar1",current="43970026"}], |
| memory=[{address="0x0000000000602264",length="4"}, |
| {address="0x0000000000615bc0",length="4"}] |
| (gdb) |
| |
| Where: |
| |
| 'explicit-variables' |
| The set of objects that have been collected in their entirety (as |
| opposed to collecting just a few elements of an array or a few |
| struct members). For each object, its name and value are printed. |
| The '--var-print-values' option affects how or whether the value |
| field is output. If VAR_PVAL is 0, then print only the names; if |
| it is 1, print also their values; and if it is 2, print the name, |
| type and value for simple data types, and the name and type for |
| arrays, structures and unions. |
| |
| 'computed-expressions' |
| The set of computed expressions that have been collected at the |
| current trace frame. The '--comp-print-values' option affects this |
| set like the '--var-print-values' option affects the |
| 'explicit-variables' set. See above. |
| |
| 'registers' |
| The registers that have been collected at the current trace frame. |
| For each register collected, the name and current value are |
| returned. The value is formatted according to the |
| '--registers-format' option. See the '-data-list-register-values' |
| command for a list of the allowed formats. The default is 'x'. |
| |
| 'tvars' |
| The trace state variables that have been collected at the current |
| trace frame. For each trace state variable collected, the name and |
| current value are returned. |
| |
| 'memory' |
| The set of memory ranges that have been collected at the current |
| trace frame. Its content is a list of tuples. Each tuple |
| represents a collected memory range and has the following fields: |
| |
| 'address' |
| The start address of the memory range, as hexadecimal literal. |
| |
| 'length' |
| The length of the memory range, as decimal literal. |
| |
| 'contents' |
| The contents of the memory block, in hex. This field is only |
| present if the '--memory-contents' option is specified. |
| |
| GDB Command |
| ........... |
| |
| There is no corresponding GDB command. |
| |
| Example |
| ....... |
| |
| -trace-list-variables |
| --------------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-list-variables |
| |
| Return a table of all defined trace variables. Each element of the |
| table has the following fields: |
| |
| 'name' |
| The name of the trace variable. This field is always present. |
| |
| 'initial' |
| The initial value. This is a 64-bit signed integer. This field is |
| always present. |
| |
| 'current' |
| The value the trace variable has at the moment. This is a 64-bit |
| signed integer. This field is absent iff current value is not |
| defined, for example if the trace was never run, or is presently |
| running. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tvariables'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -trace-list-variables |
| ^done,trace-variables={nr_rows="1",nr_cols="3", |
| hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, |
| {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, |
| {width="11",alignment="-1",col_name="current",colhdr="Current"}], |
| body=[variable={name="$trace_timestamp",initial="0"} |
| variable={name="$foo",initial="10",current="15"}]} |
| (gdb) |
| |
| -trace-save |
| ----------- |
| |
| Synopsis |
| ........ |
| |
| -trace-save [ -r ] [ -ctf ] FILENAME |
| |
| Saves the collected trace data to FILENAME. Without the '-r' option, |
| the data is downloaded from the target and saved in a local file. With |
| the '-r' option the target is asked to perform the save. |
| |
| By default, this command will save the trace in the tfile format. |
| You can supply the optional '-ctf' argument to save it the CTF format. |
| See *note Trace Files:: for more information about CTF. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tsave'. |
| |
| -trace-start |
| ------------ |
| |
| Synopsis |
| ........ |
| |
| -trace-start |
| |
| Starts a tracing experiment. The result of this command does not |
| have any fields. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tstart'. |
| |
| -trace-status |
| ------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-status |
| |
| Obtains the status of a tracing experiment. The result may include |
| the following fields: |
| |
| 'supported' |
| May have a value of either '0', when no tracing operations are |
| supported, '1', when all tracing operations are supported, or |
| 'file' when examining trace file. In the latter case, examining of |
| trace frame is possible but new tracing experiement cannot be |
| started. This field is always present. |
| |
| 'running' |
| May have a value of either '0' or '1' depending on whether tracing |
| experiement is in progress on target. This field is present if |
| 'supported' field is not '0'. |
| |
| 'stop-reason' |
| Report the reason why the tracing was stopped last time. This |
| field may be absent iff tracing was never stopped on target yet. |
| The value of 'request' means the tracing was stopped as result of |
| the '-trace-stop' command. The value of 'overflow' means the |
| tracing buffer is full. The value of 'disconnection' means tracing |
| was automatically stopped when GDB has disconnected. The value of |
| 'passcount' means tracing was stopped when a tracepoint was passed |
| a maximal number of times for that tracepoint. This field is |
| present if 'supported' field is not '0'. |
| |
| 'stopping-tracepoint' |
| The number of tracepoint whose passcount as exceeded. This field |
| is present iff the 'stop-reason' field has the value of |
| 'passcount'. |
| |
| 'frames' |
| 'frames-created' |
| The 'frames' field is a count of the total number of trace frames |
| in the trace buffer, while 'frames-created' is the total created |
| during the run, including ones that were discarded, such as when a |
| circular trace buffer filled up. Both fields are optional. |
| |
| 'buffer-size' |
| 'buffer-free' |
| These fields tell the current size of the tracing buffer and the |
| remaining space. These fields are optional. |
| |
| 'circular' |
| The value of the circular trace buffer flag. '1' means that the |
| trace buffer is circular and old trace frames will be discarded if |
| necessary to make room, '0' means that the trace buffer is linear |
| and may fill up. |
| |
| 'disconnected' |
| The value of the disconnected tracing flag. '1' means that tracing |
| will continue after GDB disconnects, '0' means that the trace run |
| will stop. |
| |
| 'trace-file' |
| The filename of the trace file being examined. This field is |
| optional, and only present when examining a trace file. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tstatus'. |
| |
| -trace-stop |
| ----------- |
| |
| Synopsis |
| ........ |
| |
| -trace-stop |
| |
| Stops a tracing experiment. The result of this command has the same |
| fields as '-trace-status', except that the 'supported' and 'running' |
| fields are not output. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'tstop'. |
| |
| |
| File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI |
| |
| 27.18 GDB/MI Symbol Query Commands |
| ================================== |
| |
| The '-symbol-info-functions' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-functions [--include-nondebug] |
| [--type TYPE_REGEXP] |
| [--name NAME_REGEXP] |
| [--max-results LIMIT] |
| |
| Return a list containing the names and types for all global functions |
| taken from the debug information. The functions are grouped by source |
| file, and shown with the line number on which each function is defined. |
| |
| The '--include-nondebug' option causes the output to include code |
| symbols from the symbol table. |
| |
| The options '--type' and '--name' allow the symbols returned to be |
| filtered based on either the name of the function, or the type signature |
| of the function. |
| |
| The option '--max-results' restricts the command to return no more |
| than LIMIT results. If exactly LIMIT results are returned then there |
| might be additional results available if a higher limit is used. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info functions'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-info-functions |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="36", name="f4", type="void (int *)", |
| description="void f4(int *);"}, |
| {line="42", name="main", type="int ()", |
| description="int main();"}, |
| {line="30", name="f1", type="my_int_t (int, int)", |
| description="static my_int_t f1(int, int);"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="33", name="f2", type="float (another_float_t)", |
| description="float f2(another_float_t);"}, |
| {line="39", name="f3", type="int (another_int_t)", |
| description="int f3(another_int_t);"}, |
| {line="27", name="f1", type="another_float_t (int)", |
| description="static another_float_t f1(int);"}]}]} |
| (gdb) |
| -symbol-info-functions --name f1 |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="30", name="f1", type="my_int_t (int, int)", |
| description="static my_int_t f1(int, int);"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="27", name="f1", type="another_float_t (int)", |
| description="static another_float_t f1(int);"}]}]} |
| (gdb) |
| -symbol-info-functions --type void |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="36", name="f4", type="void (int *)", |
| description="void f4(int *);"}]}]} |
| (gdb) |
| -symbol-info-functions --include-nondebug |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="36", name="f4", type="void (int *)", |
| description="void f4(int *);"}, |
| {line="42", name="main", type="int ()", |
| description="int main();"}, |
| {line="30", name="f1", type="my_int_t (int, int)", |
| description="static my_int_t f1(int, int);"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="33", name="f2", type="float (another_float_t)", |
| description="float f2(another_float_t);"}, |
| {line="39", name="f3", type="int (another_int_t)", |
| description="int f3(another_int_t);"}, |
| {line="27", name="f1", type="another_float_t (int)", |
| description="static another_float_t f1(int);"}]}], |
| nondebug= |
| [{address="0x0000000000400398",name="_init"}, |
| {address="0x00000000004003b0",name="_start"}, |
| ... |
| ]} |
| |
| The '-symbol-info-module-functions' Command |
| ------------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-module-functions [--module MODULE_REGEXP] |
| [--name NAME_REGEXP] |
| [--type TYPE_REGEXP] |
| |
| Return a list containing the names of all known functions within all |
| know Fortran modules. The functions are grouped by source file and |
| containing module, and shown with the line number on which each function |
| is defined. |
| |
| The option '--module' only returns results for modules matching |
| MODULE_REGEXP. The option '--name' only returns functions whose name |
| matches NAME_REGEXP, and '--type' only returns functions whose type |
| matches TYPE_REGEXP. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info module functions'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-info-module-functions |
| ^done,symbols= |
| [{module="mod1", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| symbols=[{line="21",name="mod1::check_all",type="void (void)", |
| description="void mod1::check_all(void);"}]}]}, |
| {module="mod2", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| symbols=[{line="30",name="mod2::check_var_i",type="void (void)", |
| description="void mod2::check_var_i(void);"}]}]}, |
| {module="mod3", |
| files=[{filename="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="21",name="mod3::check_all",type="void (void)", |
| description="void mod3::check_all(void);"}, |
| {line="27",name="mod3::check_mod2",type="void (void)", |
| description="void mod3::check_mod2(void);"}]}]}, |
| {module="modmany", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="35",name="modmany::check_some",type="void (void)", |
| description="void modmany::check_some(void);"}]}]}, |
| {module="moduse", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="44",name="moduse::check_all",type="void (void)", |
| description="void moduse::check_all(void);"}, |
| {line="49",name="moduse::check_var_x",type="void (void)", |
| description="void moduse::check_var_x(void);"}]}]}] |
| |
| The '-symbol-info-module-variables' Command |
| ------------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-module-variables [--module MODULE_REGEXP] |
| [--name NAME_REGEXP] |
| [--type TYPE_REGEXP] |
| |
| Return a list containing the names of all known variables within all |
| know Fortran modules. The variables are grouped by source file and |
| containing module, and shown with the line number on which each variable |
| is defined. |
| |
| The option '--module' only returns results for modules matching |
| MODULE_REGEXP. The option '--name' only returns variables whose name |
| matches NAME_REGEXP, and '--type' only returns variables whose type |
| matches TYPE_REGEXP. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info module variables'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-info-module-variables |
| ^done,symbols= |
| [{module="mod1", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| symbols=[{line="18",name="mod1::var_const",type="integer(kind=4)", |
| description="integer(kind=4) mod1::var_const;"}, |
| {line="17",name="mod1::var_i",type="integer(kind=4)", |
| description="integer(kind=4) mod1::var_i;"}]}]}, |
| {module="mod2", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| symbols=[{line="28",name="mod2::var_i",type="integer(kind=4)", |
| description="integer(kind=4) mod2::var_i;"}]}]}, |
| {module="mod3", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="18",name="mod3::mod1",type="integer(kind=4)", |
| description="integer(kind=4) mod3::mod1;"}, |
| {line="17",name="mod3::mod2",type="integer(kind=4)", |
| description="integer(kind=4) mod3::mod2;"}, |
| {line="19",name="mod3::var_i",type="integer(kind=4)", |
| description="integer(kind=4) mod3::var_i;"}]}]}, |
| {module="modmany", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="33",name="modmany::var_a",type="integer(kind=4)", |
| description="integer(kind=4) modmany::var_a;"}, |
| {line="33",name="modmany::var_b",type="integer(kind=4)", |
| description="integer(kind=4) modmany::var_b;"}, |
| {line="33",name="modmany::var_c",type="integer(kind=4)", |
| description="integer(kind=4) modmany::var_c;"}, |
| {line="33",name="modmany::var_i",type="integer(kind=4)", |
| description="integer(kind=4) modmany::var_i;"}]}]}, |
| {module="moduse", |
| files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="42",name="moduse::var_x",type="integer(kind=4)", |
| description="integer(kind=4) moduse::var_x;"}, |
| {line="42",name="moduse::var_y",type="integer(kind=4)", |
| description="integer(kind=4) moduse::var_y;"}]}]}] |
| |
| The '-symbol-info-modules' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-modules [--name NAME_REGEXP] |
| [--max-results LIMIT] |
| |
| |
| Return a list containing the names of all known Fortran modules. The |
| modules are grouped by source file, and shown with the line number on |
| which each modules is defined. |
| |
| The option '--name' allows the modules returned to be filtered based |
| the name of the module. |
| |
| The option '--max-results' restricts the command to return no more |
| than LIMIT results. If exactly LIMIT results are returned then there |
| might be additional results available if a higher limit is used. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info modules'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-info-modules |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| symbols=[{line="16",name="mod1"}, |
| {line="22",name="mod2"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="16",name="mod3"}, |
| {line="22",name="modmany"}, |
| {line="26",name="moduse"}]}]} |
| (gdb) |
| -symbol-info-modules --name mod[123] |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", |
| symbols=[{line="16",name="mod1"}, |
| {line="22",name="mod2"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", |
| symbols=[{line="16",name="mod3"}]}]} |
| |
| The '-symbol-info-types' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-types [--name NAME_REGEXP] |
| [--max-results LIMIT] |
| |
| |
| Return a list of all defined types. The types are grouped by source |
| file, and shown with the line number on which each user defined type is |
| defined. Some base types are not defined in the source code but are |
| added to the debug information by the compiler, for example 'int', |
| 'float', etc.; these types do not have an associated line number. |
| |
| The option '--name' allows the list of types returned to be filtered |
| by name. |
| |
| The option '--max-results' restricts the command to return no more |
| than LIMIT results. If exactly LIMIT results are returned then there |
| might be additional results available if a higher limit is used. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info types'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-info-types |
| ^done,symbols= |
| {debug= |
| [{filename="gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{name="float"}, |
| {name="int"}, |
| {line="27",name="typedef int my_int_t;"}]}, |
| {filename="gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="24",name="typedef float another_float_t;"}, |
| {line="23",name="typedef int another_int_t;"}, |
| {name="float"}, |
| {name="int"}]}]} |
| (gdb) |
| -symbol-info-types --name _int_ |
| ^done,symbols= |
| {debug= |
| [{filename="gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="27",name="typedef int my_int_t;"}]}, |
| {filename="gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="23",name="typedef int another_int_t;"}]}]} |
| |
| The '-symbol-info-variables' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-variables [--include-nondebug] |
| [--type TYPE_REGEXP] |
| [--name NAME_REGEXP] |
| [--max-results LIMIT] |
| |
| |
| Return a list containing the names and types for all global variables |
| taken from the debug information. The variables are grouped by source |
| file, and shown with the line number on which each variable is defined. |
| |
| The '--include-nondebug' option causes the output to include data |
| symbols from the symbol table. |
| |
| The options '--type' and '--name' allow the symbols returned to be |
| filtered based on either the name of the variable, or the type of the |
| variable. |
| |
| The option '--max-results' restricts the command to return no more |
| than LIMIT results. If exactly LIMIT results are returned then there |
| might be additional results available if a higher limit is used. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info variables'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-info-variables |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="25",name="global_f1",type="float", |
| description="static float global_f1;"}, |
| {line="24",name="global_i1",type="int", |
| description="static int global_i1;"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="21",name="global_f2",type="int", |
| description="int global_f2;"}, |
| {line="20",name="global_i2",type="int", |
| description="int global_i2;"}, |
| {line="19",name="global_f1",type="float", |
| description="static float global_f1;"}, |
| {line="18",name="global_i1",type="int", |
| description="static int global_i1;"}]}]} |
| (gdb) |
| -symbol-info-variables --name f1 |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="25",name="global_f1",type="float", |
| description="static float global_f1;"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="19",name="global_f1",type="float", |
| description="static float global_f1;"}]}]} |
| (gdb) |
| -symbol-info-variables --type float |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="25",name="global_f1",type="float", |
| description="static float global_f1;"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="19",name="global_f1",type="float", |
| description="static float global_f1;"}]}]} |
| (gdb) |
| -symbol-info-variables --include-nondebug |
| ^done,symbols= |
| {debug= |
| [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", |
| symbols=[{line="25",name="global_f1",type="float", |
| description="static float global_f1;"}, |
| {line="24",name="global_i1",type="int", |
| description="static int global_i1;"}]}, |
| {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", |
| symbols=[{line="21",name="global_f2",type="int", |
| description="int global_f2;"}, |
| {line="20",name="global_i2",type="int", |
| description="int global_i2;"}, |
| {line="19",name="global_f1",type="float", |
| description="static float global_f1;"}, |
| {line="18",name="global_i1",type="int", |
| description="static int global_i1;"}]}], |
| nondebug= |
| [{address="0x00000000004005d0",name="_IO_stdin_used"}, |
| {address="0x00000000004005d8",name="__dso_handle"} |
| ... |
| ]} |
| |
| The '-symbol-list-lines' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-lines FILENAME |
| |
| Print the list of lines that contain code and their associated |
| program addresses for the given source filename. The entries are sorted |
| in ascending PC order. |
| |
| GDB Command |
| ........... |
| |
| There is no corresponding GDB command. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-list-lines basics.c |
| ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI |
| |
| 27.19 GDB/MI File Commands |
| ========================== |
| |
| This section describes the GDB/MI commands to specify executable file |
| names and to read in and obtain symbol table information. |
| |
| The '-file-exec-and-symbols' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -file-exec-and-symbols FILE |
| |
| Specify the executable file to be debugged. This file is the one |
| from which the symbol table is also read. If no file is specified, the |
| command clears the executable and symbol information. If breakpoints |
| are set when using this command with no arguments, GDB will produce |
| error messages. Otherwise, no output is produced, except a completion |
| notification. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'file'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| |
| The '-file-exec-file' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-exec-file FILE |
| |
| Specify the executable file to be debugged. Unlike |
| '-file-exec-and-symbols', the symbol table is _not_ read from this file. |
| If used without argument, GDB clears the information about the |
| executable file. No output is produced, except a completion |
| notification. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'exec-file'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| |
| The '-file-list-exec-source-file' Command |
| ----------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-exec-source-file |
| |
| List the line number, the current source file, and the absolute path |
| to the current source file for the current executable. The macro |
| information field has a value of '1' or '0' depending on whether or not |
| the file includes preprocessor macro information. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is 'info source' |
| |
| Example |
| ....... |
| |
| (gdb) |
| 123-file-list-exec-source-file |
| 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" |
| (gdb) |
| |
| The '-file-list-exec-source-files' Command |
| ------------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -file-list-exec-source-files |
| |
| List the source files for the current executable. |
| |
| It will always output both the filename and fullname (absolute file |
| name) of a source file. |
| |
| 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 [ REGEXP ] |
| |
| List the shared libraries in the program. With a regular expression |
| REGEXP, only those libraries whose names match REGEXP are listed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info shared'. The fields have a |
| similar meaning to the '=library-loaded' notification. The 'ranges' |
| field specifies the multiple segments belonging to this library. Each |
| range has the following fields: |
| |
| 'from' |
| The address defining the inclusive lower bound of the segment. |
| 'to' |
| The address defining the exclusive upper bound of the segment. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-list-exec-source-files |
| ^done,shared-libraries=[ |
| {id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[{from="0x72815989",to="0x728162c0"}]}, |
| {id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[{from="0x76ee48c0",to="0x76ee9160"}]}] |
| (gdb) |
| |
| The '-file-symbol-file' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-symbol-file FILE |
| |
| Read symbol table info from the specified FILE argument. When used |
| without arguments, clears GDB's symbol table info. No output is |
| produced, except for a completion notification. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'symbol-file'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI |
| |
| 27.20 GDB/MI Target Manipulation Commands |
| ========================================= |
| |
| The '-target-attach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-attach PID | GID | FILE |
| |
| Attach to a process PID or a file FILE outside of GDB, or a thread |
| group GID. If attaching to a thread group, the id previously returned |
| by '-list-thread-groups --available' must be used. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'attach'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-attach 34 |
| =thread-created,id="1" |
| *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} |
| ^done |
| (gdb) |
| |
| The '-target-detach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-detach [ PID | GID ] |
| |
| Detach from the remote target which normally resumes its execution. |
| If either PID or GID is specified, detaches from either the specified |
| process, or specified thread group. There's no output. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'detach'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-detach |
| ^done |
| (gdb) |
| |
| The '-target-disconnect' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-disconnect |
| |
| Disconnect from the remote target. There's no output and the target |
| is generally not resumed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'disconnect'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-disconnect |
| ^done |
| (gdb) |
| |
| The '-target-download' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-download |
| |
| Loads the executable onto the remote target. It prints out an update |
| message every half second, which includes the fields: |
| |
| 'section' |
| The name of the section. |
| 'section-sent' |
| The size of what has been sent so far for that section. |
| 'section-size' |
| The size of the section. |
| 'total-sent' |
| The total size of what was sent so far (the current and the |
| previous sections). |
| 'total-size' |
| The size of the overall executable to download. |
| |
| Each message is sent as status record (*note GDB/MI Output Syntax: |
| GDB/MI Output Syntax.). |
| |
| In addition, it prints the name and size of the sections, as they are |
| downloaded. These messages include the following fields: |
| |
| 'section' |
| The name of the section. |
| 'section-size' |
| The size of the section. |
| 'total-size' |
| The size of the overall executable to download. |
| |
| At the end, a summary is printed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'load'. |
| |
| Example |
| ....... |
| |
| Note: each status message appears on a single line. Here the messages |
| have been broken down so that they can fit onto a page. |
| |
| (gdb) |
| -target-download |
| +download,{section=".text",section-size="6668",total-size="9880"} |
| +download,{section=".text",section-sent="512",section-size="6668", |
| total-sent="512",total-size="9880"} |
| +download,{section=".text",section-sent="1024",section-size="6668", |
| total-sent="1024",total-size="9880"} |
| +download,{section=".text",section-sent="1536",section-size="6668", |
| total-sent="1536",total-size="9880"} |
| +download,{section=".text",section-sent="2048",section-size="6668", |
| total-sent="2048",total-size="9880"} |
| +download,{section=".text",section-sent="2560",section-size="6668", |
| total-sent="2560",total-size="9880"} |
| +download,{section=".text",section-sent="3072",section-size="6668", |
| total-sent="3072",total-size="9880"} |
| +download,{section=".text",section-sent="3584",section-size="6668", |
| total-sent="3584",total-size="9880"} |
| +download,{section=".text",section-sent="4096",section-size="6668", |
| total-sent="4096",total-size="9880"} |
| +download,{section=".text",section-sent="4608",section-size="6668", |
| total-sent="4608",total-size="9880"} |
| +download,{section=".text",section-sent="5120",section-size="6668", |
| total-sent="5120",total-size="9880"} |
| +download,{section=".text",section-sent="5632",section-size="6668", |
| total-sent="5632",total-size="9880"} |
| +download,{section=".text",section-sent="6144",section-size="6668", |
| total-sent="6144",total-size="9880"} |
| +download,{section=".text",section-sent="6656",section-size="6668", |
| total-sent="6656",total-size="9880"} |
| +download,{section=".init",section-size="28",total-size="9880"} |
| +download,{section=".fini",section-size="28",total-size="9880"} |
| +download,{section=".data",section-size="3156",total-size="9880"} |
| +download,{section=".data",section-sent="512",section-size="3156", |
| total-sent="7236",total-size="9880"} |
| +download,{section=".data",section-sent="1024",section-size="3156", |
| total-sent="7748",total-size="9880"} |
| +download,{section=".data",section-sent="1536",section-size="3156", |
| total-sent="8260",total-size="9880"} |
| +download,{section=".data",section-sent="2048",section-size="3156", |
| total-sent="8772",total-size="9880"} |
| +download,{section=".data",section-sent="2560",section-size="3156", |
| total-sent="9284",total-size="9880"} |
| +download,{section=".data",section-sent="3072",section-size="3156", |
| total-sent="9796",total-size="9880"} |
| ^done,address="0x10004",load-size="9880",transfer-rate="6586", |
| write-rate="429" |
| (gdb) |
| |
| GDB Command |
| ........... |
| |
| No equivalent. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The '-target-flash-erase' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-flash-erase |
| |
| Erases all known flash memory regions on the target. |
| |
| The corresponding GDB command is 'flash-erase'. |
| |
| The output is a list of flash regions that have been erased, with |
| starting addresses and memory region sizes. |
| |
| (gdb) |
| -target-flash-erase |
| ^done,erased-regions={address="0x0",size="0x40000"} |
| (gdb) |
| |
| The '-target-select' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-select TYPE PARAMETERS ... |
| |
| Connect GDB to the remote target. This command takes two args: |
| |
| 'TYPE' |
| The type of target, for instance 'remote', etc. |
| 'PARAMETERS' |
| Device names, host names and the like. *Note Commands for Managing |
| Targets: Target Commands, for more details. |
| |
| The output is a connection notification, followed by the address at |
| which the target program is, in the following form: |
| |
| ^connected,addr="ADDRESS",func="FUNCTION NAME", |
| args=[ARG LIST] |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'target'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-select remote /dev/ttya |
| ^connected,addr="0xfe00a300",func="??",args=[] |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI |
| |
| 27.21 GDB/MI File Transfer Commands |
| =================================== |
| |
| The '-target-file-put' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-file-put HOSTFILE TARGETFILE |
| |
| Copy file HOSTFILE from the host system (the machine running GDB) to |
| TARGETFILE on the target system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'remote put'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-file-put localfile remotefile |
| ^done |
| (gdb) |
| |
| The '-target-file-get' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-file-get TARGETFILE HOSTFILE |
| |
| Copy file TARGETFILE from the target system to HOSTFILE on the host |
| system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'remote get'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-file-get remotefile localfile |
| ^done |
| (gdb) |
| |
| The '-target-file-delete' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-file-delete TARGETFILE |
| |
| Delete TARGETFILE from the target system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'remote delete'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-file-delete remotefile |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI |
| |
| 27.22 Ada Exceptions GDB/MI Commands |
| ==================================== |
| |
| The '-info-ada-exceptions' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -info-ada-exceptions [ REGEXP] |
| |
| List all Ada exceptions defined within the program being debugged. |
| With a regular expression REGEXP, only those exceptions whose names |
| match REGEXP are listed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info exceptions'. |
| |
| Result |
| ...... |
| |
| The result is a table of Ada exceptions. The following columns are |
| defined for each exception: |
| |
| 'name' |
| The name of the exception. |
| |
| 'address' |
| The address of the exception. |
| |
| Example |
| ....... |
| |
| -info-ada-exceptions aint |
| ^done,ada-exceptions={nr_rows="2",nr_cols="2", |
| hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"}, |
| {width="1",alignment="-1",col_name="address",colhdr="Address"}], |
| body=[{name="constraint_error",address="0x0000000000613da0"}, |
| {name="const.aint_global_e",address="0x0000000000613b00"}]} |
| |
| Catching Ada Exceptions |
| ----------------------- |
| |
| The commands describing how to ask GDB to stop when a program raises an |
| exception are described at *note Ada Exception GDB/MI Catchpoint |
| Commands::. |
| |
| |
| File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI |
| |
| 27.23 GDB/MI Support Commands |
| ============================= |
| |
| Since new commands and features get regularly added to GDB/MI, some |
| commands are available to help front-ends query the debugger about |
| support for these capabilities. Similarly, it is also possible to query |
| GDB about target support of certain features. |
| |
| The '-info-gdb-mi-command' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -info-gdb-mi-command CMD_NAME |
| |
| Query support for the GDB/MI command named CMD_NAME. |
| |
| Note that the dash ('-') starting all GDB/MI commands is technically |
| not part of the command name (*note GDB/MI Input Syntax::), and thus |
| should be omitted in CMD_NAME. However, for ease of use, this command |
| also accepts the form with the leading dash. |
| |
| GDB Command |
| ........... |
| |
| There is no corresponding GDB command. |
| |
| Result |
| ...... |
| |
| The result is a tuple. There is currently only one field: |
| |
| 'exists' |
| This field is equal to '"true"' if the GDB/MI command exists, |
| '"false"' otherwise. |
| |
| Example |
| ....... |
| |
| Here is an example where the GDB/MI command does not exist: |
| |
| -info-gdb-mi-command unsupported-command |
| ^done,command={exists="false"} |
| |
| And here is an example where the GDB/MI command is known to the |
| debugger: |
| |
| -info-gdb-mi-command symbol-list-lines |
| ^done,command={exists="true"} |
| |
| The '-list-features' Command |
| ---------------------------- |
| |
| Returns a list of particular features of the MI protocol that this |
| version of gdb implements. A feature can be a command, or a new field |
| in an output of some command, or even an important bugfix. While a |
| frontend can sometimes detect presence of a feature at runtime, it is |
| easier to perform detection at debugger startup. |
| |
| The command returns a list of strings, with each string naming an |
| available feature. Each returned string is just a name, it does not |
| have any internal structure. The list of possible feature names is |
| given below. |
| |
| Example output: |
| |
| (gdb) -list-features |
| ^done,result=["feature1","feature2"] |
| |
| The current list of features is: |
| |
| 'frozen-varobjs' |
| Indicates support for the '-var-set-frozen' command, as well as |
| possible presence of the 'frozen' field in the output of |
| '-varobj-create'. |
| 'pending-breakpoints' |
| Indicates support for the '-f' option to the '-break-insert' |
| command. |
| 'python' |
| Indicates Python scripting support, Python-based pretty-printing |
| commands, and possible presence of the 'display_hint' field in the |
| output of '-var-list-children' |
| 'thread-info' |
| Indicates support for the '-thread-info' command. |
| 'data-read-memory-bytes' |
| Indicates support for the '-data-read-memory-bytes' and the |
| '-data-write-memory-bytes' commands. |
| 'breakpoint-notifications' |
| Indicates that changes to breakpoints and breakpoints created via |
| the CLI will be announced via async records. |
| 'ada-task-info' |
| Indicates support for the '-ada-task-info' command. |
| 'language-option' |
| Indicates that all GDB/MI commands accept the '--language' option |
| (*note Context management::). |
| 'info-gdb-mi-command' |
| Indicates support for the '-info-gdb-mi-command' command. |
| 'undefined-command-error-code' |
| Indicates support for the "undefined-command" error code in error |
| result records, produced when trying to execute an undefined GDB/MI |
| command (*note GDB/MI Result Records::). |
| 'exec-run-start-option' |
| Indicates that the '-exec-run' command supports the '--start' |
| option (*note GDB/MI Program Execution::). |
| 'data-disassemble-a-option' |
| Indicates that the '-data-disassemble' command supports the '-a' |
| option (*note GDB/MI Data Manipulation::). |
| |
| The '-list-target-features' Command |
| ----------------------------------- |
| |
| Returns a list of particular features that are supported by the target. |
| Those features affect the permitted MI commands, but unlike the features |
| reported by the '-list-features' command, the features depend on which |
| target GDB is using at the moment. Whenever a target can change, due to |
| commands such as '-target-select', '-target-attach' or '-exec-run', the |
| list of target features may change, and the frontend should obtain it |
| again. Example output: |
| |
| (gdb) -list-target-features |
| ^done,result=["async"] |
| |
| The current list of features is: |
| |
| 'async' |
| Indicates that the target is capable of asynchronous command |
| execution, which means that GDB will accept further commands while |
| the target is running. |
| |
| 'reverse' |
| Indicates that the target is capable of reverse execution. *Note |
| Reverse Execution::, for more information. |
| |
| |
| File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI |
| |
| 27.24 Miscellaneous GDB/MI Commands |
| =================================== |
| |
| The '-gdb-exit' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-exit |
| |
| Exit GDB immediately. |
| |
| GDB Command |
| ........... |
| |
| Approximately corresponds to 'quit'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-exit |
| ^exit |
| |
| The '-gdb-set' Command |
| ---------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-set |
| |
| Set an internal GDB variable. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'set'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-set $foo=3 |
| ^done |
| (gdb) |
| |
| The '-gdb-show' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-show |
| |
| Show the current value of a GDB variable. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'show'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-show annotate |
| ^done,value="0" |
| (gdb) |
| |
| The '-gdb-version' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-version |
| |
| Show version information for GDB. Used mostly in testing. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is 'show version'. GDB by default shows this |
| information when you start an interactive session. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-version |
| ~GNU gdb 5.2.1 |
| ~Copyright 2000 Free Software Foundation, Inc. |
| ~GDB is free software, covered by the GNU General Public License, and |
| ~you are welcome to change it and/or distribute copies of it under |
| ~ certain conditions. |
| ~Type "show copying" to see the conditions. |
| ~There is absolutely no warranty for GDB. Type "show warranty" for |
| ~ details. |
| ~This GDB was configured as |
| "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". |
| ^done |
| (gdb) |
| |
| The '-list-thread-groups' Command |
| --------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] |
| |
| Lists thread groups (*note Thread groups::). When a single thread |
| group is passed as the argument, lists the children of that group. When |
| several thread group are passed, lists information about those thread |
| groups. Without any parameters, lists information about all top-level |
| thread groups. |
| |
| Normally, thread groups that are being debugged are reported. With |
| the '--available' option, GDB reports thread groups available on the |
| target. |
| |
| The output of this command may have either a 'threads' result or a |
| 'groups' result. The 'thread' result has a list of tuples as value, |
| with each tuple describing a thread (*note GDB/MI Thread Information::). |
| The 'groups' result has a list of tuples as value, each tuple describing |
| a thread group. If top-level groups are requested (that is, no |
| parameter is passed), or when several groups are passed, the output |
| always has a 'groups' result. The format of the 'group' result is |
| described below. |
| |
| To reduce the number of roundtrips it's possible to list thread |
| groups together with their children, by passing the '--recurse' option |
| and the recursion depth. Presently, only recursion depth of 1 is |
| permitted. If this option is present, then every reported thread group |
| will also include its children, either as 'group' or 'threads' field. |
| |
| In general, any combination of option and parameters is permitted, |
| with the following caveats: |
| |
| * When a single thread group is passed, the output will typically be |
| the 'threads' result. Because threads may not contain anything, |
| the 'recurse' option will be ignored. |
| |
| * When the '--available' option is passed, limited information may be |
| available. In particular, the list of threads of a process might |
| be inaccessible. Further, specifying specific thread groups might |
| not give any performance advantage over listing all thread groups. |
| The frontend should assume that '-list-thread-groups --available' |
| is always an expensive operation and cache the results. |
| |
| The 'groups' result is a list of tuples, where each tuple may have |
| the following fields: |
| |
| 'id' |
| Identifier of the thread group. This field is always present. The |
| identifier is an opaque string; frontends should not try to convert |
| it to an integer, even though it might look like one. |
| |
| 'type' |
| The type of the thread group. At present, only 'process' is a |
| valid type. |
| |
| 'pid' |
| The target-specific process identifier. This field is only present |
| for thread groups of type 'process' and only if the process exists. |
| |
| 'exit-code' |
| The exit code of this group's last exited thread, formatted in |
| octal. This field is only present for thread groups of type |
| 'process' and only if the process is not running. |
| |
| 'num_children' |
| The number of children this thread group has. This field may be |
| absent for an available thread group. |
| |
| 'threads' |
| This field has a list of tuples as value, each tuple describing a |
| thread. It may be present if the '--recurse' option is specified, |
| and it's actually possible to obtain the threads. |
| |
| 'cores' |
| This field is a list of integers, each identifying a core that one |
| thread of the group is running on. This field may be absent if |
| such information is not available. |
| |
| 'executable' |
| The name of the executable file that corresponds to this thread |
| group. The field is only present for thread groups of type |
| 'process', and only if there is a corresponding executable file. |
| |
| Example |
| ------- |
| |
| gdb |
| -list-thread-groups |
| ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] |
| -list-thread-groups 17 |
| ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", |
| frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, |
| {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", |
| frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], |
| file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"},state="running"}]] |
| -list-thread-groups --available |
| ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] |
| -list-thread-groups --available --recurse 1 |
| ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], |
| threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, |
| {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] |
| -list-thread-groups --available --recurse 1 17 18 |
| ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], |
| threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, |
| {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] |
| |
| The '-info-os' Command |
| ---------------------- |
| |
| Synopsis |
| ........ |
| |
| -info-os [ TYPE ] |
| |
| If no argument is supplied, the command returns a table of available |
| operating-system-specific information types. If one of these types is |
| supplied as an argument TYPE, then the command returns a table of data |
| of that type. |
| |
| The types of information available depend on the target operating |
| system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info os'. |
| |
| Example |
| ....... |
| |
| When run on a GNU/Linux system, the output will look something like |
| this: |
| |
| gdb |
| -info-os |
| ^done,OSDataTable={nr_rows="10",nr_cols="3", |
| hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"}, |
| {width="10",alignment="-1",col_name="col1",colhdr="Description"}, |
| {width="10",alignment="-1",col_name="col2",colhdr="Title"}], |
| body=[item={col0="cpus",col1="Listing of all cpus/cores on the system", |
| col2="CPUs"}, |
| item={col0="files",col1="Listing of all file descriptors", |
| col2="File descriptors"}, |
| item={col0="modules",col1="Listing of all loaded kernel modules", |
| col2="Kernel modules"}, |
| item={col0="msg",col1="Listing of all message queues", |
| col2="Message queues"}, |
| item={col0="processes",col1="Listing of all processes", |
| col2="Processes"}, |
| item={col0="procgroups",col1="Listing of all process groups", |
| col2="Process groups"}, |
| item={col0="semaphores",col1="Listing of all semaphores", |
| col2="Semaphores"}, |
| item={col0="shm",col1="Listing of all shared-memory regions", |
| col2="Shared-memory regions"}, |
| item={col0="sockets",col1="Listing of all internet-domain sockets", |
| col2="Sockets"}, |
| item={col0="threads",col1="Listing of all threads", |
| col2="Threads"}] |
| gdb |
| -info-os processes |
| ^done,OSDataTable={nr_rows="190",nr_cols="4", |
| hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"}, |
| {width="10",alignment="-1",col_name="col1",colhdr="user"}, |
| {width="10",alignment="-1",col_name="col2",colhdr="command"}, |
| {width="10",alignment="-1",col_name="col3",colhdr="cores"}], |
| body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"}, |
| item={col0="2",col1="root",col2="[kthreadd]",col3="1"}, |
| item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"}, |
| ... |
| item={col0="26446",col1="stan",col2="bash",col3="0"}, |
| item={col0="28152",col1="stan",col2="bash",col3="1"}]} |
| (gdb) |
| |
| (Note that the MI output here includes a '"Title"' column that does |
| not appear in command-line 'info os'; this column is useful for MI |
| clients that want to enumerate the types of data, such as in a popup |
| menu, but is needless clutter on the command line, and 'info os' omits |
| it.) |
| |
| The '-add-inferior' Command |
| --------------------------- |
| |
| Synopsis |
| -------- |
| |
| -add-inferior |
| |
| Creates a new inferior (*note Inferiors and Programs::). The created |
| inferior is not associated with any executable. Such association may be |
| established with the '-file-exec-and-symbols' command (*note GDB/MI File |
| Commands::). The command response has a single field, 'inferior', whose |
| value is the identifier of the thread group corresponding to the new |
| inferior. |
| |
| Example |
| ------- |
| |
| gdb |
| -add-inferior |
| ^done,inferior="i3" |
| |
| The '-interpreter-exec' Command |
| ------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -interpreter-exec INTERPRETER COMMAND |
| |
| Execute the specified COMMAND in the given INTERPRETER. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is 'interpreter-exec'. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -interpreter-exec console "break main" |
| &"During symbol reading, couldn't parse type; debugger out of date?.\n" |
| &"During symbol reading, bad structure-type format.\n" |
| ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" |
| ^done |
| (gdb) |
| |
| The '-inferior-tty-set' Command |
| ------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -inferior-tty-set /dev/pts/1 |
| |
| Set terminal for future runs of the program being debugged. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is 'set inferior-tty' /dev/pts/1. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -inferior-tty-set /dev/pts/1 |
| ^done |
| (gdb) |
| |
| The '-inferior-tty-show' Command |
| -------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -inferior-tty-show |
| |
| Show terminal for future runs of program being debugged. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is 'show inferior-tty'. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -inferior-tty-set /dev/pts/1 |
| ^done |
| (gdb) |
| -inferior-tty-show |
| ^done,inferior_tty_terminal="/dev/pts/1" |
| (gdb) |
| |
| The '-enable-timings' Command |
| ----------------------------- |
| |
| Synopsis |
| -------- |
| |
| -enable-timings [yes | no] |
| |
| Toggle the printing of the wallclock, user and system times for an MI |
| command as a field in its output. This command is to help frontend |
| developers optimize the performance of their code. No argument is |
| equivalent to 'yes'. |
| |
| GDB Command |
| ----------- |
| |
| No equivalent. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -enable-timings |
| ^done |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x080484ed",func="main",file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], |
| times="0"}, |
| time={wallclock="0.05185",user="0.00800",system="0.00000"} |
| (gdb) |
| -enable-timings no |
| ^done |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", |
| frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, |
| {name="argv",value="0xbfb60364"}],file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"} |
| (gdb) |
| |
| The '-complete' Command |
| ----------------------- |
| |
| Synopsis |
| -------- |
| |
| -complete COMMAND |
| |
| Show a list of completions for partially typed CLI COMMAND. |
| |
| This command is intended for GDB/MI frontends that cannot use two |
| separate CLI and MI channels -- for example: because of lack of PTYs |
| like on Windows or because GDB is used remotely via a SSH connection. |
| |
| Result |
| ------ |
| |
| The result consists of two or three fields: |
| |
| 'completion' |
| This field contains the completed COMMAND. If COMMAND has no known |
| completions, this field is omitted. |
| |
| 'matches' |
| This field contains a (possibly empty) array of matches. It is |
| always present. |
| |
| 'max_completions_reached' |
| This field contains '1' if number of known completions is above |
| 'max-completions' limit (*note Completion::), otherwise it contains |
| '0'. It is always present. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is 'complete'. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -complete br |
| ^done,completion="break", |
| matches=["break","break-range"], |
| max_completions_reached="0" |
| (gdb) |
| -complete "b ma" |
| ^done,completion="b ma", |
| matches=["b madvise","b main"],max_completions_reached="0" |
| (gdb) |
| -complete "b push_b" |
| ^done,completion="b push_back(", |
| matches=[ |
| "b A::push_back(void*)", |
| "b std::string::push_back(char)", |
| "b std::vector<int, std::allocator<int> >::push_back(int&&)"], |
| max_completions_reached="0" |
| (gdb) |
| -complete "nonexist" |
| ^done,matches=[],max_completions_reached="0" |
| (gdb) |
| |
| |
| |
| File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top |
| |
| 28 GDB Annotations |
| ****************** |
| |
| This chapter describes annotations in GDB. Annotations were designed to |
| interface GDB to graphical user interfaces or other similar programs |
| which want to interact with GDB at a relatively high level. |
| |
| The annotation mechanism has largely been superseded by GDB/MI (*note |
| GDB/MI::). |
| |
| * Menu: |
| |
| * Annotations Overview:: What annotations are; the general syntax. |
| * Server Prefix:: Issuing a command without affecting user state. |
| * Prompting:: Annotations marking GDB's need for input. |
| * Errors:: Annotations for error messages. |
| * Invalidation:: Some annotations describe things now invalid. |
| * Annotations for Running:: |
| Whether the program is running, how it stopped, etc. |
| * Source Annotations:: Annotations describing source code. |
| |
| |
| File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations |
| |
| 28.1 What is an Annotation? |
| =========================== |
| |
| Annotations start with a newline character, two 'control-z' characters, |
| and the name of the annotation. If there is no additional information |
| associated with this annotation, the name of the annotation is followed |
| immediately by a newline. If there is additional information, the name |
| of the annotation is followed by a space, the additional information, |
| and a newline. The additional information cannot contain newline |
| characters. |
| |
| Any output not beginning with a newline and two 'control-z' |
| characters denotes literal output from GDB. Currently there is no need |
| for GDB to output a newline followed by two 'control-z' characters, but |
| if there was such a need, the annotations could be extended with an |
| 'escape' annotation which means those three characters as output. |
| |
| The annotation LEVEL, which is specified using the '--annotate' |
| command line option (*note Mode Options::), controls how much |
| information GDB prints together with its prompt, values of expressions, |
| source lines, and other types of output. Level 0 is for no annotations, |
| level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3 |
| is the maximum annotation suitable for programs that control GDB, and |
| level 2 annotations have been made obsolete (*note Limitations of the |
| Annotation Interface: (annotate)Limitations.). |
| |
| 'set annotate LEVEL' |
| The GDB command 'set annotate' sets the level of annotations to the |
| specified LEVEL. |
| |
| 'show annotate' |
| Show the current annotation level. |
| |
| This chapter describes level 3 annotations. |
| |
| A simple example of starting up GDB with annotations is: |
| |
| $ gdb --annotate=3 |
| GNU gdb 6.0 |
| Copyright 2003 Free Software Foundation, Inc. |
| GDB is free software, covered by the GNU General Public License, |
| and you are welcome to change it and/or distribute copies of it |
| under certain conditions. |
| Type "show copying" to see the conditions. |
| There is absolutely no warranty for GDB. Type "show warranty" |
| for details. |
| This GDB was configured as "i386-pc-linux-gnu" |
| |
| ^Z^Zpre-prompt |
| (gdb) |
| ^Z^Zprompt |
| quit |
| |
| ^Z^Zpost-prompt |
| $ |
| |
| Here 'quit' is input to GDB; the rest is output from GDB. The three |
| lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are |
| annotations; the rest is output from GDB. |
| |
| |
| File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations |
| |
| 28.2 The Server Prefix |
| ====================== |
| |
| If you prefix a command with 'server ' then it will not affect the |
| command history, nor will it affect GDB's notion of which command to |
| repeat if <RET> is pressed on a line by itself. This means that |
| commands can be run behind a user's back by a front-end in a transparent |
| manner. |
| |
| The 'server ' prefix does not affect the recording of values into the |
| value history; to print a value without recording it into the value |
| history, use the 'output' command instead of the 'print' command. |
| |
| Using this prefix also disables confirmation requests (*note |
| confirmation requests::). |
| |
| |
| File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations |
| |
| 28.3 Annotation for GDB Input |
| ============================= |
| |
| When GDB prompts for input, it annotates this fact so it is possible to |
| know when to send output, when the output from a given command is over, |
| etc. |
| |
| Different kinds of input each have a different "input type". Each |
| input type has three annotations: a 'pre-' annotation, which denotes the |
| beginning of any prompt which is being output, a plain annotation, which |
| denotes the end of the prompt, and then a 'post-' annotation which |
| denotes the end of any echo which may (or may not) be associated with |
| the input. For example, the 'prompt' input type features the following |
| annotations: |
| |
| ^Z^Zpre-prompt |
| ^Z^Zprompt |
| ^Z^Zpost-prompt |
| |
| The input types are |
| |
| 'prompt' |
| When GDB is prompting for a command (the main GDB prompt). |
| |
| 'commands' |
| When GDB prompts for a set of commands, like in the 'commands' |
| command. The annotations are repeated for each command which is |
| input. |
| |
| 'overload-choice' |
| When GDB wants the user to select between various overloaded |
| functions. |
| |
| 'query' |
| When GDB wants the user to confirm a potentially dangerous |
| operation. |
| |
| 'prompt-for-continue' |
| When GDB is asking the user to press return to continue. Note: |
| Don't expect this to work well; instead use 'set height 0' to |
| disable prompting. This is because the counting of lines is buggy |
| in the presence of annotations. |
| |
| |
| File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations |
| |
| 28.4 Errors |
| =========== |
| |
| ^Z^Zquit |
| |
| This annotation occurs right before GDB responds to an interrupt. |
| |
| ^Z^Zerror |
| |
| This annotation occurs right before GDB responds to an error. |
| |
| Quit and error annotations indicate that any annotations which GDB |
| was in the middle of may end abruptly. For example, if a |
| 'value-history-begin' annotation is followed by a 'error', one cannot |
| expect to receive the matching 'value-history-end'. One cannot expect |
| not to receive it either, however; an error annotation does not |
| necessarily mean that GDB is immediately returning all the way to the |
| top level. |
| |
| A quit or error annotation may be preceded by |
| |
| ^Z^Zerror-begin |
| |
| Any output between that and the quit or error annotation is the error |
| message. |
| |
| Warning messages are not yet annotated. |
| |
| |
| File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations |
| |
| 28.5 Invalidation Notices |
| ========================= |
| |
| The following annotations say that certain pieces of state may have |
| changed. |
| |
| '^Z^Zframes-invalid' |
| |
| The frames (for example, output from the 'backtrace' command) may |
| have changed. |
| |
| '^Z^Zbreakpoints-invalid' |
| |
| The breakpoints may have changed. For example, the user just added |
| or deleted a breakpoint. |
| |
| |
| File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations |
| |
| 28.6 Running the Program |
| ======================== |
| |
| When the program starts executing due to a GDB command such as 'step' or |
| 'continue', |
| |
| ^Z^Zstarting |
| |
| is output. When the program stops, |
| |
| ^Z^Zstopped |
| |
| is output. Before the 'stopped' annotation, a variety of annotations |
| describe how the program stopped. |
| |
| '^Z^Zexited EXIT-STATUS' |
| The program exited, and EXIT-STATUS is the exit status (zero for |
| successful exit, otherwise nonzero). |
| |
| '^Z^Zsignalled' |
| The program exited with a signal. After the '^Z^Zsignalled', the |
| annotation continues: |
| |
| INTRO-TEXT |
| ^Z^Zsignal-name |
| NAME |
| ^Z^Zsignal-name-end |
| MIDDLE-TEXT |
| ^Z^Zsignal-string |
| STRING |
| ^Z^Zsignal-string-end |
| END-TEXT |
| |
| where NAME is the name of the signal, such as 'SIGILL' or |
| 'SIGSEGV', and STRING is the explanation of the signal, such as |
| 'Illegal Instruction' or 'Segmentation fault'. The arguments |
| INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit |
| and have no particular format. |
| |
| '^Z^Zsignal' |
| The syntax of this annotation is just like 'signalled', but GDB is |
| just saying that the program received the signal, not that it was |
| terminated with it. |
| |
| '^Z^Zbreakpoint NUMBER' |
| The program hit breakpoint number NUMBER. |
| |
| '^Z^Zwatchpoint NUMBER' |
| The program hit watchpoint number NUMBER. |
| |
| |
| File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations |
| |
| 28.7 Displaying Source |
| ====================== |
| |
| The following annotation is used instead of displaying source code: |
| |
| ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR |
| |
| where FILENAME is an absolute file name indicating which source file, |
| LINE is the line number within that file (where 1 is the first line in |
| the file), CHARACTER is the character position within the file (where 0 |
| is the first character in the file) (for most debug formats this will |
| necessarily point to the beginning of a line), MIDDLE is 'middle' if |
| ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning |
| of the line, and ADDR is the address in the target program associated |
| with the source which is being displayed. The ADDR is in the form '0x' |
| followed by one or more lowercase hex digits (note that this does not |
| depend on the language). |
| |
| |
| File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top |
| |
| 29 JIT Compilation Interface |
| **************************** |
| |
| This chapter documents GDB's "just-in-time" (JIT) compilation interface. |
| A JIT compiler is a program or library that generates native executable |
| code at runtime and executes it, usually in order to achieve good |
| performance while maintaining platform independence. |
| |
| Programs that use JIT compilation are normally difficult to debug |
| because portions of their code are generated at runtime, instead of |
| being loaded from object files, which is where GDB normally finds the |
| program's symbols and debug information. In order to debug programs |
| that use JIT compilation, GDB has an interface that allows the program |
| to register in-memory symbol files with GDB at runtime. |
| |
| If you are using GDB to debug a program that uses this interface, |
| then it should work transparently so long as you have not stripped the |
| binary. If you are developing a JIT compiler, then the interface is |
| documented in the rest of this chapter. At this time, the only known |
| client of this interface is the LLVM JIT. |
| |
| Broadly speaking, the JIT interface mirrors the dynamic loader |
| interface. The JIT compiler communicates with GDB by writing data into |
| a global variable and calling a function at a well-known symbol. When |
| GDB attaches, it reads a linked list of symbol files from the global |
| variable to find existing code, and puts a breakpoint in the function so |
| that it can find out about additional code. |
| |
| * Menu: |
| |
| * Declarations:: Relevant C struct declarations |
| * Registering Code:: Steps to register code |
| * Unregistering Code:: Steps to unregister code |
| * Custom Debug Info:: Emit debug information in a custom format |
| |
| |
| File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface |
| |
| 29.1 JIT Declarations |
| ===================== |
| |
| These are the relevant struct declarations that a C program should |
| include to implement the interface: |
| |
| typedef enum |
| { |
| JIT_NOACTION = 0, |
| JIT_REGISTER_FN, |
| JIT_UNREGISTER_FN |
| } jit_actions_t; |
| |
| struct jit_code_entry |
| { |
| struct jit_code_entry *next_entry; |
| struct jit_code_entry *prev_entry; |
| const char *symfile_addr; |
| uint64_t symfile_size; |
| }; |
| |
| struct jit_descriptor |
| { |
| uint32_t version; |
| /* This type should be jit_actions_t, but we use uint32_t |
| to be explicit about the bitwidth. */ |
| uint32_t action_flag; |
| struct jit_code_entry *relevant_entry; |
| struct jit_code_entry *first_entry; |
| }; |
| |
| /* GDB puts a breakpoint in this function. */ |
| void __attribute__((noinline)) __jit_debug_register_code() { }; |
| |
| /* Make sure to specify the version statically, because the |
| debugger may check the version before we can set it. */ |
| struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; |
| |
| If the JIT is multi-threaded, then it is important that the JIT |
| synchronize any modifications to this global data properly, which can |
| easily be done by putting a global mutex around modifications to these |
| structures. |
| |
| |
| File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface |
| |
| 29.2 Registering Code |
| ===================== |
| |
| To register code with GDB, the JIT should follow this protocol: |
| |
| * Generate an object file in memory with symbols and other desired |
| debug information. The file must include the virtual addresses of |
| the sections. |
| |
| * Create a code entry for the file, which gives the start and size of |
| the symbol file. |
| |
| * Add it to the linked list in the JIT descriptor. |
| |
| * Point the relevant_entry field of the descriptor at the entry. |
| |
| * Set 'action_flag' to 'JIT_REGISTER' and call |
| '__jit_debug_register_code'. |
| |
| When GDB is attached and the breakpoint fires, GDB uses the |
| 'relevant_entry' pointer so it doesn't have to walk the list looking for |
| new code. However, the linked list must still be maintained in order to |
| allow GDB to attach to a running process and still find the symbol |
| files. |
| |
| |
| File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface |
| |
| 29.3 Unregistering Code |
| ======================= |
| |
| If code is freed, then the JIT should use the following protocol: |
| |
| * Remove the code entry corresponding to the code from the linked |
| list. |
| |
| * Point the 'relevant_entry' field of the descriptor at the code |
| entry. |
| |
| * Set 'action_flag' to 'JIT_UNREGISTER' and call |
| '__jit_debug_register_code'. |
| |
| If the JIT frees or recompiles code without unregistering it, then |
| GDB and the JIT will leak the memory used for the associated symbol |
| files. |
| |
| |
| File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface |
| |
| 29.4 Custom Debug Info |
| ====================== |
| |
| Generating debug information in platform-native file formats (like ELF |
| or COFF) may be an overkill for JIT compilers; especially if all the |
| debug info is used for is displaying a meaningful backtrace. The issue |
| can be resolved by having the JIT writers decide on a debug info format |
| and also provide a reader that parses the debug info generated by the |
| JIT compiler. This section gives a brief overview on writing such a |
| parser. More specific details can be found in the source file |
| 'gdb/jit-reader.in', which is also installed as a header at |
| 'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion. |
| |
| The reader is implemented as a shared object (so this functionality |
| is not available on platforms which don't allow loading shared objects |
| at runtime). Two GDB commands, 'jit-reader-load' and |
| 'jit-reader-unload' are provided, to be used to load and unload the |
| readers from a preconfigured directory. Once loaded, the shared object |
| is used the parse the debug information emitted by the JIT compiler. |
| |
| * Menu: |
| |
| * Using JIT Debug Info Readers:: How to use supplied readers correctly |
| * Writing JIT Debug Info Readers:: Creating a debug-info reader |
| |
| |
| File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info |
| |
| 29.4.1 Using JIT Debug Info Readers |
| ----------------------------------- |
| |
| Readers can be loaded and unloaded using the 'jit-reader-load' and |
| 'jit-reader-unload' commands. |
| |
| 'jit-reader-load READER' |
| Load the JIT reader named READER, which is a shared object |
| specified as either an absolute or a relative file name. In the |
| latter case, GDB will try to load the reader from a pre-configured |
| directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is |
| the system library directory, often '/usr/local/lib'). |
| |
| Only one reader can be active at a time; trying to load a second |
| reader when one is already loaded will result in GDB reporting an |
| error. A new JIT reader can be loaded by first unloading the |
| current one using 'jit-reader-unload' and then invoking |
| 'jit-reader-load'. |
| |
| 'jit-reader-unload' |
| Unload the currently loaded JIT reader. |
| |
| |
| File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info |
| |
| 29.4.2 Writing JIT Debug Info Readers |
| ------------------------------------- |
| |
| As mentioned, a reader is essentially a shared object conforming to a |
| certain ABI. This ABI is described in 'jit-reader.h'. |
| |
| 'jit-reader.h' defines the structures, macros and functions required |
| to write a reader. It is installed (along with GDB), in |
| 'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory. |
| |
| Readers need to be released under a GPL compatible license. A reader |
| can be declared as released under such a license by placing the macro |
| 'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file. |
| |
| The entry point for readers is the symbol 'gdb_init_reader', which is |
| expected to be a function with the prototype |
| |
| extern struct gdb_reader_funcs *gdb_init_reader (void); |
| |
| 'struct gdb_reader_funcs' contains a set of pointers to callback |
| functions. These functions are executed to read the debug info |
| generated by the JIT compiler ('read'), to unwind stack frames |
| ('unwind') and to create canonical frame IDs ('get_frame_id'). It also |
| has a callback that is called when the reader is being unloaded |
| ('destroy'). The struct looks like this |
| |
| struct gdb_reader_funcs |
| { |
| /* Must be set to GDB_READER_INTERFACE_VERSION. */ |
| int reader_version; |
| |
| /* For use by the reader. */ |
| void *priv_data; |
| |
| gdb_read_debug_info *read; |
| gdb_unwind_frame *unwind; |
| gdb_get_frame_id *get_frame_id; |
| gdb_destroy_reader *destroy; |
| }; |
| |
| The callbacks are provided with another set of callbacks by GDB to do |
| their job. For 'read', these callbacks are passed in a 'struct |
| gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct |
| gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to |
| create new object files and new symbol tables inside those object files. |
| 'struct gdb_unwind_callbacks' has callbacks to read registers off the |
| current frame and to write out the values of the registers in the |
| previous frame. Both have a callback ('target_read') to read bytes off |
| the target's address space. |
| |
| |
| File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top |
| |
| 30 In-Process Agent |
| ******************* |
| |
| The traditional debugging model is conceptually low-speed, but works |
| fine, because most bugs can be reproduced in debugging-mode execution. |
| However, as multi-core or many-core processors are becoming mainstream, |
| and multi-threaded programs become more and more popular, there should |
| be more and more bugs that only manifest themselves at normal-mode |
| execution, for example, thread races, because debugger's interference |
| with the program's timing may conceal the bugs. On the other hand, in |
| some applications, it is not feasible for the debugger to interrupt the |
| program's execution long enough for the developer to learn anything |
| helpful about its behavior. If the program's correctness depends on its |
| real-time behavior, delays introduced by a debugger might cause the |
| program to fail, even when the code itself is correct. It is useful to |
| be able to observe the program's behavior without interrupting it. |
| |
| Therefore, traditional debugging model is too intrusive to reproduce |
| some bugs. In order to reduce the interference with the program, we can |
| reduce the number of operations performed by debugger. The "In-Process |
| Agent", a shared library, is running within the same process with |
| inferior, and is able to perform some debugging operations itself. As a |
| result, debugger is only involved when necessary, and performance of |
| debugging can be improved accordingly. Note that interference with |
| program can be reduced but can't be removed completely, because the |
| in-process agent will still stop or slow down the program. |
| |
| The in-process agent can interpret and execute Agent Expressions |
| (*note Agent Expressions::) during performing debugging operations. The |
| agent expressions can be used for different purposes, such as collecting |
| data in tracepoints, and condition evaluation in breakpoints. |
| |
| You can control whether the in-process agent is used as an aid for |
| debugging with the following commands: |
| |
| 'set agent on' |
| Causes the in-process agent to perform some operations on behalf of |
| the debugger. Just which operations requested by the user will be |
| done by the in-process agent depends on the its capabilities. For |
| example, if you request to evaluate breakpoint conditions in the |
| in-process agent, and the in-process agent has such capability as |
| well, then breakpoint conditions will be evaluated in the |
| in-process agent. |
| |
| 'set agent off' |
| Disables execution of debugging operations by the in-process agent. |
| All of the operations will be performed by GDB. |
| |
| 'show agent' |
| Display the current setting of execution of debugging operations by |
| the in-process agent. |
| |
| * Menu: |
| |
| * In-Process Agent Protocol:: |
| |
| |
| File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent |
| |
| 30.1 In-Process Agent Protocol |
| ============================== |
| |
| The in-process agent is able to communicate with both GDB and GDBserver |
| (*note In-Process Agent::). This section documents the protocol used |
| for communications between GDB or GDBserver and the IPA. In general, GDB |
| or GDBserver sends commands (*note IPA Protocol Commands::) and data to |
| in-process agent, and then in-process agent replies back with the return |
| result of the command, or some other information. The data sent to |
| in-process agent is composed of primitive data types, such as 4-byte or |
| 8-byte type, and composite types, which are called objects (*note IPA |
| Protocol Objects::). |
| |
| * Menu: |
| |
| * IPA Protocol Objects:: |
| * IPA Protocol Commands:: |
| |
| |
| File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol |
| |
| 30.1.1 IPA Protocol Objects |
| --------------------------- |
| |
| The commands sent to and results received from agent may contain some |
| complex data types called "objects". |
| |
| The in-process agent is running on the same machine with GDB or |
| GDBserver, so it doesn't have to handle as much differences between two |
| ends as remote protocol (*note Remote Protocol::) tries to handle. |
| However, there are still some differences of two ends in two processes: |
| |
| 1. word size. On some 64-bit machines, GDB or GDBserver can be |
| compiled as a 64-bit executable, while in-process agent is a 32-bit |
| one. |
| 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver |
| is compiled with one, and in-process agent is compiled with the |
| other one. |
| |
| Here are the IPA Protocol Objects: |
| |
| 1. agent expression object. It represents an agent expression (*note |
| Agent Expressions::). |
| 2. tracepoint action object. It represents a tracepoint action (*note |
| Tracepoint Action Lists: Tracepoint Actions.) to collect registers, |
| memory, static trace data and to evaluate expression. |
| 3. tracepoint object. It represents a tracepoint (*note |
| Tracepoints::). |
| |
| The following table describes important attributes of each IPA |
| protocol object: |
| |
| Name Size Description |
| --------------------------------------------------------------------------- |
| _agent expression |
| object_ |
| length 4 length of bytes code |
| byte code LENGTH contents of byte code |
| _tracepoint action |
| for collecting |
| memory_ |
| 'M' 1 type of tracepoint action |
| addr 8 if BASEREG is '-1', ADDR is the |
| address of the lowest byte to |
| collect, otherwise ADDR is the |
| offset of BASEREG for memory |
| collecting. |
| len 8 length of memory for collecting |
| basereg 4 the register number containing the |
| starting memory address for |
| collecting. |
| _tracepoint action |
| for collecting |
| registers_ |
| 'R' 1 type of tracepoint action |
| _tracepoint action |
| for collecting |
| static trace data_ |
| 'L' 1 type of tracepoint action |
| _tracepoint action |
| for expression |
| evaluation_ |
| 'X' 1 type of tracepoint action |
| agent expression length of *note agent expression object:: |
| _tracepoint object_ |
| number 4 number of tracepoint |
| address 8 address of tracepoint inserted on |
| type 4 type of tracepoint |
| enabled 1 enable or disable of tracepoint |
| step_count 8 step |
| pass_count 8 pass |
| numactions 4 number of tracepoint actions |
| hit count 8 hit count |
| trace frame usage 8 trace frame usage |
| compiled_cond 8 compiled condition |
| orig_size 8 orig size |
| condition 4 if zero if condition is NULL, |
| condition is otherwise is |
| NULL *note agent expression object:: |
| otherwise |
| length of |
| *note agent expression object:: |
| actions variable numactions number of |
| *note tracepoint action object:: |
| |
| |
| File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol |
| |
| 30.1.2 IPA Protocol Commands |
| ---------------------------- |
| |
| The spaces in each command are delimiters to ease reading this commands |
| specification. They don't exist in real commands. |
| |
| 'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD' |
| Installs a new fast tracepoint described by TRACEPOINT_OBJECT |
| (*note tracepoint object::). The GDB_JUMP_PAD_HEAD, 8-byte long, |
| is the head of "jumppad", which is used to jump to data collection |
| routine in IPA finally. |
| |
| Replies: |
| 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP' |
| TARGET_ADDRESS is address of tracepoint in the inferior. The |
| GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of |
| TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. The |
| FJUMP contains a sequence of instructions jump to jumppad |
| entry. The FJUMP_SIZE, 4-byte long, is the size of FJUMP. |
| 'E NN' |
| for an error |
| |
| 'close' |
| Closes the in-process agent. This command is sent when GDB or |
| GDBserver is about to kill inferiors. |
| |
| 'qTfSTM' |
| *Note qTfSTM::. |
| 'qTsSTM' |
| *Note qTsSTM::. |
| 'qTSTMat' |
| *Note qTSTMat::. |
| 'probe_marker_at:ADDRESS' |
| Asks in-process agent to probe the marker at ADDRESS. |
| |
| Replies: |
| 'E NN' |
| for an error |
| 'unprobe_marker_at:ADDRESS' |
| Asks in-process agent to unprobe the marker at ADDRESS. |
| |
| |
| File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top |
| |
| 31 Reporting Bugs in GDB |
| ************************ |
| |
| Your bug reports play an essential role in making GDB reliable. |
| |
| Reporting a bug may help you by bringing a solution to your problem, |
| or it may not. But in any case the principal function of a bug report |
| is to help the entire community by making the next version of GDB work |
| better. Bug reports are your contribution to the maintenance of GDB. |
| |
| In order for a bug report to serve its purpose, you must include the |
| information that enables us to fix the bug. |
| |
| * Menu: |
| |
| * Bug Criteria:: Have you found a bug? |
| * Bug Reporting:: How to report bugs |
| |
| |
| File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs |
| |
| 31.1 Have You Found a Bug? |
| ========================== |
| |
| If you are not sure whether you have found a bug, here are some |
| guidelines: |
| |
| * If the debugger gets a fatal signal, for any input whatever, that |
| is a GDB bug. Reliable debuggers never crash. |
| |
| * If GDB produces an error message for valid input, that is a bug. |
| (Note that if you're cross debugging, the problem may also be |
| somewhere in the connection to the target.) |
| |
| * If GDB does not produce an error message for invalid input, that is |
| a bug. However, you should note that your idea of "invalid input" |
| might be our idea of "an extension" or "support for traditional |
| practice". |
| |
| * If you are an experienced user of debugging tools, your suggestions |
| for improvement of GDB are welcome in any case. |
| |
| |
| File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs |
| |
| 31.2 How to Report Bugs |
| ======================= |
| |
| A number of companies and individuals offer support for GNU products. |
| If you obtained GDB from a support organization, we recommend you |
| contact that organization first. |
| |
| You can find contact information for many support companies and |
| individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. |
| |
| In any event, we also recommend that you submit bug reports for GDB. |
| The preferred method is to submit them directly using GDB's Bugs web |
| page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the e-mail |
| gateway <bug-gdb@gnu.org> can be used. |
| |
| *Do not send bug reports to 'info-gdb', or to 'help-gdb', or to any |
| newsgroups.* Most users of GDB do not want to receive bug reports. |
| Those that do have arranged to receive 'bug-gdb'. |
| |
| The mailing list 'bug-gdb' has a newsgroup 'gnu.gdb.bug' which serves |
| as a repeater. The mailing list and the newsgroup carry exactly the |
| same messages. Often people think of posting bug reports to the |
| newsgroup instead of mailing them. This appears to work, but it has one |
| problem which can be crucial: a newsgroup posting often lacks a mail |
| path back to the sender. Thus, if we need to ask for more information, |
| we may be unable to reach you. For this reason, it is better to send |
| bug reports to the mailing list. |
| |
| The fundamental principle of reporting bugs usefully is this: *report |
| all the facts*. If you are not sure whether to state a fact or leave it |
| out, state it! |
| |
| Often people omit facts because they think they know what causes the |
| problem and assume that some details do not matter. Thus, you might |
| assume that the name of the variable you use in an example does not |
| matter. Well, probably it does not, but one cannot be sure. Perhaps |
| the bug is a stray memory reference which happens to fetch from the |
| location where that name is stored in memory; perhaps, if the name were |
| different, the contents of that location would fool the debugger into |
| doing the right thing despite the bug. Play it safe and give a |
| specific, complete example. That is the easiest thing for you to do, |
| and the most helpful. |
| |
| Keep in mind that the purpose of a bug report is to enable us to fix |
| the bug. It may be that the bug has been reported previously, but |
| neither you nor we can know that unless your bug report is complete and |
| self-contained. |
| |
| Sometimes people give a few sketchy facts and ask, "Does this ring a |
| bell?" Those bug reports are useless, and we urge everyone to _refuse |
| to respond to them_ except to chide the sender to report bugs properly. |
| |
| To enable us to fix the bug, you should include all these things: |
| |
| * The version of GDB. GDB announces it if you start with no |
| arguments; you can also print it at any time using 'show version'. |
| |
| Without this, we will not know whether there is any point in |
| looking for the bug in the current version of GDB. |
| |
| * The type of machine you are using, and the operating system name |
| and version number. |
| |
| * The details of the GDB build-time configuration. GDB shows these |
| details if you invoke it with the '--configuration' command-line |
| option, or if you type 'show configuration' at GDB's prompt. |
| |
| * What compiler (and its version) was used to compile GDB--e.g. |
| "gcc-2.8.1". |
| |
| * What compiler (and its version) was used to compile the program you |
| are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C |
| Compiler". For GCC, you can say 'gcc --version' to get this |
| information; for other compilers, see the documentation for those |
| compilers. |
| |
| * The command arguments you gave the compiler to compile your example |
| and observe the bug. For example, did you use '-O'? To guarantee |
| you will not omit something important, list them all. A copy of |
| the Makefile (or the output from make) is sufficient. |
| |
| If we were to try to guess the arguments, we would probably guess |
| wrong and then we might not encounter the bug. |
| |
| * A complete input script, and all necessary source files, that will |
| reproduce the bug. |
| |
| * A description of what behavior you observe that you believe is |
| incorrect. For example, "It gets a fatal signal." |
| |
| Of course, if the bug is that GDB gets a fatal signal, then we will |
| certainly notice it. But if the bug is incorrect output, we might |
| not notice unless it is glaringly wrong. You might as well not |
| give us a chance to make a mistake. |
| |
| Even if the problem you experience is a fatal signal, you should |
| still say so explicitly. Suppose something strange is going on, |
| such as, your copy of GDB is out of synch, or you have encountered |
| a bug in the C library on your system. (This has happened!) Your |
| copy might crash and ours would not. If you told us to expect a |
| crash, then when ours fails to crash, we would know that the bug |
| was not happening for us. If you had not told us to expect a |
| crash, then we would not be able to draw any conclusion from our |
| observations. |
| |
| To collect all this information, you can use a session recording |
| program such as 'script', which is available on many Unix systems. |
| Just run your GDB session inside 'script' and then include the |
| 'typescript' file with your bug report. |
| |
| Another way to record a GDB session is to run GDB inside Emacs and |
| then save the entire buffer to a file. |
| |
| * If you wish to suggest changes to the GDB source, send us context |
| diffs. If you even discuss something in the GDB source, refer to |
| it by context, not by line number. |
| |
| The line numbers in our development sources will not match those in |
| your sources. Your line numbers would convey no useful information |
| to us. |
| |
| Here are some things that are not necessary: |
| |
| * A description of the envelope of the bug. |
| |
| Often people who encounter a bug spend a lot of time investigating |
| which changes to the input file will make the bug go away and which |
| changes will not affect it. |
| |
| This is often time consuming and not very useful, because the way |
| we will find the bug is by running a single example under the |
| debugger with breakpoints, not by pure deduction from a series of |
| examples. We recommend that you save your time for something else. |
| |
| Of course, if you can find a simpler example to report _instead_ of |
| the original one, that is a convenience for us. Errors in the |
| output will be easier to spot, running under the debugger will take |
| less time, and so on. |
| |
| However, simplification is not vital; if you do not want to do |
| this, report the bug anyway and send us the entire test case you |
| used. |
| |
| * A patch for the bug. |
| |
| A patch for the bug does help us if it is a good one. But do not |
| omit the necessary information, such as the test case, on the |
| assumption that a patch is all we need. We might see problems with |
| your patch and decide to fix the problem another way, or we might |
| not understand it at all. |
| |
| Sometimes with a program as complicated as GDB it is very hard to |
| construct an example that will make the program follow a certain |
| path through the code. If you do not send us the example, we will |
| not be able to construct one, so we will not be able to verify that |
| the bug is fixed. |
| |
| And if we cannot understand what bug you are trying to fix, or why |
| your patch should be an improvement, we will not install it. A |
| test case will help us to understand. |
| |
| * A guess about what the bug is or what it depends on. |
| |
| Such guesses are usually wrong. Even we cannot guess right about |
| such things without first using the debugger to find the facts. |
| |
| |
| File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top |
| |
| 32 Command Line Editing |
| *********************** |
| |
| This chapter describes the basic features of the GNU command line |
| editing interface. |
| |
| * Menu: |
| |
| * Introduction and Notation:: Notation used in this text. |
| * Readline Interaction:: The minimum set of commands for editing a line. |
| * Readline Init File:: Customizing Readline from a user's view. |
| * Bindable Readline Commands:: A description of most of the Readline commands |
| available for binding |
| * Readline vi Mode:: A short description of how to make Readline |
| behave like the vi editor. |
| |
| |
| File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing |
| |
| 32.1 Introduction to Line Editing |
| ================================= |
| |
| The following paragraphs describe the notation used to represent |
| keystrokes. |
| |
| The text 'C-k' is read as 'Control-K' and describes the character |
| produced when the <k> key is pressed while the Control key is depressed. |
| |
| The text 'M-k' is read as 'Meta-K' and describes the character |
| produced when the Meta key (if you have one) is depressed, and the <k> |
| key is pressed. The Meta key is labeled <ALT> on many keyboards. On |
| keyboards with two keys labeled <ALT> (usually to either side of the |
| space bar), the <ALT> on the left side is generally set to work as a |
| Meta key. The <ALT> key on the right may also be configured to work as |
| a Meta key or may be configured as some other modifier, such as a |
| Compose key for typing accented characters. |
| |
| If you do not have a Meta or <ALT> key, or another key working as a |
| Meta key, the identical keystroke can be generated by typing <ESC> |
| _first_, and then typing <k>. Either process is known as "metafying" |
| the <k> key. |
| |
| The text 'M-C-k' is read as 'Meta-Control-k' and describes the |
| character produced by "metafying" 'C-k'. |
| |
| In addition, several keys have their own names. Specifically, <DEL>, |
| <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen |
| in this text, or in an init file (*note Readline Init File::). If your |
| keyboard lacks a <LFD> key, typing <C-j> will produce the desired |
| character. The <RET> key may be labeled <Return> or <Enter> on some |
| keyboards. |
| |
| |
| File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing |
| |
| 32.2 Readline Interaction |
| ========================= |
| |
| Often during an interactive session you type in a long line of text, |
| only to notice that the first word on the line is misspelled. The |
| Readline library gives you a set of commands for manipulating the text |
| as you type it in, allowing you to just fix your typo, and not forcing |
| you to retype the majority of the line. Using these editing commands, |
| you move the cursor to the place that needs correction, and delete or |
| insert the text of the corrections. Then, when you are satisfied with |
| the line, you simply press <RET>. You do not have to be at the end of |
| the line to press <RET>; the entire line is accepted regardless of the |
| location of the cursor within the line. |
| |
| * Menu: |
| |
| * Readline Bare Essentials:: The least you need to know about Readline. |
| * Readline Movement Commands:: Moving about the input line. |
| * Readline Killing Commands:: How to delete text, and how to get it back! |
| * Readline Arguments:: Giving numeric arguments to commands. |
| * Searching:: Searching through previous lines. |
| |
| |
| File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction |
| |
| 32.2.1 Readline Bare Essentials |
| ------------------------------- |
| |
| In order to enter characters into the line, simply type them. The typed |
| character appears where the cursor was, and then the cursor moves one |
| space to the right. If you mistype a character, you can use your erase |
| character to back up and delete the mistyped character. |
| |
| Sometimes you may mistype a character, and not notice the error until |
| you have typed several other characters. In that case, you can type |
| 'C-b' to move the cursor to the left, and then correct your mistake. |
| Afterwards, you can move the cursor to the right with 'C-f'. |
| |
| When you add text in the middle of a line, you will notice that |
| characters to the right of the cursor are 'pushed over' to make room for |
| the text that you have inserted. Likewise, when you delete text behind |
| the cursor, characters to the right of the cursor are 'pulled back' to |
| fill in the blank space created by the removal of the text. A list of |
| the bare essentials for editing the text of an input line follows. |
| |
| 'C-b' |
| Move back one character. |
| 'C-f' |
| Move forward one character. |
| <DEL> or <Backspace> |
| Delete the character to the left of the cursor. |
| 'C-d' |
| Delete the character underneath the cursor. |
| Printing characters |
| Insert the character into the line at the cursor. |
| 'C-_' or 'C-x C-u' |
| Undo the last editing command. You can undo all the way back to an |
| empty line. |
| |
| (Depending on your configuration, the <Backspace> key be set to delete |
| the character to the left of the cursor and the <DEL> key set to delete |
| the character underneath the cursor, like 'C-d', rather than the |
| character to the left of the cursor.) |
| |
| |
| File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction |
| |
| 32.2.2 Readline Movement Commands |
| --------------------------------- |
| |
| The above table describes the most basic keystrokes that you need in |
| order to do editing of the input line. For your convenience, many other |
| commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>. |
| Here are some commands for moving more rapidly about the line. |
| |
| 'C-a' |
| Move to the start of the line. |
| 'C-e' |
| Move to the end of the line. |
| 'M-f' |
| Move forward a word, where a word is composed of letters and |
| digits. |
| 'M-b' |
| Move backward a word. |
| 'C-l' |
| Clear the screen, reprinting the current line at the top. |
| |
| Notice how 'C-f' moves forward a character, while 'M-f' moves forward |
| a word. It is a loose convention that control keystrokes operate on |
| characters while meta keystrokes operate on words. |
| |
| |
| File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction |
| |
| 32.2.3 Readline Killing Commands |
| -------------------------------- |
| |
| "Killing" text means to delete the text from the line, but to save it |
| away for later use, usually by "yanking" (re-inserting) it back into the |
| line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) |
| |
| If the description for a command says that it 'kills' text, then you |
| can be sure that you can get the text back in a different (or the same) |
| place later. |
| |
| When you use a kill command, the text is saved in a "kill-ring". Any |
| number of consecutive kills save all of the killed text together, so |
| that when you yank it back, you get it all. The kill ring is not line |
| specific; the text that you killed on a previously typed line is |
| available to be yanked back later, when you are typing another line. |
| |
| Here is the list of commands for killing text. |
| |
| 'C-k' |
| Kill the text from the current cursor position to the end of the |
| line. |
| |
| 'M-d' |
| Kill from the cursor to the end of the current word, or, if between |
| words, to the end of the next word. Word boundaries are the same |
| as those used by 'M-f'. |
| |
| 'M-<DEL>' |
| Kill from the cursor the start of the current word, or, if between |
| words, to the start of the previous word. Word boundaries are the |
| same as those used by 'M-b'. |
| |
| 'C-w' |
| Kill from the cursor to the previous whitespace. This is different |
| than 'M-<DEL>' because the word boundaries differ. |
| |
| Here is how to "yank" the text back into the line. Yanking means to |
| copy the most-recently-killed text from the kill buffer. |
| |
| 'C-y' |
| Yank the most recently killed text back into the buffer at the |
| cursor. |
| |
| 'M-y' |
| Rotate the kill-ring, and yank the new top. You can only do this |
| if the prior command is 'C-y' or 'M-y'. |
| |
| |
| File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction |
| |
| 32.2.4 Readline Arguments |
| ------------------------- |
| |
| You can pass numeric arguments to Readline commands. Sometimes the |
| argument acts as a repeat count, other times it is the sign of the |
| argument that is significant. If you pass a negative argument to a |
| command which normally acts in a forward direction, that command will |
| act in a backward direction. For example, to kill text back to the |
| start of the line, you might type 'M-- C-k'. |
| |
| The general way to pass numeric arguments to a command is to type |
| meta digits before the command. If the first 'digit' typed is a minus |
| sign ('-'), then the sign of the argument will be negative. Once you |
| have typed one meta digit to get the argument started, you can type the |
| remainder of the digits, and then the command. For example, to give the |
| 'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will |
| delete the next ten characters on the input line. |
| |
| |
| File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction |
| |
| 32.2.5 Searching for Commands in the History |
| -------------------------------------------- |
| |
| Readline provides commands for searching through the command history for |
| lines containing a specified string. There are two search modes: |
| "incremental" and "non-incremental". |
| |
| Incremental searches begin before the user has finished typing the |
| search string. As each character of the search string is typed, |
| Readline displays the next entry from the history matching the string |
| typed so far. An incremental search requires only as many characters as |
| needed to find the desired history entry. To search backward in the |
| history for a particular string, type 'C-r'. Typing 'C-s' searches |
| forward through the history. The characters present in the value of the |
| 'isearch-terminators' variable are used to terminate an incremental |
| search. If that variable has not been assigned a value, the <ESC> and |
| 'C-J' characters will terminate an incremental search. 'C-g' will abort |
| an incremental search and restore the original line. When the search is |
| terminated, the history entry containing the search string becomes the |
| current line. |
| |
| To find other matching entries in the history list, type 'C-r' or |
| 'C-s' as appropriate. This will search backward or forward in the |
| history for the next entry matching the search string typed so far. Any |
| other key sequence bound to a Readline command will terminate the search |
| and execute that command. For instance, a <RET> will terminate the |
| search and accept the line, thereby executing the command from the |
| history list. A movement command will terminate the search, make the |
| last line found the current line, and begin editing. |
| |
| Readline remembers the last incremental search string. If two 'C-r's |
| are typed without any intervening characters defining a new search |
| string, any remembered search string is used. |
| |
| Non-incremental searches read the entire search string before |
| starting to search for matching history lines. The search string may be |
| typed by the user or be part of the contents of the current line. |
| |
| |
| File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing |
| |
| 32.3 Readline Init File |
| ======================= |
| |
| Although the Readline library comes with a set of Emacs-like keybindings |
| installed by default, it is possible to use a different set of |
| keybindings. Any user can customize programs that use Readline by |
| putting commands in an "inputrc" file, conventionally in his home |
| directory. The name of this file is taken from the value of the |
| environment variable 'INPUTRC'. If that variable is unset, the default |
| is '~/.inputrc'. If that file does not exist or cannot be read, the |
| ultimate default is '/etc/inputrc'. |
| |
| When a program which uses the Readline library starts up, the init |
| file is read, and the key bindings are set. |
| |
| In addition, the 'C-x C-r' command re-reads this init file, thus |
| incorporating any changes that you might have made to it. |
| |
| * Menu: |
| |
| * Readline Init File Syntax:: Syntax for the commands in the inputrc file. |
| |
| * Conditional Init Constructs:: Conditional key bindings in the inputrc file. |
| |
| * Sample Init File:: An example inputrc file. |
| |
| |
| File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File |
| |
| 32.3.1 Readline Init File Syntax |
| -------------------------------- |
| |
| There are only a few basic constructs allowed in the Readline init file. |
| Blank lines are ignored. Lines beginning with a '#' are comments. |
| Lines beginning with a '$' indicate conditional constructs (*note |
| Conditional Init Constructs::). Other lines denote variable settings |
| and key bindings. |
| |
| Variable Settings |
| You can modify the run-time behavior of Readline by altering the |
| values of variables in Readline using the 'set' command within the |
| init file. The syntax is simple: |
| |
| set VARIABLE VALUE |
| |
| Here, for example, is how to change from the default Emacs-like key |
| binding to use 'vi' line editing commands: |
| |
| set editing-mode vi |
| |
| Variable names and values, where appropriate, are recognized |
| without regard to case. Unrecognized variable names are ignored. |
| |
| Boolean variables (those that can be set to on or off) are set to |
| on if the value is null or empty, ON (case-insensitive), or 1. Any |
| other value results in the variable being set to off. |
| |
| A great deal of run-time behavior is changeable with the following |
| variables. |
| |
| 'bell-style' |
| Controls what happens when Readline wants to ring the terminal |
| bell. If set to 'none', Readline never rings the bell. If |
| set to 'visible', Readline uses a visible bell if one is |
| available. If set to 'audible' (the default), Readline |
| attempts to ring the terminal's bell. |
| |
| 'bind-tty-special-chars' |
| If set to 'on' (the default), Readline attempts to bind the |
| control characters treated specially by the kernel's terminal |
| driver to their Readline equivalents. |
| |
| 'blink-matching-paren' |
| If set to 'on', Readline attempts to briefly move the cursor |
| to an opening parenthesis when a closing parenthesis is |
| inserted. The default is 'off'. |
| |
| 'colored-completion-prefix' |
| If set to 'on', when listing completions, Readline displays |
| the common prefix of the set of possible completions using a |
| different color. The color definitions are taken from the |
| value of the 'LS_COLORS' environment variable. The default is |
| 'off'. |
| |
| 'colored-stats' |
| If set to 'on', Readline displays possible completions using |
| different colors to indicate their file type. The color |
| definitions are taken from the value of the 'LS_COLORS' |
| environment variable. The default is 'off'. |
| |
| 'comment-begin' |
| The string to insert at the beginning of the line when the |
| 'insert-comment' command is executed. The default value is |
| '"#"'. |
| |
| 'completion-display-width' |
| The number of screen columns used to display possible matches |
| when performing completion. The value is ignored if it is |
| less than 0 or greater than the terminal screen width. A |
| value of 0 will cause matches to be displayed one per line. |
| The default value is -1. |
| |
| 'completion-ignore-case' |
| If set to 'on', Readline performs filename matching and |
| completion in a case-insensitive fashion. The default value |
| is 'off'. |
| |
| 'completion-map-case' |
| If set to 'on', and COMPLETION-IGNORE-CASE is enabled, |
| Readline treats hyphens ('-') and underscores ('_') as |
| equivalent when performing case-insensitive filename matching |
| and completion. The default value is 'off'. |
| |
| 'completion-prefix-display-length' |
| The length in characters of the common prefix of a list of |
| possible completions that is displayed without modification. |
| When set to a value greater than zero, common prefixes longer |
| than this value are replaced with an ellipsis when displaying |
| possible completions. |
| |
| 'completion-query-items' |
| The number of possible completions that determines when the |
| user is asked whether the list of possibilities should be |
| displayed. If the number of possible completions is greater |
| than this value, Readline will ask the user whether or not he |
| wishes to view them; otherwise, they are simply listed. This |
| variable must be set to an integer value greater than or equal |
| to 0. A negative value means Readline should never ask. The |
| default limit is '100'. |
| |
| 'convert-meta' |
| If set to 'on', Readline will convert characters with the |
| eighth bit set to an ASCII key sequence by stripping the |
| eighth bit and prefixing an <ESC> character, converting them |
| to a meta-prefixed key sequence. The default value is 'on', |
| but will be set to 'off' if the locale is one that contains |
| eight-bit characters. |
| |
| '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'. |
| |
| 'echo-control-characters' |
| When set to 'on', on operating systems that indicate they |
| support it, readline echoes a character corresponding to a |
| signal generated from the keyboard. The default is 'on'. |
| |
| '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'. |
| |
| 'emacs-mode-string' |
| If the SHOW-MODE-IN-PROMPT variable is enabled, this string is |
| displayed immediately before the last line of the primary |
| prompt when emacs editing mode is active. The value is |
| expanded like a key binding, so the standard set of meta- and |
| control prefixes and backslash escape sequences is available. |
| Use the '\1' and '\2' escapes to begin and end sequences of |
| non-printing characters, which can be used to embed a terminal |
| control sequence into the mode string. The default is '@'. |
| |
| 'enable-bracketed-paste' |
| When set to 'On', Readline will configure the terminal in a |
| way that will enable it to insert each paste into the editing |
| buffer as a single string of characters, instead of treating |
| each character as if it had been read from the keyboard. This |
| can prevent pasted characters from being interpreted as |
| editing commands. The default is 'off'. |
| |
| 'enable-keypad' |
| When set to 'on', Readline will try to enable the application |
| keypad when it is called. Some systems need this to enable |
| the arrow keys. The default is 'off'. |
| |
| 'enable-meta-key' |
| When set to 'on', Readline will try to enable any meta |
| modifier key the terminal claims to support when it is called. |
| On many terminals, the meta key is used to send eight-bit |
| characters. The default is 'on'. |
| |
| 'expand-tilde' |
| If set to 'on', tilde expansion is performed when Readline |
| attempts word completion. The default is 'off'. |
| |
| 'history-preserve-point' |
| If set to 'on', the history code attempts to place the point |
| (the current cursor position) at the same location on each |
| history line retrieved with 'previous-history' or |
| 'next-history'. The default is 'off'. |
| |
| 'history-size' |
| Set the maximum number of history entries saved in the history |
| list. If set to zero, any existing history entries are |
| deleted and no new entries are saved. If set to a value less |
| than zero, the number of history entries is not limited. By |
| default, the number of history entries is not limited. If an |
| attempt is made to set HISTORY-SIZE to a non-numeric value, |
| the maximum number of history entries will be set to 500. |
| |
| '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', but Readline will set it to 'on' if |
| the locale contains eight-bit characters. 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. Built-in 'keymap' names are 'emacs', |
| 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', |
| 'vi-command', and 'vi-insert'. 'vi' is equivalent to |
| 'vi-command' ('vi-move' is also a synonym); 'emacs' is |
| equivalent to 'emacs-standard'. Applications may add |
| additional names. The default value is 'emacs'. The value of |
| the 'editing-mode' variable also affects the default keymap. |
| |
| 'keyseq-timeout' |
| Specifies the duration Readline will wait for a character when |
| reading an ambiguous key sequence (one that can form a |
| complete key sequence using the input read so far, or can take |
| additional input to complete a longer key sequence). If no |
| input is received within the timeout, Readline will use the |
| shorter but complete key sequence. Readline uses this value |
| to determine whether or not input is available on the current |
| input source ('rl_instream' by default). The value is |
| specified in milliseconds, so a value of 1000 means that |
| Readline will wait one second for additional input. If this |
| variable is set to a value less than or equal to zero, or to a |
| non-numeric value, Readline will wait until another key is |
| pressed to decide which key sequence to complete. The default |
| value is '500'. |
| |
| 'mark-directories' |
| If set to 'on', completed directory names have a slash |
| appended. The default is 'on'. |
| |
| 'mark-modified-lines' |
| This variable, when set to 'on', causes Readline to display an |
| asterisk ('*') at the start of history lines which have been |
| modified. This variable is 'off' by default. |
| |
| 'mark-symlinked-directories' |
| If set to 'on', completed names which are symbolic links to |
| directories have a slash appended (subject to the value of |
| 'mark-directories'). The default is 'off'. |
| |
| 'match-hidden-files' |
| This variable, when set to 'on', causes Readline to match |
| files whose names begin with a '.' (hidden files) when |
| performing filename completion. If set to 'off', the leading |
| '.' must be supplied by the user in the filename to be |
| completed. This variable is 'on' by default. |
| |
| 'menu-complete-display-prefix' |
| If set to 'on', menu completion displays the common prefix of |
| the list of possible completions (which may be empty) before |
| cycling through the list. The default is 'off'. |
| |
| 'output-meta' |
| If set to 'on', Readline will display characters with the |
| eighth bit set directly rather than as a meta-prefixed escape |
| sequence. The default is 'off', but Readline will set it to |
| 'on' if the locale contains eight-bit characters. |
| |
| 'page-completions' |
| If set to 'on', Readline uses an internal 'more'-like pager to |
| display a screenful of possible completions at a time. This |
| variable is 'on' by default. |
| |
| 'print-completions-horizontally' |
| If set to 'on', Readline will display completions with matches |
| sorted horizontally in alphabetical order, rather than down |
| the screen. The default is 'off'. |
| |
| 'revert-all-at-newline' |
| If set to 'on', Readline will undo all changes to history |
| lines before returning when 'accept-line' is executed. By |
| default, history lines may be modified and retain individual |
| undo lists across calls to 'readline'. The default is 'off'. |
| |
| 'show-all-if-ambiguous' |
| This alters the default behavior of the completion functions. |
| If set to 'on', words which have more than one possible |
| completion cause the matches to be listed immediately instead |
| of ringing the bell. The default value is 'off'. |
| |
| 'show-all-if-unmodified' |
| This alters the default behavior of the completion functions |
| in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to |
| 'on', words which have more than one possible completion |
| without any possible partial completion (the possible |
| completions don't share a common prefix) cause the matches to |
| be listed immediately instead of ringing the bell. The |
| default value is 'off'. |
| |
| 'show-mode-in-prompt' |
| If set to 'on', add a string to the beginning of the prompt |
| indicating the editing mode: emacs, vi command, or vi |
| insertion. The mode strings are user-settable (e.g., |
| EMACS-MODE-STRING). The default value is 'off'. |
| |
| 'skip-completed-text' |
| If set to 'on', this alters the default completion behavior |
| when inserting a single match into the line. It's only active |
| when performing completion in the middle of a word. If |
| enabled, readline does not insert characters from the |
| completion that match characters after point in the word being |
| completed, so portions of the word following the cursor are |
| not duplicated. For instance, if this is enabled, attempting |
| completion when the cursor is after the 'e' in 'Makefile' will |
| result in 'Makefile' rather than 'Makefilefile', assuming |
| there is a single possible completion. The default value is |
| 'off'. |
| |
| 'vi-cmd-mode-string' |
| If the SHOW-MODE-IN-PROMPT variable is enabled, this string is |
| displayed immediately before the last line of the primary |
| prompt when vi editing mode is active and in command mode. |
| The value is expanded like a key binding, so the standard set |
| of meta- and control prefixes and backslash escape sequences |
| is available. Use the '\1' and '\2' escapes to begin and end |
| sequences of non-printing characters, which can be used to |
| embed a terminal control sequence into the mode string. The |
| default is '(cmd)'. |
| |
| 'vi-ins-mode-string' |
| If the SHOW-MODE-IN-PROMPT variable is enabled, this string is |
| displayed immediately before the last line of the primary |
| prompt when vi editing mode is active and in insertion mode. |
| The value is expanded like a key binding, so the standard set |
| of meta- and control prefixes and backslash escape sequences |
| is available. Use the '\1' and '\2' escapes to begin and end |
| sequences of non-printing characters, which can be used to |
| embed a terminal control sequence into the mode string. The |
| default is '(ins)'. |
| |
| 'visible-stats' |
| If set to 'on', a character denoting a file's type is appended |
| to the filename when listing possible completions. The |
| default is 'off'. |
| |
| Key Bindings |
| The syntax for controlling key bindings in the init file is simple. |
| First you need to find the name of the command that you want to |
| change. The following sections contain tables of the command name, |
| the default keybinding, if any, and a short description of what the |
| command does. |
| |
| Once you know the name of the command, simply place on a line in |
| the init file the name of the key you wish to bind the command to, |
| a colon, and then the name of the command. There can be no space |
| between the key name and the colon - that will be interpreted as |
| part of the key name. The name of the key can be expressed in |
| different ways, depending on what you find most comfortable. |
| |
| In addition to command names, readline allows keys to be bound to a |
| string that is inserted when the key is pressed (a MACRO). |
| |
| KEYNAME: FUNCTION-NAME or MACRO |
| KEYNAME is the name of a key spelled out in English. For |
| example: |
| Control-u: universal-argument |
| Meta-Rubout: backward-kill-word |
| Control-o: "> output" |
| |
| In the example above, '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 |
| |
| 32.3.2 Conditional Init Constructs |
| ---------------------------------- |
| |
| Readline implements a facility similar in spirit to the conditional |
| compilation features of the C preprocessor which allows key bindings and |
| variable settings to be performed as the result of tests. There are |
| four parser directives used. |
| |
| '$if' |
| The '$if' construct allows bindings to be made based on the editing |
| mode, the terminal being used, or the application using Readline. |
| The text of the test, after any comparison operator, extends to the |
| end of the line; unless otherwise noted, 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. |
| |
| 'version' |
| The 'version' test may be used to perform comparisons against |
| specific Readline versions. The 'version' expands to the |
| current Readline version. The set of comparison operators |
| includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The |
| version number supplied on the right side of the operator |
| consists of a major version number, an optional decimal point, |
| and an optional minor version (e.g., '7.1'). If the minor |
| version is omitted, it is assumed to be '0'. The operator may |
| be separated from the string 'version' and from the version |
| number argument by whitespace. The following example sets a |
| variable if the Readline version being used is 7.0 or newer: |
| $if version >= 7.0 |
| set show-mode-in-prompt on |
| $endif |
| |
| '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 |
| |
| 'variable' |
| The VARIABLE construct provides simple equality tests for |
| Readline variables and values. The permitted comparison |
| operators are '=', '==', and '!='. The variable name must be |
| separated from the comparison operator by whitespace; the |
| operator may be separated from the value on the right hand |
| side by whitespace. Both string and boolean variables may be |
| tested. Boolean variables must be tested against the values |
| ON and OFF. The following example is equivalent to the |
| 'mode=emacs' test described above: |
| $if editing-mode == emacs |
| set show-mode-in-prompt on |
| $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 |
| |
| 32.3.3 Sample Init File |
| ----------------------- |
| |
| Here is an example of an INPUTRC file. This illustrates key binding, |
| variable assignment, and conditional syntax. |
| |
| # This file controls the behaviour of line input editing for |
| # programs that use the GNU Readline library. Existing |
| # programs include FTP, Bash, and GDB. |
| # |
| # You can re-read the inputrc file with C-x C-r. |
| # Lines beginning with '#' are comments. |
| # |
| # First, include any system-wide 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 |
| |
| 32.4 Bindable Readline Commands |
| =============================== |
| |
| * Menu: |
| |
| * Commands For Moving:: Moving about the line. |
| * Commands For History:: Getting at previous lines. |
| * Commands For Text:: Commands for changing text. |
| * Commands For Killing:: Commands for killing and yanking. |
| * Numeric Arguments:: Specifying numeric arguments, repeat counts. |
| * Commands For Completion:: Getting Readline to do the typing for you. |
| * Keyboard Macros:: Saving and re-executing typed characters |
| * Miscellaneous Commands:: Other miscellaneous commands. |
| |
| This section describes Readline commands that may be bound to key |
| sequences. Command names without an accompanying key sequence are |
| unbound by default. |
| |
| In the following descriptions, "point" refers to the current cursor |
| position, and "mark" refers to a cursor position saved by the 'set-mark' |
| command. The text between the point and mark is referred to as the |
| "region". |
| |
| |
| File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands |
| |
| 32.4.1 Commands For Moving |
| -------------------------- |
| |
| 'beginning-of-line (C-a)' |
| Move to the start of the current line. |
| |
| 'end-of-line (C-e)' |
| Move to the end of the line. |
| |
| 'forward-char (C-f)' |
| Move forward a character. |
| |
| 'backward-char (C-b)' |
| Move back a character. |
| |
| 'forward-word (M-f)' |
| Move forward to the end of the next word. Words are composed of |
| letters and digits. |
| |
| 'backward-word (M-b)' |
| Move back to the start of the current or previous word. Words are |
| composed of letters and digits. |
| |
| 'previous-screen-line ()' |
| Attempt to move point to the same physical screen column on the |
| previous physical screen line. This will not have the desired |
| effect if the current Readline line does not take up more than one |
| physical line or if point is not greater than the length of the |
| prompt plus the screen width. |
| |
| 'next-screen-line ()' |
| Attempt to move point to the same physical screen column on the |
| next physical screen line. This will not have the desired effect |
| if the current Readline line does not take up more than one |
| physical line or if the length of the current Readline line is not |
| greater than the length of the prompt plus the screen width. |
| |
| '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 |
| |
| 32.4.2 Commands For Manipulating The History |
| -------------------------------------------- |
| |
| 'accept-line (Newline or Return)' |
| Accept the line regardless of where the cursor is. If this line is |
| non-empty, it may be added to the history list for future recall |
| with 'add_history()'. If this line is a modified history line, the |
| history line is restored to its original state. |
| |
| 'previous-history (C-p)' |
| Move 'back' through the history list, fetching the previous |
| command. |
| |
| 'next-history (C-n)' |
| Move 'forward' through the history list, fetching the next command. |
| |
| 'beginning-of-history (M-<)' |
| Move to the first line in the history. |
| |
| 'end-of-history (M->)' |
| Move to the end of the input history, i.e., the line currently |
| being entered. |
| |
| 'reverse-search-history (C-r)' |
| Search backward starting at the current line and moving 'up' |
| through the history as necessary. This is an incremental search. |
| |
| 'forward-search-history (C-s)' |
| Search forward starting at the current line and moving 'down' |
| through the 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. The search string may match |
| anywhere in a history line. |
| |
| 'non-incremental-forward-search-history (M-n)' |
| Search forward starting at the current line and moving 'down' |
| through the history as necessary using a non-incremental search for |
| a string supplied by the user. The search string may match |
| anywhere in a history line. |
| |
| 'history-search-forward ()' |
| Search forward through the history for the string of characters |
| between the start of the current line and the point. The search |
| string must match at the beginning of a history line. 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. The search |
| string must match at the beginning of a history line. This is a |
| non-incremental search. By default, this command is unbound. |
| |
| 'history-substring-search-forward ()' |
| Search forward through the history for the string of characters |
| between the start of the current line and the point. The search |
| string may match anywhere in a history line. This is a |
| non-incremental search. By default, this command is unbound. |
| |
| 'history-substring-search-backward ()' |
| Search backward through the history for the string of characters |
| between the start of the current line and the point. The search |
| string may match anywhere in a history line. This is a |
| non-incremental search. By default, this command is unbound. |
| |
| 'yank-nth-arg (M-C-y)' |
| Insert the first argument to the previous command (usually the |
| second word on the previous line) at point. With an argument N, |
| insert the Nth word from the previous command (the words in the |
| previous command begin with word 0). A negative argument inserts |
| the Nth word from the end of the previous command. Once the |
| argument N is computed, the argument is extracted as if the '!N' |
| history expansion had been specified. |
| |
| 'yank-last-arg (M-. or M-_)' |
| Insert last argument to the previous command (the last word of the |
| previous history entry). With a numeric argument, behave exactly |
| like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back |
| through the history list, inserting the last word (or the word |
| specified by the argument to the first call) of each line in turn. |
| Any numeric argument supplied to these successive calls determines |
| the direction to move through the history. A negative argument |
| switches the direction through the history (back or forward). The |
| history expansion facilities are used to extract the last argument, |
| as if the '!$' history expansion had been specified. |
| |
| |
| File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands |
| |
| 32.4.3 Commands For Changing Text |
| --------------------------------- |
| |
| 'end-of-file (usually C-d)' |
| The character indicating end-of-file as set, for example, by |
| 'stty'. If this character is read when there are no characters on |
| the line, and point is at the beginning of the line, Readline |
| interprets it as the end of input and returns EOF. |
| |
| 'delete-char (C-d)' |
| Delete the character at point. If this function is bound to the |
| same character as the tty EOF character, as 'C-d' commonly is, see |
| above for the effects. |
| |
| '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. |
| |
| 'bracketed-paste-begin ()' |
| This function is intended to be bound to the "bracketed paste" |
| escape sequence sent by some terminals, and such a binding is |
| assigned by default. It allows Readline to insert the pasted text |
| as a single unit without treating each character as if it had been |
| read from the keyboard. The characters are inserted as if each one |
| was bound to 'self-insert' instead of executing any editing |
| commands. |
| |
| '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 |
| |
| 32.4.4 Killing And Yanking |
| -------------------------- |
| |
| 'kill-line (C-k)' |
| Kill the text from point to the end of the line. |
| |
| 'backward-kill-line (C-x Rubout)' |
| Kill backward from the cursor to the beginning of the current 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 |
| |
| 32.4.5 Specifying Numeric Arguments |
| ----------------------------------- |
| |
| 'digit-argument (M-0, M-1, ... M--)' |
| Add this digit to the argument already accumulating, or start a new |
| argument. 'M--' starts a negative argument. |
| |
| 'universal-argument ()' |
| This is another way to specify an argument. If this command is |
| followed by one or more digits, optionally with a leading minus |
| sign, those digits define the argument. If the command is followed |
| by digits, executing 'universal-argument' again ends the numeric |
| argument, but is otherwise ignored. As a special case, if this |
| command is immediately followed by a character that is neither a |
| digit nor 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 |
| |
| 32.4.6 Letting Readline Type For You |
| ------------------------------------ |
| |
| 'complete (<TAB>)' |
| Attempt to perform completion on the text before point. The actual |
| completion performed is application-specific. The default is |
| filename completion. |
| |
| 'possible-completions (M-?)' |
| List the possible completions of the text before point. When |
| displaying completions, Readline sets the number of columns used |
| for display to the value of 'completion-display-width', the value |
| of the environment variable 'COLUMNS', or the screen width, in that |
| order. |
| |
| 'insert-completions (M-*)' |
| Insert all completions of the text before point that would have |
| been generated by 'possible-completions'. |
| |
| 'menu-complete ()' |
| Similar to 'complete', but replaces the word to be completed with a |
| single match from the list of possible completions. Repeated |
| execution of 'menu-complete' steps through the list of possible |
| completions, inserting each match in turn. At the end of the list |
| of completions, the bell is rung (subject to the setting of |
| 'bell-style') and the original text is restored. An argument of N |
| moves N positions forward in the list of matches; a negative |
| argument may be used to move backward through the list. This |
| command is intended to be bound to <TAB>, but is unbound by |
| default. |
| |
| 'menu-complete-backward ()' |
| Identical to 'menu-complete', but moves backward through the list |
| of possible completions, as if 'menu-complete' had been given a |
| negative argument. |
| |
| 'delete-char-or-list ()' |
| Deletes the character under the cursor if not at the beginning or |
| end of the line (like 'delete-char'). If at the end of the line, |
| behaves identically to 'possible-completions'. This command is |
| unbound by default. |
| |
| |
| File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands |
| |
| 32.4.7 Keyboard Macros |
| ---------------------- |
| |
| 'start-kbd-macro (C-x ()' |
| Begin saving the characters typed into the current keyboard macro. |
| |
| 'end-kbd-macro (C-x ))' |
| Stop saving the characters typed into the current keyboard macro |
| and save the definition. |
| |
| 'call-last-kbd-macro (C-x e)' |
| Re-execute the last keyboard macro defined, by making the |
| characters in the macro appear as if typed at the keyboard. |
| |
| 'print-last-kbd-macro ()' |
| Print the last keboard macro defined in a format suitable for the |
| INPUTRC file. |
| |
| |
| File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands |
| |
| 32.4.8 Some Miscellaneous Commands |
| ---------------------------------- |
| |
| 're-read-init-file (C-x C-r)' |
| Read in the contents of the INPUTRC file, and incorporate any |
| bindings or variable assignments found there. |
| |
| 'abort (C-g)' |
| Abort the current editing command and ring the terminal's bell |
| (subject to the setting of 'bell-style'). |
| |
| 'do-lowercase-version (M-A, M-B, M-X, ...)' |
| If the metafied character X is upper case, run the command that is |
| bound to the corresponding metafied lower case character. The |
| behavior is undefined if X is already lower case. |
| |
| 'prefix-meta (<ESC>)' |
| Metafy the next character typed. This is for keyboards without a |
| meta key. Typing '<ESC> f' is equivalent to typing 'M-f'. |
| |
| 'undo (C-_ or C-x C-u)' |
| Incremental undo, separately remembered for each line. |
| |
| 'revert-line (M-r)' |
| Undo all changes made to this line. This is like executing the |
| 'undo' command enough times to get back to the beginning. |
| |
| 'tilde-expand (M-~)' |
| Perform tilde expansion on the current word. |
| |
| 'set-mark (C-@)' |
| Set the mark to the point. If a numeric argument is supplied, the |
| mark is set to that position. |
| |
| 'exchange-point-and-mark (C-x C-x)' |
| Swap the point with the mark. The current cursor position is set |
| to the saved position, and the old cursor position is saved as the |
| mark. |
| |
| 'character-search (C-])' |
| A character is read and point is moved to the next occurrence of |
| that character. A negative count searches for previous |
| occurrences. |
| |
| 'character-search-backward (M-C-])' |
| A character is read and point is moved to the previous occurrence |
| of that character. A negative count searches for subsequent |
| occurrences. |
| |
| 'skip-csi-sequence ()' |
| Read enough characters to consume a multi-key sequence such as |
| those defined for keys like Home and End. Such sequences begin |
| with a Control Sequence Indicator (CSI), usually ESC-[. If this |
| sequence is bound to "\e[", keys producing such sequences will have |
| no effect unless explicitly bound to a readline command, instead of |
| inserting stray characters into the editing buffer. This is |
| unbound by default, but usually bound to ESC-[. |
| |
| 'insert-comment (M-#)' |
| Without a numeric argument, the value of the 'comment-begin' |
| variable is inserted at the beginning of the current line. If a |
| numeric argument is supplied, this command acts as a toggle: if the |
| characters at the beginning of the line do not match the value of |
| 'comment-begin', the value is inserted, otherwise the characters in |
| 'comment-begin' are deleted from the beginning of the line. In |
| either case, the line is accepted as if a newline had been typed. |
| |
| 'dump-functions ()' |
| Print all of the functions and their key bindings to the Readline |
| output stream. If a numeric argument is supplied, the output is |
| formatted in such a way that it can be made part of an INPUTRC |
| file. This command is unbound by default. |
| |
| 'dump-variables ()' |
| Print all of the settable variables and their values to the |
| Readline output stream. If a numeric argument is supplied, the |
| output is formatted in such a way that it can be made part of an |
| INPUTRC file. This command is unbound by default. |
| |
| 'dump-macros ()' |
| Print all of the Readline key sequences bound to macros and the |
| strings they output. If a numeric argument is supplied, the output |
| is formatted in such a way that it can be made part of an INPUTRC |
| file. This command is unbound by default. |
| |
| 'emacs-editing-mode (C-e)' |
| When in 'vi' command mode, this causes a switch to 'emacs' editing |
| mode. |
| |
| 'vi-editing-mode (M-C-j)' |
| When in 'emacs' editing mode, this causes a switch to 'vi' editing |
| mode. |
| |
| |
| File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing |
| |
| 32.5 Readline vi Mode |
| ===================== |
| |
| While the Readline library does not have a full set of 'vi' editing |
| functions, it does contain enough to allow simple editing of the line. |
| The Readline 'vi' mode behaves as specified in the POSIX standard. |
| |
| In order to switch interactively between 'emacs' and 'vi' editing |
| modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' |
| mode and to vi-editing-mode in 'emacs' mode). The Readline default is |
| 'emacs' mode. |
| |
| When you enter a line in 'vi' mode, you are already placed in |
| 'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches |
| you into 'command' mode, where you can edit the text of the line with |
| the standard 'vi' movement keys, move to previous history lines with 'k' |
| and subsequent lines with 'j', and so forth. |
| |
| |
| File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top |
| |
| 33 Using History Interactively |
| ****************************** |
| |
| This chapter describes how to use the GNU History Library interactively, |
| from a user's standpoint. It should be considered a user's guide. For |
| information on using the GNU History Library in your own programs, *note |
| (history)Programming with GNU History::. |
| |
| * Menu: |
| |
| * History Interaction:: What it feels like using History as a user. |
| |
| |
| File: gdb.info, Node: History Interaction, Up: Using History Interactively |
| |
| 33.1 History Expansion |
| ====================== |
| |
| The History library provides a history expansion feature that is similar |
| to the history expansion provided by 'csh'. This section describes the |
| syntax used to manipulate the history information. |
| |
| History expansions introduce words from the history list into the |
| input stream, making it easy to repeat commands, insert the arguments to |
| a previous command into the current input line, or fix errors in |
| previous commands quickly. |
| |
| History expansion takes place in two parts. The first is to |
| determine which line from the history list should be used during |
| substitution. The second is to select portions of that line for |
| inclusion into the current one. The line selected from the history is |
| called the "event", and the portions of that line that are acted upon |
| are called "words". Various "modifiers" are available to manipulate the |
| selected words. The line is broken into words in the same fashion that |
| Bash does, so that several words surrounded by quotes are considered one |
| word. History expansions are introduced by the appearance of the |
| history expansion character, which is '!' by default. |
| |
| History expansion implements shell-like quoting conventions: a |
| backslash can be used to remove the special handling for the next |
| character; single quotes enclose verbatim sequences of characters, and |
| can be used to inhibit history expansion; and characters enclosed within |
| double quotes may be subject to history expansion, since backslash can |
| escape the history expansion character, but single quotes may not, since |
| they are not treated specially within double quotes. |
| |
| * 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 |
| |
| 33.1.1 Event Designators |
| ------------------------ |
| |
| An event designator is a reference to a command line entry in the |
| history list. Unless the reference is absolute, events are relative to |
| the current position in the history list. |
| |
| '!' |
| Start a history substitution, except when followed by a space, tab, |
| the end of the line, or '='. |
| |
| '!N' |
| Refer to command line N. |
| |
| '!-N' |
| Refer to the command N lines back. |
| |
| '!!' |
| Refer to the previous command. This is a synonym for '!-1'. |
| |
| '!STRING' |
| Refer to the most recent command preceding the current position in |
| the history list starting with STRING. |
| |
| '!?STRING[?]' |
| Refer to the most recent command preceding the current position in |
| the history list containing STRING. The trailing '?' may be |
| omitted if the STRING is followed immediately by a newline. |
| |
| '^STRING1^STRING2^' |
| Quick Substitution. Repeat the last command, replacing STRING1 |
| with STRING2. Equivalent to '!!:s/STRING1/STRING2/'. |
| |
| '!#' |
| The entire command line typed so far. |
| |
| |
| File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction |
| |
| 33.1.2 Word Designators |
| ----------------------- |
| |
| Word designators are used to select desired words from the event. A ':' |
| separates the event specification from the word designator. It may be |
| omitted if the word designator begins with a '^', '$', '*', '-', or '%'. |
| Words are numbered from the beginning of the line, with the first word |
| being denoted by 0 (zero). Words are inserted into the current line |
| separated by single spaces. |
| |
| For example, |
| |
| '!!' |
| designates the preceding command. When you type this, the |
| preceding command is repeated in toto. |
| |
| '!!:$' |
| designates the last argument of the preceding command. This may be |
| shortened to '!$'. |
| |
| '!fi:2' |
| designates the second argument of the most recent command starting |
| with the letters 'fi'. |
| |
| Here are the word designators: |
| |
| '0 (zero)' |
| The '0'th word. For many applications, this is the command word. |
| |
| 'N' |
| The Nth word. |
| |
| '^' |
| The first argument; that is, word 1. |
| |
| '$' |
| The last argument. |
| |
| '%' |
| The word matched by the most recent '?STRING?' search. |
| |
| 'X-Y' |
| A range of words; '-Y' abbreviates '0-Y'. |
| |
| '*' |
| All of the words, except the '0'th. This is a synonym for '1-$'. |
| It is not an error to use '*' if there is just one word in the |
| event; the empty string is returned in that case. |
| |
| 'X*' |
| Abbreviates 'X-$' |
| |
| 'X-' |
| Abbreviates 'X-$' like 'X*', but omits the last word. |
| |
| If a word designator is supplied without an event specification, the |
| previous command is used as the event. |
| |
| |
| File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction |
| |
| 33.1.3 Modifiers |
| ---------------- |
| |
| After the optional word designator, you can add a sequence of one or |
| more of the following modifiers, each preceded by a ':'. |
| |
| 'h' |
| Remove a trailing pathname component, leaving only the head. |
| |
| 't' |
| Remove all leading pathname components, leaving the tail. |
| |
| 'r' |
| Remove a trailing suffix of the form '.SUFFIX', leaving the |
| basename. |
| |
| 'e' |
| Remove all but the trailing suffix. |
| |
| 'p' |
| Print the new command but do not execute it. |
| |
| 's/OLD/NEW/' |
| Substitute NEW for the first occurrence of OLD in the event line. |
| Any delimiter may be used in place of '/'. The delimiter may be |
| quoted in OLD and NEW with a single backslash. If '&' appears in |
| NEW, it is replaced by OLD. A single backslash will quote the '&'. |
| The final delimiter is optional if it is the last character on the |
| input line. |
| |
| '&' |
| Repeat the previous substitution. |
| |
| 'g' |
| 'a' |
| Cause changes to be applied over the entire event line. Used in |
| conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. |
| |
| 'G' |
| Apply the following 's' modifier once to each word in the event. |
| |
| |
| File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top |
| |
| Appendix A In Memoriam |
| ********************** |
| |
| The GDB project mourns the loss of the following long-time contributors: |
| |
| 'Fred Fish' |
| Fred was a long-standing contributor to GDB (1991-2006), and to |
| Free Software in general. Outside of GDB, he was known in the |
| Amiga world for his series of Fish Disks, and the GeekGadget |
| project. |
| |
| 'Michael Snyder' |
| Michael was one of the Global Maintainers of the GDB project, with |
| contributions recorded as early as 1996, until 2011. In addition |
| to his day to day participation, he was a large driving force |
| behind adding Reverse Debugging to GDB. |
| |
| Beyond their technical contributions to the project, they were also |
| enjoyable members of the Free Software Community. We will miss them. |
| |
| |
| File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top |
| |
| Appendix B Formatting Documentation |
| *********************************** |
| |
| The GDB 4 release includes an already-formatted reference card, ready |
| for printing with PostScript or Ghostscript, in the 'gdb' subdirectory |
| of the main source directory(1). If you can use PostScript or |
| Ghostscript with your printer, you can print the reference card |
| immediately with 'refcard.ps'. |
| |
| The release also includes the source for the reference card. You can |
| format it, using TeX, by typing: |
| |
| make refcard.dvi |
| |
| The GDB reference card is designed to print in "landscape" mode on US |
| "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches |
| high. You will need to specify this form of printing as an option to |
| your DVI output program. |
| |
| All the documentation for GDB comes as part of the machine-readable |
| distribution. The documentation is written in Texinfo format, which is |
| a documentation system that uses a single source file to produce both |
| on-line information and a printed manual. You can use one of the Info |
| formatting commands to create the on-line version of the documentation |
| and TeX (or 'texi2roff') to typeset the printed version. |
| |
| GDB includes an already formatted copy of the on-line Info version of |
| this manual in the 'gdb' subdirectory. The main Info file is |
| 'gdb-9.1/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-9.1', in the case of version 9.1), you can make the Info |
| file by typing: |
| |
| cd gdb |
| make gdb.info |
| |
| If you want to typeset and print copies of this manual, you need TeX, |
| a program to print its DVI output files, and 'texinfo.tex', the Texinfo |
| definitions file. |
| |
| TeX is a typesetting program; it does not print files directly, but |
| produces output files called DVI files. To print a typeset document, |
| you need a program to print DVI files. If your system has TeX |
| installed, chances are it has such a program. The precise command to |
| use depends on your system; 'lpr -d' is common; another (for PostScript |
| devices) is 'dvips'. The DVI print command may require a file name |
| without any extension or a '.dvi' extension. |
| |
| TeX also requires a macro definitions file called 'texinfo.tex'. |
| This file tells TeX how to typeset a document written in Texinfo format. |
| On its own, TeX cannot either read or typeset a Texinfo file. |
| 'texinfo.tex' is distributed with GDB and is located in the |
| 'gdb-VERSION-NUMBER/texinfo' directory. |
| |
| If you have TeX and a DVI printer program installed, you can typeset |
| and print this manual. First switch to the 'gdb' subdirectory of the |
| main source directory (for example, to 'gdb-9.1/gdb') and type: |
| |
| make gdb.dvi |
| |
| Then give 'gdb.dvi' to your DVI printing program. |
| |
| ---------- Footnotes ---------- |
| |
| (1) In 'gdb-9.1/gdb/refcard.ps' of the version 9.1 release. |
| |
| |
| File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top |
| |
| Appendix C Installing GDB |
| ************************* |
| |
| * Menu: |
| |
| * Requirements:: Requirements for building GDB |
| * Running Configure:: Invoking the GDB 'configure' script |
| * Separate Objdir:: Compiling GDB in another directory |
| * Config Names:: Specifying names for hosts and targets |
| * Configure Options:: Summary of options for configure |
| * System-wide configuration:: Having a system-wide init file |
| |
| |
| File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB |
| |
| C.1 Requirements for Building GDB |
| ================================= |
| |
| Building GDB requires various tools and packages to be available. Other |
| packages will be used only if they are found. |
| |
| Tools/Packages Necessary for Building GDB |
| ========================================= |
| |
| C++11 compiler |
| GDB is written in C++11. It should be buildable with any recent |
| C++11 compiler, e.g. GCC. |
| |
| GNU make |
| GDB's build system relies on features only found in the GNU make |
| program. Other variants of 'make' will not work. |
| |
| Tools/Packages Optional for Building GDB |
| ======================================== |
| |
| Expat |
| GDB can use the Expat XML parsing library. This library may be |
| included with your operating system distribution; if it is not, you |
| can get the latest version from <http://expat.sourceforge.net>. |
| The 'configure' script will search for this library in several |
| standard locations; if it is installed in an unusual path, you can |
| use the '--with-libexpat-prefix' option to specify its location. |
| |
| Expat is used for: |
| |
| * Remote protocol memory maps (*note Memory Map Format::) |
| * Target descriptions (*note Target Descriptions::) |
| * Remote shared library lists (*Note Library List Format::, or |
| alternatively *note Library List Format for SVR4 Targets::) |
| * MS-Windows shared libraries (*note Shared Libraries::) |
| * Traceframe info (*note Traceframe Info Format::) |
| * Branch trace (*note Branch Trace Format::, *note Branch Trace |
| Configuration Format::) |
| |
| Guile |
| GDB can be scripted using GNU Guile. *Note Guile::. By default, |
| GDB will be compiled if the Guile libraries are installed and are |
| found by 'configure'. You can use the '--with-guile' option to |
| request Guile, and pass either the Guile version number or the file |
| name of the relevant 'pkg-config' program to choose a particular |
| version of Guile. |
| |
| iconv |
| GDB's features related to character sets (*note Character Sets::) |
| require a functioning 'iconv' implementation. If you are on a GNU |
| system, then this is provided by the GNU C Library. Some other |
| systems also provide a working 'iconv'. |
| |
| If GDB is using the 'iconv' program which is installed in a |
| non-standard place, you will need to tell GDB where to find it. |
| This is done with '--with-iconv-bin' which specifies the directory |
| that contains the 'iconv' program. This program is run in order to |
| make a list of the available character sets. |
| |
| On systems without 'iconv', you can install GNU Libiconv. If |
| Libiconv is installed in a standard place, GDB will automatically |
| use it if it is needed. If you have previously installed Libiconv |
| in a non-standard place, you can use the '--with-libiconv-prefix' |
| option to 'configure'. |
| |
| GDB's top-level 'configure' and 'Makefile' will arrange to build |
| Libiconv if a directory named 'libiconv' appears in the top-most |
| source directory. If Libiconv is built this way, and if the |
| operating system does not provide a suitable 'iconv' |
| implementation, then the just-built library will automatically be |
| used by GDB. One easy way to set this up is to download GNU |
| Libiconv, unpack it inside the top-level directory of the GDB |
| source tree, and then rename the directory holding the Libiconv |
| source code to 'libiconv'. |
| |
| lzma |
| GDB can support debugging sections that are compressed with the |
| LZMA library. *Note MiniDebugInfo::. If this library is not |
| included with your operating system, you can find it in the xz |
| package at <http://tukaani.org/xz/>. If the LZMA library is |
| available in the usual place, then the 'configure' script will use |
| it automatically. If it is installed in an unusual path, you can |
| use the '--with-lzma-prefix' option to specify its location. |
| |
| MPFR |
| GDB can use the GNU MPFR multiple-precision floating-point library. |
| This library may be included with your operating system |
| distribution; if it is not, you can get the latest version from |
| <http://www.mpfr.org>. 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-libmpfr-prefix' option to |
| specify its location. |
| |
| GNU MPFR is used to emulate target floating-point arithmetic during |
| expression evaluation when the target uses different floating-point |
| formats than the host. If GNU MPFR it is not available, GDB will |
| fall back to using host floating-point arithmetic. |
| |
| Python |
| GDB can be scripted using Python language. *Note Python::. By |
| default, GDB will be compiled if the Python libraries are installed |
| and are found by 'configure'. You can use the '--with-python' |
| option to request Python, and pass either the file name of the |
| relevant 'python' executable, or the name of the directory in which |
| Python is installed, to choose a particular installation of Python. |
| |
| zlib |
| GDB will use the 'zlib' library, if available, to read compressed |
| debug sections. Some linkers, such as GNU gold, are capable of |
| producing binaries with compressed debug sections. If GDB is |
| compiled with 'zlib', it will be able to read the debug information |
| in such binaries. |
| |
| The 'zlib' library is likely included with your operating system |
| distribution; if it is not, you can get the latest version from |
| <http://zlib.net>. |
| |
| |
| File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB |
| |
| C.2 Invoking the GDB 'configure' Script |
| ======================================= |
| |
| GDB comes with a 'configure' script that automates the process of |
| preparing GDB for installation; you can then use 'make' to build the |
| 'gdb' program. |
| |
| The GDB distribution includes all the source code you need for GDB in |
| a single directory, whose name is usually composed by appending the |
| version number to 'gdb'. |
| |
| For example, the GDB version 9.1 distribution is in the 'gdb-9.1' |
| directory. That directory contains: |
| |
| 'gdb-9.1/configure (and supporting files)' |
| script for configuring GDB and all its supporting libraries |
| |
| 'gdb-9.1/gdb' |
| the source specific to GDB itself |
| |
| 'gdb-9.1/bfd' |
| source for the Binary File Descriptor library |
| |
| 'gdb-9.1/include' |
| GNU include files |
| |
| 'gdb-9.1/libiberty' |
| source for the '-liberty' free software library |
| |
| 'gdb-9.1/opcodes' |
| source for the library of opcode tables and disassemblers |
| |
| 'gdb-9.1/readline' |
| source for the GNU command-line interface |
| |
| There may be other subdirectories as well. |
| |
| 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-9.1' 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-9.1 |
| ./configure |
| make |
| |
| Running 'configure' and then running 'make' builds the included |
| supporting 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 |
| |
| 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. The best way to do this is to pass |
| the '--prefix' option to 'configure', and then install it with 'make |
| install'. |
| |
| |
| File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB |
| |
| C.3 Compiling GDB in Another Directory |
| ====================================== |
| |
| If you want to run GDB versions for several host or target machines, you |
| need a different 'gdb' compiled for each combination of host and target. |
| 'configure' is designed to make this easy by allowing you to generate |
| each configuration in a separate subdirectory, rather than in the source |
| directory. If your 'make' program handles the 'VPATH' feature (GNU |
| 'make' does), running 'make' in each of these directories builds the |
| 'gdb' program specified there. |
| |
| To build 'gdb' in a separate directory, run 'configure' with the |
| '--srcdir' option to specify where to find the source. (You also need |
| to specify a path to find 'configure' itself from your working |
| directory. If the path to 'configure' would be the same as the argument |
| to '--srcdir', you can leave out the '--srcdir' option; it is assumed.) |
| |
| For example, with version 9.1, you can build GDB in a separate |
| directory for a Sun 4 like this: |
| |
| cd gdb-9.1 |
| mkdir ../gdb-sun4 |
| cd ../gdb-sun4 |
| ../gdb-9.1/configure |
| 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-9.1/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-9.1' (or in a separate configured directory configured with |
| '--srcdir=DIRNAME/gdb-9.1'), 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 |
| |
| C.4 Specifying Names for Hosts and Targets |
| ========================================== |
| |
| The specifications used for hosts and targets in the 'configure' script |
| are based on a three-part naming scheme, but some short predefined |
| aliases are also supported. The full naming scheme encodes three pieces |
| of information in the following pattern: |
| |
| ARCHITECTURE-VENDOR-OS |
| |
| For example, you can use the alias 'sun4' as a HOST argument, or as |
| the value for TARGET in a '--target=TARGET' option. The equivalent full |
| name is 'sparc-sun-sunos4'. |
| |
| The 'configure' script accompanying GDB does not provide any query |
| facility to list all supported host and target names or aliases. |
| 'configure' calls the Bourne shell script 'config.sub' to map |
| abbreviations to full names; you can read the script, if you wish, or |
| you can use it to test your guesses on abbreviations--for example: |
| |
| % sh config.sub i386-linux |
| i386-pc-linux-gnu |
| % sh config.sub alpha-linux |
| alpha-unknown-linux-gnu |
| % sh config.sub hp9k700 |
| hppa1.1-hp-hpux |
| % sh config.sub sun4 |
| sparc-sun-sunos4.1.1 |
| % sh config.sub sun3 |
| m68k-sun-sunos4.1.1 |
| % sh config.sub i986v |
| Invalid configuration `i986v': machine `i986v' not recognized |
| |
| 'config.sub' is also distributed in the GDB source directory ('gdb-9.1', |
| for version 9.1). |
| |
| |
| File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB |
| |
| C.5 'configure' Options |
| ======================= |
| |
| Here is a summary of the 'configure' options and arguments that are most |
| often useful for building GDB. 'configure' also has several other |
| options not listed here. *note (autoconf.info)Running configure |
| scripts::, for a full explanation of 'configure'. |
| |
| configure [--help] |
| [--prefix=DIR] |
| [--exec-prefix=DIR] |
| [--srcdir=DIRNAME] |
| [--target=TARGET] |
| |
| 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' |
| 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. |
| |
| '--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. Also see the '--enable-targets' option, below. |
| |
| There are many other options that are specific to GDB. This lists |
| just the most common ones; there are some very specialized options not |
| described here. |
| |
| '--enable-targets=[TARGET]...' |
| '--enable-targets=all' |
| Configure GDB for cross-debugging programs running on the specified |
| list of targets. The special value 'all' configures GDB for |
| debugging programs running on any target it supports. |
| |
| '--with-gdb-datadir=PATH' |
| Set the GDB-specific data directory. GDB will look here for |
| certain supporting files or scripts. This defaults to the 'gdb' |
| subdirectory of 'datadir' (which can be set using '--datadir'). |
| |
| '--with-relocated-sources=DIR' |
| Sets up the default source path substitution rule so that directory |
| names recorded in debug information will be automatically adjusted |
| for any directory under DIR. DIR should be a subdirectory of GDB's |
| configured prefix, the one mentioned in the '--prefix' or |
| '--exec-prefix' options to configure. This option is useful if GDB |
| is supposed to be moved to a different place after it is built. |
| |
| '--enable-64-bit-bfd' |
| Enable 64-bit support in BFD on 32-bit hosts. |
| |
| '--disable-gdbmi' |
| Build GDB without the GDB/MI machine interface (*note GDB/MI::). |
| |
| '--enable-tui' |
| Build GDB with the text-mode full-screen user interface (TUI). |
| Requires a curses library (ncurses and cursesX are also supported). |
| |
| '--with-curses' |
| Use the curses library instead of the termcap library, for |
| text-mode terminal operations. |
| |
| '--with-libunwind-ia64' |
| Use the libunwind library for unwinding function call stack on ia64 |
| target platforms. See http://www.nongnu.org/libunwind/index.html |
| for details. |
| |
| '--with-system-readline' |
| Use the readline library installed on the host, rather than the |
| library supplied as part of GDB. Readline 7 or newer is required; |
| this is enforced by the build system. |
| |
| '--with-system-zlib' |
| Use the zlib library installed on the host, rather than the library |
| supplied as part of GDB. |
| |
| '--with-expat' |
| Build GDB with Expat, a library for XML parsing. (Done by default |
| if libexpat is installed and found at configure time.) This |
| library is used to read XML files supplied with GDB. If it is |
| unavailable, some features, such as remote protocol memory maps, |
| target descriptions, and shared library lists, that are based on |
| XML files, will not be available in GDB. If your host does not |
| have libexpat installed, you can get the latest version from |
| 'http://expat.sourceforge.net'. |
| |
| '--with-libiconv-prefix[=DIR]' |
| |
| Build GDB with GNU libiconv, a character set encoding conversion |
| library. This is not done by default, as on GNU systems the |
| 'iconv' that is built in to the C library is sufficient. If your |
| host does not have a working 'iconv', you can get the latest |
| version of GNU iconv from 'https://www.gnu.org/software/libiconv/'. |
| |
| GDB's build system also supports building GNU libiconv as part of |
| the overall build. *Note Requirements::. |
| |
| '--with-lzma' |
| Build GDB with LZMA, a compression library. (Done by default if |
| liblzma is installed and found at configure time.) LZMA is used by |
| GDB's "mini debuginfo" feature, which is only useful on platforms |
| using the ELF object file format. If your host does not have |
| liblzma installed, you can get the latest version from |
| 'https://tukaani.org/xz/'. |
| |
| '--with-mpfr' |
| Build GDB with GNU MPFR, a library for multiple-precision |
| floating-point computation with correct rounding. (Done by default |
| if GNU MPFR is installed and found at configure time.) This |
| library is used to emulate target floating-point arithmetic during |
| expression evaluation when the target uses different floating-point |
| formats than the host. If GNU MPFR is not available, GDB will fall |
| back to using host floating-point arithmetic. If your host does |
| not have GNU MPFR installed, you can get the latest version from |
| 'http://www.mpfr.org'. |
| |
| '--with-python[=PYTHON]' |
| Build GDB with Python scripting support. (Done by default if |
| libpython is present and found at configure time.) Python makes |
| GDB scripting much more powerful than the restricted CLI scripting |
| language. If your host does not have Python installed, you can |
| find it on 'http://www.python.org/download/'. The oldest version |
| of Python supported by GDB is 2.6. The optional argument PYTHON is |
| used to find the Python headers and libraries. It can be either |
| the name of a Python executable, or the name of the directory in |
| which Python is installed. |
| |
| '--with-guile[=GUILE]'' |
| Build GDB with GNU Guile scripting support. (Done by default if |
| libguile is present and found at configure time.) If your host |
| does not have Guile installed, you can find it at |
| 'https://www.gnu.org/software/guile/'. The optional argument GUILE |
| can be a version number, which will cause 'configure' to try to use |
| that version of Guile; or the file name of a 'pkg-config' |
| executable, which will be queried to find the information needed to |
| compile and link against Guile. |
| |
| '--without-included-regex' |
| Don't use the regex library included with GDB (as part of the |
| libiberty library). This is the default on hosts with version 2 of |
| the GNU C library. |
| |
| '--with-sysroot=DIR' |
| Use DIR as the default system root directory for libraries whose |
| file names begin with '/lib'' or '/usr/lib''. (The value of DIR |
| can be modified at run time by using the 'set sysroot' command.) |
| If DIR is under the GDB configured prefix (set with '--prefix' or |
| '--exec-prefix options', the default system root will be |
| automatically adjusted if and when GDB is moved to a different |
| location. |
| |
| '--with-system-gdbinit=FILE' |
| Configure GDB to automatically load a system-wide init file. FILE |
| should be an absolute file name. If FILE is in a directory under |
| the configured prefix, and GDB is moved to another location after |
| being built, the location of the system-wide init file will be |
| adjusted accordingly. |
| |
| '--with-system-gdbinit-dir=DIRECTORY' |
| Configure GDB to automatically load init files from a system-wide |
| directory. DIRECTORY should be an absolute directory name. If |
| DIRECTORY is in a directory under the configured prefix, and GDB is |
| moved to another location after being built, the location of the |
| system-wide init directory will be adjusted accordingly. |
| |
| '--enable-build-warnings' |
| When building the GDB sources, ask the compiler to warn about any |
| code which looks even vaguely suspicious. It passes many different |
| warning flags, depending on the exact version of the compiler you |
| are using. |
| |
| '--enable-werror' |
| Treat compiler warnings as werrors. It adds the '-Werror' flag to |
| the compiler, which will fail the compilation if the compiler |
| outputs any warning messages. |
| |
| '--enable-ubsan' |
| Enable the GCC undefined behavior sanitizer. This is disabled by |
| default, but passing '--enable-ubsan=yes' or '--enable-ubsan=auto' |
| to 'configure' will enable it. The undefined behavior sanitizer |
| checks for C++ undefined behavior. It has a performance cost, so |
| if you are looking at GDB's performance, you should disable it. |
| The undefined behavior sanitizer was first introduced in GCC 4.9. |
| |
| |
| File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB |
| |
| C.6 System-wide configuration and settings |
| ========================================== |
| |
| GDB can be configured to have a system-wide init file and a system-wide |
| init file directory; this file and files in that directory (if they have |
| a recognized file extension) will be read and executed at startup (*note |
| What GDB does during startup: Startup.). |
| |
| Here are the corresponding configure options: |
| |
| '--with-system-gdbinit=FILE' |
| Specify that the default location of the system-wide init file is |
| FILE. |
| '--with-system-gdbinit-dir=DIRECTORY' |
| Specify that the default location of the system-wide init file |
| directory is DIRECTORY. |
| |
| If GDB has been configured with the option '--prefix=$prefix', they |
| may be subject to relocation. Two possible cases: |
| |
| * If the default location of this init file/directory contains |
| '$prefix', it will be subject to relocation. Suppose that the |
| configure options are '--prefix=$prefix |
| --with-system-gdbinit=$prefix/etc/gdbinit'; if GDB is moved from |
| '$prefix' to '$install', the system init file is looked for as |
| '$install/etc/gdbinit' instead of '$prefix/etc/gdbinit'. |
| |
| * By contrast, if the default location does not contain the prefix, |
| it will not be relocated. E.g. if GDB has been configured with |
| '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', |
| then GDB will always look for '/usr/share/gdb/gdbinit', wherever |
| GDB is installed. |
| |
| If the configured location of the system-wide init file (as given by |
| the '--with-system-gdbinit' option at configure time) is in the |
| data-directory (as specified by '--with-gdb-datadir' at configure time) |
| or in one of its subdirectories, then GDB will look for the system-wide |
| init file in the directory specified by the '--data-directory' |
| command-line option. Note that the system-wide init file is only read |
| once, during GDB initialization. If the data-directory is changed after |
| GDB has started with the 'set data-directory' command, the file will not |
| be reread. |
| |
| This applies similarly to the system-wide directory specified in |
| '--with-system-gdbinit-dir'. |
| |
| Any supported scripting language can be used for these init files, as |
| long as the file extension matches the scripting language. To be |
| interpreted as regular GDB commands, the files needs to have a '.gdb' |
| extension. |
| |
| * Menu: |
| |
| * System-wide Configuration Scripts:: Installed System-wide Configuration Scripts |
| |
| |
| File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration |
| |
| C.6.1 Installed System-wide Configuration Scripts |
| ------------------------------------------------- |
| |
| The 'system-gdbinit' directory, located inside the data-directory (as |
| specified by '--with-gdb-datadir' at configure time) contains a number |
| of scripts which can be used as system-wide init files. To |
| automatically source those scripts at startup, GDB should be configured |
| with '--with-system-gdbinit'. Otherwise, any user should be able to |
| source them by hand as needed. |
| |
| The following scripts are currently available: |
| |
| * 'elinos.py' This script is useful when debugging a program on an |
| ELinOS target. It takes advantage of the environment variables |
| defined in a standard ELinOS environment in order to determine the |
| location of the system shared libraries, and then sets the |
| 'solib-absolute-prefix' and 'solib-search-path' variables |
| appropriately. |
| |
| * 'wrs-linux.py' This script is useful when debugging a program on a |
| target running Wind River Linux. It expects the 'ENV_PREFIX' to be |
| set to the host-side sysroot used by the target system. |
| |
| |
| File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top |
| |
| Appendix D Maintenance Commands |
| ******************************* |
| |
| In addition to commands intended for GDB users, GDB includes a number of |
| commands intended for GDB developers, that are not documented elsewhere |
| in this manual. These commands are provided here for reference. (For |
| commands that turn on debugging messages, see *note Debugging Output::.) |
| |
| 'maint agent [-at LOCATION,] EXPRESSION' |
| 'maint agent-eval [-at LOCATION,] EXPRESSION' |
| Translate the given EXPRESSION into remote agent bytecodes. This |
| command is useful for debugging the Agent Expression mechanism |
| (*note Agent Expressions::). The 'agent' version produces an |
| expression useful for data collection, such as by tracepoints, |
| while 'maint agent-eval' produces an expression that evaluates |
| directly to a result. For instance, a collection expression for |
| 'globa + globb' will include bytecodes to record four bytes of |
| memory at each of the addresses of 'globa' and 'globb', while |
| discarding the result of the addition, while an evaluation |
| expression will do the addition and return the sum. If '-at' is |
| given, generate remote agent bytecode for LOCATION. If not, |
| generate remote agent bytecode for current frame PC address. |
| |
| 'maint agent-printf FORMAT,EXPR,...' |
| Translate the given format string and list of argument expressions |
| into remote agent bytecodes and display them as a disassembled |
| list. This command is useful for debugging the agent version of |
| dynamic printf (*note Dynamic Printf::). |
| |
| 'maint info breakpoints' |
| Using the same format as 'info breakpoints', display both the |
| breakpoints you've set explicitly, and those GDB is using for |
| internal purposes. Internal breakpoints are shown with negative |
| breakpoint numbers. The type column identifies what kind of |
| breakpoint is shown: |
| |
| 'breakpoint' |
| Normal, explicitly set breakpoint. |
| |
| 'watchpoint' |
| Normal, explicitly set watchpoint. |
| |
| 'longjmp' |
| Internal breakpoint, used to handle correctly stepping through |
| 'longjmp' calls. |
| |
| 'longjmp resume' |
| Internal breakpoint at the target of a 'longjmp'. |
| |
| 'until' |
| Temporary internal breakpoint used by the GDB 'until' command. |
| |
| 'finish' |
| Temporary internal breakpoint used by the GDB 'finish' |
| command. |
| |
| 'shlib events' |
| Shared library events. |
| |
| 'maint info btrace' |
| Pint information about raw branch tracing data. |
| |
| 'maint btrace packet-history' |
| Print the raw branch trace packets that are used to compute the |
| execution history for the 'record btrace' command. Both the |
| information and the format in which it is printed depend on the |
| btrace recording format. |
| |
| 'bts' |
| For the BTS recording format, print a list of blocks of |
| sequential code. For each block, the following information is |
| printed: |
| |
| Block number |
| Newer blocks have higher numbers. The oldest block has |
| number zero. |
| Lowest 'PC' |
| Highest 'PC' |
| |
| 'pt' |
| For the Intel Processor Trace recording format, print a list |
| of Intel Processor Trace packets. For each packet, the |
| following information is printed: |
| |
| Packet number |
| Newer packets have higher numbers. The oldest packet has |
| number zero. |
| Trace offset |
| The packet's offset in the trace stream. |
| Packet opcode and payload |
| |
| 'maint btrace clear-packet-history' |
| Discards the cached packet history printed by the 'maint btrace |
| packet-history' command. The history will be computed again when |
| needed. |
| |
| 'maint btrace clear' |
| Discard the branch trace data. The data will be fetched anew and |
| the branch trace will be recomputed when needed. |
| |
| This implicitly truncates the branch trace to a single branch trace |
| buffer. When updating branch trace incrementally, the branch trace |
| available to GDB may be bigger than a single branch trace buffer. |
| |
| 'maint set btrace pt skip-pad' |
| 'maint show btrace pt skip-pad' |
| Control whether GDB will skip PAD packets when computing the packet |
| history. |
| |
| 'set displaced-stepping' |
| 'show displaced-stepping' |
| Control whether or not GDB will do "displaced stepping" if the |
| target supports it. Displaced stepping is a way to single-step |
| over breakpoints without removing them from the inferior, by |
| executing an out-of-line copy of the instruction that was |
| originally at the breakpoint location. It is also known as |
| out-of-line single-stepping. |
| |
| 'set displaced-stepping on' |
| If the target architecture supports it, GDB will use displaced |
| stepping to step over breakpoints. |
| |
| 'set displaced-stepping off' |
| GDB will not use displaced stepping to step over breakpoints, |
| even if such is supported by the target architecture. |
| |
| 'set displaced-stepping auto' |
| This is the default mode. GDB will use displaced stepping |
| only if non-stop mode is active (*note Non-Stop Mode::) and |
| the target architecture supports displaced stepping. |
| |
| 'maint check-psymtabs' |
| Check the consistency of currently expanded psymtabs versus |
| symtabs. Use this to check, for example, whether a symbol is in |
| one but not the other. |
| |
| 'maint check-symtabs' |
| Check the consistency of currently expanded symtabs. |
| |
| 'maint expand-symtabs [REGEXP]' |
| Expand symbol tables. If REGEXP is specified, only expand symbol |
| tables for file names matching REGEXP. |
| |
| 'maint set catch-demangler-crashes [on|off]' |
| 'maint show catch-demangler-crashes' |
| Control whether GDB should attempt to catch crashes in the symbol |
| name demangler. The default is to attempt to catch crashes. If |
| enabled, the first time a crash is caught, a core file is created, |
| the offending symbol is displayed and the user is presented with |
| the option to terminate the current session. |
| |
| 'maint cplus first_component NAME' |
| Print the first C++ class/namespace component of NAME. |
| |
| 'maint cplus namespace' |
| Print the list of possible C++ namespaces. |
| |
| 'maint deprecate COMMAND [REPLACEMENT]' |
| 'maint undeprecate COMMAND' |
| Deprecate or undeprecate the named COMMAND. Deprecated commands |
| cause GDB to issue a warning when you use them. The optional |
| argument REPLACEMENT says which newer command should be used in |
| favor of the deprecated one; if it is given, GDB will mention the |
| replacement as part of the warning. |
| |
| 'maint dump-me' |
| Cause a fatal signal in the debugger and force it to dump its core. |
| This is supported only on systems which support aborting a program |
| with the 'SIGQUIT' signal. |
| |
| 'maint internal-error [MESSAGE-TEXT]' |
| 'maint internal-warning [MESSAGE-TEXT]' |
| 'maint demangler-warning [MESSAGE-TEXT]' |
| |
| Cause GDB to call the internal function 'internal_error', |
| 'internal_warning' or 'demangler_warning' and hence behave as |
| though an internal problem has been detected. In addition to |
| reporting the internal problem, these functions give the user the |
| opportunity to either quit GDB or (for 'internal_error' and |
| 'internal_warning') create a core file of the current GDB session. |
| |
| These commands take an optional parameter MESSAGE-TEXT that is used |
| as the text of the error or warning message. |
| |
| Here's an example of using 'internal-error': |
| |
| (gdb) maint internal-error testing, 1, 2 |
| .../maint.c:121: internal-error: testing, 1, 2 |
| A problem internal to GDB has been detected. Further |
| debugging may prove unreliable. |
| Quit this debugging session? (y or n) n |
| Create a core file? (y or n) n |
| (gdb) |
| |
| 'maint set internal-error ACTION [ask|yes|no]' |
| 'maint show internal-error ACTION' |
| 'maint set internal-warning ACTION [ask|yes|no]' |
| 'maint show internal-warning ACTION' |
| 'maint set demangler-warning ACTION [ask|yes|no]' |
| 'maint show demangler-warning ACTION' |
| When GDB reports an internal problem (error or warning) it gives |
| the user the opportunity to both quit GDB and create a core file of |
| the current GDB session. These commands let you override the |
| default behaviour for each particular ACTION, described in the |
| table below. |
| |
| 'quit' |
| You can specify that GDB should always (yes) or never (no) |
| quit. The default is to ask the user what to do. |
| |
| 'corefile' |
| You can specify that GDB should always (yes) or never (no) |
| create a core file. The default is to ask the user what to |
| do. Note that there is no 'corefile' option for |
| 'demangler-warning': demangler warnings always create a core |
| file and this cannot be disabled. |
| |
| 'maint packet TEXT' |
| If GDB is talking to an inferior via the serial protocol, then this |
| command sends the string TEXT to the inferior, and displays the |
| response packet. GDB supplies the initial '$' character, the |
| terminating '#' character, and the checksum. |
| |
| 'maint print architecture [FILE]' |
| Print the entire architecture configuration. The optional argument |
| FILE names the file where the output goes. |
| |
| 'maint print c-tdesc' |
| Print the target description (*note Target Descriptions::) as a C |
| source file. By default, the target description is for the current |
| target, but if the optional argument FILE is provided, that file is |
| used to produce the description. The FILE should be an XML |
| document, of the form described in *note Target Description |
| Format::. The created source file is built into GDB when GDB is |
| built again. This command is used by developers after they add or |
| modify XML target descriptions. |
| |
| 'maint check xml-descriptions DIR' |
| Check that the target descriptions dynamically created by GDB equal |
| the descriptions created from XML files found in DIR. |
| |
| 'maint check libthread-db' |
| Run integrity checks on the current inferior's thread debugging |
| library. This exercises all 'libthread_db' functionality used by |
| GDB on GNU/Linux systems, and by extension also exercises the |
| 'proc_service' functions provided by GDB that 'libthread_db' uses. |
| Note that parts of the test may be skipped on some platforms when |
| debugging core files. |
| |
| 'maint print dummy-frames' |
| Prints the contents of GDB's internal dummy-frame stack. |
| |
| (gdb) b add |
| ... |
| (gdb) print add(2,3) |
| Breakpoint 2, add (a=2, b=3) at ... |
| 58 return (a + b); |
| The program being debugged stopped while in a function called from GDB. |
| ... |
| (gdb) maint print dummy-frames |
| 0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353 |
| (gdb) |
| |
| Takes an optional file parameter. |
| |
| 'maint print registers [FILE]' |
| 'maint print raw-registers [FILE]' |
| 'maint print cooked-registers [FILE]' |
| 'maint print register-groups [FILE]' |
| 'maint print remote-registers [FILE]' |
| Print GDB's internal register data structures. |
| |
| The command 'maint print raw-registers' includes the contents of |
| the raw register cache; the command 'maint print cooked-registers' |
| includes the (cooked) value of all registers, including registers |
| which aren't available on the target nor visible to user; the |
| command 'maint print register-groups' includes the groups that each |
| register is a member of; and the command 'maint print |
| remote-registers' includes the remote target's register numbers and |
| offsets in the 'G' packets. |
| |
| These commands take an optional parameter, a file name to which to |
| write the information. |
| |
| 'maint print reggroups [FILE]' |
| Print GDB's internal register group data structures. The optional |
| argument FILE tells to what file to write the information. |
| |
| The register groups info looks like this: |
| |
| (gdb) maint print reggroups |
| Group Type |
| general user |
| float user |
| all user |
| vector user |
| system user |
| save internal |
| restore internal |
| |
| 'flushregs' |
| This command forces GDB to flush its internal register cache. |
| |
| 'maint print objfiles [REGEXP]' |
| Print a dump of all known object files. If REGEXP is specified, |
| only print object files whose names match REGEXP. For each object |
| file, this command prints its name, address in memory, and all of |
| its psymtabs and symtabs. |
| |
| 'maint print user-registers' |
| List all currently available "user registers". User registers |
| typically provide alternate names for actual hardware registers. |
| They include the four "standard" registers '$fp', '$pc', '$sp', and |
| '$ps'. *Note standard registers::. User registers can be used in |
| expressions in the same way as the canonical register names, but |
| only the latter are listed by the 'info registers' and 'maint print |
| registers' commands. |
| |
| 'maint print section-scripts [REGEXP]' |
| Print a dump of scripts specified in the '.debug_gdb_section' |
| section. If REGEXP is specified, only print scripts loaded by |
| object files matching REGEXP. For each script, this command prints |
| its name as specified in the objfile, and the full path if known. |
| *Note dotdebug_gdb_scripts section::. |
| |
| 'maint print statistics' |
| This command prints, for each object file in the program, various |
| data about that object file followed by the byte cache ("bcache") |
| statistics for the object file. The objfile data includes the |
| number of minimal, partial, full, and stabs symbols, the number of |
| types defined by the objfile, the number of as yet unexpanded psym |
| tables, the number of line tables and string tables, and the amount |
| of memory used by the various tables. The bcache statistics |
| include the counts, sizes, and counts of duplicates of all and |
| unique objects, max, average, and median entry size, total memory |
| used and its overhead and savings, and various measures of the hash |
| table size and chain lengths. |
| |
| 'maint print target-stack' |
| A "target" is an interface between the debugger and a particular |
| kind of file or process. Targets can be stacked in "strata", so |
| that more than one target can potentially respond to a request. In |
| particular, memory accesses will walk down the stack of targets |
| until they find a target that is interested in handling that |
| particular address. |
| |
| This command prints a short description of each layer that was |
| pushed on the "target stack", starting from the top layer down to |
| the bottom one. |
| |
| 'maint print type EXPR' |
| Print the type chain for a type specified by EXPR. The argument |
| can be either a type name or a symbol. If it is a symbol, the type |
| of that symbol is described. The type chain produced by this |
| command is a recursive definition of the data type as stored in |
| GDB's data structures, including its flags and contained types. |
| |
| 'maint selftest [FILTER]' |
| Run any self tests that were compiled in to GDB. This will print a |
| message showing how many tests were run, and how many failed. If a |
| FILTER is passed, only the tests with FILTER in their name will by |
| ran. |
| |
| 'maint info selftests' |
| List the selftests compiled in to GDB. |
| |
| 'maint set dwarf always-disassemble' |
| 'maint show dwarf always-disassemble' |
| Control the behavior of 'info address' when using DWARF debugging |
| information. |
| |
| The default is 'off', which means that GDB should try to describe a |
| variable's location in an easily readable format. When 'on', GDB |
| will instead display the DWARF location expression in an |
| assembly-like format. Note that some locations are too complex for |
| GDB to describe simply; in this case you will always see the |
| disassembly form. |
| |
| Here is an example of the resulting disassembly: |
| |
| (gdb) info addr argc |
| Symbol "argc" is a complex DWARF expression: |
| 1: DW_OP_fbreg 0 |
| |
| For more information on these expressions, see the DWARF standard |
| (http://www.dwarfstd.org/). |
| |
| 'maint set dwarf max-cache-age' |
| 'maint show dwarf max-cache-age' |
| Control the DWARF compilation unit cache. |
| |
| In object files with inter-compilation-unit references, such as |
| those produced by the GCC option '-feliminate-dwarf2-dups', the |
| DWARF 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 dwarf unwinders' |
| 'maint show dwarf unwinders' |
| Control use of the DWARF frame unwinders. |
| |
| Many targets that support DWARF debugging use GDB's DWARF frame |
| unwinders to build the backtrace. Many of these targets will also |
| have a second mechanism for building the backtrace for use in cases |
| where DWARF information is not available, this second mechanism is |
| often an analysis of a function's prologue. |
| |
| In order to extend testing coverage of the second level stack |
| unwinding mechanisms it is helpful to be able to disable the DWARF |
| stack unwinders, this can be done with this switch. |
| |
| In normal use of GDB disabling the DWARF unwinders is not |
| advisable, there are cases that are better handled through DWARF |
| than prologue analysis, and the debug experience is likely to be |
| better with the DWARF frame unwinders enabled. |
| |
| If DWARF frame unwinders are not supported for a particular target |
| architecture, then enabling this flag does not cause them to be |
| used. |
| |
| 'maint set worker-threads' |
| 'maint show worker-threads' |
| Control the number of worker threads that may be used by GDB. On |
| capable hosts, GDB may use multiple threads to speed up certain |
| CPU-intensive operations, such as demangling symbol names. While |
| the number of threads used by GDB may vary, this command can be |
| used to set an upper bound on this number. The default is '0' |
| (disabled). A value of 'unlimited' lets GDB choose a reasonable |
| number. Note that this only controls worker threads started by GDB |
| itself; libraries used by GDB may start threads of their own. |
| |
| 'maint set profile' |
| 'maint show profile' |
| Control profiling of GDB. |
| |
| Profiling will be disabled until you use the 'maint set profile' |
| command to enable it. When you enable profiling, the system will |
| begin collecting timing and execution count data; when you disable |
| profiling or exit GDB, the results will be written to a log file. |
| Remember that if you use profiling, GDB will overwrite the |
| profiling log file (often called 'gmon.out'). If you have a record |
| of important profiling data in a 'gmon.out' file, be sure to move |
| it to a safe location. |
| |
| Configuring with '--enable-profiling' arranges for GDB to be |
| compiled with the '-pg' compiler option. |
| |
| 'maint set show-debug-regs' |
| 'maint show show-debug-regs' |
| Control whether to show variables that mirror the hardware debug |
| registers. Use 'on' to enable, 'off' to disable. If enabled, the |
| debug registers values are shown when GDB inserts or removes a |
| hardware breakpoint or watchpoint, and when the inferior triggers a |
| hardware-assisted breakpoint or watchpoint. |
| |
| 'maint set show-all-tib' |
| 'maint show show-all-tib' |
| Control whether to show all non zero areas within a 1k block |
| starting at thread local base, when using the 'info w32 |
| thread-information-block' command. |
| |
| 'maint set target-async' |
| 'maint show target-async' |
| This controls whether GDB targets operate in synchronous or |
| asynchronous mode (*note Background Execution::). Normally the |
| default is asynchronous, if it is available; but this can be |
| changed to more easily debug problems occurring only in synchronous |
| mode. |
| |
| 'maint set target-non-stop' |
| 'maint show target-non-stop' |
| |
| This controls whether GDB targets always operate in non-stop mode |
| even if 'set non-stop' is 'off' (*note Non-Stop Mode::). The |
| default is 'auto', meaning non-stop mode is enabled if supported by |
| the target. |
| |
| 'maint set target-non-stop auto' |
| This is the default mode. GDB controls the target in non-stop |
| mode if the target supports it. |
| |
| 'maint set target-non-stop on' |
| GDB controls the target in non-stop mode even if the target |
| does not indicate support. |
| |
| 'maint set target-non-stop off' |
| GDB does not control the target in non-stop mode even if the |
| target supports it. |
| |
| 'maint set tui-resize-message' |
| 'maint show tui-resize-message' |
| Control whether GDB displays a message each time the terminal is |
| resized when in TUI mode. The default is 'off', which means that |
| GDB is silent during resizes. When 'on', GDB will display a |
| message after a resize is completed; the message will include a |
| number indicating how many times the terminal has been resized. |
| This setting is intended for use by the test suite, where it would |
| otherwise be difficult to determine when a resize and refresh has |
| been completed. |
| |
| 'maint set per-command' |
| 'maint show per-command' |
| |
| GDB can display the resources used by each command. This is useful |
| in debugging performance problems. |
| |
| 'maint set per-command space [on|off]' |
| 'maint show per-command space' |
| Enable or disable the printing of the memory used by GDB for |
| each command. If enabled, GDB will display how much memory |
| each command took, following the command's own output. This |
| can also be requested by invoking GDB with the '--statistics' |
| command-line switch (*note Mode Options::). |
| |
| 'maint set per-command time [on|off]' |
| 'maint show per-command time' |
| Enable or disable the printing of the execution time of GDB |
| for each command. If enabled, GDB will display how much time |
| it took to execute each command, following the command's own |
| output. Both CPU time and wallclock time are printed. |
| Printing both is useful when trying to determine whether the |
| cost is CPU or, e.g., disk/network latency. Note that the CPU |
| time printed is for GDB only, it does not include the |
| execution time of the inferior because there's no mechanism |
| currently to compute how much time was spent by GDB and how |
| much time was spent by the program been debugged. This can |
| also be requested by invoking GDB with the '--statistics' |
| command-line switch (*note Mode Options::). |
| |
| 'maint set per-command symtab [on|off]' |
| 'maint show per-command symtab' |
| Enable or disable the printing of basic symbol table |
| statistics for each command. If enabled, GDB will display the |
| following information: |
| |
| a. number of symbol tables |
| b. number of primary symbol tables |
| c. number of blocks in the blockvector |
| |
| 'maint set check-libthread-db [on|off]' |
| 'maint show check-libthread-db' |
| Control whether GDB should run integrity checks on inferior |
| specific thread debugging libraries as they are loaded. The |
| default is not to perform such checks. If any check fails GDB will |
| unload the library and continue searching for a suitable candidate |
| as described in *note set libthread-db-search-path::. For more |
| information about the tests, see *note maint check libthread-db::. |
| |
| 'maint space VALUE' |
| An alias for 'maint set per-command space'. A non-zero value |
| enables it, zero disables it. |
| |
| 'maint time VALUE' |
| An alias for 'maint set per-command time'. A non-zero value |
| enables it, zero disables it. |
| |
| 'maint translate-address [SECTION] ADDR' |
| Find the symbol stored at the location specified by the address |
| ADDR and an optional section name SECTION. If found, GDB prints |
| the name of the closest symbol and an offset from the symbol's |
| location to the specified address. This is similar to the 'info |
| address' command (*note Symbols::), except that this command also |
| allows to find symbols in other sections. |
| |
| If section was not specified, the section in which the symbol was |
| found is also printed. For dynamically linked executables, the |
| name of executable or shared library containing the symbol is |
| printed as well. |
| |
| 'maint test-options require-delimiter' |
| 'maint test-options unknown-is-error' |
| 'maint test-options unknown-is-operand' |
| These commands are used by the testsuite to validate the command |
| options framework. The 'require-delimiter' variant requires a |
| double-dash delimiter to indicate end of options. The |
| 'unknown-is-error' and 'unknown-is-operand' do not. The |
| 'unknown-is-error' variant throws an error on unknown option, while |
| 'unknown-is-operand' treats unknown options as the start of the |
| command's operands. When run, the commands output the result of |
| the processed options. When completed, the commands store the |
| internal result of completion in a variable exposed by the 'maint |
| show test-options-completion-result' command. |
| |
| 'maint show test-options-completion-result' |
| Shows the result of completing the 'maint test-options' |
| subcommands. This is used by the testsuite to validate completion |
| support in the command options framework. |
| |
| 'maint set test-settings KIND' |
| 'maint show test-settings KIND' |
| These are representative commands for each KIND of setting type GDB |
| supports. They are used by the testsuite for exercising the |
| settings infrastructure. |
| |
| 'maint with SETTING [VALUE] [-- COMMAND]' |
| Like the 'with' command, but works with 'maintenance set' |
| variables. This is used by the testsuite to exercise the 'with' |
| command's infrastructure. |
| |
| 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 E GDB Remote Serial Protocol |
| ************************************* |
| |
| * Menu: |
| |
| * Overview:: |
| * Packets:: |
| * Stop Reply Packets:: |
| * General Query Packets:: |
| * Architecture-Specific Protocol Details:: |
| * Tracepoint Packets:: |
| * Host I/O Packets:: |
| * Interrupts:: |
| * Notification Packets:: |
| * Remote Non-Stop:: |
| * Packet Acknowledgment:: |
| * Examples:: |
| * File-I/O Remote Protocol Extension:: |
| * Library List Format:: |
| * Library List Format for SVR4 Targets:: |
| * Memory Map Format:: |
| * Thread List Format:: |
| * Traceframe Info Format:: |
| * Branch Trace Format:: |
| * Branch Trace Configuration Format:: |
| |
| |
| File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol |
| |
| E.1 Overview |
| ============ |
| |
| There may be occasions when you need to know something about the |
| protocol--for example, if there is only one serial port to your target |
| machine, you might want your program to do something special if it |
| recognizes a packet meant for GDB. |
| |
| In the examples below, '->' and '<-' are used to indicate transmitted |
| and received data, respectively. |
| |
| All GDB commands and responses (other than acknowledgments and |
| notifications, see *note Notification Packets::) are sent as a PACKET. |
| A PACKET is introduced with the character '$', the actual PACKET-DATA, |
| and the terminating character '#' followed by a two-digit CHECKSUM: |
| |
| $PACKET-DATA#CHECKSUM |
| |
| The two-digit CHECKSUM is computed as the modulo 256 sum of all |
| characters between the leading '$' and the trailing '#' (an eight bit |
| unsigned checksum). |
| |
| Implementors should note that prior to GDB 5.0 the protocol |
| specification also included an optional two-digit SEQUENCE-ID: |
| |
| $SEQUENCE-ID:PACKET-DATA#CHECKSUM |
| |
| That SEQUENCE-ID was appended to the acknowledgment. GDB has never |
| output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must |
| not accept SEQUENCE-ID. |
| |
| When either the host or the target machine receives a packet, the |
| first response expected is an acknowledgment: either '+' (to indicate |
| the package was received correctly) or '-' (to request retransmission): |
| |
| -> $PACKET-DATA#CHECKSUM |
| <- + |
| |
| The '+'/'-' acknowledgments can be disabled once a connection is |
| established. *Note Packet Acknowledgment::, for details. |
| |
| The host (GDB) sends COMMANDs, and the target (the debugging stub |
| incorporated in your program) sends a RESPONSE. In the case of step and |
| continue COMMANDs, the response is only sent when the operation has |
| completed, and the target has again stopped all threads in all attached |
| processes. This is the default all-stop mode behavior, but the remote |
| protocol also supports GDB's non-stop execution mode; see *note Remote |
| Non-Stop::, for details. |
| |
| PACKET-DATA consists of a sequence of characters with the exception |
| of '#' and '$' (see 'X' packet for additional exceptions). |
| |
| Fields within the packet should be separated using ',' ';' or ':'. |
| Except where otherwise noted all numbers are represented in HEX with |
| leading zeros suppressed. |
| |
| Implementors should note that prior to GDB 5.0, the character ':' |
| could not appear as the third character in a packet (as it would |
| potentially conflict with the SEQUENCE-ID). |
| |
| Binary data in most packets is encoded either as two hexadecimal |
| digits per byte of binary data. This allowed the traditional remote |
| protocol to work over connections which were only seven-bit clean. Some |
| packets designed more recently assume an eight-bit clean connection, and |
| use a more efficient encoding to send and receive binary data. |
| |
| The binary data representation uses '7d' (ASCII '}') as an escape |
| character. Any escaped byte is transmitted as the escape character |
| followed by the original character XORed with '0x20'. For example, the |
| byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'. The |
| bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}') |
| must always be escaped. Responses sent by the stub must also escape |
| '0x2a' (ASCII '*'), so that it is not interpreted as the start of a |
| run-length encoded sequence (described next). |
| |
| Response DATA can be run-length encoded to save space. Run-length |
| encoding replaces runs of identical characters with one instance of the |
| repeated character, followed by a '*' and a repeat count. The repeat |
| count is itself sent encoded, to avoid binary characters in DATA: a |
| value of N is sent as 'N+29'. For a repeat count greater or equal to 3, |
| this produces a printable ASCII character, e.g. a space (ASCII code 32) |
| for a repeat count of 3. (This is because run-length encoding starts to |
| win for counts 3 or more.) Thus, for example, '0* ' is a run-length |
| encoding of "0000": the space character after '*' means repeat the |
| leading '0' '32 - 29 = 3' more times. |
| |
| The printable characters '#' and '$' or with a numeric value greater |
| than 126 must not be used. Runs of six repeats ('#') or seven repeats |
| ('$') can be expanded using a repeat count of only five ('"'). For |
| example, '00000000' can be encoded as '0*"00'. |
| |
| The error response returned for some packets includes a two character |
| error number. That number is not well defined. |
| |
| For any COMMAND not supported by the stub, an empty response ('$#00') |
| should be returned. That way it is possible to extend the protocol. A |
| newer GDB can tell if a packet is supported based on that response. |
| |
| At a minimum, a stub is required to support the 'g' and 'G' commands |
| for register access, and the 'm' and 'M' commands for memory access. |
| Stubs that only control single-threaded targets can implement run |
| control with the 'c' (continue), and 's' (step) commands. Stubs that |
| support multi-threading targets should support the 'vCont' command. All |
| other commands are optional. |
| |
| |
| File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol |
| |
| E.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. |
| |
| Several packets and replies include a THREAD-ID field to identify a |
| thread. Normally these are positive numbers with a target-specific |
| interpretation, formatted as big-endian hex strings. A THREAD-ID can |
| also be a literal '-1' to indicate all threads, or '0' to pick any |
| thread. |
| |
| In addition, the remote protocol supports a multiprocess feature in |
| which the THREAD-ID syntax is extended to optionally include both |
| process and thread ID fields, as 'pPID.TID'. The PID (process) and TID |
| (thread) components each have the format described above: a positive |
| number with target-specific interpretation formatted as a big-endian hex |
| string, literal '-1' to indicate all processes or threads |
| (respectively), or '0' to indicate an arbitrary process or thread. |
| Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is |
| an error to specify all processes but a specific thread, such as |
| 'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and |
| replies explicitly documented to include a process ID, rather than a |
| THREAD-ID. |
| |
| The multiprocess THREAD-ID syntax extensions are only used if both |
| GDB and the stub report support for the 'multiprocess' feature using |
| 'qSupported'. *Note multiprocess extensions::, for more information. |
| |
| Note that all packet forms beginning with an upper- or lower-case |
| letter, other than those described here, are reserved for future use. |
| |
| Here are the packet descriptions. |
| |
| '!' |
| Enable extended mode. In extended mode, the remote server is made |
| persistent. The 'R' packet is used to restart the program being |
| debugged. |
| |
| Reply: |
| 'OK' |
| The remote target both supports and has enabled extended mode. |
| |
| '?' |
| Indicate the reason the target halted. The reply is the same as |
| for step and continue. This packet has a special interpretation |
| when the target is in non-stop mode; see *note Remote Non-Stop::. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| 'A ARGLEN,ARGNUM,ARG,...' |
| Initialized 'argv[]' array passed into program. ARGLEN specifies |
| the number of bytes in the hex encoded byte stream ARG. See |
| 'gdbserver' for more details. |
| |
| Reply: |
| 'OK' |
| The arguments were set. |
| 'E NN' |
| An error occurred. |
| |
| 'b BAUD' |
| (Don't use this packet; its behavior is not well-defined.) Change |
| the serial line speed to BAUD. |
| |
| JTC: _When does the transport layer state change? When it's |
| received, or after the ACK is transmitted. In either case, there |
| are problems if the command or the acknowledgment packet is |
| dropped._ |
| |
| Stan: _If people really wanted to add something like this, and get |
| it working for the first time, they ought to modify ser-unix.c to |
| send some kind of out-of-band message to a specially-setup stub and |
| have the switch happen "in between" packets, so that from remote |
| protocol's point of view, nothing actually happened._ |
| |
| 'B ADDR,MODE' |
| Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR. |
| |
| Don't use this packet. Use the 'Z' and 'z' packets instead (*note |
| insert breakpoint or watchpoint packet::). |
| |
| 'bc' |
| Backward continue. Execute the target system in reverse. No |
| parameter. *Note Reverse Execution::, for more information. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| 'bs' |
| Backward single step. Execute one instruction in reverse. No |
| parameter. *Note Reverse Execution::, for more information. |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| 'c [ADDR]' |
| Continue at ADDR, which is the address to resume. If ADDR is |
| omitted, resume at current address. |
| |
| This packet is deprecated for multi-threading support. *Note vCont |
| packet::. |
| |
| 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. |
| |
| This packet is deprecated for multi-threading support. *Note vCont |
| packet::. |
| |
| 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' |
| 'D;PID' |
| The first form of the packet is used to detach GDB from the remote |
| system. It is sent to the remote target before GDB disconnects via |
| the 'detach' command. |
| |
| The second form, including a process ID, is used when multiprocess |
| protocol extensions are enabled (*note multiprocess extensions::), |
| to detach only a specific process. The PID is specified as a |
| big-endian hex string. |
| |
| 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 gdbarch |
| functions 'DEPRECATED_REGISTER_RAW_SIZE' and |
| 'gdbarch_register_name'. |
| |
| When reading registers from a trace frame (*note Using the |
| Collected Data: Analyze Collected Data.), the stub may also |
| return a string of literal 'x''s in place of the register data |
| digits, to indicate that the corresponding register has not |
| been collected, thus its value is unavailable. For example, |
| for an architecture with 4 registers of 4 bytes each, the |
| following reply indicates to GDB that registers 0 and 2 have |
| not been collected, while registers 1 and 3 have been |
| collected, and both have zero value: |
| |
| -> g |
| <- xxxxxxxx00000000xxxxxxxx00000000 |
| |
| 'E NN' |
| for an error. |
| |
| 'G XX...' |
| Write general registers. *Note read registers packet::, for a |
| description of the XX... data. |
| |
| Reply: |
| 'OK' |
| for success |
| 'E NN' |
| for an error |
| |
| 'H OP THREAD-ID' |
| Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.). |
| Depending on the operation to be performed, OP should be 'c' for |
| step and continue operations (note that this is deprecated, |
| supporting the 'vCont' command is a better option), and 'g' for |
| other operations. The thread designator THREAD-ID has the format |
| and interpretation described in *note thread-id syntax::. |
| |
| 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. |
| |
| The exact effect of this packet is not specified. |
| |
| For a bare-metal target, it may power cycle or reset the target |
| system. For that reason, the 'k' packet has no reply. |
| |
| For a single-process target, it may kill that process if possible. |
| |
| A multiple-process target may choose to kill just one process, or |
| all that are under GDB's control. For more precise control, use |
| the vKill packet (*note vKill packet::). |
| |
| If the target system immediately closes the connection in response |
| to 'k', GDB does not consider the lack of packet acknowledgment to |
| be an error, and assumes the kill was successful. |
| |
| If connected using 'target extended-remote', and the target does |
| not close the connection in response to a kill request, GDB probes |
| the target state as if a new connection was opened (*note ? |
| packet::). |
| |
| 'm ADDR,LENGTH' |
| Read LENGTH addressable memory units starting at address ADDR |
| (*note addressable memory unit::). 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 addressable |
| memory units 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 addressable memory units starting at address ADDR |
| (*note addressable memory unit::). The data is given by XX...; |
| 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. The XX, while needed, is |
| ignored. This packet is only available in extended mode (*note |
| extended mode::). |
| |
| The 'R' packet has no reply. |
| |
| 's [ADDR]' |
| Single step, resuming at ADDR. If ADDR is omitted, resume at same |
| address. |
| |
| This packet is deprecated for multi-threading support. *Note vCont |
| packet::. |
| |
| 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. |
| |
| This packet is deprecated for multi-threading support. *Note vCont |
| packet::. |
| |
| 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, both of which are are 4 byte long. There must be |
| at least 3 digits in ADDR. |
| |
| 'T THREAD-ID' |
| Find out if the thread THREAD-ID is alive. *Note thread-id |
| syntax::. |
| |
| 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). |
| |
| 'vAttach;PID' |
| Attach to a new process with the specified process ID PID. The |
| process ID is a hexadecimal integer identifying the process. In |
| all-stop mode, all threads in the attached process are stopped; in |
| non-stop mode, it may be attached without being stopped if that is |
| supported by the target. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'E NN' |
| for an error |
| 'Any stop packet' |
| for success in all-stop mode (*note Stop Reply Packets::) |
| 'OK' |
| for success in non-stop mode (*note Remote Non-Stop::) |
| |
| 'vCont[;ACTION[:THREAD-ID]]...' |
| Resume the inferior, specifying different actions for each thread. |
| |
| For each inferior thread, the leftmost action with a matching |
| THREAD-ID is applied. Threads that don't match any action remain |
| in their current state. Thread IDs are specified using the syntax |
| described in *note thread-id syntax::. If multiprocess extensions |
| (*note multiprocess extensions::) are supported, actions can be |
| specified to match all threads in a process by using the 'pPID.-1' |
| form of the THREAD-ID. An action with no THREAD-ID matches all |
| threads. Specifying no actions is an error. |
| |
| Currently supported actions are: |
| |
| 'c' |
| Continue. |
| 'C SIG' |
| Continue with signal SIG. The signal SIG should be two hex |
| digits. |
| 's' |
| Step. |
| 'S SIG' |
| Step with signal SIG. The signal SIG should be two hex |
| digits. |
| 't' |
| Stop. |
| 'r START,END' |
| Step once, and then keep stepping as long as the thread stops |
| at addresses between START (inclusive) and END (exclusive). |
| The remote stub reports a stop reply when either the thread |
| goes out of the range or is stopped due to an unrelated |
| reason, such as hitting a breakpoint. *Note range stepping::. |
| |
| If the range is empty (START == END), then the action becomes |
| equivalent to the 's' action. In other words, single-step |
| once, and report the stop (even if the stepped instruction |
| jumps to START). |
| |
| (A stop reply may be sent at any point even if the PC is still |
| within the stepping range; for example, it is valid to |
| implement this packet in a degenerate way as a single |
| instruction step operation.) |
| |
| The optional argument ADDR normally associated with the 'c', 'C', |
| 's', and 'S' packets is not supported in 'vCont'. |
| |
| The 't' action is only relevant in non-stop mode (*note Remote |
| Non-Stop::) and may be ignored by the stub otherwise. A stop reply |
| should be generated for any affected thread not already stopped. |
| When a thread is stopped by means of a 't' action, the |
| corresponding stop reply should indicate that the thread has |
| stopped with signal '0', regardless of whether the target uses some |
| other signal as an implementation detail. |
| |
| The server must ignore 'c', 'C', 's', 'S', and 'r' actions for |
| threads that are already running. Conversely, the server must |
| ignore 't' actions for threads that are already stopped. |
| |
| _Note:_ In non-stop mode, a thread is considered running until GDB |
| acknowledges an asynchronous stop notification for it with the |
| 'vStopped' packet (*note Remote Non-Stop::). |
| |
| The stub must support 'vCont' if it reports support for |
| multiprocess extensions (*note multiprocess extensions::). |
| |
| Reply: *Note Stop Reply Packets::, for the reply specifications. |
| |
| 'vCont?' |
| Request a list of actions supported by the 'vCont' packet. |
| |
| Reply: |
| 'vCont[;ACTION...]' |
| The 'vCont' packet is supported. Each ACTION is a supported |
| command in the 'vCont' packet. |
| '' |
| The 'vCont' packet is not supported. |
| |
| 'vCtrlC' |
| Interrupt remote target as if a control-C was pressed on the remote |
| terminal. This is the equivalent to reacting to the '^C' ('\003', |
| the control-C character) character in all-stop mode while the |
| target is running, except this works in non-stop mode. *Note |
| interrupting remote targets::, for more info on the all-stop |
| variant. |
| |
| Reply: |
| 'E NN' |
| for an error |
| 'OK' |
| for success |
| |
| 'vFile:OPERATION:PARAMETER...' |
| Perform a file operation on the target system. For details, see |
| *note Host I/O Packets::. |
| |
| 'vFlashErase:ADDR,LENGTH' |
| Direct the stub to erase LENGTH bytes of flash starting at ADDR. |
| The region may enclose any number of flash blocks, but its start |
| and end must fall on block boundaries, as indicated by the flash |
| block size appearing in the memory map (*note Memory Map Format::). |
| GDB groups flash memory programming operations together, and sends |
| a 'vFlashDone' request after each group; the stub is allowed to |
| delay erase operation until the 'vFlashDone' packet is received. |
| |
| Reply: |
| 'OK' |
| for success |
| 'E NN' |
| for an error |
| |
| '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. |
| |
| 'vKill;PID' |
| Kill the process with the specified process ID PID, which is a |
| hexadecimal integer identifying the process. This packet is used |
| in preference to 'k' when multiprocess protocol extensions are |
| supported; see *note multiprocess extensions::. |
| |
| Reply: |
| 'E NN' |
| for an error |
| 'OK' |
| for success |
| |
| 'vMustReplyEmpty' |
| The correct reply to an unknown 'v' packet is to return the empty |
| string, however, some older versions of 'gdbserver' would |
| incorrectly return 'OK' for unknown 'v' packets. |
| |
| The 'vMustReplyEmpty' is used as a feature test to check how |
| 'gdbserver' handles unknown packets, it is important that this |
| packet be handled in the same way as other unknown 'v' packets. If |
| this packet is handled differently to other unknown 'v' packets |
| then it is possible that GDB may run into problems in other areas, |
| specifically around use of 'vFile:setfs:'. |
| |
| 'vRun;FILENAME[;ARGUMENT]...' |
| Run the program FILENAME, passing it each ARGUMENT on its command |
| line. The file and arguments are hex-encoded strings. If FILENAME |
| is an empty string, the stub may use a default program (e.g. the |
| last program run). The program is created in the stopped state. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'E NN' |
| for an error |
| 'Any stop packet' |
| for success (*note Stop Reply Packets::) |
| |
| 'vStopped' |
| *Note Notification Packets::. |
| |
| 'X ADDR,LENGTH:XX...' |
| Write data to memory, where the data is transmitted in binary. |
| Memory is specified by its address ADDR and number of addressable |
| memory units LENGTH (*note addressable memory unit::); 'XX...' is |
| binary data (*note Binary Data::). |
| |
| Reply: |
| 'OK' |
| for success |
| 'E NN' |
| for an error |
| |
| 'z TYPE,ADDR,KIND' |
| 'Z TYPE,ADDR,KIND' |
| Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint |
| starting at address ADDRESS of kind KIND. |
| |
| Each breakpoint and watchpoint packet TYPE is documented |
| separately. |
| |
| _Implementation notes: A remote target shall return an empty string |
| for an unrecognized breakpoint or watchpoint packet TYPE. A remote |
| target shall support either both or neither of a given 'ZTYPE...' |
| and 'zTYPE...' packet pair. To avoid potential problems with |
| duplicate packets, the operations should be implemented in an |
| idempotent way._ |
| |
| 'z0,ADDR,KIND' |
| 'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]' |
| Insert ('Z0') or remove ('z0') a software breakpoint at address |
| ADDR of type KIND. |
| |
| A software breakpoint is implemented by replacing the instruction |
| at ADDR with a software breakpoint or trap instruction. The KIND |
| is target-specific and typically indicates the size of the |
| breakpoint in bytes that should be inserted. E.g., the ARM and |
| MIPS can insert either a 2 or 4 byte breakpoint. Some |
| architectures have additional meanings for KIND (*note |
| Architecture-Specific Protocol Details::); if no |
| architecture-specific value is being used, it should be '0'. KIND |
| is hex-encoded. COND_LIST is an optional list of conditional |
| expressions in bytecode form that should be evaluated on the |
| target's side. These are the conditions that should be taken into |
| consideration when deciding if the breakpoint trigger should be |
| reported back to GDB. |
| |
| See also the 'swbreak' stop reason (*note swbreak stop reason::) |
| for how to best report a software breakpoint event to GDB. |
| |
| The COND_LIST parameter is comprised of a series of expressions, |
| concatenated without separators. Each expression has the following |
| form: |
| |
| 'X LEN,EXPR' |
| LEN is the length of the bytecode expression and EXPR is the |
| actual conditional expression in bytecode form. |
| |
| The optional CMD_LIST parameter introduces commands that may be run |
| on the target, rather than being reported back to GDB. The |
| parameter starts with a numeric flag PERSIST; if the flag is |
| nonzero, then the breakpoint may remain active and the commands |
| continue to be run even when GDB disconnects from the target. |
| Following this flag is a series of expressions concatenated with no |
| separators. Each expression has the following form: |
| |
| 'X LEN,EXPR' |
| LEN is the length of the bytecode expression and EXPR is the |
| actual commands expression in bytecode form. |
| |
| _Implementation note: It is possible for a target to copy or move |
| code that contains software 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,KIND' |
| 'Z1,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]' |
| Insert ('Z1') or remove ('z1') a hardware breakpoint at address |
| ADDR. |
| |
| A hardware breakpoint is implemented using a mechanism that is not |
| dependent on being able to modify the target's memory. The KIND, |
| COND_LIST, and CMD_LIST arguments have the same meaning as in 'Z0' |
| packets. |
| |
| _Implementation note: A hardware breakpoint is not affected by code |
| movement._ |
| |
| Reply: |
| 'OK' |
| success |
| '' |
| not supported |
| 'E NN' |
| for an error |
| |
| 'z2,ADDR,KIND' |
| 'Z2,ADDR,KIND' |
| Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. The |
| number of bytes to watch is specified by KIND. |
| |
| Reply: |
| 'OK' |
| success |
| '' |
| not supported |
| 'E NN' |
| for an error |
| |
| 'z3,ADDR,KIND' |
| 'Z3,ADDR,KIND' |
| Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. The |
| number of bytes to watch is specified by KIND. |
| |
| Reply: |
| 'OK' |
| success |
| '' |
| not supported |
| 'E NN' |
| for an error |
| |
| 'z4,ADDR,KIND' |
| 'Z4,ADDR,KIND' |
| Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. The |
| number of bytes to watch is specified by KIND. |
| |
| 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 |
| |
| E.3 Stop Reply Packets |
| ====================== |
| |
| The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?' |
| packets can receive any of the below as a reply. Except for '?' and |
| 'vStopped', that reply is only returned when the target halts. In the |
| below the exact meaning of "signal number" is defined by the header |
| 'include/gdb/signals.h' in the GDB source code. |
| |
| In non-stop mode, the server will simply reply 'OK' to commands such |
| as 'vCont'; any stop will be the subject of a future notification. |
| *Note Remote Non-Stop::. |
| |
| As in the description of request packets, we include spaces in the |
| reply templates for clarity; these are not part of the reply packet's |
| syntax. No GDB stop reply packet uses spaces to separate its |
| components. |
| |
| 'S AA' |
| The program received signal number AA (a two-digit hexadecimal |
| number). This is equivalent to a 'T' response with no N:R pairs. |
| |
| 'T AA N1:R1;N2:R2;...' |
| The program received signal number AA (a two-digit hexadecimal |
| number). This is equivalent to an 'S' response, except that the |
| 'N:R' pairs can carry values of important registers and other |
| information directly in the stop reply packet, reducing round-trip |
| latency. Single-step and breakpoint traps are reported this way. |
| Each 'N:R' pair is interpreted as follows: |
| |
| * If N is a hexadecimal number, it is a register number, and the |
| corresponding R gives that register's value. The data R is a |
| series of bytes in target byte order, with each byte given by |
| a two-digit hex number. |
| |
| * If N is 'thread', then R is the THREAD-ID of the stopped |
| thread, as specified in *note thread-id syntax::. |
| |
| * If N is 'core', then R is the hexadecimal number of the core |
| on which the stop event was detected. |
| |
| * If N is a recognized "stop reason", it describes a more |
| specific event that stopped the target. The currently defined |
| stop reasons are listed below. The AA should be '05', the |
| trap signal. At most one stop reason should be present. |
| |
| * Otherwise, GDB should ignore this 'N:R' pair and go on to the |
| next; this allows us to extend the protocol in the future. |
| |
| The currently defined stop reasons are: |
| |
| 'watch' |
| 'rwatch' |
| 'awatch' |
| The packet indicates a watchpoint hit, and R is the data |
| address, in hex. |
| |
| 'syscall_entry' |
| 'syscall_return' |
| The packet indicates a syscall entry or return, and R is the |
| syscall number, in hex. |
| |
| 'library' |
| The packet indicates that the loaded libraries have changed. |
| GDB should use 'qXfer:libraries:read' to fetch a new list of |
| loaded libraries. The R part is ignored. |
| |
| 'replaylog' |
| The packet indicates that the target cannot continue replaying |
| logged execution events, because it has reached the end (or |
| the beginning when executing backward) of the log. The value |
| of R will be either 'begin' or 'end'. *Note Reverse |
| Execution::, for more information. |
| |
| 'swbreak' |
| The packet indicates a software breakpoint instruction was |
| executed, irrespective of whether it was GDB that planted the |
| breakpoint or the breakpoint is hardcoded in the program. The |
| R part must be left empty. |
| |
| On some architectures, such as x86, at the architecture level, |
| when a breakpoint instruction executes the program counter |
| points at the breakpoint address plus an offset. On such |
| targets, the stub is responsible for adjusting the PC to point |
| back at the breakpoint address. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| This packet is required for correct non-stop mode operation. |
| |
| 'hwbreak' |
| The packet indicates the target stopped for a hardware |
| breakpoint. The R part must be left empty. |
| |
| The same remarks about 'qSupported' and non-stop mode above |
| apply. |
| |
| 'fork' |
| The packet indicates that 'fork' was called, and R is the |
| thread ID of the new child process. Refer to *note thread-id |
| syntax:: for the format of the THREAD-ID field. This packet |
| is only applicable to targets that support fork events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'vfork' |
| The packet indicates that 'vfork' was called, and R is the |
| thread ID of the new child process. Refer to *note thread-id |
| syntax:: for the format of the THREAD-ID field. This packet |
| is only applicable to targets that support vfork events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'vforkdone' |
| The packet indicates that a child process created by a vfork |
| has either called 'exec' or terminated, so that the address |
| spaces of the parent and child process are no longer shared. |
| The R part is ignored. This packet is only applicable to |
| targets that support vforkdone events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'exec' |
| The packet indicates that 'execve' was called, and R is the |
| absolute pathname of the file that was executed, in hex. This |
| packet is only applicable to targets that support exec events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'create' |
| The packet indicates that the thread was just created. The |
| new thread is stopped until GDB sets it running with a |
| resumption packet (*note vCont packet::). This packet should |
| not be sent by default; GDB requests it with the *note |
| QThreadEvents:: packet. See also the 'w' (*note thread exit |
| event::) remote reply below. The R part is ignored. |
| |
| 'W AA' |
| 'W AA ; process:PID' |
| The process exited, and AA is the exit status. This is only |
| applicable to certain targets. |
| |
| The second form of the response, including the process ID of the |
| exited process, can be used only when GDB has reported support for |
| multiprocess protocol extensions; see *note multiprocess |
| extensions::. Both AA and PID are formatted as big-endian hex |
| strings. |
| |
| 'X AA' |
| 'X AA ; process:PID' |
| The process terminated with signal AA. |
| |
| The second form of the response, including the process ID of the |
| terminated process, can be used only when GDB has reported support |
| for multiprocess protocol extensions; see *note multiprocess |
| extensions::. Both AA and PID are formatted as big-endian hex |
| strings. |
| |
| 'w AA ; TID' |
| |
| The thread exited, and AA is the exit status. This response should |
| not be sent by default; GDB requests it with the *note |
| QThreadEvents:: packet. See also *note thread create event:: |
| above. AA is formatted as a big-endian hex string. |
| |
| 'N' |
| There are no resumed threads left in the target. In other words, |
| even though the process is alive, the last resumed thread has |
| exited. For example, say the target process has two threads: |
| thread 1 and thread 2. The client leaves thread 1 stopped, and |
| resumes thread 2, which subsequently exits. At this point, even |
| though the process is still alive, and thus no 'W' stop reply is |
| sent, no thread is actually executing either. The 'N' stop reply |
| thus informs the client that it can stop waiting for stop replies. |
| This packet should not be sent by default; older GDB versions did |
| not support it. GDB requests it, by supplying an appropriate |
| 'qSupported' feature (*note qSupported::). The remote stub must |
| also supply the appropriate 'qSupported' feature indicating |
| support. |
| |
| 'O XX...' |
| 'XX...' is hex encoding of ASCII data, to be written as the |
| program's console output. This can happen at any time while the |
| program is running and the debugger should continue to wait for |
| 'W', 'T', etc. This reply is not permitted in non-stop mode. |
| |
| 'F CALL-ID,PARAMETER...' |
| CALL-ID is the identifier which says which host system call should |
| be called. This is just the name of the function. Translation |
| into the correct system call is only applicable as it's defined in |
| GDB. *Note File-I/O Remote Protocol Extension::, for a list of |
| implemented system calls. |
| |
| 'PARAMETER...' is a list of parameters as defined for this very |
| system call. |
| |
| The target replies with this packet when it expects GDB to call a |
| host system call on behalf of the target. GDB replies with an |
| appropriate 'F' packet and keeps up waiting for the next reply |
| packet from the target. The latest 'C', 'c', 'S' or 's' action is |
| expected to be continued. *Note File-I/O Remote Protocol |
| Extension::, for more details. |
| |
| |
| File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol |
| |
| E.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: |
| |
| 'QAgent:1' |
| 'QAgent:0' |
| Turn on or off the agent as a helper to perform some debugging |
| operations delegated from GDB (*note Control Agent::). |
| |
| 'QAllow:OP:VAL...' |
| Specify which operations GDB expects to request of the target, as a |
| semicolon-separated list of operation name and value pairs. |
| Possible values for OP include 'WriteReg', 'WriteMem', |
| 'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'. VAL |
| is either 0, indicating that GDB will not request the operation, or |
| 1, indicating that it may. (The target can then use this to set up |
| its own internals optimally, for instance if the debugger never |
| expects to insert breakpoints, it may not need to install its own |
| trap handler.) |
| |
| 'qC' |
| Return the current thread ID. |
| |
| Reply: |
| 'QC THREAD-ID' |
| Where THREAD-ID is a thread ID as documented in *note |
| thread-id syntax::. |
| '(anything else)' |
| Any other reply implies the old thread ID. |
| |
| 'qCRC:ADDR,LENGTH' |
| Compute the CRC checksum of a block of memory using CRC-32 defined |
| in IEEE 802.3. The CRC is computed byte at a time, taking the most |
| significant bit of each byte first. The initial pattern code |
| '0xffffffff' is used to ensure leading zeros affect the CRC. |
| |
| _Note:_ This is the same CRC used in validating separate debug |
| files (*note Debugging Information in Separate Files: Separate |
| Debug Files.). However the algorithm is slightly different. When |
| validating separate debug files, the CRC is computed taking the |
| _least_ significant bit of each byte first, and the final result is |
| inverted to detect trailing zeros. |
| |
| Reply: |
| 'E NN' |
| An error (such as memory fault) |
| 'C CRC32' |
| The specified memory region's checksum is CRC32. |
| |
| 'QDisableRandomization:VALUE' |
| Some target operating systems will randomize the virtual address |
| space of the inferior process as a security feature, but provide a |
| feature to disable such randomization, e.g. to allow for a more |
| deterministic debugging experience. On such systems, this packet |
| with a VALUE of 1 directs the target to disable address space |
| randomization for processes subsequently started via 'vRun' |
| packets, while a packet with a VALUE of 0 tells the target to |
| enable address space randomization. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'QDisableRandomization' is not |
| supported by the stub. |
| |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). This should only be done on targets that actually |
| support disabling address space randomization. |
| |
| 'QStartupWithShell:VALUE' |
| On UNIX-like targets, it is possible to start the inferior using a |
| shell program. This is the default behavior on both GDB and |
| 'gdbserver' (*note set startup-with-shell::). This packet is used |
| to inform 'gdbserver' whether it should start the inferior using a |
| shell or not. |
| |
| If VALUE is '0', 'gdbserver' will not use a shell to start the |
| inferior. If VALUE is '1', 'gdbserver' will use a shell to start |
| the inferior. All other values are considered an error. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). This should only be done on targets that actually |
| support starting the inferior using a shell. |
| |
| Use of this packet is controlled by the 'set startup-with-shell' |
| command; *note set startup-with-shell::. |
| |
| 'QEnvironmentHexEncoded:HEX-VALUE' |
| On UNIX-like targets, it is possible to set environment variables |
| that will be passed to the inferior during the startup process. |
| This packet is used to inform 'gdbserver' of an environment |
| variable that has been defined by the user on GDB (*note set |
| environment::). |
| |
| The packet is composed by HEX-VALUE, an hex encoded representation |
| of the NAME=VALUE format representing an environment variable. The |
| name of the environment variable is represented by NAME, and the |
| value to be assigned to the environment variable is represented by |
| VALUE. If the variable has no value (i.e., the value is 'null'), |
| then VALUE will not be present. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). This should only be done on targets that actually |
| support passing environment variables to the starting inferior. |
| |
| This packet is related to the 'set environment' command; *note set |
| environment::. |
| |
| 'QEnvironmentUnset:HEX-VALUE' |
| On UNIX-like targets, it is possible to unset environment variables |
| before starting the inferior in the remote target. This packet is |
| used to inform 'gdbserver' of an environment variable that has been |
| unset by the user on GDB (*note unset environment::). |
| |
| The packet is composed by HEX-VALUE, an hex encoded representation |
| of the name of the environment variable to be unset. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). This should only be done on targets that actually |
| support passing environment variables to the starting inferior. |
| |
| This packet is related to the 'unset environment' command; *note |
| unset environment::. |
| |
| 'QEnvironmentReset' |
| On UNIX-like targets, this packet is used to reset the state of |
| environment variables in the remote target before starting the |
| inferior. In this context, reset means unsetting all environment |
| variables that were previously set by the user (i.e., were not |
| initially present in the environment). It is sent to 'gdbserver' |
| before the 'QEnvironmentHexEncoded' (*note |
| QEnvironmentHexEncoded::) and the 'QEnvironmentUnset' (*note |
| QEnvironmentUnset::) packets. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). This should only be done on targets that actually |
| support passing environment variables to the starting inferior. |
| |
| 'QSetWorkingDir:[DIRECTORY]' |
| This packet is used to inform the remote server of the intended |
| current working directory for programs that are going to be |
| executed. |
| |
| The packet is composed by DIRECTORY, an hex encoded representation |
| of the directory that the remote inferior will use as its current |
| working directory. If DIRECTORY is an empty string, the remote |
| server should reset the inferior's current working directory to its |
| original, empty value. |
| |
| This packet is only available in extended mode (*note extended |
| mode::). |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'qfThreadInfo' |
| 'qsThreadInfo' |
| Obtain a list of all active thread IDs from the target (OS). Since |
| there may be too many active threads to fit into one reply packet, |
| this query works iteratively: it may require more than one |
| query/reply sequence to obtain the entire list of threads. The |
| first query of the sequence will be the 'qfThreadInfo' query; |
| subsequent queries in the sequence will be the 'qsThreadInfo' |
| query. |
| |
| NOTE: This packet replaces the 'qL' query (see below). |
| |
| Reply: |
| 'm THREAD-ID' |
| A single thread ID |
| 'm THREAD-ID,THREAD-ID...' |
| a comma-separated list of thread IDs |
| 'l' |
| (lower case letter 'L') denotes end of list. |
| |
| In response to each query, the target will reply with a list of one |
| or more thread IDs, separated by commas. GDB will respond to each |
| reply with a request for more thread ids (using the 'qs' form of |
| the query), until the target responds with 'l' (lower-case ell, for |
| "last"). Refer to *note thread-id syntax::, for the format of the |
| THREAD-ID fields. |
| |
| _Note: GDB will send the 'qfThreadInfo' query during the initial |
| connection with the remote target, and the very first thread ID |
| mentioned in the reply will be stopped by GDB in a subsequent |
| message. Therefore, the stub should ensure that the first thread |
| ID in the 'qfThreadInfo' reply is suitable for being stopped by |
| GDB._ |
| |
| 'qGetTLSAddr:THREAD-ID,OFFSET,LM' |
| Fetch the address associated with thread local storage specified by |
| THREAD-ID, OFFSET, and LM. |
| |
| THREAD-ID is the thread ID associated with the thread for which to |
| fetch the TLS address. *Note thread-id syntax::. |
| |
| OFFSET is the (big endian, hex encoded) offset associated with the |
| thread local variable. (This offset is obtained from the debug |
| information associated with the variable.) |
| |
| LM is the (big endian, hex encoded) OS/ABI-specific encoding of the |
| load module associated with the thread local storage. For example, |
| a GNU/Linux system will pass the link map address of the shared |
| object associated with the thread local storage under |
| consideration. Other operating environments may choose to |
| represent the load module differently, so the precise meaning of |
| this parameter will vary. |
| |
| Reply: |
| 'XX...' |
| Hex encoded (big endian) bytes representing the address of the |
| thread local storage requested. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'qGetTLSAddr' is not supported |
| by the stub. |
| |
| 'qGetTIBAddr:THREAD-ID' |
| Fetch address of the Windows OS specific Thread Information Block. |
| |
| THREAD-ID is the thread ID associated with the thread. |
| |
| Reply: |
| 'XX...' |
| Hex encoded (big endian) bytes representing the linear address |
| of the thread information block. |
| |
| 'E NN' |
| An error occured. This means that either the thread was not |
| found, or the address could not be retrieved. |
| |
| '' |
| An empty reply indicates that 'qGetTIBAddr' is not supported |
| by the stub. |
| |
| 'qL STARTFLAG THREADCOUNT NEXTTHREAD' |
| Obtain thread information from RTOS. Where: STARTFLAG (one hex |
| digit) is one to indicate the first query and zero to indicate a |
| subsequent query; THREADCOUNT (two hex digits) is the maximum |
| number of threads the response packet can contain; and NEXTTHREAD |
| (eight hex digits), for subsequent queries (STARTFLAG is zero), is |
| returned in the response as ARGTHREAD. |
| |
| Don't use this packet; use the 'qfThreadInfo' query instead (see |
| above). |
| |
| Reply: |
| 'qM COUNT DONE ARGTHREAD THREAD...' |
| Where: COUNT (two hex digits) is the number of threads being |
| returned; DONE (one hex digit) is zero to indicate more |
| threads and one indicates no further threads; ARGTHREADID |
| (eight hex digits) is NEXTTHREAD from the request packet; |
| THREAD... is a sequence of thread IDs, THREADID (eight hex |
| digits), from the target. See |
| 'remote.c:parse_threadlist_response()'. |
| |
| 'qOffsets' |
| Get section offsets that the target used when relocating the |
| downloaded image. |
| |
| Reply: |
| 'Text=XXX;Data=YYY[;Bss=ZZZ]' |
| Relocate the 'Text' section by XXX from its original address. |
| Relocate the 'Data' section by YYY from its original address. |
| If the object file format provides segment information (e.g. |
| ELF 'PT_LOAD' program headers), GDB will relocate entire |
| segments by the supplied offsets. |
| |
| _Note: while a 'Bss' offset may be included in the response, |
| GDB ignores this and instead applies the 'Data' offset to the |
| 'Bss' section._ |
| |
| 'TextSeg=XXX[;DataSeg=YYY]' |
| Relocate the first segment of the object file, which |
| conventionally contains program code, to a starting address of |
| XXX. If 'DataSeg' is specified, relocate the second segment, |
| which conventionally contains modifiable data, to a starting |
| address of YYY. GDB will report an error if the object file |
| does not contain segment information, or does not contain at |
| least as many segments as mentioned in the reply. Extra |
| segments are kept at fixed offsets relative to the last |
| relocated segment. |
| |
| 'qP MODE THREAD-ID' |
| Returns information on THREAD-ID. Where: MODE is a hex encoded 32 |
| bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). |
| |
| Don't use this packet; use the 'qThreadExtraInfo' query instead |
| (see below). |
| |
| Reply: see 'remote.c:remote_unpack_thread_info_response()'. |
| |
| 'QNonStop:1' |
| 'QNonStop:0' |
| Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode. |
| *Note Remote Non-Stop::, for more information. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'QNonStop' is not supported by |
| the stub. |
| |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). Use of this packet is controlled by the 'set |
| non-stop' command; *note Non-Stop Mode::. |
| |
| 'QCatchSyscalls:1 [;SYSNO]...' |
| 'QCatchSyscalls:0' |
| Enable ('QCatchSyscalls:1') or disable ('QCatchSyscalls:0') |
| catching syscalls from the inferior process. |
| |
| For 'QCatchSyscalls:1', each listed syscall SYSNO (encoded in hex) |
| should be reported to GDB. If no syscall SYSNO is listed, every |
| system call should be reported. |
| |
| Note that if a syscall not in the list is reported, GDB will still |
| filter the event according to its own list from all corresponding |
| 'catch syscall' commands. However, it is more efficient to only |
| report the requested syscalls. |
| |
| Multiple 'QCatchSyscalls:1' packets do not combine; any earlier |
| 'QCatchSyscalls:1' list is completely replaced by the new list. |
| |
| If the inferior process execs, the state of 'QCatchSyscalls' is |
| kept for the new process too. On targets where exec may affect |
| syscall numbers, for example with exec between 32 and 64-bit |
| processes, the client should send a new packet with the new syscall |
| list. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. NN are hex digits. |
| |
| '' |
| An empty reply indicates that 'QCatchSyscalls' is not |
| supported by the stub. |
| |
| Use of this packet is controlled by the 'set remote catch-syscalls' |
| command (*note set remote catch-syscalls: Remote Configuration.). |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). |
| |
| 'QPassSignals: SIGNAL [;SIGNAL]...' |
| Each listed SIGNAL should be passed directly to the inferior |
| process. Signals are numbered identically to continue packets and |
| stop replies (*note Stop Reply Packets::). Each SIGNAL list item |
| should be strictly greater than the previous item. These signals |
| do not need to stop the inferior, or be reported to GDB. All other |
| signals should be reported to GDB. Multiple 'QPassSignals' packets |
| do not combine; any earlier 'QPassSignals' list is completely |
| replaced by the new list. This packet improves performance when |
| using 'handle SIGNAL nostop noprint pass'. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'QPassSignals' is not supported |
| by the stub. |
| |
| Use of this packet is controlled by the 'set remote pass-signals' |
| command (*note set remote pass-signals: Remote Configuration.). |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). |
| |
| 'QProgramSignals: SIGNAL [;SIGNAL]...' |
| Each listed SIGNAL may be delivered to the inferior process. |
| Others should be silently discarded. |
| |
| In some cases, the remote stub may need to decide whether to |
| deliver a signal to the program or not without GDB involvement. |
| One example of that is while detaching -- the program's threads may |
| have stopped for signals that haven't yet had a chance of being |
| reported to GDB, and so the remote stub can use the signal list |
| specified by this packet to know whether to deliver or ignore those |
| pending signals. |
| |
| This does not influence whether to deliver a signal as requested by |
| a resumption packet (*note vCont packet::). |
| |
| Signals are numbered identically to continue packets and stop |
| replies (*note Stop Reply Packets::). Each SIGNAL list item should |
| be strictly greater than the previous item. Multiple |
| 'QProgramSignals' packets do not combine; any earlier |
| 'QProgramSignals' list is completely replaced by the new list. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'QProgramSignals' is not |
| supported by the stub. |
| |
| Use of this packet is controlled by the 'set remote |
| program-signals' command (*note set remote program-signals: Remote |
| Configuration.). This packet is not probed by default; the remote |
| stub must request it, by supplying an appropriate 'qSupported' |
| response (*note qSupported::). |
| |
| 'QThreadEvents:1' |
| 'QThreadEvents:0' |
| |
| Enable ('QThreadEvents:1') or disable ('QThreadEvents:0') reporting |
| of thread create and exit events. *Note thread create event::, for |
| the reply specifications. For example, this is used in non-stop |
| mode when GDB stops a set of threads and synchronously waits for |
| the their corresponding stop replies. Without exit events, if one |
| of the threads exits, GDB would hang forever not knowing that it |
| should no longer expect a stop for that same thread. GDB does not |
| enable this feature unless the stub reports that it supports it by |
| including 'QThreadEvents+' in its 'qSupported' reply. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'QThreadEvents' is not supported |
| by the stub. |
| |
| Use of this packet is controlled by the 'set remote thread-events' |
| command (*note set remote thread-events: Remote Configuration.). |
| |
| 'qRcmd,COMMAND' |
| COMMAND (hex encoded) is passed to the local interpreter for |
| execution. Invalid commands should be reported using the output |
| string. Before the final result packet, the target may also |
| respond with a number of intermediate 'OOUTPUT' console output |
| packets. _Implementors should note that providing access to a |
| stubs's interpreter may have security implications_. |
| |
| Reply: |
| 'OK' |
| A command response with no output. |
| 'OUTPUT' |
| A command response with the hex encoded output string OUTPUT. |
| 'E NN' |
| Indicate a badly formed request. |
| '' |
| An empty reply indicates that 'qRcmd' is not recognized. |
| |
| (Note that the 'qRcmd' packet's name is separated from the command |
| by a ',', not a ':', contrary to the naming conventions above. |
| Please don't use this packet as a model for new packets.) |
| |
| 'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' |
| Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. Both ADDRESS |
| and LENGTH are encoded in hex; SEARCH-PATTERN is a sequence of |
| bytes, also hex encoded. |
| |
| Reply: |
| '0' |
| The pattern was not found. |
| '1,address' |
| The pattern was found at ADDRESS. |
| 'E NN' |
| A badly formed request or an error was encountered while |
| searching memory. |
| '' |
| An empty reply indicates that 'qSearch:memory' is not |
| recognized. |
| |
| 'QStartNoAckMode' |
| Request that the remote stub disable the normal '+'/'-' protocol |
| acknowledgments (*note Packet Acknowledgment::). |
| |
| Reply: |
| 'OK' |
| The stub has switched to no-acknowledgment mode. GDB |
| acknowledges this response, but neither the stub nor GDB shall |
| send or expect further '+'/'-' acknowledgments in the current |
| connection. |
| '' |
| An empty reply indicates that the stub does not support |
| no-acknowledgment mode. |
| |
| 'qSupported [:GDBFEATURE [;GDBFEATURE]... ]' |
| Tell the remote stub about features supported by GDB, and query the |
| stub for features it supports. This packet allows GDB and the |
| remote stub to take advantage of each others' features. |
| 'qSupported' also consolidates multiple feature probes at startup, |
| to improve GDB performance--a single larger packet performs better |
| than multiple smaller probe packets on high-latency links. Some |
| features may enable behavior which must not be on by default, e.g. |
| because it would confuse older clients or stubs. Other features |
| may describe packets which could be automatically probed for, but |
| are not. These features must be reported before GDB will use them. |
| This "default unsupported" behavior is not appropriate for all |
| packets, but it helps to keep the initial connection time under |
| control with new versions of GDB which support increasing numbers |
| of packets. |
| |
| Reply: |
| 'STUBFEATURE [;STUBFEATURE]...' |
| The stub supports or does not support each returned |
| STUBFEATURE, depending on the form of each STUBFEATURE (see |
| below for the possible forms). |
| '' |
| An empty reply indicates that 'qSupported' is not recognized, |
| or that no features needed to be reported to GDB. |
| |
| The allowed forms for each feature (either a GDBFEATURE in the |
| 'qSupported' packet, or a STUBFEATURE in the response) are: |
| |
| 'NAME=VALUE' |
| The remote protocol feature NAME is supported, and associated |
| with the specified VALUE. The format of VALUE depends on the |
| feature, but it must not include a semicolon. |
| 'NAME+' |
| The remote protocol feature NAME is supported, and does not |
| need an associated value. |
| 'NAME-' |
| The remote protocol feature NAME is not supported. |
| 'NAME?' |
| The remote protocol feature NAME may be supported, and GDB |
| should auto-detect support in some other way when it is |
| needed. This form will not be used for GDBFEATURE |
| notifications, but may be used for STUBFEATURE responses. |
| |
| Whenever the stub receives a 'qSupported' request, the supplied set |
| of GDB features should override any previous request. This allows |
| GDB to put the stub in a known state, even if the stub had |
| previously been communicating with a different version of GDB. |
| |
| The following values of GDBFEATURE (for the packet sent by GDB) are |
| defined: |
| |
| 'multiprocess' |
| This feature indicates whether GDB supports multiprocess |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'multiprocess+' in its 'qSupported' reply. *Note |
| multiprocess extensions::, for details. |
| |
| 'xmlRegisters' |
| This feature indicates that GDB supports the XML target |
| description. If the stub sees 'xmlRegisters=' with target |
| specific strings separated by a comma, it will report register |
| description. |
| |
| 'qRelocInsn' |
| This feature indicates whether GDB supports the 'qRelocInsn' |
| packet (*note Relocate instruction reply packet: Tracepoint |
| Packets.). |
| |
| 'swbreak' |
| This feature indicates whether GDB supports the swbreak stop |
| reason in stop replies. *Note swbreak stop reason::, for |
| details. |
| |
| 'hwbreak' |
| This feature indicates whether GDB supports the hwbreak stop |
| reason in stop replies. *Note swbreak stop reason::, for |
| details. |
| |
| 'fork-events' |
| This feature indicates whether GDB supports fork event |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'fork-events+' in its 'qSupported' reply. |
| |
| 'vfork-events' |
| This feature indicates whether GDB supports vfork event |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'vfork-events+' in its 'qSupported' reply. |
| |
| 'exec-events' |
| This feature indicates whether GDB supports exec event |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'exec-events+' in its 'qSupported' reply. |
| |
| 'vContSupported' |
| This feature indicates whether GDB wants to know the supported |
| actions in the reply to 'vCont?' packet. |
| |
| Stubs should ignore any unknown values for GDBFEATURE. Any GDB |
| which sends a 'qSupported' packet supports receiving packets of |
| unlimited length (earlier versions of GDB may reject overly long |
| responses). Additional values for GDBFEATURE may be defined in the |
| future to let the stub take advantage of new features in GDB, e.g. |
| incompatible improvements in the remote protocol--the |
| 'multiprocess' feature is an example of such a feature. The stub's |
| reply should be independent of the GDBFEATURE entries sent by GDB; |
| first GDB describes all the features it supports, and then the stub |
| replies with all the features it supports. |
| |
| Similarly, GDB will silently ignore unrecognized stub feature |
| responses, as long as each response uses one of the standard forms. |
| |
| Some features are flags. A stub which supports a flag feature |
| should respond with a '+' form response. Other features require |
| values, and the stub should respond with an '=' form response. |
| |
| Each feature has a default value, which GDB will use if |
| 'qSupported' is not available or if the feature is not mentioned in |
| the 'qSupported' response. The default values are fixed; a stub is |
| free to omit any feature responses that match the defaults. |
| |
| Not all features can be probed, but for those which can, the |
| probing mechanism is useful: in some cases, a stub's internal |
| architecture may not allow the protocol layer to know some |
| information about the underlying target in advance. This is |
| especially common in stubs which may be configured for multiple |
| targets. |
| |
| These are the currently defined stub features and their properties: |
| |
| Feature Name Value Default Probe |
| Required Allowed |
| |
| 'PacketSize' Yes '-' No |
| |
| 'qXfer:auxv:read' No '-' Yes |
| |
| 'qXfer:btrace:read' No '-' Yes |
| |
| 'qXfer:btrace-conf:read' No '-' Yes |
| |
| 'qXfer:exec-file:read' No '-' Yes |
| |
| 'qXfer:features:read' No '-' Yes |
| |
| 'qXfer:libraries:read' No '-' Yes |
| |
| 'qXfer:libraries-svr4:read'No '-' Yes |
| |
| 'augmented-libraries-svr4-read'No '-' No |
| |
| 'qXfer:memory-map:read' No '-' Yes |
| |
| 'qXfer:sdata:read' No '-' Yes |
| |
| 'qXfer:siginfo:read' No '-' Yes |
| |
| 'qXfer:siginfo:write' No '-' Yes |
| |
| 'qXfer:threads:read' No '-' Yes |
| |
| 'qXfer:traceframe-info:read'No '-' Yes |
| |
| 'qXfer:uib:read' No '-' Yes |
| |
| 'qXfer:fdpic:read' No '-' Yes |
| |
| 'Qbtrace:off' Yes '-' Yes |
| |
| 'Qbtrace:bts' Yes '-' Yes |
| |
| 'Qbtrace:pt' Yes '-' Yes |
| |
| 'Qbtrace-conf:bts:size' Yes '-' Yes |
| |
| 'Qbtrace-conf:pt:size' Yes '-' Yes |
| |
| 'QNonStop' No '-' Yes |
| |
| 'QCatchSyscalls' No '-' Yes |
| |
| 'QPassSignals' No '-' Yes |
| |
| 'QStartNoAckMode' No '-' Yes |
| |
| 'multiprocess' No '-' No |
| |
| 'ConditionalBreakpoints' No '-' No |
| |
| 'ConditionalTracepoints' No '-' No |
| |
| 'ReverseContinue' No '-' No |
| |
| 'ReverseStep' No '-' No |
| |
| 'TracepointSource' No '-' No |
| |
| 'QAgent' No '-' No |
| |
| 'QAllow' No '-' No |
| |
| 'QDisableRandomization' No '-' No |
| |
| 'EnableDisableTracepoints'No '-' No |
| |
| 'QTBuffer:size' No '-' No |
| |
| 'tracenz' No '-' No |
| |
| 'BreakpointCommands' No '-' No |
| |
| 'swbreak' No '-' No |
| |
| 'hwbreak' No '-' No |
| |
| 'fork-events' No '-' No |
| |
| 'vfork-events' No '-' No |
| |
| 'exec-events' No '-' No |
| |
| 'QThreadEvents' No '-' No |
| |
| 'no-resumed' No '-' No |
| |
| |
| These are the currently defined stub features, in more detail: |
| |
| 'PacketSize=BYTES' |
| The remote stub can accept packets up to at least BYTES in |
| length. GDB will send packets up to this size for bulk |
| transfers, and will never send larger packets. This is a |
| limit on the data characters in the packet, including the |
| frame and checksum. There is no trailing NUL byte in a remote |
| protocol packet; if the stub stores packets in a |
| NUL-terminated format, it should allow an extra byte in its |
| buffer for the NUL. If this stub feature is not supported, GDB |
| guesses based on the size of the 'g' packet response. |
| |
| 'qXfer:auxv:read' |
| The remote stub understands the 'qXfer:auxv:read' packet |
| (*note qXfer auxiliary vector read::). |
| |
| 'qXfer:btrace:read' |
| The remote stub understands the 'qXfer:btrace:read' packet |
| (*note qXfer btrace read::). |
| |
| 'qXfer:btrace-conf:read' |
| The remote stub understands the 'qXfer:btrace-conf:read' |
| packet (*note qXfer btrace-conf read::). |
| |
| 'qXfer:exec-file:read' |
| The remote stub understands the 'qXfer:exec-file:read' packet |
| (*note qXfer executable filename read::). |
| |
| 'qXfer:features:read' |
| The remote stub understands the 'qXfer:features:read' packet |
| (*note qXfer target description read::). |
| |
| 'qXfer:libraries:read' |
| The remote stub understands the 'qXfer:libraries:read' packet |
| (*note qXfer library list read::). |
| |
| 'qXfer:libraries-svr4:read' |
| The remote stub understands the 'qXfer:libraries-svr4:read' |
| packet (*note qXfer svr4 library list read::). |
| |
| 'augmented-libraries-svr4-read' |
| The remote stub understands the augmented form of the |
| 'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library |
| list read::). |
| |
| 'qXfer:memory-map:read' |
| The remote stub understands the 'qXfer:memory-map:read' packet |
| (*note qXfer memory map read::). |
| |
| 'qXfer:sdata:read' |
| The remote stub understands the 'qXfer:sdata:read' packet |
| (*note qXfer sdata read::). |
| |
| 'qXfer:siginfo:read' |
| The remote stub understands the 'qXfer:siginfo:read' packet |
| (*note qXfer siginfo read::). |
| |
| 'qXfer:siginfo:write' |
| The remote stub understands the 'qXfer:siginfo:write' packet |
| (*note qXfer siginfo write::). |
| |
| 'qXfer:threads:read' |
| The remote stub understands the 'qXfer:threads:read' packet |
| (*note qXfer threads read::). |
| |
| 'qXfer:traceframe-info:read' |
| The remote stub understands the 'qXfer:traceframe-info:read' |
| packet (*note qXfer traceframe info read::). |
| |
| 'qXfer:uib:read' |
| The remote stub understands the 'qXfer:uib:read' packet (*note |
| qXfer unwind info block::). |
| |
| 'qXfer:fdpic:read' |
| The remote stub understands the 'qXfer:fdpic:read' packet |
| (*note qXfer fdpic loadmap read::). |
| |
| 'QNonStop' |
| The remote stub understands the 'QNonStop' packet (*note |
| QNonStop::). |
| |
| 'QCatchSyscalls' |
| The remote stub understands the 'QCatchSyscalls' packet (*note |
| QCatchSyscalls::). |
| |
| 'QPassSignals' |
| The remote stub understands the 'QPassSignals' packet (*note |
| QPassSignals::). |
| |
| 'QStartNoAckMode' |
| The remote stub understands the 'QStartNoAckMode' packet and |
| prefers to operate in no-acknowledgment mode. *Note Packet |
| Acknowledgment::. |
| |
| 'multiprocess' |
| The remote stub understands the multiprocess extensions to the |
| remote protocol syntax. The multiprocess extensions affect |
| the syntax of thread IDs in both packets and replies (*note |
| thread-id syntax::), and add process IDs to the 'D' packet and |
| 'W' and 'X' replies. Note that reporting this feature |
| indicates support for the syntactic extensions only, not that |
| the stub necessarily supports debugging of more than one |
| process at a time. The stub must not use multiprocess |
| extensions in packet replies unless GDB has also indicated it |
| supports them in its 'qSupported' request. |
| |
| 'qXfer:osdata:read' |
| The remote stub understands the 'qXfer:osdata:read' packet |
| ((*note qXfer osdata read::). |
| |
| 'ConditionalBreakpoints' |
| The target accepts and implements evaluation of conditional |
| expressions defined for breakpoints. The target will only |
| report breakpoint triggers when such conditions are true |
| (*note Break Conditions: Conditions.). |
| |
| 'ConditionalTracepoints' |
| The remote stub accepts and implements conditional expressions |
| defined for tracepoints (*note Tracepoint Conditions::). |
| |
| 'ReverseContinue' |
| The remote stub accepts and implements the reverse continue |
| packet (*note bc::). |
| |
| 'ReverseStep' |
| The remote stub accepts and implements the reverse step packet |
| (*note bs::). |
| |
| 'TracepointSource' |
| The remote stub understands the 'QTDPsrc' packet that supplies |
| the source form of tracepoint definitions. |
| |
| 'QAgent' |
| The remote stub understands the 'QAgent' packet. |
| |
| 'QAllow' |
| The remote stub understands the 'QAllow' packet. |
| |
| 'QDisableRandomization' |
| The remote stub understands the 'QDisableRandomization' |
| packet. |
| |
| 'StaticTracepoint' |
| The remote stub supports static tracepoints. |
| |
| 'InstallInTrace' |
| The remote stub supports installing tracepoint in tracing. |
| |
| 'EnableDisableTracepoints' |
| The remote stub supports the 'QTEnable' (*note QTEnable::) and |
| 'QTDisable' (*note QTDisable::) packets that allow tracepoints |
| to be enabled and disabled while a trace experiment is |
| running. |
| |
| 'QTBuffer:size' |
| The remote stub supports the 'QTBuffer:size' (*note |
| QTBuffer-size::) packet that allows to change the size of the |
| trace buffer. |
| |
| 'tracenz' |
| The remote stub supports the 'tracenz' bytecode for collecting |
| strings. See *note Bytecode Descriptions:: for details about |
| the bytecode. |
| |
| 'BreakpointCommands' |
| The remote stub supports running a breakpoint's command list |
| itself, rather than reporting the hit to GDB. |
| |
| 'Qbtrace:off' |
| The remote stub understands the 'Qbtrace:off' packet. |
| |
| 'Qbtrace:bts' |
| The remote stub understands the 'Qbtrace:bts' packet. |
| |
| 'Qbtrace:pt' |
| The remote stub understands the 'Qbtrace:pt' packet. |
| |
| 'Qbtrace-conf:bts:size' |
| The remote stub understands the 'Qbtrace-conf:bts:size' |
| packet. |
| |
| 'Qbtrace-conf:pt:size' |
| The remote stub understands the 'Qbtrace-conf:pt:size' packet. |
| |
| 'swbreak' |
| The remote stub reports the 'swbreak' stop reason for memory |
| breakpoints. |
| |
| 'hwbreak' |
| The remote stub reports the 'hwbreak' stop reason for hardware |
| breakpoints. |
| |
| 'fork-events' |
| The remote stub reports the 'fork' stop reason for fork |
| events. |
| |
| 'vfork-events' |
| The remote stub reports the 'vfork' stop reason for vfork |
| events and vforkdone events. |
| |
| 'exec-events' |
| The remote stub reports the 'exec' stop reason for exec |
| events. |
| |
| 'vContSupported' |
| The remote stub reports the supported actions in the reply to |
| 'vCont?' packet. |
| |
| 'QThreadEvents' |
| The remote stub understands the 'QThreadEvents' packet. |
| |
| 'no-resumed' |
| The remote stub reports the 'N' stop reply. |
| |
| 'qSymbol::' |
| Notify the target that GDB is prepared to serve symbol lookup |
| requests. Accept requests from the target for the values of |
| symbols. |
| |
| Reply: |
| 'OK' |
| The target does not need to look up any (more) symbols. |
| 'qSymbol:SYM_NAME' |
| The target requests the value of symbol SYM_NAME (hex |
| encoded). GDB may provide the value by using the |
| 'qSymbol:SYM_VALUE:SYM_NAME' message, described below. |
| |
| 'qSymbol:SYM_VALUE:SYM_NAME' |
| Set the value of SYM_NAME to SYM_VALUE. |
| |
| SYM_NAME (hex encoded) is the name of a symbol whose value the |
| target has previously requested. |
| |
| SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot |
| supply a value for SYM_NAME, then this field will be empty. |
| |
| Reply: |
| 'OK' |
| The target does not need to look up any (more) symbols. |
| 'qSymbol:SYM_NAME' |
| The target requests the value of a new symbol SYM_NAME (hex |
| encoded). GDB will continue to supply the values of symbols |
| (if available), until the target ceases to request them. |
| |
| 'qTBuffer' |
| 'QTBuffer' |
| 'QTDisconnected' |
| 'QTDP' |
| 'QTDPsrc' |
| 'QTDV' |
| 'qTfP' |
| 'qTfV' |
| 'QTFrame' |
| 'qTMinFTPILen' |
| |
| *Note Tracepoint Packets::. |
| |
| 'qThreadExtraInfo,THREAD-ID' |
| Obtain from the target OS a printable string description of thread |
| attributes for the thread THREAD-ID; see *note thread-id syntax::, |
| for the forms of THREAD-ID. This string may contain anything that |
| the target OS thinks is interesting for GDB to tell the user about |
| the thread. The string is displayed in GDB's 'info threads' |
| display. Some examples of possible thread extra info strings are |
| 'Runnable', or 'Blocked on Mutex'. |
| |
| Reply: |
| 'XX...' |
| Where 'XX...' is a hex encoding of ASCII data, comprising the |
| printable string containing the extra information about the |
| thread's attributes. |
| |
| (Note that the 'qThreadExtraInfo' packet's name is separated from |
| the command by a ',', not a ':', contrary to the naming conventions |
| above. Please don't use this packet as a model for new packets.) |
| |
| 'QTNotes' |
| 'qTP' |
| 'QTSave' |
| 'qTsP' |
| 'qTsV' |
| 'QTStart' |
| 'QTStop' |
| 'QTEnable' |
| 'QTDisable' |
| 'QTinit' |
| 'QTro' |
| 'qTStatus' |
| 'qTV' |
| 'qTfSTM' |
| 'qTsSTM' |
| 'qTSTMat' |
| *Note Tracepoint Packets::. |
| |
| 'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' |
| Read uninterpreted bytes from the target's special data area |
| identified by the keyword OBJECT. Request LENGTH bytes starting at |
| OFFSET bytes into the data. The content and encoding of ANNEX is |
| specific to OBJECT; it can supply additional details about what |
| data to access. |
| |
| 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). It is |
| possible for DATA to 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. It is possible for DATA to |
| 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. The NN part 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. |
| |
| Here are the specific requests of this form defined so far. All |
| the 'qXfer:OBJECT:read:...' requests use the same reply formats, |
| listed above. |
| |
| 'qXfer:auxv:read::OFFSET,LENGTH' |
| Access the target's "auxiliary vector". *Note auxiliary |
| vector: OS Information. Note ANNEX must be empty. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:btrace:read:ANNEX:OFFSET,LENGTH' |
| |
| Return a description of the current branch trace. *Note |
| Branch Trace Format::. The annex part of the generic 'qXfer' |
| packet may have one of the following values: |
| |
| 'all' |
| Returns all available branch trace. |
| |
| 'new' |
| Returns all available branch trace if the branch trace |
| changed since the last read request. |
| |
| 'delta' |
| Returns the new branch trace since the last read request. |
| Adds a new block to the end of the trace that begins at |
| zero and ends at the source location of the first branch |
| in the trace buffer. This extra block is used to stitch |
| traces together. |
| |
| If the trace buffer overflowed, returns an error |
| indicating the overflow. |
| |
| This packet is not probed by default; the remote stub must |
| request it by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:btrace-conf:read::OFFSET,LENGTH' |
| |
| Return a description of the current branch trace |
| configuration. *Note Branch Trace Configuration Format::. |
| |
| This packet is not probed by default; the remote stub must |
| request it by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:exec-file:read:ANNEX:OFFSET,LENGTH' |
| Return the full absolute name of the file that was executed to |
| create a process running on the remote system. The annex |
| specifies the numeric process ID of the process to query, |
| encoded as a hexadecimal number. If the annex part is empty |
| the remote stub should return the filename corresponding to |
| the currently executing process. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:features:read:ANNEX:OFFSET,LENGTH' |
| Access the "target description". *Note Target Descriptions::. |
| The annex specifies which XML document to access. The main |
| description is always loaded from the 'target.xml' annex. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:libraries:read:ANNEX:OFFSET,LENGTH' |
| Access the target's list of loaded libraries. *Note Library |
| List Format::. The annex part of the generic 'qXfer' packet |
| must be empty (*note qXfer read::). |
| |
| Targets which maintain a list of libraries in the program's |
| memory do not need to implement this packet; it is designed |
| for platforms where the operating system manages the list of |
| loaded libraries. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH' |
| Access the target's list of loaded libraries when the target |
| is an SVR4 platform. *Note Library List Format for SVR4 |
| Targets::. The annex part of the generic 'qXfer' packet must |
| be empty unless the remote stub indicated it supports the |
| augmented form of this packet by supplying an appropriate |
| 'qSupported' response (*note qXfer read::, *note |
| qSupported::). |
| |
| This packet is optional for better performance on SVR4 |
| targets. GDB uses memory read packets to read the SVR4 |
| library list otherwise. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| If the remote stub indicates it supports the augmented form of |
| this packet then the annex part of the generic 'qXfer' packet |
| may contain a semicolon-separated list of 'NAME=VALUE' |
| arguments. The currently supported arguments are: |
| |
| 'start=ADDRESS' |
| A hexadecimal number specifying the address of the |
| 'struct link_map' to start reading the library list from. |
| If unset or zero then the first 'struct link_map' in the |
| library list will be chosen as the starting point. |
| |
| 'prev=ADDRESS' |
| A hexadecimal number specifying the address of the |
| 'struct link_map' immediately preceding the 'struct |
| link_map' specified by the 'start' argument. If unset or |
| zero then the remote stub will expect that no 'struct |
| link_map' exists prior to the starting point. |
| |
| Arguments that are not understood by the remote stub will be |
| silently ignored. |
| |
| 'qXfer:memory-map:read::OFFSET,LENGTH' |
| Access the target's "memory-map". *Note Memory Map Format::. |
| The annex part of the generic 'qXfer' packet must be empty |
| (*note qXfer read::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:sdata:read::OFFSET,LENGTH' |
| |
| Read contents of the extra collected static tracepoint marker |
| information. The annex part of the generic 'qXfer' packet |
| must be empty (*note qXfer read::). *Note Tracepoint Action |
| Lists: Tracepoint Actions. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:siginfo:read::OFFSET,LENGTH' |
| Read contents of the extra signal information on the target |
| system. The annex part of the generic 'qXfer' packet must be |
| empty (*note qXfer read::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:threads:read::OFFSET,LENGTH' |
| Access the list of threads on target. *Note Thread List |
| Format::. The annex part of the generic 'qXfer' packet must |
| be empty (*note qXfer read::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:traceframe-info:read::OFFSET,LENGTH' |
| |
| Return a description of the current traceframe's contents. |
| *Note Traceframe Info Format::. The annex part of the generic |
| 'qXfer' packet must be empty (*note qXfer read::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:uib:read:PC:OFFSET,LENGTH' |
| |
| Return the unwind information block for PC. This packet is |
| used on OpenVMS/ia64 to ask the kernel unwind information. |
| |
| This packet is not probed by default. |
| |
| 'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH' |
| Read contents of 'loadmap's on the target system. The annex, |
| either 'exec' or 'interp', specifies which 'loadmap', |
| executable 'loadmap' or interpreter 'loadmap' to read. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:osdata:read::OFFSET,LENGTH' |
| Access the target's "operating system information". *Note |
| Operating System Information::. |
| |
| '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. The binary-encoded data (*note Binary Data::) to be written |
| is given by DATA.... The content and encoding of ANNEX is specific |
| to OBJECT; it can supply additional details about what data to |
| access. |
| |
| 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. The NN part 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. |
| |
| Here are the specific requests of this form defined so far. All |
| the 'qXfer:OBJECT:write:...' requests use the same reply formats, |
| listed above. |
| |
| 'qXfer:siginfo:write::OFFSET:DATA...' |
| Write DATA to the extra signal information on the target |
| system. The annex part of the generic 'qXfer' packet must be |
| empty (*note qXfer write::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:OBJECT:OPERATION:...' |
| Requests of this form may be added in the future. When a stub does |
| not recognize the OBJECT keyword, or its support for OBJECT does |
| not recognize the OPERATION keyword, the stub must respond with an |
| empty packet. |
| |
| 'qAttached:PID' |
| Return an indication of whether the remote server attached to an |
| existing process or created a new process. When the multiprocess |
| protocol extensions are supported (*note multiprocess |
| extensions::), PID is an integer in hexadecimal format identifying |
| the target process. Otherwise, GDB will omit the PID field and the |
| query packet will be simplified as 'qAttached'. |
| |
| This query is used, for example, to know whether the remote process |
| should be detached or killed when a GDB session is ended with the |
| 'quit' command. |
| |
| Reply: |
| '1' |
| The remote server attached to an existing process. |
| '0' |
| The remote server created a new process. |
| 'E NN' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace:bts' |
| Enable branch tracing for the current thread using Branch Trace |
| Store. |
| |
| Reply: |
| 'OK' |
| Branch tracing has been enabled. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace:pt' |
| Enable branch tracing for the current thread using Intel Processor |
| Trace. |
| |
| Reply: |
| 'OK' |
| Branch tracing has been enabled. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace:off' |
| Disable branch tracing for the current thread. |
| |
| Reply: |
| 'OK' |
| Branch tracing has been disabled. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace-conf:bts:size=VALUE' |
| Set the requested ring buffer size for new threads that use the |
| btrace recording method in bts format. |
| |
| Reply: |
| 'OK' |
| The ring buffer size has been set. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace-conf:pt:size=VALUE' |
| Set the requested ring buffer size for new threads that use the |
| btrace recording method in pt format. |
| |
| Reply: |
| 'OK' |
| The ring buffer size has been set. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| ---------- 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. |
| |