1 This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo.
3 Copyright (C) 1988-2014 Free Software Foundation, Inc.
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.3 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being "Free Software" and "Free Software Needs Free
9 Documentation", with the Front-Cover Texts being "A GNU Manual," and
10 with the Back-Cover Texts as in (a) below.
12 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
13 this GNU Manual. Buying copies from GNU Press supports the FSF in
14 developing GNU and promoting software freedom."
15 INFO-DIR-SECTION Software development
17 * Gdb: (gdb). The GNU debugger.
18 * gdbserver: (gdb) Server. The GNU debugging server.
21 This file documents the GNU debugger GDB.
23 This is the Tenth Edition, of 'Debugging with GDB: the GNU
24 Source-Level Debugger' for GDB (GDB) Version 7.8.1.
26 Copyright (C) 1988-2014 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.3 or
30 any later version published by the Free Software Foundation; with the
31 Invariant Sections being "Free Software" and "Free Software Needs Free
32 Documentation", with the Front-Cover Texts being "A GNU Manual," and
33 with the Back-Cover Texts as in (a) below.
35 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
36 this GNU Manual. Buying copies from GNU Press supports the FSF in
37 developing GNU and promoting software freedom."
40 File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
42 27.5.4 GDB/MI Breakpoint Information
43 ------------------------------------
45 When GDB reports information about a breakpoint, a tracepoint, a
46 watchpoint, or a catchpoint, it uses a tuple with the following fields:
49 The breakpoint number. For a breakpoint that represents one
50 location of a multi-location breakpoint, this will be a dotted
54 The type of the breakpoint. For ordinary breakpoints this will be
55 'breakpoint', but many values are possible.
58 If the type of the breakpoint is 'catchpoint', then this indicates
59 the exact type of catchpoint.
62 This is the breakpoint disposition--either 'del', meaning that the
63 breakpoint will be deleted at the next stop, or 'keep', meaning
64 that the breakpoint will not be deleted.
67 This indicates whether the breakpoint is enabled, in which case the
68 value is 'y', or disabled, in which case the value is 'n'. Note
69 that this is not the same as the field 'enable'.
72 The address of the breakpoint. This may be a hexidecimal number,
73 giving the address; or the string '<PENDING>', for a pending
74 breakpoint; or the string '<MULTIPLE>', for a breakpoint with
75 multiple locations. This field will not be present if no address
76 can be determined. For example, a watchpoint does not have an
80 If known, the function in which the breakpoint appears. If not
81 known, this field is not present.
84 The name of the source file which contains this function, if known.
85 If not known, this field is not present.
88 The full file name of the source file which contains this function,
89 if known. If not known, this field is not present.
92 The line number at which this breakpoint appears, if known. If not
93 known, this field is not present.
96 If the source file is not known, this field may be provided. If
97 provided, this holds the address of the breakpoint, possibly
98 followed by a symbol name.
101 If this breakpoint is pending, this field is present and holds the
102 text used to set the breakpoint, as entered by the user.
105 Where this breakpoint's condition is evaluated, either 'host' or
109 If this is a thread-specific breakpoint, then this identifies the
110 thread in which the breakpoint can trigger.
113 If this breakpoint is restricted to a particular Ada task, then
114 this field will hold the task identifier.
117 If the breakpoint is conditional, this is the condition expression.
120 The ignore count of the breakpoint.
123 The enable count of the breakpoint.
128 'static-tracepoint-marker-string-id'
129 For a static tracepoint, the name of the static tracepoint marker.
132 For a masked watchpoint, this is the mask.
135 A tracepoint's pass count.
138 The location of the breakpoint as originally specified by the user.
139 This field is optional.
142 The number of times the breakpoint has been hit.
145 This field is only given for tracepoints. This is either 'y',
146 meaning that the tracepoint is installed, or 'n', meaning that it
150 Some extra data, the exact contents of which are type-dependent.
152 For example, here is what the output of '-break-insert' (*note GDB/MI
153 Breakpoint Commands::) might be:
155 -> -break-insert main
156 <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
157 enabled="y",addr="0x08048564",func="main",file="myprog.c",
158 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
163 File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records
165 27.5.5 GDB/MI Frame Information
166 -------------------------------
168 Response from many MI commands includes an information about stack
169 frame. This information is a tuple that may have the following fields:
172 The level of the stack frame. The innermost frame has the level of
173 zero. This field is always present.
176 The name of the function corresponding to the frame. This field
177 may be absent if GDB is unable to determine the function name.
180 The code address for the frame. This field is always present.
183 The name of the source files that correspond to the frame's code
184 address. This field may be absent.
187 The source line corresponding to the frames' code address. This
191 The name of the binary file (either executable or shared library)
192 the corresponds to the frame's code address. This field may be
196 File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records
198 27.5.6 GDB/MI Thread Information
199 --------------------------------
201 Whenever GDB has to report an information about a thread, it uses a
202 tuple with the following fields:
205 The numeric id assigned to the thread by GDB. This field is always
209 Target-specific string identifying the thread. This field is
213 Additional information about the thread provided by the target. It
214 is supposed to be human-readable and not interpreted by the
215 frontend. This field is optional.
218 Either 'stopped' or 'running', depending on whether the thread is
219 presently running. This field is always present.
222 The value of this field is an integer number of the processor core
223 the thread was last seen on. This field is optional.
226 File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records
228 27.5.7 GDB/MI Ada Exception Information
229 ---------------------------------------
231 Whenever a '*stopped' record is emitted because the program stopped
232 after hitting an exception catchpoint (*note Set Catchpoints::), GDB
233 provides the name of the exception that was raised via the
234 'exception-name' field.
237 File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI
239 27.6 Simple Examples of GDB/MI Interaction
240 ==========================================
242 This subsection presents several simple examples of interaction using
243 the GDB/MI interface. In these examples, '->' means that the following
244 line is passed to GDB/MI as input, while '<-' means the output received
247 Note the line breaks shown in the examples are here only for
248 readability, they don't appear in the real output.
253 Setting a breakpoint generates synchronous output which contains
254 detailed information of the breakpoint.
256 -> -break-insert main
257 <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
258 enabled="y",addr="0x08048564",func="main",file="myprog.c",
259 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
266 Program execution generates asynchronous records and MI gives the reason
267 that execution stopped.
272 <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
273 frame={addr="0x08048564",func="main",
274 args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],
275 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"}
280 <- *stopped,reason="exited-normally"
286 Quitting GDB just prints the result class '^exit'.
292 Please note that '^exit' is printed immediately, but it might take
293 some time for GDB to actually exit. During that time, GDB performs
294 necessary cleanups, including killing programs being debugged or
295 disconnecting from debug hardware, so the frontend should wait till GDB
296 exits and should only forcibly kill GDB if it fails to exit in
302 Here's what happens if you pass a non-existent command:
305 <- ^error,msg="Undefined MI command: rubbish"
309 File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
311 27.7 GDB/MI Command Description Format
312 ======================================
314 The remaining sections describe blocks of commands. Each block of
315 commands is laid out in a fashion similar to this section.
320 The motivation for this collection of commands.
325 A brief introduction to this collection of commands as a whole.
330 For each command in the block, the following is described:
343 The corresponding GDB CLI command(s), if any.
348 Example(s) formatted for readability. Some of the described commands
349 have not been implemented yet and these are labeled N.A. (not
353 File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI
355 27.8 GDB/MI Breakpoint Commands
356 ===============================
358 This section documents GDB/MI commands for manipulating breakpoints.
360 The '-break-after' Command
361 --------------------------
366 -break-after NUMBER COUNT
368 The breakpoint number NUMBER is not in effect until it has been hit
369 COUNT times. To see how this is reflected in the output of the
370 '-break-list' command, see the description of the '-break-list' command
376 The corresponding GDB command is 'ignore'.
383 ^done,bkpt={number="1",type="breakpoint",disp="keep",
384 enabled="y",addr="0x000100d0",func="main",file="hello.c",
385 fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
393 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
394 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
395 {width="14",alignment="-1",col_name="type",colhdr="Type"},
396 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
397 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
398 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
399 {width="40",alignment="2",col_name="what",colhdr="What"}],
400 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
401 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
402 line="5",thread-groups=["i1"],times="0",ignore="3"}]}
405 The '-break-commands' Command
406 -----------------------------
411 -break-commands NUMBER [ COMMAND1 ... COMMANDN ]
413 Specifies the CLI commands that should be executed when breakpoint
414 NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands.
415 If no command is specified, any previously-set commands are cleared.
416 *Note Break Commands::. Typical use of this functionality is tracing a
417 program, that is, printing of values of some variables whenever
418 breakpoint is hit and then continuing.
423 The corresponding GDB command is 'commands'.
430 ^done,bkpt={number="1",type="breakpoint",disp="keep",
431 enabled="y",addr="0x000100d0",func="main",file="hello.c",
432 fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
435 -break-commands 1 "print v" "continue"
439 The '-break-condition' Command
440 ------------------------------
445 -break-condition NUMBER EXPR
447 Breakpoint NUMBER will stop the program only if the condition in EXPR
448 is true. The condition becomes part of the '-break-list' output (see
449 the description of the '-break-list' command below).
454 The corresponding GDB command is 'condition'.
464 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
465 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
466 {width="14",alignment="-1",col_name="type",colhdr="Type"},
467 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
468 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
469 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
470 {width="40",alignment="2",col_name="what",colhdr="What"}],
471 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
472 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
473 line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]}
476 The '-break-delete' Command
477 ---------------------------
482 -break-delete ( BREAKPOINT )+
484 Delete the breakpoint(s) whose number(s) are specified in the
485 argument list. This is obviously reflected in the breakpoint list.
490 The corresponding GDB command is 'delete'.
500 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
501 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
502 {width="14",alignment="-1",col_name="type",colhdr="Type"},
503 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
504 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
505 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
506 {width="40",alignment="2",col_name="what",colhdr="What"}],
510 The '-break-disable' Command
511 ----------------------------
516 -break-disable ( BREAKPOINT )+
518 Disable the named BREAKPOINT(s). The field 'enabled' in the break
519 list is now set to 'n' for the named BREAKPOINT(s).
524 The corresponding GDB command is 'disable'.
534 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
535 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
536 {width="14",alignment="-1",col_name="type",colhdr="Type"},
537 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
538 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
539 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
540 {width="40",alignment="2",col_name="what",colhdr="What"}],
541 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
542 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
543 line="5",thread-groups=["i1"],times="0"}]}
546 The '-break-enable' Command
547 ---------------------------
552 -break-enable ( BREAKPOINT )+
554 Enable (previously disabled) BREAKPOINT(s).
559 The corresponding GDB command is 'enable'.
569 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
570 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
571 {width="14",alignment="-1",col_name="type",colhdr="Type"},
572 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
573 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
574 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
575 {width="40",alignment="2",col_name="what",colhdr="What"}],
576 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
577 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
578 line="5",thread-groups=["i1"],times="0"}]}
581 The '-break-info' Command
582 -------------------------
587 -break-info BREAKPOINT
589 Get information about a single breakpoint.
591 The result is a table of breakpoints. *Note GDB/MI Breakpoint
592 Information::, for details on the format of each breakpoint in the
598 The corresponding GDB command is 'info break BREAKPOINT'.
605 The '-break-insert' Command
606 ---------------------------
611 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
612 [ -c CONDITION ] [ -i IGNORE-COUNT ]
613 [ -p THREAD-ID ] [ LOCATION ]
615 If specified, LOCATION, can be one of:
622 The possible optional parameters of this command are:
625 Insert a temporary breakpoint.
627 Insert a hardware breakpoint.
629 If LOCATION cannot be parsed (for example if it refers to unknown
630 files or functions), create a pending breakpoint. Without this
631 flag, GDB will report an error, and won't create a breakpoint, if
632 LOCATION cannot be parsed.
634 Create a disabled breakpoint.
636 Create a tracepoint. *Note Tracepoints::. When this parameter is
637 used together with '-h', a fast tracepoint is created.
639 Make the breakpoint conditional on CONDITION.
641 Initialize the IGNORE-COUNT.
643 Restrict the breakpoint to the specified THREAD-ID.
648 *Note GDB/MI Breakpoint Information::, for details on the format of the
649 resulting breakpoint.
651 Note: this format is open to change.
656 The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and
664 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
665 fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
669 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
670 fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
674 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
675 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
676 {width="14",alignment="-1",col_name="type",colhdr="Type"},
677 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
678 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
679 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
680 {width="40",alignment="2",col_name="what",colhdr="What"}],
681 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
682 addr="0x0001072c", func="main",file="recursive2.c",
683 fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
685 bkpt={number="2",type="breakpoint",disp="del",enabled="y",
686 addr="0x00010774",func="foo",file="recursive2.c",
687 fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
691 The '-dprintf-insert' Command
692 -----------------------------
697 -dprintf-insert [ -t ] [ -f ] [ -d ]
698 [ -c CONDITION ] [ -i IGNORE-COUNT ]
699 [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ]
702 If specified, LOCATION, can be one of:
709 The possible optional parameters of this command are:
712 Insert a temporary breakpoint.
714 If LOCATION cannot be parsed (for example, if it refers to unknown
715 files or functions), create a pending breakpoint. Without this
716 flag, GDB will report an error, and won't create a breakpoint, if
717 LOCATION cannot be parsed.
719 Create a disabled breakpoint.
721 Make the breakpoint conditional on CONDITION.
723 Set the ignore count of the breakpoint (*note ignore count:
724 Conditions.) to IGNORE-COUNT.
726 Restrict the breakpoint to the specified THREAD-ID.
731 *Note GDB/MI Breakpoint Information::, for details on the format of the
732 resulting breakpoint.
737 The corresponding GDB command is 'dprintf'.
743 4-dprintf-insert foo "At foo entry\n"
744 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y",
745 addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
746 fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
747 times="0",script={"printf \"At foo entry\\n\"","continue"},
748 original-location="foo"}
750 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
751 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y",
752 addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
753 fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
754 times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"},
755 original-location="mi-dprintf.c:26"}
758 The '-break-list' Command
759 -------------------------
766 Displays the list of inserted breakpoints, showing the following
770 number of the breakpoint
772 type of the breakpoint: 'breakpoint' or 'watchpoint'
774 should the breakpoint be deleted or disabled when it is hit: 'keep'
777 is the breakpoint enabled or no: 'y' or 'n'
779 memory location at which the breakpoint is set
781 logical location of the breakpoint, expressed by function name,
782 file name, line number
784 list of thread groups to which this breakpoint applies
786 number of times the breakpoint has been hit
788 If there are no breakpoints or watchpoints, the 'BreakpointTable'
789 'body' field is an empty list.
794 The corresponding GDB command is 'info break'.
801 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
802 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
803 {width="14",alignment="-1",col_name="type",colhdr="Type"},
804 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
805 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
806 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
807 {width="40",alignment="2",col_name="what",colhdr="What"}],
808 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
809 addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
811 bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
812 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
813 line="13",thread-groups=["i1"],times="0"}]}
816 Here's an example of the result when there are no breakpoints:
820 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
821 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
822 {width="14",alignment="-1",col_name="type",colhdr="Type"},
823 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
824 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
825 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
826 {width="40",alignment="2",col_name="what",colhdr="What"}],
830 The '-break-passcount' Command
831 ------------------------------
836 -break-passcount TRACEPOINT-NUMBER PASSCOUNT
838 Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If
839 the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint,
840 error is emitted. This corresponds to CLI command 'passcount'.
842 The '-break-watch' Command
843 --------------------------
848 -break-watch [ -a | -r ]
850 Create a watchpoint. With the '-a' option it will create an "access"
851 watchpoint, i.e., a watchpoint that triggers either on a read from or on
852 a write to the memory location. With the '-r' option, the watchpoint
853 created is a "read" watchpoint, i.e., it will trigger only when the
854 memory location is accessed for reading. Without either of the options,
855 the watchpoint created is a regular watchpoint, i.e., it will trigger
856 when the memory location is accessed for writing. *Note Setting
857 Watchpoints: Set Watchpoints.
859 Note that '-break-list' will report a single list of watchpoints and
860 breakpoints inserted.
865 The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'.
870 Setting a watchpoint on a variable in the 'main' function:
874 ^done,wpt={number="2",exp="x"}
879 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
880 value={old="-268439212",new="55"},
881 frame={func="main",args=[],file="recursive2.c",
882 fullname="/home/foo/bar/recursive2.c",line="5"}
885 Setting a watchpoint on a variable local to a function. GDB will
886 stop the program execution twice: first for the variable changing value,
887 then for the watchpoint going out of scope.
891 ^done,wpt={number="5",exp="C"}
896 *stopped,reason="watchpoint-trigger",
897 wpt={number="5",exp="C"},value={old="-276895068",new="3"},
898 frame={func="callee4",args=[],
899 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
900 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
905 *stopped,reason="watchpoint-scope",wpnum="5",
906 frame={func="callee3",args=[{name="strarg",
907 value="0x11940 \"A string argument.\""}],
908 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
909 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
912 Listing breakpoints and watchpoints, at different points in the
913 program execution. Note that once the watchpoint goes out of scope, it
918 ^done,wpt={number="2",exp="C"}
921 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
922 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
923 {width="14",alignment="-1",col_name="type",colhdr="Type"},
924 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
925 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
926 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
927 {width="40",alignment="2",col_name="what",colhdr="What"}],
928 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
929 addr="0x00010734",func="callee4",
930 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
931 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
933 bkpt={number="2",type="watchpoint",disp="keep",
934 enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]}
939 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
940 value={old="-276895068",new="3"},
941 frame={func="callee4",args=[],
942 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
943 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
946 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
947 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
948 {width="14",alignment="-1",col_name="type",colhdr="Type"},
949 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
950 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
951 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
952 {width="40",alignment="2",col_name="what",colhdr="What"}],
953 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
954 addr="0x00010734",func="callee4",
955 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
956 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
958 bkpt={number="2",type="watchpoint",disp="keep",
959 enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]}
963 ^done,reason="watchpoint-scope",wpnum="2",
964 frame={func="callee3",args=[{name="strarg",
965 value="0x11940 \"A string argument.\""}],
966 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
967 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
970 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
971 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
972 {width="14",alignment="-1",col_name="type",colhdr="Type"},
973 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
974 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
975 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
976 {width="40",alignment="2",col_name="what",colhdr="What"}],
977 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
978 addr="0x00010734",func="callee4",
979 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
980 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
981 thread-groups=["i1"],times="1"}]}
985 File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
987 27.9 GDB/MI Catchpoint Commands
988 ===============================
990 This section documents GDB/MI commands for manipulating catchpoints.
994 * Shared Library GDB/MI Catchpoint Commands::
995 * Ada Exception GDB/MI Catchpoint Commands::
998 File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
1000 27.9.1 Shared Library GDB/MI Catchpoints
1001 ----------------------------------------
1003 The '-catch-load' Command
1004 -------------------------
1009 -catch-load [ -t ] [ -d ] REGEXP
1011 Add a catchpoint for library load events. If the '-t' option is
1012 used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
1013 Breaks.). If the '-d' option is used, the catchpoint is created in a
1014 disabled state. The 'regexp' argument is a regular expression used to
1015 match the name of the loaded library.
1020 The corresponding GDB command is 'catch load'.
1025 -catch-load -t foo.so
1026 ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y",
1027 what="load of library matching foo.so",catch-type="load",times="0"}
1030 The '-catch-unload' Command
1031 ---------------------------
1036 -catch-unload [ -t ] [ -d ] REGEXP
1038 Add a catchpoint for library unload events. If the '-t' option is
1039 used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
1040 Breaks.). If the '-d' option is used, the catchpoint is created in a
1041 disabled state. The 'regexp' argument is a regular expression used to
1042 match the name of the unloaded library.
1047 The corresponding GDB command is 'catch unload'.
1052 -catch-unload -d bar.so
1053 ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n",
1054 what="load of library matching bar.so",catch-type="unload",times="0"}
1058 File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
1060 27.9.2 Ada Exception GDB/MI Catchpoints
1061 ---------------------------------------
1063 The following GDB/MI commands can be used to create catchpoints that
1064 stop the execution when Ada exceptions are being raised.
1066 The '-catch-assert' Command
1067 ---------------------------
1072 -catch-assert [ -c CONDITION] [ -d ] [ -t ]
1074 Add a catchpoint for failed Ada assertions.
1076 The possible optional parameters for this command are:
1079 Make the catchpoint conditional on CONDITION.
1081 Create a disabled catchpoint.
1083 Create a temporary catchpoint.
1088 The corresponding GDB command is 'catch assert'.
1094 ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep",
1095 enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
1096 thread-groups=["i1"],times="0",
1097 original-location="__gnat_debug_raise_assert_failure"}
1100 The '-catch-exception' Command
1101 ------------------------------
1106 -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ]
1109 Add a catchpoint stopping when Ada exceptions are raised. By
1110 default, the command stops the program when any Ada exception gets
1111 raised. But it is also possible, by using some of the optional
1112 parameters described below, to create more selective catchpoints.
1114 The possible optional parameters for this command are:
1117 Make the catchpoint conditional on CONDITION.
1119 Create a disabled catchpoint.
1121 Only stop when EXCEPTION-NAME is raised. This option cannot be
1122 used combined with '-u'.
1124 Create a temporary catchpoint.
1126 Stop only when an unhandled exception gets raised. This option
1127 cannot be used combined with '-e'.
1132 The corresponding GDB commands are 'catch exception' and 'catch
1133 exception unhandled'.
1138 -catch-exception -e Program_Error
1139 ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep",
1140 enabled="y",addr="0x0000000000404874",
1141 what="`Program_Error' Ada exception", thread-groups=["i1"],
1142 times="0",original-location="__gnat_debug_raise_exception"}
1146 File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI
1148 27.10 GDB/MI Program Context
1149 ============================
1151 The '-exec-arguments' Command
1152 -----------------------------
1157 -exec-arguments ARGS
1159 Set the inferior program arguments, to be used in the next
1165 The corresponding GDB command is 'set args'.
1171 -exec-arguments -v word
1175 The '-environment-cd' Command
1176 -----------------------------
1181 -environment-cd PATHDIR
1183 Set GDB's working directory.
1188 The corresponding GDB command is 'cd'.
1194 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1198 The '-environment-directory' Command
1199 ------------------------------------
1204 -environment-directory [ -r ] [ PATHDIR ]+
1206 Add directories PATHDIR to beginning of search path for source files.
1207 If the '-r' option is used, the search path is reset to the default
1208 search path. If directories PATHDIR are supplied in addition to the
1209 '-r' option, the search path is first reset and then addition occurs as
1210 normal. Multiple directories may be specified, separated by blanks.
1211 Specifying multiple directories in a single command results in the
1212 directories added to the beginning of the search path in the same order
1213 they were presented in the command. If blanks are needed as part of a
1214 directory name, double-quotes should be used around the name. In the
1215 command output, the path will show up separated by the system
1216 directory-separator character. The directory-separator character must
1217 not be used in any directory name. If no directories are specified, the
1218 current search path is displayed.
1223 The corresponding GDB command is 'dir'.
1229 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1230 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
1232 -environment-directory ""
1233 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
1235 -environment-directory -r /home/jjohnstn/src/gdb /usr/src
1236 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
1238 -environment-directory -r
1239 ^done,source-path="$cdir:$cwd"
1242 The '-environment-path' Command
1243 -------------------------------
1248 -environment-path [ -r ] [ PATHDIR ]+
1250 Add directories PATHDIR to beginning of search path for object files.
1251 If the '-r' option is used, the search path is reset to the original
1252 search path that existed at gdb start-up. If directories PATHDIR are
1253 supplied in addition to the '-r' option, the search path is first reset
1254 and then addition occurs as normal. Multiple directories may be
1255 specified, separated by blanks. Specifying multiple directories in a
1256 single command results in the directories added to the beginning of the
1257 search path in the same order they were presented in the command. If
1258 blanks are needed as part of a directory name, double-quotes should be
1259 used around the name. In the command output, the path will show up
1260 separated by the system directory-separator character. The
1261 directory-separator character must not be used in any directory name.
1262 If no directories are specified, the current path is displayed.
1267 The corresponding GDB command is 'path'.
1274 ^done,path="/usr/bin"
1276 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
1277 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
1279 -environment-path -r /usr/local/bin
1280 ^done,path="/usr/local/bin:/usr/bin"
1283 The '-environment-pwd' Command
1284 ------------------------------
1291 Show the current working directory.
1296 The corresponding GDB command is 'pwd'.
1303 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
1307 File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI
1309 27.11 GDB/MI Thread Commands
1310 ============================
1312 The '-thread-info' Command
1313 --------------------------
1318 -thread-info [ THREAD-ID ]
1320 Reports information about either a specific thread, if the THREAD-ID
1321 parameter is present, or about all threads. When printing information
1322 about all threads, also reports the current thread.
1327 The 'info thread' command prints the same information about all threads.
1332 The result is a list of threads. The following attributes are defined
1336 This field exists only for the current thread. It has the value
1340 The identifier that GDB uses to refer to the thread.
1343 The identifier that the target uses to refer to the thread.
1346 Extra information about the thread, in a target-specific format.
1347 This field is optional.
1350 The name of the thread. If the user specified a name using the
1351 'thread name' command, then this name is given. Otherwise, if GDB
1352 can extract the thread name from the target, then that name is
1353 given. If GDB cannot find the thread name, then this field is
1357 The stack frame currently executing in the thread.
1360 The thread's state. The 'state' field may have the following
1364 The thread is stopped. Frame information is available for
1368 The thread is running. There's no frame information for
1372 If GDB can find the CPU core on which this thread is running, then
1373 this field is the core identifier. This field is optional.
1380 {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
1381 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",
1382 args=[]},state="running"},
1383 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
1384 frame={level="0",addr="0x0804891f",func="foo",
1385 args=[{name="i",value="10"}],
1386 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},
1388 current-thread-id="1"
1391 The '-thread-list-ids' Command
1392 ------------------------------
1399 Produces a list of the currently known GDB thread ids. At the end of
1400 the list it also prints the total number of such threads.
1402 This command is retained for historical reasons, the '-thread-info'
1403 command should be used instead.
1408 Part of 'info threads' supplies the same information.
1415 ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
1416 current-thread-id="1",number-of-threads="3"
1419 The '-thread-select' Command
1420 ----------------------------
1425 -thread-select THREADNUM
1427 Make THREADNUM the current thread. It prints the number of the new
1428 current thread, and the topmost frame for that thread.
1430 This command is deprecated in favor of explicitly using the
1431 '--thread' option to each command.
1436 The corresponding GDB command is 'thread'.
1445 *stopped,reason="end-stepping-range",thread-id="2",line="187",
1446 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
1450 thread-ids={thread-id="3",thread-id="2",thread-id="1"},
1451 number-of-threads="3"
1454 ^done,new-thread-id="3",
1455 frame={level="0",func="vprintf",
1456 args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
1457 {name="arg",value="0x2"}],file="vprintf.c",line="31"}
1461 File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI
1463 27.12 GDB/MI Ada Tasking Commands
1464 =================================
1466 The '-ada-task-info' Command
1467 ----------------------------
1472 -ada-task-info [ TASK-ID ]
1474 Reports information about either a specific Ada task, if the TASK-ID
1475 parameter is present, or about all Ada tasks.
1480 The 'info tasks' command prints the same information about all Ada tasks
1481 (*note Ada Tasks::).
1486 The result is a table of Ada tasks. The following columns are defined
1490 This field exists only for the current thread. It has the value
1494 The identifier that GDB uses to refer to the Ada task.
1497 The identifier that the target uses to refer to the Ada task.
1500 The identifier of the thread corresponding to the Ada task.
1502 This field should always exist, as Ada tasks are always implemented
1503 on top of a thread. But if GDB cannot find this corresponding
1504 thread for any reason, the field is omitted.
1507 This field exists only when the task was created by another task.
1508 In this case, it provides the ID of the parent task.
1511 The base priority of the task.
1514 The current state of the task. For a detailed description of the
1515 possible states, see *note Ada Tasks::.
1518 The name of the task.
1524 ^done,tasks={nr_rows="3",nr_cols="8",
1525 hdr=[{width="1",alignment="-1",col_name="current",colhdr=""},
1526 {width="3",alignment="1",col_name="id",colhdr="ID"},
1527 {width="9",alignment="1",col_name="task-id",colhdr="TID"},
1528 {width="4",alignment="1",col_name="thread-id",colhdr=""},
1529 {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"},
1530 {width="3",alignment="1",col_name="priority",colhdr="Pri"},
1531 {width="22",alignment="-1",col_name="state",colhdr="State"},
1532 {width="1",alignment="2",col_name="name",colhdr="Name"}],
1533 body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48",
1534 state="Child Termination Wait",name="main_task"}]}
1538 File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI
1540 27.13 GDB/MI Program Execution
1541 ==============================
1543 These are the asynchronous commands which generate the out-of-band
1544 record '*stopped'. Currently GDB only really executes asynchronously
1545 with remote targets and this interaction is mimicked in other cases.
1547 The '-exec-continue' Command
1548 ----------------------------
1553 -exec-continue [--reverse] [--all|--thread-group N]
1555 Resumes the execution of the inferior program, which will continue to
1556 execute until it reaches a debugger stop event. If the '--reverse'
1557 option is specified, execution resumes in reverse until it reaches a
1558 stop event. Stop events may include
1559 * breakpoints or watchpoints
1560 * signals or exceptions
1561 * the end of the process (or its beginning under '--reverse')
1562 * the end or beginning of a replay log if one is being used.
1563 In all-stop mode (*note All-Stop Mode::), may resume only one thread,
1564 or all threads, depending on the value of the 'scheduler-locking'
1565 variable. If '--all' is specified, all threads (in all inferiors) will
1566 be resumed. The '--all' option is ignored in all-stop mode. If the
1567 '--thread-group' options is specified, then all threads in that thread
1573 The corresponding GDB corresponding is 'continue'.
1582 *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={
1583 func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
1587 The '-exec-finish' Command
1588 --------------------------
1593 -exec-finish [--reverse]
1595 Resumes the execution of the inferior program until the current
1596 function is exited. Displays the results returned by the function. If
1597 the '--reverse' option is specified, resumes the reverse execution of
1598 the inferior program until the point where current function was called.
1603 The corresponding GDB command is 'finish'.
1608 Function returning 'void'.
1614 *stopped,reason="function-finished",frame={func="main",args=[],
1615 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
1618 Function returning other than 'void'. The name of the internal GDB
1619 variable storing the result is printed, together with the value itself.
1624 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
1625 args=[{name="a",value="1"],{name="b",value="9"}},
1626 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1627 gdb-result-var="$1",return-value="0"
1630 The '-exec-interrupt' Command
1631 -----------------------------
1636 -exec-interrupt [--all|--thread-group N]
1638 Interrupts the background execution of the target. Note how the
1639 token associated with the stop message is the one for the execution
1640 command that has been interrupted. The token for the interrupt itself
1641 only appears in the '^done' output. If the user is trying to interrupt
1642 a non-running program, an error message will be printed.
1644 Note that when asynchronous execution is enabled, this command is
1645 asynchronous just like other execution commands. That is, first the
1646 '^done' response will be printed, and the target stop will be reported
1647 after that using the '*stopped' notification.
1649 In non-stop mode, only the context thread is interrupted by default.
1650 All threads (in all inferiors) will be interrupted if the '--all' option
1651 is specified. If the '--thread-group' option is specified, all threads
1652 in that group will be interrupted.
1657 The corresponding GDB command is 'interrupt'.
1670 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1671 frame={addr="0x00010140",func="foo",args=[],file="try.c",
1672 fullname="/home/foo/bar/try.c",line="13"}
1677 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1680 The '-exec-jump' Command
1681 ------------------------
1688 Resumes execution of the inferior program at the location specified
1689 by parameter. *Note Specify Location::, for a description of the
1690 different forms of LOCATION.
1695 The corresponding GDB command is 'jump'.
1701 *running,thread-id="all"
1704 The '-exec-next' Command
1705 ------------------------
1710 -exec-next [--reverse]
1712 Resumes execution of the inferior program, stopping when the
1713 beginning of the next source line is reached.
1715 If the '--reverse' option is specified, resumes reverse execution of
1716 the inferior program, stopping at the beginning of the previous source
1717 line. If you issue this command on the first line of a function, it
1718 will take you back to the caller of that function, to the source line
1719 where the function was called.
1724 The corresponding GDB command is 'next'.
1732 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1735 The '-exec-next-instruction' Command
1736 ------------------------------------
1741 -exec-next-instruction [--reverse]
1743 Executes one machine instruction. If the instruction is a function
1744 call, continues until the function returns. If the program stops at an
1745 instruction in the middle of a source line, the address will be printed
1748 If the '--reverse' option is specified, resumes reverse execution of
1749 the inferior program, stopping at the previous instruction. If the
1750 previously executed instruction was a return from another function, it
1751 will continue to execute in reverse until the call to that function
1752 (from the current stack frame) is reached.
1757 The corresponding GDB command is 'nexti'.
1763 -exec-next-instruction
1767 *stopped,reason="end-stepping-range",
1768 addr="0x000100d4",line="5",file="hello.c"
1771 The '-exec-return' Command
1772 --------------------------
1779 Makes current function return immediately. Doesn't execute the
1780 inferior. Displays the new current frame.
1785 The corresponding GDB command is 'return'.
1791 200-break-insert callee4
1792 200^done,bkpt={number="1",addr="0x00010734",
1793 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
1798 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
1799 frame={func="callee4",args=[],
1800 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1801 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
1807 111^done,frame={level="0",func="callee3",
1808 args=[{name="strarg",
1809 value="0x11940 \"A string argument.\""}],
1810 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1811 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
1814 The '-exec-run' Command
1815 -----------------------
1820 -exec-run [ --all | --thread-group N ] [ --start ]
1822 Starts execution of the inferior from the beginning. The inferior
1823 executes until either a breakpoint is encountered or the program exits.
1824 In the latter case the output will include an exit code, if the program
1825 has exited exceptionally.
1827 When neither the '--all' nor the '--thread-group' option is
1828 specified, the current inferior is started. If the '--thread-group'
1829 option is specified, it should refer to a thread group of type
1830 'process', and that thread group will be started. If the '--all' option
1831 is specified, then all inferiors will be started.
1833 Using the '--start' option instructs the debugger to stop the
1834 execution at the start of the inferior's main subprogram, following the
1835 same behavior as the 'start' command (*note Starting::).
1840 The corresponding GDB command is 'run'.
1847 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
1852 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
1853 frame={func="main",args=[],file="recursive2.c",
1854 fullname="/home/foo/bar/recursive2.c",line="4"}
1857 Program exited normally:
1864 *stopped,reason="exited-normally"
1867 Program exited exceptionally:
1874 *stopped,reason="exited",exit-code="01"
1877 Another way the program can terminate is if it receives a signal such
1878 as 'SIGINT'. In this case, GDB/MI displays this:
1881 *stopped,reason="exited-signalled",signal-name="SIGINT",
1882 signal-meaning="Interrupt"
1884 The '-exec-step' Command
1885 ------------------------
1890 -exec-step [--reverse]
1892 Resumes execution of the inferior program, stopping when the
1893 beginning of the next source line is reached, if the next source line is
1894 not a function call. If it is, stop at the first instruction of the
1895 called function. If the '--reverse' option is specified, resumes
1896 reverse execution of the inferior program, stopping at the beginning of
1897 the previously executed source line.
1902 The corresponding GDB command is 'step'.
1907 Stepping into a function:
1912 *stopped,reason="end-stepping-range",
1913 frame={func="foo",args=[{name="a",value="10"},
1914 {name="b",value="0"}],file="recursive2.c",
1915 fullname="/home/foo/bar/recursive2.c",line="11"}
1923 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
1926 The '-exec-step-instruction' Command
1927 ------------------------------------
1932 -exec-step-instruction [--reverse]
1934 Resumes the inferior which executes one machine instruction. If the
1935 '--reverse' option is specified, resumes reverse execution of the
1936 inferior program, stopping at the previously executed instruction. The
1937 output, once GDB has stopped, will vary depending on whether we have
1938 stopped in the middle of a source line or not. In the former case, the
1939 address at which the program stopped will be printed as well.
1944 The corresponding GDB command is 'stepi'.
1950 -exec-step-instruction
1954 *stopped,reason="end-stepping-range",
1955 frame={func="foo",args=[],file="try.c",
1956 fullname="/home/foo/bar/try.c",line="10"}
1958 -exec-step-instruction
1962 *stopped,reason="end-stepping-range",
1963 frame={addr="0x000100f4",func="foo",args=[],file="try.c",
1964 fullname="/home/foo/bar/try.c",line="10"}
1967 The '-exec-until' Command
1968 -------------------------
1973 -exec-until [ LOCATION ]
1975 Executes the inferior until the LOCATION specified in the argument is
1976 reached. If there is no argument, the inferior executes until a source
1977 line greater than the current one is reached. The reason for stopping
1978 in this case will be 'location-reached'.
1983 The corresponding GDB command is 'until'.
1989 -exec-until recursive2.c:6
1993 *stopped,reason="location-reached",frame={func="main",args=[],
1994 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
1998 File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
2000 27.14 GDB/MI Stack Manipulation Commands
2001 ========================================
2003 The '-enable-frame-filters' Command
2004 -----------------------------------
2006 -enable-frame-filters
2008 GDB allows Python-based frame filters to affect the output of the MI
2009 commands relating to stack traces. As there is no way to implement this
2010 in a fully backward-compatible way, a front end must request that this
2011 functionality be enabled.
2013 Once enabled, this feature cannot be disabled.
2015 Note that if Python support has not been compiled into GDB, this
2016 command will still succeed (and do nothing).
2018 The '-stack-info-frame' Command
2019 -------------------------------
2026 Get info on the selected frame.
2031 The corresponding GDB command is 'info frame' or 'frame' (without
2039 ^done,frame={level="1",addr="0x0001076c",func="callee3",
2040 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2041 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
2044 The '-stack-info-depth' Command
2045 -------------------------------
2050 -stack-info-depth [ MAX-DEPTH ]
2052 Return the depth of the stack. If the integer argument MAX-DEPTH is
2053 specified, do not count beyond MAX-DEPTH frames.
2058 There's no equivalent GDB command.
2063 For a stack with frame levels 0 through 11:
2072 -stack-info-depth 12
2075 -stack-info-depth 11
2078 -stack-info-depth 13
2082 The '-stack-list-arguments' Command
2083 -----------------------------------
2088 -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
2089 [ LOW-FRAME HIGH-FRAME ]
2091 Display a list of the arguments for the frames between LOW-FRAME and
2092 HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
2093 list the arguments for the whole call stack. If the two arguments are
2094 equal, show the single frame at the corresponding level. It is an error
2095 if LOW-FRAME is larger than the actual number of frames. On the other
2096 hand, HIGH-FRAME may be larger than the actual number of frames, in
2097 which case only existing frames will be returned.
2099 If PRINT-VALUES is 0 or '--no-values', print only the names of the
2100 variables; if it is 1 or '--all-values', print also their values; and if
2101 it is 2 or '--simple-values', print the name, type and value for simple
2102 data types, and the name and type for arrays, structures and unions. If
2103 the option '--no-frame-filters' is supplied, then Python frame filters
2104 will not be executed.
2106 If the '--skip-unavailable' option is specified, arguments that are
2107 not available are not listed. Partially available arguments are still
2110 Use of this command to obtain arguments in a single frame is
2111 deprecated in favor of the '-stack-list-variables' command.
2116 GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args'
2117 command which partially overlaps with the functionality of
2118 '-stack-list-arguments'.
2127 frame={level="0",addr="0x00010734",func="callee4",
2128 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2129 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
2130 frame={level="1",addr="0x0001076c",func="callee3",
2131 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2132 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
2133 frame={level="2",addr="0x0001078c",func="callee2",
2134 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2135 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
2136 frame={level="3",addr="0x000107b4",func="callee1",
2137 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2138 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
2139 frame={level="4",addr="0x000107e0",func="main",
2140 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2141 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
2143 -stack-list-arguments 0
2146 frame={level="0",args=[]},
2147 frame={level="1",args=[name="strarg"]},
2148 frame={level="2",args=[name="intarg",name="strarg"]},
2149 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
2150 frame={level="4",args=[]}]
2152 -stack-list-arguments 1
2155 frame={level="0",args=[]},
2157 args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
2158 frame={level="2",args=[
2159 {name="intarg",value="2"},
2160 {name="strarg",value="0x11940 \"A string argument.\""}]},
2161 {frame={level="3",args=[
2162 {name="intarg",value="2"},
2163 {name="strarg",value="0x11940 \"A string argument.\""},
2164 {name="fltarg",value="3.5"}]},
2165 frame={level="4",args=[]}]
2167 -stack-list-arguments 0 2 2
2168 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
2170 -stack-list-arguments 1 2 2
2171 ^done,stack-args=[frame={level="2",
2172 args=[{name="intarg",value="2"},
2173 {name="strarg",value="0x11940 \"A string argument.\""}]}]
2176 The '-stack-list-frames' Command
2177 --------------------------------
2182 -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ]
2184 List the frames currently on the stack. For each frame it displays
2188 The frame number, 0 being the topmost frame, i.e., the innermost
2191 The '$pc' value for that frame.
2195 File name of the source file where the function lives.
2197 The full file name of the source file where the function lives.
2199 Line number corresponding to the '$pc'.
2201 The shared library where this function is defined. This is only
2202 given if the frame's function is not known.
2204 If invoked without arguments, this command prints a backtrace for the
2205 whole stack. If given two integer arguments, it shows the frames whose
2206 levels are between the two arguments (inclusive). If the two arguments
2207 are equal, it shows the single frame at the corresponding level. It is
2208 an error if LOW-FRAME is larger than the actual number of frames. On
2209 the other hand, HIGH-FRAME may be larger than the actual number of
2210 frames, in which case only existing frames will be returned. If the
2211 option '--no-frame-filters' is supplied, then Python frame filters will
2217 The corresponding GDB commands are 'backtrace' and 'where'.
2222 Full stack backtrace:
2227 [frame={level="0",addr="0x0001076c",func="foo",
2228 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
2229 frame={level="1",addr="0x000107a4",func="foo",
2230 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2231 frame={level="2",addr="0x000107a4",func="foo",
2232 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2233 frame={level="3",addr="0x000107a4",func="foo",
2234 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2235 frame={level="4",addr="0x000107a4",func="foo",
2236 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2237 frame={level="5",addr="0x000107a4",func="foo",
2238 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2239 frame={level="6",addr="0x000107a4",func="foo",
2240 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2241 frame={level="7",addr="0x000107a4",func="foo",
2242 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2243 frame={level="8",addr="0x000107a4",func="foo",
2244 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2245 frame={level="9",addr="0x000107a4",func="foo",
2246 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2247 frame={level="10",addr="0x000107a4",func="foo",
2248 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2249 frame={level="11",addr="0x00010738",func="main",
2250 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
2253 Show frames between LOW_FRAME and HIGH_FRAME:
2256 -stack-list-frames 3 5
2258 [frame={level="3",addr="0x000107a4",func="foo",
2259 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2260 frame={level="4",addr="0x000107a4",func="foo",
2261 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2262 frame={level="5",addr="0x000107a4",func="foo",
2263 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
2266 Show a single frame:
2269 -stack-list-frames 3 3
2271 [frame={level="3",addr="0x000107a4",func="foo",
2272 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
2275 The '-stack-list-locals' Command
2276 --------------------------------
2281 -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
2283 Display the local variable names for the selected frame. If
2284 PRINT-VALUES is 0 or '--no-values', print only the names of the
2285 variables; if it is 1 or '--all-values', print also their values; and if
2286 it is 2 or '--simple-values', print the name, type and value for simple
2287 data types, and the name and type for arrays, structures and unions. In
2288 this last case, a frontend can immediately display the value of simple
2289 data types and create variable objects for other data types when the
2290 user wishes to explore their values in more detail. If the option
2291 '--no-frame-filters' is supplied, then Python frame filters will not be
2294 If the '--skip-unavailable' option is specified, local variables that
2295 are not available are not listed. Partially available local variables
2296 are still displayed, however.
2298 This command is deprecated in favor of the '-stack-list-variables'
2304 'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'.
2310 -stack-list-locals 0
2311 ^done,locals=[name="A",name="B",name="C"]
2313 -stack-list-locals --all-values
2314 ^done,locals=[{name="A",value="1"},{name="B",value="2"},
2315 {name="C",value="{1, 2, 3}"}]
2316 -stack-list-locals --simple-values
2317 ^done,locals=[{name="A",type="int",value="1"},
2318 {name="B",type="int",value="2"},{name="C",type="int [3]"}]
2321 The '-stack-list-variables' Command
2322 -----------------------------------
2327 -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
2329 Display the names of local variables and function arguments for the
2330 selected frame. If PRINT-VALUES is 0 or '--no-values', print only the
2331 names of the variables; if it is 1 or '--all-values', print also their
2332 values; and if it is 2 or '--simple-values', print the name, type and
2333 value for simple data types, and the name and type for arrays,
2334 structures and unions. If the option '--no-frame-filters' is supplied,
2335 then Python frame filters will not be executed.
2337 If the '--skip-unavailable' option is specified, local variables and
2338 arguments that are not available are not listed. Partially available
2339 arguments and local variables are still displayed, however.
2345 -stack-list-variables --thread 1 --frame 0 --all-values
2346 ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}]
2349 The '-stack-select-frame' Command
2350 ---------------------------------
2355 -stack-select-frame FRAMENUM
2357 Change the selected frame. Select a different frame FRAMENUM on the
2360 This command in deprecated in favor of passing the '--frame' option
2366 The corresponding GDB commands are 'frame', 'up', 'down',
2367 'select-frame', 'up-silent', and 'down-silent'.
2373 -stack-select-frame 2
2378 File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
2380 27.15 GDB/MI Variable Objects
2381 =============================
2383 Introduction to Variable Objects
2384 --------------------------------
2386 Variable objects are "object-oriented" MI interface for examining and
2387 changing values of expressions. Unlike some other MI interfaces that
2388 work with expressions, variable objects are specifically designed for
2389 simple and efficient presentation in the frontend. A variable object is
2390 identified by string name. When a variable object is created, the
2391 frontend specifies the expression for that variable object. The
2392 expression can be a simple variable, or it can be an arbitrary complex
2393 expression, and can even involve CPU registers. After creating a
2394 variable object, the frontend can invoke other variable object
2395 operations--for example to obtain or change the value of a variable
2396 object, or to change display format.
2398 Variable objects have hierarchical tree structure. Any variable
2399 object that corresponds to a composite type, such as structure in C, has
2400 a number of child variable objects, for example corresponding to each
2401 element of a structure. A child variable object can itself have
2402 children, recursively. Recursion ends when we reach leaf variable
2403 objects, which always have built-in types. Child variable objects are
2404 created only by explicit request, so if a frontend is not interested in
2405 the children of a particular variable object, no child will be created.
2407 For a leaf variable object it is possible to obtain its value as a
2408 string, or set the value from a string. String value can be also
2409 obtained for a non-leaf variable object, but it's generally a string
2410 that only indicates the type of the object, and does not list its
2411 contents. Assignment to a non-leaf variable object is not allowed.
2413 A frontend does not need to read the values of all variable objects
2414 each time the program stops. Instead, MI provides an update command
2415 that lists all variable objects whose values has changed since the last
2416 update operation. This considerably reduces the amount of data that
2417 must be transferred to the frontend. As noted above, children variable
2418 objects are created on demand, and only leaf variable objects have a
2419 real value. As result, gdb will read target memory only for leaf
2420 variables that frontend has created.
2422 The automatic update is not always desirable. For example, a
2423 frontend might want to keep a value of some expression for future
2424 reference, and never update it. For another example, fetching memory is
2425 relatively slow for embedded targets, so a frontend might want to
2426 disable automatic update for the variables that are either not visible
2427 on the screen, or "closed". This is possible using so called "frozen
2428 variable objects". Such variable objects are never implicitly updated.
2430 Variable objects can be either "fixed" or "floating". For the fixed
2431 variable object, the expression is parsed when the variable object is
2432 created, including associating identifiers to specific variables. The
2433 meaning of expression never changes. For a floating variable object the
2434 values of variables whose names appear in the expressions are
2435 re-evaluated every time in the context of the current frame. Consider
2440 struct work_state state;
2446 If a fixed variable object for the 'state' variable is created in
2447 this function, and we enter the recursive call, the variable object will
2448 report the value of 'state' in the top-level 'do_work' invocation. On
2449 the other hand, a floating variable object will report the value of
2450 'state' in the current frame.
2452 If an expression specified when creating a fixed variable object
2453 refers to a local variable, the variable object becomes bound to the
2454 thread and frame in which the variable object is created. When such
2455 variable object is updated, GDB makes sure that the thread/frame
2456 combination the variable object is bound to still exists, and
2457 re-evaluates the variable object in context of that thread/frame.
2459 The following is the complete set of GDB/MI operations defined to
2460 access this functionality:
2462 *Operation* *Description*
2464 '-enable-pretty-printing' enable Python-based pretty-printing
2465 '-var-create' create a variable object
2466 '-var-delete' delete the variable object and/or its
2468 '-var-set-format' set the display format of this variable
2469 '-var-show-format' show the display format of this variable
2470 '-var-info-num-children' tells how many children this object has
2471 '-var-list-children' return a list of the object's children
2472 '-var-info-type' show the type of this variable object
2473 '-var-info-expression' print parent-relative expression that
2474 this variable object represents
2475 '-var-info-path-expression' print full expression that this variable
2477 '-var-show-attributes' is this variable editable? does it exist
2479 '-var-evaluate-expression' get the value of this variable
2480 '-var-assign' set the value of this variable
2481 '-var-update' update the variable and its children
2482 '-var-set-frozen' set frozeness attribute
2483 '-var-set-update-range' set range of children to display on
2486 In the next subsection we describe each operation in detail and
2487 suggest how it can be used.
2489 Description And Use of Operations on Variable Objects
2490 -----------------------------------------------------
2492 The '-enable-pretty-printing' Command
2493 -------------------------------------
2495 -enable-pretty-printing
2497 GDB allows Python-based visualizers to affect the output of the MI
2498 variable object commands. However, because there was no way to
2499 implement this in a fully backward-compatible way, a front end must
2500 request that this functionality be enabled.
2502 Once enabled, this feature cannot be disabled.
2504 Note that if Python support has not been compiled into GDB, this
2505 command will still succeed (and do nothing).
2507 This feature is currently (as of GDB 7.0) experimental, and may work
2508 differently in future versions of GDB.
2510 The '-var-create' Command
2511 -------------------------
2516 -var-create {NAME | "-"}
2517 {FRAME-ADDR | "*" | "@"} EXPRESSION
2519 This operation creates a variable object, which allows the monitoring
2520 of a variable, the result of an expression, a memory cell or a CPU
2523 The NAME parameter is the string by which the object can be
2524 referenced. It must be unique. If '-' is specified, the varobj system
2525 will generate a string "varNNNNNN" automatically. It will be unique
2526 provided that one does not specify NAME of that format. The command
2527 fails if a duplicate name is found.
2529 The frame under which the expression should be evaluated can be
2530 specified by FRAME-ADDR. A '*' indicates that the current frame should
2531 be used. A '@' indicates that a floating variable object must be
2534 EXPRESSION is any expression valid on the current language set (must
2535 not begin with a '*'), or one of the following:
2537 * '*ADDR', where ADDR is the address of a memory cell
2539 * '*ADDR-ADDR' -- a memory address range (TBD)
2541 * '$REGNAME' -- a CPU register name
2543 A varobj's contents may be provided by a Python-based pretty-printer.
2544 In this case the varobj is known as a "dynamic varobj". Dynamic varobjs
2545 have slightly different semantics in some cases. If the
2546 '-enable-pretty-printing' command is not sent, then GDB will never
2547 create a dynamic varobj. This ensures backward compatibility for
2553 This operation returns attributes of the newly-created varobj. These
2557 The name of the varobj.
2560 The number of children of the varobj. This number is not
2561 necessarily reliable for a dynamic varobj. Instead, you must
2562 examine the 'has_more' attribute.
2565 The varobj's scalar value. For a varobj whose type is some sort of
2566 aggregate (e.g., a 'struct'), or for a dynamic varobj, this value
2567 will not be interesting.
2570 The varobj's type. This is a string representation of the type, as
2571 would be printed by the GDB CLI. If 'print object' (*note set print
2572 object: Print Settings.) is set to 'on', the _actual_ (derived)
2573 type of the object is shown rather than the _declared_ one.
2576 If a variable object is bound to a specific thread, then this is
2577 the thread's identifier.
2580 For a dynamic varobj, this indicates whether there appear to be any
2581 children available. For a non-dynamic varobj, this will be 0.
2584 This attribute will be present and have the value '1' if the varobj
2585 is a dynamic varobj. If the varobj is not a dynamic varobj, then
2586 this attribute will not be present.
2589 A dynamic varobj can supply a display hint to the front end. The
2590 value comes directly from the Python pretty-printer object's
2591 'display_hint' method. *Note Pretty Printing API::.
2593 Typical output will look like this:
2595 name="NAME",numchild="N",type="TYPE",thread-id="M",
2598 The '-var-delete' Command
2599 -------------------------
2604 -var-delete [ -c ] NAME
2606 Deletes a previously created variable object and all of its children.
2607 With the '-c' option, just deletes the children.
2609 Returns an error if the object NAME is not found.
2611 The '-var-set-format' Command
2612 -----------------------------
2617 -var-set-format NAME FORMAT-SPEC
2619 Sets the output format for the value of the object NAME to be
2622 The syntax for the FORMAT-SPEC is as follows:
2625 {binary | decimal | hexadecimal | octal | natural}
2627 The natural format is the default format choosen automatically based
2628 on the variable type (like decimal for an 'int', hex for pointers,
2631 For a variable with children, the format is set only on the variable
2632 itself, and the children are not affected.
2634 The '-var-show-format' Command
2635 ------------------------------
2640 -var-show-format NAME
2642 Returns the format used to display the value of the object NAME.
2647 The '-var-info-num-children' Command
2648 ------------------------------------
2653 -var-info-num-children NAME
2655 Returns the number of children of a variable object NAME:
2659 Note that this number is not completely reliable for a dynamic
2660 varobj. It will return the current number of children, but more
2661 children may be available.
2663 The '-var-list-children' Command
2664 --------------------------------
2669 -var-list-children [PRINT-VALUES] NAME [FROM TO]
2671 Return a list of the children of the specified variable object and
2672 create variable objects for them, if they do not already exist. With a
2673 single argument or if PRINT-VALUES has a value of 0 or '--no-values',
2674 print only the names of the variables; if PRINT-VALUES is 1 or
2675 '--all-values', also print their values; and if it is 2 or
2676 '--simple-values' print the name and value for simple data types and
2677 just the name for arrays, structures and unions.
2679 FROM and TO, if specified, indicate the range of children to report.
2680 If FROM or TO is less than zero, the range is reset and all children
2681 will be reported. Otherwise, children starting at FROM (zero-based) and
2682 up to and excluding TO will be reported.
2684 If a child range is requested, it will only affect the current call
2685 to '-var-list-children', but not future calls to '-var-update'. For
2686 this, you must instead use '-var-set-update-range'. The intent of this
2687 approach is to enable a front end to implement any update approach it
2688 likes; for example, scrolling a view may cause the front end to request
2689 more children with '-var-list-children', and then the front end could
2690 call '-var-set-update-range' with a different range to ensure that
2691 future updates are restricted to just the visible items.
2693 For each child the following results are returned:
2696 Name of the variable object created for this child.
2699 The expression to be shown to the user by the front end to
2700 designate this child. For example this may be the name of a
2703 For a dynamic varobj, this value cannot be used to form an
2704 expression. There is no way to do this at all with a dynamic
2707 For C/C++ structures there are several pseudo children returned to
2708 designate access qualifiers. For these pseudo children EXP is
2709 'public', 'private', or 'protected'. In this case the type and
2710 value are not present.
2712 A dynamic varobj will not report the access qualifying
2713 pseudo-children, regardless of the language. This information is
2714 not available at all with a dynamic varobj.
2717 Number of children this child has. For a dynamic varobj, this will
2721 The type of the child. If 'print object' (*note set print object:
2722 Print Settings.) is set to 'on', the _actual_ (derived) type of the
2723 object is shown rather than the _declared_ one.
2726 If values were requested, this is the value.
2729 If this variable object is associated with a thread, this is the
2730 thread id. Otherwise this result is not present.
2733 If the variable object is frozen, this variable will be present
2737 A dynamic varobj can supply a display hint to the front end. The
2738 value comes directly from the Python pretty-printer object's
2739 'display_hint' method. *Note Pretty Printing API::.
2742 This attribute will be present and have the value '1' if the varobj
2743 is a dynamic varobj. If the varobj is not a dynamic varobj, then
2744 this attribute will not be present.
2746 The result may have its own attributes:
2749 A dynamic varobj can supply a display hint to the front end. The
2750 value comes directly from the Python pretty-printer object's
2751 'display_hint' method. *Note Pretty Printing API::.
2754 This is an integer attribute which is nonzero if there are children
2755 remaining after the end of the selected range.
2761 -var-list-children n
2762 ^done,numchild=N,children=[child={name=NAME,exp=EXP,
2763 numchild=N,type=TYPE},(repeats N times)]
2765 -var-list-children --all-values n
2766 ^done,numchild=N,children=[child={name=NAME,exp=EXP,
2767 numchild=N,value=VALUE,type=TYPE},(repeats N times)]
2769 The '-var-info-type' Command
2770 ----------------------------
2777 Returns the type of the specified variable NAME. The type is
2778 returned as a string in the same format as it is output by the GDB CLI:
2782 The '-var-info-expression' Command
2783 ----------------------------------
2788 -var-info-expression NAME
2790 Returns a string that is suitable for presenting this variable object
2791 in user interface. The string is generally not valid expression in the
2792 current language, and cannot be evaluated.
2794 For example, if 'a' is an array, and variable object 'A' was created
2795 for 'a', then we'll get this output:
2797 (gdb) -var-info-expression A.1
2798 ^done,lang="C",exp="1"
2800 Here, the value of 'lang' is the language name, which can be found in
2801 *note Supported Languages::.
2803 Note that the output of the '-var-list-children' command also
2804 includes those expressions, so the '-var-info-expression' command is of
2807 The '-var-info-path-expression' Command
2808 ---------------------------------------
2813 -var-info-path-expression NAME
2815 Returns an expression that can be evaluated in the current context
2816 and will yield the same value that a variable object has. Compare this
2817 with the '-var-info-expression' command, which result can be used only
2818 for UI presentation. Typical use of the '-var-info-path-expression'
2819 command is creating a watchpoint from a variable object.
2821 This command is currently not valid for children of a dynamic varobj,
2822 and will give an error when invoked on one.
2824 For example, suppose 'C' is a C++ class, derived from class 'Base',
2825 and that the 'Base' class has a member called 'm_size'. Assume a
2826 variable 'c' is has the type of 'C' and a variable object 'C' was
2827 created for variable 'c'. Then, we'll get this output:
2828 (gdb) -var-info-path-expression C.Base.public.m_size
2829 ^done,path_expr=((Base)c).m_size)
2831 The '-var-show-attributes' Command
2832 ----------------------------------
2837 -var-show-attributes NAME
2839 List attributes of the specified variable object NAME:
2841 status=ATTR [ ( ,ATTR )* ]
2843 where ATTR is '{ { editable | noneditable } | TBD }'.
2845 The '-var-evaluate-expression' Command
2846 --------------------------------------
2851 -var-evaluate-expression [-f FORMAT-SPEC] NAME
2853 Evaluates the expression that is represented by the specified
2854 variable object and returns its value as a string. The format of the
2855 string can be specified with the '-f' option. The possible values of
2856 this option are the same as for '-var-set-format' (*note
2857 -var-set-format::). If the '-f' option is not specified, the current
2858 display format will be used. The current display format can be changed
2859 using the '-var-set-format' command.
2863 Note that one must invoke '-var-list-children' for a variable before
2864 the value of a child variable can be evaluated.
2866 The '-var-assign' Command
2867 -------------------------
2872 -var-assign NAME EXPRESSION
2874 Assigns the value of EXPRESSION to the variable object specified by
2875 NAME. The object must be 'editable'. If the variable's value is
2876 altered by the assign, the variable will show up in any subsequent
2887 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
2890 The '-var-update' Command
2891 -------------------------
2896 -var-update [PRINT-VALUES] {NAME | "*"}
2898 Reevaluate the expressions corresponding to the variable object NAME
2899 and all its direct and indirect children, and return the list of
2900 variable objects whose values have changed; NAME must be a root variable
2901 object. Here, "changed" means that the result of
2902 '-var-evaluate-expression' before and after the '-var-update' is
2903 different. If '*' is used as the variable object names, all existing
2904 variable objects are updated, except for frozen ones (*note
2905 -var-set-frozen::). The option PRINT-VALUES determines whether both
2906 names and values, or just names are printed. The possible values of
2907 this option are the same as for '-var-list-children' (*note
2908 -var-list-children::). It is recommended to use the '--all-values'
2909 option, to reduce the number of MI commands needed on each program stop.
2911 With the '*' parameter, if a variable object is bound to a currently
2912 running thread, it will not be updated, without any diagnostic.
2914 If '-var-set-update-range' was previously used on a varobj, then only
2915 the selected range of children will be reported.
2917 '-var-update' reports all the changed varobjs in a tuple named
2920 Each item in the change list is itself a tuple holding:
2923 The name of the varobj.
2926 If values were requested for this update, then this field will be
2927 present and will hold the value of the varobj.
2930 This field is a string which may take one of three values:
2933 The variable object's current value is valid.
2936 The variable object does not currently hold a valid value but
2937 it may hold one in the future if its associated expression
2938 comes back into scope.
2941 The variable object no longer holds a valid value. This can
2942 occur when the executable file being debugged has changed,
2943 either through recompilation or by using the GDB 'file'
2944 command. The front end should normally choose to delete these
2947 In the future new values may be added to this list so the front
2948 should be prepared for this possibility. *Note GDB/MI Development
2949 and Front Ends: GDB/MI Development and Front Ends.
2952 This is only present if the varobj is still valid. If the type
2953 changed, then this will be the string 'true'; otherwise it will be
2956 When a varobj's type changes, its children are also likely to have
2957 become incorrect. Therefore, the varobj's children are
2958 automatically deleted when this attribute is 'true'. Also, the
2959 varobj's update range, when set using the '-var-set-update-range'
2963 If the varobj's type changed, then this field will be present and
2964 will hold the new type.
2967 For a dynamic varobj, if the number of children changed, or if the
2968 type changed, this will be the new number of children.
2970 The 'numchild' field in other varobj responses is generally not
2971 valid for a dynamic varobj - it will show the number of children
2972 that GDB knows about, but because dynamic varobjs lazily
2973 instantiate their children, this will not reflect the number of
2974 children which may be available.
2976 The 'new_num_children' attribute only reports changes to the number
2977 of children known by GDB. This is the only way to detect whether
2978 an update has removed children (which necessarily can only happen
2979 at the end of the update range).
2982 The display hint, if any.
2985 This is an integer value, which will be 1 if there are more
2986 children available outside the varobj's update range.
2989 This attribute will be present and have the value '1' if the varobj
2990 is a dynamic varobj. If the varobj is not a dynamic varobj, then
2991 this attribute will not be present.
2994 If new children were added to a dynamic varobj within the selected
2995 update range (as set by '-var-set-update-range'), then they will be
2996 listed in this attribute.
3005 -var-update --all-values var1
3006 ^done,changelist=[{name="var1",value="3",in_scope="true",
3007 type_changed="false"}]
3010 The '-var-set-frozen' Command
3011 -----------------------------
3016 -var-set-frozen NAME FLAG
3018 Set the frozenness flag on the variable object NAME. The FLAG
3019 parameter should be either '1' to make the variable frozen or '0' to
3020 make it unfrozen. If a variable object is frozen, then neither itself,
3021 nor any of its children, are implicitly updated by '-var-update' of a
3022 parent variable or by '-var-update *'. Only '-var-update' of the
3023 variable itself will update its value and values of its children. After
3024 a variable object is unfrozen, it is implicitly updated by all
3025 subsequent '-var-update' operations. Unfreezing a variable does not
3026 update it, only subsequent '-var-update' does.
3036 The '-var-set-update-range' command
3037 -----------------------------------
3042 -var-set-update-range NAME FROM TO
3044 Set the range of children to be returned by future invocations of
3047 FROM and TO indicate the range of children to report. If FROM or TO
3048 is less than zero, the range is reset and all children will be reported.
3049 Otherwise, children starting at FROM (zero-based) and up to and
3050 excluding TO will be reported.
3056 -var-set-update-range V 1 2
3059 The '-var-set-visualizer' command
3060 ---------------------------------
3065 -var-set-visualizer NAME VISUALIZER
3067 Set a visualizer for the variable object NAME.
3069 VISUALIZER is the visualizer to use. The special value 'None' means
3070 to disable any visualizer in use.
3072 If not 'None', VISUALIZER must be a Python expression. This
3073 expression must evaluate to a callable object which accepts a single
3074 argument. GDB will call this object with the value of the varobj NAME
3075 as an argument (this is done so that the same Python pretty-printing
3076 code can be used for both the CLI and MI). When called, this object must
3077 return an object which conforms to the pretty-printing interface (*note
3078 Pretty Printing API::).
3080 The pre-defined function 'gdb.default_visualizer' may be used to
3081 select a visualizer by following the built-in process (*note Selecting
3082 Pretty-Printers::). This is done automatically when a varobj is
3083 created, and so ordinarily is not needed.
3085 This feature is only available if Python support is enabled. The MI
3086 command '-list-features' (*note GDB/MI Support Commands::) can be used
3092 Resetting the visualizer:
3095 -var-set-visualizer V None
3098 Reselecting the default (type-based) visualizer:
3101 -var-set-visualizer V gdb.default_visualizer
3104 Suppose 'SomeClass' is a visualizer class. A lambda expression can
3105 be used to instantiate this class for a varobj:
3108 -var-set-visualizer V "lambda val: SomeClass()"
3112 File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
3114 27.16 GDB/MI Data Manipulation
3115 ==============================
3117 This section describes the GDB/MI commands that manipulate data: examine
3118 memory and registers, evaluate expressions, etc.
3120 The '-data-disassemble' Command
3121 -------------------------------
3127 [ -s START-ADDR -e END-ADDR ]
3128 | [ -f FILENAME -l LINENUM [ -n LINES ] ]
3134 is the beginning address (or '$pc')
3138 is the name of the file to disassemble
3140 is the line number to disassemble around
3142 is the number of disassembly lines to be produced. If it is -1,
3143 the whole function will be disassembled, in case no END-ADDR is
3144 specified. If END-ADDR is specified as a non-zero value, and LINES
3145 is lower than the number of disassembly lines between START-ADDR
3146 and END-ADDR, only LINES lines are displayed; if LINES is higher
3147 than the number of lines between START-ADDR and END-ADDR, only the
3148 lines up to END-ADDR are displayed.
3150 is either 0 (meaning only disassembly), 1 (meaning mixed source and
3151 disassembly), 2 (meaning disassembly with raw opcodes), or 3
3152 (meaning mixed source and disassembly with raw opcodes).
3157 The result of the '-data-disassemble' command will be a list named
3158 'asm_insns', the contents of this list depend on the MODE used with the
3159 '-data-disassemble' command.
3161 For modes 0 and 2 the 'asm_insns' list contains tuples with the
3165 The address at which this instruction was disassembled.
3168 The name of the function this instruction is within.
3171 The decimal offset in bytes from the start of 'func-name'.
3174 The text disassembly for this 'address'.
3177 This field is only present for mode 2. This contains the raw
3178 opcode bytes for the 'inst' field.
3180 For modes 1 and 3 the 'asm_insns' list contains tuples named
3181 'src_and_asm_line', each of which has the following fields:
3184 The line number within 'file'.
3187 The file name from the compilation unit. This might be an absolute
3188 file name or a relative file name depending on the compile command
3192 Absolute file name of 'file'. It is converted to a canonical form
3193 using the source file search path (*note Specifying Source
3194 Directories: Source Path.) and after resolving all the symbolic
3197 If the source file is not found this field will contain the path as
3198 present in the debug information.
3201 This is a list of tuples containing the disassembly for 'line' in
3202 'file'. The fields of each tuple are the same as for
3203 '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name',
3204 'offset', 'inst', and optionally 'opcodes'.
3206 Note that whatever included in the 'inst' field, is not manipulated
3207 directly by GDB/MI, i.e., it is not possible to adjust its format.
3212 The corresponding GDB command is 'disassemble'.
3217 Disassemble from the current value of '$pc' to '$pc + 20':
3220 -data-disassemble -s $pc -e "$pc + 20" -- 0
3223 {address="0x000107c0",func-name="main",offset="4",
3225 {address="0x000107c4",func-name="main",offset="8",
3226 inst="sethi %hi(0x11800), %o2"},
3227 {address="0x000107c8",func-name="main",offset="12",
3228 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
3229 {address="0x000107cc",func-name="main",offset="16",
3230 inst="sethi %hi(0x11800), %o2"},
3231 {address="0x000107d0",func-name="main",offset="20",
3232 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
3235 Disassemble the whole 'main' function. Line 32 is part of 'main'.
3237 -data-disassemble -f basics.c -l 32 -- 0
3239 {address="0x000107bc",func-name="main",offset="0",
3240 inst="save %sp, -112, %sp"},
3241 {address="0x000107c0",func-name="main",offset="4",
3243 {address="0x000107c4",func-name="main",offset="8",
3244 inst="sethi %hi(0x11800), %o2"},
3246 {address="0x0001081c",func-name="main",offset="96",inst="ret "},
3247 {address="0x00010820",func-name="main",offset="100",inst="restore "}]
3250 Disassemble 3 instructions from the start of 'main':
3253 -data-disassemble -f basics.c -l 32 -n 3 -- 0
3255 {address="0x000107bc",func-name="main",offset="0",
3256 inst="save %sp, -112, %sp"},
3257 {address="0x000107c0",func-name="main",offset="4",
3259 {address="0x000107c4",func-name="main",offset="8",
3260 inst="sethi %hi(0x11800), %o2"}]
3263 Disassemble 3 instructions from the start of 'main' in mixed mode:
3266 -data-disassemble -f basics.c -l 32 -n 3 -- 1
3268 src_and_asm_line={line="31",
3269 file="../../../src/gdb/testsuite/gdb.mi/basics.c",
3270 fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
3271 line_asm_insn=[{address="0x000107bc",
3272 func-name="main",offset="0",inst="save %sp, -112, %sp"}]},
3273 src_and_asm_line={line="32",
3274 file="../../../src/gdb/testsuite/gdb.mi/basics.c",
3275 fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
3276 line_asm_insn=[{address="0x000107c0",
3277 func-name="main",offset="4",inst="mov 2, %o0"},
3278 {address="0x000107c4",func-name="main",offset="8",
3279 inst="sethi %hi(0x11800), %o2"}]}]
3282 The '-data-evaluate-expression' Command
3283 ---------------------------------------
3288 -data-evaluate-expression EXPR
3290 Evaluate EXPR as an expression. The expression could contain an
3291 inferior function call. The function call will execute synchronously.
3292 If the expression contains spaces, it must be enclosed in double quotes.
3297 The corresponding GDB commands are 'print', 'output', and 'call'. In
3298 'gdbtk' only, there's a corresponding 'gdb_eval' command.
3303 In the following example, the numbers that precede the commands are the
3304 "tokens" described in *note GDB/MI Command Syntax: GDB/MI Command
3305 Syntax. Notice how GDB/MI returns the same tokens in its output.
3307 211-data-evaluate-expression A
3310 311-data-evaluate-expression &A
3311 311^done,value="0xefffeb7c"
3313 411-data-evaluate-expression A+3
3316 511-data-evaluate-expression "A + 3"
3320 The '-data-list-changed-registers' Command
3321 ------------------------------------------
3326 -data-list-changed-registers
3328 Display a list of the registers that have changed.
3333 GDB doesn't have a direct analog for this command; 'gdbtk' has the
3334 corresponding command 'gdb_changed_register_list'.
3346 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={
3347 func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
3350 -data-list-changed-registers
3351 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
3352 "10","11","13","14","15","16","17","18","19","20","21","22","23",
3353 "24","25","26","27","28","30","31","64","65","66","67","69"]
3356 The '-data-list-register-names' Command
3357 ---------------------------------------
3362 -data-list-register-names [ ( REGNO )+ ]
3364 Show a list of register names for the current target. If no
3365 arguments are given, it shows a list of the names of all the registers.
3366 If integer numbers are given as arguments, it will print a list of the
3367 names of the registers corresponding to the arguments. To ensure
3368 consistency between a register name and its number, the output list may
3369 include empty register names.
3374 GDB does not have a command which corresponds to
3375 '-data-list-register-names'. In 'gdbtk' there is a corresponding
3376 command 'gdb_regnames'.
3381 For the PPC MBX board:
3383 -data-list-register-names
3384 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
3385 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
3386 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
3387 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
3388 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
3389 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
3390 "", "pc","ps","cr","lr","ctr","xer"]
3392 -data-list-register-names 1 2 3
3393 ^done,register-names=["r1","r2","r3"]
3396 The '-data-list-register-values' Command
3397 ----------------------------------------
3402 -data-list-register-values
3403 [ --skip-unavailable ] FMT [ ( REGNO )*]
3405 Display the registers' contents. The format according to which the
3406 registers' contents are to be returned is given by FMT, followed by an
3407 optional list of numbers specifying the registers to display. A missing
3408 list of numbers indicates that the contents of all the registers must be
3409 returned. The '--skip-unavailable' option indicates that only the
3410 available registers are to be returned.
3412 Allowed formats for FMT are:
3430 The corresponding GDB commands are 'info reg', 'info all-reg', and (in
3431 'gdbtk') 'gdb_fetch_registers'.
3436 For a PPC MBX board (note: line breaks are for readability only, they
3437 don't appear in the actual output):
3440 -data-list-register-values r 64 65
3441 ^done,register-values=[{number="64",value="0xfe00a300"},
3442 {number="65",value="0x00029002"}]
3444 -data-list-register-values x
3445 ^done,register-values=[{number="0",value="0xfe0043c8"},
3446 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
3447 {number="3",value="0x0"},{number="4",value="0xa"},
3448 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
3449 {number="7",value="0xfe011e98"},{number="8",value="0x2"},
3450 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
3451 {number="11",value="0x1"},{number="12",value="0x0"},
3452 {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
3453 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
3454 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
3455 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
3456 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
3457 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
3458 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
3459 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
3460 {number="29",value="0x0"},{number="30",value="0xfe010000"},
3461 {number="31",value="0x0"},{number="32",value="0x0"},
3462 {number="33",value="0x0"},{number="34",value="0x0"},
3463 {number="35",value="0x0"},{number="36",value="0x0"},
3464 {number="37",value="0x0"},{number="38",value="0x0"},
3465 {number="39",value="0x0"},{number="40",value="0x0"},
3466 {number="41",value="0x0"},{number="42",value="0x0"},
3467 {number="43",value="0x0"},{number="44",value="0x0"},
3468 {number="45",value="0x0"},{number="46",value="0x0"},
3469 {number="47",value="0x0"},{number="48",value="0x0"},
3470 {number="49",value="0x0"},{number="50",value="0x0"},
3471 {number="51",value="0x0"},{number="52",value="0x0"},
3472 {number="53",value="0x0"},{number="54",value="0x0"},
3473 {number="55",value="0x0"},{number="56",value="0x0"},
3474 {number="57",value="0x0"},{number="58",value="0x0"},
3475 {number="59",value="0x0"},{number="60",value="0x0"},
3476 {number="61",value="0x0"},{number="62",value="0x0"},
3477 {number="63",value="0x0"},{number="64",value="0xfe00a300"},
3478 {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
3479 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
3480 {number="69",value="0x20002b03"}]
3483 The '-data-read-memory' Command
3484 -------------------------------
3486 This command is deprecated, use '-data-read-memory-bytes' instead.
3491 -data-read-memory [ -o BYTE-OFFSET ]
3492 ADDRESS WORD-FORMAT WORD-SIZE
3493 NR-ROWS NR-COLS [ ASCHAR ]
3498 An expression specifying the address of the first memory word to be
3499 read. Complex expressions containing embedded white space should
3500 be quoted using the C convention.
3503 The format to be used to print the memory words. The notation is
3504 the same as for GDB's 'print' command (*note Output Formats: Output
3508 The size of each memory word in bytes.
3511 The number of rows in the output table.
3514 The number of columns in the output table.
3517 If present, indicates that each row should include an ASCII dump.
3518 The value of ASCHAR is used as a padding character when a byte is
3519 not a member of the printable ASCII character set (printable ASCII
3520 characters are those whose code is between 32 and 126,
3524 An offset to add to the ADDRESS before fetching memory.
3526 This command displays memory contents as a table of NR-ROWS by
3527 NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS *
3528 NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should
3529 less than the requested number of bytes be returned by the target, the
3530 missing words are identified using 'N/A'. The number of bytes read from
3531 the target is returned in 'nr-bytes' and the starting address used to
3532 read memory in 'addr'.
3534 The address of the next/previous row or page is available in
3535 'next-row' and 'prev-row', 'next-page' and 'prev-page'.
3540 The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory
3546 Read six bytes of memory starting at 'bytes+6' but then offset by '-6'
3547 bytes. Format as three rows of two columns. One byte per word.
3548 Display each word in hex.
3551 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
3552 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
3553 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
3554 prev-page="0x0000138a",memory=[
3555 {addr="0x00001390",data=["0x00","0x01"]},
3556 {addr="0x00001392",data=["0x02","0x03"]},
3557 {addr="0x00001394",data=["0x04","0x05"]}]
3560 Read two bytes of memory starting at address 'shorts + 64' and
3561 display as a single word formatted in decimal.
3564 5-data-read-memory shorts+64 d 2 1 1
3565 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
3566 next-row="0x00001512",prev-row="0x0000150e",
3567 next-page="0x00001512",prev-page="0x0000150e",memory=[
3568 {addr="0x00001510",data=["128"]}]
3571 Read thirty two bytes of memory starting at 'bytes+16' and format as
3572 eight rows of four columns. Include a string encoding with 'x' used as
3573 the non-printable character.
3576 4-data-read-memory bytes+16 x 1 8 4 x
3577 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
3578 next-row="0x000013c0",prev-row="0x0000139c",
3579 next-page="0x000013c0",prev-page="0x00001380",memory=[
3580 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
3581 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
3582 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
3583 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
3584 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
3585 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
3586 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
3587 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
3590 The '-data-read-memory-bytes' Command
3591 -------------------------------------
3596 -data-read-memory-bytes [ -o BYTE-OFFSET ]
3602 An expression specifying the address of the first memory word to be
3603 read. Complex expressions containing embedded white space should
3604 be quoted using the C convention.
3607 The number of bytes to read. This should be an integer literal.
3610 The offsets in bytes relative to ADDRESS at which to start reading.
3611 This should be an integer literal. This option is provided so that
3612 a frontend is not required to first evaluate address and then
3613 perform address arithmetics itself.
3615 This command attempts to read all accessible memory regions in the
3616 specified range. First, all regions marked as unreadable in the memory
3617 map (if one is defined) will be skipped. *Note Memory Region
3618 Attributes::. Second, GDB will attempt to read the remaining regions.
3619 For each one, if reading full region results in an errors, GDB will try
3620 to read a subset of the region.
3622 In general, every single byte in the region may be readable or not,
3623 and the only way to read every readable byte is to try a read at every
3624 address, which is not practical. Therefore, GDB will attempt to read
3625 all accessible bytes at either beginning or the end of the region, using
3626 a binary division scheme. This heuristic works well for reading accross
3627 a memory map boundary. Note that if a region has a readable range that
3628 is neither at the beginning or the end, GDB will not read it.
3630 The result record (*note GDB/MI Result Records::) that is output of
3631 the command includes a field named 'memory' whose content is a list of
3632 tuples. Each tuple represent a successfully read memory block and has
3633 the following fields:
3636 The start address of the memory block, as hexadecimal literal.
3639 The end address of the memory block, as hexadecimal literal.
3642 The offset of the memory block, as hexadecimal literal, relative to
3643 the start address passed to '-data-read-memory-bytes'.
3646 The contents of the memory block, in hex.
3651 The corresponding GDB command is 'x'.
3657 -data-read-memory-bytes &a 10
3658 ^done,memory=[{begin="0xbffff154",offset="0x00000000",
3660 contents="01000000020000000300"}]
3663 The '-data-write-memory-bytes' Command
3664 --------------------------------------
3669 -data-write-memory-bytes ADDRESS CONTENTS
3670 -data-write-memory-bytes ADDRESS CONTENTS [COUNT]
3675 An expression specifying the address of the first memory word to be
3676 read. Complex expressions containing embedded white space should
3677 be quoted using the C convention.
3680 The hex-encoded bytes to write.
3683 Optional argument indicating the number of bytes to be written. If
3684 COUNT is greater than CONTENTS' length, GDB will repeatedly write
3685 CONTENTS until it fills COUNT bytes.
3690 There's no corresponding GDB command.
3696 -data-write-memory-bytes &a "aabbccdd"
3701 -data-write-memory-bytes &a "aabbccdd" 16e
3706 File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
3708 27.17 GDB/MI Tracepoint Commands
3709 ================================
3711 The commands defined in this section implement MI support for
3712 tracepoints. For detailed introduction, see *note Tracepoints::.
3714 The '-trace-find' Command
3715 -------------------------
3720 -trace-find MODE [PARAMETERS...]
3722 Find a trace frame using criteria defined by MODE and PARAMETERS.
3723 The following table lists permissible modes and their parameters. For
3724 details of operation, see *note tfind::.
3727 No parameters are required. Stops examining trace frames.
3730 An integer is required as parameter. Selects tracepoint frame with
3734 An integer is required as parameter. Finds next trace frame that
3735 corresponds to tracepoint with the specified number.
3738 An address is required as parameter. Finds next trace frame that
3739 corresponds to any tracepoint at the specified address.
3742 Two addresses are required as parameters. Finds next trace frame
3743 that corresponds to a tracepoint at an address inside the specified
3744 range. Both bounds are considered to be inside the range.
3747 Two addresses are required as parameters. Finds next trace frame
3748 that corresponds to a tracepoint at an address outside the
3749 specified range. Both bounds are considered to be inside the
3753 Line specification is required as parameter. *Note Specify
3754 Location::. Finds next trace frame that corresponds to a
3755 tracepoint at the specified location.
3757 If 'none' was passed as MODE, the response does not have fields.
3758 Otherwise, the response may have the following fields:
3761 This field has either '0' or '1' as the value, depending on whether
3762 a matching tracepoint was found.
3765 The index of the found traceframe. This field is present iff the
3766 'found' field has value of '1'.
3769 The index of the found tracepoint. This field is present iff the
3770 'found' field has value of '1'.
3773 The information about the frame corresponding to the found trace
3774 frame. This field is present only if a trace frame was found.
3775 *Note GDB/MI Frame Information::, for description of this field.
3780 The corresponding GDB command is 'tfind'.
3782 -trace-define-variable
3783 ----------------------
3788 -trace-define-variable NAME [ VALUE ]
3790 Create trace variable NAME if it does not exist. If VALUE is
3791 specified, sets the initial value of the specified trace variable to
3792 that value. Note that the NAME should start with the '$' character.
3797 The corresponding GDB command is 'tvariable'.
3799 The '-trace-frame-collected' Command
3800 ------------------------------------
3805 -trace-frame-collected
3806 [--var-print-values VAR_PVAL]
3807 [--comp-print-values COMP_PVAL]
3808 [--registers-format REGFORMAT]
3811 This command returns the set of collected objects, register names,
3812 trace state variable names, memory ranges and computed expressions that
3813 have been collected at a particular trace frame. The optional
3814 parameters to the command affect the output format in different ways.
3815 See the output description table below for more details.
3817 The reported names can be used in the normal manner to create varobjs
3818 and inspect the objects themselves. The items returned by this command
3819 are categorized so that it is clear which is a variable, which is a
3820 register, which is a trace state variable, which is a memory range and
3821 which is a computed expression.
3823 For instance, if the actions were
3824 collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
3825 collect *(int*)0xaf02bef0@40
3827 the object collected in its entirety would be 'myVar'. The object
3828 'myArray' would be partially collected, because only the element at
3829 index 'myIndex' would be collected. The remaining objects would be
3830 computed expressions.
3832 An example output would be:
3835 -trace-frame-collected
3837 explicit-variables=[{name="myVar",value="1"}],
3838 computed-expressions=[{name="myArray[myIndex]",value="0"},
3839 {name="myObj.field",value="0"},
3840 {name="myPtr->field",value="1"},
3841 {name="myCount + 2",value="3"},
3842 {name="$tvar1 + 1",value="43970027"}],
3843 registers=[{number="0",value="0x7fe2c6e79ec8"},
3844 {number="1",value="0x0"},
3845 {number="2",value="0x4"},
3847 {number="125",value="0x0"}],
3848 tvars=[{name="$tvar1",current="43970026"}],
3849 memory=[{address="0x0000000000602264",length="4"},
3850 {address="0x0000000000615bc0",length="4"}]
3855 'explicit-variables'
3856 The set of objects that have been collected in their entirety (as
3857 opposed to collecting just a few elements of an array or a few
3858 struct members). For each object, its name and value are printed.
3859 The '--var-print-values' option affects how or whether the value
3860 field is output. If VAR_PVAL is 0, then print only the names; if
3861 it is 1, print also their values; and if it is 2, print the name,
3862 type and value for simple data types, and the name and type for
3863 arrays, structures and unions.
3865 'computed-expressions'
3866 The set of computed expressions that have been collected at the
3867 current trace frame. The '--comp-print-values' option affects this
3868 set like the '--var-print-values' option affects the
3869 'explicit-variables' set. See above.
3872 The registers that have been collected at the current trace frame.
3873 For each register collected, the name and current value are
3874 returned. The value is formatted according to the
3875 '--registers-format' option. See the '-data-list-register-values'
3876 command for a list of the allowed formats. The default is 'x'.
3879 The trace state variables that have been collected at the current
3880 trace frame. For each trace state variable collected, the name and
3881 current value are returned.
3884 The set of memory ranges that have been collected at the current
3885 trace frame. Its content is a list of tuples. Each tuple
3886 represents a collected memory range and has the following fields:
3889 The start address of the memory range, as hexadecimal literal.
3892 The length of the memory range, as decimal literal.
3895 The contents of the memory block, in hex. This field is only
3896 present if the '--memory-contents' option is specified.
3901 There is no corresponding GDB command.
3906 -trace-list-variables
3907 ---------------------
3912 -trace-list-variables
3914 Return a table of all defined trace variables. Each element of the
3915 table has the following fields:
3918 The name of the trace variable. This field is always present.
3921 The initial value. This is a 64-bit signed integer. This field is
3925 The value the trace variable has at the moment. This is a 64-bit
3926 signed integer. This field is absent iff current value is not
3927 defined, for example if the trace was never run, or is presently
3933 The corresponding GDB command is 'tvariables'.
3939 -trace-list-variables
3940 ^done,trace-variables={nr_rows="1",nr_cols="3",
3941 hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"},
3942 {width="11",alignment="-1",col_name="initial",colhdr="Initial"},
3943 {width="11",alignment="-1",col_name="current",colhdr="Current"}],
3944 body=[variable={name="$trace_timestamp",initial="0"}
3945 variable={name="$foo",initial="10",current="15"}]}
3954 -trace-save [-r ] FILENAME
3956 Saves the collected trace data to FILENAME. Without the '-r' option,
3957 the data is downloaded from the target and saved in a local file. With
3958 the '-r' option the target is asked to perform the save.
3963 The corresponding GDB command is 'tsave'.
3973 Starts a tracing experiments. The result of this command does not
3979 The corresponding GDB command is 'tstart'.
3989 Obtains the status of a tracing experiment. The result may include
3990 the following fields:
3993 May have a value of either '0', when no tracing operations are
3994 supported, '1', when all tracing operations are supported, or
3995 'file' when examining trace file. In the latter case, examining of
3996 trace frame is possible but new tracing experiement cannot be
3997 started. This field is always present.
4000 May have a value of either '0' or '1' depending on whether tracing
4001 experiement is in progress on target. This field is present if
4002 'supported' field is not '0'.
4005 Report the reason why the tracing was stopped last time. This
4006 field may be absent iff tracing was never stopped on target yet.
4007 The value of 'request' means the tracing was stopped as result of
4008 the '-trace-stop' command. The value of 'overflow' means the
4009 tracing buffer is full. The value of 'disconnection' means tracing
4010 was automatically stopped when GDB has disconnected. The value of
4011 'passcount' means tracing was stopped when a tracepoint was passed
4012 a maximal number of times for that tracepoint. This field is
4013 present if 'supported' field is not '0'.
4015 'stopping-tracepoint'
4016 The number of tracepoint whose passcount as exceeded. This field
4017 is present iff the 'stop-reason' field has the value of
4022 The 'frames' field is a count of the total number of trace frames
4023 in the trace buffer, while 'frames-created' is the total created
4024 during the run, including ones that were discarded, such as when a
4025 circular trace buffer filled up. Both fields are optional.
4029 These fields tell the current size of the tracing buffer and the
4030 remaining space. These fields are optional.
4033 The value of the circular trace buffer flag. '1' means that the
4034 trace buffer is circular and old trace frames will be discarded if
4035 necessary to make room, '0' means that the trace buffer is linear
4039 The value of the disconnected tracing flag. '1' means that tracing
4040 will continue after GDB disconnects, '0' means that the trace run
4044 The filename of the trace file being examined. This field is
4045 optional, and only present when examining a trace file.
4050 The corresponding GDB command is 'tstatus'.
4060 Stops a tracing experiment. The result of this command has the same
4061 fields as '-trace-status', except that the 'supported' and 'running'
4062 fields are not output.
4067 The corresponding GDB command is 'tstop'.
4070 File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
4072 27.18 GDB/MI Symbol Query Commands
4073 ==================================
4075 The '-symbol-list-lines' Command
4076 --------------------------------
4081 -symbol-list-lines FILENAME
4083 Print the list of lines that contain code and their associated
4084 program addresses for the given source filename. The entries are sorted
4085 in ascending PC order.
4090 There is no corresponding GDB command.
4096 -symbol-list-lines basics.c
4097 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
4101 File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
4103 27.19 GDB/MI File Commands
4104 ==========================
4106 This section describes the GDB/MI commands to specify executable file
4107 names and to read in and obtain symbol table information.
4109 The '-file-exec-and-symbols' Command
4110 ------------------------------------
4115 -file-exec-and-symbols FILE
4117 Specify the executable file to be debugged. This file is the one
4118 from which the symbol table is also read. If no file is specified, the
4119 command clears the executable and symbol information. If breakpoints
4120 are set when using this command with no arguments, GDB will produce
4121 error messages. Otherwise, no output is produced, except a completion
4127 The corresponding GDB command is 'file'.
4133 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
4137 The '-file-exec-file' Command
4138 -----------------------------
4143 -file-exec-file FILE
4145 Specify the executable file to be debugged. Unlike
4146 '-file-exec-and-symbols', the symbol table is _not_ read from this file.
4147 If used without argument, GDB clears the information about the
4148 executable file. No output is produced, except a completion
4154 The corresponding GDB command is 'exec-file'.
4160 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
4164 The '-file-list-exec-source-file' Command
4165 -----------------------------------------
4170 -file-list-exec-source-file
4172 List the line number, the current source file, and the absolute path
4173 to the current source file for the current executable. The macro
4174 information field has a value of '1' or '0' depending on whether or not
4175 the file includes preprocessor macro information.
4180 The GDB equivalent is 'info source'
4186 123-file-list-exec-source-file
4187 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
4190 The '-file-list-exec-source-files' Command
4191 ------------------------------------------
4196 -file-list-exec-source-files
4198 List the source files for the current executable.
4200 It will always output both the filename and fullname (absolute file
4201 name) of a source file.
4206 The GDB equivalent is 'info sources'. 'gdbtk' has an analogous command
4213 -file-list-exec-source-files
4215 {file=foo.c,fullname=/home/foo.c},
4216 {file=/home/bar.c,fullname=/home/bar.c},
4217 {file=gdb_could_not_find_fullpath.c}]
4220 The '-file-symbol-file' Command
4221 -------------------------------
4226 -file-symbol-file FILE
4228 Read symbol table info from the specified FILE argument. When used
4229 without arguments, clears GDB's symbol table info. No output is
4230 produced, except for a completion notification.
4235 The corresponding GDB command is 'symbol-file'.
4241 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
4246 File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
4248 27.20 GDB/MI Target Manipulation Commands
4249 =========================================
4251 The '-target-attach' Command
4252 ----------------------------
4257 -target-attach PID | GID | FILE
4259 Attach to a process PID or a file FILE outside of GDB, or a thread
4260 group GID. If attaching to a thread group, the id previously returned
4261 by '-list-thread-groups --available' must be used.
4266 The corresponding GDB command is 'attach'.
4273 =thread-created,id="1"
4274 *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}
4278 The '-target-detach' Command
4279 ----------------------------
4284 -target-detach [ PID | GID ]
4286 Detach from the remote target which normally resumes its execution.
4287 If either PID or GID is specified, detaches from either the specified
4288 process, or specified thread group. There's no output.
4293 The corresponding GDB command is 'detach'.
4303 The '-target-disconnect' Command
4304 --------------------------------
4311 Disconnect from the remote target. There's no output and the target
4312 is generally not resumed.
4317 The corresponding GDB command is 'disconnect'.
4327 The '-target-download' Command
4328 ------------------------------
4335 Loads the executable onto the remote target. It prints out an update
4336 message every half second, which includes the fields:
4339 The name of the section.
4341 The size of what has been sent so far for that section.
4343 The size of the section.
4345 The total size of what was sent so far (the current and the
4348 The size of the overall executable to download.
4350 Each message is sent as status record (*note GDB/MI Output Syntax:
4351 GDB/MI Output Syntax.).
4353 In addition, it prints the name and size of the sections, as they are
4354 downloaded. These messages include the following fields:
4357 The name of the section.
4359 The size of the section.
4361 The size of the overall executable to download.
4363 At the end, a summary is printed.
4368 The corresponding GDB command is 'load'.
4373 Note: each status message appears on a single line. Here the messages
4374 have been broken down so that they can fit onto a page.
4378 +download,{section=".text",section-size="6668",total-size="9880"}
4379 +download,{section=".text",section-sent="512",section-size="6668",
4380 total-sent="512",total-size="9880"}
4381 +download,{section=".text",section-sent="1024",section-size="6668",
4382 total-sent="1024",total-size="9880"}
4383 +download,{section=".text",section-sent="1536",section-size="6668",
4384 total-sent="1536",total-size="9880"}
4385 +download,{section=".text",section-sent="2048",section-size="6668",
4386 total-sent="2048",total-size="9880"}
4387 +download,{section=".text",section-sent="2560",section-size="6668",
4388 total-sent="2560",total-size="9880"}
4389 +download,{section=".text",section-sent="3072",section-size="6668",
4390 total-sent="3072",total-size="9880"}
4391 +download,{section=".text",section-sent="3584",section-size="6668",
4392 total-sent="3584",total-size="9880"}
4393 +download,{section=".text",section-sent="4096",section-size="6668",
4394 total-sent="4096",total-size="9880"}
4395 +download,{section=".text",section-sent="4608",section-size="6668",
4396 total-sent="4608",total-size="9880"}
4397 +download,{section=".text",section-sent="5120",section-size="6668",
4398 total-sent="5120",total-size="9880"}
4399 +download,{section=".text",section-sent="5632",section-size="6668",
4400 total-sent="5632",total-size="9880"}
4401 +download,{section=".text",section-sent="6144",section-size="6668",
4402 total-sent="6144",total-size="9880"}
4403 +download,{section=".text",section-sent="6656",section-size="6668",
4404 total-sent="6656",total-size="9880"}
4405 +download,{section=".init",section-size="28",total-size="9880"}
4406 +download,{section=".fini",section-size="28",total-size="9880"}
4407 +download,{section=".data",section-size="3156",total-size="9880"}
4408 +download,{section=".data",section-sent="512",section-size="3156",
4409 total-sent="7236",total-size="9880"}
4410 +download,{section=".data",section-sent="1024",section-size="3156",
4411 total-sent="7748",total-size="9880"}
4412 +download,{section=".data",section-sent="1536",section-size="3156",
4413 total-sent="8260",total-size="9880"}
4414 +download,{section=".data",section-sent="2048",section-size="3156",
4415 total-sent="8772",total-size="9880"}
4416 +download,{section=".data",section-sent="2560",section-size="3156",
4417 total-sent="9284",total-size="9880"}
4418 +download,{section=".data",section-sent="3072",section-size="3156",
4419 total-sent="9796",total-size="9880"}
4420 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
4434 The '-target-select' Command
4435 ----------------------------
4440 -target-select TYPE PARAMETERS ...
4442 Connect GDB to the remote target. This command takes two args:
4445 The type of target, for instance 'remote', etc.
4447 Device names, host names and the like. *Note Commands for Managing
4448 Targets: Target Commands, for more details.
4450 The output is a connection notification, followed by the address at
4451 which the target program is, in the following form:
4453 ^connected,addr="ADDRESS",func="FUNCTION NAME",
4459 The corresponding GDB command is 'target'.
4465 -target-select remote /dev/ttya
4466 ^connected,addr="0xfe00a300",func="??",args=[]
4470 File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
4472 27.21 GDB/MI File Transfer Commands
4473 ===================================
4475 The '-target-file-put' Command
4476 ------------------------------
4481 -target-file-put HOSTFILE TARGETFILE
4483 Copy file HOSTFILE from the host system (the machine running GDB) to
4484 TARGETFILE on the target system.
4489 The corresponding GDB command is 'remote put'.
4495 -target-file-put localfile remotefile
4499 The '-target-file-get' Command
4500 ------------------------------
4505 -target-file-get TARGETFILE HOSTFILE
4507 Copy file TARGETFILE from the target system to HOSTFILE on the host
4513 The corresponding GDB command is 'remote get'.
4519 -target-file-get remotefile localfile
4523 The '-target-file-delete' Command
4524 ---------------------------------
4529 -target-file-delete TARGETFILE
4531 Delete TARGETFILE from the target system.
4536 The corresponding GDB command is 'remote delete'.
4542 -target-file-delete remotefile
4547 File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
4549 27.22 Ada Exceptions GDB/MI Commands
4550 ====================================
4552 The '-info-ada-exceptions' Command
4553 ----------------------------------
4558 -info-ada-exceptions [ REGEXP]
4560 List all Ada exceptions defined within the program being debugged.
4561 With a regular expression REGEXP, only those exceptions whose names
4562 match REGEXP are listed.
4567 The corresponding GDB command is 'info exceptions'.
4572 The result is a table of Ada exceptions. The following columns are
4573 defined for each exception:
4576 The name of the exception.
4579 The address of the exception.
4584 -info-ada-exceptions aint
4585 ^done,ada-exceptions={nr_rows="2",nr_cols="2",
4586 hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"},
4587 {width="1",alignment="-1",col_name="address",colhdr="Address"}],
4588 body=[{name="constraint_error",address="0x0000000000613da0"},
4589 {name="const.aint_global_e",address="0x0000000000613b00"}]}
4591 Catching Ada Exceptions
4592 -----------------------
4594 The commands describing how to ask GDB to stop when a program raises an
4595 exception are described at *note Ada Exception GDB/MI Catchpoint
4599 File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI
4601 27.23 GDB/MI Support Commands
4602 =============================
4604 Since new commands and features get regularly added to GDB/MI, some
4605 commands are available to help front-ends query the debugger about
4606 support for these capabilities. Similarly, it is also possible to query
4607 GDB about target support of certain features.
4609 The '-info-gdb-mi-command' Command
4610 ----------------------------------
4615 -info-gdb-mi-command CMD_NAME
4617 Query support for the GDB/MI command named CMD_NAME.
4619 Note that the dash ('-') starting all GDB/MI commands is technically
4620 not part of the command name (*note GDB/MI Input Syntax::), and thus
4621 should be omitted in CMD_NAME. However, for ease of use, this command
4622 also accepts the form with the leading dash.
4627 There is no corresponding GDB command.
4632 The result is a tuple. There is currently only one field:
4635 This field is equal to '"true"' if the GDB/MI command exists,
4636 '"false"' otherwise.
4641 Here is an example where the GDB/MI command does not exist:
4643 -info-gdb-mi-command unsupported-command
4644 ^done,command={exists="false"}
4646 And here is an example where the GDB/MI command is known to the
4649 -info-gdb-mi-command symbol-list-lines
4650 ^done,command={exists="true"}
4652 The '-list-features' Command
4653 ----------------------------
4655 Returns a list of particular features of the MI protocol that this
4656 version of gdb implements. A feature can be a command, or a new field
4657 in an output of some command, or even an important bugfix. While a
4658 frontend can sometimes detect presence of a feature at runtime, it is
4659 easier to perform detection at debugger startup.
4661 The command returns a list of strings, with each string naming an
4662 available feature. Each returned string is just a name, it does not
4663 have any internal structure. The list of possible feature names is
4668 (gdb) -list-features
4669 ^done,result=["feature1","feature2"]
4671 The current list of features is:
4674 Indicates support for the '-var-set-frozen' command, as well as
4675 possible presense of the 'frozen' field in the output of
4677 'pending-breakpoints'
4678 Indicates support for the '-f' option to the '-break-insert'
4681 Indicates Python scripting support, Python-based pretty-printing
4682 commands, and possible presence of the 'display_hint' field in the
4683 output of '-var-list-children'
4685 Indicates support for the '-thread-info' command.
4686 'data-read-memory-bytes'
4687 Indicates support for the '-data-read-memory-bytes' and the
4688 '-data-write-memory-bytes' commands.
4689 'breakpoint-notifications'
4690 Indicates that changes to breakpoints and breakpoints created via
4691 the CLI will be announced via async records.
4693 Indicates support for the '-ada-task-info' command.
4695 Indicates that all GDB/MI commands accept the '--language' option
4696 (*note Context management::).
4697 'info-gdb-mi-command'
4698 Indicates support for the '-info-gdb-mi-command' command.
4699 'undefined-command-error-code'
4700 Indicates support for the "undefined-command" error code in error
4701 result records, produced when trying to execute an undefined GDB/MI
4702 command (*note GDB/MI Result Records::).
4703 'exec-run-start-option'
4704 Indicates that the '-exec-run' command supports the '--start'
4705 option (*note GDB/MI Program Execution::).
4707 The '-list-target-features' Command
4708 -----------------------------------
4710 Returns a list of particular features that are supported by the target.
4711 Those features affect the permitted MI commands, but unlike the features
4712 reported by the '-list-features' command, the features depend on which
4713 target GDB is using at the moment. Whenever a target can change, due to
4714 commands such as '-target-select', '-target-attach' or '-exec-run', the
4715 list of target features may change, and the frontend should obtain it
4716 again. Example output:
4718 (gdb) -list-target-features
4719 ^done,result=["async"]
4721 The current list of features is:
4724 Indicates that the target is capable of asynchronous command
4725 execution, which means that GDB will accept further commands while
4726 the target is running.
4729 Indicates that the target is capable of reverse execution. *Note
4730 Reverse Execution::, for more information.
4733 File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI
4735 27.24 Miscellaneous GDB/MI Commands
4736 ===================================
4738 The '-gdb-exit' Command
4739 -----------------------
4746 Exit GDB immediately.
4751 Approximately corresponds to 'quit'.
4760 The '-gdb-set' Command
4761 ----------------------
4768 Set an internal GDB variable.
4773 The corresponding GDB command is 'set'.
4783 The '-gdb-show' Command
4784 -----------------------
4791 Show the current value of a GDB variable.
4796 The corresponding GDB command is 'show'.
4806 The '-gdb-version' Command
4807 --------------------------
4814 Show version information for GDB. Used mostly in testing.
4819 The GDB equivalent is 'show version'. GDB by default shows this
4820 information when you start an interactive session.
4828 ~Copyright 2000 Free Software Foundation, Inc.
4829 ~GDB is free software, covered by the GNU General Public License, and
4830 ~you are welcome to change it and/or distribute copies of it under
4831 ~ certain conditions.
4832 ~Type "show copying" to see the conditions.
4833 ~There is absolutely no warranty for GDB. Type "show warranty" for
4835 ~This GDB was configured as
4836 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
4840 The '-list-thread-groups' Command
4841 ---------------------------------
4846 -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
4848 Lists thread groups (*note Thread groups::). When a single thread
4849 group is passed as the argument, lists the children of that group. When
4850 several thread group are passed, lists information about those thread
4851 groups. Without any parameters, lists information about all top-level
4854 Normally, thread groups that are being debugged are reported. With
4855 the '--available' option, GDB reports thread groups available on the
4858 The output of this command may have either a 'threads' result or a
4859 'groups' result. The 'thread' result has a list of tuples as value,
4860 with each tuple describing a thread (*note GDB/MI Thread Information::).
4861 The 'groups' result has a list of tuples as value, each tuple describing
4862 a thread group. If top-level groups are requested (that is, no
4863 parameter is passed), or when several groups are passed, the output
4864 always has a 'groups' result. The format of the 'group' result is
4867 To reduce the number of roundtrips it's possible to list thread
4868 groups together with their children, by passing the '--recurse' option
4869 and the recursion depth. Presently, only recursion depth of 1 is
4870 permitted. If this option is present, then every reported thread group
4871 will also include its children, either as 'group' or 'threads' field.
4873 In general, any combination of option and parameters is permitted,
4874 with the following caveats:
4876 * When a single thread group is passed, the output will typically be
4877 the 'threads' result. Because threads may not contain anything,
4878 the 'recurse' option will be ignored.
4880 * When the '--available' option is passed, limited information may be
4881 available. In particular, the list of threads of a process might
4882 be inaccessible. Further, specifying specific thread groups might
4883 not give any performance advantage over listing all thread groups.
4884 The frontend should assume that '-list-thread-groups --available'
4885 is always an expensive operation and cache the results.
4887 The 'groups' result is a list of tuples, where each tuple may have
4888 the following fields:
4891 Identifier of the thread group. This field is always present. The
4892 identifier is an opaque string; frontends should not try to convert
4893 it to an integer, even though it might look like one.
4896 The type of the thread group. At present, only 'process' is a
4900 The target-specific process identifier. This field is only present
4901 for thread groups of type 'process' and only if the process exists.
4904 The number of children this thread group has. This field may be
4905 absent for an available thread group.
4908 This field has a list of tuples as value, each tuple describing a
4909 thread. It may be present if the '--recurse' option is specified,
4910 and it's actually possible to obtain the threads.
4913 This field is a list of integers, each identifying a core that one
4914 thread of the group is running on. This field may be absent if
4915 such information is not available.
4918 The name of the executable file that corresponds to this thread
4919 group. The field is only present for thread groups of type
4920 'process', and only if there is a corresponding executable file.
4927 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
4928 -list-thread-groups 17
4929 ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
4930 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
4931 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
4932 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
4933 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
4934 -list-thread-groups --available
4935 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
4936 -list-thread-groups --available --recurse 1
4937 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
4938 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
4939 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
4940 -list-thread-groups --available --recurse 1 17 18
4941 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
4942 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
4943 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
4945 The '-info-os' Command
4946 ----------------------
4953 If no argument is supplied, the command returns a table of available
4954 operating-system-specific information types. If one of these types is
4955 supplied as an argument TYPE, then the command returns a table of data
4958 The types of information available depend on the target operating
4964 The corresponding GDB command is 'info os'.
4969 When run on a GNU/Linux system, the output will look something like
4974 ^done,OSDataTable={nr_rows="9",nr_cols="3",
4975 hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"},
4976 {width="10",alignment="-1",col_name="col1",colhdr="Description"},
4977 {width="10",alignment="-1",col_name="col2",colhdr="Title"}],
4978 body=[item={col0="processes",col1="Listing of all processes",
4980 item={col0="procgroups",col1="Listing of all process groups",
4981 col2="Process groups"},
4982 item={col0="threads",col1="Listing of all threads",
4984 item={col0="files",col1="Listing of all file descriptors",
4985 col2="File descriptors"},
4986 item={col0="sockets",col1="Listing of all internet-domain sockets",
4988 item={col0="shm",col1="Listing of all shared-memory regions",
4989 col2="Shared-memory regions"},
4990 item={col0="semaphores",col1="Listing of all semaphores",
4992 item={col0="msg",col1="Listing of all message queues",
4993 col2="Message queues"},
4994 item={col0="modules",col1="Listing of all loaded kernel modules",
4995 col2="Kernel modules"}]}
4998 ^done,OSDataTable={nr_rows="190",nr_cols="4",
4999 hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"},
5000 {width="10",alignment="-1",col_name="col1",colhdr="user"},
5001 {width="10",alignment="-1",col_name="col2",colhdr="command"},
5002 {width="10",alignment="-1",col_name="col3",colhdr="cores"}],
5003 body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"},
5004 item={col0="2",col1="root",col2="[kthreadd]",col3="1"},
5005 item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"},
5007 item={col0="26446",col1="stan",col2="bash",col3="0"},
5008 item={col0="28152",col1="stan",col2="bash",col3="1"}]}
5011 (Note that the MI output here includes a '"Title"' column that does
5012 not appear in command-line 'info os'; this column is useful for MI
5013 clients that want to enumerate the types of data, such as in a popup
5014 menu, but is needless clutter on the command line, and 'info os' omits
5017 The '-add-inferior' Command
5018 ---------------------------
5025 Creates a new inferior (*note Inferiors and Programs::). The created
5026 inferior is not associated with any executable. Such association may be
5027 established with the '-file-exec-and-symbols' command (*note GDB/MI File
5028 Commands::). The command response has a single field, 'inferior', whose
5029 value is the identifier of the thread group corresponding to the new
5039 The '-interpreter-exec' Command
5040 -------------------------------
5045 -interpreter-exec INTERPRETER COMMAND
5047 Execute the specified COMMAND in the given INTERPRETER.
5052 The corresponding GDB command is 'interpreter-exec'.
5058 -interpreter-exec console "break main"
5059 &"During symbol reading, couldn't parse type; debugger out of date?.\n"
5060 &"During symbol reading, bad structure-type format.\n"
5061 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
5065 The '-inferior-tty-set' Command
5066 -------------------------------
5071 -inferior-tty-set /dev/pts/1
5073 Set terminal for future runs of the program being debugged.
5078 The corresponding GDB command is 'set inferior-tty' /dev/pts/1.
5084 -inferior-tty-set /dev/pts/1
5088 The '-inferior-tty-show' Command
5089 --------------------------------
5096 Show terminal for future runs of program being debugged.
5101 The corresponding GDB command is 'show inferior-tty'.
5107 -inferior-tty-set /dev/pts/1
5111 ^done,inferior_tty_terminal="/dev/pts/1"
5114 The '-enable-timings' Command
5115 -----------------------------
5120 -enable-timings [yes | no]
5122 Toggle the printing of the wallclock, user and system times for an MI
5123 command as a field in its output. This command is to help frontend
5124 developers optimize the performance of their code. No argument is
5125 equivalent to 'yes'.
5140 ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5141 addr="0x080484ed",func="main",file="myprog.c",
5142 fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
5144 time={wallclock="0.05185",user="0.00800",system="0.00000"}
5152 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
5153 frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
5154 {name="argv",value="0xbfb60364"}],file="myprog.c",
5155 fullname="/home/nickrob/myprog.c",line="73"}
5159 File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
5164 This chapter describes annotations in GDB. Annotations were designed to
5165 interface GDB to graphical user interfaces or other similar programs
5166 which want to interact with GDB at a relatively high level.
5168 The annotation mechanism has largely been superseded by GDB/MI (*note
5173 * Annotations Overview:: What annotations are; the general syntax.
5174 * Server Prefix:: Issuing a command without affecting user state.
5175 * Prompting:: Annotations marking GDB's need for input.
5176 * Errors:: Annotations for error messages.
5177 * Invalidation:: Some annotations describe things now invalid.
5178 * Annotations for Running::
5179 Whether the program is running, how it stopped, etc.
5180 * Source Annotations:: Annotations describing source code.
5183 File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
5185 28.1 What is an Annotation?
5186 ===========================
5188 Annotations start with a newline character, two 'control-z' characters,
5189 and the name of the annotation. If there is no additional information
5190 associated with this annotation, the name of the annotation is followed
5191 immediately by a newline. If there is additional information, the name
5192 of the annotation is followed by a space, the additional information,
5193 and a newline. The additional information cannot contain newline
5196 Any output not beginning with a newline and two 'control-z'
5197 characters denotes literal output from GDB. Currently there is no need
5198 for GDB to output a newline followed by two 'control-z' characters, but
5199 if there was such a need, the annotations could be extended with an
5200 'escape' annotation which means those three characters as output.
5202 The annotation LEVEL, which is specified using the '--annotate'
5203 command line option (*note Mode Options::), controls how much
5204 information GDB prints together with its prompt, values of expressions,
5205 source lines, and other types of output. Level 0 is for no annotations,
5206 level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3
5207 is the maximum annotation suitable for programs that control GDB, and
5208 level 2 annotations have been made obsolete (*note Limitations of the
5209 Annotation Interface: (annotate)Limitations.).
5211 'set annotate LEVEL'
5212 The GDB command 'set annotate' sets the level of annotations to the
5216 Show the current annotation level.
5218 This chapter describes level 3 annotations.
5220 A simple example of starting up GDB with annotations is:
5224 Copyright 2003 Free Software Foundation, Inc.
5225 GDB is free software, covered by the GNU General Public License,
5226 and you are welcome to change it and/or distribute copies of it
5227 under certain conditions.
5228 Type "show copying" to see the conditions.
5229 There is absolutely no warranty for GDB. Type "show warranty"
5231 This GDB was configured as "i386-pc-linux-gnu"
5241 Here 'quit' is input to GDB; the rest is output from GDB. The three
5242 lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are
5243 annotations; the rest is output from GDB.
5246 File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
5248 28.2 The Server Prefix
5249 ======================
5251 If you prefix a command with 'server ' then it will not affect the
5252 command history, nor will it affect GDB's notion of which command to
5253 repeat if <RET> is pressed on a line by itself. This means that
5254 commands can be run behind a user's back by a front-end in a transparent
5257 The 'server ' prefix does not affect the recording of values into the
5258 value history; to print a value without recording it into the value
5259 history, use the 'output' command instead of the 'print' command.
5261 Using this prefix also disables confirmation requests (*note
5262 confirmation requests::).
5265 File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
5267 28.3 Annotation for GDB Input
5268 =============================
5270 When GDB prompts for input, it annotates this fact so it is possible to
5271 know when to send output, when the output from a given command is over,
5274 Different kinds of input each have a different "input type". Each
5275 input type has three annotations: a 'pre-' annotation, which denotes the
5276 beginning of any prompt which is being output, a plain annotation, which
5277 denotes the end of the prompt, and then a 'post-' annotation which
5278 denotes the end of any echo which may (or may not) be associated with
5279 the input. For example, the 'prompt' input type features the following
5289 When GDB is prompting for a command (the main GDB prompt).
5292 When GDB prompts for a set of commands, like in the 'commands'
5293 command. The annotations are repeated for each command which is
5297 When GDB wants the user to select between various overloaded
5301 When GDB wants the user to confirm a potentially dangerous
5304 'prompt-for-continue'
5305 When GDB is asking the user to press return to continue. Note:
5306 Don't expect this to work well; instead use 'set height 0' to
5307 disable prompting. This is because the counting of lines is buggy
5308 in the presence of annotations.
5311 File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
5318 This annotation occurs right before GDB responds to an interrupt.
5322 This annotation occurs right before GDB responds to an error.
5324 Quit and error annotations indicate that any annotations which GDB
5325 was in the middle of may end abruptly. For example, if a
5326 'value-history-begin' annotation is followed by a 'error', one cannot
5327 expect to receive the matching 'value-history-end'. One cannot expect
5328 not to receive it either, however; an error annotation does not
5329 necessarily mean that GDB is immediately returning all the way to the
5332 A quit or error annotation may be preceded by
5336 Any output between that and the quit or error annotation is the error
5339 Warning messages are not yet annotated.
5342 File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
5344 28.5 Invalidation Notices
5345 =========================
5347 The following annotations say that certain pieces of state may have
5350 '^Z^Zframes-invalid'
5352 The frames (for example, output from the 'backtrace' command) may
5355 '^Z^Zbreakpoints-invalid'
5357 The breakpoints may have changed. For example, the user just added
5358 or deleted a breakpoint.
5361 File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
5363 28.6 Running the Program
5364 ========================
5366 When the program starts executing due to a GDB command such as 'step' or
5371 is output. When the program stops,
5375 is output. Before the 'stopped' annotation, a variety of annotations
5376 describe how the program stopped.
5378 '^Z^Zexited EXIT-STATUS'
5379 The program exited, and EXIT-STATUS is the exit status (zero for
5380 successful exit, otherwise nonzero).
5383 The program exited with a signal. After the '^Z^Zsignalled', the
5384 annotation continues:
5393 ^Z^Zsignal-string-end
5396 where NAME is the name of the signal, such as 'SIGILL' or
5397 'SIGSEGV', and STRING is the explanation of the signal, such as
5398 'Illegal Instruction' or 'Segmentation fault'. The arguments
5399 INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit
5400 and have no particular format.
5403 The syntax of this annotation is just like 'signalled', but GDB is
5404 just saying that the program received the signal, not that it was
5407 '^Z^Zbreakpoint NUMBER'
5408 The program hit breakpoint number NUMBER.
5410 '^Z^Zwatchpoint NUMBER'
5411 The program hit watchpoint number NUMBER.
5414 File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
5416 28.7 Displaying Source
5417 ======================
5419 The following annotation is used instead of displaying source code:
5421 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
5423 where FILENAME is an absolute file name indicating which source file,
5424 LINE is the line number within that file (where 1 is the first line in
5425 the file), CHARACTER is the character position within the file (where 0
5426 is the first character in the file) (for most debug formats this will
5427 necessarily point to the beginning of a line), MIDDLE is 'middle' if
5428 ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning
5429 of the line, and ADDR is the address in the target program associated
5430 with the source which is being displayed. The ADDR is in the form '0x'
5431 followed by one or more lowercase hex digits (note that this does not
5432 depend on the language).
5435 File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top
5437 29 JIT Compilation Interface
5438 ****************************
5440 This chapter documents GDB's "just-in-time" (JIT) compilation interface.
5441 A JIT compiler is a program or library that generates native executable
5442 code at runtime and executes it, usually in order to achieve good
5443 performance while maintaining platform independence.
5445 Programs that use JIT compilation are normally difficult to debug
5446 because portions of their code are generated at runtime, instead of
5447 being loaded from object files, which is where GDB normally finds the
5448 program's symbols and debug information. In order to debug programs
5449 that use JIT compilation, GDB has an interface that allows the program
5450 to register in-memory symbol files with GDB at runtime.
5452 If you are using GDB to debug a program that uses this interface,
5453 then it should work transparently so long as you have not stripped the
5454 binary. If you are developing a JIT compiler, then the interface is
5455 documented in the rest of this chapter. At this time, the only known
5456 client of this interface is the LLVM JIT.
5458 Broadly speaking, the JIT interface mirrors the dynamic loader
5459 interface. The JIT compiler communicates with GDB by writing data into
5460 a global variable and calling a fuction at a well-known symbol. When
5461 GDB attaches, it reads a linked list of symbol files from the global
5462 variable to find existing code, and puts a breakpoint in the function so
5463 that it can find out about additional code.
5467 * Declarations:: Relevant C struct declarations
5468 * Registering Code:: Steps to register code
5469 * Unregistering Code:: Steps to unregister code
5470 * Custom Debug Info:: Emit debug information in a custom format
5473 File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface
5475 29.1 JIT Declarations
5476 =====================
5478 These are the relevant struct declarations that a C program should
5479 include to implement the interface:
5488 struct jit_code_entry
5490 struct jit_code_entry *next_entry;
5491 struct jit_code_entry *prev_entry;
5492 const char *symfile_addr;
5493 uint64_t symfile_size;
5496 struct jit_descriptor
5499 /* This type should be jit_actions_t, but we use uint32_t
5500 to be explicit about the bitwidth. */
5501 uint32_t action_flag;
5502 struct jit_code_entry *relevant_entry;
5503 struct jit_code_entry *first_entry;
5506 /* GDB puts a breakpoint in this function. */
5507 void __attribute__((noinline)) __jit_debug_register_code() { };
5509 /* Make sure to specify the version statically, because the
5510 debugger may check the version before we can set it. */
5511 struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
5513 If the JIT is multi-threaded, then it is important that the JIT
5514 synchronize any modifications to this global data properly, which can
5515 easily be done by putting a global mutex around modifications to these
5519 File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface
5521 29.2 Registering Code
5522 =====================
5524 To register code with GDB, the JIT should follow this protocol:
5526 * Generate an object file in memory with symbols and other desired
5527 debug information. The file must include the virtual addresses of
5530 * Create a code entry for the file, which gives the start and size of
5533 * Add it to the linked list in the JIT descriptor.
5535 * Point the relevant_entry field of the descriptor at the entry.
5537 * Set 'action_flag' to 'JIT_REGISTER' and call
5538 '__jit_debug_register_code'.
5540 When GDB is attached and the breakpoint fires, GDB uses the
5541 'relevant_entry' pointer so it doesn't have to walk the list looking for
5542 new code. However, the linked list must still be maintained in order to
5543 allow GDB to attach to a running process and still find the symbol
5547 File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface
5549 29.3 Unregistering Code
5550 =======================
5552 If code is freed, then the JIT should use the following protocol:
5554 * Remove the code entry corresponding to the code from the linked
5557 * Point the 'relevant_entry' field of the descriptor at the code
5560 * Set 'action_flag' to 'JIT_UNREGISTER' and call
5561 '__jit_debug_register_code'.
5563 If the JIT frees or recompiles code without unregistering it, then
5564 GDB and the JIT will leak the memory used for the associated symbol
5568 File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface
5570 29.4 Custom Debug Info
5571 ======================
5573 Generating debug information in platform-native file formats (like ELF
5574 or COFF) may be an overkill for JIT compilers; especially if all the
5575 debug info is used for is displaying a meaningful backtrace. The issue
5576 can be resolved by having the JIT writers decide on a debug info format
5577 and also provide a reader that parses the debug info generated by the
5578 JIT compiler. This section gives a brief overview on writing such a
5579 parser. More specific details can be found in the source file
5580 'gdb/jit-reader.in', which is also installed as a header at
5581 'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion.
5583 The reader is implemented as a shared object (so this functionality
5584 is not available on platforms which don't allow loading shared objects
5585 at runtime). Two GDB commands, 'jit-reader-load' and
5586 'jit-reader-unload' are provided, to be used to load and unload the
5587 readers from a preconfigured directory. Once loaded, the shared object
5588 is used the parse the debug information emitted by the JIT compiler.
5592 * Using JIT Debug Info Readers:: How to use supplied readers correctly
5593 * Writing JIT Debug Info Readers:: Creating a debug-info reader
5596 File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info
5598 29.4.1 Using JIT Debug Info Readers
5599 -----------------------------------
5601 Readers can be loaded and unloaded using the 'jit-reader-load' and
5602 'jit-reader-unload' commands.
5604 'jit-reader-load READER'
5605 Load the JIT reader named READER, which is a shared object
5606 specified as either an absolute or a relative file name. In the
5607 latter case, GDB will try to load the reader from a pre-configured
5608 directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is
5609 the system library directory, often '/usr/local/lib').
5611 Only one reader can be active at a time; trying to load a second
5612 reader when one is already loaded will result in GDB reporting an
5613 error. A new JIT reader can be loaded by first unloading the
5614 current one using 'jit-reader-unload' and then invoking
5618 Unload the currently loaded JIT reader.
5621 File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info
5623 29.4.2 Writing JIT Debug Info Readers
5624 -------------------------------------
5626 As mentioned, a reader is essentially a shared object conforming to a
5627 certain ABI. This ABI is described in 'jit-reader.h'.
5629 'jit-reader.h' defines the structures, macros and functions required
5630 to write a reader. It is installed (along with GDB), in
5631 'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory.
5633 Readers need to be released under a GPL compatible license. A reader
5634 can be declared as released under such a license by placing the macro
5635 'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file.
5637 The entry point for readers is the symbol 'gdb_init_reader', which is
5638 expected to be a function with the prototype
5640 extern struct gdb_reader_funcs *gdb_init_reader (void);
5642 'struct gdb_reader_funcs' contains a set of pointers to callback
5643 functions. These functions are executed to read the debug info
5644 generated by the JIT compiler ('read'), to unwind stack frames
5645 ('unwind') and to create canonical frame IDs ('get_Frame_id'). It also
5646 has a callback that is called when the reader is being unloaded
5647 ('destroy'). The struct looks like this
5649 struct gdb_reader_funcs
5651 /* Must be set to GDB_READER_INTERFACE_VERSION. */
5654 /* For use by the reader. */
5657 gdb_read_debug_info *read;
5658 gdb_unwind_frame *unwind;
5659 gdb_get_frame_id *get_frame_id;
5660 gdb_destroy_reader *destroy;
5663 The callbacks are provided with another set of callbacks by GDB to do
5664 their job. For 'read', these callbacks are passed in a 'struct
5665 gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct
5666 gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to
5667 create new object files and new symbol tables inside those object files.
5668 'struct gdb_unwind_callbacks' has callbacks to read registers off the
5669 current frame and to write out the values of the registers in the
5670 previous frame. Both have a callback ('target_read') to read bytes off
5671 the target's address space.
5674 File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top
5679 The traditional debugging model is conceptually low-speed, but works
5680 fine, because most bugs can be reproduced in debugging-mode execution.
5681 However, as multi-core or many-core processors are becoming mainstream,
5682 and multi-threaded programs become more and more popular, there should
5683 be more and more bugs that only manifest themselves at normal-mode
5684 execution, for example, thread races, because debugger's interference
5685 with the program's timing may conceal the bugs. On the other hand, in
5686 some applications, it is not feasible for the debugger to interrupt the
5687 program's execution long enough for the developer to learn anything
5688 helpful about its behavior. If the program's correctness depends on its
5689 real-time behavior, delays introduced by a debugger might cause the
5690 program to fail, even when the code itself is correct. It is useful to
5691 be able to observe the program's behavior without interrupting it.
5693 Therefore, traditional debugging model is too intrusive to reproduce
5694 some bugs. In order to reduce the interference with the program, we can
5695 reduce the number of operations performed by debugger. The "In-Process
5696 Agent", a shared library, is running within the same process with
5697 inferior, and is able to perform some debugging operations itself. As a
5698 result, debugger is only involved when necessary, and performance of
5699 debugging can be improved accordingly. Note that interference with
5700 program can be reduced but can't be removed completely, because the
5701 in-process agent will still stop or slow down the program.
5703 The in-process agent can interpret and execute Agent Expressions
5704 (*note Agent Expressions::) during performing debugging operations. The
5705 agent expressions can be used for different purposes, such as collecting
5706 data in tracepoints, and condition evaluation in breakpoints.
5708 You can control whether the in-process agent is used as an aid for
5709 debugging with the following commands:
5712 Causes the in-process agent to perform some operations on behalf of
5713 the debugger. Just which operations requested by the user will be
5714 done by the in-process agent depends on the its capabilities. For
5715 example, if you request to evaluate breakpoint conditions in the
5716 in-process agent, and the in-process agent has such capability as
5717 well, then breakpoint conditions will be evaluated in the
5721 Disables execution of debugging operations by the in-process agent.
5722 All of the operations will be performed by GDB.
5725 Display the current setting of execution of debugging operations by
5726 the in-process agent.
5730 * In-Process Agent Protocol::
5733 File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent
5735 30.1 In-Process Agent Protocol
5736 ==============================
5738 The in-process agent is able to communicate with both GDB and GDBserver
5739 (*note In-Process Agent::). This section documents the protocol used
5740 for communications between GDB or GDBserver and the IPA. In general, GDB
5741 or GDBserver sends commands (*note IPA Protocol Commands::) and data to
5742 in-process agent, and then in-process agent replies back with the return
5743 result of the command, or some other information. The data sent to
5744 in-process agent is composed of primitive data types, such as 4-byte or
5745 8-byte type, and composite types, which are called objects (*note IPA
5746 Protocol Objects::).
5750 * IPA Protocol Objects::
5751 * IPA Protocol Commands::
5754 File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol
5756 30.1.1 IPA Protocol Objects
5757 ---------------------------
5759 The commands sent to and results received from agent may contain some
5760 complex data types called "objects".
5762 The in-process agent is running on the same machine with GDB or
5763 GDBserver, so it doesn't have to handle as much differences between two
5764 ends as remote protocol (*note Remote Protocol::) tries to handle.
5765 However, there are still some differences of two ends in two processes:
5767 1. word size. On some 64-bit machines, GDB or GDBserver can be
5768 compiled as a 64-bit executable, while in-process agent is a 32-bit
5770 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver
5771 is compiled with one, and in-process agent is compiled with the
5774 Here are the IPA Protocol Objects:
5776 1. agent expression object. It represents an agent expression (*note
5777 Agent Expressions::).
5778 2. tracepoint action object. It represents a tracepoint action (*note
5779 Tracepoint Action Lists: Tracepoint Actions.) to collect registers,
5780 memory, static trace data and to evaluate expression.
5781 3. tracepoint object. It represents a tracepoint (*note
5784 The following table describes important attributes of each IPA
5787 Name Size Description
5788 ---------------------------------------------------------------------------
5791 length 4 length of bytes code
5792 byte code LENGTH contents of byte code
5796 'M' 1 type of tracepoint action
5797 addr 8 if BASEREG is '-1', ADDR is the
5798 address of the lowest byte to
5799 collect, otherwise ADDR is the
5800 offset of BASEREG for memory
5802 len 8 length of memory for collecting
5803 basereg 4 the register number containing the
5804 starting memory address for
5809 'R' 1 type of tracepoint action
5813 'L' 1 type of tracepoint action
5817 'X' 1 type of tracepoint action
5818 agent expression length of *note agent expression object::
5820 number 4 number of tracepoint
5821 address 8 address of tracepoint inserted on
5822 type 4 type of tracepoint
5823 enabled 1 enable or disable of tracepoint
5826 numactions 4 number of tracepoint actions
5827 hit count 8 hit count
5828 trace frame usage 8 trace frame usage
5829 compiled_cond 8 compiled condition
5830 orig_size 8 orig size
5831 condition 4 if zero if condition is NULL,
5832 condition is otherwise is *note agent
5833 NULL expression object::
5839 actions variable numactions number of *note
5840 tracepoint action object::
5843 File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol
5845 30.1.2 IPA Protocol Commands
5846 ----------------------------
5848 The spaces in each command are delimiters to ease reading this commands
5849 specification. They don't exist in real commands.
5851 'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'
5852 Installs a new fast tracepoint described by TRACEPOINT_OBJECT
5853 (*note tracepoint object::). The GDB_JUMP_PAD_HEAD, 8-byte long,
5854 is the head of "jumppad", which is used to jump to data collection
5855 routine in IPA finally.
5858 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'
5859 TARGET_ADDRESS is address of tracepoint in the inferior. The
5860 GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of
5861 TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. The
5862 FJUMP contains a sequence of instructions jump to jumppad
5863 entry. The FJUMP_SIZE, 4-byte long, is the size of FJUMP.
5868 Closes the in-process agent. This command is sent when GDB or
5869 GDBserver is about to kill inferiors.
5877 'probe_marker_at:ADDRESS'
5878 Asks in-process agent to probe the marker at ADDRESS.
5883 'unprobe_marker_at:ADDRESS'
5884 Asks in-process agent to unprobe the marker at ADDRESS.
5887 File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top
5889 31 Reporting Bugs in GDB
5890 ************************
5892 Your bug reports play an essential role in making GDB reliable.
5894 Reporting a bug may help you by bringing a solution to your problem,
5895 or it may not. But in any case the principal function of a bug report
5896 is to help the entire community by making the next version of GDB work
5897 better. Bug reports are your contribution to the maintenance of GDB.
5899 In order for a bug report to serve its purpose, you must include the
5900 information that enables us to fix the bug.
5904 * Bug Criteria:: Have you found a bug?
5905 * Bug Reporting:: How to report bugs
5908 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
5910 31.1 Have You Found a Bug?
5911 ==========================
5913 If you are not sure whether you have found a bug, here are some
5916 * If the debugger gets a fatal signal, for any input whatever, that
5917 is a GDB bug. Reliable debuggers never crash.
5919 * If GDB produces an error message for valid input, that is a bug.
5920 (Note that if you're cross debugging, the problem may also be
5921 somewhere in the connection to the target.)
5923 * If GDB does not produce an error message for invalid input, that is
5924 a bug. However, you should note that your idea of "invalid input"
5925 might be our idea of "an extension" or "support for traditional
5928 * If you are an experienced user of debugging tools, your suggestions
5929 for improvement of GDB are welcome in any case.
5932 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
5934 31.2 How to Report Bugs
5935 =======================
5937 A number of companies and individuals offer support for GNU products.
5938 If you obtained GDB from a support organization, we recommend you
5939 contact that organization first.
5941 You can find contact information for many support companies and
5942 individuals in the file 'etc/SERVICE' in the GNU Emacs distribution.
5944 In any event, we also recommend that you submit bug reports for GDB.
5945 The preferred method is to submit them directly using GDB's Bugs web
5946 page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the e-mail
5947 gateway <bug-gdb@gnu.org> can be used.
5949 *Do not send bug reports to 'info-gdb', or to 'help-gdb', or to any
5950 newsgroups.* Most users of GDB do not want to receive bug reports.
5951 Those that do have arranged to receive 'bug-gdb'.
5953 The mailing list 'bug-gdb' has a newsgroup 'gnu.gdb.bug' which serves
5954 as a repeater. The mailing list and the newsgroup carry exactly the
5955 same messages. Often people think of posting bug reports to the
5956 newsgroup instead of mailing them. This appears to work, but it has one
5957 problem which can be crucial: a newsgroup posting often lacks a mail
5958 path back to the sender. Thus, if we need to ask for more information,
5959 we may be unable to reach you. For this reason, it is better to send
5960 bug reports to the mailing list.
5962 The fundamental principle of reporting bugs usefully is this: *report
5963 all the facts*. If you are not sure whether to state a fact or leave it
5966 Often people omit facts because they think they know what causes the
5967 problem and assume that some details do not matter. Thus, you might
5968 assume that the name of the variable you use in an example does not
5969 matter. Well, probably it does not, but one cannot be sure. Perhaps
5970 the bug is a stray memory reference which happens to fetch from the
5971 location where that name is stored in memory; perhaps, if the name were
5972 different, the contents of that location would fool the debugger into
5973 doing the right thing despite the bug. Play it safe and give a
5974 specific, complete example. That is the easiest thing for you to do,
5975 and the most helpful.
5977 Keep in mind that the purpose of a bug report is to enable us to fix
5978 the bug. It may be that the bug has been reported previously, but
5979 neither you nor we can know that unless your bug report is complete and
5982 Sometimes people give a few sketchy facts and ask, "Does this ring a
5983 bell?" Those bug reports are useless, and we urge everyone to _refuse
5984 to respond to them_ except to chide the sender to report bugs properly.
5986 To enable us to fix the bug, you should include all these things:
5988 * The version of GDB. GDB announces it if you start with no
5989 arguments; you can also print it at any time using 'show version'.
5991 Without this, we will not know whether there is any point in
5992 looking for the bug in the current version of GDB.
5994 * The type of machine you are using, and the operating system name
5997 * The details of the GDB build-time configuration. GDB shows these
5998 details if you invoke it with the '--configuration' command-line
5999 option, or if you type 'show configuration' at GDB's prompt.
6001 * What compiler (and its version) was used to compile GDB--e.g.
6004 * What compiler (and its version) was used to compile the program you
6005 are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C
6006 Compiler". For GCC, you can say 'gcc --version' to get this
6007 information; for other compilers, see the documentation for those
6010 * The command arguments you gave the compiler to compile your example
6011 and observe the bug. For example, did you use '-O'? To guarantee
6012 you will not omit something important, list them all. A copy of
6013 the Makefile (or the output from make) is sufficient.
6015 If we were to try to guess the arguments, we would probably guess
6016 wrong and then we might not encounter the bug.
6018 * A complete input script, and all necessary source files, that will
6021 * A description of what behavior you observe that you believe is
6022 incorrect. For example, "It gets a fatal signal."
6024 Of course, if the bug is that GDB gets a fatal signal, then we will
6025 certainly notice it. But if the bug is incorrect output, we might
6026 not notice unless it is glaringly wrong. You might as well not
6027 give us a chance to make a mistake.
6029 Even if the problem you experience is a fatal signal, you should
6030 still say so explicitly. Suppose something strange is going on,
6031 such as, your copy of GDB is out of synch, or you have encountered
6032 a bug in the C library on your system. (This has happened!) Your
6033 copy might crash and ours would not. If you told us to expect a
6034 crash, then when ours fails to crash, we would know that the bug
6035 was not happening for us. If you had not told us to expect a
6036 crash, then we would not be able to draw any conclusion from our
6039 To collect all this information, you can use a session recording
6040 program such as 'script', which is available on many Unix systems.
6041 Just run your GDB session inside 'script' and then include the
6042 'typescript' file with your bug report.
6044 Another way to record a GDB session is to run GDB inside Emacs and
6045 then save the entire buffer to a file.
6047 * If you wish to suggest changes to the GDB source, send us context
6048 diffs. If you even discuss something in the GDB source, refer to
6049 it by context, not by line number.
6051 The line numbers in our development sources will not match those in
6052 your sources. Your line numbers would convey no useful information
6055 Here are some things that are not necessary:
6057 * A description of the envelope of the bug.
6059 Often people who encounter a bug spend a lot of time investigating
6060 which changes to the input file will make the bug go away and which
6061 changes will not affect it.
6063 This is often time consuming and not very useful, because the way
6064 we will find the bug is by running a single example under the
6065 debugger with breakpoints, not by pure deduction from a series of
6066 examples. We recommend that you save your time for something else.
6068 Of course, if you can find a simpler example to report _instead_ of
6069 the original one, that is a convenience for us. Errors in the
6070 output will be easier to spot, running under the debugger will take
6071 less time, and so on.
6073 However, simplification is not vital; if you do not want to do
6074 this, report the bug anyway and send us the entire test case you
6077 * A patch for the bug.
6079 A patch for the bug does help us if it is a good one. But do not
6080 omit the necessary information, such as the test case, on the
6081 assumption that a patch is all we need. We might see problems with
6082 your patch and decide to fix the problem another way, or we might
6083 not understand it at all.
6085 Sometimes with a program as complicated as GDB it is very hard to
6086 construct an example that will make the program follow a certain
6087 path through the code. If you do not send us the example, we will
6088 not be able to construct one, so we will not be able to verify that
6091 And if we cannot understand what bug you are trying to fix, or why
6092 your patch should be an improvement, we will not install it. A
6093 test case will help us to understand.
6095 * A guess about what the bug is or what it depends on.
6097 Such guesses are usually wrong. Even we cannot guess right about
6098 such things without first using the debugger to find the facts.
6101 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
6103 32 Command Line Editing
6104 ***********************
6106 This chapter describes the basic features of the GNU command line
6111 * Introduction and Notation:: Notation used in this text.
6112 * Readline Interaction:: The minimum set of commands for editing a line.
6113 * Readline Init File:: Customizing Readline from a user's view.
6114 * Bindable Readline Commands:: A description of most of the Readline commands
6115 available for binding
6116 * Readline vi Mode:: A short description of how to make Readline
6117 behave like the vi editor.
6120 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
6122 32.1 Introduction to Line Editing
6123 =================================
6125 The following paragraphs describe the notation used to represent
6128 The text 'C-k' is read as 'Control-K' and describes the character
6129 produced when the <k> key is pressed while the Control key is depressed.
6131 The text 'M-k' is read as 'Meta-K' and describes the character
6132 produced when the Meta key (if you have one) is depressed, and the <k>
6133 key is pressed. The Meta key is labeled <ALT> on many keyboards. On
6134 keyboards with two keys labeled <ALT> (usually to either side of the
6135 space bar), the <ALT> on the left side is generally set to work as a
6136 Meta key. The <ALT> key on the right may also be configured to work as
6137 a Meta key or may be configured as some other modifier, such as a
6138 Compose key for typing accented characters.
6140 If you do not have a Meta or <ALT> key, or another key working as a
6141 Meta key, the identical keystroke can be generated by typing <ESC>
6142 _first_, and then typing <k>. Either process is known as "metafying"
6145 The text 'M-C-k' is read as 'Meta-Control-k' and describes the
6146 character produced by "metafying" 'C-k'.
6148 In addition, several keys have their own names. Specifically, <DEL>,
6149 <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen
6150 in this text, or in an init file (*note Readline Init File::). If your
6151 keyboard lacks a <LFD> key, typing <C-j> will produce the desired
6152 character. The <RET> key may be labeled <Return> or <Enter> on some
6156 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
6158 32.2 Readline Interaction
6159 =========================
6161 Often during an interactive session you type in a long line of text,
6162 only to notice that the first word on the line is misspelled. The
6163 Readline library gives you a set of commands for manipulating the text
6164 as you type it in, allowing you to just fix your typo, and not forcing
6165 you to retype the majority of the line. Using these editing commands,
6166 you move the cursor to the place that needs correction, and delete or
6167 insert the text of the corrections. Then, when you are satisfied with
6168 the line, you simply press <RET>. You do not have to be at the end of
6169 the line to press <RET>; the entire line is accepted regardless of the
6170 location of the cursor within the line.
6174 * Readline Bare Essentials:: The least you need to know about Readline.
6175 * Readline Movement Commands:: Moving about the input line.
6176 * Readline Killing Commands:: How to delete text, and how to get it back!
6177 * Readline Arguments:: Giving numeric arguments to commands.
6178 * Searching:: Searching through previous lines.
6181 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
6183 32.2.1 Readline Bare Essentials
6184 -------------------------------
6186 In order to enter characters into the line, simply type them. The typed
6187 character appears where the cursor was, and then the cursor moves one
6188 space to the right. If you mistype a character, you can use your erase
6189 character to back up and delete the mistyped character.
6191 Sometimes you may mistype a character, and not notice the error until
6192 you have typed several other characters. In that case, you can type
6193 'C-b' to move the cursor to the left, and then correct your mistake.
6194 Afterwards, you can move the cursor to the right with 'C-f'.
6196 When you add text in the middle of a line, you will notice that
6197 characters to the right of the cursor are 'pushed over' to make room for
6198 the text that you have inserted. Likewise, when you delete text behind
6199 the cursor, characters to the right of the cursor are 'pulled back' to
6200 fill in the blank space created by the removal of the text. A list of
6201 the bare essentials for editing the text of an input line follows.
6204 Move back one character.
6206 Move forward one character.
6207 <DEL> or <Backspace>
6208 Delete the character to the left of the cursor.
6210 Delete the character underneath the cursor.
6212 Insert the character into the line at the cursor.
6214 Undo the last editing command. You can undo all the way back to an
6217 (Depending on your configuration, the <Backspace> key be set to delete
6218 the character to the left of the cursor and the <DEL> key set to delete
6219 the character underneath the cursor, like 'C-d', rather than the
6220 character to the left of the cursor.)
6223 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
6225 32.2.2 Readline Movement Commands
6226 ---------------------------------
6228 The above table describes the most basic keystrokes that you need in
6229 order to do editing of the input line. For your convenience, many other
6230 commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>.
6231 Here are some commands for moving more rapidly about the line.
6234 Move to the start of the line.
6236 Move to the end of the line.
6238 Move forward a word, where a word is composed of letters and
6241 Move backward a word.
6243 Clear the screen, reprinting the current line at the top.
6245 Notice how 'C-f' moves forward a character, while 'M-f' moves forward
6246 a word. It is a loose convention that control keystrokes operate on
6247 characters while meta keystrokes operate on words.
6250 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
6252 32.2.3 Readline Killing Commands
6253 --------------------------------
6255 "Killing" text means to delete the text from the line, but to save it
6256 away for later use, usually by "yanking" (re-inserting) it back into the
6257 line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.)
6259 If the description for a command says that it 'kills' text, then you
6260 can be sure that you can get the text back in a different (or the same)
6263 When you use a kill command, the text is saved in a "kill-ring". Any
6264 number of consecutive kills save all of the killed text together, so
6265 that when you yank it back, you get it all. The kill ring is not line
6266 specific; the text that you killed on a previously typed line is
6267 available to be yanked back later, when you are typing another line.
6269 Here is the list of commands for killing text.
6272 Kill the text from the current cursor position to the end of the
6276 Kill from the cursor to the end of the current word, or, if between
6277 words, to the end of the next word. Word boundaries are the same
6278 as those used by 'M-f'.
6281 Kill from the cursor the start of the current word, or, if between
6282 words, to the start of the previous word. Word boundaries are the
6283 same as those used by 'M-b'.
6286 Kill from the cursor to the previous whitespace. This is different
6287 than 'M-<DEL>' because the word boundaries differ.
6289 Here is how to "yank" the text back into the line. Yanking means to
6290 copy the most-recently-killed text from the kill buffer.
6293 Yank the most recently killed text back into the buffer at the
6297 Rotate the kill-ring, and yank the new top. You can only do this
6298 if the prior command is 'C-y' or 'M-y'.
6301 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
6303 32.2.4 Readline Arguments
6304 -------------------------
6306 You can pass numeric arguments to Readline commands. Sometimes the
6307 argument acts as a repeat count, other times it is the sign of the
6308 argument that is significant. If you pass a negative argument to a
6309 command which normally acts in a forward direction, that command will
6310 act in a backward direction. For example, to kill text back to the
6311 start of the line, you might type 'M-- C-k'.
6313 The general way to pass numeric arguments to a command is to type
6314 meta digits before the command. If the first 'digit' typed is a minus
6315 sign ('-'), then the sign of the argument will be negative. Once you
6316 have typed one meta digit to get the argument started, you can type the
6317 remainder of the digits, and then the command. For example, to give the
6318 'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will
6319 delete the next ten characters on the input line.
6322 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
6324 32.2.5 Searching for Commands in the History
6325 --------------------------------------------
6327 Readline provides commands for searching through the command history for
6328 lines containing a specified string. There are two search modes:
6329 "incremental" and "non-incremental".
6331 Incremental searches begin before the user has finished typing the
6332 search string. As each character of the search string is typed,
6333 Readline displays the next entry from the history matching the string
6334 typed so far. An incremental search requires only as many characters as
6335 needed to find the desired history entry. To search backward in the
6336 history for a particular string, type 'C-r'. Typing 'C-s' searches
6337 forward through the history. The characters present in the value of the
6338 'isearch-terminators' variable are used to terminate an incremental
6339 search. If that variable has not been assigned a value, the <ESC> and
6340 'C-J' characters will terminate an incremental search. 'C-g' will abort
6341 an incremental search and restore the original line. When the search is
6342 terminated, the history entry containing the search string becomes the
6345 To find other matching entries in the history list, type 'C-r' or
6346 'C-s' as appropriate. This will search backward or forward in the
6347 history for the next entry matching the search string typed so far. Any
6348 other key sequence bound to a Readline command will terminate the search
6349 and execute that command. For instance, a <RET> will terminate the
6350 search and accept the line, thereby executing the command from the
6351 history list. A movement command will terminate the search, make the
6352 last line found the current line, and begin editing.
6354 Readline remembers the last incremental search string. If two 'C-r's
6355 are typed without any intervening characters defining a new search
6356 string, any remembered search string is used.
6358 Non-incremental searches read the entire search string before
6359 starting to search for matching history lines. The search string may be
6360 typed by the user or be part of the contents of the current line.
6363 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
6365 32.3 Readline Init File
6366 =======================
6368 Although the Readline library comes with a set of Emacs-like keybindings
6369 installed by default, it is possible to use a different set of
6370 keybindings. Any user can customize programs that use Readline by
6371 putting commands in an "inputrc" file, conventionally in his home
6372 directory. The name of this file is taken from the value of the
6373 environment variable 'INPUTRC'. If that variable is unset, the default
6374 is '~/.inputrc'. If that file does not exist or cannot be read, the
6375 ultimate default is '/etc/inputrc'.
6377 When a program which uses the Readline library starts up, the init
6378 file is read, and the key bindings are set.
6380 In addition, the 'C-x C-r' command re-reads this init file, thus
6381 incorporating any changes that you might have made to it.
6385 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
6387 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
6389 * Sample Init File:: An example inputrc file.
6392 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
6394 32.3.1 Readline Init File Syntax
6395 --------------------------------
6397 There are only a few basic constructs allowed in the Readline init file.
6398 Blank lines are ignored. Lines beginning with a '#' are comments.
6399 Lines beginning with a '$' indicate conditional constructs (*note
6400 Conditional Init Constructs::). Other lines denote variable settings
6404 You can modify the run-time behavior of Readline by altering the
6405 values of variables in Readline using the 'set' command within the
6406 init file. The syntax is simple:
6410 Here, for example, is how to change from the default Emacs-like key
6411 binding to use 'vi' line editing commands:
6415 Variable names and values, where appropriate, are recognized
6416 without regard to case. Unrecognized variable names are ignored.
6418 Boolean variables (those that can be set to on or off) are set to
6419 on if the value is null or empty, ON (case-insensitive), or 1. Any
6420 other value results in the variable being set to off.
6422 A great deal of run-time behavior is changeable with the following
6426 Controls what happens when Readline wants to ring the terminal
6427 bell. If set to 'none', Readline never rings the bell. If
6428 set to 'visible', Readline uses a visible bell if one is
6429 available. If set to 'audible' (the default), Readline
6430 attempts to ring the terminal's bell.
6432 'bind-tty-special-chars'
6433 If set to 'on', Readline attempts to bind the control
6434 characters treated specially by the kernel's terminal driver
6435 to their Readline equivalents.
6438 The string to insert at the beginning of the line when the
6439 'insert-comment' command is executed. The default value is
6442 'completion-display-width'
6443 The number of screen columns used to display possible matches
6444 when performing completion. The value is ignored if it is
6445 less than 0 or greater than the terminal screen width. A
6446 value of 0 will cause matches to be displayed one per line.
6447 The default value is -1.
6449 'completion-ignore-case'
6450 If set to 'on', Readline performs filename matching and
6451 completion in a case-insensitive fashion. The default value
6454 'completion-map-case'
6455 If set to 'on', and COMPLETION-IGNORE-CASE is enabled,
6456 Readline treats hyphens ('-') and underscores ('_') as
6457 equivalent when performing case-insensitive filename matching
6460 'completion-prefix-display-length'
6461 The length in characters of the common prefix of a list of
6462 possible completions that is displayed without modification.
6463 When set to a value greater than zero, common prefixes longer
6464 than this value are replaced with an ellipsis when displaying
6465 possible completions.
6467 'completion-query-items'
6468 The number of possible completions that determines when the
6469 user is asked whether the list of possibilities should be
6470 displayed. If the number of possible completions is greater
6471 than this value, Readline will ask the user whether or not he
6472 wishes to view them; otherwise, they are simply listed. This
6473 variable must be set to an integer value greater than or equal
6474 to 0. A negative value means Readline should never ask. The
6475 default limit is '100'.
6478 If set to 'on', Readline will convert characters with the
6479 eighth bit set to an ASCII key sequence by stripping the
6480 eighth bit and prefixing an <ESC> character, converting them
6481 to a meta-prefixed key sequence. The default value is 'on'.
6483 'disable-completion'
6484 If set to 'On', Readline will inhibit word completion.
6485 Completion characters will be inserted into the line as if
6486 they had been mapped to 'self-insert'. The default is 'off'.
6489 The 'editing-mode' variable controls which default set of key
6490 bindings is used. By default, Readline starts up in Emacs
6491 editing mode, where the keystrokes are most similar to Emacs.
6492 This variable can be set to either 'emacs' or 'vi'.
6494 'echo-control-characters'
6495 When set to 'on', on operating systems that indicate they
6496 support it, readline echoes a character corresponding to a
6497 signal generated from the keyboard. The default is 'on'.
6500 When set to 'on', Readline will try to enable the application
6501 keypad when it is called. Some systems need this to enable
6502 the arrow keys. The default is 'off'.
6505 When set to 'on', Readline will try to enable any meta
6506 modifier key the terminal claims to support when it is called.
6507 On many terminals, the meta key is used to send eight-bit
6508 characters. The default is 'on'.
6511 If set to 'on', tilde expansion is performed when Readline
6512 attempts word completion. The default is 'off'.
6514 'history-preserve-point'
6515 If set to 'on', the history code attempts to place the point
6516 (the current cursor position) at the same location on each
6517 history line retrieved with 'previous-history' or
6518 'next-history'. The default is 'off'.
6521 Set the maximum number of history entries saved in the history
6522 list. If set to zero, the number of entries in the history
6523 list is not limited.
6525 'horizontal-scroll-mode'
6526 This variable can be set to either 'on' or 'off'. Setting it
6527 to 'on' means that the text of the lines being edited will
6528 scroll horizontally on a single screen line when they are
6529 longer than the width of the screen, instead of wrapping onto
6530 a new screen line. By default, this variable is set to 'off'.
6533 If set to 'on', Readline will enable eight-bit input (it will
6534 not clear the eighth bit in the characters it reads),
6535 regardless of what the terminal claims it can support. The
6536 default value is 'off'. The name 'meta-flag' is a synonym for
6539 'isearch-terminators'
6540 The string of characters that should terminate an incremental
6541 search without subsequently executing the character as a
6542 command (*note Searching::). If this variable has not been
6543 given a value, the characters <ESC> and 'C-J' will terminate
6544 an incremental search.
6547 Sets Readline's idea of the current keymap for key binding
6548 commands. Acceptable 'keymap' names are 'emacs',
6549 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',
6550 'vi-command', and 'vi-insert'. 'vi' is equivalent to
6551 'vi-command'; 'emacs' is equivalent to 'emacs-standard'. The
6552 default value is 'emacs'. The value of the 'editing-mode'
6553 variable also affects the default keymap.
6556 If set to 'on', completed directory names have a slash
6557 appended. The default is 'on'.
6559 'mark-modified-lines'
6560 This variable, when set to 'on', causes Readline to display an
6561 asterisk ('*') at the start of history lines which have been
6562 modified. This variable is 'off' by default.
6564 'mark-symlinked-directories'
6565 If set to 'on', completed names which are symbolic links to
6566 directories have a slash appended (subject to the value of
6567 'mark-directories'). The default is 'off'.
6569 'match-hidden-files'
6570 This variable, when set to 'on', causes Readline to match
6571 files whose names begin with a '.' (hidden files) when
6572 performing filename completion. If set to 'off', the leading
6573 '.' must be supplied by the user in the filename to be
6574 completed. This variable is 'on' by default.
6576 'menu-complete-display-prefix'
6577 If set to 'on', menu completion displays the common prefix of
6578 the list of possible completions (which may be empty) before
6579 cycling through the list. The default is 'off'.
6582 If set to 'on', Readline will display characters with the
6583 eighth bit set directly rather than as a meta-prefixed escape
6584 sequence. The default is 'off'.
6587 If set to 'on', Readline uses an internal 'more'-like pager to
6588 display a screenful of possible completions at a time. This
6589 variable is 'on' by default.
6591 'print-completions-horizontally'
6592 If set to 'on', Readline will display completions with matches
6593 sorted horizontally in alphabetical order, rather than down
6594 the screen. The default is 'off'.
6596 'revert-all-at-newline'
6597 If set to 'on', Readline will undo all changes to history
6598 lines before returning when 'accept-line' is executed. By
6599 default, history lines may be modified and retain individual
6600 undo lists across calls to 'readline'. The default is 'off'.
6602 'show-all-if-ambiguous'
6603 This alters the default behavior of the completion functions.
6604 If set to 'on', words which have more than one possible
6605 completion cause the matches to be listed immediately instead
6606 of ringing the bell. The default value is 'off'.
6608 'show-all-if-unmodified'
6609 This alters the default behavior of the completion functions
6610 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
6611 'on', words which have more than one possible completion
6612 without any possible partial completion (the possible
6613 completions don't share a common prefix) cause the matches to
6614 be listed immediately instead of ringing the bell. The
6615 default value is 'off'.
6617 'skip-completed-text'
6618 If set to 'on', this alters the default completion behavior
6619 when inserting a single match into the line. It's only active
6620 when performing completion in the middle of a word. If
6621 enabled, readline does not insert characters from the
6622 completion that match characters after point in the word being
6623 completed, so portions of the word following the cursor are
6624 not duplicated. For instance, if this is enabled, attempting
6625 completion when the cursor is after the 'e' in 'Makefile' will
6626 result in 'Makefile' rather than 'Makefilefile', assuming
6627 there is a single possible completion. The default value is
6631 If set to 'on', a character denoting a file's type is appended
6632 to the filename when listing possible completions. The
6636 The syntax for controlling key bindings in the init file is simple.
6637 First you need to find the name of the command that you want to
6638 change. The following sections contain tables of the command name,
6639 the default keybinding, if any, and a short description of what the
6642 Once you know the name of the command, simply place on a line in
6643 the init file the name of the key you wish to bind the command to,
6644 a colon, and then the name of the command. There can be no space
6645 between the key name and the colon - that will be interpreted as
6646 part of the key name. The name of the key can be expressed in
6647 different ways, depending on what you find most comfortable.
6649 In addition to command names, readline allows keys to be bound to a
6650 string that is inserted when the key is pressed (a MACRO).
6652 KEYNAME: FUNCTION-NAME or MACRO
6653 KEYNAME is the name of a key spelled out in English. For
6655 Control-u: universal-argument
6656 Meta-Rubout: backward-kill-word
6657 Control-o: "> output"
6659 In the above example, 'C-u' is bound to the function
6660 'universal-argument', 'M-DEL' is bound to the function
6661 'backward-kill-word', and 'C-o' is bound to run the macro
6662 expressed on the right hand side (that is, to insert the text
6663 '> output' into the line).
6665 A number of symbolic character names are recognized while
6666 processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
6667 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
6669 "KEYSEQ": FUNCTION-NAME or MACRO
6670 KEYSEQ differs from KEYNAME above in that strings denoting an
6671 entire key sequence can be specified, by placing the key
6672 sequence in double quotes. Some GNU Emacs style key escapes
6673 can be used, as in the following example, but the special
6674 character names are not recognized.
6676 "\C-u": universal-argument
6677 "\C-x\C-r": re-read-init-file
6678 "\e[11~": "Function Key 1"
6680 In the above example, 'C-u' is again bound to the function
6681 'universal-argument' (just as it was in the first example),
6682 ''C-x' 'C-r'' is bound to the function 're-read-init-file',
6683 and '<ESC> <[> <1> <1> <~>' is bound to insert the text
6686 The following GNU Emacs style escape sequences are available when
6687 specifying key sequences:
6698 <">, a double quotation mark
6700 <'>, a single quote or apostrophe
6702 In addition to the GNU Emacs style escape sequences, a second set
6703 of backslash escapes is available:
6722 the eight-bit character whose value is the octal value NNN
6723 (one to three digits)
6725 the eight-bit character whose value is the hexadecimal value
6726 HH (one or two hex digits)
6728 When entering the text of a macro, single or double quotes must be
6729 used to indicate a macro definition. Unquoted text is assumed to
6730 be a function name. In the macro body, the backslash escapes
6731 described above are expanded. Backslash will quote any other
6732 character in the macro text, including '"' and '''. For example,
6733 the following binding will make ''C-x' \' insert a single '\' into
6738 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
6740 32.3.2 Conditional Init Constructs
6741 ----------------------------------
6743 Readline implements a facility similar in spirit to the conditional
6744 compilation features of the C preprocessor which allows key bindings and
6745 variable settings to be performed as the result of tests. There are
6746 four parser directives used.
6749 The '$if' construct allows bindings to be made based on the editing
6750 mode, the terminal being used, or the application using Readline.
6751 The text of the test extends to the end of the line; no characters
6752 are required to isolate it.
6755 The 'mode=' form of the '$if' directive is used to test
6756 whether Readline is in 'emacs' or 'vi' mode. This may be used
6757 in conjunction with the 'set keymap' command, for instance, to
6758 set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps
6759 only if Readline is starting out in 'emacs' mode.
6762 The 'term=' form may be used to include terminal-specific key
6763 bindings, perhaps to bind the key sequences output by the
6764 terminal's function keys. The word on the right side of the
6765 '=' is tested against both the full name of the terminal and
6766 the portion of the terminal name before the first '-'. This
6767 allows 'sun' to match both 'sun' and 'sun-cmd', for instance.
6770 The APPLICATION construct is used to include
6771 application-specific settings. Each program using the
6772 Readline library sets the APPLICATION NAME, and you can test
6773 for a particular value. This could be used to bind key
6774 sequences to functions useful for a specific program. For
6775 instance, the following command adds a key sequence that
6776 quotes the current or previous word in Bash:
6778 # Quote the current or previous word
6779 "\C-xq": "\eb\"\ef\""
6783 This command, as seen in the previous example, terminates an '$if'
6787 Commands in this branch of the '$if' directive are executed if the
6791 This directive takes a single filename as an argument and reads
6792 commands and bindings from that file. For example, the following
6793 directive reads from '/etc/inputrc':
6794 $include /etc/inputrc
6797 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
6799 32.3.3 Sample Init File
6800 -----------------------
6802 Here is an example of an INPUTRC file. This illustrates key binding,
6803 variable assignment, and conditional syntax.
6805 # This file controls the behaviour of line input editing for
6806 # programs that use the GNU Readline library. Existing
6807 # programs include FTP, Bash, and GDB.
6809 # You can re-read the inputrc file with C-x C-r.
6810 # Lines beginning with '#' are comments.
6812 # First, include any systemwide bindings and variable
6813 # assignments from /etc/Inputrc
6814 $include /etc/Inputrc
6817 # Set various bindings for emacs mode.
6819 set editing-mode emacs
6823 Meta-Control-h: backward-kill-word Text after the function name is ignored
6826 # Arrow keys in keypad mode
6828 #"\M-OD": backward-char
6829 #"\M-OC": forward-char
6830 #"\M-OA": previous-history
6831 #"\M-OB": next-history
6833 # Arrow keys in ANSI mode
6835 "\M-[D": backward-char
6836 "\M-[C": forward-char
6837 "\M-[A": previous-history
6838 "\M-[B": next-history
6840 # Arrow keys in 8 bit keypad mode
6842 #"\M-\C-OD": backward-char
6843 #"\M-\C-OC": forward-char
6844 #"\M-\C-OA": previous-history
6845 #"\M-\C-OB": next-history
6847 # Arrow keys in 8 bit ANSI mode
6849 #"\M-\C-[D": backward-char
6850 #"\M-\C-[C": forward-char
6851 #"\M-\C-[A": previous-history
6852 #"\M-\C-[B": next-history
6858 # An old-style binding. This happens to be the default.
6861 # Macros that are convenient for shell interaction
6864 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
6865 # prepare to type a quoted word --
6866 # insert open and close double quotes
6867 # and move to just after the open quote
6868 "\C-x\"": "\"\"\C-b"
6869 # insert a backslash (testing backslash escapes
6870 # in sequences and macros)
6872 # Quote the current or previous word
6873 "\C-xq": "\eb\"\ef\""
6874 # Add a binding to refresh the line, which is unbound
6875 "\C-xr": redraw-current-line
6876 # Edit variable on current line.
6877 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
6880 # use a visible bell if one is available
6881 set bell-style visible
6883 # don't strip characters to 7 bits when reading
6886 # allow iso-latin1 characters to be inserted rather
6887 # than converted to prefix-meta sequences
6888 set convert-meta off
6890 # display characters with the eighth bit set directly
6891 # rather than as meta-prefixed characters
6894 # if there are more than 150 possible completions for
6895 # a word, ask the user if he wants to see all of them
6896 set completion-query-items 150
6902 "\M-.": yank-last-arg
6906 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
6908 32.4 Bindable Readline Commands
6909 ===============================
6913 * Commands For Moving:: Moving about the line.
6914 * Commands For History:: Getting at previous lines.
6915 * Commands For Text:: Commands for changing text.
6916 * Commands For Killing:: Commands for killing and yanking.
6917 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
6918 * Commands For Completion:: Getting Readline to do the typing for you.
6919 * Keyboard Macros:: Saving and re-executing typed characters
6920 * Miscellaneous Commands:: Other miscellaneous commands.
6922 This section describes Readline commands that may be bound to key
6923 sequences. Command names without an accompanying key sequence are
6926 In the following descriptions, "point" refers to the current cursor
6927 position, and "mark" refers to a cursor position saved by the 'set-mark'
6928 command. The text between the point and mark is referred to as the
6932 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
6934 32.4.1 Commands For Moving
6935 --------------------------
6937 'beginning-of-line (C-a)'
6938 Move to the start of the current line.
6941 Move to the end of the line.
6943 'forward-char (C-f)'
6944 Move forward a character.
6946 'backward-char (C-b)'
6947 Move back a character.
6949 'forward-word (M-f)'
6950 Move forward to the end of the next word. Words are composed of
6953 'backward-word (M-b)'
6954 Move back to the start of the current or previous word. Words are
6955 composed of letters and digits.
6957 'clear-screen (C-l)'
6958 Clear the screen and redraw the current line, leaving the current
6959 line at the top of the screen.
6961 'redraw-current-line ()'
6962 Refresh the current line. By default, this is unbound.
6965 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
6967 32.4.2 Commands For Manipulating The History
6968 --------------------------------------------
6970 'accept-line (Newline or Return)'
6971 Accept the line regardless of where the cursor is. If this line is
6972 non-empty, it may be added to the history list for future recall
6973 with 'add_history()'. If this line is a modified history line, the
6974 history line is restored to its original state.
6976 'previous-history (C-p)'
6977 Move 'back' through the history list, fetching the previous
6980 'next-history (C-n)'
6981 Move 'forward' through the history list, fetching the next command.
6983 'beginning-of-history (M-<)'
6984 Move to the first line in the history.
6986 'end-of-history (M->)'
6987 Move to the end of the input history, i.e., the line currently
6990 'reverse-search-history (C-r)'
6991 Search backward starting at the current line and moving 'up'
6992 through the history as necessary. This is an incremental search.
6994 'forward-search-history (C-s)'
6995 Search forward starting at the current line and moving 'down'
6996 through the the history as necessary. This is an incremental
6999 'non-incremental-reverse-search-history (M-p)'
7000 Search backward starting at the current line and moving 'up'
7001 through the history as necessary using a non-incremental search for
7002 a string supplied by the user.
7004 'non-incremental-forward-search-history (M-n)'
7005 Search forward starting at the current line and moving 'down'
7006 through the the history as necessary using a non-incremental search
7007 for a string supplied by the user.
7009 'history-search-forward ()'
7010 Search forward through the history for the string of characters
7011 between the start of the current line and the point. This is a
7012 non-incremental search. By default, this command is unbound.
7014 'history-search-backward ()'
7015 Search backward through the history for the string of characters
7016 between the start of the current line and the point. This is a
7017 non-incremental search. By default, this command is unbound.
7019 'yank-nth-arg (M-C-y)'
7020 Insert the first argument to the previous command (usually the
7021 second word on the previous line) at point. With an argument N,
7022 insert the Nth word from the previous command (the words in the
7023 previous command begin with word 0). A negative argument inserts
7024 the Nth word from the end of the previous command. Once the
7025 argument N is computed, the argument is extracted as if the '!N'
7026 history expansion had been specified.
7028 'yank-last-arg (M-. or M-_)'
7029 Insert last argument to the previous command (the last word of the
7030 previous history entry). With a numeric argument, behave exactly
7031 like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back
7032 through the history list, inserting the last word (or the word
7033 specified by the argument to the first call) of each line in turn.
7034 Any numeric argument supplied to these successive calls determines
7035 the direction to move through the history. A negative argument
7036 switches the direction through the history (back or forward). The
7037 history expansion facilities are used to extract the last argument,
7038 as if the '!$' history expansion had been specified.
7041 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
7043 32.4.3 Commands For Changing Text
7044 ---------------------------------
7047 Delete the character at point. If point is at the beginning of the
7048 line, there are no characters in the line, and the last character
7049 typed was not bound to 'delete-char', then return EOF.
7051 'backward-delete-char (Rubout)'
7052 Delete the character behind the cursor. A numeric argument means
7053 to kill the characters instead of deleting them.
7055 'forward-backward-delete-char ()'
7056 Delete the character under the cursor, unless the cursor is at the
7057 end of the line, in which case the character behind the cursor is
7058 deleted. By default, this is not bound to a key.
7060 'quoted-insert (C-q or C-v)'
7061 Add the next character typed to the line verbatim. This is how to
7062 insert key sequences like 'C-q', for example.
7064 'tab-insert (M-<TAB>)'
7065 Insert a tab character.
7067 'self-insert (a, b, A, 1, !, ...)'
7070 'transpose-chars (C-t)'
7071 Drag the character before the cursor forward over the character at
7072 the cursor, moving the cursor forward as well. If the insertion
7073 point is at the end of the line, then this transposes the last two
7074 characters of the line. Negative arguments have no effect.
7076 'transpose-words (M-t)'
7077 Drag the word before point past the word after point, moving point
7078 past that word as well. If the insertion point is at the end of
7079 the line, this transposes the last two words on the line.
7082 Uppercase the current (or following) word. With a negative
7083 argument, uppercase the previous word, but do not move the cursor.
7085 'downcase-word (M-l)'
7086 Lowercase the current (or following) word. With a negative
7087 argument, lowercase the previous word, but do not move the cursor.
7089 'capitalize-word (M-c)'
7090 Capitalize the current (or following) word. With a negative
7091 argument, capitalize the previous word, but do not move the cursor.
7094 Toggle overwrite mode. With an explicit positive numeric argument,
7095 switches to overwrite mode. With an explicit non-positive numeric
7096 argument, switches to insert mode. This command affects only
7097 'emacs' mode; 'vi' mode does overwrite differently. Each call to
7098 'readline()' starts in insert mode.
7100 In overwrite mode, characters bound to 'self-insert' replace the
7101 text at point rather than pushing the text to the right.
7102 Characters bound to 'backward-delete-char' replace the character
7103 before point with a space.
7105 By default, this command is unbound.
7108 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
7110 32.4.4 Killing And Yanking
7111 --------------------------
7114 Kill the text from point to the end of the line.
7116 'backward-kill-line (C-x Rubout)'
7117 Kill backward to the beginning of the line.
7119 'unix-line-discard (C-u)'
7120 Kill backward from the cursor to the beginning of the current line.
7122 'kill-whole-line ()'
7123 Kill all characters on the current line, no matter where point is.
7124 By default, this is unbound.
7127 Kill from point to the end of the current word, or if between
7128 words, to the end of the next word. Word boundaries are the same
7131 'backward-kill-word (M-<DEL>)'
7132 Kill the word behind point. Word boundaries are the same as
7135 'unix-word-rubout (C-w)'
7136 Kill the word behind point, using white space as a word boundary.
7137 The killed text is saved on the kill-ring.
7139 'unix-filename-rubout ()'
7140 Kill the word behind point, using white space and the slash
7141 character as the word boundaries. The killed text is saved on the
7144 'delete-horizontal-space ()'
7145 Delete all spaces and tabs around point. By default, this is
7149 Kill the text in the current region. By default, this command is
7152 'copy-region-as-kill ()'
7153 Copy the text in the region to the kill buffer, so it can be yanked
7154 right away. By default, this command is unbound.
7156 'copy-backward-word ()'
7157 Copy the word before point to the kill buffer. The word boundaries
7158 are the same as 'backward-word'. By default, this command is
7161 'copy-forward-word ()'
7162 Copy the word following point to the kill buffer. The word
7163 boundaries are the same as 'forward-word'. By default, this
7167 Yank the top of the kill ring into the buffer at point.
7170 Rotate the kill-ring, and yank the new top. You can only do this
7171 if the prior command is 'yank' or 'yank-pop'.
7174 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
7176 32.4.5 Specifying Numeric Arguments
7177 -----------------------------------
7179 'digit-argument (M-0, M-1, ... M--)'
7180 Add this digit to the argument already accumulating, or start a new
7181 argument. 'M--' starts a negative argument.
7183 'universal-argument ()'
7184 This is another way to specify an argument. If this command is
7185 followed by one or more digits, optionally with a leading minus
7186 sign, those digits define the argument. If the command is followed
7187 by digits, executing 'universal-argument' again ends the numeric
7188 argument, but is otherwise ignored. As a special case, if this
7189 command is immediately followed by a character that is neither a
7190 digit or minus sign, the argument count for the next command is
7191 multiplied by four. The argument count is initially one, so
7192 executing this function the first time makes the argument count
7193 four, a second time makes the argument count sixteen, and so on.
7194 By default, this is not bound to a key.
7197 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
7199 32.4.6 Letting Readline Type For You
7200 ------------------------------------
7203 Attempt to perform completion on the text before point. The actual
7204 completion performed is application-specific. The default is
7205 filename completion.
7207 'possible-completions (M-?)'
7208 List the possible completions of the text before point. When
7209 displaying completions, Readline sets the number of columns used
7210 for display to the value of 'completion-display-width', the value
7211 of the environment variable 'COLUMNS', or the screen width, in that
7214 'insert-completions (M-*)'
7215 Insert all completions of the text before point that would have
7216 been generated by 'possible-completions'.
7219 Similar to 'complete', but replaces the word to be completed with a
7220 single match from the list of possible completions. Repeated
7221 execution of 'menu-complete' steps through the list of possible
7222 completions, inserting each match in turn. At the end of the list
7223 of completions, the bell is rung (subject to the setting of
7224 'bell-style') and the original text is restored. An argument of N
7225 moves N positions forward in the list of matches; a negative
7226 argument may be used to move backward through the list. This
7227 command is intended to be bound to <TAB>, but is unbound by
7230 'menu-complete-backward ()'
7231 Identical to 'menu-complete', but moves backward through the list
7232 of possible completions, as if 'menu-complete' had been given a
7235 'delete-char-or-list ()'
7236 Deletes the character under the cursor if not at the beginning or
7237 end of the line (like 'delete-char'). If at the end of the line,
7238 behaves identically to 'possible-completions'. This command is
7242 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
7244 32.4.7 Keyboard Macros
7245 ----------------------
7247 'start-kbd-macro (C-x ()'
7248 Begin saving the characters typed into the current keyboard macro.
7250 'end-kbd-macro (C-x ))'
7251 Stop saving the characters typed into the current keyboard macro
7252 and save the definition.
7254 'call-last-kbd-macro (C-x e)'
7255 Re-execute the last keyboard macro defined, by making the
7256 characters in the macro appear as if typed at the keyboard.
7259 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
7261 32.4.8 Some Miscellaneous Commands
7262 ----------------------------------
7264 're-read-init-file (C-x C-r)'
7265 Read in the contents of the INPUTRC file, and incorporate any
7266 bindings or variable assignments found there.
7269 Abort the current editing command and ring the terminal's bell
7270 (subject to the setting of 'bell-style').
7272 'do-uppercase-version (M-a, M-b, M-X, ...)'
7273 If the metafied character X is lowercase, run the command that is
7274 bound to the corresponding uppercase character.
7276 'prefix-meta (<ESC>)'
7277 Metafy the next character typed. This is for keyboards without a
7278 meta key. Typing '<ESC> f' is equivalent to typing 'M-f'.
7280 'undo (C-_ or C-x C-u)'
7281 Incremental undo, separately remembered for each line.
7284 Undo all changes made to this line. This is like executing the
7285 'undo' command enough times to get back to the beginning.
7287 'tilde-expand (M-~)'
7288 Perform tilde expansion on the current word.
7291 Set the mark to the point. If a numeric argument is supplied, the
7292 mark is set to that position.
7294 'exchange-point-and-mark (C-x C-x)'
7295 Swap the point with the mark. The current cursor position is set
7296 to the saved position, and the old cursor position is saved as the
7299 'character-search (C-])'
7300 A character is read and point is moved to the next occurrence of
7301 that character. A negative count searches for previous
7304 'character-search-backward (M-C-])'
7305 A character is read and point is moved to the previous occurrence
7306 of that character. A negative count searches for subsequent
7309 'skip-csi-sequence ()'
7310 Read enough characters to consume a multi-key sequence such as
7311 those defined for keys like Home and End. Such sequences begin
7312 with a Control Sequence Indicator (CSI), usually ESC-[. If this
7313 sequence is bound to "\e[", keys producing such sequences will have
7314 no effect unless explicitly bound to a readline command, instead of
7315 inserting stray characters into the editing buffer. This is
7316 unbound by default, but usually bound to ESC-[.
7318 'insert-comment (M-#)'
7319 Without a numeric argument, the value of the 'comment-begin'
7320 variable is inserted at the beginning of the current line. If a
7321 numeric argument is supplied, this command acts as a toggle: if the
7322 characters at the beginning of the line do not match the value of
7323 'comment-begin', the value is inserted, otherwise the characters in
7324 'comment-begin' are deleted from the beginning of the line. In
7325 either case, the line is accepted as if a newline had been typed.
7328 Print all of the functions and their key bindings to the Readline
7329 output stream. If a numeric argument is supplied, the output is
7330 formatted in such a way that it can be made part of an INPUTRC
7331 file. This command is unbound by default.
7334 Print all of the settable variables and their values to the
7335 Readline output stream. If a numeric argument is supplied, the
7336 output is formatted in such a way that it can be made part of an
7337 INPUTRC file. This command is unbound by default.
7340 Print all of the Readline key sequences bound to macros and the
7341 strings they output. If a numeric argument is supplied, the output
7342 is formatted in such a way that it can be made part of an INPUTRC
7343 file. This command is unbound by default.
7345 'emacs-editing-mode (C-e)'
7346 When in 'vi' command mode, this causes a switch to 'emacs' editing
7349 'vi-editing-mode (M-C-j)'
7350 When in 'emacs' editing mode, this causes a switch to 'vi' editing
7354 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
7356 32.5 Readline vi Mode
7357 =====================
7359 While the Readline library does not have a full set of 'vi' editing
7360 functions, it does contain enough to allow simple editing of the line.
7361 The Readline 'vi' mode behaves as specified in the POSIX standard.
7363 In order to switch interactively between 'emacs' and 'vi' editing
7364 modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi'
7365 mode and to vi-editing-mode in 'emacs' mode). The Readline default is
7368 When you enter a line in 'vi' mode, you are already placed in
7369 'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches
7370 you into 'command' mode, where you can edit the text of the line with
7371 the standard 'vi' movement keys, move to previous history lines with 'k'
7372 and subsequent lines with 'j', and so forth.
7375 File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top
7377 33 Using History Interactively
7378 ******************************
7380 This chapter describes how to use the GNU History Library interactively,
7381 from a user's standpoint. It should be considered a user's guide. For
7382 information on using the GNU History Library in your own programs, *note
7383 (history)Programming with GNU History::.
7387 * History Interaction:: What it feels like using History as a user.
7390 File: gdb.info, Node: History Interaction, Up: Using History Interactively
7392 33.1 History Expansion
7393 ======================
7395 The History library provides a history expansion feature that is similar
7396 to the history expansion provided by 'csh'. This section describes the
7397 syntax used to manipulate the history information.
7399 History expansions introduce words from the history list into the
7400 input stream, making it easy to repeat commands, insert the arguments to
7401 a previous command into the current input line, or fix errors in
7402 previous commands quickly.
7404 History expansion takes place in two parts. The first is to
7405 determine which line from the history list should be used during
7406 substitution. The second is to select portions of that line for
7407 inclusion into the current one. The line selected from the history is
7408 called the "event", and the portions of that line that are acted upon
7409 are called "words". Various "modifiers" are available to manipulate the
7410 selected words. The line is broken into words in the same fashion that
7411 Bash does, so that several words surrounded by quotes are considered one
7412 word. History expansions are introduced by the appearance of the
7413 history expansion character, which is '!' by default.
7417 * Event Designators:: How to specify which history line to use.
7418 * Word Designators:: Specifying which words are of interest.
7419 * Modifiers:: Modifying the results of substitution.
7422 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
7424 33.1.1 Event Designators
7425 ------------------------
7427 An event designator is a reference to a command line entry in the
7428 history list. Unless the reference is absolute, events are relative to
7429 the current position in the history list.
7432 Start a history substitution, except when followed by a space, tab,
7433 the end of the line, or '='.
7436 Refer to command line N.
7439 Refer to the command N lines back.
7442 Refer to the previous command. This is a synonym for '!-1'.
7445 Refer to the most recent command preceding the current position in
7446 the history list starting with STRING.
7449 Refer to the most recent command preceding the current position in
7450 the history list containing STRING. The trailing '?' may be
7451 omitted if the STRING is followed immediately by a newline.
7454 Quick Substitution. Repeat the last command, replacing STRING1
7455 with STRING2. Equivalent to '!!:s/STRING1/STRING2/'.
7458 The entire command line typed so far.
7461 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
7463 33.1.2 Word Designators
7464 -----------------------
7466 Word designators are used to select desired words from the event. A ':'
7467 separates the event specification from the word designator. It may be
7468 omitted if the word designator begins with a '^', '$', '*', '-', or '%'.
7469 Words are numbered from the beginning of the line, with the first word
7470 being denoted by 0 (zero). Words are inserted into the current line
7471 separated by single spaces.
7476 designates the preceding command. When you type this, the
7477 preceding command is repeated in toto.
7480 designates the last argument of the preceding command. This may be
7484 designates the second argument of the most recent command starting
7485 with the letters 'fi'.
7487 Here are the word designators:
7490 The '0'th word. For many applications, this is the command word.
7496 The first argument; that is, word 1.
7502 The word matched by the most recent '?STRING?' search.
7505 A range of words; '-Y' abbreviates '0-Y'.
7508 All of the words, except the '0'th. This is a synonym for '1-$'.
7509 It is not an error to use '*' if there is just one word in the
7510 event; the empty string is returned in that case.
7516 Abbreviates 'X-$' like 'X*', but omits the last word.
7518 If a word designator is supplied without an event specification, the
7519 previous command is used as the event.
7522 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
7527 After the optional word designator, you can add a sequence of one or
7528 more of the following modifiers, each preceded by a ':'.
7531 Remove a trailing pathname component, leaving only the head.
7534 Remove all leading pathname components, leaving the tail.
7537 Remove a trailing suffix of the form '.SUFFIX', leaving the
7541 Remove all but the trailing suffix.
7544 Print the new command but do not execute it.
7547 Substitute NEW for the first occurrence of OLD in the event line.
7548 Any delimiter may be used in place of '/'. The delimiter may be
7549 quoted in OLD and NEW with a single backslash. If '&' appears in
7550 NEW, it is replaced by OLD. A single backslash will quote the '&'.
7551 The final delimiter is optional if it is the last character on the
7555 Repeat the previous substitution.
7559 Cause changes to be applied over the entire event line. Used in
7560 conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.
7563 Apply the following 's' modifier once to each word in the event.
7566 File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top
7568 Appendix A In Memoriam
7569 **********************
7571 The GDB project mourns the loss of the following long-time contributors:
7574 Fred was a long-standing contributor to GDB (1991-2006), and to
7575 Free Software in general. Outside of GDB, he was known in the
7576 Amiga world for his series of Fish Disks, and the GeekGadget
7580 Michael was one of the Global Maintainers of the GDB project, with
7581 contributions recorded as early as 1996, until 2011. In addition
7582 to his day to day participation, he was a large driving force
7583 behind adding Reverse Debugging to GDB.
7585 Beyond their technical contributions to the project, they were also
7586 enjoyable members of the Free Software Community. We will miss them.
7589 File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top
7591 Appendix B Formatting Documentation
7592 ***********************************
7594 The GDB 4 release includes an already-formatted reference card, ready
7595 for printing with PostScript or Ghostscript, in the 'gdb' subdirectory
7596 of the main source directory(1). If you can use PostScript or
7597 Ghostscript with your printer, you can print the reference card
7598 immediately with 'refcard.ps'.
7600 The release also includes the source for the reference card. You can
7601 format it, using TeX, by typing:
7605 The GDB reference card is designed to print in "landscape" mode on US
7606 "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
7607 high. You will need to specify this form of printing as an option to
7608 your DVI output program.
7610 All the documentation for GDB comes as part of the machine-readable
7611 distribution. The documentation is written in Texinfo format, which is
7612 a documentation system that uses a single source file to produce both
7613 on-line information and a printed manual. You can use one of the Info
7614 formatting commands to create the on-line version of the documentation
7615 and TeX (or 'texi2roff') to typeset the printed version.
7617 GDB includes an already formatted copy of the on-line Info version of
7618 this manual in the 'gdb' subdirectory. The main Info file is
7619 'gdb-7.8.1/gdb/gdb.info', and it refers to subordinate files matching
7620 'gdb.info*' in the same directory. If necessary, you can print out
7621 these files, or read them with any editor; but they are easier to read
7622 using the 'info' subsystem in GNU Emacs or the standalone 'info'
7623 program, available as part of the GNU Texinfo distribution.
7625 If you want to format these Info files yourself, you need one of the
7626 Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'.
7628 If you have 'makeinfo' installed, and are in the top level GDB source
7629 directory ('gdb-7.8.1', in the case of version 7.8.1), you can make the
7630 Info file by typing:
7635 If you want to typeset and print copies of this manual, you need TeX,
7636 a program to print its DVI output files, and 'texinfo.tex', the Texinfo
7639 TeX is a typesetting program; it does not print files directly, but
7640 produces output files called DVI files. To print a typeset document,
7641 you need a program to print DVI files. If your system has TeX
7642 installed, chances are it has such a program. The precise command to
7643 use depends on your system; 'lpr -d' is common; another (for PostScript
7644 devices) is 'dvips'. The DVI print command may require a file name
7645 without any extension or a '.dvi' extension.
7647 TeX also requires a macro definitions file called 'texinfo.tex'.
7648 This file tells TeX how to typeset a document written in Texinfo format.
7649 On its own, TeX cannot either read or typeset a Texinfo file.
7650 'texinfo.tex' is distributed with GDB and is located in the
7651 'gdb-VERSION-NUMBER/texinfo' directory.
7653 If you have TeX and a DVI printer program installed, you can typeset
7654 and print this manual. First switch to the 'gdb' subdirectory of the
7655 main source directory (for example, to 'gdb-7.8.1/gdb') and type:
7659 Then give 'gdb.dvi' to your DVI printing program.
7661 ---------- Footnotes ----------
7663 (1) In 'gdb-7.8.1/gdb/refcard.ps' of the version 7.8.1 release.
7666 File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
7668 Appendix C Installing GDB
7669 *************************
7673 * Requirements:: Requirements for building GDB
7674 * Running Configure:: Invoking the GDB 'configure' script
7675 * Separate Objdir:: Compiling GDB in another directory
7676 * Config Names:: Specifying names for hosts and targets
7677 * Configure Options:: Summary of options for configure
7678 * System-wide configuration:: Having a system-wide init file
7681 File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
7683 C.1 Requirements for Building GDB
7684 =================================
7686 Building GDB requires various tools and packages to be available. Other
7687 packages will be used only if they are found.
7689 Tools/Packages Necessary for Building GDB
7690 =========================================
7693 GDB is written in ISO C90. It should be buildable with any working
7694 C90 compiler, e.g. GCC.
7696 Tools/Packages Optional for Building GDB
7697 ========================================
7700 GDB can use the Expat XML parsing library. This library may be
7701 included with your operating system distribution; if it is not, you
7702 can get the latest version from <http://expat.sourceforge.net>.
7703 The 'configure' script will search for this library in several
7704 standard locations; if it is installed in an unusual path, you can
7705 use the '--with-libexpat-prefix' option to specify its location.
7709 * Remote protocol memory maps (*note Memory Map Format::)
7710 * Target descriptions (*note Target Descriptions::)
7711 * Remote shared library lists (*Note Library List Format::, or
7712 alternatively *note Library List Format for SVR4 Targets::)
7713 * MS-Windows shared libraries (*note Shared Libraries::)
7714 * Traceframe info (*note Traceframe Info Format::)
7715 * Branch trace (*note Branch Trace Format::)
7718 GDB will use the 'zlib' library, if available, to read compressed
7719 debug sections. Some linkers, such as GNU gold, are capable of
7720 producing binaries with compressed debug sections. If GDB is
7721 compiled with 'zlib', it will be able to read the debug information
7724 The 'zlib' library is likely included with your operating system
7725 distribution; if it is not, you can get the latest version from
7729 GDB's features related to character sets (*note Character Sets::)
7730 require a functioning 'iconv' implementation. If you are on a GNU
7731 system, then this is provided by the GNU C Library. Some other
7732 systems also provide a working 'iconv'.
7734 If GDB is using the 'iconv' program which is installed in a
7735 non-standard place, you will need to tell GDB where to find it.
7736 This is done with '--with-iconv-bin' which specifies the directory
7737 that contains the 'iconv' program.
7739 On systems without 'iconv', you can install GNU Libiconv. If you
7740 have previously installed Libiconv, you can use the
7741 '--with-libiconv-prefix' option to configure.
7743 GDB's top-level 'configure' and 'Makefile' will arrange to build
7744 Libiconv if a directory named 'libiconv' appears in the top-most
7745 source directory. If Libiconv is built this way, and if the
7746 operating system does not provide a suitable 'iconv'
7747 implementation, then the just-built library will automatically be
7748 used by GDB. One easy way to set this up is to download GNU
7749 Libiconv, unpack it, and then rename the directory holding the
7750 Libiconv source code to 'libiconv'.
7753 File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
7755 C.2 Invoking the GDB 'configure' Script
7756 =======================================
7758 GDB comes with a 'configure' script that automates the process of
7759 preparing GDB for installation; you can then use 'make' to build the
7762 The GDB distribution includes all the source code you need for GDB in
7763 a single directory, whose name is usually composed by appending the
7764 version number to 'gdb'.
7766 For example, the GDB version 7.8.1 distribution is in the 'gdb-7.8.1'
7767 directory. That directory contains:
7769 'gdb-7.8.1/configure (and supporting files)'
7770 script for configuring GDB and all its supporting libraries
7773 the source specific to GDB itself
7776 source for the Binary File Descriptor library
7781 'gdb-7.8.1/libiberty'
7782 source for the '-liberty' free software library
7785 source for the library of opcode tables and disassemblers
7787 'gdb-7.8.1/readline'
7788 source for the GNU command-line interface
7791 source for the GNU filename pattern-matching subroutine
7794 source for the GNU memory-mapped malloc package
7796 The simplest way to configure and build GDB is to run 'configure'
7797 from the 'gdb-VERSION-NUMBER' source directory, which in this example is
7798 the 'gdb-7.8.1' directory.
7800 First switch to the 'gdb-VERSION-NUMBER' source directory if you are
7801 not already in it; then run 'configure'. Pass the identifier for the
7802 platform on which GDB will run as an argument.
7810 where HOST is an identifier such as 'sun4' or 'decstation', that
7811 identifies the platform where GDB will run. (You can often leave off
7812 HOST; 'configure' tries to guess the correct value by examining your
7815 Running 'configure HOST' and then running 'make' builds the 'bfd',
7816 'readline', 'mmalloc', and 'libiberty' libraries, then 'gdb' itself.
7817 The configured source files, and the binaries, are left in the
7818 corresponding source directories.
7820 'configure' is a Bourne-shell ('/bin/sh') script; if your system does
7821 not recognize this automatically when you run a different shell, you may
7822 need to run 'sh' on it explicitly:
7826 If you run 'configure' from a directory that contains source
7827 directories for multiple libraries or programs, such as the 'gdb-7.8.1'
7828 source directory for version 7.8.1, 'configure' creates configuration
7829 files for every directory level underneath (unless you tell it not to,
7830 with the '--norecursion' option).
7832 You should run the 'configure' script from the top directory in the
7833 source tree, the 'gdb-VERSION-NUMBER' directory. If you run 'configure'
7834 from one of the subdirectories, you will configure only that
7835 subdirectory. That is usually not what you want. In particular, if you
7836 run the first 'configure' from the 'gdb' subdirectory of the
7837 'gdb-VERSION-NUMBER' directory, you will omit the configuration of
7838 'bfd', 'readline', and other sibling directories of the 'gdb'
7839 subdirectory. This leads to build errors about missing include files
7840 such as 'bfd/bfd.h'.
7842 You can install 'gdb' anywhere; it has no hardwired paths. However,
7843 you should make sure that the shell on your path (named by the 'SHELL'
7844 environment variable) is publicly readable. Remember that GDB uses the
7845 shell to start your program--some systems refuse to let GDB debug child
7846 processes whose programs are not readable.
7849 File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
7851 C.3 Compiling GDB in Another Directory
7852 ======================================
7854 If you want to run GDB versions for several host or target machines, you
7855 need a different 'gdb' compiled for each combination of host and target.
7856 'configure' is designed to make this easy by allowing you to generate
7857 each configuration in a separate subdirectory, rather than in the source
7858 directory. If your 'make' program handles the 'VPATH' feature (GNU
7859 'make' does), running 'make' in each of these directories builds the
7860 'gdb' program specified there.
7862 To build 'gdb' in a separate directory, run 'configure' with the
7863 '--srcdir' option to specify where to find the source. (You also need
7864 to specify a path to find 'configure' itself from your working
7865 directory. If the path to 'configure' would be the same as the argument
7866 to '--srcdir', you can leave out the '--srcdir' option; it is assumed.)
7868 For example, with version 7.8.1, you can build GDB in a separate
7869 directory for a Sun 4 like this:
7874 ../gdb-7.8.1/configure sun4
7877 When 'configure' builds a configuration using a remote source
7878 directory, it creates a tree for the binaries with the same structure
7879 (and using the same names) as the tree under the source directory. In
7880 the example, you'd find the Sun 4 library 'libiberty.a' in the directory
7881 'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'.
7883 Make sure that your path to the 'configure' script has just one
7884 instance of 'gdb' in it. If your path to 'configure' looks like
7885 '../gdb-7.8.1/gdb/configure', you are configuring only one subdirectory
7886 of GDB, not the whole package. This leads to build errors about missing
7887 include files such as 'bfd/bfd.h'.
7889 One popular reason to build several GDB configurations in separate
7890 directories is to configure GDB for cross-compiling (where GDB runs on
7891 one machine--the "host"--while debugging programs that run on another
7892 machine--the "target"). You specify a cross-debugging target by giving
7893 the '--target=TARGET' option to 'configure'.
7895 When you run 'make' to build a program or library, you must run it in
7896 a configured directory--whatever directory you were in when you called
7897 'configure' (or one of its subdirectories).
7899 The 'Makefile' that 'configure' generates in each source directory
7900 also runs recursively. If you type 'make' in a source directory such as
7901 'gdb-7.8.1' (or in a separate configured directory configured with
7902 '--srcdir=DIRNAME/gdb-7.8.1'), you will build all the required
7903 libraries, and then build GDB.
7905 When you have multiple hosts or targets configured in separate
7906 directories, you can run 'make' on them in parallel (for example, if
7907 they are NFS-mounted on each of the hosts); they will not interfere with
7911 File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
7913 C.4 Specifying Names for Hosts and Targets
7914 ==========================================
7916 The specifications used for hosts and targets in the 'configure' script
7917 are based on a three-part naming scheme, but some short predefined
7918 aliases are also supported. The full naming scheme encodes three pieces
7919 of information in the following pattern:
7921 ARCHITECTURE-VENDOR-OS
7923 For example, you can use the alias 'sun4' as a HOST argument, or as
7924 the value for TARGET in a '--target=TARGET' option. The equivalent full
7925 name is 'sparc-sun-sunos4'.
7927 The 'configure' script accompanying GDB does not provide any query
7928 facility to list all supported host and target names or aliases.
7929 'configure' calls the Bourne shell script 'config.sub' to map
7930 abbreviations to full names; you can read the script, if you wish, or
7931 you can use it to test your guesses on abbreviations--for example:
7933 % sh config.sub i386-linux
7935 % sh config.sub alpha-linux
7936 alpha-unknown-linux-gnu
7937 % sh config.sub hp9k700
7939 % sh config.sub sun4
7940 sparc-sun-sunos4.1.1
7941 % sh config.sub sun3
7943 % sh config.sub i986v
7944 Invalid configuration `i986v': machine `i986v' not recognized
7946 'config.sub' is also distributed in the GDB source directory
7947 ('gdb-7.8.1', for version 7.8.1).
7950 File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
7952 C.5 'configure' Options
7953 =======================
7955 Here is a summary of the 'configure' options and arguments that are most
7956 often useful for building GDB. 'configure' also has several other
7957 options not listed here. *note (configure.info)What Configure Does::,
7958 for a full explanation of 'configure'.
7964 [--norecursion] [--rm]
7968 You may introduce options with a single '-' rather than '--' if you
7969 prefer; but you may abbreviate option names if you use '--'.
7972 Display a quick summary of how to invoke 'configure'.
7975 Configure the source to install programs and files under directory
7979 Configure the source to install programs under directory 'DIR'.
7982 *Warning: using this option requires GNU 'make', or another 'make'
7983 that implements the 'VPATH' feature.*
7984 Use this option to make configurations in directories separate from
7985 the GDB source directories. Among other things, you can use this
7986 to build (or maintain) several configurations simultaneously, in
7987 separate directories. 'configure' writes configuration-specific
7988 files in the current directory, but arranges for them to use the
7989 source in the directory DIRNAME. 'configure' creates directories
7990 under the working directory in parallel to the source directories
7994 Configure only the directory level where 'configure' is executed;
7995 do not propagate configuration to subdirectories.
7998 Configure GDB for cross-debugging programs running on the specified
7999 TARGET. Without this option, GDB is configured to debug programs
8000 that run on the same machine (HOST) as GDB itself.
8002 There is no convenient way to generate a list of all available
8006 Configure GDB to run on the specified HOST.
8008 There is no convenient way to generate a list of all available
8011 There are many other options available as well, but they are
8012 generally needed for special purposes only.
8015 File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
8017 C.6 System-wide configuration and settings
8018 ==========================================
8020 GDB can be configured to have a system-wide init file; this file will be
8021 read and executed at startup (*note What GDB does during startup:
8024 Here is the corresponding configure option:
8026 '--with-system-gdbinit=FILE'
8027 Specify that the default location of the system-wide init file is
8030 If GDB has been configured with the option '--prefix=$prefix', it may
8031 be subject to relocation. Two possible cases:
8033 * If the default location of this init file contains '$prefix', it
8034 will be subject to relocation. Suppose that the configure options
8035 are '--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
8036 if GDB is moved from '$prefix' to '$install', the system init file
8037 is looked for as '$install/etc/gdbinit' instead of
8038 '$prefix/etc/gdbinit'.
8040 * By contrast, if the default location does not contain the prefix,
8041 it will not be relocated. E.g. if GDB has been configured with
8042 '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
8043 then GDB will always look for '/usr/share/gdb/gdbinit', wherever
8046 If the configured location of the system-wide init file (as given by
8047 the '--with-system-gdbinit' option at configure time) is in the
8048 data-directory (as specified by '--with-gdb-datadir' at configure time)
8049 or in one of its subdirectories, then GDB will look for the system-wide
8050 init file in the directory specified by the '--data-directory'
8051 command-line option. Note that the system-wide init file is only read
8052 once, during GDB initialization. If the data-directory is changed after
8053 GDB has started with the 'set data-directory' command, the file will not
8058 * System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
8061 File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration
8063 C.6.1 Installed System-wide Configuration Scripts
8064 -------------------------------------------------
8066 The 'system-gdbinit' directory, located inside the data-directory (as
8067 specified by '--with-gdb-datadir' at configure time) contains a number
8068 of scripts which can be used as system-wide init files. To
8069 automatically source those scripts at startup, GDB should be configured
8070 with '--with-system-gdbinit'. Otherwise, any user should be able to
8071 source them by hand as needed.
8073 The following scripts are currently available:
8075 * 'elinos.py' This script is useful when debugging a program on an
8076 ELinOS target. It takes advantage of the environment variables
8077 defined in a standard ELinOS environment in order to determine the
8078 location of the system shared libraries, and then sets the
8079 'solib-absolute-prefix' and 'solib-search-path' variables
8082 * 'wrs-linux.py' This script is useful when debugging a program on a
8083 target running Wind River Linux. It expects the 'ENV_PREFIX' to be
8084 set to the host-side sysroot used by the target system.
8087 File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
8089 Appendix D Maintenance Commands
8090 *******************************
8092 In addition to commands intended for GDB users, GDB includes a number of
8093 commands intended for GDB developers, that are not documented elsewhere
8094 in this manual. These commands are provided here for reference. (For
8095 commands that turn on debugging messages, see *note Debugging Output::.)
8097 'maint agent [-at LOCATION,] EXPRESSION'
8098 'maint agent-eval [-at LOCATION,] EXPRESSION'
8099 Translate the given EXPRESSION into remote agent bytecodes. This
8100 command is useful for debugging the Agent Expression mechanism
8101 (*note Agent Expressions::). The 'agent' version produces an
8102 expression useful for data collection, such as by tracepoints,
8103 while 'maint agent-eval' produces an expression that evaluates
8104 directly to a result. For instance, a collection expression for
8105 'globa + globb' will include bytecodes to record four bytes of
8106 memory at each of the addresses of 'globa' and 'globb', while
8107 discarding the result of the addition, while an evaluation
8108 expression will do the addition and return the sum. If '-at' is
8109 given, generate remote agent bytecode for LOCATION. If not,
8110 generate remote agent bytecode for current frame PC address.
8112 'maint agent-printf FORMAT,EXPR,...'
8113 Translate the given format string and list of argument expressions
8114 into remote agent bytecodes and display them as a disassembled
8115 list. This command is useful for debugging the agent version of
8116 dynamic printf (*note Dynamic Printf::).
8118 'maint info breakpoints'
8119 Using the same format as 'info breakpoints', display both the
8120 breakpoints you've set explicitly, and those GDB is using for
8121 internal purposes. Internal breakpoints are shown with negative
8122 breakpoint numbers. The type column identifies what kind of
8123 breakpoint is shown:
8126 Normal, explicitly set breakpoint.
8129 Normal, explicitly set watchpoint.
8132 Internal breakpoint, used to handle correctly stepping through
8136 Internal breakpoint at the target of a 'longjmp'.
8139 Temporary internal breakpoint used by the GDB 'until' command.
8142 Temporary internal breakpoint used by the GDB 'finish'
8146 Shared library events.
8149 This prints information about each 'bfd' object that is known to
8150 GDB. *Note BFD: (bfd)Top.
8152 'set displaced-stepping'
8153 'show displaced-stepping'
8154 Control whether or not GDB will do "displaced stepping" if the
8155 target supports it. Displaced stepping is a way to single-step
8156 over breakpoints without removing them from the inferior, by
8157 executing an out-of-line copy of the instruction that was
8158 originally at the breakpoint location. It is also known as
8159 out-of-line single-stepping.
8161 'set displaced-stepping on'
8162 If the target architecture supports it, GDB will use displaced
8163 stepping to step over breakpoints.
8165 'set displaced-stepping off'
8166 GDB will not use displaced stepping to step over breakpoints,
8167 even if such is supported by the target architecture.
8169 'set displaced-stepping auto'
8170 This is the default mode. GDB will use displaced stepping
8171 only if non-stop mode is active (*note Non-Stop Mode::) and
8172 the target architecture supports displaced stepping.
8174 'maint check-psymtabs'
8175 Check the consistency of currently expanded psymtabs versus
8176 symtabs. Use this to check, for example, whether a symbol is in
8177 one but not the other.
8179 'maint check-symtabs'
8180 Check the consistency of currently expanded symtabs.
8182 'maint expand-symtabs [REGEXP]'
8183 Expand symbol tables. If REGEXP is specified, only expand symbol
8184 tables for file names matching REGEXP.
8186 'maint cplus first_component NAME'
8187 Print the first C++ class/namespace component of NAME.
8189 'maint cplus namespace'
8190 Print the list of possible C++ namespaces.
8192 'maint demangle NAME'
8193 Demangle a C++ or Objective-C mangled NAME.
8195 'maint deprecate COMMAND [REPLACEMENT]'
8196 'maint undeprecate COMMAND'
8197 Deprecate or undeprecate the named COMMAND. Deprecated commands
8198 cause GDB to issue a warning when you use them. The optional
8199 argument REPLACEMENT says which newer command should be used in
8200 favor of the deprecated one; if it is given, GDB will mention the
8201 replacement as part of the warning.
8204 Cause a fatal signal in the debugger and force it to dump its core.
8205 This is supported only on systems which support aborting a program
8206 with the 'SIGQUIT' signal.
8208 'maint internal-error [MESSAGE-TEXT]'
8209 'maint internal-warning [MESSAGE-TEXT]'
8210 Cause GDB to call the internal function 'internal_error' or
8211 'internal_warning' and hence behave as though an internal error or
8212 internal warning has been detected. In addition to reporting the
8213 internal problem, these functions give the user the opportunity to
8214 either quit GDB or create a core file of the current GDB session.
8216 These commands take an optional parameter MESSAGE-TEXT that is used
8217 as the text of the error or warning message.
8219 Here's an example of using 'internal-error':
8221 (gdb) maint internal-error testing, 1, 2
8222 .../maint.c:121: internal-error: testing, 1, 2
8223 A problem internal to GDB has been detected. Further
8224 debugging may prove unreliable.
8225 Quit this debugging session? (y or n) n
8226 Create a core file? (y or n) n
8229 'maint set internal-error ACTION [ask|yes|no]'
8230 'maint show internal-error ACTION'
8231 'maint set internal-warning ACTION [ask|yes|no]'
8232 'maint show internal-warning ACTION'
8233 When GDB reports an internal problem (error or warning) it gives
8234 the user the opportunity to both quit GDB and create a core file of
8235 the current GDB session. These commands let you override the
8236 default behaviour for each particular ACTION, described in the
8240 You can specify that GDB should always (yes) or never (no)
8241 quit. The default is to ask the user what to do.
8244 You can specify that GDB should always (yes) or never (no)
8245 create a core file. The default is to ask the user what to
8249 If GDB is talking to an inferior via the serial protocol, then this
8250 command sends the string TEXT to the inferior, and displays the
8251 response packet. GDB supplies the initial '$' character, the
8252 terminating '#' character, and the checksum.
8254 'maint print architecture [FILE]'
8255 Print the entire architecture configuration. The optional argument
8256 FILE names the file where the output goes.
8258 'maint print c-tdesc'
8259 Print the current target description (*note Target Descriptions::)
8260 as a C source file. The created source file can be used in GDB
8261 when an XML parser is not available to parse the description.
8263 'maint print dummy-frames'
8264 Prints the contents of GDB's internal dummy-frame stack.
8268 (gdb) print add(2,3)
8269 Breakpoint 2, add (a=2, b=3) at ...
8271 The program being debugged stopped while in a function called from GDB.
8273 (gdb) maint print dummy-frames
8274 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
8275 top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
8276 call_lo=0x01014000 call_hi=0x01014001
8279 Takes an optional file parameter.
8281 'maint print registers [FILE]'
8282 'maint print raw-registers [FILE]'
8283 'maint print cooked-registers [FILE]'
8284 'maint print register-groups [FILE]'
8285 'maint print remote-registers [FILE]'
8286 Print GDB's internal register data structures.
8288 The command 'maint print raw-registers' includes the contents of
8289 the raw register cache; the command 'maint print cooked-registers'
8290 includes the (cooked) value of all registers, including registers
8291 which aren't available on the target nor visible to user; the
8292 command 'maint print register-groups' includes the groups that each
8293 register is a member of; and the command 'maint print
8294 remote-registers' includes the remote target's register numbers and
8295 offsets in the 'G' packets.
8297 These commands take an optional parameter, a file name to which to
8298 write the information.
8300 'maint print reggroups [FILE]'
8301 Print GDB's internal register group data structures. The optional
8302 argument FILE tells to what file to write the information.
8304 The register groups info looks like this:
8306 (gdb) maint print reggroups
8317 This command forces GDB to flush its internal register cache.
8319 'maint print objfiles [REGEXP]'
8320 Print a dump of all known object files. If REGEXP is specified,
8321 only print object files whose names match REGEXP. For each object
8322 file, this command prints its name, address in memory, and all of
8323 its psymtabs and symtabs.
8325 'maint print section-scripts [REGEXP]'
8326 Print a dump of scripts specified in the '.debug_gdb_section'
8327 section. If REGEXP is specified, only print scripts loaded by
8328 object files matching REGEXP. For each script, this command prints
8329 its name as specified in the objfile, and the full path if known.
8330 *Note dotdebug_gdb_scripts section::.
8332 'maint print statistics'
8333 This command prints, for each object file in the program, various
8334 data about that object file followed by the byte cache ("bcache")
8335 statistics for the object file. The objfile data includes the
8336 number of minimal, partial, full, and stabs symbols, the number of
8337 types defined by the objfile, the number of as yet unexpanded psym
8338 tables, the number of line tables and string tables, and the amount
8339 of memory used by the various tables. The bcache statistics
8340 include the counts, sizes, and counts of duplicates of all and
8341 unique objects, max, average, and median entry size, total memory
8342 used and its overhead and savings, and various measures of the hash
8343 table size and chain lengths.
8345 'maint print target-stack'
8346 A "target" is an interface between the debugger and a particular
8347 kind of file or process. Targets can be stacked in "strata", so
8348 that more than one target can potentially respond to a request. In
8349 particular, memory accesses will walk down the stack of targets
8350 until they find a target that is interested in handling that
8353 This command prints a short description of each layer that was
8354 pushed on the "target stack", starting from the top layer down to
8357 'maint print type EXPR'
8358 Print the type chain for a type specified by EXPR. The argument
8359 can be either a type name or a symbol. If it is a symbol, the type
8360 of that symbol is described. The type chain produced by this
8361 command is a recursive definition of the data type as stored in
8362 GDB's data structures, including its flags and contained types.
8364 'maint set dwarf2 always-disassemble'
8365 'maint show dwarf2 always-disassemble'
8366 Control the behavior of 'info address' when using DWARF debugging
8369 The default is 'off', which means that GDB should try to describe a
8370 variable's location in an easily readable format. When 'on', GDB
8371 will instead display the DWARF location expression in an
8372 assembly-like format. Note that some locations are too complex for
8373 GDB to describe simply; in this case you will always see the
8376 Here is an example of the resulting disassembly:
8378 (gdb) info addr argc
8379 Symbol "argc" is a complex DWARF expression:
8382 For more information on these expressions, see the DWARF standard
8383 (http://www.dwarfstd.org/).
8385 'maint set dwarf2 max-cache-age'
8386 'maint show dwarf2 max-cache-age'
8387 Control the DWARF 2 compilation unit cache.
8389 In object files with inter-compilation-unit references, such as
8390 those produced by the GCC option '-feliminate-dwarf2-dups', the
8391 DWARF 2 reader needs to frequently refer to previously read
8392 compilation units. This setting controls how long a compilation
8393 unit will remain in the cache if it is not referenced. A higher
8394 limit means that cached compilation units will be stored in memory
8395 longer, and more total memory will be used. Setting it to zero
8396 disables caching, which will slow down GDB startup, but reduce
8400 'maint show profile'
8401 Control profiling of GDB.
8403 Profiling will be disabled until you use the 'maint set profile'
8404 command to enable it. When you enable profiling, the system will
8405 begin collecting timing and execution count data; when you disable
8406 profiling or exit GDB, the results will be written to a log file.
8407 Remember that if you use profiling, GDB will overwrite the
8408 profiling log file (often called 'gmon.out'). If you have a record
8409 of important profiling data in a 'gmon.out' file, be sure to move
8410 it to a safe location.
8412 Configuring with '--enable-profiling' arranges for GDB to be
8413 compiled with the '-pg' compiler option.
8415 'maint set show-debug-regs'
8416 'maint show show-debug-regs'
8417 Control whether to show variables that mirror the hardware debug
8418 registers. Use 'on' to enable, 'off' to disable. If enabled, the
8419 debug registers values are shown when GDB inserts or removes a
8420 hardware breakpoint or watchpoint, and when the inferior triggers a
8421 hardware-assisted breakpoint or watchpoint.
8423 'maint set show-all-tib'
8424 'maint show show-all-tib'
8425 Control whether to show all non zero areas within a 1k block
8426 starting at thread local base, when using the 'info w32
8427 thread-information-block' command.
8429 'maint set target-async'
8430 'maint show target-async'
8431 This controls whether GDB targets operate in synchronous or
8432 asynchronous mode (*note Background Execution::). Normally the
8433 default is asynchronous, if it is available; but this can be
8434 changed to more easily debug problems occurring only in synchronous
8437 'maint set per-command'
8438 'maint show per-command'
8440 GDB can display the resources used by each command. This is useful
8441 in debugging performance problems.
8443 'maint set per-command space [on|off]'
8444 'maint show per-command space'
8445 Enable or disable the printing of the memory used by GDB for
8446 each command. If enabled, GDB will display how much memory
8447 each command took, following the command's own output. This
8448 can also be requested by invoking GDB with the '--statistics'
8449 command-line switch (*note Mode Options::).
8451 'maint set per-command time [on|off]'
8452 'maint show per-command time'
8453 Enable or disable the printing of the execution time of GDB
8454 for each command. If enabled, GDB will display how much time
8455 it took to execute each command, following the command's own
8456 output. Both CPU time and wallclock time are printed.
8457 Printing both is useful when trying to determine whether the
8458 cost is CPU or, e.g., disk/network latency. Note that the CPU
8459 time printed is for GDB only, it does not include the
8460 execution time of the inferior because there's no mechanism
8461 currently to compute how much time was spent by GDB and how
8462 much time was spent by the program been debugged. This can
8463 also be requested by invoking GDB with the '--statistics'
8464 command-line switch (*note Mode Options::).
8466 'maint set per-command symtab [on|off]'
8467 'maint show per-command symtab'
8468 Enable or disable the printing of basic symbol table
8469 statistics for each command. If enabled, GDB will display the
8470 following information:
8472 a. number of symbol tables
8473 b. number of primary symbol tables
8474 c. number of blocks in the blockvector
8477 An alias for 'maint set per-command space'. A non-zero value
8478 enables it, zero disables it.
8481 An alias for 'maint set per-command time'. A non-zero value
8482 enables it, zero disables it.
8484 'maint translate-address [SECTION] ADDR'
8485 Find the symbol stored at the location specified by the address
8486 ADDR and an optional section name SECTION. If found, GDB prints
8487 the name of the closest symbol and an offset from the symbol's
8488 location to the specified address. This is similar to the 'info
8489 address' command (*note Symbols::), except that this command also
8490 allows to find symbols in other sections.
8492 If section was not specified, the section in which the symbol was
8493 found is also printed. For dynamically linked executables, the
8494 name of executable or shared library containing the symbol is
8497 The following command is useful for non-interactive invocations of
8498 GDB, such as in the test suite.
8501 Set the maximum number of seconds GDB will wait for the target
8502 operation to finish. If this time expires, GDB reports and error
8503 and the command is aborted.
8506 Show the current setting of the target wait timeout.
8509 File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
8511 Appendix E GDB Remote Serial Protocol
8512 *************************************
8518 * Stop Reply Packets::
8519 * General Query Packets::
8520 * Architecture-Specific Protocol Details::
8521 * Tracepoint Packets::
8522 * Host I/O Packets::
8524 * Notification Packets::
8526 * Packet Acknowledgment::
8528 * File-I/O Remote Protocol Extension::
8529 * Library List Format::
8530 * Library List Format for SVR4 Targets::
8531 * Memory Map Format::
8532 * Thread List Format::
8533 * Traceframe Info Format::
8534 * Branch Trace Format::
8537 File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
8542 There may be occasions when you need to know something about the
8543 protocol--for example, if there is only one serial port to your target
8544 machine, you might want your program to do something special if it
8545 recognizes a packet meant for GDB.
8547 In the examples below, '->' and '<-' are used to indicate transmitted
8548 and received data, respectively.
8550 All GDB commands and responses (other than acknowledgments and
8551 notifications, see *note Notification Packets::) are sent as a PACKET.
8552 A PACKET is introduced with the character '$', the actual PACKET-DATA,
8553 and the terminating character '#' followed by a two-digit CHECKSUM:
8555 $PACKET-DATA#CHECKSUM
8557 The two-digit CHECKSUM is computed as the modulo 256 sum of all
8558 characters between the leading '$' and the trailing '#' (an eight bit
8561 Implementors should note that prior to GDB 5.0 the protocol
8562 specification also included an optional two-digit SEQUENCE-ID:
8564 $SEQUENCE-ID:PACKET-DATA#CHECKSUM
8566 That SEQUENCE-ID was appended to the acknowledgment. GDB has never
8567 output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must
8568 not accept SEQUENCE-ID.
8570 When either the host or the target machine receives a packet, the
8571 first response expected is an acknowledgment: either '+' (to indicate
8572 the package was received correctly) or '-' (to request retransmission):
8574 -> $PACKET-DATA#CHECKSUM
8577 The '+'/'-' acknowledgments can be disabled once a connection is
8578 established. *Note Packet Acknowledgment::, for details.
8580 The host (GDB) sends COMMANDs, and the target (the debugging stub
8581 incorporated in your program) sends a RESPONSE. In the case of step and
8582 continue COMMANDs, the response is only sent when the operation has
8583 completed, and the target has again stopped all threads in all attached
8584 processes. This is the default all-stop mode behavior, but the remote
8585 protocol also supports GDB's non-stop execution mode; see *note Remote
8586 Non-Stop::, for details.
8588 PACKET-DATA consists of a sequence of characters with the exception
8589 of '#' and '$' (see 'X' packet for additional exceptions).
8591 Fields within the packet should be separated using ',' ';' or ':'.
8592 Except where otherwise noted all numbers are represented in HEX with
8593 leading zeros suppressed.
8595 Implementors should note that prior to GDB 5.0, the character ':'
8596 could not appear as the third character in a packet (as it would
8597 potentially conflict with the SEQUENCE-ID).
8599 Binary data in most packets is encoded either as two hexadecimal
8600 digits per byte of binary data. This allowed the traditional remote
8601 protocol to work over connections which were only seven-bit clean. Some
8602 packets designed more recently assume an eight-bit clean connection, and
8603 use a more efficient encoding to send and receive binary data.
8605 The binary data representation uses '7d' (ASCII '}') as an escape
8606 character. Any escaped byte is transmitted as the escape character
8607 followed by the original character XORed with '0x20'. For example, the
8608 byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'. The
8609 bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}')
8610 must always be escaped. Responses sent by the stub must also escape
8611 '0x2a' (ASCII '*'), so that it is not interpreted as the start of a
8612 run-length encoded sequence (described next).
8614 Response DATA can be run-length encoded to save space. Run-length
8615 encoding replaces runs of identical characters with one instance of the
8616 repeated character, followed by a '*' and a repeat count. The repeat
8617 count is itself sent encoded, to avoid binary characters in DATA: a
8618 value of N is sent as 'N+29'. For a repeat count greater or equal to 3,
8619 this produces a printable ASCII character, e.g. a space (ASCII code 32)
8620 for a repeat count of 3. (This is because run-length encoding starts to
8621 win for counts 3 or more.) Thus, for example, '0* ' is a run-length
8622 encoding of "0000": the space character after '*' means repeat the
8623 leading '0' '32 - 29 = 3' more times.
8625 The printable characters '#' and '$' or with a numeric value greater
8626 than 126 must not be used. Runs of six repeats ('#') or seven repeats
8627 ('$') can be expanded using a repeat count of only five ('"'). For
8628 example, '00000000' can be encoded as '0*"00'.
8630 The error response returned for some packets includes a two character
8631 error number. That number is not well defined.
8633 For any COMMAND not supported by the stub, an empty response ('$#00')
8634 should be returned. That way it is possible to extend the protocol. A
8635 newer GDB can tell if a packet is supported based on that response.
8637 At a minimum, a stub is required to support the 'g' and 'G' commands
8638 for register access, and the 'm' and 'M' commands for memory access.
8639 Stubs that only control single-threaded targets can implement run
8640 control with the 'c' (continue), and 's' (step) commands. Stubs that
8641 support multi-threading targets should support the 'vCont' command. All
8642 other commands are optional.
8645 File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
8650 The following table provides a complete list of all currently defined
8651 COMMANDs and their corresponding response DATA. *Note File-I/O Remote
8652 Protocol Extension::, for details about the File I/O extension of the
8655 Each packet's description has a template showing the packet's overall
8656 syntax, followed by an explanation of the packet's meaning. We include
8657 spaces in some of the templates for clarity; these are not part of the
8658 packet's syntax. No GDB packet uses spaces to separate its components.
8659 For example, a template like 'foo BAR BAZ' describes a packet beginning
8660 with the three ASCII bytes 'foo', followed by a BAR, followed directly
8661 by a BAZ. GDB does not transmit a space character between the 'foo' and
8662 the BAR, or between the BAR and the BAZ.
8664 Several packets and replies include a THREAD-ID field to identify a
8665 thread. Normally these are positive numbers with a target-specific
8666 interpretation, formatted as big-endian hex strings. A THREAD-ID can
8667 also be a literal '-1' to indicate all threads, or '0' to pick any
8670 In addition, the remote protocol supports a multiprocess feature in
8671 which the THREAD-ID syntax is extended to optionally include both
8672 process and thread ID fields, as 'pPID.TID'. The PID (process) and TID
8673 (thread) components each have the format described above: a positive
8674 number with target-specific interpretation formatted as a big-endian hex
8675 string, literal '-1' to indicate all processes or threads
8676 (respectively), or '0' to indicate an arbitrary process or thread.
8677 Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is
8678 an error to specify all processes but a specific thread, such as
8679 'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and
8680 replies explicitly documented to include a process ID, rather than a
8683 The multiprocess THREAD-ID syntax extensions are only used if both
8684 GDB and the stub report support for the 'multiprocess' feature using
8685 'qSupported'. *Note multiprocess extensions::, for more information.
8687 Note that all packet forms beginning with an upper- or lower-case
8688 letter, other than those described here, are reserved for future use.
8690 Here are the packet descriptions.
8693 Enable extended mode. In extended mode, the remote server is made
8694 persistent. The 'R' packet is used to restart the program being
8699 The remote target both supports and has enabled extended mode.
8702 Indicate the reason the target halted. The reply is the same as
8703 for step and continue. This packet has a special interpretation
8704 when the target is in non-stop mode; see *note Remote Non-Stop::.
8706 Reply: *Note Stop Reply Packets::, for the reply specifications.
8708 'A ARGLEN,ARGNUM,ARG,...'
8709 Initialized 'argv[]' array passed into program. ARGLEN specifies
8710 the number of bytes in the hex encoded byte stream ARG. See
8711 'gdbserver' for more details.
8715 The arguments were set.
8720 (Don't use this packet; its behavior is not well-defined.) Change
8721 the serial line speed to BAUD.
8723 JTC: _When does the transport layer state change? When it's
8724 received, or after the ACK is transmitted. In either case, there
8725 are problems if the command or the acknowledgment packet is
8728 Stan: _If people really wanted to add something like this, and get
8729 it working for the first time, they ought to modify ser-unix.c to
8730 send some kind of out-of-band message to a specially-setup stub and
8731 have the switch happen "in between" packets, so that from remote
8732 protocol's point of view, nothing actually happened._
8735 Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR.
8737 Don't use this packet. Use the 'Z' and 'z' packets instead (*note
8738 insert breakpoint or watchpoint packet::).
8741 Backward continue. Execute the target system in reverse. No
8742 parameter. *Note Reverse Execution::, for more information.
8744 Reply: *Note Stop Reply Packets::, for the reply specifications.
8747 Backward single step. Execute one instruction in reverse. No
8748 parameter. *Note Reverse Execution::, for more information.
8750 Reply: *Note Stop Reply Packets::, for the reply specifications.
8753 Continue at ADDR, which is the address to resume. If ADDR is
8754 omitted, resume at current address.
8756 This packet is deprecated for multi-threading support. *Note vCont
8759 Reply: *Note Stop Reply Packets::, for the reply specifications.
8762 Continue with signal SIG (hex signal number). If ';ADDR' is
8763 omitted, resume at same address.
8765 This packet is deprecated for multi-threading support. *Note vCont
8768 Reply: *Note Stop Reply Packets::, for the reply specifications.
8773 Don't use this packet; instead, define a general set packet (*note
8774 General Query Packets::).
8778 The first form of the packet is used to detach GDB from the remote
8779 system. It is sent to the remote target before GDB disconnects via
8780 the 'detach' command.
8782 The second form, including a process ID, is used when multiprocess
8783 protocol extensions are enabled (*note multiprocess extensions::),
8784 to detach only a specific process. The PID is specified as a
8785 big-endian hex string.
8794 A reply from GDB to an 'F' packet sent by the target. This is part
8795 of the File-I/O protocol extension. *Note File-I/O Remote Protocol
8796 Extension::, for the specification.
8799 Read general registers.
8803 Each byte of register data is described by two hex digits.
8804 The bytes with the register are transmitted in target byte
8805 order. The size of each register and their position within
8806 the 'g' packet are determined by the GDB internal gdbarch
8807 functions 'DEPRECATED_REGISTER_RAW_SIZE' and
8808 'gdbarch_register_name'. The specification of several
8809 standard 'g' packets is specified below.
8811 When reading registers from a trace frame (*note Using the
8812 Collected Data: Analyze Collected Data.), the stub may also
8813 return a string of literal 'x''s in place of the register data
8814 digits, to indicate that the corresponding register has not
8815 been collected, thus its value is unavailable. For example,
8816 for an architecture with 4 registers of 4 bytes each, the
8817 following reply indicates to GDB that registers 0 and 2 have
8818 not been collected, while registers 1 and 3 have been
8819 collected, and both have zero value:
8822 <- xxxxxxxx00000000xxxxxxxx00000000
8828 Write general registers. *Note read registers packet::, for a
8829 description of the XX... data.
8838 Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.).
8839 Depending on the operation to be performed, OP should be 'c' for
8840 step and continue operations (note that this is deprecated,
8841 supporting the 'vCont' command is a better option), and 'g' for
8842 other operations. The thread designator THREAD-ID has the format
8843 and interpretation described in *note thread-id syntax::.
8852 Step the remote target by a single clock cycle. If ',NNN' is
8853 present, cycle step NNN cycles. If ADDR is present, cycle step
8854 starting at that address.
8857 Signal, then cycle step. *Note step with signal packet::. *Note
8858 cycle step packet::.
8863 The exact effect of this packet is not specified.
8865 For a bare-metal target, it may power cycle or reset the target
8866 system. For that reason, the 'k' packet has no reply.
8868 For a single-process target, it may kill that process if possible.
8870 A multiple-process target may choose to kill just one process, or
8871 all that are under GDB's control. For more precise control, use
8872 the vKill packet (*note vKill packet::).
8874 If the target system immediately closes the connection in response
8875 to 'k', GDB does not consider the lack of packet acknowledgment to
8876 be an error, and assumes the kill was successful.
8878 If connected using 'target extended-remote', and the target does
8879 not close the connection in response to a kill request, GDB probes
8880 the target state as if a new connection was opened (*note ?
8884 Read LENGTH bytes of memory starting at address ADDR. Note that
8885 ADDR may not be aligned to any particular boundary.
8887 The stub need not use any particular size or alignment when
8888 gathering data from memory for the response; even if ADDR is
8889 word-aligned and LENGTH is a multiple of the word size, the stub is
8890 free to use byte accesses, or not. For this reason, this packet
8891 may not be suitable for accessing memory-mapped I/O devices.
8895 Memory contents; each byte is transmitted as a two-digit
8896 hexadecimal number. The reply may contain fewer bytes than
8897 requested if the server was able to read only part of the
8902 'M ADDR,LENGTH:XX...'
8903 Write LENGTH bytes of memory starting at address ADDR. The data is
8904 given by XX...; each byte is transmitted as a two-digit hexadecimal
8911 for an error (this includes the case where only part of the
8915 Read the value of register N; N is in hex. *Note read registers
8916 packet::, for a description of how the returned register value is
8921 the register's value
8925 Indicating an unrecognized QUERY.
8928 Write register N... with value R.... The register number N is in
8929 hexadecimal, and R... contains two hex digits for each byte in the
8930 register (target byte order).
8940 General query ('q') and set ('Q'). These packets are described
8941 fully in *note General Query Packets::.
8944 Reset the entire system.
8946 Don't use this packet; use the 'R' packet instead.
8949 Restart the program being debugged. The XX, while needed, is
8950 ignored. This packet is only available in extended mode (*note
8953 The 'R' packet has no reply.
8956 Single step, resuming at ADDR. If ADDR is omitted, resume at same
8959 This packet is deprecated for multi-threading support. *Note vCont
8962 Reply: *Note Stop Reply Packets::, for the reply specifications.
8965 Step with signal. This is analogous to the 'C' packet, but
8966 requests a single-step, rather than a normal resumption of
8969 This packet is deprecated for multi-threading support. *Note vCont
8972 Reply: *Note Stop Reply Packets::, for the reply specifications.
8975 Search backwards starting at address ADDR for a match with pattern
8976 PP and mask MM, both of which are are 4 byte long. There must be
8977 at least 3 digits in ADDR.
8980 Find out if the thread THREAD-ID is alive. *Note thread-id
8985 thread is still alive
8990 Packets starting with 'v' are identified by a multi-letter name, up
8991 to the first ';' or '?' (or the end of the packet).
8994 Attach to a new process with the specified process ID PID. The
8995 process ID is a hexadecimal integer identifying the process. In
8996 all-stop mode, all threads in the attached process are stopped; in
8997 non-stop mode, it may be attached without being stopped if that is
8998 supported by the target.
9000 This packet is only available in extended mode (*note extended
9007 for success in all-stop mode (*note Stop Reply Packets::)
9009 for success in non-stop mode (*note Remote Non-Stop::)
9011 'vCont[;ACTION[:THREAD-ID]]...'
9012 Resume the inferior, specifying different actions for each thread.
9013 If an action is specified with no THREAD-ID, then it is applied to
9014 any threads that don't have a specific action specified; if no
9015 default action is specified then other threads should remain
9016 stopped in all-stop mode and in their current state in non-stop
9017 mode. Specifying multiple default actions is an error; specifying
9018 no actions is also an error. Thread IDs are specified using the
9019 syntax described in *note thread-id syntax::.
9021 Currently supported actions are:
9026 Continue with signal SIG. The signal SIG should be two hex
9031 Step with signal SIG. The signal SIG should be two hex
9036 Step once, and then keep stepping as long as the thread stops
9037 at addresses between START (inclusive) and END (exclusive).
9038 The remote stub reports a stop reply when either the thread
9039 goes out of the range or is stopped due to an unrelated
9040 reason, such as hitting a breakpoint. *Note range stepping::.
9042 If the range is empty (START == END), then the action becomes
9043 equivalent to the 's' action. In other words, single-step
9044 once, and report the stop (even if the stepped instruction
9047 (A stop reply may be sent at any point even if the PC is still
9048 within the stepping range; for example, it is valid to
9049 implement this packet in a degenerate way as a single
9050 instruction step operation.)
9052 The optional argument ADDR normally associated with the 'c', 'C',
9053 's', and 'S' packets is not supported in 'vCont'.
9055 The 't' action is only relevant in non-stop mode (*note Remote
9056 Non-Stop::) and may be ignored by the stub otherwise. A stop reply
9057 should be generated for any affected thread not already stopped.
9058 When a thread is stopped by means of a 't' action, the
9059 corresponding stop reply should indicate that the thread has
9060 stopped with signal '0', regardless of whether the target uses some
9061 other signal as an implementation detail.
9063 The stub must support 'vCont' if it reports support for
9064 multiprocess extensions (*note multiprocess extensions::). Note
9065 that in this case 'vCont' actions can be specified to apply to all
9066 threads in a process by using the 'pPID.-1' form of the THREAD-ID.
9068 Reply: *Note Stop Reply Packets::, for the reply specifications.
9071 Request a list of actions supported by the 'vCont' packet.
9075 The 'vCont' packet is supported. Each ACTION is a supported
9076 command in the 'vCont' packet.
9078 The 'vCont' packet is not supported.
9080 'vFile:OPERATION:PARAMETER...'
9081 Perform a file operation on the target system. For details, see
9082 *note Host I/O Packets::.
9084 'vFlashErase:ADDR,LENGTH'
9085 Direct the stub to erase LENGTH bytes of flash starting at ADDR.
9086 The region may enclose any number of flash blocks, but its start
9087 and end must fall on block boundaries, as indicated by the flash
9088 block size appearing in the memory map (*note Memory Map Format::).
9089 GDB groups flash memory programming operations together, and sends
9090 a 'vFlashDone' request after each group; the stub is allowed to
9091 delay erase operation until the 'vFlashDone' packet is received.
9099 'vFlashWrite:ADDR:XX...'
9100 Direct the stub to write data to flash address ADDR. The data is
9101 passed in binary form using the same encoding as for the 'X' packet
9102 (*note Binary Data::). The memory ranges specified by
9103 'vFlashWrite' packets preceding a 'vFlashDone' packet must not
9104 overlap, and must appear in order of increasing addresses (although
9105 'vFlashErase' packets for higher addresses may already have been
9106 received; the ordering is guaranteed only between 'vFlashWrite'
9107 packets). If a packet writes to an address that was neither erased
9108 by a preceding 'vFlashErase' packet nor by some other
9109 target-specific method, the results are unpredictable.
9115 for vFlashWrite addressing non-flash memory
9120 Indicate to the stub that flash programming operation is finished.
9121 The stub is permitted to delay or batch the effects of a group of
9122 'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet
9123 is received. The contents of the affected regions of flash memory
9124 are unpredictable until the 'vFlashDone' request is completed.
9127 Kill the process with the specified process ID PID, which is a
9128 hexadecimal integer identifying the process. This packet is used
9129 in preference to 'k' when multiprocess protocol extensions are
9130 supported; see *note multiprocess extensions::.
9138 'vRun;FILENAME[;ARGUMENT]...'
9139 Run the program FILENAME, passing it each ARGUMENT on its command
9140 line. The file and arguments are hex-encoded strings. If FILENAME
9141 is an empty string, the stub may use a default program (e.g. the
9142 last program run). The program is created in the stopped state.
9144 This packet is only available in extended mode (*note extended
9151 for success (*note Stop Reply Packets::)
9154 *Note Notification Packets::.
9156 'X ADDR,LENGTH:XX...'
9157 Write data to memory, where the data is transmitted in binary.
9158 Memory is specified by its address ADDR and number of bytes LENGTH;
9159 'XX...' is binary data (*note Binary Data::).
9169 Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint
9170 starting at address ADDRESS of kind KIND.
9172 Each breakpoint and watchpoint packet TYPE is documented
9175 _Implementation notes: A remote target shall return an empty string
9176 for an unrecognized breakpoint or watchpoint packet TYPE. A remote
9177 target shall support either both or neither of a given 'ZTYPE...'
9178 and 'zTYPE...' packet pair. To avoid potential problems with
9179 duplicate packets, the operations should be implemented in an
9183 'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
9184 Insert ('Z0') or remove ('z0') a memory breakpoint at address ADDR
9187 A memory breakpoint is implemented by replacing the instruction at
9188 ADDR with a software breakpoint or trap instruction. The KIND is
9189 target-specific and typically indicates the size of the breakpoint
9190 in bytes that should be inserted. E.g., the ARM and MIPS can
9191 insert either a 2 or 4 byte breakpoint. Some architectures have
9192 additional meanings for KIND; COND_LIST is an optional list of
9193 conditional expressions in bytecode form that should be evaluated
9194 on the target's side. These are the conditions that should be
9195 taken into consideration when deciding if the breakpoint trigger
9196 should be reported back to GDBN.
9198 The COND_LIST parameter is comprised of a series of expressions,
9199 concatenated without separators. Each expression has the following
9203 LEN is the length of the bytecode expression and EXPR is the
9204 actual conditional expression in bytecode form.
9206 The optional CMD_LIST parameter introduces commands that may be run
9207 on the target, rather than being reported back to GDB. The
9208 parameter starts with a numeric flag PERSIST; if the flag is
9209 nonzero, then the breakpoint may remain active and the commands
9210 continue to be run even when GDB disconnects from the target.
9211 Following this flag is a series of expressions concatenated with no
9212 separators. Each expression has the following form:
9215 LEN is the length of the bytecode expression and EXPR is the
9216 actual conditional expression in bytecode form.
9218 see *note Architecture-Specific Protocol Details::.
9220 _Implementation note: It is possible for a target to copy or move
9221 code that contains memory breakpoints (e.g., when implementing
9222 overlays). The behavior of this packet, in the presence of such a
9223 target, is not defined._
9234 'Z1,ADDR,KIND[;COND_LIST...]'
9235 Insert ('Z1') or remove ('z1') a hardware breakpoint at address
9238 A hardware breakpoint is implemented using a mechanism that is not
9239 dependant on being able to modify the target's memory. The KIND
9240 and COND_LIST have the same meaning as in 'Z0' packets.
9242 _Implementation note: A hardware breakpoint is not affected by code
9255 Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. The
9256 number of bytes to watch is specified by KIND.
9268 Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. The
9269 number of bytes to watch is specified by KIND.
9281 Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. The
9282 number of bytes to watch is specified by KIND.
projects / platform / upstream / gdb.git / blob