1 This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo.
3 Copyright (C) 1988-2015 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.9.
26 Copyright (C) 1988-2015 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 Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI
42 27.3 GDB/MI Compatibility with CLI
43 ==================================
45 For the developers convenience CLI commands can be entered directly, but
46 there may be some unexpected behaviour. For example, commands that
47 query the user will behave as if the user replied yes, breakpoint
48 command lists are not executed and some CLI commands, such as 'if',
49 'when' and 'define', prompt for further input with '>', which is not
52 This feature may be removed at some stage in the future and it is
53 recommended that front ends use the '-interpreter-exec' command (*note
57 File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
59 27.4 GDB/MI Development and Front Ends
60 ======================================
62 The application which takes the MI output and presents the state of the
63 program being debugged to the user is called a "front end".
65 Although GDB/MI is still incomplete, it is currently being used by a
66 variety of front ends to GDB. This makes it difficult to introduce new
67 functionality without breaking existing usage. This section tries to
68 minimize the problems by describing how the protocol might change.
70 Some changes in MI need not break a carefully designed front end, and
71 for these the MI version will remain unchanged. The following is a list
72 of changes that may occur within one level, so front ends should parse
73 MI output in a way that can handle them:
75 * New MI commands may be added.
77 * New fields may be added to the output of any MI command.
79 * The range of values for fields with specified values, e.g.,
80 'in_scope' (*note -var-update::) may be extended.
82 If the changes are likely to break front ends, the MI version level
83 will be increased by one. This will allow the front end to parse the
84 output according to the MI version. Apart from mi0, new versions of GDB
85 will not support old versions of MI and it will be the responsibility of
86 the front end to work with the new one.
88 The best way to avoid unexpected changes in MI that might break your
89 front end is to make your project known to GDB developers and follow
90 development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>.
93 File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI
95 27.5 GDB/MI Output Records
96 ==========================
100 * GDB/MI Result Records::
101 * GDB/MI Stream Records::
102 * GDB/MI Async Records::
103 * GDB/MI Breakpoint Information::
104 * GDB/MI Frame Information::
105 * GDB/MI Thread Information::
106 * GDB/MI Ada Exception Information::
109 File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
111 27.5.1 GDB/MI Result Records
112 ----------------------------
114 In addition to a number of out-of-band notifications, the response to a
115 GDB/MI command includes one of the following result indications:
117 '"^done" [ "," RESULTS ]'
118 The synchronous operation was successful, 'RESULTS' are the return
122 This result record is equivalent to '^done'. Historically, it was
123 output instead of '^done' if the command has resumed the target.
124 This behaviour is maintained for backward compatibility, but all
125 frontends should treat '^done' and '^running' identically and rely
126 on the '*running' output record to determine which threads are
130 GDB has connected to a remote target.
132 '"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]'
133 The operation failed. The 'msg=C-STRING' variable contains the
134 corresponding error message.
136 If present, the 'code=C-STRING' variable provides an error code on
137 which consumers can rely on to detect the corresponding error
138 condition. At present, only one error code is defined:
140 '"undefined-command"'
141 Indicates that the command causing the error does not exist.
147 File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
149 27.5.2 GDB/MI Stream Records
150 ----------------------------
152 GDB internally maintains a number of output streams: the console, the
153 target, and the log. The output intended for each of these streams is
154 funneled through the GDB/MI interface using "stream records".
156 Each stream record begins with a unique "prefix character" which
157 identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
158 Syntax.). In addition to the prefix, each stream record contains a
159 'STRING-OUTPUT'. This is either raw text (with an implicit new line) or
160 a quoted C string (which does not contain an implicit newline).
163 The console output stream contains text that should be displayed in
164 the CLI console window. It contains the textual responses to CLI
168 The target output stream contains any textual output from the
169 running target. This is only present when GDB's event loop is
170 truly asynchronous, which is currently only the case for remote
174 The log stream contains debugging messages being produced by GDB's
178 File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
180 27.5.3 GDB/MI Async Records
181 ---------------------------
183 "Async" records are used to notify the GDB/MI client of additional
184 changes that have occurred. Those changes can either be a consequence
185 of GDB/MI commands (e.g., a breakpoint modified) or a result of target
186 activity (e.g., target stopped).
188 The following is the list of possible async records:
190 '*running,thread-id="THREAD"'
191 The target is now running. The THREAD field tells which specific
192 thread is now running, and can be 'all' if all threads are running.
193 The frontend should assume that no interaction with a running
194 thread is possible after this notification is produced. The
195 frontend should not assume that this notification is output only
196 once for any command. GDB may emit this notification several
197 times, either for different threads, because it cannot resume all
198 threads together, or even for a single thread, if the thread must
199 be stepped though some code before letting it run freely.
201 '*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"'
202 The target has stopped. The REASON field can have one of the
206 A breakpoint was reached.
208 A watchpoint was triggered.
209 'read-watchpoint-trigger'
210 A read watchpoint was triggered.
211 'access-watchpoint-trigger'
212 An access watchpoint was triggered.
214 An -exec-finish or similar CLI command was accomplished.
216 An -exec-until or similar CLI command was accomplished.
218 A watchpoint has gone out of scope.
220 An -exec-next, -exec-next-instruction, -exec-step,
221 -exec-step-instruction or similar CLI command was
224 The inferior exited because of a signal.
228 The inferior exited normally.
230 A signal was received by the inferior.
232 The inferior has stopped due to a library being loaded or
233 unloaded. This can happen when 'stop-on-solib-events' (*note
234 Files::) is set or when a 'catch load' or 'catch unload'
235 catchpoint is in use (*note Set Catchpoints::).
237 The inferior has forked. This is reported when 'catch fork'
238 (*note Set Catchpoints::) has been used.
240 The inferior has vforked. This is reported in when 'catch
241 vfork' (*note Set Catchpoints::) has been used.
243 The inferior entered a system call. This is reported when
244 'catch syscall' (*note Set Catchpoints::) has been used.
246 The inferior returned from a system call. This is reported
247 when 'catch syscall' (*note Set Catchpoints::) has been used.
249 The inferior called 'exec'. This is reported when 'catch
250 exec' (*note Set Catchpoints::) has been used.
252 The ID field identifies the thread that directly caused the stop -
253 for example by hitting a breakpoint. Depending on whether all-stop
254 mode is in effect (*note All-Stop Mode::), GDB may either stop all
255 threads, or only the thread that directly triggered the stop. If
256 all threads are stopped, the STOPPED field will have the value of
257 '"all"'. Otherwise, the value of the STOPPED field will be a list
258 of thread identifiers. Presently, this list will always include a
259 single thread, but frontend should be prepared to see several
260 threads in the list. The CORE field reports the processor core on
261 which the stop event has happened. This field may be absent if
262 such information is not available.
264 '=thread-group-added,id="ID"'
265 '=thread-group-removed,id="ID"'
266 A thread group was either added or removed. The ID field contains
267 the GDB identifier of the thread group. When a thread group is
268 added, it generally might not be associated with a running process.
269 When a thread group is removed, its id becomes invalid and cannot
272 '=thread-group-started,id="ID",pid="PID"'
273 A thread group became associated with a running program, either
274 because the program was just started or the thread group was
275 attached to a program. The ID field contains the GDB identifier of
276 the thread group. The PID field contains process identifier,
277 specific to the operating system.
279 '=thread-group-exited,id="ID"[,exit-code="CODE"]'
280 A thread group is no longer associated with a running program,
281 either because the program has exited, or because it was detached
282 from. The ID field contains the GDB identifier of the thread
283 group. The CODE field is the exit code of the inferior; it exists
284 only when the inferior exited with some code.
286 '=thread-created,id="ID",group-id="GID"'
287 '=thread-exited,id="ID",group-id="GID"'
288 A thread either was created, or has exited. The ID field contains
289 the GDB identifier of the thread. The GID field identifies the
290 thread group this thread belongs to.
292 '=thread-selected,id="ID"'
293 Informs that the selected thread was changed as result of the last
294 command. This notification is not emitted as result of
295 '-thread-select' command but is emitted whenever an MI command that
296 is not documented to change the selected thread actually changes
297 it. In particular, invoking, directly or indirectly (via
298 user-defined command), the CLI 'thread' command, will generate this
301 We suggest that in response to this notification, front ends
302 highlight the selected thread and cause subsequent commands to
303 apply to that thread.
305 '=library-loaded,...'
306 Reports that a new library file was loaded by the program. This
307 notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and
308 SYMBOLS-LOADED. The ID field is an opaque identifier of the
309 library. For remote debugging case, TARGET-NAME and HOST-NAME
310 fields give the name of the library file on the target, and on the
311 host respectively. For native debugging, both those fields have
312 the same value. The SYMBOLS-LOADED field is emitted only for
313 backward compatibility and should not be relied on to convey any
314 useful information. The THREAD-GROUP field, if present, specifies
315 the id of the thread group in whose context the library was loaded.
316 If the field is absent, it means the library was loaded in the
317 context of all present thread groups.
319 '=library-unloaded,...'
320 Reports that a library was unloaded by the program. This
321 notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the
322 same meaning as for the '=library-loaded' notification. The
323 THREAD-GROUP field, if present, specifies the id of the thread
324 group in whose context the library was unloaded. If the field is
325 absent, it means the library was unloaded in the context of all
326 present thread groups.
328 '=traceframe-changed,num=TFNUM,tracepoint=TPNUM'
329 '=traceframe-changed,end'
330 Reports that the trace frame was changed and its new number is
331 TFNUM. The number of the tracepoint associated with this trace
334 '=tsv-created,name=NAME,initial=INITIAL'
335 Reports that the new trace state variable NAME is created with
336 initial value INITIAL.
338 '=tsv-deleted,name=NAME'
340 Reports that the trace state variable NAME is deleted or all trace
341 state variables are deleted.
343 '=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]'
344 Reports that the trace state variable NAME is modified with the
345 initial value INITIAL. The current value CURRENT of trace state
346 variable is optional and is reported if the current value of trace
347 state variable is known.
349 '=breakpoint-created,bkpt={...}'
350 '=breakpoint-modified,bkpt={...}'
351 '=breakpoint-deleted,id=NUMBER'
352 Reports that a breakpoint was created, modified, or deleted,
353 respectively. Only user-visible breakpoints are reported to the MI
356 The BKPT argument is of the same form as returned by the various
357 breakpoint commands; *Note GDB/MI Breakpoint Commands::. The
358 NUMBER is the ordinal number of the breakpoint.
360 Note that if a breakpoint is emitted in the result record of a
361 command, then it will not also be emitted in an async record.
363 '=record-started,thread-group="ID"'
364 '=record-stopped,thread-group="ID"'
365 Execution log recording was either started or stopped on an
366 inferior. The ID is the GDB identifier of the thread group
367 corresponding to the affected inferior.
369 '=cmd-param-changed,param=PARAM,value=VALUE'
370 Reports that a parameter of the command 'set PARAM' is changed to
371 VALUE. In the multi-word 'set' command, the PARAM is the whole
372 parameter list to 'set' command. For example, In command 'set
373 check type on', PARAM is 'check type' and VALUE is 'on'.
375 '=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]'
376 Reports that bytes from ADDR to DATA + LEN were written in an
377 inferior. The ID is the identifier of the thread group
378 corresponding to the affected inferior. The optional 'type="code"'
379 part is reported if the memory written to holds executable code.
382 File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
384 27.5.4 GDB/MI Breakpoint Information
385 ------------------------------------
387 When GDB reports information about a breakpoint, a tracepoint, a
388 watchpoint, or a catchpoint, it uses a tuple with the following fields:
391 The breakpoint number. For a breakpoint that represents one
392 location of a multi-location breakpoint, this will be a dotted
396 The type of the breakpoint. For ordinary breakpoints this will be
397 'breakpoint', but many values are possible.
400 If the type of the breakpoint is 'catchpoint', then this indicates
401 the exact type of catchpoint.
404 This is the breakpoint disposition--either 'del', meaning that the
405 breakpoint will be deleted at the next stop, or 'keep', meaning
406 that the breakpoint will not be deleted.
409 This indicates whether the breakpoint is enabled, in which case the
410 value is 'y', or disabled, in which case the value is 'n'. Note
411 that this is not the same as the field 'enable'.
414 The address of the breakpoint. This may be a hexidecimal number,
415 giving the address; or the string '<PENDING>', for a pending
416 breakpoint; or the string '<MULTIPLE>', for a breakpoint with
417 multiple locations. This field will not be present if no address
418 can be determined. For example, a watchpoint does not have an
422 If known, the function in which the breakpoint appears. If not
423 known, this field is not present.
426 The name of the source file which contains this function, if known.
427 If not known, this field is not present.
430 The full file name of the source file which contains this function,
431 if known. If not known, this field is not present.
434 The line number at which this breakpoint appears, if known. If not
435 known, this field is not present.
438 If the source file is not known, this field may be provided. If
439 provided, this holds the address of the breakpoint, possibly
440 followed by a symbol name.
443 If this breakpoint is pending, this field is present and holds the
444 text used to set the breakpoint, as entered by the user.
447 Where this breakpoint's condition is evaluated, either 'host' or
451 If this is a thread-specific breakpoint, then this identifies the
452 thread in which the breakpoint can trigger.
455 If this breakpoint is restricted to a particular Ada task, then
456 this field will hold the task identifier.
459 If the breakpoint is conditional, this is the condition expression.
462 The ignore count of the breakpoint.
465 The enable count of the breakpoint.
470 'static-tracepoint-marker-string-id'
471 For a static tracepoint, the name of the static tracepoint marker.
474 For a masked watchpoint, this is the mask.
477 A tracepoint's pass count.
480 The location of the breakpoint as originally specified by the user.
481 This field is optional.
484 The number of times the breakpoint has been hit.
487 This field is only given for tracepoints. This is either 'y',
488 meaning that the tracepoint is installed, or 'n', meaning that it
492 Some extra data, the exact contents of which are type-dependent.
494 For example, here is what the output of '-break-insert' (*note GDB/MI
495 Breakpoint Commands::) might be:
497 -> -break-insert main
498 <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
499 enabled="y",addr="0x08048564",func="main",file="myprog.c",
500 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
505 File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records
507 27.5.5 GDB/MI Frame Information
508 -------------------------------
510 Response from many MI commands includes an information about stack
511 frame. This information is a tuple that may have the following fields:
514 The level of the stack frame. The innermost frame has the level of
515 zero. This field is always present.
518 The name of the function corresponding to the frame. This field
519 may be absent if GDB is unable to determine the function name.
522 The code address for the frame. This field is always present.
525 The name of the source files that correspond to the frame's code
526 address. This field may be absent.
529 The source line corresponding to the frames' code address. This
533 The name of the binary file (either executable or shared library)
534 the corresponds to the frame's code address. This field may be
538 File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records
540 27.5.6 GDB/MI Thread Information
541 --------------------------------
543 Whenever GDB has to report an information about a thread, it uses a
544 tuple with the following fields:
547 The numeric id assigned to the thread by GDB. This field is always
551 Target-specific string identifying the thread. This field is
555 Additional information about the thread provided by the target. It
556 is supposed to be human-readable and not interpreted by the
557 frontend. This field is optional.
560 Either 'stopped' or 'running', depending on whether the thread is
561 presently running. This field is always present.
564 The value of this field is an integer number of the processor core
565 the thread was last seen on. This field is optional.
568 File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records
570 27.5.7 GDB/MI Ada Exception Information
571 ---------------------------------------
573 Whenever a '*stopped' record is emitted because the program stopped
574 after hitting an exception catchpoint (*note Set Catchpoints::), GDB
575 provides the name of the exception that was raised via the
576 'exception-name' field.
579 File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI
581 27.6 Simple Examples of GDB/MI Interaction
582 ==========================================
584 This subsection presents several simple examples of interaction using
585 the GDB/MI interface. In these examples, '->' means that the following
586 line is passed to GDB/MI as input, while '<-' means the output received
589 Note the line breaks shown in the examples are here only for
590 readability, they don't appear in the real output.
595 Setting a breakpoint generates synchronous output which contains
596 detailed information of the breakpoint.
598 -> -break-insert main
599 <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
600 enabled="y",addr="0x08048564",func="main",file="myprog.c",
601 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
608 Program execution generates asynchronous records and MI gives the reason
609 that execution stopped.
614 <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
615 frame={addr="0x08048564",func="main",
616 args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],
617 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"}
622 <- *stopped,reason="exited-normally"
628 Quitting GDB just prints the result class '^exit'.
634 Please note that '^exit' is printed immediately, but it might take
635 some time for GDB to actually exit. During that time, GDB performs
636 necessary cleanups, including killing programs being debugged or
637 disconnecting from debug hardware, so the frontend should wait till GDB
638 exits and should only forcibly kill GDB if it fails to exit in
644 Here's what happens if you pass a non-existent command:
647 <- ^error,msg="Undefined MI command: rubbish"
651 File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
653 27.7 GDB/MI Command Description Format
654 ======================================
656 The remaining sections describe blocks of commands. Each block of
657 commands is laid out in a fashion similar to this section.
662 The motivation for this collection of commands.
667 A brief introduction to this collection of commands as a whole.
672 For each command in the block, the following is described:
685 The corresponding GDB CLI command(s), if any.
690 Example(s) formatted for readability. Some of the described commands
691 have not been implemented yet and these are labeled N.A. (not
695 File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI
697 27.8 GDB/MI Breakpoint Commands
698 ===============================
700 This section documents GDB/MI commands for manipulating breakpoints.
702 The '-break-after' Command
703 --------------------------
708 -break-after NUMBER COUNT
710 The breakpoint number NUMBER is not in effect until it has been hit
711 COUNT times. To see how this is reflected in the output of the
712 '-break-list' command, see the description of the '-break-list' command
718 The corresponding GDB command is 'ignore'.
725 ^done,bkpt={number="1",type="breakpoint",disp="keep",
726 enabled="y",addr="0x000100d0",func="main",file="hello.c",
727 fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
735 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
736 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
737 {width="14",alignment="-1",col_name="type",colhdr="Type"},
738 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
739 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
740 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
741 {width="40",alignment="2",col_name="what",colhdr="What"}],
742 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
743 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
744 line="5",thread-groups=["i1"],times="0",ignore="3"}]}
747 The '-break-commands' Command
748 -----------------------------
753 -break-commands NUMBER [ COMMAND1 ... COMMANDN ]
755 Specifies the CLI commands that should be executed when breakpoint
756 NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands.
757 If no command is specified, any previously-set commands are cleared.
758 *Note Break Commands::. Typical use of this functionality is tracing a
759 program, that is, printing of values of some variables whenever
760 breakpoint is hit and then continuing.
765 The corresponding GDB command is 'commands'.
772 ^done,bkpt={number="1",type="breakpoint",disp="keep",
773 enabled="y",addr="0x000100d0",func="main",file="hello.c",
774 fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
777 -break-commands 1 "print v" "continue"
781 The '-break-condition' Command
782 ------------------------------
787 -break-condition NUMBER EXPR
789 Breakpoint NUMBER will stop the program only if the condition in EXPR
790 is true. The condition becomes part of the '-break-list' output (see
791 the description of the '-break-list' command below).
796 The corresponding GDB command is 'condition'.
806 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
807 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
808 {width="14",alignment="-1",col_name="type",colhdr="Type"},
809 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
810 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
811 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
812 {width="40",alignment="2",col_name="what",colhdr="What"}],
813 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
814 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
815 line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]}
818 The '-break-delete' Command
819 ---------------------------
824 -break-delete ( BREAKPOINT )+
826 Delete the breakpoint(s) whose number(s) are specified in the
827 argument list. This is obviously reflected in the breakpoint list.
832 The corresponding GDB command is 'delete'.
842 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
843 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
844 {width="14",alignment="-1",col_name="type",colhdr="Type"},
845 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
846 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
847 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
848 {width="40",alignment="2",col_name="what",colhdr="What"}],
852 The '-break-disable' Command
853 ----------------------------
858 -break-disable ( BREAKPOINT )+
860 Disable the named BREAKPOINT(s). The field 'enabled' in the break
861 list is now set to 'n' for the named BREAKPOINT(s).
866 The corresponding GDB command is 'disable'.
876 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
877 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
878 {width="14",alignment="-1",col_name="type",colhdr="Type"},
879 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
880 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
881 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
882 {width="40",alignment="2",col_name="what",colhdr="What"}],
883 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
884 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
885 line="5",thread-groups=["i1"],times="0"}]}
888 The '-break-enable' Command
889 ---------------------------
894 -break-enable ( BREAKPOINT )+
896 Enable (previously disabled) BREAKPOINT(s).
901 The corresponding GDB command is 'enable'.
911 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
912 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
913 {width="14",alignment="-1",col_name="type",colhdr="Type"},
914 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
915 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
916 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
917 {width="40",alignment="2",col_name="what",colhdr="What"}],
918 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
919 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
920 line="5",thread-groups=["i1"],times="0"}]}
923 The '-break-info' Command
924 -------------------------
929 -break-info BREAKPOINT
931 Get information about a single breakpoint.
933 The result is a table of breakpoints. *Note GDB/MI Breakpoint
934 Information::, for details on the format of each breakpoint in the
940 The corresponding GDB command is 'info break BREAKPOINT'.
947 The '-break-insert' Command
948 ---------------------------
953 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
954 [ -c CONDITION ] [ -i IGNORE-COUNT ]
955 [ -p THREAD-ID ] [ LOCATION ]
957 If specified, LOCATION, can be one of:
964 The possible optional parameters of this command are:
967 Insert a temporary breakpoint.
969 Insert a hardware breakpoint.
971 If LOCATION cannot be parsed (for example if it refers to unknown
972 files or functions), create a pending breakpoint. Without this
973 flag, GDB will report an error, and won't create a breakpoint, if
974 LOCATION cannot be parsed.
976 Create a disabled breakpoint.
978 Create a tracepoint. *Note Tracepoints::. When this parameter is
979 used together with '-h', a fast tracepoint is created.
981 Make the breakpoint conditional on CONDITION.
983 Initialize the IGNORE-COUNT.
985 Restrict the breakpoint to the specified THREAD-ID.
990 *Note GDB/MI Breakpoint Information::, for details on the format of the
991 resulting breakpoint.
993 Note: this format is open to change.
998 The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and
1006 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
1007 fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
1010 -break-insert -t foo
1011 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
1012 fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
1016 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
1017 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
1018 {width="14",alignment="-1",col_name="type",colhdr="Type"},
1019 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
1020 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
1021 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
1022 {width="40",alignment="2",col_name="what",colhdr="What"}],
1023 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
1024 addr="0x0001072c", func="main",file="recursive2.c",
1025 fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
1027 bkpt={number="2",type="breakpoint",disp="del",enabled="y",
1028 addr="0x00010774",func="foo",file="recursive2.c",
1029 fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
1033 The '-dprintf-insert' Command
1034 -----------------------------
1039 -dprintf-insert [ -t ] [ -f ] [ -d ]
1040 [ -c CONDITION ] [ -i IGNORE-COUNT ]
1041 [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ]
1044 If specified, LOCATION, can be one of:
1051 The possible optional parameters of this command are:
1054 Insert a temporary breakpoint.
1056 If LOCATION cannot be parsed (for example, if it refers to unknown
1057 files or functions), create a pending breakpoint. Without this
1058 flag, GDB will report an error, and won't create a breakpoint, if
1059 LOCATION cannot be parsed.
1061 Create a disabled breakpoint.
1063 Make the breakpoint conditional on CONDITION.
1065 Set the ignore count of the breakpoint (*note ignore count:
1066 Conditions.) to IGNORE-COUNT.
1068 Restrict the breakpoint to the specified THREAD-ID.
1073 *Note GDB/MI Breakpoint Information::, for details on the format of the
1074 resulting breakpoint.
1079 The corresponding GDB command is 'dprintf'.
1085 4-dprintf-insert foo "At foo entry\n"
1086 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y",
1087 addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
1088 fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
1089 times="0",script={"printf \"At foo entry\\n\"","continue"},
1090 original-location="foo"}
1092 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
1093 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y",
1094 addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
1095 fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
1096 times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"},
1097 original-location="mi-dprintf.c:26"}
1100 The '-break-list' Command
1101 -------------------------
1108 Displays the list of inserted breakpoints, showing the following
1112 number of the breakpoint
1114 type of the breakpoint: 'breakpoint' or 'watchpoint'
1116 should the breakpoint be deleted or disabled when it is hit: 'keep'
1119 is the breakpoint enabled or no: 'y' or 'n'
1121 memory location at which the breakpoint is set
1123 logical location of the breakpoint, expressed by function name,
1124 file name, line number
1126 list of thread groups to which this breakpoint applies
1128 number of times the breakpoint has been hit
1130 If there are no breakpoints or watchpoints, the 'BreakpointTable'
1131 'body' field is an empty list.
1136 The corresponding GDB command is 'info break'.
1143 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
1144 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
1145 {width="14",alignment="-1",col_name="type",colhdr="Type"},
1146 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
1147 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
1148 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
1149 {width="40",alignment="2",col_name="what",colhdr="What"}],
1150 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
1151 addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
1153 bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
1154 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
1155 line="13",thread-groups=["i1"],times="0"}]}
1158 Here's an example of the result when there are no breakpoints:
1162 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
1163 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
1164 {width="14",alignment="-1",col_name="type",colhdr="Type"},
1165 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
1166 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
1167 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
1168 {width="40",alignment="2",col_name="what",colhdr="What"}],
1172 The '-break-passcount' Command
1173 ------------------------------
1178 -break-passcount TRACEPOINT-NUMBER PASSCOUNT
1180 Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If
1181 the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint,
1182 error is emitted. This corresponds to CLI command 'passcount'.
1184 The '-break-watch' Command
1185 --------------------------
1190 -break-watch [ -a | -r ]
1192 Create a watchpoint. With the '-a' option it will create an "access"
1193 watchpoint, i.e., a watchpoint that triggers either on a read from or on
1194 a write to the memory location. With the '-r' option, the watchpoint
1195 created is a "read" watchpoint, i.e., it will trigger only when the
1196 memory location is accessed for reading. Without either of the options,
1197 the watchpoint created is a regular watchpoint, i.e., it will trigger
1198 when the memory location is accessed for writing. *Note Setting
1199 Watchpoints: Set Watchpoints.
1201 Note that '-break-list' will report a single list of watchpoints and
1202 breakpoints inserted.
1207 The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'.
1212 Setting a watchpoint on a variable in the 'main' function:
1216 ^done,wpt={number="2",exp="x"}
1221 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
1222 value={old="-268439212",new="55"},
1223 frame={func="main",args=[],file="recursive2.c",
1224 fullname="/home/foo/bar/recursive2.c",line="5"}
1227 Setting a watchpoint on a variable local to a function. GDB will
1228 stop the program execution twice: first for the variable changing value,
1229 then for the watchpoint going out of scope.
1233 ^done,wpt={number="5",exp="C"}
1238 *stopped,reason="watchpoint-trigger",
1239 wpt={number="5",exp="C"},value={old="-276895068",new="3"},
1240 frame={func="callee4",args=[],
1241 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1242 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
1247 *stopped,reason="watchpoint-scope",wpnum="5",
1248 frame={func="callee3",args=[{name="strarg",
1249 value="0x11940 \"A string argument.\""}],
1250 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1251 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
1254 Listing breakpoints and watchpoints, at different points in the
1255 program execution. Note that once the watchpoint goes out of scope, it
1260 ^done,wpt={number="2",exp="C"}
1263 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
1264 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
1265 {width="14",alignment="-1",col_name="type",colhdr="Type"},
1266 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
1267 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
1268 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
1269 {width="40",alignment="2",col_name="what",colhdr="What"}],
1270 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
1271 addr="0x00010734",func="callee4",
1272 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1273 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
1275 bkpt={number="2",type="watchpoint",disp="keep",
1276 enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]}
1281 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
1282 value={old="-276895068",new="3"},
1283 frame={func="callee4",args=[],
1284 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1285 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
1288 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
1289 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
1290 {width="14",alignment="-1",col_name="type",colhdr="Type"},
1291 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
1292 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
1293 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
1294 {width="40",alignment="2",col_name="what",colhdr="What"}],
1295 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
1296 addr="0x00010734",func="callee4",
1297 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1298 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
1300 bkpt={number="2",type="watchpoint",disp="keep",
1301 enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]}
1305 ^done,reason="watchpoint-scope",wpnum="2",
1306 frame={func="callee3",args=[{name="strarg",
1307 value="0x11940 \"A string argument.\""}],
1308 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1309 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
1312 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
1313 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
1314 {width="14",alignment="-1",col_name="type",colhdr="Type"},
1315 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
1316 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
1317 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
1318 {width="40",alignment="2",col_name="what",colhdr="What"}],
1319 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
1320 addr="0x00010734",func="callee4",
1321 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1322 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
1323 thread-groups=["i1"],times="1"}]}
1327 File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
1329 27.9 GDB/MI Catchpoint Commands
1330 ===============================
1332 This section documents GDB/MI commands for manipulating catchpoints.
1336 * Shared Library GDB/MI Catchpoint Commands::
1337 * Ada Exception GDB/MI Catchpoint Commands::
1340 File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
1342 27.9.1 Shared Library GDB/MI Catchpoints
1343 ----------------------------------------
1345 The '-catch-load' Command
1346 -------------------------
1351 -catch-load [ -t ] [ -d ] REGEXP
1353 Add a catchpoint for library load events. If the '-t' option is
1354 used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
1355 Breaks.). If the '-d' option is used, the catchpoint is created in a
1356 disabled state. The 'regexp' argument is a regular expression used to
1357 match the name of the loaded library.
1362 The corresponding GDB command is 'catch load'.
1367 -catch-load -t foo.so
1368 ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y",
1369 what="load of library matching foo.so",catch-type="load",times="0"}
1372 The '-catch-unload' Command
1373 ---------------------------
1378 -catch-unload [ -t ] [ -d ] REGEXP
1380 Add a catchpoint for library unload events. If the '-t' option is
1381 used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
1382 Breaks.). If the '-d' option is used, the catchpoint is created in a
1383 disabled state. The 'regexp' argument is a regular expression used to
1384 match the name of the unloaded library.
1389 The corresponding GDB command is 'catch unload'.
1394 -catch-unload -d bar.so
1395 ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n",
1396 what="load of library matching bar.so",catch-type="unload",times="0"}
1400 File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
1402 27.9.2 Ada Exception GDB/MI Catchpoints
1403 ---------------------------------------
1405 The following GDB/MI commands can be used to create catchpoints that
1406 stop the execution when Ada exceptions are being raised.
1408 The '-catch-assert' Command
1409 ---------------------------
1414 -catch-assert [ -c CONDITION] [ -d ] [ -t ]
1416 Add a catchpoint for failed Ada assertions.
1418 The possible optional parameters for this command are:
1421 Make the catchpoint conditional on CONDITION.
1423 Create a disabled catchpoint.
1425 Create a temporary catchpoint.
1430 The corresponding GDB command is 'catch assert'.
1436 ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep",
1437 enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
1438 thread-groups=["i1"],times="0",
1439 original-location="__gnat_debug_raise_assert_failure"}
1442 The '-catch-exception' Command
1443 ------------------------------
1448 -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ]
1451 Add a catchpoint stopping when Ada exceptions are raised. By
1452 default, the command stops the program when any Ada exception gets
1453 raised. But it is also possible, by using some of the optional
1454 parameters described below, to create more selective catchpoints.
1456 The possible optional parameters for this command are:
1459 Make the catchpoint conditional on CONDITION.
1461 Create a disabled catchpoint.
1463 Only stop when EXCEPTION-NAME is raised. This option cannot be
1464 used combined with '-u'.
1466 Create a temporary catchpoint.
1468 Stop only when an unhandled exception gets raised. This option
1469 cannot be used combined with '-e'.
1474 The corresponding GDB commands are 'catch exception' and 'catch
1475 exception unhandled'.
1480 -catch-exception -e Program_Error
1481 ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep",
1482 enabled="y",addr="0x0000000000404874",
1483 what="`Program_Error' Ada exception", thread-groups=["i1"],
1484 times="0",original-location="__gnat_debug_raise_exception"}
1488 File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI
1490 27.10 GDB/MI Program Context
1491 ============================
1493 The '-exec-arguments' Command
1494 -----------------------------
1499 -exec-arguments ARGS
1501 Set the inferior program arguments, to be used in the next
1507 The corresponding GDB command is 'set args'.
1513 -exec-arguments -v word
1517 The '-environment-cd' Command
1518 -----------------------------
1523 -environment-cd PATHDIR
1525 Set GDB's working directory.
1530 The corresponding GDB command is 'cd'.
1536 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1540 The '-environment-directory' Command
1541 ------------------------------------
1546 -environment-directory [ -r ] [ PATHDIR ]+
1548 Add directories PATHDIR to beginning of search path for source files.
1549 If the '-r' option is used, the search path is reset to the default
1550 search path. If directories PATHDIR are supplied in addition to the
1551 '-r' option, the search path is first reset and then addition occurs as
1552 normal. Multiple directories may be specified, separated by blanks.
1553 Specifying multiple directories in a single command results in the
1554 directories added to the beginning of the search path in the same order
1555 they were presented in the command. If blanks are needed as part of a
1556 directory name, double-quotes should be used around the name. In the
1557 command output, the path will show up separated by the system
1558 directory-separator character. The directory-separator character must
1559 not be used in any directory name. If no directories are specified, the
1560 current search path is displayed.
1565 The corresponding GDB command is 'dir'.
1571 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1572 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
1574 -environment-directory ""
1575 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
1577 -environment-directory -r /home/jjohnstn/src/gdb /usr/src
1578 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
1580 -environment-directory -r
1581 ^done,source-path="$cdir:$cwd"
1584 The '-environment-path' Command
1585 -------------------------------
1590 -environment-path [ -r ] [ PATHDIR ]+
1592 Add directories PATHDIR to beginning of search path for object files.
1593 If the '-r' option is used, the search path is reset to the original
1594 search path that existed at gdb start-up. If directories PATHDIR are
1595 supplied in addition to the '-r' option, the search path is first reset
1596 and then addition occurs as normal. Multiple directories may be
1597 specified, separated by blanks. Specifying multiple directories in a
1598 single command results in the directories added to the beginning of the
1599 search path in the same order they were presented in the command. If
1600 blanks are needed as part of a directory name, double-quotes should be
1601 used around the name. In the command output, the path will show up
1602 separated by the system directory-separator character. The
1603 directory-separator character must not be used in any directory name.
1604 If no directories are specified, the current path is displayed.
1609 The corresponding GDB command is 'path'.
1616 ^done,path="/usr/bin"
1618 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
1619 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
1621 -environment-path -r /usr/local/bin
1622 ^done,path="/usr/local/bin:/usr/bin"
1625 The '-environment-pwd' Command
1626 ------------------------------
1633 Show the current working directory.
1638 The corresponding GDB command is 'pwd'.
1645 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
1649 File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI
1651 27.11 GDB/MI Thread Commands
1652 ============================
1654 The '-thread-info' Command
1655 --------------------------
1660 -thread-info [ THREAD-ID ]
1662 Reports information about either a specific thread, if the THREAD-ID
1663 parameter is present, or about all threads. When printing information
1664 about all threads, also reports the current thread.
1669 The 'info thread' command prints the same information about all threads.
1674 The result is a list of threads. The following attributes are defined
1678 This field exists only for the current thread. It has the value
1682 The identifier that GDB uses to refer to the thread.
1685 The identifier that the target uses to refer to the thread.
1688 Extra information about the thread, in a target-specific format.
1689 This field is optional.
1692 The name of the thread. If the user specified a name using the
1693 'thread name' command, then this name is given. Otherwise, if GDB
1694 can extract the thread name from the target, then that name is
1695 given. If GDB cannot find the thread name, then this field is
1699 The stack frame currently executing in the thread.
1702 The thread's state. The 'state' field may have the following
1706 The thread is stopped. Frame information is available for
1710 The thread is running. There's no frame information for
1714 If GDB can find the CPU core on which this thread is running, then
1715 this field is the core identifier. This field is optional.
1722 {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
1723 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",
1724 args=[]},state="running"},
1725 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
1726 frame={level="0",addr="0x0804891f",func="foo",
1727 args=[{name="i",value="10"}],
1728 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},
1730 current-thread-id="1"
1733 The '-thread-list-ids' Command
1734 ------------------------------
1741 Produces a list of the currently known GDB thread ids. At the end of
1742 the list it also prints the total number of such threads.
1744 This command is retained for historical reasons, the '-thread-info'
1745 command should be used instead.
1750 Part of 'info threads' supplies the same information.
1757 ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
1758 current-thread-id="1",number-of-threads="3"
1761 The '-thread-select' Command
1762 ----------------------------
1767 -thread-select THREADNUM
1769 Make THREADNUM the current thread. It prints the number of the new
1770 current thread, and the topmost frame for that thread.
1772 This command is deprecated in favor of explicitly using the
1773 '--thread' option to each command.
1778 The corresponding GDB command is 'thread'.
1787 *stopped,reason="end-stepping-range",thread-id="2",line="187",
1788 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
1792 thread-ids={thread-id="3",thread-id="2",thread-id="1"},
1793 number-of-threads="3"
1796 ^done,new-thread-id="3",
1797 frame={level="0",func="vprintf",
1798 args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
1799 {name="arg",value="0x2"}],file="vprintf.c",line="31"}
1803 File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI
1805 27.12 GDB/MI Ada Tasking Commands
1806 =================================
1808 The '-ada-task-info' Command
1809 ----------------------------
1814 -ada-task-info [ TASK-ID ]
1816 Reports information about either a specific Ada task, if the TASK-ID
1817 parameter is present, or about all Ada tasks.
1822 The 'info tasks' command prints the same information about all Ada tasks
1823 (*note Ada Tasks::).
1828 The result is a table of Ada tasks. The following columns are defined
1832 This field exists only for the current thread. It has the value
1836 The identifier that GDB uses to refer to the Ada task.
1839 The identifier that the target uses to refer to the Ada task.
1842 The identifier of the thread corresponding to the Ada task.
1844 This field should always exist, as Ada tasks are always implemented
1845 on top of a thread. But if GDB cannot find this corresponding
1846 thread for any reason, the field is omitted.
1849 This field exists only when the task was created by another task.
1850 In this case, it provides the ID of the parent task.
1853 The base priority of the task.
1856 The current state of the task. For a detailed description of the
1857 possible states, see *note Ada Tasks::.
1860 The name of the task.
1866 ^done,tasks={nr_rows="3",nr_cols="8",
1867 hdr=[{width="1",alignment="-1",col_name="current",colhdr=""},
1868 {width="3",alignment="1",col_name="id",colhdr="ID"},
1869 {width="9",alignment="1",col_name="task-id",colhdr="TID"},
1870 {width="4",alignment="1",col_name="thread-id",colhdr=""},
1871 {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"},
1872 {width="3",alignment="1",col_name="priority",colhdr="Pri"},
1873 {width="22",alignment="-1",col_name="state",colhdr="State"},
1874 {width="1",alignment="2",col_name="name",colhdr="Name"}],
1875 body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48",
1876 state="Child Termination Wait",name="main_task"}]}
1880 File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI
1882 27.13 GDB/MI Program Execution
1883 ==============================
1885 These are the asynchronous commands which generate the out-of-band
1886 record '*stopped'. Currently GDB only really executes asynchronously
1887 with remote targets and this interaction is mimicked in other cases.
1889 The '-exec-continue' Command
1890 ----------------------------
1895 -exec-continue [--reverse] [--all|--thread-group N]
1897 Resumes the execution of the inferior program, which will continue to
1898 execute until it reaches a debugger stop event. If the '--reverse'
1899 option is specified, execution resumes in reverse until it reaches a
1900 stop event. Stop events may include
1901 * breakpoints or watchpoints
1902 * signals or exceptions
1903 * the end of the process (or its beginning under '--reverse')
1904 * the end or beginning of a replay log if one is being used.
1905 In all-stop mode (*note All-Stop Mode::), may resume only one thread,
1906 or all threads, depending on the value of the 'scheduler-locking'
1907 variable. If '--all' is specified, all threads (in all inferiors) will
1908 be resumed. The '--all' option is ignored in all-stop mode. If the
1909 '--thread-group' options is specified, then all threads in that thread
1915 The corresponding GDB corresponding is 'continue'.
1924 *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={
1925 func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
1929 The '-exec-finish' Command
1930 --------------------------
1935 -exec-finish [--reverse]
1937 Resumes the execution of the inferior program until the current
1938 function is exited. Displays the results returned by the function. If
1939 the '--reverse' option is specified, resumes the reverse execution of
1940 the inferior program until the point where current function was called.
1945 The corresponding GDB command is 'finish'.
1950 Function returning 'void'.
1956 *stopped,reason="function-finished",frame={func="main",args=[],
1957 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
1960 Function returning other than 'void'. The name of the internal GDB
1961 variable storing the result is printed, together with the value itself.
1966 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
1967 args=[{name="a",value="1"],{name="b",value="9"}},
1968 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1969 gdb-result-var="$1",return-value="0"
1972 The '-exec-interrupt' Command
1973 -----------------------------
1978 -exec-interrupt [--all|--thread-group N]
1980 Interrupts the background execution of the target. Note how the
1981 token associated with the stop message is the one for the execution
1982 command that has been interrupted. The token for the interrupt itself
1983 only appears in the '^done' output. If the user is trying to interrupt
1984 a non-running program, an error message will be printed.
1986 Note that when asynchronous execution is enabled, this command is
1987 asynchronous just like other execution commands. That is, first the
1988 '^done' response will be printed, and the target stop will be reported
1989 after that using the '*stopped' notification.
1991 In non-stop mode, only the context thread is interrupted by default.
1992 All threads (in all inferiors) will be interrupted if the '--all' option
1993 is specified. If the '--thread-group' option is specified, all threads
1994 in that group will be interrupted.
1999 The corresponding GDB command is 'interrupt'.
2012 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
2013 frame={addr="0x00010140",func="foo",args=[],file="try.c",
2014 fullname="/home/foo/bar/try.c",line="13"}
2019 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
2022 The '-exec-jump' Command
2023 ------------------------
2030 Resumes execution of the inferior program at the location specified
2031 by parameter. *Note Specify Location::, for a description of the
2032 different forms of LOCATION.
2037 The corresponding GDB command is 'jump'.
2043 *running,thread-id="all"
2046 The '-exec-next' Command
2047 ------------------------
2052 -exec-next [--reverse]
2054 Resumes execution of the inferior program, stopping when the
2055 beginning of the next source line is reached.
2057 If the '--reverse' option is specified, resumes reverse execution of
2058 the inferior program, stopping at the beginning of the previous source
2059 line. If you issue this command on the first line of a function, it
2060 will take you back to the caller of that function, to the source line
2061 where the function was called.
2066 The corresponding GDB command is 'next'.
2074 *stopped,reason="end-stepping-range",line="8",file="hello.c"
2077 The '-exec-next-instruction' Command
2078 ------------------------------------
2083 -exec-next-instruction [--reverse]
2085 Executes one machine instruction. If the instruction is a function
2086 call, continues until the function returns. If the program stops at an
2087 instruction in the middle of a source line, the address will be printed
2090 If the '--reverse' option is specified, resumes reverse execution of
2091 the inferior program, stopping at the previous instruction. If the
2092 previously executed instruction was a return from another function, it
2093 will continue to execute in reverse until the call to that function
2094 (from the current stack frame) is reached.
2099 The corresponding GDB command is 'nexti'.
2105 -exec-next-instruction
2109 *stopped,reason="end-stepping-range",
2110 addr="0x000100d4",line="5",file="hello.c"
2113 The '-exec-return' Command
2114 --------------------------
2121 Makes current function return immediately. Doesn't execute the
2122 inferior. Displays the new current frame.
2127 The corresponding GDB command is 'return'.
2133 200-break-insert callee4
2134 200^done,bkpt={number="1",addr="0x00010734",
2135 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
2140 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
2141 frame={func="callee4",args=[],
2142 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2143 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
2149 111^done,frame={level="0",func="callee3",
2150 args=[{name="strarg",
2151 value="0x11940 \"A string argument.\""}],
2152 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2153 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
2156 The '-exec-run' Command
2157 -----------------------
2162 -exec-run [ --all | --thread-group N ] [ --start ]
2164 Starts execution of the inferior from the beginning. The inferior
2165 executes until either a breakpoint is encountered or the program exits.
2166 In the latter case the output will include an exit code, if the program
2167 has exited exceptionally.
2169 When neither the '--all' nor the '--thread-group' option is
2170 specified, the current inferior is started. If the '--thread-group'
2171 option is specified, it should refer to a thread group of type
2172 'process', and that thread group will be started. If the '--all' option
2173 is specified, then all inferiors will be started.
2175 Using the '--start' option instructs the debugger to stop the
2176 execution at the start of the inferior's main subprogram, following the
2177 same behavior as the 'start' command (*note Starting::).
2182 The corresponding GDB command is 'run'.
2189 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
2194 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
2195 frame={func="main",args=[],file="recursive2.c",
2196 fullname="/home/foo/bar/recursive2.c",line="4"}
2199 Program exited normally:
2206 *stopped,reason="exited-normally"
2209 Program exited exceptionally:
2216 *stopped,reason="exited",exit-code="01"
2219 Another way the program can terminate is if it receives a signal such
2220 as 'SIGINT'. In this case, GDB/MI displays this:
2223 *stopped,reason="exited-signalled",signal-name="SIGINT",
2224 signal-meaning="Interrupt"
2226 The '-exec-step' Command
2227 ------------------------
2232 -exec-step [--reverse]
2234 Resumes execution of the inferior program, stopping when the
2235 beginning of the next source line is reached, if the next source line is
2236 not a function call. If it is, stop at the first instruction of the
2237 called function. If the '--reverse' option is specified, resumes
2238 reverse execution of the inferior program, stopping at the beginning of
2239 the previously executed source line.
2244 The corresponding GDB command is 'step'.
2249 Stepping into a function:
2254 *stopped,reason="end-stepping-range",
2255 frame={func="foo",args=[{name="a",value="10"},
2256 {name="b",value="0"}],file="recursive2.c",
2257 fullname="/home/foo/bar/recursive2.c",line="11"}
2265 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2268 The '-exec-step-instruction' Command
2269 ------------------------------------
2274 -exec-step-instruction [--reverse]
2276 Resumes the inferior which executes one machine instruction. If the
2277 '--reverse' option is specified, resumes reverse execution of the
2278 inferior program, stopping at the previously executed instruction. The
2279 output, once GDB has stopped, will vary depending on whether we have
2280 stopped in the middle of a source line or not. In the former case, the
2281 address at which the program stopped will be printed as well.
2286 The corresponding GDB command is 'stepi'.
2292 -exec-step-instruction
2296 *stopped,reason="end-stepping-range",
2297 frame={func="foo",args=[],file="try.c",
2298 fullname="/home/foo/bar/try.c",line="10"}
2300 -exec-step-instruction
2304 *stopped,reason="end-stepping-range",
2305 frame={addr="0x000100f4",func="foo",args=[],file="try.c",
2306 fullname="/home/foo/bar/try.c",line="10"}
2309 The '-exec-until' Command
2310 -------------------------
2315 -exec-until [ LOCATION ]
2317 Executes the inferior until the LOCATION specified in the argument is
2318 reached. If there is no argument, the inferior executes until a source
2319 line greater than the current one is reached. The reason for stopping
2320 in this case will be 'location-reached'.
2325 The corresponding GDB command is 'until'.
2331 -exec-until recursive2.c:6
2335 *stopped,reason="location-reached",frame={func="main",args=[],
2336 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
2340 File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
2342 27.14 GDB/MI Stack Manipulation Commands
2343 ========================================
2345 The '-enable-frame-filters' Command
2346 -----------------------------------
2348 -enable-frame-filters
2350 GDB allows Python-based frame filters to affect the output of the MI
2351 commands relating to stack traces. As there is no way to implement this
2352 in a fully backward-compatible way, a front end must request that this
2353 functionality be enabled.
2355 Once enabled, this feature cannot be disabled.
2357 Note that if Python support has not been compiled into GDB, this
2358 command will still succeed (and do nothing).
2360 The '-stack-info-frame' Command
2361 -------------------------------
2368 Get info on the selected frame.
2373 The corresponding GDB command is 'info frame' or 'frame' (without
2381 ^done,frame={level="1",addr="0x0001076c",func="callee3",
2382 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2383 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
2386 The '-stack-info-depth' Command
2387 -------------------------------
2392 -stack-info-depth [ MAX-DEPTH ]
2394 Return the depth of the stack. If the integer argument MAX-DEPTH is
2395 specified, do not count beyond MAX-DEPTH frames.
2400 There's no equivalent GDB command.
2405 For a stack with frame levels 0 through 11:
2414 -stack-info-depth 12
2417 -stack-info-depth 11
2420 -stack-info-depth 13
2424 The '-stack-list-arguments' Command
2425 -----------------------------------
2430 -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
2431 [ LOW-FRAME HIGH-FRAME ]
2433 Display a list of the arguments for the frames between LOW-FRAME and
2434 HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
2435 list the arguments for the whole call stack. If the two arguments are
2436 equal, show the single frame at the corresponding level. It is an error
2437 if LOW-FRAME is larger than the actual number of frames. On the other
2438 hand, HIGH-FRAME may be larger than the actual number of frames, in
2439 which case only existing frames will be returned.
2441 If PRINT-VALUES is 0 or '--no-values', print only the names of the
2442 variables; if it is 1 or '--all-values', print also their values; and if
2443 it is 2 or '--simple-values', print the name, type and value for simple
2444 data types, and the name and type for arrays, structures and unions. If
2445 the option '--no-frame-filters' is supplied, then Python frame filters
2446 will not be executed.
2448 If the '--skip-unavailable' option is specified, arguments that are
2449 not available are not listed. Partially available arguments are still
2452 Use of this command to obtain arguments in a single frame is
2453 deprecated in favor of the '-stack-list-variables' command.
2458 GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args'
2459 command which partially overlaps with the functionality of
2460 '-stack-list-arguments'.
2469 frame={level="0",addr="0x00010734",func="callee4",
2470 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2471 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
2472 frame={level="1",addr="0x0001076c",func="callee3",
2473 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2474 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
2475 frame={level="2",addr="0x0001078c",func="callee2",
2476 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2477 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
2478 frame={level="3",addr="0x000107b4",func="callee1",
2479 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2480 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
2481 frame={level="4",addr="0x000107e0",func="main",
2482 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
2483 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
2485 -stack-list-arguments 0
2488 frame={level="0",args=[]},
2489 frame={level="1",args=[name="strarg"]},
2490 frame={level="2",args=[name="intarg",name="strarg"]},
2491 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
2492 frame={level="4",args=[]}]
2494 -stack-list-arguments 1
2497 frame={level="0",args=[]},
2499 args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
2500 frame={level="2",args=[
2501 {name="intarg",value="2"},
2502 {name="strarg",value="0x11940 \"A string argument.\""}]},
2503 {frame={level="3",args=[
2504 {name="intarg",value="2"},
2505 {name="strarg",value="0x11940 \"A string argument.\""},
2506 {name="fltarg",value="3.5"}]},
2507 frame={level="4",args=[]}]
2509 -stack-list-arguments 0 2 2
2510 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
2512 -stack-list-arguments 1 2 2
2513 ^done,stack-args=[frame={level="2",
2514 args=[{name="intarg",value="2"},
2515 {name="strarg",value="0x11940 \"A string argument.\""}]}]
2518 The '-stack-list-frames' Command
2519 --------------------------------
2524 -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ]
2526 List the frames currently on the stack. For each frame it displays
2530 The frame number, 0 being the topmost frame, i.e., the innermost
2533 The '$pc' value for that frame.
2537 File name of the source file where the function lives.
2539 The full file name of the source file where the function lives.
2541 Line number corresponding to the '$pc'.
2543 The shared library where this function is defined. This is only
2544 given if the frame's function is not known.
2546 If invoked without arguments, this command prints a backtrace for the
2547 whole stack. If given two integer arguments, it shows the frames whose
2548 levels are between the two arguments (inclusive). If the two arguments
2549 are equal, it shows the single frame at the corresponding level. It is
2550 an error if LOW-FRAME is larger than the actual number of frames. On
2551 the other hand, HIGH-FRAME may be larger than the actual number of
2552 frames, in which case only existing frames will be returned. If the
2553 option '--no-frame-filters' is supplied, then Python frame filters will
2559 The corresponding GDB commands are 'backtrace' and 'where'.
2564 Full stack backtrace:
2569 [frame={level="0",addr="0x0001076c",func="foo",
2570 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
2571 frame={level="1",addr="0x000107a4",func="foo",
2572 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2573 frame={level="2",addr="0x000107a4",func="foo",
2574 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2575 frame={level="3",addr="0x000107a4",func="foo",
2576 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2577 frame={level="4",addr="0x000107a4",func="foo",
2578 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2579 frame={level="5",addr="0x000107a4",func="foo",
2580 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2581 frame={level="6",addr="0x000107a4",func="foo",
2582 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2583 frame={level="7",addr="0x000107a4",func="foo",
2584 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2585 frame={level="8",addr="0x000107a4",func="foo",
2586 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2587 frame={level="9",addr="0x000107a4",func="foo",
2588 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2589 frame={level="10",addr="0x000107a4",func="foo",
2590 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2591 frame={level="11",addr="0x00010738",func="main",
2592 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
2595 Show frames between LOW_FRAME and HIGH_FRAME:
2598 -stack-list-frames 3 5
2600 [frame={level="3",addr="0x000107a4",func="foo",
2601 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2602 frame={level="4",addr="0x000107a4",func="foo",
2603 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
2604 frame={level="5",addr="0x000107a4",func="foo",
2605 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
2608 Show a single frame:
2611 -stack-list-frames 3 3
2613 [frame={level="3",addr="0x000107a4",func="foo",
2614 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
2617 The '-stack-list-locals' Command
2618 --------------------------------
2623 -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
2625 Display the local variable names for the selected frame. If
2626 PRINT-VALUES is 0 or '--no-values', print only the names of the
2627 variables; if it is 1 or '--all-values', print also their values; and if
2628 it is 2 or '--simple-values', print the name, type and value for simple
2629 data types, and the name and type for arrays, structures and unions. In
2630 this last case, a frontend can immediately display the value of simple
2631 data types and create variable objects for other data types when the
2632 user wishes to explore their values in more detail. If the option
2633 '--no-frame-filters' is supplied, then Python frame filters will not be
2636 If the '--skip-unavailable' option is specified, local variables that
2637 are not available are not listed. Partially available local variables
2638 are still displayed, however.
2640 This command is deprecated in favor of the '-stack-list-variables'
2646 'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'.
2652 -stack-list-locals 0
2653 ^done,locals=[name="A",name="B",name="C"]
2655 -stack-list-locals --all-values
2656 ^done,locals=[{name="A",value="1"},{name="B",value="2"},
2657 {name="C",value="{1, 2, 3}"}]
2658 -stack-list-locals --simple-values
2659 ^done,locals=[{name="A",type="int",value="1"},
2660 {name="B",type="int",value="2"},{name="C",type="int [3]"}]
2663 The '-stack-list-variables' Command
2664 -----------------------------------
2669 -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
2671 Display the names of local variables and function arguments for the
2672 selected frame. If PRINT-VALUES is 0 or '--no-values', print only the
2673 names of the variables; if it is 1 or '--all-values', print also their
2674 values; and if it is 2 or '--simple-values', print the name, type and
2675 value for simple data types, and the name and type for arrays,
2676 structures and unions. If the option '--no-frame-filters' is supplied,
2677 then Python frame filters will not be executed.
2679 If the '--skip-unavailable' option is specified, local variables and
2680 arguments that are not available are not listed. Partially available
2681 arguments and local variables are still displayed, however.
2687 -stack-list-variables --thread 1 --frame 0 --all-values
2688 ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}]
2691 The '-stack-select-frame' Command
2692 ---------------------------------
2697 -stack-select-frame FRAMENUM
2699 Change the selected frame. Select a different frame FRAMENUM on the
2702 This command in deprecated in favor of passing the '--frame' option
2708 The corresponding GDB commands are 'frame', 'up', 'down',
2709 'select-frame', 'up-silent', and 'down-silent'.
2715 -stack-select-frame 2
2720 File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
2722 27.15 GDB/MI Variable Objects
2723 =============================
2725 Introduction to Variable Objects
2726 --------------------------------
2728 Variable objects are "object-oriented" MI interface for examining and
2729 changing values of expressions. Unlike some other MI interfaces that
2730 work with expressions, variable objects are specifically designed for
2731 simple and efficient presentation in the frontend. A variable object is
2732 identified by string name. When a variable object is created, the
2733 frontend specifies the expression for that variable object. The
2734 expression can be a simple variable, or it can be an arbitrary complex
2735 expression, and can even involve CPU registers. After creating a
2736 variable object, the frontend can invoke other variable object
2737 operations--for example to obtain or change the value of a variable
2738 object, or to change display format.
2740 Variable objects have hierarchical tree structure. Any variable
2741 object that corresponds to a composite type, such as structure in C, has
2742 a number of child variable objects, for example corresponding to each
2743 element of a structure. A child variable object can itself have
2744 children, recursively. Recursion ends when we reach leaf variable
2745 objects, which always have built-in types. Child variable objects are
2746 created only by explicit request, so if a frontend is not interested in
2747 the children of a particular variable object, no child will be created.
2749 For a leaf variable object it is possible to obtain its value as a
2750 string, or set the value from a string. String value can be also
2751 obtained for a non-leaf variable object, but it's generally a string
2752 that only indicates the type of the object, and does not list its
2753 contents. Assignment to a non-leaf variable object is not allowed.
2755 A frontend does not need to read the values of all variable objects
2756 each time the program stops. Instead, MI provides an update command
2757 that lists all variable objects whose values has changed since the last
2758 update operation. This considerably reduces the amount of data that
2759 must be transferred to the frontend. As noted above, children variable
2760 objects are created on demand, and only leaf variable objects have a
2761 real value. As result, gdb will read target memory only for leaf
2762 variables that frontend has created.
2764 The automatic update is not always desirable. For example, a
2765 frontend might want to keep a value of some expression for future
2766 reference, and never update it. For another example, fetching memory is
2767 relatively slow for embedded targets, so a frontend might want to
2768 disable automatic update for the variables that are either not visible
2769 on the screen, or "closed". This is possible using so called "frozen
2770 variable objects". Such variable objects are never implicitly updated.
2772 Variable objects can be either "fixed" or "floating". For the fixed
2773 variable object, the expression is parsed when the variable object is
2774 created, including associating identifiers to specific variables. The
2775 meaning of expression never changes. For a floating variable object the
2776 values of variables whose names appear in the expressions are
2777 re-evaluated every time in the context of the current frame. Consider
2782 struct work_state state;
2788 If a fixed variable object for the 'state' variable is created in
2789 this function, and we enter the recursive call, the variable object will
2790 report the value of 'state' in the top-level 'do_work' invocation. On
2791 the other hand, a floating variable object will report the value of
2792 'state' in the current frame.
2794 If an expression specified when creating a fixed variable object
2795 refers to a local variable, the variable object becomes bound to the
2796 thread and frame in which the variable object is created. When such
2797 variable object is updated, GDB makes sure that the thread/frame
2798 combination the variable object is bound to still exists, and
2799 re-evaluates the variable object in context of that thread/frame.
2801 The following is the complete set of GDB/MI operations defined to
2802 access this functionality:
2804 *Operation* *Description*
2806 '-enable-pretty-printing' enable Python-based pretty-printing
2807 '-var-create' create a variable object
2808 '-var-delete' delete the variable object and/or its
2810 '-var-set-format' set the display format of this variable
2811 '-var-show-format' show the display format of this variable
2812 '-var-info-num-children' tells how many children this object has
2813 '-var-list-children' return a list of the object's children
2814 '-var-info-type' show the type of this variable object
2815 '-var-info-expression' print parent-relative expression that
2816 this variable object represents
2817 '-var-info-path-expression' print full expression that this variable
2819 '-var-show-attributes' is this variable editable? does it exist
2821 '-var-evaluate-expression' get the value of this variable
2822 '-var-assign' set the value of this variable
2823 '-var-update' update the variable and its children
2824 '-var-set-frozen' set frozeness attribute
2825 '-var-set-update-range' set range of children to display on
2828 In the next subsection we describe each operation in detail and
2829 suggest how it can be used.
2831 Description And Use of Operations on Variable Objects
2832 -----------------------------------------------------
2834 The '-enable-pretty-printing' Command
2835 -------------------------------------
2837 -enable-pretty-printing
2839 GDB allows Python-based visualizers to affect the output of the MI
2840 variable object commands. However, because there was no way to
2841 implement this in a fully backward-compatible way, a front end must
2842 request that this functionality be enabled.
2844 Once enabled, this feature cannot be disabled.
2846 Note that if Python support has not been compiled into GDB, this
2847 command will still succeed (and do nothing).
2849 This feature is currently (as of GDB 7.0) experimental, and may work
2850 differently in future versions of GDB.
2852 The '-var-create' Command
2853 -------------------------
2858 -var-create {NAME | "-"}
2859 {FRAME-ADDR | "*" | "@"} EXPRESSION
2861 This operation creates a variable object, which allows the monitoring
2862 of a variable, the result of an expression, a memory cell or a CPU
2865 The NAME parameter is the string by which the object can be
2866 referenced. It must be unique. If '-' is specified, the varobj system
2867 will generate a string "varNNNNNN" automatically. It will be unique
2868 provided that one does not specify NAME of that format. The command
2869 fails if a duplicate name is found.
2871 The frame under which the expression should be evaluated can be
2872 specified by FRAME-ADDR. A '*' indicates that the current frame should
2873 be used. A '@' indicates that a floating variable object must be
2876 EXPRESSION is any expression valid on the current language set (must
2877 not begin with a '*'), or one of the following:
2879 * '*ADDR', where ADDR is the address of a memory cell
2881 * '*ADDR-ADDR' -- a memory address range (TBD)
2883 * '$REGNAME' -- a CPU register name
2885 A varobj's contents may be provided by a Python-based pretty-printer.
2886 In this case the varobj is known as a "dynamic varobj". Dynamic varobjs
2887 have slightly different semantics in some cases. If the
2888 '-enable-pretty-printing' command is not sent, then GDB will never
2889 create a dynamic varobj. This ensures backward compatibility for
2895 This operation returns attributes of the newly-created varobj. These
2899 The name of the varobj.
2902 The number of children of the varobj. This number is not
2903 necessarily reliable for a dynamic varobj. Instead, you must
2904 examine the 'has_more' attribute.
2907 The varobj's scalar value. For a varobj whose type is some sort of
2908 aggregate (e.g., a 'struct'), or for a dynamic varobj, this value
2909 will not be interesting.
2912 The varobj's type. This is a string representation of the type, as
2913 would be printed by the GDB CLI. If 'print object' (*note set print
2914 object: Print Settings.) is set to 'on', the _actual_ (derived)
2915 type of the object is shown rather than the _declared_ one.
2918 If a variable object is bound to a specific thread, then this is
2919 the thread's identifier.
2922 For a dynamic varobj, this indicates whether there appear to be any
2923 children available. For a non-dynamic varobj, this will be 0.
2926 This attribute will be present and have the value '1' if the varobj
2927 is a dynamic varobj. If the varobj is not a dynamic varobj, then
2928 this attribute will not be present.
2931 A dynamic varobj can supply a display hint to the front end. The
2932 value comes directly from the Python pretty-printer object's
2933 'display_hint' method. *Note Pretty Printing API::.
2935 Typical output will look like this:
2937 name="NAME",numchild="N",type="TYPE",thread-id="M",
2940 The '-var-delete' Command
2941 -------------------------
2946 -var-delete [ -c ] NAME
2948 Deletes a previously created variable object and all of its children.
2949 With the '-c' option, just deletes the children.
2951 Returns an error if the object NAME is not found.
2953 The '-var-set-format' Command
2954 -----------------------------
2959 -var-set-format NAME FORMAT-SPEC
2961 Sets the output format for the value of the object NAME to be
2964 The syntax for the FORMAT-SPEC is as follows:
2967 {binary | decimal | hexadecimal | octal | natural}
2969 The natural format is the default format choosen automatically based
2970 on the variable type (like decimal for an 'int', hex for pointers,
2973 For a variable with children, the format is set only on the variable
2974 itself, and the children are not affected.
2976 The '-var-show-format' Command
2977 ------------------------------
2982 -var-show-format NAME
2984 Returns the format used to display the value of the object NAME.
2989 The '-var-info-num-children' Command
2990 ------------------------------------
2995 -var-info-num-children NAME
2997 Returns the number of children of a variable object NAME:
3001 Note that this number is not completely reliable for a dynamic
3002 varobj. It will return the current number of children, but more
3003 children may be available.
3005 The '-var-list-children' Command
3006 --------------------------------
3011 -var-list-children [PRINT-VALUES] NAME [FROM TO]
3013 Return a list of the children of the specified variable object and
3014 create variable objects for them, if they do not already exist. With a
3015 single argument or if PRINT-VALUES has a value of 0 or '--no-values',
3016 print only the names of the variables; if PRINT-VALUES is 1 or
3017 '--all-values', also print their values; and if it is 2 or
3018 '--simple-values' print the name and value for simple data types and
3019 just the name for arrays, structures and unions.
3021 FROM and TO, if specified, indicate the range of children to report.
3022 If FROM or TO is less than zero, the range is reset and all children
3023 will be reported. Otherwise, children starting at FROM (zero-based) and
3024 up to and excluding TO will be reported.
3026 If a child range is requested, it will only affect the current call
3027 to '-var-list-children', but not future calls to '-var-update'. For
3028 this, you must instead use '-var-set-update-range'. The intent of this
3029 approach is to enable a front end to implement any update approach it
3030 likes; for example, scrolling a view may cause the front end to request
3031 more children with '-var-list-children', and then the front end could
3032 call '-var-set-update-range' with a different range to ensure that
3033 future updates are restricted to just the visible items.
3035 For each child the following results are returned:
3038 Name of the variable object created for this child.
3041 The expression to be shown to the user by the front end to
3042 designate this child. For example this may be the name of a
3045 For a dynamic varobj, this value cannot be used to form an
3046 expression. There is no way to do this at all with a dynamic
3049 For C/C++ structures there are several pseudo children returned to
3050 designate access qualifiers. For these pseudo children EXP is
3051 'public', 'private', or 'protected'. In this case the type and
3052 value are not present.
3054 A dynamic varobj will not report the access qualifying
3055 pseudo-children, regardless of the language. This information is
3056 not available at all with a dynamic varobj.
3059 Number of children this child has. For a dynamic varobj, this will
3063 The type of the child. If 'print object' (*note set print object:
3064 Print Settings.) is set to 'on', the _actual_ (derived) type of the
3065 object is shown rather than the _declared_ one.
3068 If values were requested, this is the value.
3071 If this variable object is associated with a thread, this is the
3072 thread id. Otherwise this result is not present.
3075 If the variable object is frozen, this variable will be present
3079 A dynamic varobj can supply a display hint to the front end. The
3080 value comes directly from the Python pretty-printer object's
3081 'display_hint' method. *Note Pretty Printing API::.
3084 This attribute will be present and have the value '1' if the varobj
3085 is a dynamic varobj. If the varobj is not a dynamic varobj, then
3086 this attribute will not be present.
3088 The result may have its own attributes:
3091 A dynamic varobj can supply a display hint to the front end. The
3092 value comes directly from the Python pretty-printer object's
3093 'display_hint' method. *Note Pretty Printing API::.
3096 This is an integer attribute which is nonzero if there are children
3097 remaining after the end of the selected range.
3103 -var-list-children n
3104 ^done,numchild=N,children=[child={name=NAME,exp=EXP,
3105 numchild=N,type=TYPE},(repeats N times)]
3107 -var-list-children --all-values n
3108 ^done,numchild=N,children=[child={name=NAME,exp=EXP,
3109 numchild=N,value=VALUE,type=TYPE},(repeats N times)]
3111 The '-var-info-type' Command
3112 ----------------------------
3119 Returns the type of the specified variable NAME. The type is
3120 returned as a string in the same format as it is output by the GDB CLI:
3124 The '-var-info-expression' Command
3125 ----------------------------------
3130 -var-info-expression NAME
3132 Returns a string that is suitable for presenting this variable object
3133 in user interface. The string is generally not valid expression in the
3134 current language, and cannot be evaluated.
3136 For example, if 'a' is an array, and variable object 'A' was created
3137 for 'a', then we'll get this output:
3139 (gdb) -var-info-expression A.1
3140 ^done,lang="C",exp="1"
3142 Here, the value of 'lang' is the language name, which can be found in
3143 *note Supported Languages::.
3145 Note that the output of the '-var-list-children' command also
3146 includes those expressions, so the '-var-info-expression' command is of
3149 The '-var-info-path-expression' Command
3150 ---------------------------------------
3155 -var-info-path-expression NAME
3157 Returns an expression that can be evaluated in the current context
3158 and will yield the same value that a variable object has. Compare this
3159 with the '-var-info-expression' command, which result can be used only
3160 for UI presentation. Typical use of the '-var-info-path-expression'
3161 command is creating a watchpoint from a variable object.
3163 This command is currently not valid for children of a dynamic varobj,
3164 and will give an error when invoked on one.
3166 For example, suppose 'C' is a C++ class, derived from class 'Base',
3167 and that the 'Base' class has a member called 'm_size'. Assume a
3168 variable 'c' is has the type of 'C' and a variable object 'C' was
3169 created for variable 'c'. Then, we'll get this output:
3170 (gdb) -var-info-path-expression C.Base.public.m_size
3171 ^done,path_expr=((Base)c).m_size)
3173 The '-var-show-attributes' Command
3174 ----------------------------------
3179 -var-show-attributes NAME
3181 List attributes of the specified variable object NAME:
3183 status=ATTR [ ( ,ATTR )* ]
3185 where ATTR is '{ { editable | noneditable } | TBD }'.
3187 The '-var-evaluate-expression' Command
3188 --------------------------------------
3193 -var-evaluate-expression [-f FORMAT-SPEC] NAME
3195 Evaluates the expression that is represented by the specified
3196 variable object and returns its value as a string. The format of the
3197 string can be specified with the '-f' option. The possible values of
3198 this option are the same as for '-var-set-format' (*note
3199 -var-set-format::). If the '-f' option is not specified, the current
3200 display format will be used. The current display format can be changed
3201 using the '-var-set-format' command.
3205 Note that one must invoke '-var-list-children' for a variable before
3206 the value of a child variable can be evaluated.
3208 The '-var-assign' Command
3209 -------------------------
3214 -var-assign NAME EXPRESSION
3216 Assigns the value of EXPRESSION to the variable object specified by
3217 NAME. The object must be 'editable'. If the variable's value is
3218 altered by the assign, the variable will show up in any subsequent
3229 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
3232 The '-var-update' Command
3233 -------------------------
3238 -var-update [PRINT-VALUES] {NAME | "*"}
3240 Reevaluate the expressions corresponding to the variable object NAME
3241 and all its direct and indirect children, and return the list of
3242 variable objects whose values have changed; NAME must be a root variable
3243 object. Here, "changed" means that the result of
3244 '-var-evaluate-expression' before and after the '-var-update' is
3245 different. If '*' is used as the variable object names, all existing
3246 variable objects are updated, except for frozen ones (*note
3247 -var-set-frozen::). The option PRINT-VALUES determines whether both
3248 names and values, or just names are printed. The possible values of
3249 this option are the same as for '-var-list-children' (*note
3250 -var-list-children::). It is recommended to use the '--all-values'
3251 option, to reduce the number of MI commands needed on each program stop.
3253 With the '*' parameter, if a variable object is bound to a currently
3254 running thread, it will not be updated, without any diagnostic.
3256 If '-var-set-update-range' was previously used on a varobj, then only
3257 the selected range of children will be reported.
3259 '-var-update' reports all the changed varobjs in a tuple named
3262 Each item in the change list is itself a tuple holding:
3265 The name of the varobj.
3268 If values were requested for this update, then this field will be
3269 present and will hold the value of the varobj.
3272 This field is a string which may take one of three values:
3275 The variable object's current value is valid.
3278 The variable object does not currently hold a valid value but
3279 it may hold one in the future if its associated expression
3280 comes back into scope.
3283 The variable object no longer holds a valid value. This can
3284 occur when the executable file being debugged has changed,
3285 either through recompilation or by using the GDB 'file'
3286 command. The front end should normally choose to delete these
3289 In the future new values may be added to this list so the front
3290 should be prepared for this possibility. *Note GDB/MI Development
3291 and Front Ends: GDB/MI Development and Front Ends.
3294 This is only present if the varobj is still valid. If the type
3295 changed, then this will be the string 'true'; otherwise it will be
3298 When a varobj's type changes, its children are also likely to have
3299 become incorrect. Therefore, the varobj's children are
3300 automatically deleted when this attribute is 'true'. Also, the
3301 varobj's update range, when set using the '-var-set-update-range'
3305 If the varobj's type changed, then this field will be present and
3306 will hold the new type.
3309 For a dynamic varobj, if the number of children changed, or if the
3310 type changed, this will be the new number of children.
3312 The 'numchild' field in other varobj responses is generally not
3313 valid for a dynamic varobj - it will show the number of children
3314 that GDB knows about, but because dynamic varobjs lazily
3315 instantiate their children, this will not reflect the number of
3316 children which may be available.
3318 The 'new_num_children' attribute only reports changes to the number
3319 of children known by GDB. This is the only way to detect whether
3320 an update has removed children (which necessarily can only happen
3321 at the end of the update range).
3324 The display hint, if any.
3327 This is an integer value, which will be 1 if there are more
3328 children available outside the varobj's update range.
3331 This attribute will be present and have the value '1' if the varobj
3332 is a dynamic varobj. If the varobj is not a dynamic varobj, then
3333 this attribute will not be present.
3336 If new children were added to a dynamic varobj within the selected
3337 update range (as set by '-var-set-update-range'), then they will be
3338 listed in this attribute.
3347 -var-update --all-values var1
3348 ^done,changelist=[{name="var1",value="3",in_scope="true",
3349 type_changed="false"}]
3352 The '-var-set-frozen' Command
3353 -----------------------------
3358 -var-set-frozen NAME FLAG
3360 Set the frozenness flag on the variable object NAME. The FLAG
3361 parameter should be either '1' to make the variable frozen or '0' to
3362 make it unfrozen. If a variable object is frozen, then neither itself,
3363 nor any of its children, are implicitly updated by '-var-update' of a
3364 parent variable or by '-var-update *'. Only '-var-update' of the
3365 variable itself will update its value and values of its children. After
3366 a variable object is unfrozen, it is implicitly updated by all
3367 subsequent '-var-update' operations. Unfreezing a variable does not
3368 update it, only subsequent '-var-update' does.
3378 The '-var-set-update-range' command
3379 -----------------------------------
3384 -var-set-update-range NAME FROM TO
3386 Set the range of children to be returned by future invocations of
3389 FROM and TO indicate the range of children to report. If FROM or TO
3390 is less than zero, the range is reset and all children will be reported.
3391 Otherwise, children starting at FROM (zero-based) and up to and
3392 excluding TO will be reported.
3398 -var-set-update-range V 1 2
3401 The '-var-set-visualizer' command
3402 ---------------------------------
3407 -var-set-visualizer NAME VISUALIZER
3409 Set a visualizer for the variable object NAME.
3411 VISUALIZER is the visualizer to use. The special value 'None' means
3412 to disable any visualizer in use.
3414 If not 'None', VISUALIZER must be a Python expression. This
3415 expression must evaluate to a callable object which accepts a single
3416 argument. GDB will call this object with the value of the varobj NAME
3417 as an argument (this is done so that the same Python pretty-printing
3418 code can be used for both the CLI and MI). When called, this object must
3419 return an object which conforms to the pretty-printing interface (*note
3420 Pretty Printing API::).
3422 The pre-defined function 'gdb.default_visualizer' may be used to
3423 select a visualizer by following the built-in process (*note Selecting
3424 Pretty-Printers::). This is done automatically when a varobj is
3425 created, and so ordinarily is not needed.
3427 This feature is only available if Python support is enabled. The MI
3428 command '-list-features' (*note GDB/MI Support Commands::) can be used
3434 Resetting the visualizer:
3437 -var-set-visualizer V None
3440 Reselecting the default (type-based) visualizer:
3443 -var-set-visualizer V gdb.default_visualizer
3446 Suppose 'SomeClass' is a visualizer class. A lambda expression can
3447 be used to instantiate this class for a varobj:
3450 -var-set-visualizer V "lambda val: SomeClass()"
3454 File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
3456 27.16 GDB/MI Data Manipulation
3457 ==============================
3459 This section describes the GDB/MI commands that manipulate data: examine
3460 memory and registers, evaluate expressions, etc.
3462 The '-data-disassemble' Command
3463 -------------------------------
3469 [ -s START-ADDR -e END-ADDR ]
3470 | [ -f FILENAME -l LINENUM [ -n LINES ] ]
3476 is the beginning address (or '$pc')
3480 is the name of the file to disassemble
3482 is the line number to disassemble around
3484 is the number of disassembly lines to be produced. If it is -1,
3485 the whole function will be disassembled, in case no END-ADDR is
3486 specified. If END-ADDR is specified as a non-zero value, and LINES
3487 is lower than the number of disassembly lines between START-ADDR
3488 and END-ADDR, only LINES lines are displayed; if LINES is higher
3489 than the number of lines between START-ADDR and END-ADDR, only the
3490 lines up to END-ADDR are displayed.
3492 is either 0 (meaning only disassembly), 1 (meaning mixed source and
3493 disassembly), 2 (meaning disassembly with raw opcodes), or 3
3494 (meaning mixed source and disassembly with raw opcodes).
3499 The result of the '-data-disassemble' command will be a list named
3500 'asm_insns', the contents of this list depend on the MODE used with the
3501 '-data-disassemble' command.
3503 For modes 0 and 2 the 'asm_insns' list contains tuples with the
3507 The address at which this instruction was disassembled.
3510 The name of the function this instruction is within.
3513 The decimal offset in bytes from the start of 'func-name'.
3516 The text disassembly for this 'address'.
3519 This field is only present for mode 2. This contains the raw
3520 opcode bytes for the 'inst' field.
3522 For modes 1 and 3 the 'asm_insns' list contains tuples named
3523 'src_and_asm_line', each of which has the following fields:
3526 The line number within 'file'.
3529 The file name from the compilation unit. This might be an absolute
3530 file name or a relative file name depending on the compile command
3534 Absolute file name of 'file'. It is converted to a canonical form
3535 using the source file search path (*note Specifying Source
3536 Directories: Source Path.) and after resolving all the symbolic
3539 If the source file is not found this field will contain the path as
3540 present in the debug information.
3543 This is a list of tuples containing the disassembly for 'line' in
3544 'file'. The fields of each tuple are the same as for
3545 '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name',
3546 'offset', 'inst', and optionally 'opcodes'.
3548 Note that whatever included in the 'inst' field, is not manipulated
3549 directly by GDB/MI, i.e., it is not possible to adjust its format.
3554 The corresponding GDB command is 'disassemble'.
3559 Disassemble from the current value of '$pc' to '$pc + 20':
3562 -data-disassemble -s $pc -e "$pc + 20" -- 0
3565 {address="0x000107c0",func-name="main",offset="4",
3567 {address="0x000107c4",func-name="main",offset="8",
3568 inst="sethi %hi(0x11800), %o2"},
3569 {address="0x000107c8",func-name="main",offset="12",
3570 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
3571 {address="0x000107cc",func-name="main",offset="16",
3572 inst="sethi %hi(0x11800), %o2"},
3573 {address="0x000107d0",func-name="main",offset="20",
3574 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
3577 Disassemble the whole 'main' function. Line 32 is part of 'main'.
3579 -data-disassemble -f basics.c -l 32 -- 0
3581 {address="0x000107bc",func-name="main",offset="0",
3582 inst="save %sp, -112, %sp"},
3583 {address="0x000107c0",func-name="main",offset="4",
3585 {address="0x000107c4",func-name="main",offset="8",
3586 inst="sethi %hi(0x11800), %o2"},
3588 {address="0x0001081c",func-name="main",offset="96",inst="ret "},
3589 {address="0x00010820",func-name="main",offset="100",inst="restore "}]
3592 Disassemble 3 instructions from the start of 'main':
3595 -data-disassemble -f basics.c -l 32 -n 3 -- 0
3597 {address="0x000107bc",func-name="main",offset="0",
3598 inst="save %sp, -112, %sp"},
3599 {address="0x000107c0",func-name="main",offset="4",
3601 {address="0x000107c4",func-name="main",offset="8",
3602 inst="sethi %hi(0x11800), %o2"}]
3605 Disassemble 3 instructions from the start of 'main' in mixed mode:
3608 -data-disassemble -f basics.c -l 32 -n 3 -- 1
3610 src_and_asm_line={line="31",
3611 file="../../../src/gdb/testsuite/gdb.mi/basics.c",
3612 fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
3613 line_asm_insn=[{address="0x000107bc",
3614 func-name="main",offset="0",inst="save %sp, -112, %sp"}]},
3615 src_and_asm_line={line="32",
3616 file="../../../src/gdb/testsuite/gdb.mi/basics.c",
3617 fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
3618 line_asm_insn=[{address="0x000107c0",
3619 func-name="main",offset="4",inst="mov 2, %o0"},
3620 {address="0x000107c4",func-name="main",offset="8",
3621 inst="sethi %hi(0x11800), %o2"}]}]
3624 The '-data-evaluate-expression' Command
3625 ---------------------------------------
3630 -data-evaluate-expression EXPR
3632 Evaluate EXPR as an expression. The expression could contain an
3633 inferior function call. The function call will execute synchronously.
3634 If the expression contains spaces, it must be enclosed in double quotes.
3639 The corresponding GDB commands are 'print', 'output', and 'call'. In
3640 'gdbtk' only, there's a corresponding 'gdb_eval' command.
3645 In the following example, the numbers that precede the commands are the
3646 "tokens" described in *note GDB/MI Command Syntax: GDB/MI Command
3647 Syntax. Notice how GDB/MI returns the same tokens in its output.
3649 211-data-evaluate-expression A
3652 311-data-evaluate-expression &A
3653 311^done,value="0xefffeb7c"
3655 411-data-evaluate-expression A+3
3658 511-data-evaluate-expression "A + 3"
3662 The '-data-list-changed-registers' Command
3663 ------------------------------------------
3668 -data-list-changed-registers
3670 Display a list of the registers that have changed.
3675 GDB doesn't have a direct analog for this command; 'gdbtk' has the
3676 corresponding command 'gdb_changed_register_list'.
3688 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={
3689 func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
3692 -data-list-changed-registers
3693 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
3694 "10","11","13","14","15","16","17","18","19","20","21","22","23",
3695 "24","25","26","27","28","30","31","64","65","66","67","69"]
3698 The '-data-list-register-names' Command
3699 ---------------------------------------
3704 -data-list-register-names [ ( REGNO )+ ]
3706 Show a list of register names for the current target. If no
3707 arguments are given, it shows a list of the names of all the registers.
3708 If integer numbers are given as arguments, it will print a list of the
3709 names of the registers corresponding to the arguments. To ensure
3710 consistency between a register name and its number, the output list may
3711 include empty register names.
3716 GDB does not have a command which corresponds to
3717 '-data-list-register-names'. In 'gdbtk' there is a corresponding
3718 command 'gdb_regnames'.
3723 For the PPC MBX board:
3725 -data-list-register-names
3726 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
3727 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
3728 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
3729 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
3730 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
3731 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
3732 "", "pc","ps","cr","lr","ctr","xer"]
3734 -data-list-register-names 1 2 3
3735 ^done,register-names=["r1","r2","r3"]
3738 The '-data-list-register-values' Command
3739 ----------------------------------------
3744 -data-list-register-values
3745 [ --skip-unavailable ] FMT [ ( REGNO )*]
3747 Display the registers' contents. The format according to which the
3748 registers' contents are to be returned is given by FMT, followed by an
3749 optional list of numbers specifying the registers to display. A missing
3750 list of numbers indicates that the contents of all the registers must be
3751 returned. The '--skip-unavailable' option indicates that only the
3752 available registers are to be returned.
3754 Allowed formats for FMT are:
3772 The corresponding GDB commands are 'info reg', 'info all-reg', and (in
3773 'gdbtk') 'gdb_fetch_registers'.
3778 For a PPC MBX board (note: line breaks are for readability only, they
3779 don't appear in the actual output):
3782 -data-list-register-values r 64 65
3783 ^done,register-values=[{number="64",value="0xfe00a300"},
3784 {number="65",value="0x00029002"}]
3786 -data-list-register-values x
3787 ^done,register-values=[{number="0",value="0xfe0043c8"},
3788 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
3789 {number="3",value="0x0"},{number="4",value="0xa"},
3790 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
3791 {number="7",value="0xfe011e98"},{number="8",value="0x2"},
3792 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
3793 {number="11",value="0x1"},{number="12",value="0x0"},
3794 {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
3795 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
3796 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
3797 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
3798 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
3799 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
3800 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
3801 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
3802 {number="29",value="0x0"},{number="30",value="0xfe010000"},
3803 {number="31",value="0x0"},{number="32",value="0x0"},
3804 {number="33",value="0x0"},{number="34",value="0x0"},
3805 {number="35",value="0x0"},{number="36",value="0x0"},
3806 {number="37",value="0x0"},{number="38",value="0x0"},
3807 {number="39",value="0x0"},{number="40",value="0x0"},
3808 {number="41",value="0x0"},{number="42",value="0x0"},
3809 {number="43",value="0x0"},{number="44",value="0x0"},
3810 {number="45",value="0x0"},{number="46",value="0x0"},
3811 {number="47",value="0x0"},{number="48",value="0x0"},
3812 {number="49",value="0x0"},{number="50",value="0x0"},
3813 {number="51",value="0x0"},{number="52",value="0x0"},
3814 {number="53",value="0x0"},{number="54",value="0x0"},
3815 {number="55",value="0x0"},{number="56",value="0x0"},
3816 {number="57",value="0x0"},{number="58",value="0x0"},
3817 {number="59",value="0x0"},{number="60",value="0x0"},
3818 {number="61",value="0x0"},{number="62",value="0x0"},
3819 {number="63",value="0x0"},{number="64",value="0xfe00a300"},
3820 {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
3821 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
3822 {number="69",value="0x20002b03"}]
3825 The '-data-read-memory' Command
3826 -------------------------------
3828 This command is deprecated, use '-data-read-memory-bytes' instead.
3833 -data-read-memory [ -o BYTE-OFFSET ]
3834 ADDRESS WORD-FORMAT WORD-SIZE
3835 NR-ROWS NR-COLS [ ASCHAR ]
3840 An expression specifying the address of the first memory word to be
3841 read. Complex expressions containing embedded white space should
3842 be quoted using the C convention.
3845 The format to be used to print the memory words. The notation is
3846 the same as for GDB's 'print' command (*note Output Formats: Output
3850 The size of each memory word in bytes.
3853 The number of rows in the output table.
3856 The number of columns in the output table.
3859 If present, indicates that each row should include an ASCII dump.
3860 The value of ASCHAR is used as a padding character when a byte is
3861 not a member of the printable ASCII character set (printable ASCII
3862 characters are those whose code is between 32 and 126,
3866 An offset to add to the ADDRESS before fetching memory.
3868 This command displays memory contents as a table of NR-ROWS by
3869 NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS *
3870 NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should
3871 less than the requested number of bytes be returned by the target, the
3872 missing words are identified using 'N/A'. The number of bytes read from
3873 the target is returned in 'nr-bytes' and the starting address used to
3874 read memory in 'addr'.
3876 The address of the next/previous row or page is available in
3877 'next-row' and 'prev-row', 'next-page' and 'prev-page'.
3882 The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory
3888 Read six bytes of memory starting at 'bytes+6' but then offset by '-6'
3889 bytes. Format as three rows of two columns. One byte per word.
3890 Display each word in hex.
3893 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
3894 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
3895 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
3896 prev-page="0x0000138a",memory=[
3897 {addr="0x00001390",data=["0x00","0x01"]},
3898 {addr="0x00001392",data=["0x02","0x03"]},
3899 {addr="0x00001394",data=["0x04","0x05"]}]
3902 Read two bytes of memory starting at address 'shorts + 64' and
3903 display as a single word formatted in decimal.
3906 5-data-read-memory shorts+64 d 2 1 1
3907 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
3908 next-row="0x00001512",prev-row="0x0000150e",
3909 next-page="0x00001512",prev-page="0x0000150e",memory=[
3910 {addr="0x00001510",data=["128"]}]
3913 Read thirty two bytes of memory starting at 'bytes+16' and format as
3914 eight rows of four columns. Include a string encoding with 'x' used as
3915 the non-printable character.
3918 4-data-read-memory bytes+16 x 1 8 4 x
3919 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
3920 next-row="0x000013c0",prev-row="0x0000139c",
3921 next-page="0x000013c0",prev-page="0x00001380",memory=[
3922 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
3923 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
3924 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
3925 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
3926 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
3927 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
3928 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
3929 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
3932 The '-data-read-memory-bytes' Command
3933 -------------------------------------
3938 -data-read-memory-bytes [ -o BYTE-OFFSET ]
3944 An expression specifying the address of the first memory word to be
3945 read. Complex expressions containing embedded white space should
3946 be quoted using the C convention.
3949 The number of bytes to read. This should be an integer literal.
3952 The offsets in bytes relative to ADDRESS at which to start reading.
3953 This should be an integer literal. This option is provided so that
3954 a frontend is not required to first evaluate address and then
3955 perform address arithmetics itself.
3957 This command attempts to read all accessible memory regions in the
3958 specified range. First, all regions marked as unreadable in the memory
3959 map (if one is defined) will be skipped. *Note Memory Region
3960 Attributes::. Second, GDB will attempt to read the remaining regions.
3961 For each one, if reading full region results in an errors, GDB will try
3962 to read a subset of the region.
3964 In general, every single byte in the region may be readable or not,
3965 and the only way to read every readable byte is to try a read at every
3966 address, which is not practical. Therefore, GDB will attempt to read
3967 all accessible bytes at either beginning or the end of the region, using
3968 a binary division scheme. This heuristic works well for reading accross
3969 a memory map boundary. Note that if a region has a readable range that
3970 is neither at the beginning or the end, GDB will not read it.
3972 The result record (*note GDB/MI Result Records::) that is output of
3973 the command includes a field named 'memory' whose content is a list of
3974 tuples. Each tuple represent a successfully read memory block and has
3975 the following fields:
3978 The start address of the memory block, as hexadecimal literal.
3981 The end address of the memory block, as hexadecimal literal.
3984 The offset of the memory block, as hexadecimal literal, relative to
3985 the start address passed to '-data-read-memory-bytes'.
3988 The contents of the memory block, in hex.
3993 The corresponding GDB command is 'x'.
3999 -data-read-memory-bytes &a 10
4000 ^done,memory=[{begin="0xbffff154",offset="0x00000000",
4002 contents="01000000020000000300"}]
4005 The '-data-write-memory-bytes' Command
4006 --------------------------------------
4011 -data-write-memory-bytes ADDRESS CONTENTS
4012 -data-write-memory-bytes ADDRESS CONTENTS [COUNT]
4017 An expression specifying the address of the first memory word to be
4018 read. Complex expressions containing embedded white space should
4019 be quoted using the C convention.
4022 The hex-encoded bytes to write.
4025 Optional argument indicating the number of bytes to be written. If
4026 COUNT is greater than CONTENTS' length, GDB will repeatedly write
4027 CONTENTS until it fills COUNT bytes.
4032 There's no corresponding GDB command.
4038 -data-write-memory-bytes &a "aabbccdd"
4043 -data-write-memory-bytes &a "aabbccdd" 16e
4048 File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
4050 27.17 GDB/MI Tracepoint Commands
4051 ================================
4053 The commands defined in this section implement MI support for
4054 tracepoints. For detailed introduction, see *note Tracepoints::.
4056 The '-trace-find' Command
4057 -------------------------
4062 -trace-find MODE [PARAMETERS...]
4064 Find a trace frame using criteria defined by MODE and PARAMETERS.
4065 The following table lists permissible modes and their parameters. For
4066 details of operation, see *note tfind::.
4069 No parameters are required. Stops examining trace frames.
4072 An integer is required as parameter. Selects tracepoint frame with
4076 An integer is required as parameter. Finds next trace frame that
4077 corresponds to tracepoint with the specified number.
4080 An address is required as parameter. Finds next trace frame that
4081 corresponds to any tracepoint at the specified address.
4084 Two addresses are required as parameters. Finds next trace frame
4085 that corresponds to a tracepoint at an address inside the specified
4086 range. Both bounds are considered to be inside the range.
4089 Two addresses are required as parameters. Finds next trace frame
4090 that corresponds to a tracepoint at an address outside the
4091 specified range. Both bounds are considered to be inside the
4095 Line specification is required as parameter. *Note Specify
4096 Location::. Finds next trace frame that corresponds to a
4097 tracepoint at the specified location.
4099 If 'none' was passed as MODE, the response does not have fields.
4100 Otherwise, the response may have the following fields:
4103 This field has either '0' or '1' as the value, depending on whether
4104 a matching tracepoint was found.
4107 The index of the found traceframe. This field is present iff the
4108 'found' field has value of '1'.
4111 The index of the found tracepoint. This field is present iff the
4112 'found' field has value of '1'.
4115 The information about the frame corresponding to the found trace
4116 frame. This field is present only if a trace frame was found.
4117 *Note GDB/MI Frame Information::, for description of this field.
4122 The corresponding GDB command is 'tfind'.
4124 -trace-define-variable
4125 ----------------------
4130 -trace-define-variable NAME [ VALUE ]
4132 Create trace variable NAME if it does not exist. If VALUE is
4133 specified, sets the initial value of the specified trace variable to
4134 that value. Note that the NAME should start with the '$' character.
4139 The corresponding GDB command is 'tvariable'.
4141 The '-trace-frame-collected' Command
4142 ------------------------------------
4147 -trace-frame-collected
4148 [--var-print-values VAR_PVAL]
4149 [--comp-print-values COMP_PVAL]
4150 [--registers-format REGFORMAT]
4153 This command returns the set of collected objects, register names,
4154 trace state variable names, memory ranges and computed expressions that
4155 have been collected at a particular trace frame. The optional
4156 parameters to the command affect the output format in different ways.
4157 See the output description table below for more details.
4159 The reported names can be used in the normal manner to create varobjs
4160 and inspect the objects themselves. The items returned by this command
4161 are categorized so that it is clear which is a variable, which is a
4162 register, which is a trace state variable, which is a memory range and
4163 which is a computed expression.
4165 For instance, if the actions were
4166 collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
4167 collect *(int*)0xaf02bef0@40
4169 the object collected in its entirety would be 'myVar'. The object
4170 'myArray' would be partially collected, because only the element at
4171 index 'myIndex' would be collected. The remaining objects would be
4172 computed expressions.
4174 An example output would be:
4177 -trace-frame-collected
4179 explicit-variables=[{name="myVar",value="1"}],
4180 computed-expressions=[{name="myArray[myIndex]",value="0"},
4181 {name="myObj.field",value="0"},
4182 {name="myPtr->field",value="1"},
4183 {name="myCount + 2",value="3"},
4184 {name="$tvar1 + 1",value="43970027"}],
4185 registers=[{number="0",value="0x7fe2c6e79ec8"},
4186 {number="1",value="0x0"},
4187 {number="2",value="0x4"},
4189 {number="125",value="0x0"}],
4190 tvars=[{name="$tvar1",current="43970026"}],
4191 memory=[{address="0x0000000000602264",length="4"},
4192 {address="0x0000000000615bc0",length="4"}]
4197 'explicit-variables'
4198 The set of objects that have been collected in their entirety (as
4199 opposed to collecting just a few elements of an array or a few
4200 struct members). For each object, its name and value are printed.
4201 The '--var-print-values' option affects how or whether the value
4202 field is output. If VAR_PVAL is 0, then print only the names; if
4203 it is 1, print also their values; and if it is 2, print the name,
4204 type and value for simple data types, and the name and type for
4205 arrays, structures and unions.
4207 'computed-expressions'
4208 The set of computed expressions that have been collected at the
4209 current trace frame. The '--comp-print-values' option affects this
4210 set like the '--var-print-values' option affects the
4211 'explicit-variables' set. See above.
4214 The registers that have been collected at the current trace frame.
4215 For each register collected, the name and current value are
4216 returned. The value is formatted according to the
4217 '--registers-format' option. See the '-data-list-register-values'
4218 command for a list of the allowed formats. The default is 'x'.
4221 The trace state variables that have been collected at the current
4222 trace frame. For each trace state variable collected, the name and
4223 current value are returned.
4226 The set of memory ranges that have been collected at the current
4227 trace frame. Its content is a list of tuples. Each tuple
4228 represents a collected memory range and has the following fields:
4231 The start address of the memory range, as hexadecimal literal.
4234 The length of the memory range, as decimal literal.
4237 The contents of the memory block, in hex. This field is only
4238 present if the '--memory-contents' option is specified.
4243 There is no corresponding GDB command.
4248 -trace-list-variables
4249 ---------------------
4254 -trace-list-variables
4256 Return a table of all defined trace variables. Each element of the
4257 table has the following fields:
4260 The name of the trace variable. This field is always present.
4263 The initial value. This is a 64-bit signed integer. This field is
4267 The value the trace variable has at the moment. This is a 64-bit
4268 signed integer. This field is absent iff current value is not
4269 defined, for example if the trace was never run, or is presently
4275 The corresponding GDB command is 'tvariables'.
4281 -trace-list-variables
4282 ^done,trace-variables={nr_rows="1",nr_cols="3",
4283 hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"},
4284 {width="11",alignment="-1",col_name="initial",colhdr="Initial"},
4285 {width="11",alignment="-1",col_name="current",colhdr="Current"}],
4286 body=[variable={name="$trace_timestamp",initial="0"}
4287 variable={name="$foo",initial="10",current="15"}]}
4296 -trace-save [-r ] FILENAME
4298 Saves the collected trace data to FILENAME. Without the '-r' option,
4299 the data is downloaded from the target and saved in a local file. With
4300 the '-r' option the target is asked to perform the save.
4305 The corresponding GDB command is 'tsave'.
4315 Starts a tracing experiments. The result of this command does not
4321 The corresponding GDB command is 'tstart'.
4331 Obtains the status of a tracing experiment. The result may include
4332 the following fields:
4335 May have a value of either '0', when no tracing operations are
4336 supported, '1', when all tracing operations are supported, or
4337 'file' when examining trace file. In the latter case, examining of
4338 trace frame is possible but new tracing experiement cannot be
4339 started. This field is always present.
4342 May have a value of either '0' or '1' depending on whether tracing
4343 experiement is in progress on target. This field is present if
4344 'supported' field is not '0'.
4347 Report the reason why the tracing was stopped last time. This
4348 field may be absent iff tracing was never stopped on target yet.
4349 The value of 'request' means the tracing was stopped as result of
4350 the '-trace-stop' command. The value of 'overflow' means the
4351 tracing buffer is full. The value of 'disconnection' means tracing
4352 was automatically stopped when GDB has disconnected. The value of
4353 'passcount' means tracing was stopped when a tracepoint was passed
4354 a maximal number of times for that tracepoint. This field is
4355 present if 'supported' field is not '0'.
4357 'stopping-tracepoint'
4358 The number of tracepoint whose passcount as exceeded. This field
4359 is present iff the 'stop-reason' field has the value of
4364 The 'frames' field is a count of the total number of trace frames
4365 in the trace buffer, while 'frames-created' is the total created
4366 during the run, including ones that were discarded, such as when a
4367 circular trace buffer filled up. Both fields are optional.
4371 These fields tell the current size of the tracing buffer and the
4372 remaining space. These fields are optional.
4375 The value of the circular trace buffer flag. '1' means that the
4376 trace buffer is circular and old trace frames will be discarded if
4377 necessary to make room, '0' means that the trace buffer is linear
4381 The value of the disconnected tracing flag. '1' means that tracing
4382 will continue after GDB disconnects, '0' means that the trace run
4386 The filename of the trace file being examined. This field is
4387 optional, and only present when examining a trace file.
4392 The corresponding GDB command is 'tstatus'.
4402 Stops a tracing experiment. The result of this command has the same
4403 fields as '-trace-status', except that the 'supported' and 'running'
4404 fields are not output.
4409 The corresponding GDB command is 'tstop'.
4412 File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
4414 27.18 GDB/MI Symbol Query Commands
4415 ==================================
4417 The '-symbol-list-lines' Command
4418 --------------------------------
4423 -symbol-list-lines FILENAME
4425 Print the list of lines that contain code and their associated
4426 program addresses for the given source filename. The entries are sorted
4427 in ascending PC order.
4432 There is no corresponding GDB command.
4438 -symbol-list-lines basics.c
4439 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
4443 File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
4445 27.19 GDB/MI File Commands
4446 ==========================
4448 This section describes the GDB/MI commands to specify executable file
4449 names and to read in and obtain symbol table information.
4451 The '-file-exec-and-symbols' Command
4452 ------------------------------------
4457 -file-exec-and-symbols FILE
4459 Specify the executable file to be debugged. This file is the one
4460 from which the symbol table is also read. If no file is specified, the
4461 command clears the executable and symbol information. If breakpoints
4462 are set when using this command with no arguments, GDB will produce
4463 error messages. Otherwise, no output is produced, except a completion
4469 The corresponding GDB command is 'file'.
4475 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
4479 The '-file-exec-file' Command
4480 -----------------------------
4485 -file-exec-file FILE
4487 Specify the executable file to be debugged. Unlike
4488 '-file-exec-and-symbols', the symbol table is _not_ read from this file.
4489 If used without argument, GDB clears the information about the
4490 executable file. No output is produced, except a completion
4496 The corresponding GDB command is 'exec-file'.
4502 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
4506 The '-file-list-exec-source-file' Command
4507 -----------------------------------------
4512 -file-list-exec-source-file
4514 List the line number, the current source file, and the absolute path
4515 to the current source file for the current executable. The macro
4516 information field has a value of '1' or '0' depending on whether or not
4517 the file includes preprocessor macro information.
4522 The GDB equivalent is 'info source'
4528 123-file-list-exec-source-file
4529 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
4532 The '-file-list-exec-source-files' Command
4533 ------------------------------------------
4538 -file-list-exec-source-files
4540 List the source files for the current executable.
4542 It will always output both the filename and fullname (absolute file
4543 name) of a source file.
4548 The GDB equivalent is 'info sources'. 'gdbtk' has an analogous command
4555 -file-list-exec-source-files
4557 {file=foo.c,fullname=/home/foo.c},
4558 {file=/home/bar.c,fullname=/home/bar.c},
4559 {file=gdb_could_not_find_fullpath.c}]
4562 The '-file-symbol-file' Command
4563 -------------------------------
4568 -file-symbol-file FILE
4570 Read symbol table info from the specified FILE argument. When used
4571 without arguments, clears GDB's symbol table info. No output is
4572 produced, except for a completion notification.
4577 The corresponding GDB command is 'symbol-file'.
4583 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
4588 File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
4590 27.20 GDB/MI Target Manipulation Commands
4591 =========================================
4593 The '-target-attach' Command
4594 ----------------------------
4599 -target-attach PID | GID | FILE
4601 Attach to a process PID or a file FILE outside of GDB, or a thread
4602 group GID. If attaching to a thread group, the id previously returned
4603 by '-list-thread-groups --available' must be used.
4608 The corresponding GDB command is 'attach'.
4615 =thread-created,id="1"
4616 *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}
4620 The '-target-detach' Command
4621 ----------------------------
4626 -target-detach [ PID | GID ]
4628 Detach from the remote target which normally resumes its execution.
4629 If either PID or GID is specified, detaches from either the specified
4630 process, or specified thread group. There's no output.
4635 The corresponding GDB command is 'detach'.
4645 The '-target-disconnect' Command
4646 --------------------------------
4653 Disconnect from the remote target. There's no output and the target
4654 is generally not resumed.
4659 The corresponding GDB command is 'disconnect'.
4669 The '-target-download' Command
4670 ------------------------------
4677 Loads the executable onto the remote target. It prints out an update
4678 message every half second, which includes the fields:
4681 The name of the section.
4683 The size of what has been sent so far for that section.
4685 The size of the section.
4687 The total size of what was sent so far (the current and the
4690 The size of the overall executable to download.
4692 Each message is sent as status record (*note GDB/MI Output Syntax:
4693 GDB/MI Output Syntax.).
4695 In addition, it prints the name and size of the sections, as they are
4696 downloaded. These messages include the following fields:
4699 The name of the section.
4701 The size of the section.
4703 The size of the overall executable to download.
4705 At the end, a summary is printed.
4710 The corresponding GDB command is 'load'.
4715 Note: each status message appears on a single line. Here the messages
4716 have been broken down so that they can fit onto a page.
4720 +download,{section=".text",section-size="6668",total-size="9880"}
4721 +download,{section=".text",section-sent="512",section-size="6668",
4722 total-sent="512",total-size="9880"}
4723 +download,{section=".text",section-sent="1024",section-size="6668",
4724 total-sent="1024",total-size="9880"}
4725 +download,{section=".text",section-sent="1536",section-size="6668",
4726 total-sent="1536",total-size="9880"}
4727 +download,{section=".text",section-sent="2048",section-size="6668",
4728 total-sent="2048",total-size="9880"}
4729 +download,{section=".text",section-sent="2560",section-size="6668",
4730 total-sent="2560",total-size="9880"}
4731 +download,{section=".text",section-sent="3072",section-size="6668",
4732 total-sent="3072",total-size="9880"}
4733 +download,{section=".text",section-sent="3584",section-size="6668",
4734 total-sent="3584",total-size="9880"}
4735 +download,{section=".text",section-sent="4096",section-size="6668",
4736 total-sent="4096",total-size="9880"}
4737 +download,{section=".text",section-sent="4608",section-size="6668",
4738 total-sent="4608",total-size="9880"}
4739 +download,{section=".text",section-sent="5120",section-size="6668",
4740 total-sent="5120",total-size="9880"}
4741 +download,{section=".text",section-sent="5632",section-size="6668",
4742 total-sent="5632",total-size="9880"}
4743 +download,{section=".text",section-sent="6144",section-size="6668",
4744 total-sent="6144",total-size="9880"}
4745 +download,{section=".text",section-sent="6656",section-size="6668",
4746 total-sent="6656",total-size="9880"}
4747 +download,{section=".init",section-size="28",total-size="9880"}
4748 +download,{section=".fini",section-size="28",total-size="9880"}
4749 +download,{section=".data",section-size="3156",total-size="9880"}
4750 +download,{section=".data",section-sent="512",section-size="3156",
4751 total-sent="7236",total-size="9880"}
4752 +download,{section=".data",section-sent="1024",section-size="3156",
4753 total-sent="7748",total-size="9880"}
4754 +download,{section=".data",section-sent="1536",section-size="3156",
4755 total-sent="8260",total-size="9880"}
4756 +download,{section=".data",section-sent="2048",section-size="3156",
4757 total-sent="8772",total-size="9880"}
4758 +download,{section=".data",section-sent="2560",section-size="3156",
4759 total-sent="9284",total-size="9880"}
4760 +download,{section=".data",section-sent="3072",section-size="3156",
4761 total-sent="9796",total-size="9880"}
4762 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
4776 The '-target-select' Command
4777 ----------------------------
4782 -target-select TYPE PARAMETERS ...
4784 Connect GDB to the remote target. This command takes two args:
4787 The type of target, for instance 'remote', etc.
4789 Device names, host names and the like. *Note Commands for Managing
4790 Targets: Target Commands, for more details.
4792 The output is a connection notification, followed by the address at
4793 which the target program is, in the following form:
4795 ^connected,addr="ADDRESS",func="FUNCTION NAME",
4801 The corresponding GDB command is 'target'.
4807 -target-select remote /dev/ttya
4808 ^connected,addr="0xfe00a300",func="??",args=[]
4812 File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
4814 27.21 GDB/MI File Transfer Commands
4815 ===================================
4817 The '-target-file-put' Command
4818 ------------------------------
4823 -target-file-put HOSTFILE TARGETFILE
4825 Copy file HOSTFILE from the host system (the machine running GDB) to
4826 TARGETFILE on the target system.
4831 The corresponding GDB command is 'remote put'.
4837 -target-file-put localfile remotefile
4841 The '-target-file-get' Command
4842 ------------------------------
4847 -target-file-get TARGETFILE HOSTFILE
4849 Copy file TARGETFILE from the target system to HOSTFILE on the host
4855 The corresponding GDB command is 'remote get'.
4861 -target-file-get remotefile localfile
4865 The '-target-file-delete' Command
4866 ---------------------------------
4871 -target-file-delete TARGETFILE
4873 Delete TARGETFILE from the target system.
4878 The corresponding GDB command is 'remote delete'.
4884 -target-file-delete remotefile
4889 File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
4891 27.22 Ada Exceptions GDB/MI Commands
4892 ====================================
4894 The '-info-ada-exceptions' Command
4895 ----------------------------------
4900 -info-ada-exceptions [ REGEXP]
4902 List all Ada exceptions defined within the program being debugged.
4903 With a regular expression REGEXP, only those exceptions whose names
4904 match REGEXP are listed.
4909 The corresponding GDB command is 'info exceptions'.
4914 The result is a table of Ada exceptions. The following columns are
4915 defined for each exception:
4918 The name of the exception.
4921 The address of the exception.
4926 -info-ada-exceptions aint
4927 ^done,ada-exceptions={nr_rows="2",nr_cols="2",
4928 hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"},
4929 {width="1",alignment="-1",col_name="address",colhdr="Address"}],
4930 body=[{name="constraint_error",address="0x0000000000613da0"},
4931 {name="const.aint_global_e",address="0x0000000000613b00"}]}
4933 Catching Ada Exceptions
4934 -----------------------
4936 The commands describing how to ask GDB to stop when a program raises an
4937 exception are described at *note Ada Exception GDB/MI Catchpoint
4941 File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI
4943 27.23 GDB/MI Support Commands
4944 =============================
4946 Since new commands and features get regularly added to GDB/MI, some
4947 commands are available to help front-ends query the debugger about
4948 support for these capabilities. Similarly, it is also possible to query
4949 GDB about target support of certain features.
4951 The '-info-gdb-mi-command' Command
4952 ----------------------------------
4957 -info-gdb-mi-command CMD_NAME
4959 Query support for the GDB/MI command named CMD_NAME.
4961 Note that the dash ('-') starting all GDB/MI commands is technically
4962 not part of the command name (*note GDB/MI Input Syntax::), and thus
4963 should be omitted in CMD_NAME. However, for ease of use, this command
4964 also accepts the form with the leading dash.
4969 There is no corresponding GDB command.
4974 The result is a tuple. There is currently only one field:
4977 This field is equal to '"true"' if the GDB/MI command exists,
4978 '"false"' otherwise.
4983 Here is an example where the GDB/MI command does not exist:
4985 -info-gdb-mi-command unsupported-command
4986 ^done,command={exists="false"}
4988 And here is an example where the GDB/MI command is known to the
4991 -info-gdb-mi-command symbol-list-lines
4992 ^done,command={exists="true"}
4994 The '-list-features' Command
4995 ----------------------------
4997 Returns a list of particular features of the MI protocol that this
4998 version of gdb implements. A feature can be a command, or a new field
4999 in an output of some command, or even an important bugfix. While a
5000 frontend can sometimes detect presence of a feature at runtime, it is
5001 easier to perform detection at debugger startup.
5003 The command returns a list of strings, with each string naming an
5004 available feature. Each returned string is just a name, it does not
5005 have any internal structure. The list of possible feature names is
5010 (gdb) -list-features
5011 ^done,result=["feature1","feature2"]
5013 The current list of features is:
5016 Indicates support for the '-var-set-frozen' command, as well as
5017 possible presense of the 'frozen' field in the output of
5019 'pending-breakpoints'
5020 Indicates support for the '-f' option to the '-break-insert'
5023 Indicates Python scripting support, Python-based pretty-printing
5024 commands, and possible presence of the 'display_hint' field in the
5025 output of '-var-list-children'
5027 Indicates support for the '-thread-info' command.
5028 'data-read-memory-bytes'
5029 Indicates support for the '-data-read-memory-bytes' and the
5030 '-data-write-memory-bytes' commands.
5031 'breakpoint-notifications'
5032 Indicates that changes to breakpoints and breakpoints created via
5033 the CLI will be announced via async records.
5035 Indicates support for the '-ada-task-info' command.
5037 Indicates that all GDB/MI commands accept the '--language' option
5038 (*note Context management::).
5039 'info-gdb-mi-command'
5040 Indicates support for the '-info-gdb-mi-command' command.
5041 'undefined-command-error-code'
5042 Indicates support for the "undefined-command" error code in error
5043 result records, produced when trying to execute an undefined GDB/MI
5044 command (*note GDB/MI Result Records::).
5045 'exec-run-start-option'
5046 Indicates that the '-exec-run' command supports the '--start'
5047 option (*note GDB/MI Program Execution::).
5049 The '-list-target-features' Command
5050 -----------------------------------
5052 Returns a list of particular features that are supported by the target.
5053 Those features affect the permitted MI commands, but unlike the features
5054 reported by the '-list-features' command, the features depend on which
5055 target GDB is using at the moment. Whenever a target can change, due to
5056 commands such as '-target-select', '-target-attach' or '-exec-run', the
5057 list of target features may change, and the frontend should obtain it
5058 again. Example output:
5060 (gdb) -list-target-features
5061 ^done,result=["async"]
5063 The current list of features is:
5066 Indicates that the target is capable of asynchronous command
5067 execution, which means that GDB will accept further commands while
5068 the target is running.
5071 Indicates that the target is capable of reverse execution. *Note
5072 Reverse Execution::, for more information.
5075 File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI
5077 27.24 Miscellaneous GDB/MI Commands
5078 ===================================
5080 The '-gdb-exit' Command
5081 -----------------------
5088 Exit GDB immediately.
5093 Approximately corresponds to 'quit'.
5102 The '-gdb-set' Command
5103 ----------------------
5110 Set an internal GDB variable.
5115 The corresponding GDB command is 'set'.
5125 The '-gdb-show' Command
5126 -----------------------
5133 Show the current value of a GDB variable.
5138 The corresponding GDB command is 'show'.
5148 The '-gdb-version' Command
5149 --------------------------
5156 Show version information for GDB. Used mostly in testing.
5161 The GDB equivalent is 'show version'. GDB by default shows this
5162 information when you start an interactive session.
5170 ~Copyright 2000 Free Software Foundation, Inc.
5171 ~GDB is free software, covered by the GNU General Public License, and
5172 ~you are welcome to change it and/or distribute copies of it under
5173 ~ certain conditions.
5174 ~Type "show copying" to see the conditions.
5175 ~There is absolutely no warranty for GDB. Type "show warranty" for
5177 ~This GDB was configured as
5178 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
5182 The '-list-thread-groups' Command
5183 ---------------------------------
5188 -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
5190 Lists thread groups (*note Thread groups::). When a single thread
5191 group is passed as the argument, lists the children of that group. When
5192 several thread group are passed, lists information about those thread
5193 groups. Without any parameters, lists information about all top-level
5196 Normally, thread groups that are being debugged are reported. With
5197 the '--available' option, GDB reports thread groups available on the
5200 The output of this command may have either a 'threads' result or a
5201 'groups' result. The 'thread' result has a list of tuples as value,
5202 with each tuple describing a thread (*note GDB/MI Thread Information::).
5203 The 'groups' result has a list of tuples as value, each tuple describing
5204 a thread group. If top-level groups are requested (that is, no
5205 parameter is passed), or when several groups are passed, the output
5206 always has a 'groups' result. The format of the 'group' result is
5209 To reduce the number of roundtrips it's possible to list thread
5210 groups together with their children, by passing the '--recurse' option
5211 and the recursion depth. Presently, only recursion depth of 1 is
5212 permitted. If this option is present, then every reported thread group
5213 will also include its children, either as 'group' or 'threads' field.
5215 In general, any combination of option and parameters is permitted,
5216 with the following caveats:
5218 * When a single thread group is passed, the output will typically be
5219 the 'threads' result. Because threads may not contain anything,
5220 the 'recurse' option will be ignored.
5222 * When the '--available' option is passed, limited information may be
5223 available. In particular, the list of threads of a process might
5224 be inaccessible. Further, specifying specific thread groups might
5225 not give any performance advantage over listing all thread groups.
5226 The frontend should assume that '-list-thread-groups --available'
5227 is always an expensive operation and cache the results.
5229 The 'groups' result is a list of tuples, where each tuple may have
5230 the following fields:
5233 Identifier of the thread group. This field is always present. The
5234 identifier is an opaque string; frontends should not try to convert
5235 it to an integer, even though it might look like one.
5238 The type of the thread group. At present, only 'process' is a
5242 The target-specific process identifier. This field is only present
5243 for thread groups of type 'process' and only if the process exists.
5246 The exit code of this group's last exited thread, formatted in
5247 octal. This field is only present for thread groups of type
5248 'process' and only if the process is not running.
5251 The number of children this thread group has. This field may be
5252 absent for an available thread group.
5255 This field has a list of tuples as value, each tuple describing a
5256 thread. It may be present if the '--recurse' option is specified,
5257 and it's actually possible to obtain the threads.
5260 This field is a list of integers, each identifying a core that one
5261 thread of the group is running on. This field may be absent if
5262 such information is not available.
5265 The name of the executable file that corresponds to this thread
5266 group. The field is only present for thread groups of type
5267 'process', and only if there is a corresponding executable file.
5274 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
5275 -list-thread-groups 17
5276 ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
5277 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
5278 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
5279 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
5280 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
5281 -list-thread-groups --available
5282 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
5283 -list-thread-groups --available --recurse 1
5284 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
5285 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
5286 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
5287 -list-thread-groups --available --recurse 1 17 18
5288 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
5289 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
5290 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
5292 The '-info-os' Command
5293 ----------------------
5300 If no argument is supplied, the command returns a table of available
5301 operating-system-specific information types. If one of these types is
5302 supplied as an argument TYPE, then the command returns a table of data
5305 The types of information available depend on the target operating
5311 The corresponding GDB command is 'info os'.
5316 When run on a GNU/Linux system, the output will look something like
5321 ^done,OSDataTable={nr_rows="9",nr_cols="3",
5322 hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"},
5323 {width="10",alignment="-1",col_name="col1",colhdr="Description"},
5324 {width="10",alignment="-1",col_name="col2",colhdr="Title"}],
5325 body=[item={col0="processes",col1="Listing of all processes",
5327 item={col0="procgroups",col1="Listing of all process groups",
5328 col2="Process groups"},
5329 item={col0="threads",col1="Listing of all threads",
5331 item={col0="files",col1="Listing of all file descriptors",
5332 col2="File descriptors"},
5333 item={col0="sockets",col1="Listing of all internet-domain sockets",
5335 item={col0="shm",col1="Listing of all shared-memory regions",
5336 col2="Shared-memory regions"},
5337 item={col0="semaphores",col1="Listing of all semaphores",
5339 item={col0="msg",col1="Listing of all message queues",
5340 col2="Message queues"},
5341 item={col0="modules",col1="Listing of all loaded kernel modules",
5342 col2="Kernel modules"}]}
5345 ^done,OSDataTable={nr_rows="190",nr_cols="4",
5346 hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"},
5347 {width="10",alignment="-1",col_name="col1",colhdr="user"},
5348 {width="10",alignment="-1",col_name="col2",colhdr="command"},
5349 {width="10",alignment="-1",col_name="col3",colhdr="cores"}],
5350 body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"},
5351 item={col0="2",col1="root",col2="[kthreadd]",col3="1"},
5352 item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"},
5354 item={col0="26446",col1="stan",col2="bash",col3="0"},
5355 item={col0="28152",col1="stan",col2="bash",col3="1"}]}
5358 (Note that the MI output here includes a '"Title"' column that does
5359 not appear in command-line 'info os'; this column is useful for MI
5360 clients that want to enumerate the types of data, such as in a popup
5361 menu, but is needless clutter on the command line, and 'info os' omits
5364 The '-add-inferior' Command
5365 ---------------------------
5372 Creates a new inferior (*note Inferiors and Programs::). The created
5373 inferior is not associated with any executable. Such association may be
5374 established with the '-file-exec-and-symbols' command (*note GDB/MI File
5375 Commands::). The command response has a single field, 'inferior', whose
5376 value is the identifier of the thread group corresponding to the new
5386 The '-interpreter-exec' Command
5387 -------------------------------
5392 -interpreter-exec INTERPRETER COMMAND
5394 Execute the specified COMMAND in the given INTERPRETER.
5399 The corresponding GDB command is 'interpreter-exec'.
5405 -interpreter-exec console "break main"
5406 &"During symbol reading, couldn't parse type; debugger out of date?.\n"
5407 &"During symbol reading, bad structure-type format.\n"
5408 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
5412 The '-inferior-tty-set' Command
5413 -------------------------------
5418 -inferior-tty-set /dev/pts/1
5420 Set terminal for future runs of the program being debugged.
5425 The corresponding GDB command is 'set inferior-tty' /dev/pts/1.
5431 -inferior-tty-set /dev/pts/1
5435 The '-inferior-tty-show' Command
5436 --------------------------------
5443 Show terminal for future runs of program being debugged.
5448 The corresponding GDB command is 'show inferior-tty'.
5454 -inferior-tty-set /dev/pts/1
5458 ^done,inferior_tty_terminal="/dev/pts/1"
5461 The '-enable-timings' Command
5462 -----------------------------
5467 -enable-timings [yes | no]
5469 Toggle the printing of the wallclock, user and system times for an MI
5470 command as a field in its output. This command is to help frontend
5471 developers optimize the performance of their code. No argument is
5472 equivalent to 'yes'.
5487 ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5488 addr="0x080484ed",func="main",file="myprog.c",
5489 fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
5491 time={wallclock="0.05185",user="0.00800",system="0.00000"}
5499 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
5500 frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
5501 {name="argv",value="0xbfb60364"}],file="myprog.c",
5502 fullname="/home/nickrob/myprog.c",line="73"}
5506 File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
5511 This chapter describes annotations in GDB. Annotations were designed to
5512 interface GDB to graphical user interfaces or other similar programs
5513 which want to interact with GDB at a relatively high level.
5515 The annotation mechanism has largely been superseded by GDB/MI (*note
5520 * Annotations Overview:: What annotations are; the general syntax.
5521 * Server Prefix:: Issuing a command without affecting user state.
5522 * Prompting:: Annotations marking GDB's need for input.
5523 * Errors:: Annotations for error messages.
5524 * Invalidation:: Some annotations describe things now invalid.
5525 * Annotations for Running::
5526 Whether the program is running, how it stopped, etc.
5527 * Source Annotations:: Annotations describing source code.
5530 File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
5532 28.1 What is an Annotation?
5533 ===========================
5535 Annotations start with a newline character, two 'control-z' characters,
5536 and the name of the annotation. If there is no additional information
5537 associated with this annotation, the name of the annotation is followed
5538 immediately by a newline. If there is additional information, the name
5539 of the annotation is followed by a space, the additional information,
5540 and a newline. The additional information cannot contain newline
5543 Any output not beginning with a newline and two 'control-z'
5544 characters denotes literal output from GDB. Currently there is no need
5545 for GDB to output a newline followed by two 'control-z' characters, but
5546 if there was such a need, the annotations could be extended with an
5547 'escape' annotation which means those three characters as output.
5549 The annotation LEVEL, which is specified using the '--annotate'
5550 command line option (*note Mode Options::), controls how much
5551 information GDB prints together with its prompt, values of expressions,
5552 source lines, and other types of output. Level 0 is for no annotations,
5553 level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3
5554 is the maximum annotation suitable for programs that control GDB, and
5555 level 2 annotations have been made obsolete (*note Limitations of the
5556 Annotation Interface: (annotate)Limitations.).
5558 'set annotate LEVEL'
5559 The GDB command 'set annotate' sets the level of annotations to the
5563 Show the current annotation level.
5565 This chapter describes level 3 annotations.
5567 A simple example of starting up GDB with annotations is:
5571 Copyright 2003 Free Software Foundation, Inc.
5572 GDB is free software, covered by the GNU General Public License,
5573 and you are welcome to change it and/or distribute copies of it
5574 under certain conditions.
5575 Type "show copying" to see the conditions.
5576 There is absolutely no warranty for GDB. Type "show warranty"
5578 This GDB was configured as "i386-pc-linux-gnu"
5588 Here 'quit' is input to GDB; the rest is output from GDB. The three
5589 lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are
5590 annotations; the rest is output from GDB.
5593 File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
5595 28.2 The Server Prefix
5596 ======================
5598 If you prefix a command with 'server ' then it will not affect the
5599 command history, nor will it affect GDB's notion of which command to
5600 repeat if <RET> is pressed on a line by itself. This means that
5601 commands can be run behind a user's back by a front-end in a transparent
5604 The 'server ' prefix does not affect the recording of values into the
5605 value history; to print a value without recording it into the value
5606 history, use the 'output' command instead of the 'print' command.
5608 Using this prefix also disables confirmation requests (*note
5609 confirmation requests::).
5612 File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
5614 28.3 Annotation for GDB Input
5615 =============================
5617 When GDB prompts for input, it annotates this fact so it is possible to
5618 know when to send output, when the output from a given command is over,
5621 Different kinds of input each have a different "input type". Each
5622 input type has three annotations: a 'pre-' annotation, which denotes the
5623 beginning of any prompt which is being output, a plain annotation, which
5624 denotes the end of the prompt, and then a 'post-' annotation which
5625 denotes the end of any echo which may (or may not) be associated with
5626 the input. For example, the 'prompt' input type features the following
5636 When GDB is prompting for a command (the main GDB prompt).
5639 When GDB prompts for a set of commands, like in the 'commands'
5640 command. The annotations are repeated for each command which is
5644 When GDB wants the user to select between various overloaded
5648 When GDB wants the user to confirm a potentially dangerous
5651 'prompt-for-continue'
5652 When GDB is asking the user to press return to continue. Note:
5653 Don't expect this to work well; instead use 'set height 0' to
5654 disable prompting. This is because the counting of lines is buggy
5655 in the presence of annotations.
5658 File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
5665 This annotation occurs right before GDB responds to an interrupt.
5669 This annotation occurs right before GDB responds to an error.
5671 Quit and error annotations indicate that any annotations which GDB
5672 was in the middle of may end abruptly. For example, if a
5673 'value-history-begin' annotation is followed by a 'error', one cannot
5674 expect to receive the matching 'value-history-end'. One cannot expect
5675 not to receive it either, however; an error annotation does not
5676 necessarily mean that GDB is immediately returning all the way to the
5679 A quit or error annotation may be preceded by
5683 Any output between that and the quit or error annotation is the error
5686 Warning messages are not yet annotated.
5689 File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
5691 28.5 Invalidation Notices
5692 =========================
5694 The following annotations say that certain pieces of state may have
5697 '^Z^Zframes-invalid'
5699 The frames (for example, output from the 'backtrace' command) may
5702 '^Z^Zbreakpoints-invalid'
5704 The breakpoints may have changed. For example, the user just added
5705 or deleted a breakpoint.
5708 File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
5710 28.6 Running the Program
5711 ========================
5713 When the program starts executing due to a GDB command such as 'step' or
5718 is output. When the program stops,
5722 is output. Before the 'stopped' annotation, a variety of annotations
5723 describe how the program stopped.
5725 '^Z^Zexited EXIT-STATUS'
5726 The program exited, and EXIT-STATUS is the exit status (zero for
5727 successful exit, otherwise nonzero).
5730 The program exited with a signal. After the '^Z^Zsignalled', the
5731 annotation continues:
5740 ^Z^Zsignal-string-end
5743 where NAME is the name of the signal, such as 'SIGILL' or
5744 'SIGSEGV', and STRING is the explanation of the signal, such as
5745 'Illegal Instruction' or 'Segmentation fault'. The arguments
5746 INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit
5747 and have no particular format.
5750 The syntax of this annotation is just like 'signalled', but GDB is
5751 just saying that the program received the signal, not that it was
5754 '^Z^Zbreakpoint NUMBER'
5755 The program hit breakpoint number NUMBER.
5757 '^Z^Zwatchpoint NUMBER'
5758 The program hit watchpoint number NUMBER.
5761 File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
5763 28.7 Displaying Source
5764 ======================
5766 The following annotation is used instead of displaying source code:
5768 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
5770 where FILENAME is an absolute file name indicating which source file,
5771 LINE is the line number within that file (where 1 is the first line in
5772 the file), CHARACTER is the character position within the file (where 0
5773 is the first character in the file) (for most debug formats this will
5774 necessarily point to the beginning of a line), MIDDLE is 'middle' if
5775 ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning
5776 of the line, and ADDR is the address in the target program associated
5777 with the source which is being displayed. The ADDR is in the form '0x'
5778 followed by one or more lowercase hex digits (note that this does not
5779 depend on the language).
5782 File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top
5784 29 JIT Compilation Interface
5785 ****************************
5787 This chapter documents GDB's "just-in-time" (JIT) compilation interface.
5788 A JIT compiler is a program or library that generates native executable
5789 code at runtime and executes it, usually in order to achieve good
5790 performance while maintaining platform independence.
5792 Programs that use JIT compilation are normally difficult to debug
5793 because portions of their code are generated at runtime, instead of
5794 being loaded from object files, which is where GDB normally finds the
5795 program's symbols and debug information. In order to debug programs
5796 that use JIT compilation, GDB has an interface that allows the program
5797 to register in-memory symbol files with GDB at runtime.
5799 If you are using GDB to debug a program that uses this interface,
5800 then it should work transparently so long as you have not stripped the
5801 binary. If you are developing a JIT compiler, then the interface is
5802 documented in the rest of this chapter. At this time, the only known
5803 client of this interface is the LLVM JIT.
5805 Broadly speaking, the JIT interface mirrors the dynamic loader
5806 interface. The JIT compiler communicates with GDB by writing data into
5807 a global variable and calling a fuction at a well-known symbol. When
5808 GDB attaches, it reads a linked list of symbol files from the global
5809 variable to find existing code, and puts a breakpoint in the function so
5810 that it can find out about additional code.
5814 * Declarations:: Relevant C struct declarations
5815 * Registering Code:: Steps to register code
5816 * Unregistering Code:: Steps to unregister code
5817 * Custom Debug Info:: Emit debug information in a custom format
5820 File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface
5822 29.1 JIT Declarations
5823 =====================
5825 These are the relevant struct declarations that a C program should
5826 include to implement the interface:
5835 struct jit_code_entry
5837 struct jit_code_entry *next_entry;
5838 struct jit_code_entry *prev_entry;
5839 const char *symfile_addr;
5840 uint64_t symfile_size;
5843 struct jit_descriptor
5846 /* This type should be jit_actions_t, but we use uint32_t
5847 to be explicit about the bitwidth. */
5848 uint32_t action_flag;
5849 struct jit_code_entry *relevant_entry;
5850 struct jit_code_entry *first_entry;
5853 /* GDB puts a breakpoint in this function. */
5854 void __attribute__((noinline)) __jit_debug_register_code() { };
5856 /* Make sure to specify the version statically, because the
5857 debugger may check the version before we can set it. */
5858 struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
5860 If the JIT is multi-threaded, then it is important that the JIT
5861 synchronize any modifications to this global data properly, which can
5862 easily be done by putting a global mutex around modifications to these
5866 File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface
5868 29.2 Registering Code
5869 =====================
5871 To register code with GDB, the JIT should follow this protocol:
5873 * Generate an object file in memory with symbols and other desired
5874 debug information. The file must include the virtual addresses of
5877 * Create a code entry for the file, which gives the start and size of
5880 * Add it to the linked list in the JIT descriptor.
5882 * Point the relevant_entry field of the descriptor at the entry.
5884 * Set 'action_flag' to 'JIT_REGISTER' and call
5885 '__jit_debug_register_code'.
5887 When GDB is attached and the breakpoint fires, GDB uses the
5888 'relevant_entry' pointer so it doesn't have to walk the list looking for
5889 new code. However, the linked list must still be maintained in order to
5890 allow GDB to attach to a running process and still find the symbol
5894 File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface
5896 29.3 Unregistering Code
5897 =======================
5899 If code is freed, then the JIT should use the following protocol:
5901 * Remove the code entry corresponding to the code from the linked
5904 * Point the 'relevant_entry' field of the descriptor at the code
5907 * Set 'action_flag' to 'JIT_UNREGISTER' and call
5908 '__jit_debug_register_code'.
5910 If the JIT frees or recompiles code without unregistering it, then
5911 GDB and the JIT will leak the memory used for the associated symbol
5915 File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface
5917 29.4 Custom Debug Info
5918 ======================
5920 Generating debug information in platform-native file formats (like ELF
5921 or COFF) may be an overkill for JIT compilers; especially if all the
5922 debug info is used for is displaying a meaningful backtrace. The issue
5923 can be resolved by having the JIT writers decide on a debug info format
5924 and also provide a reader that parses the debug info generated by the
5925 JIT compiler. This section gives a brief overview on writing such a
5926 parser. More specific details can be found in the source file
5927 'gdb/jit-reader.in', which is also installed as a header at
5928 'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion.
5930 The reader is implemented as a shared object (so this functionality
5931 is not available on platforms which don't allow loading shared objects
5932 at runtime). Two GDB commands, 'jit-reader-load' and
5933 'jit-reader-unload' are provided, to be used to load and unload the
5934 readers from a preconfigured directory. Once loaded, the shared object
5935 is used the parse the debug information emitted by the JIT compiler.
5939 * Using JIT Debug Info Readers:: How to use supplied readers correctly
5940 * Writing JIT Debug Info Readers:: Creating a debug-info reader
5943 File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info
5945 29.4.1 Using JIT Debug Info Readers
5946 -----------------------------------
5948 Readers can be loaded and unloaded using the 'jit-reader-load' and
5949 'jit-reader-unload' commands.
5951 'jit-reader-load READER'
5952 Load the JIT reader named READER, which is a shared object
5953 specified as either an absolute or a relative file name. In the
5954 latter case, GDB will try to load the reader from a pre-configured
5955 directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is
5956 the system library directory, often '/usr/local/lib').
5958 Only one reader can be active at a time; trying to load a second
5959 reader when one is already loaded will result in GDB reporting an
5960 error. A new JIT reader can be loaded by first unloading the
5961 current one using 'jit-reader-unload' and then invoking
5965 Unload the currently loaded JIT reader.
5968 File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info
5970 29.4.2 Writing JIT Debug Info Readers
5971 -------------------------------------
5973 As mentioned, a reader is essentially a shared object conforming to a
5974 certain ABI. This ABI is described in 'jit-reader.h'.
5976 'jit-reader.h' defines the structures, macros and functions required
5977 to write a reader. It is installed (along with GDB), in
5978 'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory.
5980 Readers need to be released under a GPL compatible license. A reader
5981 can be declared as released under such a license by placing the macro
5982 'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file.
5984 The entry point for readers is the symbol 'gdb_init_reader', which is
5985 expected to be a function with the prototype
5987 extern struct gdb_reader_funcs *gdb_init_reader (void);
5989 'struct gdb_reader_funcs' contains a set of pointers to callback
5990 functions. These functions are executed to read the debug info
5991 generated by the JIT compiler ('read'), to unwind stack frames
5992 ('unwind') and to create canonical frame IDs ('get_Frame_id'). It also
5993 has a callback that is called when the reader is being unloaded
5994 ('destroy'). The struct looks like this
5996 struct gdb_reader_funcs
5998 /* Must be set to GDB_READER_INTERFACE_VERSION. */
6001 /* For use by the reader. */
6004 gdb_read_debug_info *read;
6005 gdb_unwind_frame *unwind;
6006 gdb_get_frame_id *get_frame_id;
6007 gdb_destroy_reader *destroy;
6010 The callbacks are provided with another set of callbacks by GDB to do
6011 their job. For 'read', these callbacks are passed in a 'struct
6012 gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct
6013 gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to
6014 create new object files and new symbol tables inside those object files.
6015 'struct gdb_unwind_callbacks' has callbacks to read registers off the
6016 current frame and to write out the values of the registers in the
6017 previous frame. Both have a callback ('target_read') to read bytes off
6018 the target's address space.
6021 File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top
6026 The traditional debugging model is conceptually low-speed, but works
6027 fine, because most bugs can be reproduced in debugging-mode execution.
6028 However, as multi-core or many-core processors are becoming mainstream,
6029 and multi-threaded programs become more and more popular, there should
6030 be more and more bugs that only manifest themselves at normal-mode
6031 execution, for example, thread races, because debugger's interference
6032 with the program's timing may conceal the bugs. On the other hand, in
6033 some applications, it is not feasible for the debugger to interrupt the
6034 program's execution long enough for the developer to learn anything
6035 helpful about its behavior. If the program's correctness depends on its
6036 real-time behavior, delays introduced by a debugger might cause the
6037 program to fail, even when the code itself is correct. It is useful to
6038 be able to observe the program's behavior without interrupting it.
6040 Therefore, traditional debugging model is too intrusive to reproduce
6041 some bugs. In order to reduce the interference with the program, we can
6042 reduce the number of operations performed by debugger. The "In-Process
6043 Agent", a shared library, is running within the same process with
6044 inferior, and is able to perform some debugging operations itself. As a
6045 result, debugger is only involved when necessary, and performance of
6046 debugging can be improved accordingly. Note that interference with
6047 program can be reduced but can't be removed completely, because the
6048 in-process agent will still stop or slow down the program.
6050 The in-process agent can interpret and execute Agent Expressions
6051 (*note Agent Expressions::) during performing debugging operations. The
6052 agent expressions can be used for different purposes, such as collecting
6053 data in tracepoints, and condition evaluation in breakpoints.
6055 You can control whether the in-process agent is used as an aid for
6056 debugging with the following commands:
6059 Causes the in-process agent to perform some operations on behalf of
6060 the debugger. Just which operations requested by the user will be
6061 done by the in-process agent depends on the its capabilities. For
6062 example, if you request to evaluate breakpoint conditions in the
6063 in-process agent, and the in-process agent has such capability as
6064 well, then breakpoint conditions will be evaluated in the
6068 Disables execution of debugging operations by the in-process agent.
6069 All of the operations will be performed by GDB.
6072 Display the current setting of execution of debugging operations by
6073 the in-process agent.
6077 * In-Process Agent Protocol::
6080 File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent
6082 30.1 In-Process Agent Protocol
6083 ==============================
6085 The in-process agent is able to communicate with both GDB and GDBserver
6086 (*note In-Process Agent::). This section documents the protocol used
6087 for communications between GDB or GDBserver and the IPA. In general, GDB
6088 or GDBserver sends commands (*note IPA Protocol Commands::) and data to
6089 in-process agent, and then in-process agent replies back with the return
6090 result of the command, or some other information. The data sent to
6091 in-process agent is composed of primitive data types, such as 4-byte or
6092 8-byte type, and composite types, which are called objects (*note IPA
6093 Protocol Objects::).
6097 * IPA Protocol Objects::
6098 * IPA Protocol Commands::
6101 File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol
6103 30.1.1 IPA Protocol Objects
6104 ---------------------------
6106 The commands sent to and results received from agent may contain some
6107 complex data types called "objects".
6109 The in-process agent is running on the same machine with GDB or
6110 GDBserver, so it doesn't have to handle as much differences between two
6111 ends as remote protocol (*note Remote Protocol::) tries to handle.
6112 However, there are still some differences of two ends in two processes:
6114 1. word size. On some 64-bit machines, GDB or GDBserver can be
6115 compiled as a 64-bit executable, while in-process agent is a 32-bit
6117 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver
6118 is compiled with one, and in-process agent is compiled with the
6121 Here are the IPA Protocol Objects:
6123 1. agent expression object. It represents an agent expression (*note
6124 Agent Expressions::).
6125 2. tracepoint action object. It represents a tracepoint action (*note
6126 Tracepoint Action Lists: Tracepoint Actions.) to collect registers,
6127 memory, static trace data and to evaluate expression.
6128 3. tracepoint object. It represents a tracepoint (*note
6131 The following table describes important attributes of each IPA
6134 Name Size Description
6135 ---------------------------------------------------------------------------
6138 length 4 length of bytes code
6139 byte code LENGTH contents of byte code
6143 'M' 1 type of tracepoint action
6144 addr 8 if BASEREG is '-1', ADDR is the
6145 address of the lowest byte to
6146 collect, otherwise ADDR is the
6147 offset of BASEREG for memory
6149 len 8 length of memory for collecting
6150 basereg 4 the register number containing the
6151 starting memory address for
6156 'R' 1 type of tracepoint action
6160 'L' 1 type of tracepoint action
6164 'X' 1 type of tracepoint action
6165 agent expression length of *note agent expression object::
6167 number 4 number of tracepoint
6168 address 8 address of tracepoint inserted on
6169 type 4 type of tracepoint
6170 enabled 1 enable or disable of tracepoint
6173 numactions 4 number of tracepoint actions
6174 hit count 8 hit count
6175 trace frame usage 8 trace frame usage
6176 compiled_cond 8 compiled condition
6177 orig_size 8 orig size
6178 condition 4 if zero if condition is NULL,
6179 condition is otherwise is *note agent
6180 NULL expression object::
6186 actions variable numactions number of *note
6187 tracepoint action object::
6190 File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol
6192 30.1.2 IPA Protocol Commands
6193 ----------------------------
6195 The spaces in each command are delimiters to ease reading this commands
6196 specification. They don't exist in real commands.
6198 'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'
6199 Installs a new fast tracepoint described by TRACEPOINT_OBJECT
6200 (*note tracepoint object::). The GDB_JUMP_PAD_HEAD, 8-byte long,
6201 is the head of "jumppad", which is used to jump to data collection
6202 routine in IPA finally.
6205 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'
6206 TARGET_ADDRESS is address of tracepoint in the inferior. The
6207 GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of
6208 TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. The
6209 FJUMP contains a sequence of instructions jump to jumppad
6210 entry. The FJUMP_SIZE, 4-byte long, is the size of FJUMP.
6215 Closes the in-process agent. This command is sent when GDB or
6216 GDBserver is about to kill inferiors.
6224 'probe_marker_at:ADDRESS'
6225 Asks in-process agent to probe the marker at ADDRESS.
6230 'unprobe_marker_at:ADDRESS'
6231 Asks in-process agent to unprobe the marker at ADDRESS.
6234 File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top
6236 31 Reporting Bugs in GDB
6237 ************************
6239 Your bug reports play an essential role in making GDB reliable.
6241 Reporting a bug may help you by bringing a solution to your problem,
6242 or it may not. But in any case the principal function of a bug report
6243 is to help the entire community by making the next version of GDB work
6244 better. Bug reports are your contribution to the maintenance of GDB.
6246 In order for a bug report to serve its purpose, you must include the
6247 information that enables us to fix the bug.
6251 * Bug Criteria:: Have you found a bug?
6252 * Bug Reporting:: How to report bugs
6255 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
6257 31.1 Have You Found a Bug?
6258 ==========================
6260 If you are not sure whether you have found a bug, here are some
6263 * If the debugger gets a fatal signal, for any input whatever, that
6264 is a GDB bug. Reliable debuggers never crash.
6266 * If GDB produces an error message for valid input, that is a bug.
6267 (Note that if you're cross debugging, the problem may also be
6268 somewhere in the connection to the target.)
6270 * If GDB does not produce an error message for invalid input, that is
6271 a bug. However, you should note that your idea of "invalid input"
6272 might be our idea of "an extension" or "support for traditional
6275 * If you are an experienced user of debugging tools, your suggestions
6276 for improvement of GDB are welcome in any case.
6279 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
6281 31.2 How to Report Bugs
6282 =======================
6284 A number of companies and individuals offer support for GNU products.
6285 If you obtained GDB from a support organization, we recommend you
6286 contact that organization first.
6288 You can find contact information for many support companies and
6289 individuals in the file 'etc/SERVICE' in the GNU Emacs distribution.
6291 In any event, we also recommend that you submit bug reports for GDB.
6292 The preferred method is to submit them directly using GDB's Bugs web
6293 page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the e-mail
6294 gateway <bug-gdb@gnu.org> can be used.
6296 *Do not send bug reports to 'info-gdb', or to 'help-gdb', or to any
6297 newsgroups.* Most users of GDB do not want to receive bug reports.
6298 Those that do have arranged to receive 'bug-gdb'.
6300 The mailing list 'bug-gdb' has a newsgroup 'gnu.gdb.bug' which serves
6301 as a repeater. The mailing list and the newsgroup carry exactly the
6302 same messages. Often people think of posting bug reports to the
6303 newsgroup instead of mailing them. This appears to work, but it has one
6304 problem which can be crucial: a newsgroup posting often lacks a mail
6305 path back to the sender. Thus, if we need to ask for more information,
6306 we may be unable to reach you. For this reason, it is better to send
6307 bug reports to the mailing list.
6309 The fundamental principle of reporting bugs usefully is this: *report
6310 all the facts*. If you are not sure whether to state a fact or leave it
6313 Often people omit facts because they think they know what causes the
6314 problem and assume that some details do not matter. Thus, you might
6315 assume that the name of the variable you use in an example does not
6316 matter. Well, probably it does not, but one cannot be sure. Perhaps
6317 the bug is a stray memory reference which happens to fetch from the
6318 location where that name is stored in memory; perhaps, if the name were
6319 different, the contents of that location would fool the debugger into
6320 doing the right thing despite the bug. Play it safe and give a
6321 specific, complete example. That is the easiest thing for you to do,
6322 and the most helpful.
6324 Keep in mind that the purpose of a bug report is to enable us to fix
6325 the bug. It may be that the bug has been reported previously, but
6326 neither you nor we can know that unless your bug report is complete and
6329 Sometimes people give a few sketchy facts and ask, "Does this ring a
6330 bell?" Those bug reports are useless, and we urge everyone to _refuse
6331 to respond to them_ except to chide the sender to report bugs properly.
6333 To enable us to fix the bug, you should include all these things:
6335 * The version of GDB. GDB announces it if you start with no
6336 arguments; you can also print it at any time using 'show version'.
6338 Without this, we will not know whether there is any point in
6339 looking for the bug in the current version of GDB.
6341 * The type of machine you are using, and the operating system name
6344 * The details of the GDB build-time configuration. GDB shows these
6345 details if you invoke it with the '--configuration' command-line
6346 option, or if you type 'show configuration' at GDB's prompt.
6348 * What compiler (and its version) was used to compile GDB--e.g.
6351 * What compiler (and its version) was used to compile the program you
6352 are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C
6353 Compiler". For GCC, you can say 'gcc --version' to get this
6354 information; for other compilers, see the documentation for those
6357 * The command arguments you gave the compiler to compile your example
6358 and observe the bug. For example, did you use '-O'? To guarantee
6359 you will not omit something important, list them all. A copy of
6360 the Makefile (or the output from make) is sufficient.
6362 If we were to try to guess the arguments, we would probably guess
6363 wrong and then we might not encounter the bug.
6365 * A complete input script, and all necessary source files, that will
6368 * A description of what behavior you observe that you believe is
6369 incorrect. For example, "It gets a fatal signal."
6371 Of course, if the bug is that GDB gets a fatal signal, then we will
6372 certainly notice it. But if the bug is incorrect output, we might
6373 not notice unless it is glaringly wrong. You might as well not
6374 give us a chance to make a mistake.
6376 Even if the problem you experience is a fatal signal, you should
6377 still say so explicitly. Suppose something strange is going on,
6378 such as, your copy of GDB is out of synch, or you have encountered
6379 a bug in the C library on your system. (This has happened!) Your
6380 copy might crash and ours would not. If you told us to expect a
6381 crash, then when ours fails to crash, we would know that the bug
6382 was not happening for us. If you had not told us to expect a
6383 crash, then we would not be able to draw any conclusion from our
6386 To collect all this information, you can use a session recording
6387 program such as 'script', which is available on many Unix systems.
6388 Just run your GDB session inside 'script' and then include the
6389 'typescript' file with your bug report.
6391 Another way to record a GDB session is to run GDB inside Emacs and
6392 then save the entire buffer to a file.
6394 * If you wish to suggest changes to the GDB source, send us context
6395 diffs. If you even discuss something in the GDB source, refer to
6396 it by context, not by line number.
6398 The line numbers in our development sources will not match those in
6399 your sources. Your line numbers would convey no useful information
6402 Here are some things that are not necessary:
6404 * A description of the envelope of the bug.
6406 Often people who encounter a bug spend a lot of time investigating
6407 which changes to the input file will make the bug go away and which
6408 changes will not affect it.
6410 This is often time consuming and not very useful, because the way
6411 we will find the bug is by running a single example under the
6412 debugger with breakpoints, not by pure deduction from a series of
6413 examples. We recommend that you save your time for something else.
6415 Of course, if you can find a simpler example to report _instead_ of
6416 the original one, that is a convenience for us. Errors in the
6417 output will be easier to spot, running under the debugger will take
6418 less time, and so on.
6420 However, simplification is not vital; if you do not want to do
6421 this, report the bug anyway and send us the entire test case you
6424 * A patch for the bug.
6426 A patch for the bug does help us if it is a good one. But do not
6427 omit the necessary information, such as the test case, on the
6428 assumption that a patch is all we need. We might see problems with
6429 your patch and decide to fix the problem another way, or we might
6430 not understand it at all.
6432 Sometimes with a program as complicated as GDB it is very hard to
6433 construct an example that will make the program follow a certain
6434 path through the code. If you do not send us the example, we will
6435 not be able to construct one, so we will not be able to verify that
6438 And if we cannot understand what bug you are trying to fix, or why
6439 your patch should be an improvement, we will not install it. A
6440 test case will help us to understand.
6442 * A guess about what the bug is or what it depends on.
6444 Such guesses are usually wrong. Even we cannot guess right about
6445 such things without first using the debugger to find the facts.
6448 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
6450 32 Command Line Editing
6451 ***********************
6453 This chapter describes the basic features of the GNU command line
6458 * Introduction and Notation:: Notation used in this text.
6459 * Readline Interaction:: The minimum set of commands for editing a line.
6460 * Readline Init File:: Customizing Readline from a user's view.
6461 * Bindable Readline Commands:: A description of most of the Readline commands
6462 available for binding
6463 * Readline vi Mode:: A short description of how to make Readline
6464 behave like the vi editor.
6467 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
6469 32.1 Introduction to Line Editing
6470 =================================
6472 The following paragraphs describe the notation used to represent
6475 The text 'C-k' is read as 'Control-K' and describes the character
6476 produced when the <k> key is pressed while the Control key is depressed.
6478 The text 'M-k' is read as 'Meta-K' and describes the character
6479 produced when the Meta key (if you have one) is depressed, and the <k>
6480 key is pressed. The Meta key is labeled <ALT> on many keyboards. On
6481 keyboards with two keys labeled <ALT> (usually to either side of the
6482 space bar), the <ALT> on the left side is generally set to work as a
6483 Meta key. The <ALT> key on the right may also be configured to work as
6484 a Meta key or may be configured as some other modifier, such as a
6485 Compose key for typing accented characters.
6487 If you do not have a Meta or <ALT> key, or another key working as a
6488 Meta key, the identical keystroke can be generated by typing <ESC>
6489 _first_, and then typing <k>. Either process is known as "metafying"
6492 The text 'M-C-k' is read as 'Meta-Control-k' and describes the
6493 character produced by "metafying" 'C-k'.
6495 In addition, several keys have their own names. Specifically, <DEL>,
6496 <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen
6497 in this text, or in an init file (*note Readline Init File::). If your
6498 keyboard lacks a <LFD> key, typing <C-j> will produce the desired
6499 character. The <RET> key may be labeled <Return> or <Enter> on some
6503 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
6505 32.2 Readline Interaction
6506 =========================
6508 Often during an interactive session you type in a long line of text,
6509 only to notice that the first word on the line is misspelled. The
6510 Readline library gives you a set of commands for manipulating the text
6511 as you type it in, allowing you to just fix your typo, and not forcing
6512 you to retype the majority of the line. Using these editing commands,
6513 you move the cursor to the place that needs correction, and delete or
6514 insert the text of the corrections. Then, when you are satisfied with
6515 the line, you simply press <RET>. You do not have to be at the end of
6516 the line to press <RET>; the entire line is accepted regardless of the
6517 location of the cursor within the line.
6521 * Readline Bare Essentials:: The least you need to know about Readline.
6522 * Readline Movement Commands:: Moving about the input line.
6523 * Readline Killing Commands:: How to delete text, and how to get it back!
6524 * Readline Arguments:: Giving numeric arguments to commands.
6525 * Searching:: Searching through previous lines.
6528 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
6530 32.2.1 Readline Bare Essentials
6531 -------------------------------
6533 In order to enter characters into the line, simply type them. The typed
6534 character appears where the cursor was, and then the cursor moves one
6535 space to the right. If you mistype a character, you can use your erase
6536 character to back up and delete the mistyped character.
6538 Sometimes you may mistype a character, and not notice the error until
6539 you have typed several other characters. In that case, you can type
6540 'C-b' to move the cursor to the left, and then correct your mistake.
6541 Afterwards, you can move the cursor to the right with 'C-f'.
6543 When you add text in the middle of a line, you will notice that
6544 characters to the right of the cursor are 'pushed over' to make room for
6545 the text that you have inserted. Likewise, when you delete text behind
6546 the cursor, characters to the right of the cursor are 'pulled back' to
6547 fill in the blank space created by the removal of the text. A list of
6548 the bare essentials for editing the text of an input line follows.
6551 Move back one character.
6553 Move forward one character.
6554 <DEL> or <Backspace>
6555 Delete the character to the left of the cursor.
6557 Delete the character underneath the cursor.
6559 Insert the character into the line at the cursor.
6561 Undo the last editing command. You can undo all the way back to an
6564 (Depending on your configuration, the <Backspace> key be set to delete
6565 the character to the left of the cursor and the <DEL> key set to delete
6566 the character underneath the cursor, like 'C-d', rather than the
6567 character to the left of the cursor.)
6570 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
6572 32.2.2 Readline Movement Commands
6573 ---------------------------------
6575 The above table describes the most basic keystrokes that you need in
6576 order to do editing of the input line. For your convenience, many other
6577 commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>.
6578 Here are some commands for moving more rapidly about the line.
6581 Move to the start of the line.
6583 Move to the end of the line.
6585 Move forward a word, where a word is composed of letters and
6588 Move backward a word.
6590 Clear the screen, reprinting the current line at the top.
6592 Notice how 'C-f' moves forward a character, while 'M-f' moves forward
6593 a word. It is a loose convention that control keystrokes operate on
6594 characters while meta keystrokes operate on words.
6597 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
6599 32.2.3 Readline Killing Commands
6600 --------------------------------
6602 "Killing" text means to delete the text from the line, but to save it
6603 away for later use, usually by "yanking" (re-inserting) it back into the
6604 line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.)
6606 If the description for a command says that it 'kills' text, then you
6607 can be sure that you can get the text back in a different (or the same)
6610 When you use a kill command, the text is saved in a "kill-ring". Any
6611 number of consecutive kills save all of the killed text together, so
6612 that when you yank it back, you get it all. The kill ring is not line
6613 specific; the text that you killed on a previously typed line is
6614 available to be yanked back later, when you are typing another line.
6616 Here is the list of commands for killing text.
6619 Kill the text from the current cursor position to the end of the
6623 Kill from the cursor to the end of the current word, or, if between
6624 words, to the end of the next word. Word boundaries are the same
6625 as those used by 'M-f'.
6628 Kill from the cursor the start of the current word, or, if between
6629 words, to the start of the previous word. Word boundaries are the
6630 same as those used by 'M-b'.
6633 Kill from the cursor to the previous whitespace. This is different
6634 than 'M-<DEL>' because the word boundaries differ.
6636 Here is how to "yank" the text back into the line. Yanking means to
6637 copy the most-recently-killed text from the kill buffer.
6640 Yank the most recently killed text back into the buffer at the
6644 Rotate the kill-ring, and yank the new top. You can only do this
6645 if the prior command is 'C-y' or 'M-y'.
6648 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
6650 32.2.4 Readline Arguments
6651 -------------------------
6653 You can pass numeric arguments to Readline commands. Sometimes the
6654 argument acts as a repeat count, other times it is the sign of the
6655 argument that is significant. If you pass a negative argument to a
6656 command which normally acts in a forward direction, that command will
6657 act in a backward direction. For example, to kill text back to the
6658 start of the line, you might type 'M-- C-k'.
6660 The general way to pass numeric arguments to a command is to type
6661 meta digits before the command. If the first 'digit' typed is a minus
6662 sign ('-'), then the sign of the argument will be negative. Once you
6663 have typed one meta digit to get the argument started, you can type the
6664 remainder of the digits, and then the command. For example, to give the
6665 'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will
6666 delete the next ten characters on the input line.
6669 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
6671 32.2.5 Searching for Commands in the History
6672 --------------------------------------------
6674 Readline provides commands for searching through the command history for
6675 lines containing a specified string. There are two search modes:
6676 "incremental" and "non-incremental".
6678 Incremental searches begin before the user has finished typing the
6679 search string. As each character of the search string is typed,
6680 Readline displays the next entry from the history matching the string
6681 typed so far. An incremental search requires only as many characters as
6682 needed to find the desired history entry. To search backward in the
6683 history for a particular string, type 'C-r'. Typing 'C-s' searches
6684 forward through the history. The characters present in the value of the
6685 'isearch-terminators' variable are used to terminate an incremental
6686 search. If that variable has not been assigned a value, the <ESC> and
6687 'C-J' characters will terminate an incremental search. 'C-g' will abort
6688 an incremental search and restore the original line. When the search is
6689 terminated, the history entry containing the search string becomes the
6692 To find other matching entries in the history list, type 'C-r' or
6693 'C-s' as appropriate. This will search backward or forward in the
6694 history for the next entry matching the search string typed so far. Any
6695 other key sequence bound to a Readline command will terminate the search
6696 and execute that command. For instance, a <RET> will terminate the
6697 search and accept the line, thereby executing the command from the
6698 history list. A movement command will terminate the search, make the
6699 last line found the current line, and begin editing.
6701 Readline remembers the last incremental search string. If two 'C-r's
6702 are typed without any intervening characters defining a new search
6703 string, any remembered search string is used.
6705 Non-incremental searches read the entire search string before
6706 starting to search for matching history lines. The search string may be
6707 typed by the user or be part of the contents of the current line.
6710 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
6712 32.3 Readline Init File
6713 =======================
6715 Although the Readline library comes with a set of Emacs-like keybindings
6716 installed by default, it is possible to use a different set of
6717 keybindings. Any user can customize programs that use Readline by
6718 putting commands in an "inputrc" file, conventionally in his home
6719 directory. The name of this file is taken from the value of the
6720 environment variable 'INPUTRC'. If that variable is unset, the default
6721 is '~/.inputrc'. If that file does not exist or cannot be read, the
6722 ultimate default is '/etc/inputrc'.
6724 When a program which uses the Readline library starts up, the init
6725 file is read, and the key bindings are set.
6727 In addition, the 'C-x C-r' command re-reads this init file, thus
6728 incorporating any changes that you might have made to it.
6732 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
6734 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
6736 * Sample Init File:: An example inputrc file.
6739 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
6741 32.3.1 Readline Init File Syntax
6742 --------------------------------
6744 There are only a few basic constructs allowed in the Readline init file.
6745 Blank lines are ignored. Lines beginning with a '#' are comments.
6746 Lines beginning with a '$' indicate conditional constructs (*note
6747 Conditional Init Constructs::). Other lines denote variable settings
6751 You can modify the run-time behavior of Readline by altering the
6752 values of variables in Readline using the 'set' command within the
6753 init file. The syntax is simple:
6757 Here, for example, is how to change from the default Emacs-like key
6758 binding to use 'vi' line editing commands:
6762 Variable names and values, where appropriate, are recognized
6763 without regard to case. Unrecognized variable names are ignored.
6765 Boolean variables (those that can be set to on or off) are set to
6766 on if the value is null or empty, ON (case-insensitive), or 1. Any
6767 other value results in the variable being set to off.
6769 A great deal of run-time behavior is changeable with the following
6773 Controls what happens when Readline wants to ring the terminal
6774 bell. If set to 'none', Readline never rings the bell. If
6775 set to 'visible', Readline uses a visible bell if one is
6776 available. If set to 'audible' (the default), Readline
6777 attempts to ring the terminal's bell.
6779 'bind-tty-special-chars'
6780 If set to 'on', Readline attempts to bind the control
6781 characters treated specially by the kernel's terminal driver
6782 to their Readline equivalents.
6785 The string to insert at the beginning of the line when the
6786 'insert-comment' command is executed. The default value is
6789 'completion-display-width'
6790 The number of screen columns used to display possible matches
6791 when performing completion. The value is ignored if it is
6792 less than 0 or greater than the terminal screen width. A
6793 value of 0 will cause matches to be displayed one per line.
6794 The default value is -1.
6796 'completion-ignore-case'
6797 If set to 'on', Readline performs filename matching and
6798 completion in a case-insensitive fashion. The default value
6801 'completion-map-case'
6802 If set to 'on', and COMPLETION-IGNORE-CASE is enabled,
6803 Readline treats hyphens ('-') and underscores ('_') as
6804 equivalent when performing case-insensitive filename matching
6807 'completion-prefix-display-length'
6808 The length in characters of the common prefix of a list of
6809 possible completions that is displayed without modification.
6810 When set to a value greater than zero, common prefixes longer
6811 than this value are replaced with an ellipsis when displaying
6812 possible completions.
6814 'completion-query-items'
6815 The number of possible completions that determines when the
6816 user is asked whether the list of possibilities should be
6817 displayed. If the number of possible completions is greater
6818 than this value, Readline will ask the user whether or not he
6819 wishes to view them; otherwise, they are simply listed. This
6820 variable must be set to an integer value greater than or equal
6821 to 0. A negative value means Readline should never ask. The
6822 default limit is '100'.
6825 If set to 'on', Readline will convert characters with the
6826 eighth bit set to an ASCII key sequence by stripping the
6827 eighth bit and prefixing an <ESC> character, converting them
6828 to a meta-prefixed key sequence. The default value is 'on'.
6830 'disable-completion'
6831 If set to 'On', Readline will inhibit word completion.
6832 Completion characters will be inserted into the line as if
6833 they had been mapped to 'self-insert'. The default is 'off'.
6836 The 'editing-mode' variable controls which default set of key
6837 bindings is used. By default, Readline starts up in Emacs
6838 editing mode, where the keystrokes are most similar to Emacs.
6839 This variable can be set to either 'emacs' or 'vi'.
6841 'echo-control-characters'
6842 When set to 'on', on operating systems that indicate they
6843 support it, readline echoes a character corresponding to a
6844 signal generated from the keyboard. The default is 'on'.
6847 When set to 'on', Readline will try to enable the application
6848 keypad when it is called. Some systems need this to enable
6849 the arrow keys. The default is 'off'.
6852 When set to 'on', Readline will try to enable any meta
6853 modifier key the terminal claims to support when it is called.
6854 On many terminals, the meta key is used to send eight-bit
6855 characters. The default is 'on'.
6858 If set to 'on', tilde expansion is performed when Readline
6859 attempts word completion. The default is 'off'.
6861 'history-preserve-point'
6862 If set to 'on', the history code attempts to place the point
6863 (the current cursor position) at the same location on each
6864 history line retrieved with 'previous-history' or
6865 'next-history'. The default is 'off'.
6868 Set the maximum number of history entries saved in the history
6869 list. If set to zero, the number of entries in the history
6870 list is not limited.
6872 'horizontal-scroll-mode'
6873 This variable can be set to either 'on' or 'off'. Setting it
6874 to 'on' means that the text of the lines being edited will
6875 scroll horizontally on a single screen line when they are
6876 longer than the width of the screen, instead of wrapping onto
6877 a new screen line. By default, this variable is set to 'off'.
6880 If set to 'on', Readline will enable eight-bit input (it will
6881 not clear the eighth bit in the characters it reads),
6882 regardless of what the terminal claims it can support. The
6883 default value is 'off'. The name 'meta-flag' is a synonym for
6886 'isearch-terminators'
6887 The string of characters that should terminate an incremental
6888 search without subsequently executing the character as a
6889 command (*note Searching::). If this variable has not been
6890 given a value, the characters <ESC> and 'C-J' will terminate
6891 an incremental search.
6894 Sets Readline's idea of the current keymap for key binding
6895 commands. Acceptable 'keymap' names are 'emacs',
6896 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',
6897 'vi-command', and 'vi-insert'. 'vi' is equivalent to
6898 'vi-command'; 'emacs' is equivalent to 'emacs-standard'. The
6899 default value is 'emacs'. The value of the 'editing-mode'
6900 variable also affects the default keymap.
6903 If set to 'on', completed directory names have a slash
6904 appended. The default is 'on'.
6906 'mark-modified-lines'
6907 This variable, when set to 'on', causes Readline to display an
6908 asterisk ('*') at the start of history lines which have been
6909 modified. This variable is 'off' by default.
6911 'mark-symlinked-directories'
6912 If set to 'on', completed names which are symbolic links to
6913 directories have a slash appended (subject to the value of
6914 'mark-directories'). The default is 'off'.
6916 'match-hidden-files'
6917 This variable, when set to 'on', causes Readline to match
6918 files whose names begin with a '.' (hidden files) when
6919 performing filename completion. If set to 'off', the leading
6920 '.' must be supplied by the user in the filename to be
6921 completed. This variable is 'on' by default.
6923 'menu-complete-display-prefix'
6924 If set to 'on', menu completion displays the common prefix of
6925 the list of possible completions (which may be empty) before
6926 cycling through the list. The default is 'off'.
6929 If set to 'on', Readline will display characters with the
6930 eighth bit set directly rather than as a meta-prefixed escape
6931 sequence. The default is 'off'.
6934 If set to 'on', Readline uses an internal 'more'-like pager to
6935 display a screenful of possible completions at a time. This
6936 variable is 'on' by default.
6938 'print-completions-horizontally'
6939 If set to 'on', Readline will display completions with matches
6940 sorted horizontally in alphabetical order, rather than down
6941 the screen. The default is 'off'.
6943 'revert-all-at-newline'
6944 If set to 'on', Readline will undo all changes to history
6945 lines before returning when 'accept-line' is executed. By
6946 default, history lines may be modified and retain individual
6947 undo lists across calls to 'readline'. The default is 'off'.
6949 'show-all-if-ambiguous'
6950 This alters the default behavior of the completion functions.
6951 If set to 'on', words which have more than one possible
6952 completion cause the matches to be listed immediately instead
6953 of ringing the bell. The default value is 'off'.
6955 'show-all-if-unmodified'
6956 This alters the default behavior of the completion functions
6957 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
6958 'on', words which have more than one possible completion
6959 without any possible partial completion (the possible
6960 completions don't share a common prefix) cause the matches to
6961 be listed immediately instead of ringing the bell. The
6962 default value is 'off'.
6964 'skip-completed-text'
6965 If set to 'on', this alters the default completion behavior
6966 when inserting a single match into the line. It's only active
6967 when performing completion in the middle of a word. If
6968 enabled, readline does not insert characters from the
6969 completion that match characters after point in the word being
6970 completed, so portions of the word following the cursor are
6971 not duplicated. For instance, if this is enabled, attempting
6972 completion when the cursor is after the 'e' in 'Makefile' will
6973 result in 'Makefile' rather than 'Makefilefile', assuming
6974 there is a single possible completion. The default value is
6978 If set to 'on', a character denoting a file's type is appended
6979 to the filename when listing possible completions. The
6983 The syntax for controlling key bindings in the init file is simple.
6984 First you need to find the name of the command that you want to
6985 change. The following sections contain tables of the command name,
6986 the default keybinding, if any, and a short description of what the
6989 Once you know the name of the command, simply place on a line in
6990 the init file the name of the key you wish to bind the command to,
6991 a colon, and then the name of the command. There can be no space
6992 between the key name and the colon - that will be interpreted as
6993 part of the key name. The name of the key can be expressed in
6994 different ways, depending on what you find most comfortable.
6996 In addition to command names, readline allows keys to be bound to a
6997 string that is inserted when the key is pressed (a MACRO).
6999 KEYNAME: FUNCTION-NAME or MACRO
7000 KEYNAME is the name of a key spelled out in English. For
7002 Control-u: universal-argument
7003 Meta-Rubout: backward-kill-word
7004 Control-o: "> output"
7006 In the above example, 'C-u' is bound to the function
7007 'universal-argument', 'M-DEL' is bound to the function
7008 'backward-kill-word', and 'C-o' is bound to run the macro
7009 expressed on the right hand side (that is, to insert the text
7010 '> output' into the line).
7012 A number of symbolic character names are recognized while
7013 processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
7014 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
7016 "KEYSEQ": FUNCTION-NAME or MACRO
7017 KEYSEQ differs from KEYNAME above in that strings denoting an
7018 entire key sequence can be specified, by placing the key
7019 sequence in double quotes. Some GNU Emacs style key escapes
7020 can be used, as in the following example, but the special
7021 character names are not recognized.
7023 "\C-u": universal-argument
7024 "\C-x\C-r": re-read-init-file
7025 "\e[11~": "Function Key 1"
7027 In the above example, 'C-u' is again bound to the function
7028 'universal-argument' (just as it was in the first example),
7029 ''C-x' 'C-r'' is bound to the function 're-read-init-file',
7030 and '<ESC> <[> <1> <1> <~>' is bound to insert the text
7033 The following GNU Emacs style escape sequences are available when
7034 specifying key sequences:
7045 <">, a double quotation mark
7047 <'>, a single quote or apostrophe
7049 In addition to the GNU Emacs style escape sequences, a second set
7050 of backslash escapes is available:
7069 the eight-bit character whose value is the octal value NNN
7070 (one to three digits)
7072 the eight-bit character whose value is the hexadecimal value
7073 HH (one or two hex digits)
7075 When entering the text of a macro, single or double quotes must be
7076 used to indicate a macro definition. Unquoted text is assumed to
7077 be a function name. In the macro body, the backslash escapes
7078 described above are expanded. Backslash will quote any other
7079 character in the macro text, including '"' and '''. For example,
7080 the following binding will make ''C-x' \' insert a single '\' into
7085 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
7087 32.3.2 Conditional Init Constructs
7088 ----------------------------------
7090 Readline implements a facility similar in spirit to the conditional
7091 compilation features of the C preprocessor which allows key bindings and
7092 variable settings to be performed as the result of tests. There are
7093 four parser directives used.
7096 The '$if' construct allows bindings to be made based on the editing
7097 mode, the terminal being used, or the application using Readline.
7098 The text of the test extends to the end of the line; no characters
7099 are required to isolate it.
7102 The 'mode=' form of the '$if' directive is used to test
7103 whether Readline is in 'emacs' or 'vi' mode. This may be used
7104 in conjunction with the 'set keymap' command, for instance, to
7105 set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps
7106 only if Readline is starting out in 'emacs' mode.
7109 The 'term=' form may be used to include terminal-specific key
7110 bindings, perhaps to bind the key sequences output by the
7111 terminal's function keys. The word on the right side of the
7112 '=' is tested against both the full name of the terminal and
7113 the portion of the terminal name before the first '-'. This
7114 allows 'sun' to match both 'sun' and 'sun-cmd', for instance.
7117 The APPLICATION construct is used to include
7118 application-specific settings. Each program using the
7119 Readline library sets the APPLICATION NAME, and you can test
7120 for a particular value. This could be used to bind key
7121 sequences to functions useful for a specific program. For
7122 instance, the following command adds a key sequence that
7123 quotes the current or previous word in Bash:
7125 # Quote the current or previous word
7126 "\C-xq": "\eb\"\ef\""
7130 This command, as seen in the previous example, terminates an '$if'
7134 Commands in this branch of the '$if' directive are executed if the
7138 This directive takes a single filename as an argument and reads
7139 commands and bindings from that file. For example, the following
7140 directive reads from '/etc/inputrc':
7141 $include /etc/inputrc
7144 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
7146 32.3.3 Sample Init File
7147 -----------------------
7149 Here is an example of an INPUTRC file. This illustrates key binding,
7150 variable assignment, and conditional syntax.
7152 # This file controls the behaviour of line input editing for
7153 # programs that use the GNU Readline library. Existing
7154 # programs include FTP, Bash, and GDB.
7156 # You can re-read the inputrc file with C-x C-r.
7157 # Lines beginning with '#' are comments.
7159 # First, include any systemwide bindings and variable
7160 # assignments from /etc/Inputrc
7161 $include /etc/Inputrc
7164 # Set various bindings for emacs mode.
7166 set editing-mode emacs
7170 Meta-Control-h: backward-kill-word Text after the function name is ignored
7173 # Arrow keys in keypad mode
7175 #"\M-OD": backward-char
7176 #"\M-OC": forward-char
7177 #"\M-OA": previous-history
7178 #"\M-OB": next-history
7180 # Arrow keys in ANSI mode
7182 "\M-[D": backward-char
7183 "\M-[C": forward-char
7184 "\M-[A": previous-history
7185 "\M-[B": next-history
7187 # Arrow keys in 8 bit keypad mode
7189 #"\M-\C-OD": backward-char
7190 #"\M-\C-OC": forward-char
7191 #"\M-\C-OA": previous-history
7192 #"\M-\C-OB": next-history
7194 # Arrow keys in 8 bit ANSI mode
7196 #"\M-\C-[D": backward-char
7197 #"\M-\C-[C": forward-char
7198 #"\M-\C-[A": previous-history
7199 #"\M-\C-[B": next-history
7205 # An old-style binding. This happens to be the default.
7208 # Macros that are convenient for shell interaction
7211 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
7212 # prepare to type a quoted word --
7213 # insert open and close double quotes
7214 # and move to just after the open quote
7215 "\C-x\"": "\"\"\C-b"
7216 # insert a backslash (testing backslash escapes
7217 # in sequences and macros)
7219 # Quote the current or previous word
7220 "\C-xq": "\eb\"\ef\""
7221 # Add a binding to refresh the line, which is unbound
7222 "\C-xr": redraw-current-line
7223 # Edit variable on current line.
7224 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
7227 # use a visible bell if one is available
7228 set bell-style visible
7230 # don't strip characters to 7 bits when reading
7233 # allow iso-latin1 characters to be inserted rather
7234 # than converted to prefix-meta sequences
7235 set convert-meta off
7237 # display characters with the eighth bit set directly
7238 # rather than as meta-prefixed characters
7241 # if there are more than 150 possible completions for
7242 # a word, ask the user if he wants to see all of them
7243 set completion-query-items 150
7249 "\M-.": yank-last-arg
7253 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
7255 32.4 Bindable Readline Commands
7256 ===============================
7260 * Commands For Moving:: Moving about the line.
7261 * Commands For History:: Getting at previous lines.
7262 * Commands For Text:: Commands for changing text.
7263 * Commands For Killing:: Commands for killing and yanking.
7264 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
7265 * Commands For Completion:: Getting Readline to do the typing for you.
7266 * Keyboard Macros:: Saving and re-executing typed characters
7267 * Miscellaneous Commands:: Other miscellaneous commands.
7269 This section describes Readline commands that may be bound to key
7270 sequences. Command names without an accompanying key sequence are
7273 In the following descriptions, "point" refers to the current cursor
7274 position, and "mark" refers to a cursor position saved by the 'set-mark'
7275 command. The text between the point and mark is referred to as the
7279 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
7281 32.4.1 Commands For Moving
7282 --------------------------
7284 'beginning-of-line (C-a)'
7285 Move to the start of the current line.
7288 Move to the end of the line.
7290 'forward-char (C-f)'
7291 Move forward a character.
7293 'backward-char (C-b)'
7294 Move back a character.
7296 'forward-word (M-f)'
7297 Move forward to the end of the next word. Words are composed of
7300 'backward-word (M-b)'
7301 Move back to the start of the current or previous word. Words are
7302 composed of letters and digits.
7304 'clear-screen (C-l)'
7305 Clear the screen and redraw the current line, leaving the current
7306 line at the top of the screen.
7308 'redraw-current-line ()'
7309 Refresh the current line. By default, this is unbound.
7312 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
7314 32.4.2 Commands For Manipulating The History
7315 --------------------------------------------
7317 'accept-line (Newline or Return)'
7318 Accept the line regardless of where the cursor is. If this line is
7319 non-empty, it may be added to the history list for future recall
7320 with 'add_history()'. If this line is a modified history line, the
7321 history line is restored to its original state.
7323 'previous-history (C-p)'
7324 Move 'back' through the history list, fetching the previous
7327 'next-history (C-n)'
7328 Move 'forward' through the history list, fetching the next command.
7330 'beginning-of-history (M-<)'
7331 Move to the first line in the history.
7333 'end-of-history (M->)'
7334 Move to the end of the input history, i.e., the line currently
7337 'reverse-search-history (C-r)'
7338 Search backward starting at the current line and moving 'up'
7339 through the history as necessary. This is an incremental search.
7341 'forward-search-history (C-s)'
7342 Search forward starting at the current line and moving 'down'
7343 through the the history as necessary. This is an incremental
7346 'non-incremental-reverse-search-history (M-p)'
7347 Search backward starting at the current line and moving 'up'
7348 through the history as necessary using a non-incremental search for
7349 a string supplied by the user.
7351 'non-incremental-forward-search-history (M-n)'
7352 Search forward starting at the current line and moving 'down'
7353 through the the history as necessary using a non-incremental search
7354 for a string supplied by the user.
7356 'history-search-forward ()'
7357 Search forward through the history for the string of characters
7358 between the start of the current line and the point. This is a
7359 non-incremental search. By default, this command is unbound.
7361 'history-search-backward ()'
7362 Search backward through the history for the string of characters
7363 between the start of the current line and the point. This is a
7364 non-incremental search. By default, this command is unbound.
7366 'yank-nth-arg (M-C-y)'
7367 Insert the first argument to the previous command (usually the
7368 second word on the previous line) at point. With an argument N,
7369 insert the Nth word from the previous command (the words in the
7370 previous command begin with word 0). A negative argument inserts
7371 the Nth word from the end of the previous command. Once the
7372 argument N is computed, the argument is extracted as if the '!N'
7373 history expansion had been specified.
7375 'yank-last-arg (M-. or M-_)'
7376 Insert last argument to the previous command (the last word of the
7377 previous history entry). With a numeric argument, behave exactly
7378 like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back
7379 through the history list, inserting the last word (or the word
7380 specified by the argument to the first call) of each line in turn.
7381 Any numeric argument supplied to these successive calls determines
7382 the direction to move through the history. A negative argument
7383 switches the direction through the history (back or forward). The
7384 history expansion facilities are used to extract the last argument,
7385 as if the '!$' history expansion had been specified.
7388 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
7390 32.4.3 Commands For Changing Text
7391 ---------------------------------
7394 Delete the character at point. If point is at the beginning of the
7395 line, there are no characters in the line, and the last character
7396 typed was not bound to 'delete-char', then return EOF.
7398 'backward-delete-char (Rubout)'
7399 Delete the character behind the cursor. A numeric argument means
7400 to kill the characters instead of deleting them.
7402 'forward-backward-delete-char ()'
7403 Delete the character under the cursor, unless the cursor is at the
7404 end of the line, in which case the character behind the cursor is
7405 deleted. By default, this is not bound to a key.
7407 'quoted-insert (C-q or C-v)'
7408 Add the next character typed to the line verbatim. This is how to
7409 insert key sequences like 'C-q', for example.
7411 'tab-insert (M-<TAB>)'
7412 Insert a tab character.
7414 'self-insert (a, b, A, 1, !, ...)'
7417 'transpose-chars (C-t)'
7418 Drag the character before the cursor forward over the character at
7419 the cursor, moving the cursor forward as well. If the insertion
7420 point is at the end of the line, then this transposes the last two
7421 characters of the line. Negative arguments have no effect.
7423 'transpose-words (M-t)'
7424 Drag the word before point past the word after point, moving point
7425 past that word as well. If the insertion point is at the end of
7426 the line, this transposes the last two words on the line.
7429 Uppercase the current (or following) word. With a negative
7430 argument, uppercase the previous word, but do not move the cursor.
7432 'downcase-word (M-l)'
7433 Lowercase the current (or following) word. With a negative
7434 argument, lowercase the previous word, but do not move the cursor.
7436 'capitalize-word (M-c)'
7437 Capitalize the current (or following) word. With a negative
7438 argument, capitalize the previous word, but do not move the cursor.
7441 Toggle overwrite mode. With an explicit positive numeric argument,
7442 switches to overwrite mode. With an explicit non-positive numeric
7443 argument, switches to insert mode. This command affects only
7444 'emacs' mode; 'vi' mode does overwrite differently. Each call to
7445 'readline()' starts in insert mode.
7447 In overwrite mode, characters bound to 'self-insert' replace the
7448 text at point rather than pushing the text to the right.
7449 Characters bound to 'backward-delete-char' replace the character
7450 before point with a space.
7452 By default, this command is unbound.
7455 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
7457 32.4.4 Killing And Yanking
7458 --------------------------
7461 Kill the text from point to the end of the line.
7463 'backward-kill-line (C-x Rubout)'
7464 Kill backward to the beginning of the line.
7466 'unix-line-discard (C-u)'
7467 Kill backward from the cursor to the beginning of the current line.
7469 'kill-whole-line ()'
7470 Kill all characters on the current line, no matter where point is.
7471 By default, this is unbound.
7474 Kill from point to the end of the current word, or if between
7475 words, to the end of the next word. Word boundaries are the same
7478 'backward-kill-word (M-<DEL>)'
7479 Kill the word behind point. Word boundaries are the same as
7482 'unix-word-rubout (C-w)'
7483 Kill the word behind point, using white space as a word boundary.
7484 The killed text is saved on the kill-ring.
7486 'unix-filename-rubout ()'
7487 Kill the word behind point, using white space and the slash
7488 character as the word boundaries. The killed text is saved on the
7491 'delete-horizontal-space ()'
7492 Delete all spaces and tabs around point. By default, this is
7496 Kill the text in the current region. By default, this command is
7499 'copy-region-as-kill ()'
7500 Copy the text in the region to the kill buffer, so it can be yanked
7501 right away. By default, this command is unbound.
7503 'copy-backward-word ()'
7504 Copy the word before point to the kill buffer. The word boundaries
7505 are the same as 'backward-word'. By default, this command is
7508 'copy-forward-word ()'
7509 Copy the word following point to the kill buffer. The word
7510 boundaries are the same as 'forward-word'. By default, this
7514 Yank the top of the kill ring into the buffer at point.
7517 Rotate the kill-ring, and yank the new top. You can only do this
7518 if the prior command is 'yank' or 'yank-pop'.
7521 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
7523 32.4.5 Specifying Numeric Arguments
7524 -----------------------------------
7526 'digit-argument (M-0, M-1, ... M--)'
7527 Add this digit to the argument already accumulating, or start a new
7528 argument. 'M--' starts a negative argument.
7530 'universal-argument ()'
7531 This is another way to specify an argument. If this command is
7532 followed by one or more digits, optionally with a leading minus
7533 sign, those digits define the argument. If the command is followed
7534 by digits, executing 'universal-argument' again ends the numeric
7535 argument, but is otherwise ignored. As a special case, if this
7536 command is immediately followed by a character that is neither a
7537 digit or minus sign, the argument count for the next command is
7538 multiplied by four. The argument count is initially one, so
7539 executing this function the first time makes the argument count
7540 four, a second time makes the argument count sixteen, and so on.
7541 By default, this is not bound to a key.
7544 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
7546 32.4.6 Letting Readline Type For You
7547 ------------------------------------
7550 Attempt to perform completion on the text before point. The actual
7551 completion performed is application-specific. The default is
7552 filename completion.
7554 'possible-completions (M-?)'
7555 List the possible completions of the text before point. When
7556 displaying completions, Readline sets the number of columns used
7557 for display to the value of 'completion-display-width', the value
7558 of the environment variable 'COLUMNS', or the screen width, in that
7561 'insert-completions (M-*)'
7562 Insert all completions of the text before point that would have
7563 been generated by 'possible-completions'.
7566 Similar to 'complete', but replaces the word to be completed with a
7567 single match from the list of possible completions. Repeated
7568 execution of 'menu-complete' steps through the list of possible
7569 completions, inserting each match in turn. At the end of the list
7570 of completions, the bell is rung (subject to the setting of
7571 'bell-style') and the original text is restored. An argument of N
7572 moves N positions forward in the list of matches; a negative
7573 argument may be used to move backward through the list. This
7574 command is intended to be bound to <TAB>, but is unbound by
7577 'menu-complete-backward ()'
7578 Identical to 'menu-complete', but moves backward through the list
7579 of possible completions, as if 'menu-complete' had been given a
7582 'delete-char-or-list ()'
7583 Deletes the character under the cursor if not at the beginning or
7584 end of the line (like 'delete-char'). If at the end of the line,
7585 behaves identically to 'possible-completions'. This command is
7589 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
7591 32.4.7 Keyboard Macros
7592 ----------------------
7594 'start-kbd-macro (C-x ()'
7595 Begin saving the characters typed into the current keyboard macro.
7597 'end-kbd-macro (C-x ))'
7598 Stop saving the characters typed into the current keyboard macro
7599 and save the definition.
7601 'call-last-kbd-macro (C-x e)'
7602 Re-execute the last keyboard macro defined, by making the
7603 characters in the macro appear as if typed at the keyboard.
7606 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
7608 32.4.8 Some Miscellaneous Commands
7609 ----------------------------------
7611 're-read-init-file (C-x C-r)'
7612 Read in the contents of the INPUTRC file, and incorporate any
7613 bindings or variable assignments found there.
7616 Abort the current editing command and ring the terminal's bell
7617 (subject to the setting of 'bell-style').
7619 'do-uppercase-version (M-a, M-b, M-X, ...)'
7620 If the metafied character X is lowercase, run the command that is
7621 bound to the corresponding uppercase character.
7623 'prefix-meta (<ESC>)'
7624 Metafy the next character typed. This is for keyboards without a
7625 meta key. Typing '<ESC> f' is equivalent to typing 'M-f'.
7627 'undo (C-_ or C-x C-u)'
7628 Incremental undo, separately remembered for each line.
7631 Undo all changes made to this line. This is like executing the
7632 'undo' command enough times to get back to the beginning.
7634 'tilde-expand (M-~)'
7635 Perform tilde expansion on the current word.
7638 Set the mark to the point. If a numeric argument is supplied, the
7639 mark is set to that position.
7641 'exchange-point-and-mark (C-x C-x)'
7642 Swap the point with the mark. The current cursor position is set
7643 to the saved position, and the old cursor position is saved as the
7646 'character-search (C-])'
7647 A character is read and point is moved to the next occurrence of
7648 that character. A negative count searches for previous
7651 'character-search-backward (M-C-])'
7652 A character is read and point is moved to the previous occurrence
7653 of that character. A negative count searches for subsequent
7656 'skip-csi-sequence ()'
7657 Read enough characters to consume a multi-key sequence such as
7658 those defined for keys like Home and End. Such sequences begin
7659 with a Control Sequence Indicator (CSI), usually ESC-[. If this
7660 sequence is bound to "\e[", keys producing such sequences will have
7661 no effect unless explicitly bound to a readline command, instead of
7662 inserting stray characters into the editing buffer. This is
7663 unbound by default, but usually bound to ESC-[.
7665 'insert-comment (M-#)'
7666 Without a numeric argument, the value of the 'comment-begin'
7667 variable is inserted at the beginning of the current line. If a
7668 numeric argument is supplied, this command acts as a toggle: if the
7669 characters at the beginning of the line do not match the value of
7670 'comment-begin', the value is inserted, otherwise the characters in
7671 'comment-begin' are deleted from the beginning of the line. In
7672 either case, the line is accepted as if a newline had been typed.
7675 Print all of the functions and their key bindings to the Readline
7676 output stream. If a numeric argument is supplied, the output is
7677 formatted in such a way that it can be made part of an INPUTRC
7678 file. This command is unbound by default.
7681 Print all of the settable variables and their values to the
7682 Readline output stream. If a numeric argument is supplied, the
7683 output is formatted in such a way that it can be made part of an
7684 INPUTRC file. This command is unbound by default.
7687 Print all of the Readline key sequences bound to macros and the
7688 strings they output. If a numeric argument is supplied, the output
7689 is formatted in such a way that it can be made part of an INPUTRC
7690 file. This command is unbound by default.
7692 'emacs-editing-mode (C-e)'
7693 When in 'vi' command mode, this causes a switch to 'emacs' editing
7696 'vi-editing-mode (M-C-j)'
7697 When in 'emacs' editing mode, this causes a switch to 'vi' editing
7701 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
7703 32.5 Readline vi Mode
7704 =====================
7706 While the Readline library does not have a full set of 'vi' editing
7707 functions, it does contain enough to allow simple editing of the line.
7708 The Readline 'vi' mode behaves as specified in the POSIX standard.
7710 In order to switch interactively between 'emacs' and 'vi' editing
7711 modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi'
7712 mode and to vi-editing-mode in 'emacs' mode). The Readline default is
7715 When you enter a line in 'vi' mode, you are already placed in
7716 'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches
7717 you into 'command' mode, where you can edit the text of the line with
7718 the standard 'vi' movement keys, move to previous history lines with 'k'
7719 and subsequent lines with 'j', and so forth.
7722 File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top
7724 33 Using History Interactively
7725 ******************************
7727 This chapter describes how to use the GNU History Library interactively,
7728 from a user's standpoint. It should be considered a user's guide. For
7729 information on using the GNU History Library in your own programs, *note
7730 (history)Programming with GNU History::.
7734 * History Interaction:: What it feels like using History as a user.
7737 File: gdb.info, Node: History Interaction, Up: Using History Interactively
7739 33.1 History Expansion
7740 ======================
7742 The History library provides a history expansion feature that is similar
7743 to the history expansion provided by 'csh'. This section describes the
7744 syntax used to manipulate the history information.
7746 History expansions introduce words from the history list into the
7747 input stream, making it easy to repeat commands, insert the arguments to
7748 a previous command into the current input line, or fix errors in
7749 previous commands quickly.
7751 History expansion takes place in two parts. The first is to
7752 determine which line from the history list should be used during
7753 substitution. The second is to select portions of that line for
7754 inclusion into the current one. The line selected from the history is
7755 called the "event", and the portions of that line that are acted upon
7756 are called "words". Various "modifiers" are available to manipulate the
7757 selected words. The line is broken into words in the same fashion that
7758 Bash does, so that several words surrounded by quotes are considered one
7759 word. History expansions are introduced by the appearance of the
7760 history expansion character, which is '!' by default.
7764 * Event Designators:: How to specify which history line to use.
7765 * Word Designators:: Specifying which words are of interest.
7766 * Modifiers:: Modifying the results of substitution.
7769 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
7771 33.1.1 Event Designators
7772 ------------------------
7774 An event designator is a reference to a command line entry in the
7775 history list. Unless the reference is absolute, events are relative to
7776 the current position in the history list.
7779 Start a history substitution, except when followed by a space, tab,
7780 the end of the line, or '='.
7783 Refer to command line N.
7786 Refer to the command N lines back.
7789 Refer to the previous command. This is a synonym for '!-1'.
7792 Refer to the most recent command preceding the current position in
7793 the history list starting with STRING.
7796 Refer to the most recent command preceding the current position in
7797 the history list containing STRING. The trailing '?' may be
7798 omitted if the STRING is followed immediately by a newline.
7801 Quick Substitution. Repeat the last command, replacing STRING1
7802 with STRING2. Equivalent to '!!:s/STRING1/STRING2/'.
7805 The entire command line typed so far.
7808 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
7810 33.1.2 Word Designators
7811 -----------------------
7813 Word designators are used to select desired words from the event. A ':'
7814 separates the event specification from the word designator. It may be
7815 omitted if the word designator begins with a '^', '$', '*', '-', or '%'.
7816 Words are numbered from the beginning of the line, with the first word
7817 being denoted by 0 (zero). Words are inserted into the current line
7818 separated by single spaces.
7823 designates the preceding command. When you type this, the
7824 preceding command is repeated in toto.
7827 designates the last argument of the preceding command. This may be
7831 designates the second argument of the most recent command starting
7832 with the letters 'fi'.
7834 Here are the word designators:
7837 The '0'th word. For many applications, this is the command word.
7843 The first argument; that is, word 1.
7849 The word matched by the most recent '?STRING?' search.
7852 A range of words; '-Y' abbreviates '0-Y'.
7855 All of the words, except the '0'th. This is a synonym for '1-$'.
7856 It is not an error to use '*' if there is just one word in the
7857 event; the empty string is returned in that case.
7863 Abbreviates 'X-$' like 'X*', but omits the last word.
7865 If a word designator is supplied without an event specification, the
7866 previous command is used as the event.
7869 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
7874 After the optional word designator, you can add a sequence of one or
7875 more of the following modifiers, each preceded by a ':'.
7878 Remove a trailing pathname component, leaving only the head.
7881 Remove all leading pathname components, leaving the tail.
7884 Remove a trailing suffix of the form '.SUFFIX', leaving the
7888 Remove all but the trailing suffix.
7891 Print the new command but do not execute it.
7894 Substitute NEW for the first occurrence of OLD in the event line.
7895 Any delimiter may be used in place of '/'. The delimiter may be
7896 quoted in OLD and NEW with a single backslash. If '&' appears in
7897 NEW, it is replaced by OLD. A single backslash will quote the '&'.
7898 The final delimiter is optional if it is the last character on the
7902 Repeat the previous substitution.
7906 Cause changes to be applied over the entire event line. Used in
7907 conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.
7910 Apply the following 's' modifier once to each word in the event.
7913 File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top
7915 Appendix A In Memoriam
7916 **********************
7918 The GDB project mourns the loss of the following long-time contributors:
7921 Fred was a long-standing contributor to GDB (1991-2006), and to
7922 Free Software in general. Outside of GDB, he was known in the
7923 Amiga world for his series of Fish Disks, and the GeekGadget
7927 Michael was one of the Global Maintainers of the GDB project, with
7928 contributions recorded as early as 1996, until 2011. In addition
7929 to his day to day participation, he was a large driving force
7930 behind adding Reverse Debugging to GDB.
7932 Beyond their technical contributions to the project, they were also
7933 enjoyable members of the Free Software Community. We will miss them.
7936 File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top
7938 Appendix B Formatting Documentation
7939 ***********************************
7941 The GDB 4 release includes an already-formatted reference card, ready
7942 for printing with PostScript or Ghostscript, in the 'gdb' subdirectory
7943 of the main source directory(1). If you can use PostScript or
7944 Ghostscript with your printer, you can print the reference card
7945 immediately with 'refcard.ps'.
7947 The release also includes the source for the reference card. You can
7948 format it, using TeX, by typing:
7952 The GDB reference card is designed to print in "landscape" mode on US
7953 "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
7954 high. You will need to specify this form of printing as an option to
7955 your DVI output program.
7957 All the documentation for GDB comes as part of the machine-readable
7958 distribution. The documentation is written in Texinfo format, which is
7959 a documentation system that uses a single source file to produce both
7960 on-line information and a printed manual. You can use one of the Info
7961 formatting commands to create the on-line version of the documentation
7962 and TeX (or 'texi2roff') to typeset the printed version.
7964 GDB includes an already formatted copy of the on-line Info version of
7965 this manual in the 'gdb' subdirectory. The main Info file is
7966 'gdb-7.9/gdb/gdb.info', and it refers to subordinate files matching
7967 'gdb.info*' in the same directory. If necessary, you can print out
7968 these files, or read them with any editor; but they are easier to read
7969 using the 'info' subsystem in GNU Emacs or the standalone 'info'
7970 program, available as part of the GNU Texinfo distribution.
7972 If you want to format these Info files yourself, you need one of the
7973 Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'.
7975 If you have 'makeinfo' installed, and are in the top level GDB source
7976 directory ('gdb-7.9', in the case of version 7.9), you can make the Info
7982 If you want to typeset and print copies of this manual, you need TeX,
7983 a program to print its DVI output files, and 'texinfo.tex', the Texinfo
7986 TeX is a typesetting program; it does not print files directly, but
7987 produces output files called DVI files. To print a typeset document,
7988 you need a program to print DVI files. If your system has TeX
7989 installed, chances are it has such a program. The precise command to
7990 use depends on your system; 'lpr -d' is common; another (for PostScript
7991 devices) is 'dvips'. The DVI print command may require a file name
7992 without any extension or a '.dvi' extension.
7994 TeX also requires a macro definitions file called 'texinfo.tex'.
7995 This file tells TeX how to typeset a document written in Texinfo format.
7996 On its own, TeX cannot either read or typeset a Texinfo file.
7997 'texinfo.tex' is distributed with GDB and is located in the
7998 'gdb-VERSION-NUMBER/texinfo' directory.
8000 If you have TeX and a DVI printer program installed, you can typeset
8001 and print this manual. First switch to the 'gdb' subdirectory of the
8002 main source directory (for example, to 'gdb-7.9/gdb') and type:
8006 Then give 'gdb.dvi' to your DVI printing program.
8008 ---------- Footnotes ----------
8010 (1) In 'gdb-7.9/gdb/refcard.ps' of the version 7.9 release.
8013 File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
8015 Appendix C Installing GDB
8016 *************************
8020 * Requirements:: Requirements for building GDB
8021 * Running Configure:: Invoking the GDB 'configure' script
8022 * Separate Objdir:: Compiling GDB in another directory
8023 * Config Names:: Specifying names for hosts and targets
8024 * Configure Options:: Summary of options for configure
8025 * System-wide configuration:: Having a system-wide init file
8028 File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
8030 C.1 Requirements for Building GDB
8031 =================================
8033 Building GDB requires various tools and packages to be available. Other
8034 packages will be used only if they are found.
8036 Tools/Packages Necessary for Building GDB
8037 =========================================
8040 GDB is written in ISO C90. It should be buildable with any working
8041 C90 compiler, e.g. GCC.
8043 Tools/Packages Optional for Building GDB
8044 ========================================
8047 GDB can use the Expat XML parsing library. This library may be
8048 included with your operating system distribution; if it is not, you
8049 can get the latest version from <http://expat.sourceforge.net>.
8050 The 'configure' script will search for this library in several
8051 standard locations; if it is installed in an unusual path, you can
8052 use the '--with-libexpat-prefix' option to specify its location.
8056 * Remote protocol memory maps (*note Memory Map Format::)
8057 * Target descriptions (*note Target Descriptions::)
8058 * Remote shared library lists (*Note Library List Format::, or
8059 alternatively *note Library List Format for SVR4 Targets::)
8060 * MS-Windows shared libraries (*note Shared Libraries::)
8061 * Traceframe info (*note Traceframe Info Format::)
8062 * Branch trace (*note Branch Trace Format::)
8065 GDB will use the 'zlib' library, if available, to read compressed
8066 debug sections. Some linkers, such as GNU gold, are capable of
8067 producing binaries with compressed debug sections. If GDB is
8068 compiled with 'zlib', it will be able to read the debug information
8071 The 'zlib' library is likely included with your operating system
8072 distribution; if it is not, you can get the latest version from
8076 GDB's features related to character sets (*note Character Sets::)
8077 require a functioning 'iconv' implementation. If you are on a GNU
8078 system, then this is provided by the GNU C Library. Some other
8079 systems also provide a working 'iconv'.
8081 If GDB is using the 'iconv' program which is installed in a
8082 non-standard place, you will need to tell GDB where to find it.
8083 This is done with '--with-iconv-bin' which specifies the directory
8084 that contains the 'iconv' program.
8086 On systems without 'iconv', you can install GNU Libiconv. If you
8087 have previously installed Libiconv, you can use the
8088 '--with-libiconv-prefix' option to configure.
8090 GDB's top-level 'configure' and 'Makefile' will arrange to build
8091 Libiconv if a directory named 'libiconv' appears in the top-most
8092 source directory. If Libiconv is built this way, and if the
8093 operating system does not provide a suitable 'iconv'
8094 implementation, then the just-built library will automatically be
8095 used by GDB. One easy way to set this up is to download GNU
8096 Libiconv, unpack it, and then rename the directory holding the
8097 Libiconv source code to 'libiconv'.
8100 File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
8102 C.2 Invoking the GDB 'configure' Script
8103 =======================================
8105 GDB comes with a 'configure' script that automates the process of
8106 preparing GDB for installation; you can then use 'make' to build the
8109 The GDB distribution includes all the source code you need for GDB in
8110 a single directory, whose name is usually composed by appending the
8111 version number to 'gdb'.
8113 For example, the GDB version 7.9 distribution is in the 'gdb-7.9'
8114 directory. That directory contains:
8116 'gdb-7.9/configure (and supporting files)'
8117 script for configuring GDB and all its supporting libraries
8120 the source specific to GDB itself
8123 source for the Binary File Descriptor library
8129 source for the '-liberty' free software library
8132 source for the library of opcode tables and disassemblers
8135 source for the GNU command-line interface
8138 source for the GNU filename pattern-matching subroutine
8141 source for the GNU memory-mapped malloc package
8143 The simplest way to configure and build GDB is to run 'configure'
8144 from the 'gdb-VERSION-NUMBER' source directory, which in this example is
8145 the 'gdb-7.9' directory.
8147 First switch to the 'gdb-VERSION-NUMBER' source directory if you are
8148 not already in it; then run 'configure'. Pass the identifier for the
8149 platform on which GDB will run as an argument.
8157 where HOST is an identifier such as 'sun4' or 'decstation', that
8158 identifies the platform where GDB will run. (You can often leave off
8159 HOST; 'configure' tries to guess the correct value by examining your
8162 Running 'configure HOST' and then running 'make' builds the 'bfd',
8163 'readline', 'mmalloc', and 'libiberty' libraries, then 'gdb' itself.
8164 The configured source files, and the binaries, are left in the
8165 corresponding source directories.
8167 'configure' is a Bourne-shell ('/bin/sh') script; if your system does
8168 not recognize this automatically when you run a different shell, you may
8169 need to run 'sh' on it explicitly:
8173 If you run 'configure' from a directory that contains source
8174 directories for multiple libraries or programs, such as the 'gdb-7.9'
8175 source directory for version 7.9, 'configure' creates configuration
8176 files for every directory level underneath (unless you tell it not to,
8177 with the '--norecursion' option).
8179 You should run the 'configure' script from the top directory in the
8180 source tree, the 'gdb-VERSION-NUMBER' directory. If you run 'configure'
8181 from one of the subdirectories, you will configure only that
8182 subdirectory. That is usually not what you want. In particular, if you
8183 run the first 'configure' from the 'gdb' subdirectory of the
8184 'gdb-VERSION-NUMBER' directory, you will omit the configuration of
8185 'bfd', 'readline', and other sibling directories of the 'gdb'
8186 subdirectory. This leads to build errors about missing include files
8187 such as 'bfd/bfd.h'.
8189 You can install 'gdb' anywhere; it has no hardwired paths. However,
8190 you should make sure that the shell on your path (named by the 'SHELL'
8191 environment variable) is publicly readable. Remember that GDB uses the
8192 shell to start your program--some systems refuse to let GDB debug child
8193 processes whose programs are not readable.
8196 File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
8198 C.3 Compiling GDB in Another Directory
8199 ======================================
8201 If you want to run GDB versions for several host or target machines, you
8202 need a different 'gdb' compiled for each combination of host and target.
8203 'configure' is designed to make this easy by allowing you to generate
8204 each configuration in a separate subdirectory, rather than in the source
8205 directory. If your 'make' program handles the 'VPATH' feature (GNU
8206 'make' does), running 'make' in each of these directories builds the
8207 'gdb' program specified there.
8209 To build 'gdb' in a separate directory, run 'configure' with the
8210 '--srcdir' option to specify where to find the source. (You also need
8211 to specify a path to find 'configure' itself from your working
8212 directory. If the path to 'configure' would be the same as the argument
8213 to '--srcdir', you can leave out the '--srcdir' option; it is assumed.)
8215 For example, with version 7.9, you can build GDB in a separate
8216 directory for a Sun 4 like this:
8221 ../gdb-7.9/configure sun4
8224 When 'configure' builds a configuration using a remote source
8225 directory, it creates a tree for the binaries with the same structure
8226 (and using the same names) as the tree under the source directory. In
8227 the example, you'd find the Sun 4 library 'libiberty.a' in the directory
8228 'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'.
8230 Make sure that your path to the 'configure' script has just one
8231 instance of 'gdb' in it. If your path to 'configure' looks like
8232 '../gdb-7.9/gdb/configure', you are configuring only one subdirectory of
8233 GDB, not the whole package. This leads to build errors about missing
8234 include files such as 'bfd/bfd.h'.
8236 One popular reason to build several GDB configurations in separate
8237 directories is to configure GDB for cross-compiling (where GDB runs on
8238 one machine--the "host"--while debugging programs that run on another
8239 machine--the "target"). You specify a cross-debugging target by giving
8240 the '--target=TARGET' option to 'configure'.
8242 When you run 'make' to build a program or library, you must run it in
8243 a configured directory--whatever directory you were in when you called
8244 'configure' (or one of its subdirectories).
8246 The 'Makefile' that 'configure' generates in each source directory
8247 also runs recursively. If you type 'make' in a source directory such as
8248 'gdb-7.9' (or in a separate configured directory configured with
8249 '--srcdir=DIRNAME/gdb-7.9'), you will build all the required libraries,
8252 When you have multiple hosts or targets configured in separate
8253 directories, you can run 'make' on them in parallel (for example, if
8254 they are NFS-mounted on each of the hosts); they will not interfere with
8258 File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
8260 C.4 Specifying Names for Hosts and Targets
8261 ==========================================
8263 The specifications used for hosts and targets in the 'configure' script
8264 are based on a three-part naming scheme, but some short predefined
8265 aliases are also supported. The full naming scheme encodes three pieces
8266 of information in the following pattern:
8268 ARCHITECTURE-VENDOR-OS
8270 For example, you can use the alias 'sun4' as a HOST argument, or as
8271 the value for TARGET in a '--target=TARGET' option. The equivalent full
8272 name is 'sparc-sun-sunos4'.
8274 The 'configure' script accompanying GDB does not provide any query
8275 facility to list all supported host and target names or aliases.
8276 'configure' calls the Bourne shell script 'config.sub' to map
8277 abbreviations to full names; you can read the script, if you wish, or
8278 you can use it to test your guesses on abbreviations--for example:
8280 % sh config.sub i386-linux
8282 % sh config.sub alpha-linux
8283 alpha-unknown-linux-gnu
8284 % sh config.sub hp9k700
8286 % sh config.sub sun4
8287 sparc-sun-sunos4.1.1
8288 % sh config.sub sun3
8290 % sh config.sub i986v
8291 Invalid configuration `i986v': machine `i986v' not recognized
8293 'config.sub' is also distributed in the GDB source directory ('gdb-7.9',
8297 File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
8299 C.5 'configure' Options
8300 =======================
8302 Here is a summary of the 'configure' options and arguments that are most
8303 often useful for building GDB. 'configure' also has several other
8304 options not listed here. *note (configure.info)What Configure Does::,
8305 for a full explanation of 'configure'.
8311 [--norecursion] [--rm]
8315 You may introduce options with a single '-' rather than '--' if you
8316 prefer; but you may abbreviate option names if you use '--'.
8319 Display a quick summary of how to invoke 'configure'.
8322 Configure the source to install programs and files under directory
8326 Configure the source to install programs under directory 'DIR'.
8329 *Warning: using this option requires GNU 'make', or another 'make'
8330 that implements the 'VPATH' feature.*
8331 Use this option to make configurations in directories separate from
8332 the GDB source directories. Among other things, you can use this
8333 to build (or maintain) several configurations simultaneously, in
8334 separate directories. 'configure' writes configuration-specific
8335 files in the current directory, but arranges for them to use the
8336 source in the directory DIRNAME. 'configure' creates directories
8337 under the working directory in parallel to the source directories
8341 Configure only the directory level where 'configure' is executed;
8342 do not propagate configuration to subdirectories.
8345 Configure GDB for cross-debugging programs running on the specified
8346 TARGET. Without this option, GDB is configured to debug programs
8347 that run on the same machine (HOST) as GDB itself.
8349 There is no convenient way to generate a list of all available
8353 Configure GDB to run on the specified HOST.
8355 There is no convenient way to generate a list of all available
8358 There are many other options available as well, but they are
8359 generally needed for special purposes only.
8362 File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
8364 C.6 System-wide configuration and settings
8365 ==========================================
8367 GDB can be configured to have a system-wide init file; this file will be
8368 read and executed at startup (*note What GDB does during startup:
8371 Here is the corresponding configure option:
8373 '--with-system-gdbinit=FILE'
8374 Specify that the default location of the system-wide init file is
8377 If GDB has been configured with the option '--prefix=$prefix', it may
8378 be subject to relocation. Two possible cases:
8380 * If the default location of this init file contains '$prefix', it
8381 will be subject to relocation. Suppose that the configure options
8382 are '--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
8383 if GDB is moved from '$prefix' to '$install', the system init file
8384 is looked for as '$install/etc/gdbinit' instead of
8385 '$prefix/etc/gdbinit'.
8387 * By contrast, if the default location does not contain the prefix,
8388 it will not be relocated. E.g. if GDB has been configured with
8389 '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
8390 then GDB will always look for '/usr/share/gdb/gdbinit', wherever
8393 If the configured location of the system-wide init file (as given by
8394 the '--with-system-gdbinit' option at configure time) is in the
8395 data-directory (as specified by '--with-gdb-datadir' at configure time)
8396 or in one of its subdirectories, then GDB will look for the system-wide
8397 init file in the directory specified by the '--data-directory'
8398 command-line option. Note that the system-wide init file is only read
8399 once, during GDB initialization. If the data-directory is changed after
8400 GDB has started with the 'set data-directory' command, the file will not
8405 * System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
8408 File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration
8410 C.6.1 Installed System-wide Configuration Scripts
8411 -------------------------------------------------
8413 The 'system-gdbinit' directory, located inside the data-directory (as
8414 specified by '--with-gdb-datadir' at configure time) contains a number
8415 of scripts which can be used as system-wide init files. To
8416 automatically source those scripts at startup, GDB should be configured
8417 with '--with-system-gdbinit'. Otherwise, any user should be able to
8418 source them by hand as needed.
8420 The following scripts are currently available:
8422 * 'elinos.py' This script is useful when debugging a program on an
8423 ELinOS target. It takes advantage of the environment variables
8424 defined in a standard ELinOS environment in order to determine the
8425 location of the system shared libraries, and then sets the
8426 'solib-absolute-prefix' and 'solib-search-path' variables
8429 * 'wrs-linux.py' This script is useful when debugging a program on a
8430 target running Wind River Linux. It expects the 'ENV_PREFIX' to be
8431 set to the host-side sysroot used by the target system.
8434 File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
8436 Appendix D Maintenance Commands
8437 *******************************
8439 In addition to commands intended for GDB users, GDB includes a number of
8440 commands intended for GDB developers, that are not documented elsewhere
8441 in this manual. These commands are provided here for reference. (For
8442 commands that turn on debugging messages, see *note Debugging Output::.)
8444 'maint agent [-at LOCATION,] EXPRESSION'
8445 'maint agent-eval [-at LOCATION,] EXPRESSION'
8446 Translate the given EXPRESSION into remote agent bytecodes. This
8447 command is useful for debugging the Agent Expression mechanism
8448 (*note Agent Expressions::). The 'agent' version produces an
8449 expression useful for data collection, such as by tracepoints,
8450 while 'maint agent-eval' produces an expression that evaluates
8451 directly to a result. For instance, a collection expression for
8452 'globa + globb' will include bytecodes to record four bytes of
8453 memory at each of the addresses of 'globa' and 'globb', while
8454 discarding the result of the addition, while an evaluation
8455 expression will do the addition and return the sum. If '-at' is
8456 given, generate remote agent bytecode for LOCATION. If not,
8457 generate remote agent bytecode for current frame PC address.
8459 'maint agent-printf FORMAT,EXPR,...'
8460 Translate the given format string and list of argument expressions
8461 into remote agent bytecodes and display them as a disassembled
8462 list. This command is useful for debugging the agent version of
8463 dynamic printf (*note Dynamic Printf::).
8465 'maint info breakpoints'
8466 Using the same format as 'info breakpoints', display both the
8467 breakpoints you've set explicitly, and those GDB is using for
8468 internal purposes. Internal breakpoints are shown with negative
8469 breakpoint numbers. The type column identifies what kind of
8470 breakpoint is shown:
8473 Normal, explicitly set breakpoint.
8476 Normal, explicitly set watchpoint.
8479 Internal breakpoint, used to handle correctly stepping through
8483 Internal breakpoint at the target of a 'longjmp'.
8486 Temporary internal breakpoint used by the GDB 'until' command.
8489 Temporary internal breakpoint used by the GDB 'finish'
8493 Shared library events.
8496 This prints information about each 'bfd' object that is known to
8497 GDB. *Note BFD: (bfd)Top.
8499 'set displaced-stepping'
8500 'show displaced-stepping'
8501 Control whether or not GDB will do "displaced stepping" if the
8502 target supports it. Displaced stepping is a way to single-step
8503 over breakpoints without removing them from the inferior, by
8504 executing an out-of-line copy of the instruction that was
8505 originally at the breakpoint location. It is also known as
8506 out-of-line single-stepping.
8508 'set displaced-stepping on'
8509 If the target architecture supports it, GDB will use displaced
8510 stepping to step over breakpoints.
8512 'set displaced-stepping off'
8513 GDB will not use displaced stepping to step over breakpoints,
8514 even if such is supported by the target architecture.
8516 'set displaced-stepping auto'
8517 This is the default mode. GDB will use displaced stepping
8518 only if non-stop mode is active (*note Non-Stop Mode::) and
8519 the target architecture supports displaced stepping.
8521 'maint check-psymtabs'
8522 Check the consistency of currently expanded psymtabs versus
8523 symtabs. Use this to check, for example, whether a symbol is in
8524 one but not the other.
8526 'maint check-symtabs'
8527 Check the consistency of currently expanded symtabs.
8529 'maint expand-symtabs [REGEXP]'
8530 Expand symbol tables. If REGEXP is specified, only expand symbol
8531 tables for file names matching REGEXP.
8533 'maint set catch-demangler-crashes [on|off]'
8534 'maint show catch-demangler-crashes'
8535 Control whether GDB should attempt to catch crashes in the symbol
8536 name demangler. The default is to attempt to catch crashes. If
8537 enabled, the first time a crash is caught, a core file is created,
8538 the offending symbol is displayed and the user is presented with
8539 the option to terminate the current session.
8541 'maint cplus first_component NAME'
8542 Print the first C++ class/namespace component of NAME.
8544 'maint cplus namespace'
8545 Print the list of possible C++ namespaces.
8547 'maint deprecate COMMAND [REPLACEMENT]'
8548 'maint undeprecate COMMAND'
8549 Deprecate or undeprecate the named COMMAND. Deprecated commands
8550 cause GDB to issue a warning when you use them. The optional
8551 argument REPLACEMENT says which newer command should be used in
8552 favor of the deprecated one; if it is given, GDB will mention the
8553 replacement as part of the warning.
8556 Cause a fatal signal in the debugger and force it to dump its core.
8557 This is supported only on systems which support aborting a program
8558 with the 'SIGQUIT' signal.
8560 'maint internal-error [MESSAGE-TEXT]'
8561 'maint internal-warning [MESSAGE-TEXT]'
8562 'maint demangler-warning [MESSAGE-TEXT]'
8564 Cause GDB to call the internal function 'internal_error',
8565 'internal_warning' or 'demangler_warning' and hence behave as
8566 though an internal problam has been detected. In addition to
8567 reporting the internal problem, these functions give the user the
8568 opportunity to either quit GDB or (for 'internal_error' and
8569 'internal_warning') create a core file of the current GDB session.
8571 These commands take an optional parameter MESSAGE-TEXT that is used
8572 as the text of the error or warning message.
8574 Here's an example of using 'internal-error':
8576 (gdb) maint internal-error testing, 1, 2
8577 .../maint.c:121: internal-error: testing, 1, 2
8578 A problem internal to GDB has been detected. Further
8579 debugging may prove unreliable.
8580 Quit this debugging session? (y or n) n
8581 Create a core file? (y or n) n
8584 'maint set internal-error ACTION [ask|yes|no]'
8585 'maint show internal-error ACTION'
8586 'maint set internal-warning ACTION [ask|yes|no]'
8587 'maint show internal-warning ACTION'
8588 'maint set demangler-warning ACTION [ask|yes|no]'
8589 'maint show demangler-warning ACTION'
8590 When GDB reports an internal problem (error or warning) it gives
8591 the user the opportunity to both quit GDB and create a core file of
8592 the current GDB session. These commands let you override the
8593 default behaviour for each particular ACTION, described in the
8597 You can specify that GDB should always (yes) or never (no)
8598 quit. The default is to ask the user what to do.
8601 You can specify that GDB should always (yes) or never (no)
8602 create a core file. The default is to ask the user what to
8603 do. Note that there is no 'corefile' option for
8604 'demangler-warning': demangler warnings always create a core
8605 file and this cannot be disabled.
8608 If GDB is talking to an inferior via the serial protocol, then this
8609 command sends the string TEXT to the inferior, and displays the
8610 response packet. GDB supplies the initial '$' character, the
8611 terminating '#' character, and the checksum.
8613 'maint print architecture [FILE]'
8614 Print the entire architecture configuration. The optional argument
8615 FILE names the file where the output goes.
8617 'maint print c-tdesc'
8618 Print the current target description (*note Target Descriptions::)
8619 as a C source file. The created source file can be used in GDB
8620 when an XML parser is not available to parse the description.
8622 'maint print dummy-frames'
8623 Prints the contents of GDB's internal dummy-frame stack.
8627 (gdb) print add(2,3)
8628 Breakpoint 2, add (a=2, b=3) at ...
8630 The program being debugged stopped while in a function called from GDB.
8632 (gdb) maint print dummy-frames
8633 0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353
8636 Takes an optional file parameter.
8638 'maint print registers [FILE]'
8639 'maint print raw-registers [FILE]'
8640 'maint print cooked-registers [FILE]'
8641 'maint print register-groups [FILE]'
8642 'maint print remote-registers [FILE]'
8643 Print GDB's internal register data structures.
8645 The command 'maint print raw-registers' includes the contents of
8646 the raw register cache; the command 'maint print cooked-registers'
8647 includes the (cooked) value of all registers, including registers
8648 which aren't available on the target nor visible to user; the
8649 command 'maint print register-groups' includes the groups that each
8650 register is a member of; and the command 'maint print
8651 remote-registers' includes the remote target's register numbers and
8652 offsets in the 'G' packets.
8654 These commands take an optional parameter, a file name to which to
8655 write the information.
8657 'maint print reggroups [FILE]'
8658 Print GDB's internal register group data structures. The optional
8659 argument FILE tells to what file to write the information.
8661 The register groups info looks like this:
8663 (gdb) maint print reggroups
8674 This command forces GDB to flush its internal register cache.
8676 'maint print objfiles [REGEXP]'
8677 Print a dump of all known object files. If REGEXP is specified,
8678 only print object files whose names match REGEXP. For each object
8679 file, this command prints its name, address in memory, and all of
8680 its psymtabs and symtabs.
8682 'maint print user-registers'
8683 List all currently available "user registers". User registers
8684 typically provide alternate names for actual hardware registers.
8685 They include the four "standard" registers '$fp', '$pc', '$sp', and
8686 '$ps'. *Note standard registers::. User registers can be used in
8687 expressions in the same way as the canonical register names, but
8688 only the latter are listed by the 'info registers' and 'maint print
8689 registers' commands.
8691 'maint print section-scripts [REGEXP]'
8692 Print a dump of scripts specified in the '.debug_gdb_section'
8693 section. If REGEXP is specified, only print scripts loaded by
8694 object files matching REGEXP. For each script, this command prints
8695 its name as specified in the objfile, and the full path if known.
8696 *Note dotdebug_gdb_scripts section::.
8698 'maint print statistics'
8699 This command prints, for each object file in the program, various
8700 data about that object file followed by the byte cache ("bcache")
8701 statistics for the object file. The objfile data includes the
8702 number of minimal, partial, full, and stabs symbols, the number of
8703 types defined by the objfile, the number of as yet unexpanded psym
8704 tables, the number of line tables and string tables, and the amount
8705 of memory used by the various tables. The bcache statistics
8706 include the counts, sizes, and counts of duplicates of all and
8707 unique objects, max, average, and median entry size, total memory
8708 used and its overhead and savings, and various measures of the hash
8709 table size and chain lengths.
8711 'maint print target-stack'
8712 A "target" is an interface between the debugger and a particular
8713 kind of file or process. Targets can be stacked in "strata", so
8714 that more than one target can potentially respond to a request. In
8715 particular, memory accesses will walk down the stack of targets
8716 until they find a target that is interested in handling that
8719 This command prints a short description of each layer that was
8720 pushed on the "target stack", starting from the top layer down to
8723 'maint print type EXPR'
8724 Print the type chain for a type specified by EXPR. The argument
8725 can be either a type name or a symbol. If it is a symbol, the type
8726 of that symbol is described. The type chain produced by this
8727 command is a recursive definition of the data type as stored in
8728 GDB's data structures, including its flags and contained types.
8730 'maint set dwarf2 always-disassemble'
8731 'maint show dwarf2 always-disassemble'
8732 Control the behavior of 'info address' when using DWARF debugging
8735 The default is 'off', which means that GDB should try to describe a
8736 variable's location in an easily readable format. When 'on', GDB
8737 will instead display the DWARF location expression in an
8738 assembly-like format. Note that some locations are too complex for
8739 GDB to describe simply; in this case you will always see the
8742 Here is an example of the resulting disassembly:
8744 (gdb) info addr argc
8745 Symbol "argc" is a complex DWARF expression:
8748 For more information on these expressions, see the DWARF standard
8749 (http://www.dwarfstd.org/).
8751 'maint set dwarf2 max-cache-age'
8752 'maint show dwarf2 max-cache-age'
8753 Control the DWARF 2 compilation unit cache.
8755 In object files with inter-compilation-unit references, such as
8756 those produced by the GCC option '-feliminate-dwarf2-dups', the
8757 DWARF 2 reader needs to frequently refer to previously read
8758 compilation units. This setting controls how long a compilation
8759 unit will remain in the cache if it is not referenced. A higher
8760 limit means that cached compilation units will be stored in memory
8761 longer, and more total memory will be used. Setting it to zero
8762 disables caching, which will slow down GDB startup, but reduce
8766 'maint show profile'
8767 Control profiling of GDB.
8769 Profiling will be disabled until you use the 'maint set profile'
8770 command to enable it. When you enable profiling, the system will
8771 begin collecting timing and execution count data; when you disable
8772 profiling or exit GDB, the results will be written to a log file.
8773 Remember that if you use profiling, GDB will overwrite the
8774 profiling log file (often called 'gmon.out'). If you have a record
8775 of important profiling data in a 'gmon.out' file, be sure to move
8776 it to a safe location.
8778 Configuring with '--enable-profiling' arranges for GDB to be
8779 compiled with the '-pg' compiler option.
8781 'maint set show-debug-regs'
8782 'maint show show-debug-regs'
8783 Control whether to show variables that mirror the hardware debug
8784 registers. Use 'on' to enable, 'off' to disable. If enabled, the
8785 debug registers values are shown when GDB inserts or removes a
8786 hardware breakpoint or watchpoint, and when the inferior triggers a
8787 hardware-assisted breakpoint or watchpoint.
8789 'maint set show-all-tib'
8790 'maint show show-all-tib'
8791 Control whether to show all non zero areas within a 1k block
8792 starting at thread local base, when using the 'info w32
8793 thread-information-block' command.
8795 'maint set target-async'
8796 'maint show target-async'
8797 This controls whether GDB targets operate in synchronous or
8798 asynchronous mode (*note Background Execution::). Normally the
8799 default is asynchronous, if it is available; but this can be
8800 changed to more easily debug problems occurring only in synchronous
8803 'maint set per-command'
8804 'maint show per-command'
8806 GDB can display the resources used by each command. This is useful
8807 in debugging performance problems.
8809 'maint set per-command space [on|off]'
8810 'maint show per-command space'
8811 Enable or disable the printing of the memory used by GDB for
8812 each command. If enabled, GDB will display how much memory
8813 each command took, following the command's own output. This
8814 can also be requested by invoking GDB with the '--statistics'
8815 command-line switch (*note Mode Options::).
8817 'maint set per-command time [on|off]'
8818 'maint show per-command time'
8819 Enable or disable the printing of the execution time of GDB
8820 for each command. If enabled, GDB will display how much time
8821 it took to execute each command, following the command's own
8822 output. Both CPU time and wallclock time are printed.
8823 Printing both is useful when trying to determine whether the
8824 cost is CPU or, e.g., disk/network latency. Note that the CPU
8825 time printed is for GDB only, it does not include the
8826 execution time of the inferior because there's no mechanism
8827 currently to compute how much time was spent by GDB and how
8828 much time was spent by the program been debugged. This can
8829 also be requested by invoking GDB with the '--statistics'
8830 command-line switch (*note Mode Options::).
8832 'maint set per-command symtab [on|off]'
8833 'maint show per-command symtab'
8834 Enable or disable the printing of basic symbol table
8835 statistics for each command. If enabled, GDB will display the
8836 following information:
8838 a. number of symbol tables
8839 b. number of primary symbol tables
8840 c. number of blocks in the blockvector
8843 An alias for 'maint set per-command space'. A non-zero value
8844 enables it, zero disables it.
8847 An alias for 'maint set per-command time'. A non-zero value
8848 enables it, zero disables it.
8850 'maint translate-address [SECTION] ADDR'
8851 Find the symbol stored at the location specified by the address
8852 ADDR and an optional section name SECTION. If found, GDB prints
8853 the name of the closest symbol and an offset from the symbol's
8854 location to the specified address. This is similar to the 'info
8855 address' command (*note Symbols::), except that this command also
8856 allows to find symbols in other sections.
8858 If section was not specified, the section in which the symbol was
8859 found is also printed. For dynamically linked executables, the
8860 name of executable or shared library containing the symbol is
8863 The following command is useful for non-interactive invocations of
8864 GDB, such as in the test suite.
8867 Set the maximum number of seconds GDB will wait for the target
8868 operation to finish. If this time expires, GDB reports and error
8869 and the command is aborted.
8872 Show the current setting of the target wait timeout.