OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gdb-6.8/] [gdb/] [doc/] [gdb.info-3] - Blame information for rev 299

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 24 jeremybenn 
This is gdb.info, produced by makeinfo version 4.8 from
2 
../.././gdb/doc/gdb.texinfo.
3 
 
4 
INFO-DIR-SECTION Software development
5 
START-INFO-DIR-ENTRY
6 
* Gdb: (gdb).                     The GNU debugger.
7 
END-INFO-DIR-ENTRY
8 
 
9 
   This file documents the GNU debugger GDB.
10 
 
11 
   This is the Ninth Edition, of `Debugging with GDB: the GNU
12 
Source-Level Debugger' for GDB Version 6.8.
13 
 
14 
   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
15 
1998,
16 
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
17 
Free Software Foundation, Inc.
18 
 
19 
   Permission is granted to copy, distribute and/or modify this document
20 
under the terms of the GNU Free Documentation License, Version 1.1 or
21 
any later version published by the Free Software Foundation; with the
22 
Invariant Sections being "Free Software" and "Free Software Needs Free
23 
Documentation", with the Front-Cover Texts being "A GNU Manual," and
24 
with the Back-Cover Texts as in (a) below.
25 
 
26 
   (a) The FSF's Back-Cover Text is: "You are free to copy and modify
27 
this GNU Manual.  Buying copies from GNU Press supports the FSF in
28 
developing GNU and promoting software freedom."
29 
 
30 

31 
File: gdb.info,  Node: GDB/MI Command Description Format,  Next: GDB/MI Breakpoint Commands,  Prev: GDB/MI Simple Examples,  Up: GDB/MI
32 
 
33 
24.6 GDB/MI Command Description Format
34 
======================================
35 
 
36 
The remaining sections describe blocks of commands.  Each block of
37 
commands is laid out in a fashion similar to this section.
38 
 
39 
Motivation
40 
----------
41 
 
42 
The motivation for this collection of commands.
43 
 
44 
Introduction
45 
------------
46 
 
47 
A brief introduction to this collection of commands as a whole.
48 
 
49 
Commands
50 
--------
51 
 
52 
For each command in the block, the following is described:
53 
 
54 
Synopsis
55 
........
56 
 
57 
      -command ARGS...
58 
 
59 
Result
60 
......
61 
 
62 
GDB Command
63 
...........
64 
 
65 
The corresponding GDB CLI command(s), if any.
66 
 
67 
Example
68 
.......
69 
 
70 
Example(s) formatted for readability.  Some of the described commands
71 
have not been implemented yet and these are labeled N.A. (not
72 
available).
73 
 
74 

75 
File: gdb.info,  Node: GDB/MI Breakpoint Commands,  Next: GDB/MI Program Context,  Prev: GDB/MI Command Description Format,  Up: GDB/MI
76 
 
77 
24.7 GDB/MI Breakpoint Commands
78 
===============================
79 
 
80 
This section documents GDB/MI commands for manipulating breakpoints.
81 
 
82 
The `-break-after' Command
83 
--------------------------
84 
 
85 
Synopsis
86 
........
87 
 
88 
      -break-after NUMBER COUNT
89 
 
90 
   The breakpoint number NUMBER is not in effect until it has been hit
91 
COUNT times.  To see how this is reflected in the output of the
92 
`-break-list' command, see the description of the `-break-list' command
93 
below.
94 
 
95 
GDB Command
96 
...........
97 
 
98 
The corresponding GDB command is `ignore'.
99 
 
100 
Example
101 
.......
102 
 
103 
     (gdb)
104 
     -break-insert main
105 
     ^done,bkpt={number="1",addr="0x000100d0",file="hello.c",
106 
     fullname="/home/foo/hello.c",line="5",times="0"}
107 
     (gdb)
108 
     -break-after 1 3
109 
     ~
110 
     ^done
111 
     (gdb)
112 
     -break-list
113 
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
114 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
115 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
116 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
117 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
118 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
119 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
120 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
121 
     addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
122 
     line="5",times="0",ignore="3"}]}
123 
     (gdb)
124 
 
125 
The `-break-condition' Command
126 
------------------------------
127 
 
128 
Synopsis
129 
........
130 
 
131 
      -break-condition NUMBER EXPR
132 
 
133 
   Breakpoint NUMBER will stop the program only if the condition in
134 
EXPR is true.  The condition becomes part of the `-break-list' output
135 
(see the description of the `-break-list' command below).
136 
 
137 
GDB Command
138 
...........
139 
 
140 
The corresponding GDB command is `condition'.
141 
 
142 
Example
143 
.......
144 
 
145 
     (gdb)
146 
     -break-condition 1 1
147 
     ^done
148 
     (gdb)
149 
     -break-list
150 
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
151 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
152 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
153 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
154 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
155 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
156 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
157 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
158 
     addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
159 
     line="5",cond="1",times="0",ignore="3"}]}
160 
     (gdb)
161 
 
162 
The `-break-delete' Command
163 
---------------------------
164 
 
165 
Synopsis
166 
........
167 
 
168 
      -break-delete ( BREAKPOINT )+
169 
 
170 
   Delete the breakpoint(s) whose number(s) are specified in the
171 
argument list.  This is obviously reflected in the breakpoint list.
172 
 
173 
GDB Command
174 
...........
175 
 
176 
The corresponding GDB command is `delete'.
177 
 
178 
Example
179 
.......
180 
 
181 
     (gdb)
182 
     -break-delete 1
183 
     ^done
184 
     (gdb)
185 
     -break-list
186 
     ^done,BreakpointTable={nr_rows="0",nr_cols="6",
187 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
188 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
189 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
190 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
191 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
192 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
193 
     body=[]}
194 
     (gdb)
195 
 
196 
The `-break-disable' Command
197 
----------------------------
198 
 
199 
Synopsis
200 
........
201 
 
202 
      -break-disable ( BREAKPOINT )+
203 
 
204 
   Disable the named BREAKPOINT(s).  The field `enabled' in the break
205 
list is now set to `n' for the named BREAKPOINT(s).
206 
 
207 
GDB Command
208 
...........
209 
 
210 
The corresponding GDB command is `disable'.
211 
 
212 
Example
213 
.......
214 
 
215 
     (gdb)
216 
     -break-disable 2
217 
     ^done
218 
     (gdb)
219 
     -break-list
220 
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
221 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
222 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
223 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
224 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
225 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
226 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
227 
     body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
228 
     addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
229 
     line="5",times="0"}]}
230 
     (gdb)
231 
 
232 
The `-break-enable' Command
233 
---------------------------
234 
 
235 
Synopsis
236 
........
237 
 
238 
      -break-enable ( BREAKPOINT )+
239 
 
240 
   Enable (previously disabled) BREAKPOINT(s).
241 
 
242 
GDB Command
243 
...........
244 
 
245 
The corresponding GDB command is `enable'.
246 
 
247 
Example
248 
.......
249 
 
250 
     (gdb)
251 
     -break-enable 2
252 
     ^done
253 
     (gdb)
254 
     -break-list
255 
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
256 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
257 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
258 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
259 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
260 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
261 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
262 
     body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
263 
     addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
264 
     line="5",times="0"}]}
265 
     (gdb)
266 
 
267 
The `-break-info' Command
268 
-------------------------
269 
 
270 
Synopsis
271 
........
272 
 
273 
      -break-info BREAKPOINT
274 
 
275 
   Get information about a single breakpoint.
276 
 
277 
GDB Command
278 
...........
279 
 
280 
The corresponding GDB command is `info break BREAKPOINT'.
281 
 
282 
Example
283 
.......
284 
 
285 
N.A.
286 
 
287 
The `-break-insert' Command
288 
---------------------------
289 
 
290 
Synopsis
291 
........
292 
 
293 
      -break-insert [ -t ] [ -h ] [ -f ]
294 
         [ -c CONDITION ] [ -i IGNORE-COUNT ]
295 
         [ -p THREAD ] [ LOCATION ]
296 
 
297 
If specified, LOCATION, can be one of:
298 
 
299 
   * function
300 
 
301 
   * filename:linenum
302 
 
303 
   * filename:function
304 
 
305 
   * *address
306 
 
307 
   The possible optional parameters of this command are:
308 
 
309 
`-t'
310 
     Insert a temporary breakpoint.
311 
 
312 
`-h'
313 
     Insert a hardware breakpoint.
314 
 
315 
`-c CONDITION'
316 
     Make the breakpoint conditional on CONDITION.
317 
 
318 
`-i IGNORE-COUNT'
319 
     Initialize the IGNORE-COUNT.
320 
 
321 
`-f'
322 
     If LOCATION cannot be parsed (for example if it refers to unknown
323 
     files or functions), create a pending breakpoint. Without this
324 
     flag, GDB will report an error, and won't create a breakpoint, if
325 
     LOCATION cannot be parsed.
326 
 
327 
Result
328 
......
329 
 
330 
The result is in the form:
331 
 
332 
     ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep",
333 
     enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME",
334 
     fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,]
335 
     times="TIMES"}
336 
 
337 
where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
338 
name of the function where the breakpoint was inserted, FILENAME is the
339 
name of the source file which contains this function, LINENO is the
340 
source line number within that file and TIMES the number of times that
341 
the breakpoint has been hit (always 0 for -break-insert but may be
342 
greater for -break-info or -break-list which use the same output).
343 
 
344 
   Note: this format is open to change.
345 
 
346 
GDB Command
347 
...........
348 
 
349 
The corresponding GDB commands are `break', `tbreak', `hbreak',
350 
`thbreak', and `rbreak'.
351 
 
352 
Example
353 
.......
354 
 
355 
     (gdb)
356 
     -break-insert main
357 
     ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
358 
     fullname="/home/foo/recursive2.c,line="4",times="0"}
359 
     (gdb)
360 
     -break-insert -t foo
361 
     ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
362 
     fullname="/home/foo/recursive2.c,line="11",times="0"}
363 
     (gdb)
364 
     -break-list
365 
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
366 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
367 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
368 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
369 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
370 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
371 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
372 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
373 
     addr="0x0001072c", func="main",file="recursive2.c",
374 
     fullname="/home/foo/recursive2.c,"line="4",times="0"},
375 
     bkpt={number="2",type="breakpoint",disp="del",enabled="y",
376 
     addr="0x00010774",func="foo",file="recursive2.c",
377 
     fullname="/home/foo/recursive2.c",line="11",times="0"}]}
378 
     (gdb)
379 
     -break-insert -r foo.*
380 
     ~int foo(int, int);
381 
     ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c,
382 
     "fullname="/home/foo/recursive2.c",line="11",times="0"}
383 
     (gdb)
384 
 
385 
The `-break-list' Command
386 
-------------------------
387 
 
388 
Synopsis
389 
........
390 
 
391 
      -break-list
392 
 
393 
   Displays the list of inserted breakpoints, showing the following
394 
fields:
395 
 
396 
`Number'
397 
     number of the breakpoint
398 
 
399 
`Type'
400 
     type of the breakpoint: `breakpoint' or `watchpoint'
401 
 
402 
`Disposition'
403 
     should the breakpoint be deleted or disabled when it is hit: `keep'
404 
     or `nokeep'
405 
 
406 
`Enabled'
407 
     is the breakpoint enabled or no: `y' or `n'
408 
 
409 
`Address'
410 
     memory location at which the breakpoint is set
411 
 
412 
`What'
413 
     logical location of the breakpoint, expressed by function name,
414 
     file name, line number
415 
 
416 
`Times'
417 
     number of times the breakpoint has been hit
418 
 
419 
   If there are no breakpoints or watchpoints, the `BreakpointTable'
420 
`body' field is an empty list.
421 
 
422 
GDB Command
423 
...........
424 
 
425 
The corresponding GDB command is `info break'.
426 
 
427 
Example
428 
.......
429 
 
430 
     (gdb)
431 
     -break-list
432 
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
433 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
434 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
435 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
436 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
437 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
438 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
439 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
440 
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
441 
     bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
442 
     addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
443 
     line="13",times="0"}]}
444 
     (gdb)
445 
 
446 
   Here's an example of the result when there are no breakpoints:
447 
 
448 
     (gdb)
449 
     -break-list
450 
     ^done,BreakpointTable={nr_rows="0",nr_cols="6",
451 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
452 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
453 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
454 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
455 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
456 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
457 
     body=[]}
458 
     (gdb)
459 
 
460 
The `-break-watch' Command
461 
--------------------------
462 
 
463 
Synopsis
464 
........
465 
 
466 
      -break-watch [ -a | -r ]
467 
 
468 
   Create a watchpoint.  With the `-a' option it will create an
469 
"access" watchpoint, i.e., a watchpoint that triggers either on a read
470 
from or on a write to the memory location.  With the `-r' option, the
471 
watchpoint created is a "read" watchpoint, i.e., it will trigger only
472 
when the memory location is accessed for reading.  Without either of
473 
the options, the watchpoint created is a regular watchpoint, i.e., it
474 
will trigger when the memory location is accessed for writing.  *Note
475 
Setting Watchpoints: Set Watchpoints.
476 
 
477 
   Note that `-break-list' will report a single list of watchpoints and
478 
breakpoints inserted.
479 
 
480 
GDB Command
481 
...........
482 
 
483 
The corresponding GDB commands are `watch', `awatch', and `rwatch'.
484 
 
485 
Example
486 
.......
487 
 
488 
Setting a watchpoint on a variable in the `main' function:
489 
 
490 
     (gdb)
491 
     -break-watch x
492 
     ^done,wpt={number="2",exp="x"}
493 
     (gdb)
494 
     -exec-continue
495 
     ^running
496 
     (gdb)
497 
     *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
498 
     value={old="-268439212",new="55"},
499 
     frame={func="main",args=[],file="recursive2.c",
500 
     fullname="/home/foo/bar/recursive2.c",line="5"}
501 
     (gdb)
502 
 
503 
   Setting a watchpoint on a variable local to a function.  GDB will
504 
stop the program execution twice: first for the variable changing
505 
value, then for the watchpoint going out of scope.
506 
 
507 
     (gdb)
508 
     -break-watch C
509 
     ^done,wpt={number="5",exp="C"}
510 
     (gdb)
511 
     -exec-continue
512 
     ^running
513 
     (gdb)
514 
     *stopped,reason="watchpoint-trigger",
515 
     wpt={number="5",exp="C"},value={old="-276895068",new="3"},
516 
     frame={func="callee4",args=[],
517 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
518 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
519 
     (gdb)
520 
     -exec-continue
521 
     ^running
522 
     (gdb)
523 
     *stopped,reason="watchpoint-scope",wpnum="5",
524 
     frame={func="callee3",args=[{name="strarg",
525 
     value="0x11940 \"A string argument.\""}],
526 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
527 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
528 
     (gdb)
529 
 
530 
   Listing breakpoints and watchpoints, at different points in the
531 
program execution.  Note that once the watchpoint goes out of scope, it
532 
is deleted.
533 
 
534 
     (gdb)
535 
     -break-watch C
536 
     ^done,wpt={number="2",exp="C"}
537 
     (gdb)
538 
     -break-list
539 
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
540 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
541 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
542 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
543 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
544 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
545 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
546 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
547 
     addr="0x00010734",func="callee4",
548 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
549 
     fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"},
550 
     bkpt={number="2",type="watchpoint",disp="keep",
551 
     enabled="y",addr="",what="C",times="0"}]}
552 
     (gdb)
553 
     -exec-continue
554 
     ^running
555 
     (gdb)
556 
     *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
557 
     value={old="-276895068",new="3"},
558 
     frame={func="callee4",args=[],
559 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
560 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
561 
     (gdb)
562 
     -break-list
563 
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
564 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
565 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
566 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
567 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
568 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
569 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
570 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
571 
     addr="0x00010734",func="callee4",
572 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
573 
     fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
574 
     bkpt={number="2",type="watchpoint",disp="keep",
575 
     enabled="y",addr="",what="C",times="-5"}]}
576 
     (gdb)
577 
     -exec-continue
578 
     ^running
579 
     ^done,reason="watchpoint-scope",wpnum="2",
580 
     frame={func="callee3",args=[{name="strarg",
581 
     value="0x11940 \"A string argument.\""}],
582 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
583 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
584 
     (gdb)
585 
     -break-list
586 
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
587 
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
588 
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
589 
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
590 
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
591 
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
592 
     {width="40",alignment="2",col_name="what",colhdr="What"}],
593 
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
594 
     addr="0x00010734",func="callee4",
595 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
596 
     fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
597 
     times="1"}]}
598 
     (gdb)
599 
 
600 

601 
File: gdb.info,  Node: GDB/MI Program Context,  Next: GDB/MI Thread Commands,  Prev: GDB/MI Breakpoint Commands,  Up: GDB/MI
602 
 
603 
24.8 GDB/MI  Program Context
604 
============================
605 
 
606 
The `-exec-arguments' Command
607 
-----------------------------
608 
 
609 
Synopsis
610 
........
611 
 
612 
      -exec-arguments ARGS
613 
 
614 
   Set the inferior program arguments, to be used in the next
615 
`-exec-run'.
616 
 
617 
GDB Command
618 
...........
619 
 
620 
The corresponding GDB command is `set args'.
621 
 
622 
Example
623 
.......
624 
 
625 
Don't have one around.
626 
 
627 
The `-exec-show-arguments' Command
628 
----------------------------------
629 
 
630 
Synopsis
631 
........
632 
 
633 
      -exec-show-arguments
634 
 
635 
   Print the arguments of the program.
636 
 
637 
GDB Command
638 
...........
639 
 
640 
The corresponding GDB command is `show args'.
641 
 
642 
Example
643 
.......
644 
 
645 
N.A.
646 
 
647 
The `-environment-cd' Command
648 
-----------------------------
649 
 
650 
Synopsis
651 
........
652 
 
653 
      -environment-cd PATHDIR
654 
 
655 
   Set GDB's working directory.
656 
 
657 
GDB Command
658 
...........
659 
 
660 
The corresponding GDB command is `cd'.
661 
 
662 
Example
663 
.......
664 
 
665 
     (gdb)
666 
     -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
667 
     ^done
668 
     (gdb)
669 
 
670 
The `-environment-directory' Command
671 
------------------------------------
672 
 
673 
Synopsis
674 
........
675 
 
676 
      -environment-directory [ -r ] [ PATHDIR ]+
677 
 
678 
   Add directories PATHDIR to beginning of search path for source files.
679 
If the `-r' option is used, the search path is reset to the default
680 
search path.  If directories PATHDIR are supplied in addition to the
681 
`-r' option, the search path is first reset and then addition occurs as
682 
normal.  Multiple directories may be specified, separated by blanks.
683 
Specifying multiple directories in a single command results in the
684 
directories added to the beginning of the search path in the same order
685 
they were presented in the command.  If blanks are needed as part of a
686 
directory name, double-quotes should be used around the name.  In the
687 
command output, the path will show up separated by the system
688 
directory-separator character.  The directory-separator character must
689 
not be used in any directory name.  If no directories are specified,
690 
the current search path is displayed.
691 
 
692 
GDB Command
693 
...........
694 
 
695 
The corresponding GDB command is `dir'.
696 
 
697 
Example
698 
.......
699 
 
700 
     (gdb)
701 
     -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
702 
     ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
703 
     (gdb)
704 
     -environment-directory ""
705 
     ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
706 
     (gdb)
707 
     -environment-directory -r /home/jjohnstn/src/gdb /usr/src
708 
     ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
709 
     (gdb)
710 
     -environment-directory -r
711 
     ^done,source-path="$cdir:$cwd"
712 
     (gdb)
713 
 
714 
The `-environment-path' Command
715 
-------------------------------
716 
 
717 
Synopsis
718 
........
719 
 
720 
      -environment-path [ -r ] [ PATHDIR ]+
721 
 
722 
   Add directories PATHDIR to beginning of search path for object files.
723 
If the `-r' option is used, the search path is reset to the original
724 
search path that existed at gdb start-up.  If directories PATHDIR are
725 
supplied in addition to the `-r' option, the search path is first reset
726 
and then addition occurs as normal.  Multiple directories may be
727 
specified, separated by blanks.  Specifying multiple directories in a
728 
single command results in the directories added to the beginning of the
729 
search path in the same order they were presented in the command.  If
730 
blanks are needed as part of a directory name, double-quotes should be
731 
used around the name.  In the command output, the path will show up
732 
separated by the system directory-separator character.  The
733 
directory-separator character must not be used in any directory name.
734 
If no directories are specified, the current path is displayed.
735 
 
736 
GDB Command
737 
...........
738 
 
739 
The corresponding GDB command is `path'.
740 
 
741 
Example
742 
.......
743 
 
744 
     (gdb)
745 
     -environment-path
746 
     ^done,path="/usr/bin"
747 
     (gdb)
748 
     -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
749 
     ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
750 
     (gdb)
751 
     -environment-path -r /usr/local/bin
752 
     ^done,path="/usr/local/bin:/usr/bin"
753 
     (gdb)
754 
 
755 
The `-environment-pwd' Command
756 
------------------------------
757 
 
758 
Synopsis
759 
........
760 
 
761 
      -environment-pwd
762 
 
763 
   Show the current working directory.
764 
 
765 
GDB Command
766 
...........
767 
 
768 
The corresponding GDB command is `pwd'.
769 
 
770 
Example
771 
.......
772 
 
773 
     (gdb)
774 
     -environment-pwd
775 
     ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
776 
     (gdb)
777 
 
778 

779 
File: gdb.info,  Node: GDB/MI Thread Commands,  Next: GDB/MI Program Execution,  Prev: GDB/MI Program Context,  Up: GDB/MI
780 
 
781 
24.9 GDB/MI Thread Commands
782 
===========================
783 
 
784 
The `-thread-info' Command
785 
--------------------------
786 
 
787 
Synopsis
788 
........
789 
 
790 
      -thread-info
791 
 
792 
GDB Command
793 
...........
794 
 
795 
No equivalent.
796 
 
797 
Example
798 
.......
799 
 
800 
N.A.
801 
 
802 
The `-thread-list-all-threads' Command
803 
--------------------------------------
804 
 
805 
Synopsis
806 
........
807 
 
808 
      -thread-list-all-threads
809 
 
810 
GDB Command
811 
...........
812 
 
813 
The equivalent GDB command is `info threads'.
814 
 
815 
Example
816 
.......
817 
 
818 
N.A.
819 
 
820 
The `-thread-list-ids' Command
821 
------------------------------
822 
 
823 
Synopsis
824 
........
825 
 
826 
      -thread-list-ids
827 
 
828 
   Produces a list of the currently known GDB thread ids.  At the end
829 
of the list it also prints the total number of such threads.
830 
 
831 
GDB Command
832 
...........
833 
 
834 
Part of `info threads' supplies the same information.
835 
 
836 
Example
837 
.......
838 
 
839 
No threads present, besides the main process:
840 
 
841 
     (gdb)
842 
     -thread-list-ids
843 
     ^done,thread-ids={},number-of-threads="0"
844 
     (gdb)
845 
 
846 
   Several threads:
847 
 
848 
     (gdb)
849 
     -thread-list-ids
850 
     ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
851 
     number-of-threads="3"
852 
     (gdb)
853 
 
854 
The `-thread-select' Command
855 
----------------------------
856 
 
857 
Synopsis
858 
........
859 
 
860 
      -thread-select THREADNUM
861 
 
862 
   Make THREADNUM the current thread.  It prints the number of the new
863 
current thread, and the topmost frame for that thread.
864 
 
865 
GDB Command
866 
...........
867 
 
868 
The corresponding GDB command is `thread'.
869 
 
870 
Example
871 
.......
872 
 
873 
     (gdb)
874 
     -exec-next
875 
     ^running
876 
     (gdb)
877 
     *stopped,reason="end-stepping-range",thread-id="2",line="187",
878 
     file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
879 
     (gdb)
880 
     -thread-list-ids
881 
     ^done,
882 
     thread-ids={thread-id="3",thread-id="2",thread-id="1"},
883 
     number-of-threads="3"
884 
     (gdb)
885 
     -thread-select 3
886 
     ^done,new-thread-id="3",
887 
     frame={level="0",func="vprintf",
888 
     args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
889 
     {name="arg",value="0x2"}],file="vprintf.c",line="31"}
890 
     (gdb)
891 
 
892 

893 
File: gdb.info,  Node: GDB/MI Program Execution,  Next: GDB/MI Stack Manipulation,  Prev: GDB/MI Thread Commands,  Up: GDB/MI
894 
 
895 
24.10 GDB/MI Program Execution
896 
==============================
897 
 
898 
These are the asynchronous commands which generate the out-of-band
899 
record `*stopped'.  Currently GDB only really executes asynchronously
900 
with remote targets and this interaction is mimicked in other cases.
901 
 
902 
The `-exec-continue' Command
903 
----------------------------
904 
 
905 
Synopsis
906 
........
907 
 
908 
      -exec-continue
909 
 
910 
   Resumes the execution of the inferior program until a breakpoint is
911 
encountered, or until the inferior exits.
912 
 
913 
GDB Command
914 
...........
915 
 
916 
The corresponding GDB corresponding is `continue'.
917 
 
918 
Example
919 
.......
920 
 
921 
     -exec-continue
922 
     ^running
923 
     (gdb)
924 
     @Hello world
925 
     *stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[],
926 
     file="hello.c",fullname="/home/foo/bar/hello.c",line="13"}
927 
     (gdb)
928 
 
929 
The `-exec-finish' Command
930 
--------------------------
931 
 
932 
Synopsis
933 
........
934 
 
935 
      -exec-finish
936 
 
937 
   Resumes the execution of the inferior program until the current
938 
function is exited.  Displays the results returned by the function.
939 
 
940 
GDB Command
941 
...........
942 
 
943 
The corresponding GDB command is `finish'.
944 
 
945 
Example
946 
.......
947 
 
948 
Function returning `void'.
949 
 
950 
     -exec-finish
951 
     ^running
952 
     (gdb)
953 
     @hello from foo
954 
     *stopped,reason="function-finished",frame={func="main",args=[],
955 
     file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
956 
     (gdb)
957 
 
958 
   Function returning other than `void'.  The name of the internal GDB
959 
variable storing the result is printed, together with the value itself.
960 
 
961 
     -exec-finish
962 
     ^running
963 
     (gdb)
964 
     *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
965 
     args=[{name="a",value="1"],{name="b",value="9"}},
966 
     file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
967 
     gdb-result-var="$1",return-value="0"
968 
     (gdb)
969 
 
970 
The `-exec-interrupt' Command
971 
-----------------------------
972 
 
973 
Synopsis
974 
........
975 
 
976 
      -exec-interrupt
977 
 
978 
   Interrupts the background execution of the target.  Note how the
979 
token associated with the stop message is the one for the execution
980 
command that has been interrupted.  The token for the interrupt itself
981 
only appears in the `^done' output.  If the user is trying to interrupt
982 
a non-running program, an error message will be printed.
983 
 
984 
GDB Command
985 
...........
986 
 
987 
The corresponding GDB command is `interrupt'.
988 
 
989 
Example
990 
.......
991 
 
992 
     (gdb)
993 
     111-exec-continue
994 
     111^running
995 
 
996 
     (gdb)
997 
     222-exec-interrupt
998 
     222^done
999 
     (gdb)
1000 
     111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1001 
     frame={addr="0x00010140",func="foo",args=[],file="try.c",
1002 
     fullname="/home/foo/bar/try.c",line="13"}
1003 
     (gdb)
1004 
 
1005 
     (gdb)
1006 
     -exec-interrupt
1007 
     ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1008 
     (gdb)
1009 
 
1010 
The `-exec-next' Command
1011 
------------------------
1012 
 
1013 
Synopsis
1014 
........
1015 
 
1016 
      -exec-next
1017 
 
1018 
   Resumes execution of the inferior program, stopping when the
1019 
beginning of the next source line is reached.
1020 
 
1021 
GDB Command
1022 
...........
1023 
 
1024 
The corresponding GDB command is `next'.
1025 
 
1026 
Example
1027 
.......
1028 
 
1029 
     -exec-next
1030 
     ^running
1031 
     (gdb)
1032 
     *stopped,reason="end-stepping-range",line="8",file="hello.c"
1033 
     (gdb)
1034 
 
1035 
The `-exec-next-instruction' Command
1036 
------------------------------------
1037 
 
1038 
Synopsis
1039 
........
1040 
 
1041 
      -exec-next-instruction
1042 
 
1043 
   Executes one machine instruction.  If the instruction is a function
1044 
call, continues until the function returns.  If the program stops at an
1045 
instruction in the middle of a source line, the address will be printed
1046 
as well.
1047 
 
1048 
GDB Command
1049 
...........
1050 
 
1051 
The corresponding GDB command is `nexti'.
1052 
 
1053 
Example
1054 
.......
1055 
 
1056 
     (gdb)
1057 
     -exec-next-instruction
1058 
     ^running
1059 
 
1060 
     (gdb)
1061 
     *stopped,reason="end-stepping-range",
1062 
     addr="0x000100d4",line="5",file="hello.c"
1063 
     (gdb)
1064 
 
1065 
The `-exec-return' Command
1066 
--------------------------
1067 
 
1068 
Synopsis
1069 
........
1070 
 
1071 
      -exec-return
1072 
 
1073 
   Makes current function return immediately.  Doesn't execute the
1074 
inferior.  Displays the new current frame.
1075 
 
1076 
GDB Command
1077 
...........
1078 
 
1079 
The corresponding GDB command is `return'.
1080 
 
1081 
Example
1082 
.......
1083 
 
1084 
     (gdb)
1085 
     200-break-insert callee4
1086 
     200^done,bkpt={number="1",addr="0x00010734",
1087 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
1088 
     (gdb)
1089 
     000-exec-run
1090 
     000^running
1091 
     (gdb)
1092 
     000*stopped,reason="breakpoint-hit",bkptno="1",
1093 
     frame={func="callee4",args=[],
1094 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1095 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
1096 
     (gdb)
1097 
     205-break-delete
1098 
     205^done
1099 
     (gdb)
1100 
     111-exec-return
1101 
     111^done,frame={level="0",func="callee3",
1102 
     args=[{name="strarg",
1103 
     value="0x11940 \"A string argument.\""}],
1104 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1105 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
1106 
     (gdb)
1107 
 
1108 
The `-exec-run' Command
1109 
-----------------------
1110 
 
1111 
Synopsis
1112 
........
1113 
 
1114 
      -exec-run
1115 
 
1116 
   Starts execution of the inferior from the beginning.  The inferior
1117 
executes until either a breakpoint is encountered or the program exits.
1118 
In the latter case the output will include an exit code, if the
1119 
program has exited exceptionally.
1120 
 
1121 
GDB Command
1122 
...........
1123 
 
1124 
The corresponding GDB command is `run'.
1125 
 
1126 
Examples
1127 
........
1128 
 
1129 
     (gdb)
1130 
     -break-insert main
1131 
     ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
1132 
     (gdb)
1133 
     -exec-run
1134 
     ^running
1135 
     (gdb)
1136 
     *stopped,reason="breakpoint-hit",bkptno="1",
1137 
     frame={func="main",args=[],file="recursive2.c",
1138 
     fullname="/home/foo/bar/recursive2.c",line="4"}
1139 
     (gdb)
1140 
 
1141 
Program exited normally:
1142 
 
1143 
     (gdb)
1144 
     -exec-run
1145 
     ^running
1146 
     (gdb)
1147 
     x = 55
1148 
     *stopped,reason="exited-normally"
1149 
     (gdb)
1150 
 
1151 
Program exited exceptionally:
1152 
 
1153 
     (gdb)
1154 
     -exec-run
1155 
     ^running
1156 
     (gdb)
1157 
     x = 55
1158 
     *stopped,reason="exited",exit-code="01"
1159 
     (gdb)
1160 
 
1161 
   Another way the program can terminate is if it receives a signal
1162 
such as `SIGINT'.  In this case, GDB/MI displays this:
1163 
 
1164 
     (gdb)
1165 
     *stopped,reason="exited-signalled",signal-name="SIGINT",
1166 
     signal-meaning="Interrupt"
1167 
 
1168 
The `-exec-step' Command
1169 
------------------------
1170 
 
1171 
Synopsis
1172 
........
1173 
 
1174 
      -exec-step
1175 
 
1176 
   Resumes execution of the inferior program, stopping when the
1177 
beginning of the next source line is reached, if the next source line
1178 
is not a function call.  If it is, stop at the first instruction of the
1179 
called function.
1180 
 
1181 
GDB Command
1182 
...........
1183 
 
1184 
The corresponding GDB command is `step'.
1185 
 
1186 
Example
1187 
.......
1188 
 
1189 
Stepping into a function:
1190 
 
1191 
     -exec-step
1192 
     ^running
1193 
     (gdb)
1194 
     *stopped,reason="end-stepping-range",
1195 
     frame={func="foo",args=[{name="a",value="10"},
1196 
     {name="b",value="0"}],file="recursive2.c",
1197 
     fullname="/home/foo/bar/recursive2.c",line="11"}
1198 
     (gdb)
1199 
 
1200 
   Regular stepping:
1201 
 
1202 
     -exec-step
1203 
     ^running
1204 
     (gdb)
1205 
     *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
1206 
     (gdb)
1207 
 
1208 
The `-exec-step-instruction' Command
1209 
------------------------------------
1210 
 
1211 
Synopsis
1212 
........
1213 
 
1214 
      -exec-step-instruction
1215 
 
1216 
   Resumes the inferior which executes one machine instruction.  The
1217 
output, once GDB has stopped, will vary depending on whether we have
1218 
stopped in the middle of a source line or not.  In the former case, the
1219 
address at which the program stopped will be printed as well.
1220 
 
1221 
GDB Command
1222 
...........
1223 
 
1224 
The corresponding GDB command is `stepi'.
1225 
 
1226 
Example
1227 
.......
1228 
 
1229 
     (gdb)
1230 
     -exec-step-instruction
1231 
     ^running
1232 
 
1233 
     (gdb)
1234 
     *stopped,reason="end-stepping-range",
1235 
     frame={func="foo",args=[],file="try.c",
1236 
     fullname="/home/foo/bar/try.c",line="10"}
1237 
     (gdb)
1238 
     -exec-step-instruction
1239 
     ^running
1240 
 
1241 
     (gdb)
1242 
     *stopped,reason="end-stepping-range",
1243 
     frame={addr="0x000100f4",func="foo",args=[],file="try.c",
1244 
     fullname="/home/foo/bar/try.c",line="10"}
1245 
     (gdb)
1246 
 
1247 
The `-exec-until' Command
1248 
-------------------------
1249 
 
1250 
Synopsis
1251 
........
1252 
 
1253 
      -exec-until [ LOCATION ]
1254 
 
1255 
   Executes the inferior until the LOCATION specified in the argument
1256 
is reached.  If there is no argument, the inferior executes until a
1257 
source line greater than the current one is reached.  The reason for
1258 
stopping in this case will be `location-reached'.
1259 
 
1260 
GDB Command
1261 
...........
1262 
 
1263 
The corresponding GDB command is `until'.
1264 
 
1265 
Example
1266 
.......
1267 
 
1268 
     (gdb)
1269 
     -exec-until recursive2.c:6
1270 
     ^running
1271 
     (gdb)
1272 
     x = 55
1273 
     *stopped,reason="location-reached",frame={func="main",args=[],
1274 
     file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
1275 
     (gdb)
1276 
 
1277 

1278 
File: gdb.info,  Node: GDB/MI Stack Manipulation,  Next: GDB/MI Variable Objects,  Prev: GDB/MI Program Execution,  Up: GDB/MI
1279 
 
1280 
24.11 GDB/MI Stack Manipulation Commands
1281 
========================================
1282 
 
1283 
The `-stack-info-frame' Command
1284 
-------------------------------
1285 
 
1286 
Synopsis
1287 
........
1288 
 
1289 
      -stack-info-frame
1290 
 
1291 
   Get info on the selected frame.
1292 
 
1293 
GDB Command
1294 
...........
1295 
 
1296 
The corresponding GDB command is `info frame' or `frame' (without
1297 
arguments).
1298 
 
1299 
Example
1300 
.......
1301 
 
1302 
     (gdb)
1303 
     -stack-info-frame
1304 
     ^done,frame={level="1",addr="0x0001076c",func="callee3",
1305 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1306 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
1307 
     (gdb)
1308 
 
1309 
The `-stack-info-depth' Command
1310 
-------------------------------
1311 
 
1312 
Synopsis
1313 
........
1314 
 
1315 
      -stack-info-depth [ MAX-DEPTH ]
1316 
 
1317 
   Return the depth of the stack.  If the integer argument MAX-DEPTH is
1318 
specified, do not count beyond MAX-DEPTH frames.
1319 
 
1320 
GDB Command
1321 
...........
1322 
 
1323 
There's no equivalent GDB command.
1324 
 
1325 
Example
1326 
.......
1327 
 
1328 
For a stack with frame levels 0 through 11:
1329 
 
1330 
     (gdb)
1331 
     -stack-info-depth
1332 
     ^done,depth="12"
1333 
     (gdb)
1334 
     -stack-info-depth 4
1335 
     ^done,depth="4"
1336 
     (gdb)
1337 
     -stack-info-depth 12
1338 
     ^done,depth="12"
1339 
     (gdb)
1340 
     -stack-info-depth 11
1341 
     ^done,depth="11"
1342 
     (gdb)
1343 
     -stack-info-depth 13
1344 
     ^done,depth="12"
1345 
     (gdb)
1346 
 
1347 
The `-stack-list-arguments' Command
1348 
-----------------------------------
1349 
 
1350 
Synopsis
1351 
........
1352 
 
1353 
      -stack-list-arguments SHOW-VALUES
1354 
         [ LOW-FRAME HIGH-FRAME ]
1355 
 
1356 
   Display a list of the arguments for the frames between LOW-FRAME and
1357 
HIGH-FRAME (inclusive).  If LOW-FRAME and HIGH-FRAME are not provided,
1358 
list the arguments for the whole call stack.  If the two arguments are
1359 
equal, show the single frame at the corresponding level.  It is an
1360 
error if LOW-FRAME is larger than the actual number of frames.  On the
1361 
other hand, HIGH-FRAME may be larger than the actual number of frames,
1362 
in which case only existing frames will be returned.
1363 
 
1364 
   The SHOW-VALUES argument must have a value of 0 or 1.  A value of 0
1365 
means that only the names of the arguments are listed, a value of 1
1366 
means that both names and values of the arguments are printed.
1367 
 
1368 
GDB Command
1369 
...........
1370 
 
1371 
GDB does not have an equivalent command.  `gdbtk' has a `gdb_get_args'
1372 
command which partially overlaps with the functionality of
1373 
`-stack-list-arguments'.
1374 
 
1375 
Example
1376 
.......
1377 
 
1378 
     (gdb)
1379 
     -stack-list-frames
1380 
     ^done,
1381 
     stack=[
1382 
     frame={level="0",addr="0x00010734",func="callee4",
1383 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1384 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
1385 
     frame={level="1",addr="0x0001076c",func="callee3",
1386 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1387 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
1388 
     frame={level="2",addr="0x0001078c",func="callee2",
1389 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1390 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
1391 
     frame={level="3",addr="0x000107b4",func="callee1",
1392 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1393 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
1394 
     frame={level="4",addr="0x000107e0",func="main",
1395 
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
1396 
     fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
1397 
     (gdb)
1398 
     -stack-list-arguments 0
1399 
     ^done,
1400 
     stack-args=[
1401 
     frame={level="0",args=[]},
1402 
     frame={level="1",args=[name="strarg"]},
1403 
     frame={level="2",args=[name="intarg",name="strarg"]},
1404 
     frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
1405 
     frame={level="4",args=[]}]
1406 
     (gdb)
1407 
     -stack-list-arguments 1
1408 
     ^done,
1409 
     stack-args=[
1410 
     frame={level="0",args=[]},
1411 
     frame={level="1",
1412 
      args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
1413 
     frame={level="2",args=[
1414 
     {name="intarg",value="2"},
1415 
     {name="strarg",value="0x11940 \"A string argument.\""}]},
1416 
     {frame={level="3",args=[
1417 
     {name="intarg",value="2"},
1418 
     {name="strarg",value="0x11940 \"A string argument.\""},
1419 
     {name="fltarg",value="3.5"}]},
1420 
     frame={level="4",args=[]}]
1421 
     (gdb)
1422 
     -stack-list-arguments 0 2 2
1423 
     ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
1424 
     (gdb)
1425 
     -stack-list-arguments 1 2 2
1426 
     ^done,stack-args=[frame={level="2",
1427 
     args=[{name="intarg",value="2"},
1428 
     {name="strarg",value="0x11940 \"A string argument.\""}]}]
1429 
     (gdb)
1430 
 
1431 
The `-stack-list-frames' Command
1432 
--------------------------------
1433 
 
1434 
Synopsis
1435 
........
1436 
 
1437 
      -stack-list-frames [ LOW-FRAME HIGH-FRAME ]
1438 
 
1439 
   List the frames currently on the stack.  For each frame it displays
1440 
the following info:
1441 
 
1442 
`LEVEL'
1443 
     The frame number, 0 being the topmost frame, i.e., the innermost
1444 
     function.
1445 
 
1446 
`ADDR'
1447 
     The `$pc' value for that frame.
1448 
 
1449 
`FUNC'
1450 
     Function name.
1451 
 
1452 
`FILE'
1453 
     File name of the source file where the function lives.
1454 
 
1455 
`LINE'
1456 
     Line number corresponding to the `$pc'.
1457 
 
1458 
   If invoked without arguments, this command prints a backtrace for the
1459 
whole stack.  If given two integer arguments, it shows the frames whose
1460 
levels are between the two arguments (inclusive).  If the two arguments
1461 
are equal, it shows the single frame at the corresponding level.  It is
1462 
an error if LOW-FRAME is larger than the actual number of frames.  On
1463 
the other hand, HIGH-FRAME may be larger than the actual number of
1464 
frames, in which case only existing frames will be returned.
1465 
 
1466 
GDB Command
1467 
...........
1468 
 
1469 
The corresponding GDB commands are `backtrace' and `where'.
1470 
 
1471 
Example
1472 
.......
1473 
 
1474 
Full stack backtrace:
1475 
 
1476 
     (gdb)
1477 
     -stack-list-frames
1478 
     ^done,stack=
1479 
     [frame={level="0",addr="0x0001076c",func="foo",
1480 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
1481 
     frame={level="1",addr="0x000107a4",func="foo",
1482 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1483 
     frame={level="2",addr="0x000107a4",func="foo",
1484 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1485 
     frame={level="3",addr="0x000107a4",func="foo",
1486 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1487 
     frame={level="4",addr="0x000107a4",func="foo",
1488 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1489 
     frame={level="5",addr="0x000107a4",func="foo",
1490 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1491 
     frame={level="6",addr="0x000107a4",func="foo",
1492 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1493 
     frame={level="7",addr="0x000107a4",func="foo",
1494 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1495 
     frame={level="8",addr="0x000107a4",func="foo",
1496 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1497 
     frame={level="9",addr="0x000107a4",func="foo",
1498 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1499 
     frame={level="10",addr="0x000107a4",func="foo",
1500 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1501 
     frame={level="11",addr="0x00010738",func="main",
1502 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
1503 
     (gdb)
1504 
 
1505 
   Show frames between LOW_FRAME and HIGH_FRAME:
1506 
 
1507 
     (gdb)
1508 
     -stack-list-frames 3 5
1509 
     ^done,stack=
1510 
     [frame={level="3",addr="0x000107a4",func="foo",
1511 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1512 
     frame={level="4",addr="0x000107a4",func="foo",
1513 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
1514 
     frame={level="5",addr="0x000107a4",func="foo",
1515 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
1516 
     (gdb)
1517 
 
1518 
   Show a single frame:
1519 
 
1520 
     (gdb)
1521 
     -stack-list-frames 3 3
1522 
     ^done,stack=
1523 
     [frame={level="3",addr="0x000107a4",func="foo",
1524 
       file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
1525 
     (gdb)
1526 
 
1527 
The `-stack-list-locals' Command
1528 
--------------------------------
1529 
 
1530 
Synopsis
1531 
........
1532 
 
1533 
      -stack-list-locals PRINT-VALUES
1534 
 
1535 
   Display the local variable names for the selected frame.  If
1536 
PRINT-VALUES is 0 or `--no-values', print only the names of the
1537 
variables; if it is 1 or `--all-values', print also their values; and
1538 
if it is 2 or `--simple-values', print the name, type and value for
1539 
simple data types and the name and type for arrays, structures and
1540 
unions.  In this last case, a frontend can immediately display the
1541 
value of simple data types and create variable objects for other data
1542 
types when the user wishes to explore their values in more detail.
1543 
 
1544 
GDB Command
1545 
...........
1546 
 
1547 
`info locals' in GDB, `gdb_get_locals' in `gdbtk'.
1548 
 
1549 
Example
1550 
.......
1551 
 
1552 
     (gdb)
1553 
     -stack-list-locals 0
1554 
     ^done,locals=[name="A",name="B",name="C"]
1555 
     (gdb)
1556 
     -stack-list-locals --all-values
1557 
     ^done,locals=[{name="A",value="1"},{name="B",value="2"},
1558 
       {name="C",value="{1, 2, 3}"}]
1559 
     -stack-list-locals --simple-values
1560 
     ^done,locals=[{name="A",type="int",value="1"},
1561 
       {name="B",type="int",value="2"},{name="C",type="int [3]"}]
1562 
     (gdb)
1563 
 
1564 
The `-stack-select-frame' Command
1565 
---------------------------------
1566 
 
1567 
Synopsis
1568 
........
1569 
 
1570 
      -stack-select-frame FRAMENUM
1571 
 
1572 
   Change the selected frame.  Select a different frame FRAMENUM on the
1573 
stack.
1574 
 
1575 
GDB Command
1576 
...........
1577 
 
1578 
The corresponding GDB commands are `frame', `up', `down',
1579 
`select-frame', `up-silent', and `down-silent'.
1580 
 
1581 
Example
1582 
.......
1583 
 
1584 
     (gdb)
1585 
     -stack-select-frame 2
1586 
     ^done
1587 
     (gdb)
1588 
 
1589 

1590 
File: gdb.info,  Node: GDB/MI Variable Objects,  Next: GDB/MI Data Manipulation,  Prev: GDB/MI Stack Manipulation,  Up: GDB/MI
1591 
 
1592 
24.12 GDB/MI Variable Objects
1593 
=============================
1594 
 
1595 
Introduction to Variable Objects
1596 
--------------------------------
1597 
 
1598 
Variable objects are "object-oriented" MI interface for examining and
1599 
changing values of expressions.  Unlike some other MI interfaces that
1600 
work with expressions, variable objects are specifically designed for
1601 
simple and efficient presentation in the frontend.  A variable object
1602 
is identified by string name.  When a variable object is created, the
1603 
frontend specifies the expression for that variable object.  The
1604 
expression can be a simple variable, or it can be an arbitrary complex
1605 
expression, and can even involve CPU registers.  After creating a
1606 
variable object, the frontend can invoke other variable object
1607 
operations--for example to obtain or change the value of a variable
1608 
object, or to change display format.
1609 
 
1610 
   Variable objects have hierarchical tree structure.  Any variable
1611 
object that corresponds to a composite type, such as structure in C, has
1612 
a number of child variable objects, for example corresponding to each
1613 
element of a structure.  A child variable object can itself have
1614 
children, recursively.  Recursion ends when we reach leaf variable
1615 
objects, which always have built-in types.  Child variable objects are
1616 
created only by explicit request, so if a frontend is not interested in
1617 
the children of a particular variable object, no child will be created.
1618 
 
1619 
   For a leaf variable object it is possible to obtain its value as a
1620 
string, or set the value from a string.  String value can be also
1621 
obtained for a non-leaf variable object, but it's generally a string
1622 
that only indicates the type of the object, and does not list its
1623 
contents.  Assignment to a non-leaf variable object is not allowed.
1624 
 
1625 
   A frontend does not need to read the values of all variable objects
1626 
each time the program stops.  Instead, MI provides an update command
1627 
that lists all variable objects whose values has changed since the last
1628 
update operation.  This considerably reduces the amount of data that
1629 
must be transferred to the frontend.  As noted above, children variable
1630 
objects are created on demand, and only leaf variable objects have a
1631 
real value.  As result, gdb will read target memory only for leaf
1632 
variables that frontend has created.
1633 
 
1634 
   The automatic update is not always desirable.  For example, a
1635 
frontend might want to keep a value of some expression for future
1636 
reference, and never update it.  For another example,  fetching memory
1637 
is relatively slow for embedded targets, so a frontend might want to
1638 
disable automatic update for the variables that are either not visible
1639 
on the screen, or "closed".  This is possible using so called "frozen
1640 
variable objects".  Such variable objects are never implicitly updated.
1641 
 
1642 
   The following is the complete set of GDB/MI operations defined to
1643 
access this functionality:
1644 
 
1645 
*Operation*                   *Description*
1646 
`-var-create'                 create a variable object
1647 
`-var-delete'                 delete the variable object and/or its
1648 
                              children
1649 
`-var-set-format'             set the display format of this variable
1650 
`-var-show-format'            show the display format of this variable
1651 
`-var-info-num-children'      tells how many children this object has
1652 
`-var-list-children'          return a list of the object's children
1653 
`-var-info-type'              show the type of this variable object
1654 
`-var-info-expression'        print parent-relative expression that this
1655 
                              variable object represents
1656 
`-var-info-path-expression'   print full expression that this variable
1657 
                              object represents
1658 
`-var-show-attributes'        is this variable editable? does it exist
1659 
                              here?
1660 
`-var-evaluate-expression'    get the value of this variable
1661 
`-var-assign'                 set the value of this variable
1662 
`-var-update'                 update the variable and its children
1663 
`-var-set-frozen'             set frozeness attribute
1664 
 
1665 
   In the next subsection we describe each operation in detail and
1666 
suggest how it can be used.
1667 
 
1668 
Description And Use of Operations on Variable Objects
1669 
-----------------------------------------------------
1670 
 
1671 
The `-var-create' Command
1672 
-------------------------
1673 
 
1674 
Synopsis
1675 
........
1676 
 
1677 
      -var-create {NAME | "-"}
1678 
         {FRAME-ADDR | "*"} EXPRESSION
1679 
 
1680 
   This operation creates a variable object, which allows the
1681 
monitoring of a variable, the result of an expression, a memory cell or
1682 
a CPU register.
1683 
 
1684 
   The NAME parameter is the string by which the object can be
1685 
referenced.  It must be unique.  If `-' is specified, the varobj system
1686 
will generate a string "varNNNNNN" automatically.  It will be unique
1687 
provided that one does not specify NAME on that format.  The command
1688 
fails if a duplicate name is found.
1689 
 
1690 
   The frame under which the expression should be evaluated can be
1691 
specified by FRAME-ADDR.  A `*' indicates that the current frame should
1692 
be used.
1693 
 
1694 
   EXPRESSION is any expression valid on the current language set (must
1695 
not begin with a `*'), or one of the following:
1696 
 
1697 
   * `*ADDR', where ADDR is the address of a memory cell
1698 
 
1699 
   * `*ADDR-ADDR' -- a memory address range (TBD)
1700 
 
1701 
   * `$REGNAME' -- a CPU register name
1702 
 
1703 
Result
1704 
......
1705 
 
1706 
This operation returns the name, number of children and the type of the
1707 
object created.  Type is returned as a string as the ones generated by
1708 
the GDB CLI:
1709 
 
1710 
      name="NAME",numchild="N",type="TYPE"
1711 
 
1712 
The `-var-delete' Command
1713 
-------------------------
1714 
 
1715 
Synopsis
1716 
........
1717 
 
1718 
      -var-delete [ -c ] NAME
1719 
 
1720 
   Deletes a previously created variable object and all of its children.
1721 
With the `-c' option, just deletes the children.
1722 
 
1723 
   Returns an error if the object NAME is not found.
1724 
 
1725 
The `-var-set-format' Command
1726 
-----------------------------
1727 
 
1728 
Synopsis
1729 
........
1730 
 
1731 
      -var-set-format NAME FORMAT-SPEC
1732 
 
1733 
   Sets the output format for the value of the object NAME to be
1734 
FORMAT-SPEC.
1735 
 
1736 
   The syntax for the FORMAT-SPEC is as follows:
1737 
 
1738 
      FORMAT-SPEC ==>
1739 
      {binary | decimal | hexadecimal | octal | natural}
1740 
 
1741 
   The natural format is the default format choosen automatically based
1742 
on the variable type (like decimal for an `int', hex for pointers,
1743 
etc.).
1744 
 
1745 
   For a variable with children, the format is set only on the variable
1746 
itself, and the children are not affected.
1747 
 
1748 
The `-var-show-format' Command
1749 
------------------------------
1750 
 
1751 
Synopsis
1752 
........
1753 
 
1754 
      -var-show-format NAME
1755 
 
1756 
   Returns the format used to display the value of the object NAME.
1757 
 
1758 
      FORMAT ==>
1759 
      FORMAT-SPEC
1760 
 
1761 
The `-var-info-num-children' Command
1762 
------------------------------------
1763 
 
1764 
Synopsis
1765 
........
1766 
 
1767 
      -var-info-num-children NAME
1768 
 
1769 
   Returns the number of children of a variable object NAME:
1770 
 
1771 
      numchild=N
1772 
 
1773 
The `-var-list-children' Command
1774 
--------------------------------
1775 
 
1776 
Synopsis
1777 
........
1778 
 
1779 
      -var-list-children [PRINT-VALUES] NAME
1780 
 
1781 
   Return a list of the children of the specified variable object and
1782 
create variable objects for them, if they do not already exist.  With a
1783 
single argument or if PRINT-VALUES has a value for of 0 or
1784 
`--no-values', print only the names of the variables; if PRINT-VALUES
1785 
is 1 or `--all-values', also print their values; and if it is 2 or
1786 
`--simple-values' print the name and value for simple data types and
1787 
just the name for arrays, structures and unions.
1788 
 
1789 
Example
1790 
.......
1791 
 
1792 
     (gdb)
1793 
      -var-list-children n
1794 
      ^done,numchild=N,children=[{name=NAME,
1795 
      numchild=N,type=TYPE},(repeats N times)]
1796 
     (gdb)
1797 
      -var-list-children --all-values n
1798 
      ^done,numchild=N,children=[{name=NAME,
1799 
      numchild=N,value=VALUE,type=TYPE},(repeats N times)]
1800 
 
1801 
The `-var-info-type' Command
1802 
----------------------------
1803 
 
1804 
Synopsis
1805 
........
1806 
 
1807 
      -var-info-type NAME
1808 
 
1809 
   Returns the type of the specified variable NAME.  The type is
1810 
returned as a string in the same format as it is output by the GDB CLI:
1811 
 
1812 
      type=TYPENAME
1813 
 
1814 
The `-var-info-expression' Command
1815 
----------------------------------
1816 
 
1817 
Synopsis
1818 
........
1819 
 
1820 
      -var-info-expression NAME
1821 
 
1822 
   Returns a string that is suitable for presenting this variable
1823 
object in user interface.  The string is generally not valid expression
1824 
in the current language, and cannot be evaluated.
1825 
 
1826 
   For example, if `a' is an array, and variable object `A' was created
1827 
for `a', then we'll get this output:
1828 
 
1829 
     (gdb) -var-info-expression A.1
1830 
     ^done,lang="C",exp="1"
1831 
 
1832 
Here, the values of `lang' can be `{"C" | "C++" | "Java"}'.
1833 
 
1834 
   Note that the output of the `-var-list-children' command also
1835 
includes those expressions, so the `-var-info-expression' command is of
1836 
limited use.
1837 
 
1838 
The `-var-info-path-expression' Command
1839 
---------------------------------------
1840 
 
1841 
Synopsis
1842 
........
1843 
 
1844 
      -var-info-path-expression NAME
1845 
 
1846 
   Returns an expression that can be evaluated in the current context
1847 
and will yield the same value that a variable object has.  Compare this
1848 
with the `-var-info-expression' command, which result can be used only
1849 
for UI presentation.  Typical use of the `-var-info-path-expression'
1850 
command is creating a watchpoint from a variable object.
1851 
 
1852 
   For example, suppose `C' is a C++ class, derived from class `Base',
1853 
and that the `Base' class has a member called `m_size'.  Assume a
1854 
variable `c' is has the type of `C' and a variable object `C' was
1855 
created for variable `c'.  Then, we'll get this output:
1856 
     (gdb) -var-info-path-expression C.Base.public.m_size
1857 
     ^done,path_expr=((Base)c).m_size)
1858 
 
1859 
The `-var-show-attributes' Command
1860 
----------------------------------
1861 
 
1862 
Synopsis
1863 
........
1864 
 
1865 
      -var-show-attributes NAME
1866 
 
1867 
   List attributes of the specified variable object NAME:
1868 
 
1869 
      status=ATTR [ ( ,ATTR )* ]
1870 
 
1871 
where ATTR is `{ { editable | noneditable } | TBD }'.
1872 
 
1873 
The `-var-evaluate-expression' Command
1874 
--------------------------------------
1875 
 
1876 
Synopsis
1877 
........
1878 
 
1879 
      -var-evaluate-expression NAME
1880 
 
1881 
   Evaluates the expression that is represented by the specified
1882 
variable object and returns its value as a string.  The format of the
1883 
string can be changed using the `-var-set-format' command.
1884 
 
1885 
      value=VALUE
1886 
 
1887 
   Note that one must invoke `-var-list-children' for a variable before
1888 
the value of a child variable can be evaluated.
1889 
 
1890 
The `-var-assign' Command
1891 
-------------------------
1892 
 
1893 
Synopsis
1894 
........
1895 
 
1896 
      -var-assign NAME EXPRESSION
1897 
 
1898 
   Assigns the value of EXPRESSION to the variable object specified by
1899 
NAME.  The object must be `editable'.  If the variable's value is
1900 
altered by the assign, the variable will show up in any subsequent
1901 
`-var-update' list.
1902 
 
1903 
Example
1904 
.......
1905 
 
1906 
     (gdb)
1907 
     -var-assign var1 3
1908 
     ^done,value="3"
1909 
     (gdb)
1910 
     -var-update *
1911 
     ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
1912 
     (gdb)
1913 
 
1914 
The `-var-update' Command
1915 
-------------------------
1916 
 
1917 
Synopsis
1918 
........
1919 
 
1920 
      -var-update [PRINT-VALUES] {NAME | "*"}
1921 
 
1922 
   Reevaluate the expressions corresponding to the variable object NAME
1923 
and all its direct and indirect children, and return the list of
1924 
variable objects whose values have changed; NAME must be a root
1925 
variable object.  Here, "changed" means that the result of
1926 
`-var-evaluate-expression' before and after the `-var-update' is
1927 
different.  If `*' is used as the variable object names, all existing
1928 
variable objects are updated, except for frozen ones (*note
1929 
-var-set-frozen::).  The option PRINT-VALUES determines whether both
1930 
names and values, or just names are printed.  The possible values of
1931 
this options are the same as for `-var-list-children' (*note
1932 
-var-list-children::).  It is recommended to use the `--all-values'
1933 
option, to reduce the number of MI commands needed on each program stop.
1934 
 
1935 
Example
1936 
.......
1937 
 
1938 
     (gdb)
1939 
     -var-assign var1 3
1940 
     ^done,value="3"
1941 
     (gdb)
1942 
     -var-update --all-values var1
1943 
     ^done,changelist=[{name="var1",value="3",in_scope="true",
1944 
     type_changed="false"}]
1945 
     (gdb)
1946 
 
1947 
   The field in_scope may take three values:
1948 
 
1949 
`"true"'
1950 
     The variable object's current value is valid.
1951 
 
1952 
`"false"'
1953 
     The variable object does not currently hold a valid value but it
1954 
     may hold one in the future if its associated expression comes back
1955 
     into scope.
1956 
 
1957 
`"invalid"'
1958 
     The variable object no longer holds a valid value.  This can occur
1959 
     when the executable file being debugged has changed, either
1960 
     through recompilation or by using the GDB `file' command.  The
1961 
     front end should normally choose to delete these variable objects.
1962 
 
1963 
   In the future new values may be added to this list so the front
1964 
should be prepared for this possibility.  *Note GDB/MI Development and
1965 
Front Ends: GDB/MI Development and Front Ends.
1966 
 
1967 
The `-var-set-frozen' Command
1968 
-----------------------------
1969 
 
1970 
Synopsis
1971 
........
1972 
 
1973 
      -var-set-frozen NAME FLAG
1974 
 
1975 
   Set the frozenness flag on the variable object NAME.  The FLAG
1976 
parameter should be either `1' to make the variable frozen or `0' to
1977 
make it unfrozen.  If a variable object is frozen, then neither itself,
1978 
nor any of its children, are implicitly updated by `-var-update' of a
1979 
parent variable or by `-var-update *'.  Only `-var-update' of the
1980 
variable itself will update its value and values of its children.
1981 
After a variable object is unfrozen, it is implicitly updated by all
1982 
subsequent `-var-update' operations.  Unfreezing a variable does not
1983 
update it, only subsequent `-var-update' does.
1984 
 
1985 
Example
1986 
.......
1987 
 
1988 
     (gdb)
1989 
     -var-set-frozen V 1
1990 
     ^done
1991 
     (gdb)
1992 
 
1993 

1994 
File: gdb.info,  Node: GDB/MI Data Manipulation,  Next: GDB/MI Tracepoint Commands,  Prev: GDB/MI Variable Objects,  Up: GDB/MI
1995 
 
1996 
24.13 GDB/MI Data Manipulation
1997 
==============================
1998 
 
1999 
This section describes the GDB/MI commands that manipulate data:
2000 
examine memory and registers, evaluate expressions, etc.
2001 
 
2002 
The `-data-disassemble' Command
2003 
-------------------------------
2004 
 
2005 
Synopsis
2006 
........
2007 
 
2008 
      -data-disassemble
2009 
         [ -s START-ADDR -e END-ADDR ]
2010 
       | [ -f FILENAME -l LINENUM [ -n LINES ] ]
2011 
       -- MODE
2012 
 
2013 
Where:
2014 
 
2015 
`START-ADDR'
2016 
     is the beginning address (or `$pc')
2017 
 
2018 
`END-ADDR'
2019 
     is the end address
2020 
 
2021 
`FILENAME'
2022 
     is the name of the file to disassemble
2023 
 
2024 
`LINENUM'
2025 
     is the line number to disassemble around
2026 
 
2027 
`LINES'
2028 
     is the number of disassembly lines to be produced.  If it is -1,
2029 
     the whole function will be disassembled, in case no END-ADDR is
2030 
     specified.  If END-ADDR is specified as a non-zero value, and
2031 
     LINES is lower than the number of disassembly lines between
2032 
     START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
2033 
     is higher than the number of lines between START-ADDR and
2034 
     END-ADDR, only the lines up to END-ADDR are displayed.
2035 
 
2036 
`MODE'
2037 
     is either 0 (meaning only disassembly) or 1 (meaning mixed source
2038 
     and disassembly).
2039 
 
2040 
Result
2041 
......
2042 
 
2043 
The output for each instruction is composed of four fields:
2044 
 
2045 
   * Address
2046 
 
2047 
   * Func-name
2048 
 
2049 
   * Offset
2050 
 
2051 
   * Instruction
2052 
 
2053 
   Note that whatever included in the instruction field, is not
2054 
manipulated directly by GDB/MI, i.e., it is not possible to adjust its
2055 
format.
2056 
 
2057 
GDB Command
2058 
...........
2059 
 
2060 
There's no direct mapping from this command to the CLI.
2061 
 
2062 
Example
2063 
.......
2064 
 
2065 
Disassemble from the current value of `$pc' to `$pc + 20':
2066 
 
2067 
     (gdb)
2068 
     -data-disassemble -s $pc -e "$pc + 20" -- 0
2069 
     ^done,
2070 
     asm_insns=[
2071 
     {address="0x000107c0",func-name="main",offset="4",
2072 
     inst="mov  2, %o0"},
2073 
     {address="0x000107c4",func-name="main",offset="8",
2074 
     inst="sethi  %hi(0x11800), %o2"},
2075 
     {address="0x000107c8",func-name="main",offset="12",
2076 
     inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
2077 
     {address="0x000107cc",func-name="main",offset="16",
2078 
     inst="sethi  %hi(0x11800), %o2"},
2079 
     {address="0x000107d0",func-name="main",offset="20",
2080 
     inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
2081 
     (gdb)
2082 
 
2083 
   Disassemble the whole `main' function.  Line 32 is part of `main'.
2084 
 
2085 
     -data-disassemble -f basics.c -l 32 -- 0
2086 
     ^done,asm_insns=[
2087 
     {address="0x000107bc",func-name="main",offset="0",
2088 
     inst="save  %sp, -112, %sp"},
2089 
     {address="0x000107c0",func-name="main",offset="4",
2090 
     inst="mov   2, %o0"},
2091 
     {address="0x000107c4",func-name="main",offset="8",
2092 
     inst="sethi %hi(0x11800), %o2"},
2093 
     [...]
2094 
     {address="0x0001081c",func-name="main",offset="96",inst="ret "},
2095 
     {address="0x00010820",func-name="main",offset="100",inst="restore "}]
2096 
     (gdb)
2097 
 
2098 
   Disassemble 3 instructions from the start of `main':
2099 
 
2100 
     (gdb)
2101 
     -data-disassemble -f basics.c -l 32 -n 3 -- 0
2102 
     ^done,asm_insns=[
2103 
     {address="0x000107bc",func-name="main",offset="0",
2104 
     inst="save  %sp, -112, %sp"},
2105 
     {address="0x000107c0",func-name="main",offset="4",
2106 
     inst="mov  2, %o0"},
2107 
     {address="0x000107c4",func-name="main",offset="8",
2108 
     inst="sethi  %hi(0x11800), %o2"}]
2109 
     (gdb)
2110 
 
2111 
   Disassemble 3 instructions from the start of `main' in mixed mode:
2112 
 
2113 
     (gdb)
2114 
     -data-disassemble -f basics.c -l 32 -n 3 -- 1
2115 
     ^done,asm_insns=[
2116 
     src_and_asm_line={line="31",
2117 
     file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
2118 
       testsuite/gdb.mi/basics.c",line_asm_insn=[
2119 
     {address="0x000107bc",func-name="main",offset="0",
2120 
     inst="save  %sp, -112, %sp"}]},
2121 
     src_and_asm_line={line="32",
2122 
     file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
2123 
       testsuite/gdb.mi/basics.c",line_asm_insn=[
2124 
     {address="0x000107c0",func-name="main",offset="4",
2125 
     inst="mov  2, %o0"},
2126 
     {address="0x000107c4",func-name="main",offset="8",
2127 
     inst="sethi  %hi(0x11800), %o2"}]}]
2128 
     (gdb)
2129 
 
2130 
The `-data-evaluate-expression' Command
2131 
---------------------------------------
2132 
 
2133 
Synopsis
2134 
........
2135 
 
2136 
      -data-evaluate-expression EXPR
2137 
 
2138 
   Evaluate EXPR as an expression.  The expression could contain an
2139 
inferior function call.  The function call will execute synchronously.
2140 
If the expression contains spaces, it must be enclosed in double quotes.
2141 
 
2142 
GDB Command
2143 
...........
2144 
 
2145 
The corresponding GDB commands are `print', `output', and `call'.  In
2146 
`gdbtk' only, there's a corresponding `gdb_eval' command.
2147 
 
2148 
Example
2149 
.......
2150 
 
2151 
In the following example, the numbers that precede the commands are the
2152 
"tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command
2153 
Syntax.  Notice how GDB/MI returns the same tokens in its output.
2154 
 
2155 
     211-data-evaluate-expression A
2156 
     211^done,value="1"
2157 
     (gdb)
2158 
     311-data-evaluate-expression &A
2159 
     311^done,value="0xefffeb7c"
2160 
     (gdb)
2161 
     411-data-evaluate-expression A+3
2162 
     411^done,value="4"
2163 
     (gdb)
2164 
     511-data-evaluate-expression "A + 3"
2165 
     511^done,value="4"
2166 
     (gdb)
2167 
 
2168 
The `-data-list-changed-registers' Command
2169 
------------------------------------------
2170 
 
2171 
Synopsis
2172 
........
2173 
 
2174 
      -data-list-changed-registers
2175 
 
2176 
   Display a list of the registers that have changed.
2177 
 
2178 
GDB Command
2179 
...........
2180 
 
2181 
GDB doesn't have a direct analog for this command; `gdbtk' has the
2182 
corresponding command `gdb_changed_register_list'.
2183 
 
2184 
Example
2185 
.......
2186 
 
2187 
On a PPC MBX board:
2188 
 
2189 
     (gdb)
2190 
     -exec-continue
2191 
     ^running
2192 
 
2193 
     (gdb)
2194 
     *stopped,reason="breakpoint-hit",bkptno="1",frame={func="main",
2195 
     args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"}
2196 
     (gdb)
2197 
     -data-list-changed-registers
2198 
     ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
2199 
     "10","11","13","14","15","16","17","18","19","20","21","22","23",
2200 
     "24","25","26","27","28","30","31","64","65","66","67","69"]
2201 
     (gdb)
2202 
 
2203 
The `-data-list-register-names' Command
2204 
---------------------------------------
2205 
 
2206 
Synopsis
2207 
........
2208 
 
2209 
      -data-list-register-names [ ( REGNO )+ ]
2210 
 
2211 
   Show a list of register names for the current target.  If no
2212 
arguments are given, it shows a list of the names of all the registers.
2213 
If integer numbers are given as arguments, it will print a list of the
2214 
names of the registers corresponding to the arguments.  To ensure
2215 
consistency between a register name and its number, the output list may
2216 
include empty register names.
2217 
 
2218 
GDB Command
2219 
...........
2220 
 
2221 
GDB does not have a command which corresponds to
2222 
`-data-list-register-names'.  In `gdbtk' there is a corresponding
2223 
command `gdb_regnames'.
2224 
 
2225 
Example
2226 
.......
2227 
 
2228 
For the PPC MBX board:
2229 
     (gdb)
2230 
     -data-list-register-names
2231 
     ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
2232 
     "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
2233 
     "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
2234 
     "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
2235 
     "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
2236 
     "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
2237 
     "", "pc","ps","cr","lr","ctr","xer"]
2238 
     (gdb)
2239 
     -data-list-register-names 1 2 3
2240 
     ^done,register-names=["r1","r2","r3"]
2241 
     (gdb)
2242 
 
2243 
The `-data-list-register-values' Command
2244 
----------------------------------------
2245 
 
2246 
Synopsis
2247 
........
2248 
 
2249 
      -data-list-register-values FMT [ ( REGNO )*]
2250 
 
2251 
   Display the registers' contents.  FMT is the format according to
2252 
which the registers' contents are to be returned, followed by an
2253 
optional list of numbers specifying the registers to display.  A
2254 
missing list of numbers indicates that the contents of all the
2255 
registers must be returned.
2256 
 
2257 
   Allowed formats for FMT are:
2258 
 
2259 
`x'
2260 
     Hexadecimal
2261 
 
2262 
`o'
2263 
     Octal
2264 
 
2265 
`t'
2266 
     Binary
2267 
 
2268 
`d'
2269 
     Decimal
2270 
 
2271 
`r'
2272 
     Raw
2273 
 
2274 
`N'
2275 
     Natural
2276 
 
2277 
GDB Command
2278 
...........
2279 
 
2280 
The corresponding GDB commands are `info reg', `info all-reg', and (in
2281 
`gdbtk') `gdb_fetch_registers'.
2282 
 
2283 
Example
2284 
.......
2285 
 
2286 
For a PPC MBX board (note: line breaks are for readability only, they
2287 
don't appear in the actual output):
2288 
 
2289 
     (gdb)
2290 
     -data-list-register-values r 64 65
2291 
     ^done,register-values=[{number="64",value="0xfe00a300"},
2292 
     {number="65",value="0x00029002"}]
2293 
     (gdb)
2294 
     -data-list-register-values x
2295 
     ^done,register-values=[{number="0",value="0xfe0043c8"},
2296 
     {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
2297 
     {number="3",value="0x0"},{number="4",value="0xa"},
2298 
     {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
2299 
     {number="7",value="0xfe011e98"},{number="8",value="0x2"},
2300 
     {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
2301 
     {number="11",value="0x1"},{number="12",value="0x0"},
2302 
     {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
2303 
     {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
2304 
     {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
2305 
     {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
2306 
     {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
2307 
     {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
2308 
     {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
2309 
     {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
2310 
     {number="29",value="0x0"},{number="30",value="0xfe010000"},
2311 
     {number="31",value="0x0"},{number="32",value="0x0"},
2312 
     {number="33",value="0x0"},{number="34",value="0x0"},
2313 
     {number="35",value="0x0"},{number="36",value="0x0"},
2314 
     {number="37",value="0x0"},{number="38",value="0x0"},
2315 
     {number="39",value="0x0"},{number="40",value="0x0"},
2316 
     {number="41",value="0x0"},{number="42",value="0x0"},
2317 
     {number="43",value="0x0"},{number="44",value="0x0"},
2318 
     {number="45",value="0x0"},{number="46",value="0x0"},
2319 
     {number="47",value="0x0"},{number="48",value="0x0"},
2320 
     {number="49",value="0x0"},{number="50",value="0x0"},
2321 
     {number="51",value="0x0"},{number="52",value="0x0"},
2322 
     {number="53",value="0x0"},{number="54",value="0x0"},
2323 
     {number="55",value="0x0"},{number="56",value="0x0"},
2324 
     {number="57",value="0x0"},{number="58",value="0x0"},
2325 
     {number="59",value="0x0"},{number="60",value="0x0"},
2326 
     {number="61",value="0x0"},{number="62",value="0x0"},
2327 
     {number="63",value="0x0"},{number="64",value="0xfe00a300"},
2328 
     {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
2329 
     {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
2330 
     {number="69",value="0x20002b03"}]
2331 
     (gdb)
2332 
 
2333 
The `-data-read-memory' Command
2334 
-------------------------------
2335 
 
2336 
Synopsis
2337 
........
2338 
 
2339 
      -data-read-memory [ -o BYTE-OFFSET ]
2340 
        ADDRESS WORD-FORMAT WORD-SIZE
2341 
        NR-ROWS NR-COLS [ ASCHAR ]
2342 
 
2343 
where:
2344 
 
2345 
`ADDRESS'
2346 
     An expression specifying the address of the first memory word to be
2347 
     read.  Complex expressions containing embedded white space should
2348 
     be quoted using the C convention.
2349 
 
2350 
`WORD-FORMAT'
2351 
     The format to be used to print the memory words.  The notation is
2352 
     the same as for GDB's `print' command (*note Output Formats:
2353 
     Output Formats.).
2354 
 
2355 
`WORD-SIZE'
2356 
     The size of each memory word in bytes.
2357 
 
2358 
`NR-ROWS'
2359 
     The number of rows in the output table.
2360 
 
2361 
`NR-COLS'
2362 
     The number of columns in the output table.
2363 
 
2364 
`ASCHAR'
2365 
     If present, indicates that each row should include an ASCII dump.
2366 
     The value of ASCHAR is used as a padding character when a byte is
2367 
     not a member of the printable ASCII character set (printable ASCII
2368 
     characters are those whose code is between 32 and 126,
2369 
     inclusively).
2370 
 
2371 
`BYTE-OFFSET'
2372 
     An offset to add to the ADDRESS before fetching memory.
2373 
 
2374 
   This command displays memory contents as a table of NR-ROWS by
2375 
NR-COLS words, each word being WORD-SIZE bytes.  In total, `NR-ROWS *
2376 
NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
2377 
Should less than the requested number of bytes be returned by the
2378 
target, the missing words are identified using `N/A'.  The number of
2379 
bytes read from the target is returned in `nr-bytes' and the starting
2380 
address used to read memory in `addr'.
2381 
 
2382 
   The address of the next/previous row or page is available in
2383 
`next-row' and `prev-row', `next-page' and `prev-page'.
2384 
 
2385 
GDB Command
2386 
...........
2387 
 
2388 
The corresponding GDB command is `x'.  `gdbtk' has `gdb_get_mem' memory
2389 
read command.
2390 
 
2391 
Example
2392 
.......
2393 
 
2394 
Read six bytes of memory starting at `bytes+6' but then offset by `-6'
2395 
bytes.  Format as three rows of two columns.  One byte per word.
2396 
Display each word in hex.
2397 
 
2398 
     (gdb)
2399 
     9-data-read-memory -o -6 -- bytes+6 x 1 3 2
2400 
     9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
2401 
     next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
2402 
     prev-page="0x0000138a",memory=[
2403 
     {addr="0x00001390",data=["0x00","0x01"]},
2404 
     {addr="0x00001392",data=["0x02","0x03"]},
2405 
     {addr="0x00001394",data=["0x04","0x05"]}]
2406 
     (gdb)
2407 
 
2408 
   Read two bytes of memory starting at address `shorts + 64' and
2409 
display as a single word formatted in decimal.
2410 
 
2411 
     (gdb)
2412 
     5-data-read-memory shorts+64 d 2 1 1
2413 
     5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
2414 
     next-row="0x00001512",prev-row="0x0000150e",
2415 
     next-page="0x00001512",prev-page="0x0000150e",memory=[
2416 
     {addr="0x00001510",data=["128"]}]
2417 
     (gdb)
2418 
 
2419 
   Read thirty two bytes of memory starting at `bytes+16' and format as
2420 
eight rows of four columns.  Include a string encoding with `x' used as
2421 
the non-printable character.
2422 
 
2423 
     (gdb)
2424 
     4-data-read-memory bytes+16 x 1 8 4 x
2425 
     4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
2426 
     next-row="0x000013c0",prev-row="0x0000139c",
2427 
     next-page="0x000013c0",prev-page="0x00001380",memory=[
2428 
     {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
2429 
     {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
2430 
     {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
2431 
     {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
2432 
     {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
2433 
     {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
2434 
     {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
2435 
     {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
2436 
     (gdb)
2437 
 
2438 

2439 
File: gdb.info,  Node: GDB/MI Tracepoint Commands,  Next: GDB/MI Symbol Query,  Prev: GDB/MI Data Manipulation,  Up: GDB/MI
2440 
 
2441 
24.14 GDB/MI Tracepoint Commands
2442 
================================
2443 
 
2444 
The tracepoint commands are not yet implemented.
2445 
 
2446 

2447 
File: gdb.info,  Node: GDB/MI Symbol Query,  Next: GDB/MI File Commands,  Prev: GDB/MI Tracepoint Commands,  Up: GDB/MI
2448 
 
2449 
24.15 GDB/MI Symbol Query Commands
2450 
==================================
2451 
 
2452 
The `-symbol-info-address' Command
2453 
----------------------------------
2454 
 
2455 
Synopsis
2456 
........
2457 
 
2458 
      -symbol-info-address SYMBOL
2459 
 
2460 
   Describe where SYMBOL is stored.
2461 
 
2462 
GDB Command
2463 
...........
2464 
 
2465 
The corresponding GDB command is `info address'.
2466 
 
2467 
Example
2468 
.......
2469 
 
2470 
N.A.
2471 
 
2472 
The `-symbol-info-file' Command
2473 
-------------------------------
2474 
 
2475 
Synopsis
2476 
........
2477 
 
2478 
      -symbol-info-file
2479 
 
2480 
   Show the file for the symbol.
2481 
 
2482 
GDB Command
2483 
...........
2484 
 
2485 
There's no equivalent GDB command.  `gdbtk' has `gdb_find_file'.
2486 
 
2487 
Example
2488 
.......
2489 
 
2490 
N.A.
2491 
 
2492 
The `-symbol-info-function' Command
2493 
-----------------------------------
2494 
 
2495 
Synopsis
2496 
........
2497 
 
2498 
      -symbol-info-function
2499 
 
2500 
   Show which function the symbol lives in.
2501 
 
2502 
GDB Command
2503 
...........
2504 
 
2505 
`gdb_get_function' in `gdbtk'.
2506 
 
2507 
Example
2508 
.......
2509 
 
2510 
N.A.
2511 
 
2512 
The `-symbol-info-line' Command
2513 
-------------------------------
2514 
 
2515 
Synopsis
2516 
........
2517 
 
2518 
      -symbol-info-line
2519 
 
2520 
   Show the core addresses of the code for a source line.
2521 
 
2522 
GDB Command
2523 
...........
2524 
 
2525 
The corresponding GDB command is `info line'.  `gdbtk' has the
2526 
`gdb_get_line' and `gdb_get_file' commands.
2527 
 
2528 
Example
2529 
.......
2530 
 
2531 
N.A.
2532 
 
2533 
The `-symbol-info-symbol' Command
2534 
---------------------------------
2535 
 
2536 
Synopsis
2537 
........
2538 
 
2539 
      -symbol-info-symbol ADDR
2540 
 
2541 
   Describe what symbol is at location ADDR.
2542 
 
2543 
GDB Command
2544 
...........
2545 
 
2546 
The corresponding GDB command is `info symbol'.
2547 
 
2548 
Example
2549 
.......
2550 
 
2551 
N.A.
2552 
 
2553 
The `-symbol-list-functions' Command
2554 
------------------------------------
2555 
 
2556 
Synopsis
2557 
........
2558 
 
2559 
      -symbol-list-functions
2560 
 
2561 
   List the functions in the executable.
2562 
 
2563 
GDB Command
2564 
...........
2565 
 
2566 
`info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'.
2567 
 
2568 
Example
2569 
.......
2570 
 
2571 
N.A.
2572 
 
2573 
The `-symbol-list-lines' Command
2574 
--------------------------------
2575 
 
2576 
Synopsis
2577 
........
2578 
 
2579 
      -symbol-list-lines FILENAME
2580 
 
2581 
   Print the list of lines that contain code and their associated
2582 
program addresses for the given source filename.  The entries are
2583 
sorted in ascending PC order.
2584 
 
2585 
GDB Command
2586 
...........
2587 
 
2588 
There is no corresponding GDB command.
2589 
 
2590 
Example
2591 
.......
2592 
 
2593 
     (gdb)
2594 
     -symbol-list-lines basics.c
2595 
     ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
2596 
     (gdb)
2597 
 
2598 
The `-symbol-list-types' Command
2599 
--------------------------------
2600 
 
2601 
Synopsis
2602 
........
2603 
 
2604 
      -symbol-list-types
2605 
 
2606 
   List all the type names.
2607 
 
2608 
GDB Command
2609 
...........
2610 
 
2611 
The corresponding commands are `info types' in GDB, `gdb_search' in
2612 
`gdbtk'.
2613 
 
2614 
Example
2615 
.......
2616 
 
2617 
N.A.
2618 
 
2619 
The `-symbol-list-variables' Command
2620 
------------------------------------
2621 
 
2622 
Synopsis
2623 
........
2624 
 
2625 
      -symbol-list-variables
2626 
 
2627 
   List all the global and static variable names.
2628 
 
2629 
GDB Command
2630 
...........
2631 
 
2632 
`info variables' in GDB, `gdb_search' in `gdbtk'.
2633 
 
2634 
Example
2635 
.......
2636 
 
2637 
N.A.
2638 
 
2639 
The `-symbol-locate' Command
2640 
----------------------------
2641 
 
2642 
Synopsis
2643 
........
2644 
 
2645 
      -symbol-locate
2646 
 
2647 
GDB Command
2648 
...........
2649 
 
2650 
`gdb_loc' in `gdbtk'.
2651 
 
2652 
Example
2653 
.......
2654 
 
2655 
N.A.
2656 
 
2657 
The `-symbol-type' Command
2658 
--------------------------
2659 
 
2660 
Synopsis
2661 
........
2662 
 
2663 
      -symbol-type VARIABLE
2664 
 
2665 
   Show type of VARIABLE.
2666 
 
2667 
GDB Command
2668 
...........
2669 
 
2670 
The corresponding GDB command is `ptype', `gdbtk' has
2671 
`gdb_obj_variable'.
2672 
 
2673 
Example
2674 
.......
2675 
 
2676 
N.A.
2677 
 
2678 

2679 
File: gdb.info,  Node: GDB/MI File Commands,  Next: GDB/MI Target Manipulation,  Prev: GDB/MI Symbol Query,  Up: GDB/MI
2680 
 
2681 
24.16 GDB/MI File Commands
2682 
==========================
2683 
 
2684 
This section describes the GDB/MI commands to specify executable file
2685 
names and to read in and obtain symbol table information.
2686 
 
2687 
The `-file-exec-and-symbols' Command
2688 
------------------------------------
2689 
 
2690 
Synopsis
2691 
........
2692 
 
2693 
      -file-exec-and-symbols FILE
2694 
 
2695 
   Specify the executable file to be debugged.  This file is the one
2696 
from which the symbol table is also read.  If no file is specified, the
2697 
command clears the executable and symbol information.  If breakpoints
2698 
are set when using this command with no arguments, GDB will produce
2699 
error messages.  Otherwise, no output is produced, except a completion
2700 
notification.
2701 
 
2702 
GDB Command
2703 
...........
2704 
 
2705 
The corresponding GDB command is `file'.
2706 
 
2707 
Example
2708 
.......
2709 
 
2710 
     (gdb)
2711 
     -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2712 
     ^done
2713 
     (gdb)
2714 
 
2715 
The `-file-exec-file' Command
2716 
-----------------------------
2717 
 
2718 
Synopsis
2719 
........
2720 
 
2721 
      -file-exec-file FILE
2722 
 
2723 
   Specify the executable file to be debugged.  Unlike
2724 
`-file-exec-and-symbols', the symbol table is _not_ read from this
2725 
file.  If used without argument, GDB clears the information about the
2726 
executable file.  No output is produced, except a completion
2727 
notification.
2728 
 
2729 
GDB Command
2730 
...........
2731 
 
2732 
The corresponding GDB command is `exec-file'.
2733 
 
2734 
Example
2735 
.......
2736 
 
2737 
     (gdb)
2738 
     -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2739 
     ^done
2740 
     (gdb)
2741 
 
2742 
The `-file-list-exec-sections' Command
2743 
--------------------------------------
2744 
 
2745 
Synopsis
2746 
........
2747 
 
2748 
      -file-list-exec-sections
2749 
 
2750 
   List the sections of the current executable file.
2751 
 
2752 
GDB Command
2753 
...........
2754 
 
2755 
The GDB command `info file' shows, among the rest, the same information
2756 
as this command.  `gdbtk' has a corresponding command `gdb_load_info'.
2757 
 
2758 
Example
2759 
.......
2760 
 
2761 
N.A.
2762 
 
2763 
The `-file-list-exec-source-file' Command
2764 
-----------------------------------------
2765 
 
2766 
Synopsis
2767 
........
2768 
 
2769 
      -file-list-exec-source-file
2770 
 
2771 
   List the line number, the current source file, and the absolute path
2772 
to the current source file for the current executable.  The macro
2773 
information field has a value of `1' or `0' depending on whether or not
2774 
the file includes preprocessor macro information.
2775 
 
2776 
GDB Command
2777 
...........
2778 
 
2779 
The GDB equivalent is `info source'
2780 
 
2781 
Example
2782 
.......
2783 
 
2784 
     (gdb)
2785 
     123-file-list-exec-source-file
2786 
     123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
2787 
     (gdb)
2788 
 
2789 
The `-file-list-exec-source-files' Command
2790 
------------------------------------------
2791 
 
2792 
Synopsis
2793 
........
2794 
 
2795 
      -file-list-exec-source-files
2796 
 
2797 
   List the source files for the current executable.
2798 
 
2799 
   It will always output the filename, but only when GDB can find the
2800 
absolute file name of a source file, will it output the fullname.
2801 
 
2802 
GDB Command
2803 
...........
2804 
 
2805 
The GDB equivalent is `info sources'.  `gdbtk' has an analogous command
2806 
`gdb_listfiles'.
2807 
 
2808 
Example
2809 
.......
2810 
 
2811 
     (gdb)
2812 
     -file-list-exec-source-files
2813 
     ^done,files=[
2814 
     {file=foo.c,fullname=/home/foo.c},
2815 
     {file=/home/bar.c,fullname=/home/bar.c},
2816 
     {file=gdb_could_not_find_fullpath.c}]
2817 
     (gdb)
2818 
 
2819 
The `-file-list-shared-libraries' Command
2820 
-----------------------------------------
2821 
 
2822 
Synopsis
2823 
........
2824 
 
2825 
      -file-list-shared-libraries
2826 
 
2827 
   List the shared libraries in the program.
2828 
 
2829 
GDB Command
2830 
...........
2831 
 
2832 
The corresponding GDB command is `info shared'.
2833 
 
2834 
Example
2835 
.......
2836 
 
2837 
N.A.
2838 
 
2839 
The `-file-list-symbol-files' Command
2840 
-------------------------------------
2841 
 
2842 
Synopsis
2843 
........
2844 
 
2845 
      -file-list-symbol-files
2846 
 
2847 
   List symbol files.
2848 
 
2849 
GDB Command
2850 
...........
2851 
 
2852 
The corresponding GDB command is `info file' (part of it).
2853 
 
2854 
Example
2855 
.......
2856 
 
2857 
N.A.
2858 
 
2859 
The `-file-symbol-file' Command
2860 
-------------------------------
2861 
 
2862 
Synopsis
2863 
........
2864 
 
2865 
      -file-symbol-file FILE
2866 
 
2867 
   Read symbol table info from the specified FILE argument.  When used
2868 
without arguments, clears GDB's symbol table info.  No output is
2869 
produced, except for a completion notification.
2870 
 
2871 
GDB Command
2872 
...........
2873 
 
2874 
The corresponding GDB command is `symbol-file'.
2875 
 
2876 
Example
2877 
.......
2878 
 
2879 
     (gdb)
2880 
     -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2881 
     ^done
2882 
     (gdb)
2883 
 
2884 

2885 
File: gdb.info,  Node: GDB/MI Target Manipulation,  Next: GDB/MI File Transfer Commands,  Prev: GDB/MI File Commands,  Up: GDB/MI
2886 
 
2887 
24.17 GDB/MI Target Manipulation Commands
2888 
=========================================
2889 
 
2890 
The `-target-attach' Command
2891 
----------------------------
2892 
 
2893 
Synopsis
2894 
........
2895 
 
2896 
      -target-attach PID | FILE
2897 
 
2898 
   Attach to a process PID or a file FILE outside of GDB.
2899 
 
2900 
GDB Command
2901 
...........
2902 
 
2903 
The corresponding GDB command is `attach'.
2904 
 
2905 
Example
2906 
.......
2907 
 
2908 
N.A.
2909 
 
2910 
The `-target-compare-sections' Command
2911 
--------------------------------------
2912 
 
2913 
Synopsis
2914 
........
2915 
 
2916 
      -target-compare-sections [ SECTION ]
2917 
 
2918 
   Compare data of section SECTION on target to the exec file.  Without
2919 
the argument, all sections are compared.
2920 
 
2921 
GDB Command
2922 
...........
2923 
 
2924 
The GDB equivalent is `compare-sections'.
2925 
 
2926 
Example
2927 
.......
2928 
 
2929 
N.A.
2930 
 
2931 
The `-target-detach' Command
2932 
----------------------------
2933 
 
2934 
Synopsis
2935 
........
2936 
 
2937 
      -target-detach
2938 
 
2939 
   Detach from the remote target which normally resumes its execution.
2940 
There's no output.
2941 
 
2942 
GDB Command
2943 
...........
2944 
 
2945 
The corresponding GDB command is `detach'.
2946 
 
2947 
Example
2948 
.......
2949 
 
2950 
     (gdb)
2951 
     -target-detach
2952 
     ^done
2953 
     (gdb)
2954 
 
2955 
The `-target-disconnect' Command
2956 
--------------------------------
2957 
 
2958 
Synopsis
2959 
........
2960 
 
2961 
      -target-disconnect
2962 
 
2963 
   Disconnect from the remote target.  There's no output and the target
2964 
is generally not resumed.
2965 
 
2966 
GDB Command
2967 
...........
2968 
 
2969 
The corresponding GDB command is `disconnect'.
2970 
 
2971 
Example
2972 
.......
2973 
 
2974 
     (gdb)
2975 
     -target-disconnect
2976 
     ^done
2977 
     (gdb)
2978 
 
2979 
The `-target-download' Command
2980 
------------------------------
2981 
 
2982 
Synopsis
2983 
........
2984 
 
2985 
      -target-download
2986 
 
2987 
   Loads the executable onto the remote target.  It prints out an
2988 
update message every half second, which includes the fields:
2989 
 
2990 
`section'
2991 
     The name of the section.
2992 
 
2993 
`section-sent'
2994 
     The size of what has been sent so far for that section.
2995 
 
2996 
`section-size'
2997 
     The size of the section.
2998 
 
2999 
`total-sent'
3000 
     The total size of what was sent so far (the current and the
3001 
     previous sections).
3002 
 
3003 
`total-size'
3004 
     The size of the overall executable to download.
3005 
 
3006 
Each message is sent as status record (*note GDB/MI Output Syntax:
3007 
GDB/MI Output Syntax.).
3008 
 
3009 
   In addition, it prints the name and size of the sections, as they are
3010 
downloaded.  These messages include the following fields:
3011 
 
3012 
`section'
3013 
     The name of the section.
3014 
 
3015 
`section-size'
3016 
     The size of the section.
3017 
 
3018 
`total-size'
3019 
     The size of the overall executable to download.
3020 
 
3021 
At the end, a summary is printed.
3022 
 
3023 
GDB Command
3024 
...........
3025 
 
3026 
The corresponding GDB command is `load'.
3027 
 
3028 
Example
3029 
.......
3030 
 
3031 
Note: each status message appears on a single line.  Here the messages
3032 
have been broken down so that they can fit onto a page.
3033 
 
3034 
     (gdb)
3035 
     -target-download
3036 
     +download,{section=".text",section-size="6668",total-size="9880"}
3037 
     +download,{section=".text",section-sent="512",section-size="6668",
3038 
     total-sent="512",total-size="9880"}
3039 
     +download,{section=".text",section-sent="1024",section-size="6668",
3040 
     total-sent="1024",total-size="9880"}
3041 
     +download,{section=".text",section-sent="1536",section-size="6668",
3042 
     total-sent="1536",total-size="9880"}
3043 
     +download,{section=".text",section-sent="2048",section-size="6668",
3044 
     total-sent="2048",total-size="9880"}
3045 
     +download,{section=".text",section-sent="2560",section-size="6668",
3046 
     total-sent="2560",total-size="9880"}
3047 
     +download,{section=".text",section-sent="3072",section-size="6668",
3048 
     total-sent="3072",total-size="9880"}
3049 
     +download,{section=".text",section-sent="3584",section-size="6668",
3050 
     total-sent="3584",total-size="9880"}
3051 
     +download,{section=".text",section-sent="4096",section-size="6668",
3052 
     total-sent="4096",total-size="9880"}
3053 
     +download,{section=".text",section-sent="4608",section-size="6668",
3054 
     total-sent="4608",total-size="9880"}
3055 
     +download,{section=".text",section-sent="5120",section-size="6668",
3056 
     total-sent="5120",total-size="9880"}
3057 
     +download,{section=".text",section-sent="5632",section-size="6668",
3058 
     total-sent="5632",total-size="9880"}
3059 
     +download,{section=".text",section-sent="6144",section-size="6668",
3060 
     total-sent="6144",total-size="9880"}
3061 
     +download,{section=".text",section-sent="6656",section-size="6668",
3062 
     total-sent="6656",total-size="9880"}
3063 
     +download,{section=".init",section-size="28",total-size="9880"}
3064 
     +download,{section=".fini",section-size="28",total-size="9880"}
3065 
     +download,{section=".data",section-size="3156",total-size="9880"}
3066 
     +download,{section=".data",section-sent="512",section-size="3156",
3067 
     total-sent="7236",total-size="9880"}
3068 
     +download,{section=".data",section-sent="1024",section-size="3156",
3069 
     total-sent="7748",total-size="9880"}
3070 
     +download,{section=".data",section-sent="1536",section-size="3156",
3071 
     total-sent="8260",total-size="9880"}
3072 
     +download,{section=".data",section-sent="2048",section-size="3156",
3073 
     total-sent="8772",total-size="9880"}
3074 
     +download,{section=".data",section-sent="2560",section-size="3156",
3075 
     total-sent="9284",total-size="9880"}
3076 
     +download,{section=".data",section-sent="3072",section-size="3156",
3077 
     total-sent="9796",total-size="9880"}
3078 
     ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3079 
     write-rate="429"
3080 
     (gdb)
3081 
 
3082 
The `-target-exec-status' Command
3083 
---------------------------------
3084 
 
3085 
Synopsis
3086 
........
3087 
 
3088 
      -target-exec-status
3089 
 
3090 
   Provide information on the state of the target (whether it is
3091 
running or not, for instance).
3092 
 
3093 
GDB Command
3094 
...........
3095 
 
3096 
There's no equivalent GDB command.
3097 
 
3098 
Example
3099 
.......
3100 
 
3101 
N.A.
3102 
 
3103 
The `-target-list-available-targets' Command
3104 
--------------------------------------------
3105 
 
3106 
Synopsis
3107 
........
3108 
 
3109 
      -target-list-available-targets
3110 
 
3111 
   List the possible targets to connect to.
3112 
 
3113 
GDB Command
3114 
...........
3115 
 
3116 
The corresponding GDB command is `help target'.
3117 
 
3118 
Example
3119 
.......
3120 
 
3121 
N.A.
3122 
 
3123 
The `-target-list-current-targets' Command
3124 
------------------------------------------
3125 
 
3126 
Synopsis
3127 
........
3128 
 
3129 
      -target-list-current-targets
3130 
 
3131 
   Describe the current target.
3132 
 
3133 
GDB Command
3134 
...........
3135 
 
3136 
The corresponding information is printed by `info file' (among other
3137 
things).
3138 
 
3139 
Example
3140 
.......
3141 
 
3142 
N.A.
3143 
 
3144 
The `-target-list-parameters' Command
3145 
-------------------------------------
3146 
 
3147 
Synopsis
3148 
........
3149 
 
3150 
      -target-list-parameters
3151 
 
3152 
GDB Command
3153 
...........
3154 
 
3155 
No equivalent.
3156 
 
3157 
Example
3158 
.......
3159 
 
3160 
N.A.
3161 
 
3162 
The `-target-select' Command
3163 
----------------------------
3164 
 
3165 
Synopsis
3166 
........
3167 
 
3168 
      -target-select TYPE PARAMETERS ...
3169 
 
3170 
   Connect GDB to the remote target.  This command takes two args:
3171 
 
3172 
`TYPE'
3173 
     The type of target, for instance `async', `remote', etc.
3174 
 
3175 
`PARAMETERS'
3176 
     Device names, host names and the like.  *Note Commands for
3177 
     Managing Targets: Target Commands, for more details.
3178 
 
3179 
   The output is a connection notification, followed by the address at
3180 
which the target program is, in the following form:
3181 
 
3182 
     ^connected,addr="ADDRESS",func="FUNCTION NAME",
3183 
       args=[ARG LIST]
3184 
 
3185 
GDB Command
3186 
...........
3187 
 
3188 
The corresponding GDB command is `target'.
3189 
 
3190 
Example
3191 
.......
3192 
 
3193 
     (gdb)
3194 
     -target-select async /dev/ttya
3195 
     ^connected,addr="0xfe00a300",func="??",args=[]
3196 
     (gdb)
3197 
 
3198 

3199 
File: gdb.info,  Node: GDB/MI File Transfer Commands,  Next: GDB/MI Miscellaneous Commands,  Prev: GDB/MI Target Manipulation,  Up: GDB/MI
3200 
 
3201 
24.18 GDB/MI File Transfer Commands
3202 
===================================
3203 
 
3204 
The `-target-file-put' Command
3205 
------------------------------
3206 
 
3207 
Synopsis
3208 
........
3209 
 
3210 
      -target-file-put HOSTFILE TARGETFILE
3211 
 
3212 
   Copy file HOSTFILE from the host system (the machine running GDB) to
3213 
TARGETFILE on the target system.
3214 
 
3215 
GDB Command
3216 
...........
3217 
 
3218 
The corresponding GDB command is `remote put'.
3219 
 
3220 
Example
3221 
.......
3222 
 
3223 
     (gdb)
3224 
     -target-file-put localfile remotefile
3225 
     ^done
3226 
     (gdb)
3227 
 
3228 
The `-target-file-put' Command
3229 
------------------------------
3230 
 
3231 
Synopsis
3232 
........
3233 
 
3234 
      -target-file-get TARGETFILE HOSTFILE
3235 
 
3236 
   Copy file TARGETFILE from the target system to HOSTFILE on the host
3237 
system.
3238 
 
3239 
GDB Command
3240 
...........
3241 
 
3242 
The corresponding GDB command is `remote get'.
3243 
 
3244 
Example
3245 
.......
3246 
 
3247 
     (gdb)
3248 
     -target-file-get remotefile localfile
3249 
     ^done
3250 
     (gdb)
3251 
 
3252 
The `-target-file-delete' Command
3253 
---------------------------------
3254 
 
3255 
Synopsis
3256 
........
3257 
 
3258 
      -target-file-delete TARGETFILE
3259 
 
3260 
   Delete TARGETFILE from the target system.
3261 
 
3262 
GDB Command
3263 
...........
3264 
 
3265 
The corresponding GDB command is `remote delete'.
3266 
 
3267 
Example
3268 
.......
3269 
 
3270 
     (gdb)
3271 
     -target-file-delete remotefile
3272 
     ^done
3273 
     (gdb)
3274 
 
3275 

3276 
File: gdb.info,  Node: GDB/MI Miscellaneous Commands,  Prev: GDB/MI File Transfer Commands,  Up: GDB/MI
3277 
 
3278 
24.19 Miscellaneous GDB/MI Commands
3279 
===================================
3280 
 
3281 
The `-gdb-exit' Command
3282 
-----------------------
3283 
 
3284 
Synopsis
3285 
........
3286 
 
3287 
      -gdb-exit
3288 
 
3289 
   Exit GDB immediately.
3290 
 
3291 
GDB Command
3292 
...........
3293 
 
3294 
Approximately corresponds to `quit'.
3295 
 
3296 
Example
3297 
.......
3298 
 
3299 
     (gdb)
3300 
     -gdb-exit
3301 
     ^exit
3302 
 
3303 
The `-exec-abort' Command
3304 
-------------------------
3305 
 
3306 
Synopsis
3307 
........
3308 
 
3309 
      -exec-abort
3310 
 
3311 
   Kill the inferior running program.
3312 
 
3313 
GDB Command
3314 
...........
3315 
 
3316 
The corresponding GDB command is `kill'.
3317 
 
3318 
Example
3319 
.......
3320 
 
3321 
N.A.
3322 
 
3323 
The `-gdb-set' Command
3324 
----------------------
3325 
 
3326 
Synopsis
3327 
........
3328 
 
3329 
      -gdb-set
3330 
 
3331 
   Set an internal GDB variable.
3332 
 
3333 
GDB Command
3334 
...........
3335 
 
3336 
The corresponding GDB command is `set'.
3337 
 
3338 
Example
3339 
.......
3340 
 
3341 
     (gdb)
3342 
     -gdb-set $foo=3
3343 
     ^done
3344 
     (gdb)
3345 
 
3346 
The `-gdb-show' Command
3347 
-----------------------
3348 
 
3349 
Synopsis
3350 
........
3351 
 
3352 
      -gdb-show
3353 
 
3354 
   Show the current value of a GDB variable.
3355 
 
3356 
GDB Command
3357 
...........
3358 
 
3359 
The corresponding GDB command is `show'.
3360 
 
3361 
Example
3362 
.......
3363 
 
3364 
     (gdb)
3365 
     -gdb-show annotate
3366 
     ^done,value="0"
3367 
     (gdb)
3368 
 
3369 
The `-gdb-version' Command
3370 
--------------------------
3371 
 
3372 
Synopsis
3373 
........
3374 
 
3375 
      -gdb-version
3376 
 
3377 
   Show version information for GDB.  Used mostly in testing.
3378 
 
3379 
GDB Command
3380 
...........
3381 
 
3382 
The GDB equivalent is `show version'.  GDB by default shows this
3383 
information when you start an interactive session.
3384 
 
3385 
Example
3386 
.......
3387 
 
3388 
     (gdb)
3389 
     -gdb-version
3390 
     ~GNU gdb 5.2.1
3391 
     ~Copyright 2000 Free Software Foundation, Inc.
3392 
     ~GDB is free software, covered by the GNU General Public License, and
3393 
     ~you are welcome to change it and/or distribute copies of it under
3394 
     ~ certain conditions.
3395 
     ~Type "show copying" to see the conditions.
3396 
     ~There is absolutely no warranty for GDB.  Type "show warranty" for
3397 
     ~ details.
3398 
     ~This GDB was configured as
3399 
      "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
3400 
     ^done
3401 
     (gdb)
3402 
 
3403 
The `-list-features' Command
3404 
----------------------------
3405 
 
3406 
Returns a list of particular features of the MI protocol that this
3407 
version of gdb implements.  A feature can be a command, or a new field
3408 
in an output of some command, or even an important bugfix.  While a
3409 
frontend can sometimes detect presence of a feature at runtime, it is
3410 
easier to perform detection at debugger startup.
3411 
 
3412 
   The command returns a list of strings, with each string naming an
3413 
available feature.  Each returned string is just a name, it does not
3414 
have any internal structure.  The list of possible feature names is
3415 
given below.
3416 
 
3417 
   Example output:
3418 
 
3419 
     (gdb) -list-features
3420 
     ^done,result=["feature1","feature2"]
3421 
 
3422 
   The current list of features is:
3423 
 
3424 
   - `frozen-varobjs'--indicates presence of the `-var-set-frozen'
3425 
     command, as well as possible presense of the `frozen' field in the
3426 
     output of `-varobj-create'.
3427 
 
3428 
   - `pending-breakpoints'--indicates presence of the `-f' option to
3429 
     the `-break-insert' command.
3430 
 
3431 
 
3432 
The `-interpreter-exec' Command
3433 
-------------------------------
3434 
 
3435 
Synopsis
3436 
--------
3437 
 
3438 
     -interpreter-exec INTERPRETER COMMAND
3439 
 
3440 
   Execute the specified COMMAND in the given INTERPRETER.
3441 
 
3442 
GDB Command
3443 
-----------
3444 
 
3445 
The corresponding GDB command is `interpreter-exec'.
3446 
 
3447 
Example
3448 
-------
3449 
 
3450 
     (gdb)
3451 
     -interpreter-exec console "break main"
3452 
     &"During symbol reading, couldn't parse type; debugger out of date?.\n"
3453 
     &"During symbol reading, bad structure-type format.\n"
3454 
     ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
3455 
     ^done
3456 
     (gdb)
3457 
 
3458 
The `-inferior-tty-set' Command
3459 
-------------------------------
3460 
 
3461 
Synopsis
3462 
--------
3463 
 
3464 
     -inferior-tty-set /dev/pts/1
3465 
 
3466 
   Set terminal for future runs of the program being debugged.
3467 
 
3468 
GDB Command
3469 
-----------
3470 
 
3471 
The corresponding GDB command is `set inferior-tty' /dev/pts/1.
3472 
 
3473 
Example
3474 
-------
3475 
 
3476 
     (gdb)
3477 
     -inferior-tty-set /dev/pts/1
3478 
     ^done
3479 
     (gdb)
3480 
 
3481 
The `-inferior-tty-show' Command
3482 
--------------------------------
3483 
 
3484 
Synopsis
3485 
--------
3486 
 
3487 
     -inferior-tty-show
3488 
 
3489 
   Show terminal for future runs of program being debugged.
3490 
 
3491 
GDB Command
3492 
-----------
3493 
 
3494 
The corresponding GDB command is `show inferior-tty'.
3495 
 
3496 
Example
3497 
-------
3498 
 
3499 
     (gdb)
3500 
     -inferior-tty-set /dev/pts/1
3501 
     ^done
3502 
     (gdb)
3503 
     -inferior-tty-show
3504 
     ^done,inferior_tty_terminal="/dev/pts/1"
3505 
     (gdb)
3506 
 
3507 
The `-enable-timings' Command
3508 
-----------------------------
3509 
 
3510 
Synopsis
3511 
--------
3512 
 
3513 
     -enable-timings [yes | no]
3514 
 
3515 
   Toggle the printing of the wallclock, user and system times for an MI
3516 
command as a field in its output.  This command is to help frontend
3517 
developers optimize the performance of their code.  No argument is
3518 
equivalent to `yes'.
3519 
 
3520 
GDB Command
3521 
-----------
3522 
 
3523 
No equivalent.
3524 
 
3525 
Example
3526 
-------
3527 
 
3528 
     (gdb)
3529 
     -enable-timings
3530 
     ^done
3531 
     (gdb)
3532 
     -break-insert main
3533 
     ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
3534 
     addr="0x080484ed",func="main",file="myprog.c",
3535 
     fullname="/home/nickrob/myprog.c",line="73",times="0"},
3536 
     time={wallclock="0.05185",user="0.00800",system="0.00000"}
3537 
     (gdb)
3538 
     -enable-timings no
3539 
     ^done
3540 
     (gdb)
3541 
     -exec-run
3542 
     ^running
3543 
     (gdb)
3544 
     *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
3545 
     frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
3546 
     {name="argv",value="0xbfb60364"}],file="myprog.c",
3547 
     fullname="/home/nickrob/myprog.c",line="73"}
3548 
     (gdb)
3549 
 
3550 

3551 
File: gdb.info,  Node: Annotations,  Next: GDB Bugs,  Prev: GDB/MI,  Up: Top
3552 
 
3553 
25 GDB Annotations
3554 
******************
3555 
 
3556 
This chapter describes annotations in GDB.  Annotations were designed
3557 
to interface GDB to graphical user interfaces or other similar programs
3558 
which want to interact with GDB at a relatively high level.
3559 
 
3560 
   The annotation mechanism has largely been superseded by GDB/MI
3561 
(*note GDB/MI::).
3562 
 
3563 
* Menu:
3564 
 
3565 
* Annotations Overview::  What annotations are; the general syntax.
3566 
* Server Prefix::       Issuing a command without affecting user state.
3567 
* Prompting::           Annotations marking GDB's need for input.
3568 
* Errors::              Annotations for error messages.
3569 
* Invalidation::        Some annotations describe things now invalid.
3570 
* Annotations for Running::
3571 
                        Whether the program is running, how it stopped, etc.
3572 
* Source Annotations::  Annotations describing source code.
3573 
 
3574 

3575 
File: gdb.info,  Node: Annotations Overview,  Next: Server Prefix,  Up: Annotations
3576 
 
3577 
25.1 What is an Annotation?
3578 
===========================
3579 
 
3580 
Annotations start with a newline character, two `control-z' characters,
3581 
and the name of the annotation.  If there is no additional information
3582 
associated with this annotation, the name of the annotation is followed
3583 
immediately by a newline.  If there is additional information, the name
3584 
of the annotation is followed by a space, the additional information,
3585 
and a newline.  The additional information cannot contain newline
3586 
characters.
3587 
 
3588 
   Any output not beginning with a newline and two `control-z'
3589 
characters denotes literal output from GDB.  Currently there is no need
3590 
for GDB to output a newline followed by two `control-z' characters, but
3591 
if there was such a need, the annotations could be extended with an
3592 
`escape' annotation which means those three characters as output.
3593 
 
3594 
   The annotation LEVEL, which is specified using the `--annotate'
3595 
command line option (*note Mode Options::), controls how much
3596 
information GDB prints together with its prompt, values of expressions,
3597 
source lines, and other types of output.  Level 0 is for no
3598 
annotations, level 1 is for use when GDB is run as a subprocess of GNU
3599 
Emacs, level 3 is the maximum annotation suitable for programs that
3600 
control GDB, and level 2 annotations have been made obsolete (*note
3601 
Limitations of the Annotation Interface: (annotate)Limitations.).
3602 
 
3603 
`set annotate LEVEL'
3604 
     The GDB command `set annotate' sets the level of annotations to
3605 
     the specified LEVEL.
3606 
 
3607 
`show annotate'
3608 
     Show the current annotation level.
3609 
 
3610 
   This chapter describes level 3 annotations.
3611 
 
3612 
   A simple example of starting up GDB with annotations is:
3613 
 
3614 
     $ gdb --annotate=3
3615 
     GNU gdb 6.0
3616 
     Copyright 2003 Free Software Foundation, Inc.
3617 
     GDB is free software, covered by the GNU General Public License,
3618 
     and you are welcome to change it and/or distribute copies of it
3619 
     under certain conditions.
3620 
     Type "show copying" to see the conditions.
3621 
     There is absolutely no warranty for GDB.  Type "show warranty"
3622 
     for details.
3623 
     This GDB was configured as "i386-pc-linux-gnu"
3624 
 
3625 
     ^Z^Zpre-prompt
3626 
     (gdb)
3627 
     ^Z^Zprompt
3628 
     quit
3629 
 
3630 
     ^Z^Zpost-prompt
3631 
     $
3632 
 
3633 
   Here `quit' is input to GDB; the rest is output from GDB.  The three
3634 
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
3635 
annotations; the rest is output from GDB.
3636 
 
3637 

3638 
File: gdb.info,  Node: Server Prefix,  Next: Prompting,  Prev: Annotations Overview,  Up: Annotations
3639 
 
3640 
25.2 The Server Prefix
3641 
======================
3642 
 
3643 
If you prefix a command with `server ' then it will not affect the
3644 
command history, nor will it affect GDB's notion of which command to
3645 
repeat if  is pressed on a line by itself.  This means that
3646 
commands can be run behind a user's back by a front-end in a
3647 
transparent manner.
3648 
 
3649 
   The server prefix does not affect the recording of values into the
3650 
value history; to print a value without recording it into the value
3651 
history, use the `output' command instead of the `print' command.
3652 
 
3653 

3654 
File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Server Prefix,  Up: Annotations
3655 
 
3656 
25.3 Annotation for GDB Input
3657 
=============================
3658 
 
3659 
When GDB prompts for input, it annotates this fact so it is possible to
3660 
know when to send output, when the output from a given command is over,
3661 
etc.
3662 
 
3663 
   Different kinds of input each have a different "input type".  Each
3664 
input type has three annotations: a `pre-' annotation, which denotes
3665 
the beginning of any prompt which is being output, a plain annotation,
3666 
which denotes the end of the prompt, and then a `post-' annotation
3667 
which denotes the end of any echo which may (or may not) be associated
3668 
with the input.  For example, the `prompt' input type features the
3669 
following annotations:
3670 
 
3671 
     ^Z^Zpre-prompt
3672 
     ^Z^Zprompt
3673 
     ^Z^Zpost-prompt
3674 
 
3675 
   The input types are
3676 
 
3677 
`prompt'
3678 
     When GDB is prompting for a command (the main GDB prompt).
3679 
 
3680 
`commands'
3681 
     When GDB prompts for a set of commands, like in the `commands'
3682 
     command.  The annotations are repeated for each command which is
3683 
     input.
3684 
 
3685 
`overload-choice'
3686 
     When GDB wants the user to select between various overloaded
3687 
     functions.
3688 
 
3689 
`query'
3690 
     When GDB wants the user to confirm a potentially dangerous
3691 
     operation.
3692 
 
3693 
`prompt-for-continue'
3694 
     When GDB is asking the user to press return to continue.  Note:
3695 
     Don't expect this to work well; instead use `set height 0' to
3696 
     disable prompting.  This is because the counting of lines is buggy
3697 
     in the presence of annotations.
3698 
 
3699 

3700 
File: gdb.info,  Node: Errors,  Next: Invalidation,  Prev: Prompting,  Up: Annotations
3701 
 
3702 
25.4 Errors
3703 
===========
3704 
 
3705 
     ^Z^Zquit
3706 
 
3707 
   This annotation occurs right before GDB responds to an interrupt.
3708 
 
3709 
     ^Z^Zerror
3710 
 
3711 
   This annotation occurs right before GDB responds to an error.
3712 
 
3713 
   Quit and error annotations indicate that any annotations which GDB
3714 
was in the middle of may end abruptly.  For example, if a
3715 
`value-history-begin' annotation is followed by a `error', one cannot
3716 
expect to receive the matching `value-history-end'.  One cannot expect
3717 
not to receive it either, however; an error annotation does not
3718 
necessarily mean that GDB is immediately returning all the way to the
3719 
top level.
3720 
 
3721 
   A quit or error annotation may be preceded by
3722 
 
3723 
     ^Z^Zerror-begin
3724 
 
3725 
   Any output between that and the quit or error annotation is the error
3726 
message.
3727 
 
3728 
   Warning messages are not yet annotated.
3729 
 
3730 

3731 
File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Errors,  Up: Annotations
3732 
 
3733 
25.5 Invalidation Notices
3734 
=========================
3735 
 
3736 
The following annotations say that certain pieces of state may have
3737 
changed.
3738 
 
3739 
`^Z^Zframes-invalid'
3740 
     The frames (for example, output from the `backtrace' command) may
3741 
     have changed.
3742 
 
3743 
`^Z^Zbreakpoints-invalid'
3744 
     The breakpoints may have changed.  For example, the user just
3745 
     added or deleted a breakpoint.
3746 
 
3747 

3748 
File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations
3749 
 
3750 
25.6 Running the Program
3751 
========================
3752 
 
3753 
When the program starts executing due to a GDB command such as `step'
3754 
or `continue',
3755 
 
3756 
     ^Z^Zstarting
3757 
 
3758 
   is output.  When the program stops,
3759 
 
3760 
     ^Z^Zstopped
3761 
 
3762 
   is output.  Before the `stopped' annotation, a variety of
3763 
annotations describe how the program stopped.
3764 
 
3765 
`^Z^Zexited EXIT-STATUS'
3766 
     The program exited, and EXIT-STATUS is the exit status (zero for
3767 
     successful exit, otherwise nonzero).
3768 
 
3769 
`^Z^Zsignalled'
3770 
     The program exited with a signal.  After the `^Z^Zsignalled', the
3771 
     annotation continues:
3772 
 
3773 
          INTRO-TEXT
3774 
          ^Z^Zsignal-name
3775 
          NAME
3776 
          ^Z^Zsignal-name-end
3777 
          MIDDLE-TEXT
3778 
          ^Z^Zsignal-string
3779 
          STRING
3780 
          ^Z^Zsignal-string-end
3781 
          END-TEXT
3782 
 
3783 
     where NAME is the name of the signal, such as `SIGILL' or
3784 
     `SIGSEGV', and STRING is the explanation of the signal, such as
3785 
     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,
3786 
     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
3787 
     particular format.
3788 
 
3789 
`^Z^Zsignal'
3790 
     The syntax of this annotation is just like `signalled', but GDB is
3791 
     just saying that the program received the signal, not that it was
3792 
     terminated with it.
3793 
 
3794 
`^Z^Zbreakpoint NUMBER'
3795 
     The program hit breakpoint number NUMBER.
3796 
 
3797 
`^Z^Zwatchpoint NUMBER'
3798 
     The program hit watchpoint number NUMBER.
3799 
 
3800 

3801 
File: gdb.info,  Node: Source Annotations,  Prev: Annotations for Running,  Up: Annotations
3802 
 
3803 
25.7 Displaying Source
3804 
======================
3805 
 
3806 
The following annotation is used instead of displaying source code:
3807 
 
3808 
     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
3809 
 
3810 
   where FILENAME is an absolute file name indicating which source
3811 
file, LINE is the line number within that file (where 1 is the first
3812 
line in the file), CHARACTER is the character position within the file
3813 
(where 0 is the first character in the file) (for most debug formats
3814 
this will necessarily point to the beginning of a line), MIDDLE is
3815 
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
3816 
the beginning of the line, and ADDR is the address in the target
3817 
program associated with the source which is being displayed.  ADDR is
3818 
in the form `0x' followed by one or more lowercase hex digits (note
3819 
that this does not depend on the language).
3820 
 
3821 

3822 
File: gdb.info,  Node: GDB Bugs,  Next: Command Line Editing,  Prev: Annotations,  Up: Top
3823 
 
3824 
26 Reporting Bugs in GDB
3825 
************************
3826 
 
3827 
Your bug reports play an essential role in making GDB reliable.
3828 
 
3829 
   Reporting a bug may help you by bringing a solution to your problem,
3830 
or it may not.  But in any case the principal function of a bug report
3831 
is to help the entire community by making the next version of GDB work
3832 
better.  Bug reports are your contribution to the maintenance of GDB.
3833 
 
3834 
   In order for a bug report to serve its purpose, you must include the
3835 
information that enables us to fix the bug.
3836 
 
3837 
* Menu:
3838 
 
3839 
* Bug Criteria::                Have you found a bug?
3840 
* Bug Reporting::               How to report bugs
3841 
 
3842 

3843 
File: gdb.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: GDB Bugs
3844 
 
3845 
26.1 Have You Found a Bug?
3846 
==========================
3847 
 
3848 
If you are not sure whether you have found a bug, here are some
3849 
guidelines:
3850 
 
3851 
   * If the debugger gets a fatal signal, for any input whatever, that
3852 
     is a GDB bug.  Reliable debuggers never crash.
3853 
 
3854 
   * If GDB produces an error message for valid input, that is a bug.
3855 
     (Note that if you're cross debugging, the problem may also be
3856 
     somewhere in the connection to the target.)
3857 
 
3858 
   * If GDB does not produce an error message for invalid input, that
3859 
     is a bug.  However, you should note that your idea of "invalid
3860 
     input" might be our idea of "an extension" or "support for
3861 
     traditional practice".
3862 
 
3863 
   * If you are an experienced user of debugging tools, your suggestions
3864 
     for improvement of GDB are welcome in any case.
3865 
 
3866 

3867 
File: gdb.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: GDB Bugs
3868 
 
3869 
26.2 How to Report Bugs
3870 
=======================
3871 
 
3872 
A number of companies and individuals offer support for GNU products.
3873 
If you obtained GDB from a support organization, we recommend you
3874 
contact that organization first.
3875 
 
3876 
   You can find contact information for many support companies and
3877 
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
3878 
 
3879 
   In any event, we also recommend that you submit bug reports for GDB.
3880 
The preferred method is to submit them directly using GDB's Bugs web
3881 
page (http://www.gnu.org/software/gdb/bugs/).  Alternatively, the
3882 
e-mail gateway  can be used.
3883 
 
3884 
   *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
3885 
newsgroups.*  Most users of GDB do not want to receive bug reports.
3886 
Those that do have arranged to receive `bug-gdb'.
3887 
 
3888 
   The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
3889 
serves as a repeater.  The mailing list and the newsgroup carry exactly
3890 
the same messages.  Often people think of posting bug reports to the
3891 
newsgroup instead of mailing them.  This appears to work, but it has one
3892 
problem which can be crucial: a newsgroup posting often lacks a mail
3893 
path back to the sender.  Thus, if we need to ask for more information,
3894 
we may be unable to reach you.  For this reason, it is better to send
3895 
bug reports to the mailing list.
3896 
 
3897 
   The fundamental principle of reporting bugs usefully is this:
3898 
*report all the facts*.  If you are not sure whether to state a fact or
3899 
leave it out, state it!
3900 
 
3901 
   Often people omit facts because they think they know what causes the
3902 
problem and assume that some details do not matter.  Thus, you might
3903 
assume that the name of the variable you use in an example does not
3904 
matter.  Well, probably it does not, but one cannot be sure.  Perhaps
3905 
the bug is a stray memory reference which happens to fetch from the
3906 
location where that name is stored in memory; perhaps, if the name were
3907 
different, the contents of that location would fool the debugger into
3908 
doing the right thing despite the bug.  Play it safe and give a
3909 
specific, complete example.  That is the easiest thing for you to do,
3910 
and the most helpful.
3911 
 
3912 
   Keep in mind that the purpose of a bug report is to enable us to fix
3913 
the bug.  It may be that the bug has been reported previously, but
3914 
neither you nor we can know that unless your bug report is complete and
3915 
self-contained.
3916 
 
3917 
   Sometimes people give a few sketchy facts and ask, "Does this ring a
3918 
bell?"  Those bug reports are useless, and we urge everyone to _refuse
3919 
to respond to them_ except to chide the sender to report bugs properly.
3920 
 
3921 
   To enable us to fix the bug, you should include all these things:
3922 
 
3923 
   * The version of GDB.  GDB announces it if you start with no
3924 
     arguments; you can also print it at any time using `show version'.
3925 
 
3926 
     Without this, we will not know whether there is any point in
3927 
     looking for the bug in the current version of GDB.
3928 
 
3929 
   * The type of machine you are using, and the operating system name
3930 
     and version number.
3931 
 
3932 
   * What compiler (and its version) was used to compile GDB--e.g.
3933 
     "gcc-2.8.1".
3934 
 
3935 
   * What compiler (and its version) was used to compile the program
3936 
     you are debugging--e.g.  "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
3937 
     C Compiler".  For GCC, you can say `gcc --version' to get this
3938 
     information; for other compilers, see the documentation for those
3939 
     compilers.
3940 
 
3941 
   * The command arguments you gave the compiler to compile your
3942 
     example and observe the bug.  For example, did you use `-O'?  To
3943 
     guarantee you will not omit something important, list them all.  A
3944 
     copy of the Makefile (or the output from make) is sufficient.
3945 
 
3946 
     If we were to try to guess the arguments, we would probably guess
3947 
     wrong and then we might not encounter the bug.
3948 
 
3949 
   * A complete input script, and all necessary source files, that will
3950 
     reproduce the bug.
3951 
 
3952 
   * A description of what behavior you observe that you believe is
3953 
     incorrect.  For example, "It gets a fatal signal."
3954 
 
3955 
     Of course, if the bug is that GDB gets a fatal signal, then we
3956 
     will certainly notice it.  But if the bug is incorrect output, we
3957 
     might not notice unless it is glaringly wrong.  You might as well
3958 
     not give us a chance to make a mistake.
3959 
 
3960 
     Even if the problem you experience is a fatal signal, you should
3961 
     still say so explicitly.  Suppose something strange is going on,
3962 
     such as, your copy of GDB is out of synch, or you have encountered
3963 
     a bug in the C library on your system.  (This has happened!)  Your
3964 
     copy might crash and ours would not.  If you told us to expect a
3965 
     crash, then when ours fails to crash, we would know that the bug
3966 
     was not happening for us.  If you had not told us to expect a
3967 
     crash, then we would not be able to draw any conclusion from our
3968 
     observations.
3969 
 
3970 
     To collect all this information, you can use a session recording
3971 
     program such as `script', which is available on many Unix systems.
3972 
     Just run your GDB session inside `script' and then include the
3973 
     `typescript' file with your bug report.
3974 
 
3975 
     Another way to record a GDB session is to run GDB inside Emacs and
3976 
     then save the entire buffer to a file.
3977 
 
3978 
   * If you wish to suggest changes to the GDB source, send us context
3979 
     diffs.  If you even discuss something in the GDB source, refer to
3980 
     it by context, not by line number.
3981 
 
3982 
     The line numbers in our development sources will not match those
3983 
     in your sources.  Your line numbers would convey no useful
3984 
     information to us.
3985 
 
3986 
 
3987 
   Here are some things that are not necessary:
3988 
 
3989 
   * A description of the envelope of the bug.
3990 
 
3991 
     Often people who encounter a bug spend a lot of time investigating
3992 
     which changes to the input file will make the bug go away and which
3993 
     changes will not affect it.
3994 
 
3995 
     This is often time consuming and not very useful, because the way
3996 
     we will find the bug is by running a single example under the
3997 
     debugger with breakpoints, not by pure deduction from a series of
3998 
     examples.  We recommend that you save your time for something else.
3999 
 
4000 
     Of course, if you can find a simpler example to report _instead_
4001 
     of the original one, that is a convenience for us.  Errors in the
4002 
     output will be easier to spot, running under the debugger will take
4003 
     less time, and so on.
4004 
 
4005 
     However, simplification is not vital; if you do not want to do
4006 
     this, report the bug anyway and send us the entire test case you
4007 
     used.
4008 
 
4009 
   * A patch for the bug.
4010 
 
4011 
     A patch for the bug does help us if it is a good one.  But do not
4012 
     omit the necessary information, such as the test case, on the
4013 
     assumption that a patch is all we need.  We might see problems
4014 
     with your patch and decide to fix the problem another way, or we
4015 
     might not understand it at all.
4016 
 
4017 
     Sometimes with a program as complicated as GDB it is very hard to
4018 
     construct an example that will make the program follow a certain
4019 
     path through the code.  If you do not send us the example, we will
4020 
     not be able to construct one, so we will not be able to verify
4021 
     that the bug is fixed.
4022 
 
4023 
     And if we cannot understand what bug you are trying to fix, or why
4024 
     your patch should be an improvement, we will not install it.  A
4025 
     test case will help us to understand.
4026 
 
4027 
   * A guess about what the bug is or what it depends on.
4028 
 
4029 
     Such guesses are usually wrong.  Even we cannot guess right about
4030 
     such things without first using the debugger to find the facts.
4031 
 
4032 

4033 
File: gdb.info,  Node: Command Line Editing,  Next: Using History Interactively,  Prev: GDB Bugs,  Up: Top
4034 
 
4035 
27 Command Line Editing
4036 
***********************
4037 
 
4038 
This chapter describes the basic features of the GNU command line
4039 
editing interface.
4040 
 
4041 
* Menu:
4042 
 
4043 
* Introduction and Notation::   Notation used in this text.
4044 
* Readline Interaction::        The minimum set of commands for editing a line.
4045 
* Readline Init File::          Customizing Readline from a user's view.
4046 
* Bindable Readline Commands::  A description of most of the Readline commands
4047 
                                available for binding
4048 
* Readline vi Mode::            A short description of how to make Readline
4049 
                                behave like the vi editor.
4050 
 
4051 

4052 
File: gdb.info,  Node: Introduction and Notation,  Next: Readline Interaction,  Up: Command Line Editing
4053 
 
4054 
27.1 Introduction to Line Editing
4055 
=================================
4056 
 
4057 
The following paragraphs describe the notation used to represent
4058 
keystrokes.
4059 
 
4060 
   The text `C-k' is read as `Control-K' and describes the character
4061 
produced when the  key is pressed while the Control key is depressed.
4062 
 
4063 
   The text `M-k' is read as `Meta-K' and describes the character
4064 
produced when the Meta key (if you have one) is depressed, and the
4065 
key is pressed.  The Meta key is labeled  on many keyboards.  On
4066 
keyboards with two keys labeled  (usually to either side of the
4067 
space bar), the  on the left side is generally set to work as a
4068 
Meta key.  The  key on the right may also be configured to work as
4069 
a Meta key or may be configured as some other modifier, such as a
4070 
Compose key for typing accented characters.
4071 
 
4072 
   If you do not have a Meta or  key, or another key working as a
4073 
Meta key, the identical keystroke can be generated by typing
4074 
_first_, and then typing .  Either process is known as "metafying"
4075 
the  key.
4076 
 
4077 
   The text `M-C-k' is read as `Meta-Control-k' and describes the
4078 
character produced by "metafying" `C-k'.
4079 
 
4080 
   In addition, several keys have their own names.  Specifically,
4081 
, , , , , and  all stand for themselves
4082 
when seen in this text, or in an init file (*note Readline Init File::).
4083 
If your keyboard lacks a  key, typing  will produce the
4084 
desired character.  The  key may be labeled  or  on
4085 
some keyboards.
4086 
 
4087 

4088 
File: gdb.info,  Node: Readline Interaction,  Next: Readline Init File,  Prev: Introduction and Notation,  Up: Command Line Editing
4089 
 
4090 
27.2 Readline Interaction
4091 
=========================
4092 
 
4093 
Often during an interactive session you type in a long line of text,
4094 
only to notice that the first word on the line is misspelled.  The
4095 
Readline library gives you a set of commands for manipulating the text
4096 
as you type it in, allowing you to just fix your typo, and not forcing
4097 
you to retype the majority of the line.  Using these editing commands,
4098 
you move the cursor to the place that needs correction, and delete or
4099 
insert the text of the corrections.  Then, when you are satisfied with
4100 
the line, you simply press .  You do not have to be at the end of
4101 
the line to press ; the entire line is accepted regardless of the
4102 
location of the cursor within the line.
4103 
 
4104 
* Menu:
4105 
 
4106 
* Readline Bare Essentials::    The least you need to know about Readline.
4107 
* Readline Movement Commands::  Moving about the input line.
4108 
* Readline Killing Commands::   How to delete text, and how to get it back!
4109 
* Readline Arguments::          Giving numeric arguments to commands.
4110 
* Searching::                   Searching through previous lines.
4111 
 
4112 

4113 
File: gdb.info,  Node: Readline Bare Essentials,  Next: Readline Movement Commands,  Up: Readline Interaction
4114 
 
4115 
27.2.1 Readline Bare Essentials
4116 
-------------------------------
4117 
 
4118 
In order to enter characters into the line, simply type them.  The typed
4119 
character appears where the cursor was, and then the cursor moves one
4120 
space to the right.  If you mistype a character, you can use your erase
4121 
character to back up and delete the mistyped character.
4122 
 
4123 
   Sometimes you may mistype a character, and not notice the error
4124 
until you have typed several other characters.  In that case, you can
4125 
type `C-b' to move the cursor to the left, and then correct your
4126 
mistake.  Afterwards, you can move the cursor to the right with `C-f'.
4127 
 
4128 
   When you add text in the middle of a line, you will notice that
4129 
characters to the right of the cursor are `pushed over' to make room
4130 
for the text that you have inserted.  Likewise, when you delete text
4131 
behind the cursor, characters to the right of the cursor are `pulled
4132 
back' to fill in the blank space created by the removal of the text.  A
4133 
list of the bare essentials for editing the text of an input line
4134 
follows.
4135 
 
4136 
`C-b'
4137 
     Move back one character.
4138 
 
4139 
`C-f'
4140 
     Move forward one character.
4141 
 
4142 
 or
4143 
     Delete the character to the left of the cursor.
4144 
 
4145 
`C-d'
4146 
     Delete the character underneath the cursor.
4147 
 
4148 
Printing characters
4149 
     Insert the character into the line at the cursor.
4150 
 
4151 
`C-_' or `C-x C-u'
4152 
     Undo the last editing command.  You can undo all the way back to an
4153 
     empty line.
4154 
 
4155 
(Depending on your configuration, the  key be set to delete
4156 
the character to the left of the cursor and the  key set to delete
4157 
the character underneath the cursor, like `C-d', rather than the
4158 
character to the left of the cursor.)
4159 
 
4160 

4161 
File: gdb.info,  Node: Readline Movement Commands,  Next: Readline Killing Commands,  Prev: Readline Bare Essentials,  Up: Readline Interaction
4162 
 
4163 
27.2.2 Readline Movement Commands
4164 
---------------------------------
4165 
 
4166 
The above table describes the most basic keystrokes that you need in
4167 
order to do editing of the input line.  For your convenience, many
4168 
other commands have been added in addition to `C-b', `C-f', `C-d', and
4169 
.  Here are some commands for moving more rapidly about the line.
4170 
 
4171 
`C-a'
4172 
     Move to the start of the line.
4173 
 
4174 
`C-e'
4175 
     Move to the end of the line.
4176 
 
4177 
`M-f'
4178 
     Move forward a word, where a word is composed of letters and
4179 
     digits.
4180 
 
4181 
`M-b'
4182 
     Move backward a word.
4183 
 
4184 
`C-l'
4185 
     Clear the screen, reprinting the current line at the top.
4186 
 
4187 
   Notice how `C-f' moves forward a character, while `M-f' moves
4188 
forward a word.  It is a loose convention that control keystrokes
4189 
operate on characters while meta keystrokes operate on words.
4190 
 
4191 

4192 
File: gdb.info,  Node: Readline Killing Commands,  Next: Readline Arguments,  Prev: Readline Movement Commands,  Up: Readline Interaction
4193 
 
4194 
27.2.3 Readline Killing Commands
4195 
--------------------------------
4196 
 
4197 
"Killing" text means to delete the text from the line, but to save it
4198 
away for later use, usually by "yanking" (re-inserting) it back into
4199 
the line.  (`Cut' and `paste' are more recent jargon for `kill' and
4200 
`yank'.)
4201 
 
4202 
   If the description for a command says that it `kills' text, then you
4203 
can be sure that you can get the text back in a different (or the same)
4204 
place later.
4205 
 
4206 
   When you use a kill command, the text is saved in a "kill-ring".
4207 
Any number of consecutive kills save all of the killed text together, so
4208 
that when you yank it back, you get it all.  The kill ring is not line
4209 
specific; the text that you killed on a previously typed line is
4210 
available to be yanked back later, when you are typing another line.
4211 
 
4212 
   Here is the list of commands for killing text.
4213 
 
4214 
`C-k'
4215 
     Kill the text from the current cursor position to the end of the
4216 
     line.
4217 
 
4218 
`M-d'
4219 
     Kill from the cursor to the end of the current word, or, if between
4220 
     words, to the end of the next word.  Word boundaries are the same
4221 
     as those used by `M-f'.
4222 
 
4223 
`M-'
4224 
     Kill from the cursor the start of the current word, or, if between
4225 
     words, to the start of the previous word.  Word boundaries are the
4226 
     same as those used by `M-b'.
4227 
 
4228 
`C-w'
4229 
     Kill from the cursor to the previous whitespace.  This is
4230 
     different than `M-' because the word boundaries differ.
4231 
 
4232 
 
4233 
   Here is how to "yank" the text back into the line.  Yanking means to
4234 
copy the most-recently-killed text from the kill buffer.
4235 
 
4236 
`C-y'
4237 
     Yank the most recently killed text back into the buffer at the
4238 
     cursor.
4239 
 
4240 
`M-y'
4241 
     Rotate the kill-ring, and yank the new top.  You can only do this
4242 
     if the prior command is `C-y' or `M-y'.
4243 
 
4244 

4245 
File: gdb.info,  Node: Readline Arguments,  Next: Searching,  Prev: Readline Killing Commands,  Up: Readline Interaction
4246 
 
4247 
27.2.4 Readline Arguments
4248 
-------------------------
4249 
 
4250 
You can pass numeric arguments to Readline commands.  Sometimes the
4251 
argument acts as a repeat count, other times it is the sign of the
4252 
argument that is significant.  If you pass a negative argument to a
4253 
command which normally acts in a forward direction, that command will
4254 
act in a backward direction.  For example, to kill text back to the
4255 
start of the line, you might type `M-- C-k'.
4256 
 
4257 
   The general way to pass numeric arguments to a command is to type
4258 
meta digits before the command.  If the first `digit' typed is a minus
4259 
sign (`-'), then the sign of the argument will be negative.  Once you
4260 
have typed one meta digit to get the argument started, you can type the
4261 
remainder of the digits, and then the command.  For example, to give
4262 
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
4263 
will delete the next ten characters on the input line.
4264 
 
4265 

4266 
File: gdb.info,  Node: Searching,  Prev: Readline Arguments,  Up: Readline Interaction
4267 
 
4268 
27.2.5 Searching for Commands in the History
4269 
--------------------------------------------
4270 
 
4271 
Readline provides commands for searching through the command history
4272 
for lines containing a specified string.  There are two search modes:
4273 
"incremental" and "non-incremental".
4274 
 
4275 
   Incremental searches begin before the user has finished typing the
4276 
search string.  As each character of the search string is typed,
4277 
Readline displays the next entry from the history matching the string
4278 
typed so far.  An incremental search requires only as many characters
4279 
as needed to find the desired history entry.  To search backward in the
4280 
history for a particular string, type `C-r'.  Typing `C-s' searches
4281 
forward through the history.  The characters present in the value of
4282 
the `isearch-terminators' variable are used to terminate an incremental
4283 
search.  If that variable has not been assigned a value, the  and
4284 
`C-J' characters will terminate an incremental search.  `C-g' will
4285 
abort an incremental search and restore the original line.  When the
4286 
search is terminated, the history entry containing the search string
4287 
becomes the current line.
4288 
 
4289 
   To find other matching entries in the history list, type `C-r' or
4290 
`C-s' as appropriate.  This will search backward or forward in the
4291 
history for the next entry matching the search string typed so far.
4292 
Any other key sequence bound to a Readline command will terminate the
4293 
search and execute that command.  For instance, a  will terminate
4294 
the search and accept the line, thereby executing the command from the
4295 
history list.  A movement command will terminate the search, make the
4296 
last line found the current line, and begin editing.
4297 
 
4298 
   Readline remembers the last incremental search string.  If two
4299 
`C-r's are typed without any intervening characters defining a new
4300 
search string, any remembered search string is used.
4301 
 
4302 
   Non-incremental searches read the entire search string before
4303 
starting to search for matching history lines.  The search string may be
4304 
typed by the user or be part of the contents of the current line.
4305 
 
4306 

4307 
File: gdb.info,  Node: Readline Init File,  Next: Bindable Readline Commands,  Prev: Readline Interaction,  Up: Command Line Editing
4308 
 
4309 
27.3 Readline Init File
4310 
=======================
4311 
 
4312 
Although the Readline library comes with a set of Emacs-like
4313 
keybindings installed by default, it is possible to use a different set
4314 
of keybindings.  Any user can customize programs that use Readline by
4315 
putting commands in an "inputrc" file, conventionally in his home
4316 
directory.  The name of this file is taken from the value of the
4317 
environment variable `INPUTRC'.  If that variable is unset, the default
4318 
is `~/.inputrc'.
4319 
 
4320 
   When a program which uses the Readline library starts up, the init
4321 
file is read, and the key bindings are set.
4322 
 
4323 
   In addition, the `C-x C-r' command re-reads this init file, thus
4324 
incorporating any changes that you might have made to it.
4325 
 
4326 
* Menu:
4327 
 
4328 
* Readline Init File Syntax::   Syntax for the commands in the inputrc file.
4329 
 
4330 
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
4331 
 
4332 
* Sample Init File::            An example inputrc file.
4333 
 
4334 

4335 
File: gdb.info,  Node: Readline Init File Syntax,  Next: Conditional Init Constructs,  Up: Readline Init File
4336 
 
4337 
27.3.1 Readline Init File Syntax
4338 
--------------------------------
4339 
 
4340 
There are only a few basic constructs allowed in the Readline init
4341 
file.  Blank lines are ignored.  Lines beginning with a `#' are
4342 
comments.  Lines beginning with a `$' indicate conditional constructs
4343 
(*note Conditional Init Constructs::).  Other lines denote variable
4344 
settings and key bindings.
4345 
 
4346 
Variable Settings
4347 
     You can modify the run-time behavior of Readline by altering the
4348 
     values of variables in Readline using the `set' command within the
4349 
     init file.  The syntax is simple:
4350 
 
4351 
          set VARIABLE VALUE
4352 
 
4353 
     Here, for example, is how to change from the default Emacs-like
4354 
     key binding to use `vi' line editing commands:
4355 
 
4356 
          set editing-mode vi
4357 
 
4358 
     Variable names and values, where appropriate, are recognized
4359 
     without regard to case.  Unrecognized variable names are ignored.
4360 
 
4361 
     Boolean variables (those that can be set to on or off) are set to
4362 
     on if the value is null or empty, ON (case-insensitive), or 1.
4363 
     Any other value results in the variable being set to off.
4364 
 
4365 
     A great deal of run-time behavior is changeable with the following
4366 
     variables.
4367 
 
4368 
    `bell-style'
4369 
          Controls what happens when Readline wants to ring the
4370 
          terminal bell.  If set to `none', Readline never rings the
4371 
          bell.  If set to `visible', Readline uses a visible bell if
4372 
          one is available.  If set to `audible' (the default),
4373 
          Readline attempts to ring the terminal's bell.
4374 
 
4375 
    `bind-tty-special-chars'
4376 
          If set to `on', Readline attempts to bind the control
4377 
          characters treated specially by the kernel's terminal driver
4378 
          to their Readline equivalents.
4379 
 
4380 
    `comment-begin'
4381 
          The string to insert at the beginning of the line when the
4382 
          `insert-comment' command is executed.  The default value is
4383 
          `"#"'.
4384 
 
4385 
    `completion-ignore-case'
4386 
          If set to `on', Readline performs filename matching and
4387 
          completion in a case-insensitive fashion.  The default value
4388 
          is `off'.
4389 
 
4390 
    `completion-query-items'
4391 
          The number of possible completions that determines when the
4392 
          user is asked whether the list of possibilities should be
4393 
          displayed.  If the number of possible completions is greater
4394 
          than this value, Readline will ask the user whether or not he
4395 
          wishes to view them; otherwise, they are simply listed.  This
4396 
          variable must be set to an integer value greater than or
4397 
          equal to 0.  A negative value means Readline should never ask.
4398 
          The default limit is `100'.
4399 
 
4400 
    `convert-meta'
4401 
          If set to `on', Readline will convert characters with the
4402 
          eighth bit set to an ASCII key sequence by stripping the
4403 
          eighth bit and prefixing an  character, converting them
4404 
          to a meta-prefixed key sequence.  The default value is `on'.
4405 
 
4406 
    `disable-completion'
4407 
          If set to `On', Readline will inhibit word completion.
4408 
          Completion  characters will be inserted into the line as if
4409 
          they had been mapped to `self-insert'.  The default is `off'.
4410 
 
4411 
    `editing-mode'
4412 
          The `editing-mode' variable controls which default set of key
4413 
          bindings is used.  By default, Readline starts up in Emacs
4414 
          editing mode, where the keystrokes are most similar to Emacs.
4415 
          This variable can be set to either `emacs' or `vi'.
4416 
 
4417 
    `enable-keypad'
4418 
          When set to `on', Readline will try to enable the application
4419 
          keypad when it is called.  Some systems need this to enable
4420 
          the arrow keys.  The default is `off'.
4421 
 
4422 
    `expand-tilde'
4423 
          If set to `on', tilde expansion is performed when Readline
4424 
          attempts word completion.  The default is `off'.
4425 
 
4426 
    `history-preserve-point'
4427 
          If set to `on', the history code attempts to place point at
4428 
          the same location on each history line retrieved with
4429 
          `previous-history' or `next-history'.  The default is `off'.
4430 
 
4431 
    `horizontal-scroll-mode'
4432 
          This variable can be set to either `on' or `off'.  Setting it
4433 
          to `on' means that the text of the lines being edited will
4434 
          scroll horizontally on a single screen line when they are
4435 
          longer than the width of the screen, instead of wrapping onto
4436 
          a new screen line.  By default, this variable is set to `off'.
4437 
 
4438 
    `input-meta'
4439 
          If set to `on', Readline will enable eight-bit input (it will
4440 
          not clear the eighth bit in the characters it reads),
4441 
          regardless of what the terminal claims it can support.  The
4442 
          default value is `off'.  The name `meta-flag' is a synonym
4443 
          for this variable.
4444 
 
4445 
    `isearch-terminators'
4446 
          The string of characters that should terminate an incremental
4447 
          search without subsequently executing the character as a
4448 
          command (*note Searching::).  If this variable has not been
4449 
          given a value, the characters  and `C-J' will terminate
4450 
          an incremental search.
4451 
 
4452 
    `keymap'
4453 
          Sets Readline's idea of the current keymap for key binding
4454 
          commands.  Acceptable `keymap' names are `emacs',
4455 
          `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
4456 
          `vi-command', and `vi-insert'.  `vi' is equivalent to
4457 
          `vi-command'; `emacs' is equivalent to `emacs-standard'.  The
4458 
          default value is `emacs'.  The value of the `editing-mode'
4459 
          variable also affects the default keymap.
4460 
 
4461 
    `mark-directories'
4462 
          If set to `on', completed directory names have a slash
4463 
          appended.  The default is `on'.
4464 
 
4465 
    `mark-modified-lines'
4466 
          This variable, when set to `on', causes Readline to display an
4467 
          asterisk (`*') at the start of history lines which have been
4468 
          modified.  This variable is `off' by default.
4469 
 
4470 
    `mark-symlinked-directories'
4471 
          If set to `on', completed names which are symbolic links to
4472 
          directories have a slash appended (subject to the value of
4473 
          `mark-directories').  The default is `off'.
4474 
 
4475 
    `match-hidden-files'
4476 
          This variable, when set to `on', causes Readline to match
4477 
          files whose names begin with a `.' (hidden files) when
4478 
          performing filename completion, unless the leading `.' is
4479 
          supplied by the user in the filename to be completed.  This
4480 
          variable is `on' by default.
4481 
 
4482 
    `output-meta'
4483 
          If set to `on', Readline will display characters with the
4484 
          eighth bit set directly rather than as a meta-prefixed escape
4485 
          sequence.  The default is `off'.
4486 
 
4487 
    `page-completions'
4488 
          If set to `on', Readline uses an internal `more'-like pager
4489 
          to display a screenful of possible completions at a time.
4490 
          This variable is `on' by default.
4491 
 
4492 
    `print-completions-horizontally'
4493 
          If set to `on', Readline will display completions with matches
4494 
          sorted horizontally in alphabetical order, rather than down
4495 
          the screen.  The default is `off'.
4496 
 
4497 
    `show-all-if-ambiguous'
4498 
          This alters the default behavior of the completion functions.
4499 
          If set to `on', words which have more than one possible
4500 
          completion cause the matches to be listed immediately instead
4501 
          of ringing the bell.  The default value is `off'.
4502 
 
4503 
    `show-all-if-unmodified'
4504 
          This alters the default behavior of the completion functions
4505 
          in a fashion similar to SHOW-ALL-IF-AMBIGUOUS.  If set to
4506 
          `on', words which have more than one possible completion
4507 
          without any possible partial completion (the possible
4508 
          completions don't share a common prefix) cause the matches to
4509 
          be listed immediately instead of ringing the bell.  The
4510 
          default value is `off'.
4511 
 
4512 
    `visible-stats'
4513 
          If set to `on', a character denoting a file's type is
4514 
          appended to the filename when listing possible completions.
4515 
          The default is `off'.
4516 
 
4517 
 
4518 
Key Bindings
4519 
     The syntax for controlling key bindings in the init file is
4520 
     simple.  First you need to find the name of the command that you
4521 
     want to change.  The following sections contain tables of the
4522 
     command name, the default keybinding, if any, and a short
4523 
     description of what the command does.
4524 
 
4525 
     Once you know the name of the command, simply place on a line in
4526 
     the init file the name of the key you wish to bind the command to,
4527 
     a colon, and then the name of the command.  The name of the key
4528 
     can be expressed in different ways, depending on what you find most
4529 
     comfortable.
4530 
 
4531 
     In addition to command names, readline allows keys to be bound to
4532 
     a string that is inserted when the key is pressed (a MACRO).
4533 
 
4534 
    KEYNAME: FUNCTION-NAME or MACRO
4535 
          KEYNAME is the name of a key spelled out in English.  For
4536 
          example:
4537 
               Control-u: universal-argument
4538 
               Meta-Rubout: backward-kill-word
4539 
               Control-o: "> output"
4540 
 
4541 
          In the above example, `C-u' is bound to the function
4542 
          `universal-argument', `M-DEL' is bound to the function
4543 
          `backward-kill-word', and `C-o' is bound to run the macro
4544 
          expressed on the right hand side (that is, to insert the text
4545 
          `> output' into the line).
4546 
 
4547 
          A number of symbolic character names are recognized while
4548 
          processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
4549 
          NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
4550 
 
4551 
    "KEYSEQ": FUNCTION-NAME or MACRO
4552 
          KEYSEQ differs from KEYNAME above in that strings denoting an
4553 
          entire key sequence can be specified, by placing the key
4554 
          sequence in double quotes.  Some GNU Emacs style key escapes
4555 
          can be used, as in the following example, but the special
4556 
          character names are not recognized.
4557 
 
4558 
               "\C-u": universal-argument
4559 
               "\C-x\C-r": re-read-init-file
4560 
               "\e[11~": "Function Key 1"
4561 
 
4562 
          In the above example, `C-u' is again bound to the function
4563 
          `universal-argument' (just as it was in the first example),
4564 
          `C-x C-r' is bound to the function `re-read-init-file', and
4565 
          ` <[> <1> <1> <~>' is bound to insert the text `Function
4566 
          Key 1'.
4567 
 
4568 
 
4569 
     The following GNU Emacs style escape sequences are available when
4570 
     specifying key sequences:
4571 
 
4572 
    `\C-'
4573 
          control prefix
4574 
 
4575 
    `\M-'
4576 
          meta prefix
4577 
 
4578 
    `\e'
4579 
          an escape character
4580 
 
4581 
    `\\'
4582 
          backslash
4583 
 
4584 
    `\"'
4585 
          <">, a double quotation mark
4586 
 
4587 
    `\''
4588 
          <'>, a single quote or apostrophe
4589 
 
4590 
     In addition to the GNU Emacs style escape sequences, a second set
4591 
     of backslash escapes is available:
4592 
 
4593 
    `\a'
4594 
          alert (bell)
4595 
 
4596 
    `\b'
4597 
          backspace
4598 
 
4599 
    `\d'
4600 
          delete
4601 
 
4602 
    `\f'
4603 
          form feed
4604 
 
4605 
    `\n'
4606 
          newline
4607 
 
4608 
    `\r'
4609 
          carriage return
4610 
 
4611 
    `\t'
4612 
          horizontal tab
4613 
 
4614 
    `\v'
4615 
          vertical tab
4616 
 
4617 
    `\NNN'
4618 
          the eight-bit character whose value is the octal value NNN
4619 
          (one to three digits)
4620 
 
4621 
    `\xHH'
4622 
          the eight-bit character whose value is the hexadecimal value
4623 
          HH (one or two hex digits)
4624 
 
4625 
     When entering the text of a macro, single or double quotes must be
4626 
     used to indicate a macro definition.  Unquoted text is assumed to
4627 
     be a function name.  In the macro body, the backslash escapes
4628 
     described above are expanded.  Backslash will quote any other
4629 
     character in the macro text, including `"' and `''.  For example,
4630 
     the following binding will make `C-x \' insert a single `\' into
4631 
     the line:
4632 
          "\C-x\\": "\\"
4633 
 
4634 
 
4635 

4636 
File: gdb.info,  Node: Conditional Init Constructs,  Next: Sample Init File,  Prev: Readline Init File Syntax,  Up: Readline Init File
4637 
 
4638 
27.3.2 Conditional Init Constructs
4639 
----------------------------------
4640 
 
4641 
Readline implements a facility similar in spirit to the conditional
4642 
compilation features of the C preprocessor which allows key bindings
4643 
and variable settings to be performed as the result of tests.  There
4644 
are four parser directives used.
4645 
 
4646 
`$if'
4647 
     The `$if' construct allows bindings to be made based on the
4648 
     editing mode, the terminal being used, or the application using
4649 
     Readline.  The text of the test extends to the end of the line; no
4650 
     characters are required to isolate it.
4651 
 
4652 
    `mode'
4653 
          The `mode=' form of the `$if' directive is used to test
4654 
          whether Readline is in `emacs' or `vi' mode.  This may be
4655 
          used in conjunction with the `set keymap' command, for
4656 
          instance, to set bindings in the `emacs-standard' and
4657 
          `emacs-ctlx' keymaps only if Readline is starting out in
4658 
          `emacs' mode.
4659 
 
4660 
    `term'
4661 
          The `term=' form may be used to include terminal-specific key
4662 
          bindings, perhaps to bind the key sequences output by the
4663 
          terminal's function keys.  The word on the right side of the
4664 
          `=' is tested against both the full name of the terminal and
4665 
          the portion of the terminal name before the first `-'.  This
4666 
          allows `sun' to match both `sun' and `sun-cmd', for instance.
4667 
 
4668 
    `application'
4669 
          The APPLICATION construct is used to include
4670 
          application-specific settings.  Each program using the
4671 
          Readline library sets the APPLICATION NAME, and you can test
4672 
          for a particular value.  This could be used to bind key
4673 
          sequences to functions useful for a specific program.  For
4674 
          instance, the following command adds a key sequence that
4675 
          quotes the current or previous word in Bash:
4676 
               $if Bash
4677 
               # Quote the current or previous word
4678 
               "\C-xq": "\eb\"\ef\""
4679 
               $endif
4680 
 
4681 
`$endif'
4682 
     This command, as seen in the previous example, terminates an `$if'
4683 
     command.
4684 
 
4685 
`$else'
4686 
     Commands in this branch of the `$if' directive are executed if the
4687 
     test fails.
4688 
 
4689 
`$include'
4690 
     This directive takes a single filename as an argument and reads
4691 
     commands and bindings from that file.  For example, the following
4692 
     directive reads from `/etc/inputrc':
4693 
          $include /etc/inputrc
4694 
 
4695 

4696 
File: gdb.info,  Node: Sample Init File,  Prev: Conditional Init Constructs,  Up: Readline Init File
4697 
 
4698 
27.3.3 Sample Init File
4699 
-----------------------
4700 
 
4701 
Here is an example of an INPUTRC file.  This illustrates key binding,
4702 
variable assignment, and conditional syntax.
4703 
 
4704 
 
4705 
     # This file controls the behaviour of line input editing for
4706 
     # programs that use the GNU Readline library.  Existing
4707 
     # programs include FTP, Bash, and GDB.
4708 
     #
4709 
     # You can re-read the inputrc file with C-x C-r.
4710 
     # Lines beginning with '#' are comments.
4711 
     #
4712 
     # First, include any systemwide bindings and variable
4713 
     # assignments from /etc/Inputrc
4714 
     $include /etc/Inputrc
4715 
 
4716 
     #
4717 
     # Set various bindings for emacs mode.
4718 
 
4719 
     set editing-mode emacs
4720 
 
4721 
     $if mode=emacs
4722 
 
4723 
     Meta-Control-h:    backward-kill-word      Text after the function name is ignored
4724 
 
4725 
     #
4726 
     # Arrow keys in keypad mode
4727 
     #
4728 
     #"\M-OD":        backward-char
4729 
     #"\M-OC":        forward-char
4730 
     #"\M-OA":        previous-history
4731 
     #"\M-OB":        next-history
4732 
     #
4733 
     # Arrow keys in ANSI mode
4734 
     #
4735 
     "\M-[D":        backward-char
4736 
     "\M-[C":        forward-char
4737 
     "\M-[A":        previous-history
4738 
     "\M-[B":        next-history
4739 
     #
4740 
     # Arrow keys in 8 bit keypad mode
4741 
     #
4742 
     #"\M-\C-OD":       backward-char
4743 
     #"\M-\C-OC":       forward-char
4744 
     #"\M-\C-OA":       previous-history
4745 
     #"\M-\C-OB":       next-history
4746 
     #
4747 
     # Arrow keys in 8 bit ANSI mode
4748 
     #
4749 
     #"\M-\C-[D":       backward-char
4750 
     #"\M-\C-[C":       forward-char
4751 
     #"\M-\C-[A":       previous-history
4752 
     #"\M-\C-[B":       next-history
4753 
 
4754 
     C-q: quoted-insert
4755 
 
4756 
     $endif
4757 
 
4758 
     # An old-style binding.  This happens to be the default.
4759 
     TAB: complete
4760 
 
4761 
     # Macros that are convenient for shell interaction
4762 
     $if Bash
4763 
     # edit the path
4764 
     "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
4765 
     # prepare to type a quoted word --
4766 
     # insert open and close double quotes
4767 
     # and move to just after the open quote
4768 
     "\C-x\"": "\"\"\C-b"
4769 
     # insert a backslash (testing backslash escapes
4770 
     # in sequences and macros)
4771 
     "\C-x\\": "\\"
4772 
     # Quote the current or previous word
4773 
     "\C-xq": "\eb\"\ef\""
4774 
     # Add a binding to refresh the line, which is unbound
4775 
     "\C-xr": redraw-current-line
4776 
     # Edit variable on current line.
4777 
     "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
4778 
     $endif
4779 
 
4780 
     # use a visible bell if one is available
4781 
     set bell-style visible
4782 
 
4783 
     # don't strip characters to 7 bits when reading
4784 
     set input-meta on
4785 
 
4786 
     # allow iso-latin1 characters to be inserted rather
4787 
     # than converted to prefix-meta sequences
4788 
     set convert-meta off
4789 
 
4790 
     # display characters with the eighth bit set directly
4791 
     # rather than as meta-prefixed characters
4792 
     set output-meta on
4793 
 
4794 
     # if there are more than 150 possible completions for
4795 
     # a word, ask the user if he wants to see all of them
4796 
     set completion-query-items 150
4797 
 
4798 
     # For FTP
4799 
     $if Ftp
4800 
     "\C-xg": "get \M-?"
4801 
     "\C-xt": "put \M-?"
4802 
     "\M-.": yank-last-arg
4803 
     $endif
4804 
 
4805 

4806 
File: gdb.info,  Node: Bindable Readline Commands,  Next: Readline vi Mode,  Prev: Readline Init File,  Up: Command Line Editing
4807 
 
4808 
27.4 Bindable Readline Commands
4809 
===============================
4810 
 
4811 
* Menu:
4812 
 
4813 
* Commands For Moving::         Moving about the line.
4814 
* Commands For History::        Getting at previous lines.
4815 
* Commands For Text::           Commands for changing text.
4816 
* Commands For Killing::        Commands for killing and yanking.
4817 
* Numeric Arguments::           Specifying numeric arguments, repeat counts.
4818 
* Commands For Completion::     Getting Readline to do the typing for you.
4819 
* Keyboard Macros::             Saving and re-executing typed characters
4820 
* Miscellaneous Commands::      Other miscellaneous commands.
4821 
 
4822 
   This section describes Readline commands that may be bound to key
4823 
sequences.  Command names without an accompanying key sequence are
4824 
unbound by default.
4825 
 
4826 
   In the following descriptions, "point" refers to the current cursor
4827 
position, and "mark" refers to a cursor position saved by the
4828 
`set-mark' command.  The text between the point and mark is referred to
4829 
as the "region".
4830 
 
4831 

4832 
File: gdb.info,  Node: Commands For Moving,  Next: Commands For History,  Up: Bindable Readline Commands
4833 
 
4834 
27.4.1 Commands For Moving
4835 
--------------------------
4836 
 
4837 
`beginning-of-line (C-a)'
4838 
     Move to the start of the current line.
4839 
 
4840 
`end-of-line (C-e)'
4841 
     Move to the end of the line.
4842 
 
4843 
`forward-char (C-f)'
4844 
     Move forward a character.
4845 
 
4846 
`backward-char (C-b)'
4847 
     Move back a character.
4848 
 
4849 
`forward-word (M-f)'
4850 
     Move forward to the end of the next word.  Words are composed of
4851 
     letters and digits.
4852 
 
4853 
`backward-word (M-b)'
4854 
     Move back to the start of the current or previous word.  Words are
4855 
     composed of letters and digits.
4856 
 
4857 
`clear-screen (C-l)'
4858 
     Clear the screen and redraw the current line, leaving the current
4859 
     line at the top of the screen.
4860 
 
4861 
`redraw-current-line ()'
4862 
     Refresh the current line.  By default, this is unbound.
4863 
 
4864 
 
4865 

4866 
File: gdb.info,  Node: Commands For History,  Next: Commands For Text,  Prev: Commands For Moving,  Up: Bindable Readline Commands
4867 
 
4868 
27.4.2 Commands For Manipulating The History
4869 
--------------------------------------------
4870 
 
4871 
`accept-line (Newline or Return)'
4872 
     Accept the line regardless of where the cursor is.  If this line is
4873 
     non-empty, it may be added to the history list for future recall
4874 
     with `add_history()'.  If this line is a modified history line,
4875 
     the history line is restored to its original state.
4876 
 
4877 
`previous-history (C-p)'
4878 
     Move `back' through the history list, fetching the previous
4879 
     command.
4880 
 
4881 
`next-history (C-n)'
4882 
     Move `forward' through the history list, fetching the next command.
4883 
 
4884 
`beginning-of-history (M-<)'
4885 
     Move to the first line in the history.
4886 
 
4887 
`end-of-history (M->)'
4888 
     Move to the end of the input history, i.e., the line currently
4889 
     being entered.
4890 
 
4891 
`reverse-search-history (C-r)'
4892 
     Search backward starting at the current line and moving `up'
4893 
     through the history as necessary.  This is an incremental search.
4894 
 
4895 
`forward-search-history (C-s)'
4896 
     Search forward starting at the current line and moving `down'
4897 
     through the the history as necessary.  This is an incremental
4898 
     search.
4899 
 
4900 
`non-incremental-reverse-search-history (M-p)'
4901 
     Search backward starting at the current line and moving `up'
4902 
     through the history as necessary using a non-incremental search
4903 
     for a string supplied by the user.
4904 
 
4905 
`non-incremental-forward-search-history (M-n)'
4906 
     Search forward starting at the current line and moving `down'
4907 
     through the the history as necessary using a non-incremental search
4908 
     for a string supplied by the user.
4909 
 
4910 
`history-search-forward ()'
4911 
     Search forward through the history for the string of characters
4912 
     between the start of the current line and the point.  This is a
4913 
     non-incremental search.  By default, this command is unbound.
4914 
 
4915 
`history-search-backward ()'
4916 
     Search backward through the history for the string of characters
4917 
     between the start of the current line and the point.  This is a
4918 
     non-incremental search.  By default, this command is unbound.
4919 
 
4920 
`yank-nth-arg (M-C-y)'
4921 
     Insert the first argument to the previous command (usually the
4922 
     second word on the previous line) at point.  With an argument N,
4923 
     insert the Nth word from the previous command (the words in the
4924 
     previous command begin with word 0).  A negative argument inserts
4925 
     the Nth word from the end of the previous command.  Once the
4926 
     argument N is computed, the argument is extracted as if the `!N'
4927 
     history expansion had been specified.
4928 
 
4929 
`yank-last-arg (M-. or M-_)'
4930 
     Insert last argument to the previous command (the last word of the
4931 
     previous history entry).  With an argument, behave exactly like
4932 
     `yank-nth-arg'.  Successive calls to `yank-last-arg' move back
4933 
     through the history list, inserting the last argument of each line
4934 
     in turn.  The history expansion facilities are used to extract the
4935 
     last argument, as if the `!$' history expansion had been specified.
4936 
 
4937 
 
4938 

4939 
File: gdb.info,  Node: Commands For Text,  Next: Commands For Killing,  Prev: Commands For History,  Up: Bindable Readline Commands
4940 
 
4941 
27.4.3 Commands For Changing Text
4942 
---------------------------------
4943 
 
4944 
`delete-char (C-d)'
4945 
     Delete the character at point.  If point is at the beginning of
4946 
     the line, there are no characters in the line, and the last
4947 
     character typed was not bound to `delete-char', then return EOF.
4948 
 
4949 
`backward-delete-char (Rubout)'
4950 
     Delete the character behind the cursor.  A numeric argument means
4951 
     to kill the characters instead of deleting them.
4952 
 
4953 
`forward-backward-delete-char ()'
4954 
     Delete the character under the cursor, unless the cursor is at the
4955 
     end of the line, in which case the character behind the cursor is
4956 
     deleted.  By default, this is not bound to a key.
4957 
 
4958 
`quoted-insert (C-q or C-v)'
4959 
     Add the next character typed to the line verbatim.  This is how to
4960 
     insert key sequences like `C-q', for example.
4961 
 
4962 
`tab-insert (M-)'
4963 
     Insert a tab character.
4964 
 
4965 
`self-insert (a, b, A, 1, !, ...)'
4966 
     Insert yourself.
4967 
 
4968 
`transpose-chars (C-t)'
4969 
     Drag the character before the cursor forward over the character at
4970 
     the cursor, moving the cursor forward as well.  If the insertion
4971 
     point is at the end of the line, then this transposes the last two
4972 
     characters of the line.  Negative arguments have no effect.
4973 
 
4974 
`transpose-words (M-t)'
4975 
     Drag the word before point past the word after point, moving point
4976 
     past that word as well.  If the insertion point is at the end of
4977 
     the line, this transposes the last two words on the line.
4978 
 
4979 
`upcase-word (M-u)'
4980 
     Uppercase the current (or following) word.  With a negative
4981 
     argument, uppercase the previous word, but do not move the cursor.
4982 
 
4983 
`downcase-word (M-l)'
4984 
     Lowercase the current (or following) word.  With a negative
4985 
     argument, lowercase the previous word, but do not move the cursor.
4986 
 
4987 
`capitalize-word (M-c)'
4988 
     Capitalize the current (or following) word.  With a negative
4989 
     argument, capitalize the previous word, but do not move the cursor.
4990 
 
4991 
`overwrite-mode ()'
4992 
     Toggle overwrite mode.  With an explicit positive numeric argument,
4993 
     switches to overwrite mode.  With an explicit non-positive numeric
4994 
     argument, switches to insert mode.  This command affects only
4995 
     `emacs' mode; `vi' mode does overwrite differently.  Each call to
4996 
     `readline()' starts in insert mode.
4997 
 
4998 
     In overwrite mode, characters bound to `self-insert' replace the
4999 
     text at point rather than pushing the text to the right.
5000 
     Characters bound to `backward-delete-char' replace the character
5001 
     before point with a space.
5002 
 
5003 
     By default, this command is unbound.
5004 
 
5005 
 
5006 

5007 
File: gdb.info,  Node: Commands For Killing,  Next: Numeric Arguments,  Prev: Commands For Text,  Up: Bindable Readline Commands
5008 
 
5009 
27.4.4 Killing And Yanking
5010 
--------------------------
5011 
 
5012 
`kill-line (C-k)'
5013 
     Kill the text from point to the end of the line.
5014 
 
5015 
`backward-kill-line (C-x Rubout)'
5016 
     Kill backward to the beginning of the line.
5017 
 
5018 
`unix-line-discard (C-u)'
5019 
     Kill backward from the cursor to the beginning of the current line.
5020 
 
5021 
`kill-whole-line ()'
5022 
     Kill all characters on the current line, no matter where point is.
5023 
     By default, this is unbound.
5024 
 
5025 
`kill-word (M-d)'
5026 
     Kill from point to the end of the current word, or if between
5027 
     words, to the end of the next word.  Word boundaries are the same
5028 
     as `forward-word'.
5029 
 
5030 
`backward-kill-word (M-)'
5031 
     Kill the word behind point.  Word boundaries are the same as
5032 
     `backward-word'.
5033 
 
5034 
`unix-word-rubout (C-w)'
5035 
     Kill the word behind point, using white space as a word boundary.
5036 
     The killed text is saved on the kill-ring.
5037 
 
5038 
`unix-filename-rubout ()'
5039 
     Kill the word behind point, using white space and the slash
5040 
     character as the word boundaries.  The killed text is saved on the
5041 
     kill-ring.
5042 
 
5043 
`delete-horizontal-space ()'
5044 
     Delete all spaces and tabs around point.  By default, this is
5045 
     unbound.
5046 
 
5047 
`kill-region ()'
5048 
     Kill the text in the current region.  By default, this command is
5049 
     unbound.
5050 
 
5051 
`copy-region-as-kill ()'
5052 
     Copy the text in the region to the kill buffer, so it can be yanked
5053 
     right away.  By default, this command is unbound.
5054 
 
5055 
`copy-backward-word ()'
5056 
     Copy the word before point to the kill buffer.  The word
5057 
     boundaries are the same as `backward-word'.  By default, this
5058 
     command is unbound.
5059 
 
5060 
`copy-forward-word ()'
5061 
     Copy the word following point to the kill buffer.  The word
5062 
     boundaries are the same as `forward-word'.  By default, this
5063 
     command is unbound.
5064 
 
5065 
`yank (C-y)'
5066 
     Yank the top of the kill ring into the buffer at point.
5067 
 
5068 
`yank-pop (M-y)'
5069 
     Rotate the kill-ring, and yank the new top.  You can only do this
5070 
     if the prior command is `yank' or `yank-pop'.
5071 
 
5072 

5073 
File: gdb.info,  Node: Numeric Arguments,  Next: Commands For Completion,  Prev: Commands For Killing,  Up: Bindable Readline Commands
5074 
 
5075 
27.4.5 Specifying Numeric Arguments
5076 
-----------------------------------
5077 
 
5078 
`digit-argument (M-0, M-1, ... M--)'
5079 
     Add this digit to the argument already accumulating, or start a new
5080 
     argument.  `M--' starts a negative argument.
5081 
 
5082 
`universal-argument ()'
5083 
     This is another way to specify an argument.  If this command is
5084 
     followed by one or more digits, optionally with a leading minus
5085 
     sign, those digits define the argument.  If the command is
5086 
     followed by digits, executing `universal-argument' again ends the
5087 
     numeric argument, but is otherwise ignored.  As a special case, if
5088 
     this command is immediately followed by a character that is
5089 
     neither a digit or minus sign, the argument count for the next
5090 
     command is multiplied by four.  The argument count is initially
5091 
     one, so executing this function the first time makes the argument
5092 
     count four, a second time makes the argument count sixteen, and so
5093 
     on.  By default, this is not bound to a key.
5094 
 
5095 

5096 
File: gdb.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Prev: Numeric Arguments,  Up: Bindable Readline Commands
5097 
 
5098 
27.4.6 Letting Readline Type For You
5099 
------------------------------------
5100 
 
5101 
`complete ()'
5102 
     Attempt to perform completion on the text before point.  The
5103 
     actual completion performed is application-specific.  The default
5104 
     is filename completion.
5105 
 
5106 
`possible-completions (M-?)'
5107 
     List the possible completions of the text before point.
5108 
 
5109 
`insert-completions (M-*)'
5110 
     Insert all completions of the text before point that would have
5111 
     been generated by `possible-completions'.
5112 
 
5113 
`menu-complete ()'
5114 
     Similar to `complete', but replaces the word to be completed with
5115 
     a single match from the list of possible completions.  Repeated
5116 
     execution of `menu-complete' steps through the list of possible
5117 
     completions, inserting each match in turn.  At the end of the list
5118 
     of completions, the bell is rung (subject to the setting of
5119 
     `bell-style') and the original text is restored.  An argument of N
5120 
     moves N positions forward in the list of matches; a negative
5121 
     argument may be used to move backward through the list.  This
5122 
     command is intended to be bound to , but is unbound by
5123 
     default.
5124 
 
5125 
`delete-char-or-list ()'
5126 
     Deletes the character under the cursor if not at the beginning or
5127 
     end of the line (like `delete-char').  If at the end of the line,
5128 
     behaves identically to `possible-completions'.  This command is
5129 
     unbound by default.
5130 
 
5131 
 
5132 

5133 
File: gdb.info,  Node: Keyboard Macros,  Next: Miscellaneous Commands,  Prev: Commands For Completion,  Up: Bindable Readline Commands
5134 
 
5135 
27.4.7 Keyboard Macros
5136 
----------------------
5137 
 
5138 
`start-kbd-macro (C-x ()'
5139 
     Begin saving the characters typed into the current keyboard macro.
5140 
 
5141 
`end-kbd-macro (C-x ))'
5142 
     Stop saving the characters typed into the current keyboard macro
5143 
     and save the definition.
5144 
 
5145 
`call-last-kbd-macro (C-x e)'
5146 
     Re-execute the last keyboard macro defined, by making the
5147 
     characters in the macro appear as if typed at the keyboard.
5148 
 
5149 
 
5150 

5151 
File: gdb.info,  Node: Miscellaneous Commands,  Prev: Keyboard Macros,  Up: Bindable Readline Commands
5152 
 
5153 
27.4.8 Some Miscellaneous Commands
5154 
----------------------------------
5155 
 
5156 
`re-read-init-file (C-x C-r)'
5157 
     Read in the contents of the INPUTRC file, and incorporate any
5158 
     bindings or variable assignments found there.
5159 
 
5160 
`abort (C-g)'
5161 
     Abort the current editing command and ring the terminal's bell
5162 
     (subject to the setting of `bell-style').
5163 
 
5164 
`do-uppercase-version (M-a, M-b, M-X, ...)'
5165 
     If the metafied character X is lowercase, run the command that is
5166 
     bound to the corresponding uppercase character.
5167 
 
5168 
`prefix-meta ()'
5169 
     Metafy the next character typed.  This is for keyboards without a
5170 
     meta key.  Typing ` f' is equivalent to typing `M-f'.
5171 
 
5172 
`undo (C-_ or C-x C-u)'
5173 
     Incremental undo, separately remembered for each line.
5174 
 
5175 
`revert-line (M-r)'
5176 
     Undo all changes made to this line.  This is like executing the
5177 
     `undo' command enough times to get back to the beginning.
5178 
 
5179 
`tilde-expand (M-~)'
5180 
     Perform tilde expansion on the current word.
5181 
 
5182 
`set-mark (C-@)'
5183 
     Set the mark to the point.  If a numeric argument is supplied, the
5184 
     mark is set to that position.
5185 
 
5186 
`exchange-point-and-mark (C-x C-x)'
5187 
     Swap the point with the mark.  The current cursor position is set
5188 
     to the saved position, and the old cursor position is saved as the
5189 
     mark.
5190 
 
5191 
`character-search (C-])'
5192 
     A character is read and point is moved to the next occurrence of
5193 
     that character.  A negative count searches for previous
5194 
     occurrences.
5195 
 
5196 
`character-search-backward (M-C-])'
5197 
     A character is read and point is moved to the previous occurrence
5198 
     of that character.  A negative count searches for subsequent
5199 
     occurrences.
5200 
 
5201 
`insert-comment (M-#)'
5202 
     Without a numeric argument, the value of the `comment-begin'
5203 
     variable is inserted at the beginning of the current line.  If a
5204 
     numeric argument is supplied, this command acts as a toggle:  if
5205 
     the characters at the beginning of the line do not match the value
5206 
     of `comment-begin', the value is inserted, otherwise the
5207 
     characters in `comment-begin' are deleted from the beginning of
5208 
     the line.  In either case, the line is accepted as if a newline
5209 
     had been typed.
5210 
 
5211 
`dump-functions ()'
5212 
     Print all of the functions and their key bindings to the Readline
5213 
     output stream.  If a numeric argument is supplied, the output is
5214 
     formatted in such a way that it can be made part of an INPUTRC
5215 
     file.  This command is unbound by default.
5216 
 
5217 
`dump-variables ()'
5218 
     Print all of the settable variables and their values to the
5219 
     Readline output stream.  If a numeric argument is supplied, the
5220 
     output is formatted in such a way that it can be made part of an
5221 
     INPUTRC file.  This command is unbound by default.
5222 
 
5223 
`dump-macros ()'
5224 
     Print all of the Readline key sequences bound to macros and the
5225 
     strings they output.  If a numeric argument is supplied, the
5226 
     output is formatted in such a way that it can be made part of an
5227 
     INPUTRC file.  This command is unbound by default.
5228 
 
5229 
`emacs-editing-mode (C-e)'
5230 
     When in `vi' command mode, this causes a switch to `emacs' editing
5231 
     mode.
5232 
 
5233 
`vi-editing-mode (M-C-j)'
5234 
     When in `emacs' editing mode, this causes a switch to `vi' editing
5235 
     mode.
5236 
 
5237 
 
5238 

5239 
File: gdb.info,  Node: Readline vi Mode,  Prev: Bindable Readline Commands,  Up: Command Line Editing
5240 
 
5241 
27.5 Readline vi Mode
5242 
=====================
5243 
 
5244 
While the Readline library does not have a full set of `vi' editing
5245 
functions, it does contain enough to allow simple editing of the line.
5246 
The Readline `vi' mode behaves as specified in the POSIX 1003.2
5247 
standard.
5248 
 
5249 
   In order to switch interactively between `emacs' and `vi' editing
5250 
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
5251 
`vi' mode and to vi-editing-mode in `emacs' mode).  The Readline
5252 
default is `emacs' mode.
5253 
 
5254 
   When you enter a line in `vi' mode, you are already placed in
5255 
`insertion' mode, as if you had typed an `i'.  Pressing  switches
5256 
you into `command' mode, where you can edit the text of the line with
5257 
the standard `vi' movement keys, move to previous history lines with
5258 
`k' and subsequent lines with `j', and so forth.
5259 
 
5260 

5261 
File: gdb.info,  Node: Using History Interactively,  Next: Formatting Documentation,  Prev: Command Line Editing,  Up: Top
5262 
 
5263 
28 Using History Interactively
5264 
******************************
5265 
 
5266 
This chapter describes how to use the GNU History Library interactively,
5267 
from a user's standpoint.  It should be considered a user's guide.  For
5268 
information on using the GNU History Library in other programs, see the
5269 
GNU Readline Library Manual.
5270 
 
5271 
* Menu:
5272 
 
5273 
* History Interaction::         What it feels like using History as a user.
5274 
 
5275 

5276 
File: gdb.info,  Node: History Interaction,  Up: Using History Interactively
5277 
 
5278 
28.1 History Expansion
5279 
======================
5280 
 
5281 
The History library provides a history expansion feature that is similar
5282 
to the history expansion provided by `csh'.  This section describes the
5283 
syntax used to manipulate the history information.
5284 
 
5285 
   History expansions introduce words from the history list into the
5286 
input stream, making it easy to repeat commands, insert the arguments
5287 
to a previous command into the current input line, or fix errors in
5288 
previous commands quickly.
5289 
 
5290 
   History expansion takes place in two parts.  The first is to
5291 
determine which line from the history list should be used during
5292 
substitution.  The second is to select portions of that line for
5293 
inclusion into the current one.  The line selected from the history is
5294 
called the "event", and the portions of that line that are acted upon
5295 
are called "words".  Various "modifiers" are available to manipulate
5296 
the selected words.  The line is broken into words in the same fashion
5297 
that Bash does, so that several words surrounded by quotes are
5298 
considered one word.  History expansions are introduced by the
5299 
appearance of the history expansion character, which is `!' by default.
5300 
 
5301 
* Menu:
5302 
 
5303 
* Event Designators::   How to specify which history line to use.
5304 
* Word Designators::    Specifying which words are of interest.
5305 
* Modifiers::           Modifying the results of substitution.
5306 
 
5307 

5308 
File: gdb.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction
5309 
 
5310 
28.1.1 Event Designators
5311 
------------------------
5312 
 
5313 
An event designator is a reference to a command line entry in the
5314 
history list.
5315 
 
5316 
`!'
5317 
     Start a history substitution, except when followed by a space, tab,
5318 
     the end of the line, or `='.
5319 
 
5320 
`!N'
5321 
     Refer to command line N.
5322 
 
5323 
`!-N'
5324 
     Refer to the command N lines back.
5325 
 
5326 
`!!'
5327 
     Refer to the previous command.  This is a synonym for `!-1'.
5328 
 
5329 
`!STRING'
5330 
     Refer to the most recent command starting with STRING.
5331 
 
5332 
`!?STRING[?]'
5333 
     Refer to the most recent command containing STRING.  The trailing
5334 
     `?' may be omitted if the STRING is followed immediately by a
5335 
     newline.
5336 
 
5337 
`^STRING1^STRING2^'
5338 
     Quick Substitution.  Repeat the last command, replacing STRING1
5339 
     with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.
5340 
 
5341 
`!#'
5342 
     The entire command line typed so far.
5343 
 
5344 
 
5345 

5346 
File: gdb.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction
5347 
 
5348 
28.1.2 Word Designators
5349 
-----------------------
5350 
 
5351 
Word designators are used to select desired words from the event.  A
5352 
`:' separates the event specification from the word designator.  It may
5353 
be omitted if the word designator begins with a `^', `$', `*', `-', or
5354 
`%'.  Words are numbered from the beginning of the line, with the first
5355 
word being denoted by 0 (zero).  Words are inserted into the current
5356 
line separated by single spaces.
5357 
 
5358 
   For example,
5359 
 
5360 
`!!'
5361 
     designates the preceding command.  When you type this, the
5362 
     preceding command is repeated in toto.
5363 
 
5364 
`!!:$'
5365 
     designates the last argument of the preceding command.  This may be
5366 
     shortened to `!$'.
5367 
 
5368 
`!fi:2'
5369 
     designates the second argument of the most recent command starting
5370 
     with the letters `fi'.
5371 
 
5372 
   Here are the word designators:
5373 
 
5374 
`0 (zero)'
5375 
     The `0'th word.  For many applications, this is the command word.
5376 
 
5377 
`N'
5378 
     The Nth word.
5379 
 
5380 
`^'
5381 
     The first argument; that is, word 1.
5382 
 
5383 
`$'
5384 
     The last argument.
5385 
 
5386 
`%'
5387 
     The word matched by the most recent `?STRING?' search.
5388 
 
5389 
`X-Y'
5390 
     A range of words; `-Y' abbreviates `0-Y'.
5391 
 
5392 
`*'
5393 
     All of the words, except the `0'th.  This is a synonym for `1-$'.
5394 
     It is not an error to use `*' if there is just one word in the
5395 
     event; the empty string is returned in that case.
5396 
 
5397 
`X*'
5398 
     Abbreviates `X-$'
5399 
 
5400 
`X-'
5401 
     Abbreviates `X-$' like `X*', but omits the last word.
5402 
 
5403 
 
5404 
   If a word designator is supplied without an event specification, the
5405 
previous command is used as the event.
5406 
 
5407 

5408 
File: gdb.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction
5409 
 
5410 
28.1.3 Modifiers
5411 
----------------
5412 
 
5413 
After the optional word designator, you can add a sequence of one or
5414 
more of the following modifiers, each preceded by a `:'.
5415 
 
5416 
`h'
5417 
     Remove a trailing pathname component, leaving only the head.
5418 
 
5419 
`t'
5420 
     Remove all leading  pathname  components, leaving the tail.
5421 
 
5422 
`r'
5423 
     Remove a trailing suffix of the form `.SUFFIX', leaving the
5424 
     basename.
5425 
 
5426 
`e'
5427 
     Remove all but the trailing suffix.
5428 
 
5429 
`p'
5430 
     Print the new command but do not execute it.
5431 
 
5432 
`s/OLD/NEW/'
5433 
     Substitute NEW for the first occurrence of OLD in the event line.
5434 
     Any delimiter may be used in place of `/'.  The delimiter may be
5435 
     quoted in OLD and NEW with a single backslash.  If `&' appears in
5436 
     NEW, it is replaced by OLD.  A single backslash will quote the
5437 
     `&'.  The final delimiter is optional if it is the last character
5438 
     on the input line.
5439 
 
5440 
`&'
5441 
     Repeat the previous substitution.
5442 
 
5443 
`g'
5444 
`a'
5445 
     Cause changes to be applied over the entire event line.  Used in
5446 
     conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
5447 
 
5448 
`G'
5449 
     Apply the following `s' modifier once to each word in the event.
5450 
 
5451 
 
5452 

5453 
File: gdb.info,  Node: Formatting Documentation,  Next: Installing GDB,  Prev: Using History Interactively,  Up: Top
5454 
 
5455 
Appendix A Formatting Documentation
5456 
***********************************
5457 
 
5458 
The GDB 4 release includes an already-formatted reference card, ready
5459 
for printing with PostScript or Ghostscript, in the `gdb' subdirectory
5460 
of the main source directory(1).  If you can use PostScript or
5461 
Ghostscript with your printer, you can print the reference card
5462 
immediately with `refcard.ps'.
5463 
 
5464 
   The release also includes the source for the reference card.  You
5465 
can format it, using TeX, by typing:
5466 
 
5467 
     make refcard.dvi
5468 
 
5469 
   The GDB reference card is designed to print in "landscape" mode on
5470 
US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
5471 
high.  You will need to specify this form of printing as an option to
5472 
your DVI output program.
5473 
 
5474 
   All the documentation for GDB comes as part of the machine-readable
5475 
distribution.  The documentation is written in Texinfo format, which is
5476 
a documentation system that uses a single source file to produce both
5477 
on-line information and a printed manual.  You can use one of the Info
5478 
formatting commands to create the on-line version of the documentation
5479 
and TeX (or `texi2roff') to typeset the printed version.
5480 
 
5481 
   GDB includes an already formatted copy of the on-line Info version
5482 
of this manual in the `gdb' subdirectory.  The main Info file is
5483 
`gdb-6.8/gdb/gdb.info', and it refers to subordinate files matching
5484 
`gdb.info*' in the same directory.  If necessary, you can print out
5485 
these files, or read them with any editor; but they are easier to read
5486 
using the `info' subsystem in GNU Emacs or the standalone `info'
5487 
program, available as part of the GNU Texinfo distribution.
5488 
 
5489 
   If you want to format these Info files yourself, you need one of the
5490 
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
5491 
 
5492 
   If you have `makeinfo' installed, and are in the top level GDB
5493 
source directory (`gdb-6.8', in the case of version 6.8), you can make
5494 
the Info file by typing:
5495 
 
5496 
     cd gdb
5497 
     make gdb.info
5498 
 
5499 
   If you want to typeset and print copies of this manual, you need TeX,
5500 
a program to print its DVI output files, and `texinfo.tex', the Texinfo
5501 
definitions file.
5502 
 
5503 
   TeX is a typesetting program; it does not print files directly, but
5504 
produces output files called DVI files.  To print a typeset document,
5505 
you need a program to print DVI files.  If your system has TeX
5506 
installed, chances are it has such a program.  The precise command to
5507 
use depends on your system; `lpr -d' is common; another (for PostScript
5508 
devices) is `dvips'.  The DVI print command may require a file name
5509 
without any extension or a `.dvi' extension.
5510 
 
5511 
   TeX also requires a macro definitions file called `texinfo.tex'.
5512 
This file tells TeX how to typeset a document written in Texinfo
5513 
format.  On its own, TeX cannot either read or typeset a Texinfo file.
5514 
`texinfo.tex' is distributed with GDB and is located in the
5515 
`gdb-VERSION-NUMBER/texinfo' directory.
5516 
 
5517 
   If you have TeX and a DVI printer program installed, you can typeset
5518 
and print this manual.  First switch to the `gdb' subdirectory of the
5519 
main source directory (for example, to `gdb-6.8/gdb') and type:
5520 
 
5521 
     make gdb.dvi
5522 
 
5523 
   Then give `gdb.dvi' to your DVI printing program.
5524 
 
5525 
   ---------- Footnotes ----------
5526 
 
5527 
   (1) In `gdb-6.8/gdb/refcard.ps' of the version 6.8 release.
5528 
 
5529 

5530 
File: gdb.info,  Node: Installing GDB,  Next: Maintenance Commands,  Prev: Formatting Documentation,  Up: Top
5531 
 
5532 
Appendix B Installing GDB
5533 
*************************
5534 
 
5535 
* Menu:
5536 
 
5537 
* Requirements::                Requirements for building GDB
5538 
* Running Configure::           Invoking the GDB `configure' script
5539 
* Separate Objdir::             Compiling GDB in another directory
5540 
* Config Names::                Specifying names for hosts and targets
5541 
* Configure Options::           Summary of options for configure
5542 
 
5543 

5544 
File: gdb.info,  Node: Requirements,  Next: Running Configure,  Up: Installing GDB
5545 
 
5546 
B.1 Requirements for Building GDB
5547 
=================================
5548 
 
5549 
Building GDB requires various tools and packages to be available.
5550 
Other packages will be used only if they are found.
5551 
 
5552 
Tools/Packages Necessary for Building GDB
5553 
=========================================
5554 
 
5555 
ISO C90 compiler
5556 
     GDB is written in ISO C90.  It should be buildable with any
5557 
     working C90 compiler, e.g. GCC.
5558 
 
5559 
 
5560 
Tools/Packages Optional for Building GDB
5561 
========================================
5562 
 
5563 
Expat
5564 
     GDB can use the Expat XML parsing library.  This library may be
5565 
     included with your operating system distribution; if it is not, you
5566 
     can get the latest version from `http://expat.sourceforge.net'.
5567 
     The `configure' script will search for this library in several
5568 
     standard locations; if it is installed in an unusual path, you can
5569 
     use the `--with-libexpat-prefix' option to specify its location.
5570 
 
5571 
     Expat is used for:
5572 
 
5573 
        * Remote protocol memory maps (*note Memory Map Format::)
5574 
 
5575 
        * Target descriptions (*note Target Descriptions::)
5576 
 
5577 
        * Remote shared library lists (*note Library List Format::)
5578 
 
5579 
        * MS-Windows shared libraries (*note Shared Libraries::)
5580 
 
5581 
 
5582 

5583 
File: gdb.info,  Node: Running Configure,  Next: Separate Objdir,  Prev: Requirements,  Up: Installing GDB
5584 
 
5585 
B.2 Invoking the GDB `configure' Script
5586 
=======================================
5587 
 
5588 
GDB comes with a `configure' script that automates the process of
5589 
preparing GDB for installation; you can then use `make' to build the
5590 
`gdb' program.
5591 
 
5592 
   The GDB distribution includes all the source code you need for GDB
5593 
in a single directory, whose name is usually composed by appending the
5594 
version number to `gdb'.
5595 
 
5596 
   For example, the GDB version 6.8 distribution is in the `gdb-6.8'
5597 
directory.  That directory contains:
5598 
 
5599 
`gdb-6.8/configure (and supporting files)'
5600 
     script for configuring GDB and all its supporting libraries
5601 
 
5602 
`gdb-6.8/gdb'
5603 
     the source specific to GDB itself
5604 
 
5605 
`gdb-6.8/bfd'
5606 
     source for the Binary File Descriptor library
5607 
 
5608 
`gdb-6.8/include'
5609 
     GNU include files
5610 
 
5611 
`gdb-6.8/libiberty'
5612 
     source for the `-liberty' free software library
5613 
 
5614 
`gdb-6.8/opcodes'
5615 
     source for the library of opcode tables and disassemblers
5616 
 
5617 
`gdb-6.8/readline'
5618 
     source for the GNU command-line interface
5619 
 
5620 
`gdb-6.8/glob'
5621 
     source for the GNU filename pattern-matching subroutine
5622 
 
5623 
`gdb-6.8/mmalloc'
5624 
     source for the GNU memory-mapped malloc package
5625 
 
5626 
   The simplest way to configure and build GDB is to run `configure'
5627 
from the `gdb-VERSION-NUMBER' source directory, which in this example
5628 
is the `gdb-6.8' directory.
5629 
 
5630 
   First switch to the `gdb-VERSION-NUMBER' source directory if you are
5631 
not already in it; then run `configure'.  Pass the identifier for the
5632 
platform on which GDB will run as an argument.
5633 
 
5634 
   For example:
5635 
 
5636 
     cd gdb-6.8
5637 
     ./configure HOST
5638 
     make
5639 
 
5640 
where HOST is an identifier such as `sun4' or `decstation', that
5641 
identifies the platform where GDB will run.  (You can often leave off
5642 
HOST; `configure' tries to guess the correct value by examining your
5643 
system.)
5644 
 
5645 
   Running `configure HOST' and then running `make' builds the `bfd',
5646 
`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
5647 
The configured source files, and the binaries, are left in the
5648 
corresponding source directories.
5649 
 
5650 
   `configure' is a Bourne-shell (`/bin/sh') script; if your system
5651 
does not recognize this automatically when you run a different shell,
5652 
you may need to run `sh' on it explicitly:
5653 
 
5654 
     sh configure HOST
5655 
 
5656 
   If you run `configure' from a directory that contains source
5657 
directories for multiple libraries or programs, such as the `gdb-6.8'
5658 
source directory for version 6.8, `configure' creates configuration
5659 
files for every directory level underneath (unless you tell it not to,
5660 
with the `--norecursion' option).
5661 
 
5662 
   You should run the `configure' script from the top directory in the
5663 
source tree, the `gdb-VERSION-NUMBER' directory.  If you run
5664 
`configure' from one of the subdirectories, you will configure only
5665 
that subdirectory.  That is usually not what you want.  In particular,
5666 
if you run the first `configure' from the `gdb' subdirectory of the
5667 
`gdb-VERSION-NUMBER' directory, you will omit the configuration of
5668 
`bfd', `readline', and other sibling directories of the `gdb'
5669 
subdirectory.  This leads to build errors about missing include files
5670 
such as `bfd/bfd.h'.
5671 
 
5672 
   You can install `gdb' anywhere; it has no hardwired paths.  However,
5673 
you should make sure that the shell on your path (named by the `SHELL'
5674 
environment variable) is publicly readable.  Remember that GDB uses the
5675 
shell to start your program--some systems refuse to let GDB debug child
5676 
processes whose programs are not readable.
5677 
 
5678 

5679 
File: gdb.info,  Node: Separate Objdir,  Next: Config Names,  Prev: Running Configure,  Up: Installing GDB
5680 
 
5681 
B.3 Compiling GDB in Another Directory
5682 
======================================
5683 
 
5684 
If you want to run GDB versions for several host or target machines,
5685 
you need a different `gdb' compiled for each combination of host and
5686 
target.  `configure' is designed to make this easy by allowing you to
5687 
generate each configuration in a separate subdirectory, rather than in
5688 
the source directory.  If your `make' program handles the `VPATH'
5689 
feature (GNU `make' does), running `make' in each of these directories
5690 
builds the `gdb' program specified there.
5691 
 
5692 
   To build `gdb' in a separate directory, run `configure' with the
5693 
`--srcdir' option to specify where to find the source.  (You also need
5694 
to specify a path to find `configure' itself from your working
5695 
directory.  If the path to `configure' would be the same as the
5696 
argument to `--srcdir', you can leave out the `--srcdir' option; it is
5697 
assumed.)
5698 
 
5699 
   For example, with version 6.8, you can build GDB in a separate
5700 
directory for a Sun 4 like this:
5701 
 
5702 
     cd gdb-6.8
5703 
     mkdir ../gdb-sun4
5704 
     cd ../gdb-sun4
5705 
     ../gdb-6.8/configure sun4
5706 
     make
5707 
 
5708 
   When `configure' builds a configuration using a remote source
5709 
directory, it creates a tree for the binaries with the same structure
5710 
(and using the same names) as the tree under the source directory.  In
5711 
the example, you'd find the Sun 4 library `libiberty.a' in the
5712 
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
5713 
 
5714 
   Make sure that your path to the `configure' script has just one
5715 
instance of `gdb' in it.  If your path to `configure' looks like
5716 
`../gdb-6.8/gdb/configure', you are configuring only one subdirectory
5717 
of GDB, not the whole package.  This leads to build errors about
5718 
missing include files such as `bfd/bfd.h'.
5719 
 
5720 
   One popular reason to build several GDB configurations in separate
5721 
directories is to configure GDB for cross-compiling (where GDB runs on
5722 
one machine--the "host"--while debugging programs that run on another
5723 
machine--the "target").  You specify a cross-debugging target by giving
5724 
the `--target=TARGET' option to `configure'.
5725 
 
5726 
   When you run `make' to build a program or library, you must run it
5727 
in a configured directory--whatever directory you were in when you
5728 
called `configure' (or one of its subdirectories).
5729 
 
5730 
   The `Makefile' that `configure' generates in each source directory
5731 
also runs recursively.  If you type `make' in a source directory such
5732 
as `gdb-6.8' (or in a separate configured directory configured with
5733 
`--srcdir=DIRNAME/gdb-6.8'), you will build all the required libraries,
5734 
and then build GDB.
5735 
 
5736 
   When you have multiple hosts or targets configured in separate
5737 
directories, you can run `make' on them in parallel (for example, if
5738 
they are NFS-mounted on each of the hosts); they will not interfere
5739 
with each other.
5740 
 
5741 

5742 
File: gdb.info,  Node: Config Names,  Next: Configure Options,  Prev: Separate Objdir,  Up: Installing GDB
5743 
 
5744 
B.4 Specifying Names for Hosts and Targets
5745 
==========================================
5746 
 
5747 
The specifications used for hosts and targets in the `configure' script
5748 
are based on a three-part naming scheme, but some short predefined
5749 
aliases are also supported.  The full naming scheme encodes three pieces
5750 
of information in the following pattern:
5751 
 
5752 
     ARCHITECTURE-VENDOR-OS
5753 
 
5754 
   For example, you can use the alias `sun4' as a HOST argument, or as
5755 
the value for TARGET in a `--target=TARGET' option.  The equivalent
5756 
full name is `sparc-sun-sunos4'.
5757 
 
5758 
   The `configure' script accompanying GDB does not provide any query
5759 
facility to list all supported host and target names or aliases.
5760 
`configure' calls the Bourne shell script `config.sub' to map
5761 
abbreviations to full names; you can read the script, if you wish, or
5762 
you can use it to test your guesses on abbreviations--for example:
5763 
 
5764 
     % sh config.sub i386-linux
5765 
     i386-pc-linux-gnu
5766 
     % sh config.sub alpha-linux
5767 
     alpha-unknown-linux-gnu
5768 
     % sh config.sub hp9k700
5769 
     hppa1.1-hp-hpux
5770 
     % sh config.sub sun4
5771 
     sparc-sun-sunos4.1.1
5772 
     % sh config.sub sun3
5773 
     m68k-sun-sunos4.1.1
5774 
     % sh config.sub i986v
5775 
     Invalid configuration `i986v': machine `i986v' not recognized
5776 
 
5777 
`config.sub' is also distributed in the GDB source directory
5778 
(`gdb-6.8', for version 6.8).
5779 
 
5780 

5781 
File: gdb.info,  Node: Configure Options,  Prev: Config Names,  Up: Installing GDB
5782 
 
5783 
B.5 `configure' Options
5784 
=======================
5785 
 
5786 
Here is a summary of the `configure' options and arguments that are
5787 
most often useful for building GDB.  `configure' also has several other
5788 
options not listed here.  *note (configure.info)What Configure Does::,
5789 
for a full explanation of `configure'.
5790 
 
5791 
     configure [--help]
5792 
               [--prefix=DIR]
5793 
               [--exec-prefix=DIR]
5794 
               [--srcdir=DIRNAME]
5795 
               [--norecursion] [--rm]
5796 
               [--target=TARGET]
5797 
               HOST
5798 
 
5799 
You may introduce options with a single `-' rather than `--' if you
5800 
prefer; but you may abbreviate option names if you use `--'.
5801 
 
5802 
`--help'
5803 
     Display a quick summary of how to invoke `configure'.
5804 
 
5805 
`--prefix=DIR'
5806 
     Configure the source to install programs and files under directory
5807 
     `DIR'.
5808 
 
5809 
`--exec-prefix=DIR'
5810 
     Configure the source to install programs under directory `DIR'.
5811 
 
5812 
`--srcdir=DIRNAME'
5813 
     *Warning: using this option requires GNU `make', or another `make'
5814 
     that implements the `VPATH' feature.*
5815 
     Use this option to make configurations in directories separate
5816 
     from the GDB source directories.  Among other things, you can use
5817 
     this to build (or maintain) several configurations simultaneously,
5818 
     in separate directories.  `configure' writes
5819 
     configuration-specific files in the current directory, but
5820 
     arranges for them to use the source in the directory DIRNAME.
5821 
     `configure' creates directories under the working directory in
5822 
     parallel to the source directories below DIRNAME.
5823 
 
5824 
`--norecursion'
5825 
     Configure only the directory level where `configure' is executed;
5826 
     do not propagate configuration to subdirectories.
5827 
 
5828 
`--target=TARGET'
5829 
     Configure GDB for cross-debugging programs running on the specified
5830 
     TARGET.  Without this option, GDB is configured to debug programs
5831 
     that run on the same machine (HOST) as GDB itself.
5832 
 
5833 
     There is no convenient way to generate a list of all available
5834 
     targets.
5835 
 
5836 
`HOST ...'
5837 
     Configure GDB to run on the specified HOST.
5838 
 
5839 
     There is no convenient way to generate a list of all available
5840 
     hosts.
5841 
 
5842 
   There are many other options available as well, but they are
5843 
generally needed for special purposes only.
5844 
 
5845 

5846 
File: gdb.info,  Node: Maintenance Commands,  Next: Remote Protocol,  Prev: Installing GDB,  Up: Top
5847 
 
5848 
Appendix C Maintenance Commands
5849 
*******************************
5850 
 
5851 
In addition to commands intended for GDB users, GDB includes a number
5852 
of commands intended for GDB developers, that are not documented
5853 
elsewhere in this manual.  These commands are provided here for
5854 
reference.  (For commands that turn on debugging messages, see *Note
5855 
Debugging Output::.)
5856 
 
5857 
`maint agent EXPRESSION'
5858 
     Translate the given EXPRESSION into remote agent bytecodes.  This
5859 
     command is useful for debugging the Agent Expression mechanism
5860 
     (*note Agent Expressions::).
5861 
 
5862 
`maint info breakpoints'
5863 
     Using the same format as `info breakpoints', display both the
5864 
     breakpoints you've set explicitly, and those GDB is using for
5865 
     internal purposes.  Internal breakpoints are shown with negative
5866 
     breakpoint numbers.  The type column identifies what kind of
5867 
     breakpoint is shown:
5868 
 
5869 
    `breakpoint'
5870 
          Normal, explicitly set breakpoint.
5871 
 
5872 
    `watchpoint'
5873 
          Normal, explicitly set watchpoint.
5874 
 
5875 
    `longjmp'
5876 
          Internal breakpoint, used to handle correctly stepping through
5877 
          `longjmp' calls.
5878 
 
5879 
    `longjmp resume'
5880 
          Internal breakpoint at the target of a `longjmp'.
5881 
 
5882 
    `until'
5883 
          Temporary internal breakpoint used by the GDB `until' command.
5884 
 
5885 
    `finish'
5886 
          Temporary internal breakpoint used by the GDB `finish'
5887 
          command.
5888 
 
5889 
    `shlib events'
5890 
          Shared library events.
5891 
 
5892 
 
5893 
`maint check-symtabs'
5894 
     Check the consistency of psymtabs and symtabs.
5895 
 
5896 
`maint cplus first_component NAME'
5897 
     Print the first C++ class/namespace component of NAME.
5898 
 
5899 
`maint cplus namespace'
5900 
     Print the list of possible C++ namespaces.
5901 
 
5902 
`maint demangle NAME'
5903 
     Demangle a C++ or Objective-C mangled NAME.
5904 
 
5905 
`maint deprecate COMMAND [REPLACEMENT]'
5906 
`maint undeprecate COMMAND'
5907 
     Deprecate or undeprecate the named COMMAND.  Deprecated commands
5908 
     cause GDB to issue a warning when you use them.  The optional
5909 
     argument REPLACEMENT says which newer command should be used in
5910 
     favor of the deprecated one; if it is given, GDB will mention the
5911 
     replacement as part of the warning.
5912 
 
5913 
`maint dump-me'
5914 
     Cause a fatal signal in the debugger and force it to dump its core.
5915 
     This is supported only on systems which support aborting a program
5916 
     with the `SIGQUIT' signal.
5917 
 
5918 
`maint internal-error [MESSAGE-TEXT]'
5919 
`maint internal-warning [MESSAGE-TEXT]'
5920 
     Cause GDB to call the internal function `internal_error' or
5921 
     `internal_warning' and hence behave as though an internal error or
5922 
     internal warning has been detected.  In addition to reporting the
5923 
     internal problem, these functions give the user the opportunity to
5924 
     either quit GDB or create a core file of the current GDB session.
5925 
 
5926 
     These commands take an optional parameter MESSAGE-TEXT that is
5927 
     used as the text of the error or warning message.
5928 
 
5929 
     Here's an example of using `internal-error':
5930 
 
5931 
          (gdb) maint internal-error testing, 1, 2
5932 
          .../maint.c:121: internal-error: testing, 1, 2
5933 
          A problem internal to GDB has been detected.  Further
5934 
          debugging may prove unreliable.
5935 
          Quit this debugging session? (y or n) n
5936 
          Create a core file? (y or n) n
5937 
          (gdb)
5938 
 
5939 
`maint packet TEXT'
5940 
     If GDB is talking to an inferior via the serial protocol, then
5941 
     this command sends the string TEXT to the inferior, and displays
5942 
     the response packet.  GDB supplies the initial `$' character, the
5943 
     terminating `#' character, and the checksum.
5944 
 
5945 
`maint print architecture [FILE]'
5946 
     Print the entire architecture configuration.  The optional argument
5947 
     FILE names the file where the output goes.
5948 
 
5949 
`maint print c-tdesc'
5950 
     Print the current target description (*note Target Descriptions::)
5951 
     as a C source file.  The created source file can be used in GDB
5952 
     when an XML parser is not available to parse the description.
5953 
 
5954 
`maint print dummy-frames'
5955 
     Prints the contents of GDB's internal dummy-frame stack.
5956 
 
5957 
          (gdb) b add
5958 
          ...
5959 
          (gdb) print add(2,3)
5960 
          Breakpoint 2, add (a=2, b=3) at ...
5961 
          58      return (a + b);
5962 
          The program being debugged stopped while in a function called from GDB.
5963 
          ...
5964 
          (gdb) maint print dummy-frames
5965 
          0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
5966 
           top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
5967 
           call_lo=0x01014000 call_hi=0x01014001
5968 
          (gdb)
5969 
 
5970 
     Takes an optional file parameter.
5971 
 
5972 
`maint print registers [FILE]'
5973 
`maint print raw-registers [FILE]'
5974 
`maint print cooked-registers [FILE]'
5975 
`maint print register-groups [FILE]'
5976 
     Print GDB's internal register data structures.
5977 
 
5978 
     The command `maint print raw-registers' includes the contents of
5979 
     the raw register cache; the command `maint print cooked-registers'
5980 
     includes the (cooked) value of all registers; and the command
5981 
     `maint print register-groups' includes the groups that each
5982 
     register is a member of.  *Note Registers: (gdbint)Registers.
5983 
 
5984 
     These commands take an optional parameter, a file name to which to
5985 
     write the information.
5986 
 
5987 
`maint print reggroups [FILE]'
5988 
     Print GDB's internal register group data structures.  The optional
5989 
     argument FILE tells to what file to write the information.
5990 
 
5991 
     The register groups info looks like this:
5992 
 
5993 
          (gdb) maint print reggroups
5994 
           Group      Type
5995 
           general    user
5996 
           float      user
5997 
           all        user
5998 
           vector     user
5999 
           system     user
6000 
           save       internal
6001 
           restore    internal
6002 
 
6003 
`flushregs'
6004 
     This command forces GDB to flush its internal register cache.
6005 
 
6006 
`maint print objfiles'
6007 
     Print a dump of all known object files.  For each object file, this
6008 
     command prints its name, address in memory, and all of its psymtabs
6009 
     and symtabs.
6010 
 
6011 
`maint print statistics'
6012 
     This command prints, for each object file in the program, various
6013 
     data about that object file followed by the byte cache ("bcache")
6014 
     statistics for the object file.  The objfile data includes the
6015 
     number of minimal, partial, full, and stabs symbols, the number of
6016 
     types defined by the objfile, the number of as yet unexpanded psym
6017 
     tables, the number of line tables and string tables, and the
6018 
     amount of memory used by the various tables.  The bcache
6019 
     statistics include the counts, sizes, and counts of duplicates of
6020 
     all and unique objects, max, average, and median entry size, total
6021 
     memory used and its overhead and savings, and various measures of
6022 
     the hash table size and chain lengths.
6023 
 
6024 
`maint print target-stack'
6025 
     A "target" is an interface between the debugger and a particular
6026 
     kind of file or process.  Targets can be stacked in "strata", so
6027 
     that more than one target can potentially respond to a request.
6028 
     In particular, memory accesses will walk down the stack of targets
6029 
     until they find a target that is interested in handling that
6030 
     particular address.
6031 
 
6032 
     This command prints a short description of each layer that was
6033 
     pushed on the "target stack", starting from the top layer down to
6034 
     the bottom one.
6035 
 
6036 
`maint print type EXPR'
6037 
     Print the type chain for a type specified by EXPR.  The argument
6038 
     can be either a type name or a symbol.  If it is a symbol, the
6039 
     type of that symbol is described.  The type chain produced by this
6040 
     command is a recursive definition of the data type as stored in
6041 
     GDB's data structures, including its flags and contained types.
6042 
 
6043 
`maint set dwarf2 max-cache-age'
6044 
`maint show dwarf2 max-cache-age'
6045 
     Control the DWARF 2 compilation unit cache.
6046 
 
6047 
     In object files with inter-compilation-unit references, such as
6048 
     those produced by the GCC option `-feliminate-dwarf2-dups', the
6049 
     DWARF 2 reader needs to frequently refer to previously read
6050 
     compilation units.  This setting controls how long a compilation
6051 
     unit will remain in the cache if it is not referenced.  A higher
6052 
     limit means that cached compilation units will be stored in memory
6053 
     longer, and more total memory will be used.  Setting it to zero
6054 
     disables caching, which will slow down GDB startup, but reduce
6055 
     memory consumption.
6056 
 
6057 
`maint set profile'
6058 
`maint show profile'
6059 
     Control profiling of GDB.
6060 
 
6061 
     Profiling will be disabled until you use the `maint set profile'
6062 
     command to enable it.  When you enable profiling, the system will
6063 
     begin collecting timing and execution count data; when you disable
6064 
     profiling or exit GDB, the results will be written to a log file.
6065 
     Remember that if you use profiling, GDB will overwrite the
6066 
     profiling log file (often called `gmon.out').  If you have a
6067 
     record of important profiling data in a `gmon.out' file, be sure
6068 
     to move it to a safe location.
6069 
 
6070 
     Configuring with `--enable-profiling' arranges for GDB to be
6071 
     compiled with the `-pg' compiler option.
6072 
 
6073 
`maint show-debug-regs'
6074 
     Control whether to show variables that mirror the x86 hardware
6075 
     debug registers.  Use `ON' to enable, `OFF' to disable.  If
6076 
     enabled, the debug registers values are shown when GDB inserts or
6077 
     removes a hardware breakpoint or watchpoint, and when the inferior
6078 
     triggers a hardware-assisted breakpoint or watchpoint.
6079 
 
6080 
`maint space'
6081 
     Control whether to display memory usage for each command.  If set
6082 
     to a nonzero value, GDB will display how much memory each command
6083 
     took, following the command's own output.  This can also be
6084 
     requested by invoking GDB with the `--statistics' command-line
6085 
     switch (*note Mode Options::).
6086 
 
6087 
`maint time'
6088 
     Control whether to display the execution time for each command.  If
6089 
     set to a nonzero value, GDB will display how much time it took to
6090 
     execute each command, following the command's own output.  This
6091 
     can also be requested by invoking GDB with the `--statistics'
6092 
     command-line switch (*note Mode Options::).
6093 
 
6094 
`maint translate-address [SECTION] ADDR'
6095 
     Find the symbol stored at the location specified by the address
6096 
     ADDR and an optional section name SECTION.  If found, GDB prints
6097 
     the name of the closest symbol and an offset from the symbol's
6098 
     location to the specified address.  This is similar to the `info
6099 
     address' command (*note Symbols::), except that this command also
6100 
     allows to find symbols in other sections.
6101 
 
6102 
 
6103 
   The following command is useful for non-interactive invocations of
6104 
GDB, such as in the test suite.
6105 
 
6106 
`set watchdog NSEC'
6107 
     Set the maximum number of seconds GDB will wait for the target
6108 
     operation to finish.  If this time expires, GDB reports and error
6109 
     and the command is aborted.
6110 
 
6111 
`show watchdog'
6112 
     Show the current setting of the target wait timeout.
6113 
 
6114 

6115 
File: gdb.info,  Node: Remote Protocol,  Next: Agent Expressions,  Prev: Maintenance Commands,  Up: Top
6116 
 
6117 
Appendix D GDB Remote Serial Protocol
6118 
*************************************
6119 
 
6120 
* Menu:
6121 
 
6122 
* Overview::
6123 
* Packets::
6124 
* Stop Reply Packets::
6125 
* General Query Packets::
6126 
* Register Packet Format::
6127 
* Tracepoint Packets::
6128 
* Host I/O Packets::
6129 
* Interrupts::
6130 
* Examples::
6131 
* File-I/O Remote Protocol Extension::
6132 
* Library List Format::
6133 
* Memory Map Format::
6134 
 
6135 

6136 
File: gdb.info,  Node: Overview,  Next: Packets,  Up: Remote Protocol
6137 
 
6138 
D.1 Overview
6139 
============
6140 
 
6141 
There may be occasions when you need to know something about the
6142 
protocol--for example, if there is only one serial port to your target
6143 
machine, you might want your program to do something special if it
6144 
recognizes a packet meant for GDB.
6145 
 
6146 
   In the examples below, `->' and `<-' are used to indicate
6147 
transmitted and received data, respectively.
6148 
 
6149 
   All GDB commands and responses (other than acknowledgments) are sent
6150 
as a PACKET.  A PACKET is introduced with the character `$', the actual
6151 
PACKET-DATA, and the terminating character `#' followed by a two-digit
6152 
CHECKSUM:
6153 
 
6154 
     `$'PACKET-DATA`#'CHECKSUM
6155 
   The two-digit CHECKSUM is computed as the modulo 256 sum of all
6156 
characters between the leading `$' and the trailing `#' (an eight bit
6157 
unsigned checksum).
6158 
 
6159 
   Implementors should note that prior to GDB 5.0 the protocol
6160 
specification also included an optional two-digit SEQUENCE-ID:
6161 
 
6162 
     `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
6163 
 
6164 
That SEQUENCE-ID was appended to the acknowledgment.  GDB has never
6165 
output SEQUENCE-IDs.  Stubs that handle packets added since GDB 5.0
6166 
must not accept SEQUENCE-ID.
6167 
 
6168 
   When either the host or the target machine receives a packet, the
6169 
first response expected is an acknowledgment: either `+' (to indicate
6170 
the package was received correctly) or `-' (to request retransmission):
6171 
 
6172 
     -> `$'PACKET-DATA`#'CHECKSUM
6173 
     <- `+'
6174 
   The host (GDB) sends COMMANDs, and the target (the debugging stub
6175 
incorporated in your program) sends a RESPONSE.  In the case of step
6176 
and continue COMMANDs, the response is only sent when the operation has
6177 
completed (the target has again stopped).
6178 
 
6179 
   PACKET-DATA consists of a sequence of characters with the exception
6180 
of `#' and `$' (see `X' packet for additional exceptions).
6181 
 
6182 
   Fields within the packet should be separated using `,' `;' or `:'.
6183 
Except where otherwise noted all numbers are represented in HEX with
6184 
leading zeros suppressed.
6185 
 
6186 
   Implementors should note that prior to GDB 5.0, the character `:'
6187 
could not appear as the third character in a packet (as it would
6188 
potentially conflict with the SEQUENCE-ID).
6189 
 
6190 
   Binary data in most packets is encoded either as two hexadecimal
6191 
digits per byte of binary data.  This allowed the traditional remote
6192 
protocol to work over connections which were only seven-bit clean.
6193 
Some packets designed more recently assume an eight-bit clean
6194 
connection, and use a more efficient encoding to send and receive
6195 
binary data.
6196 
 
6197 
   The binary data representation uses `7d' (ASCII `}') as an escape
6198 
character.  Any escaped byte is transmitted as the escape character
6199 
followed by the original character XORed with `0x20'.  For example, the
6200 
byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'.  The
6201 
bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
6202 
must always be escaped.  Responses sent by the stub must also escape
6203 
`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
6204 
run-length encoded sequence (described next).
6205 
 
6206 
   Response DATA can be run-length encoded to save space.  Run-length
6207 
encoding replaces runs of identical characters with one instance of the
6208 
repeated character, followed by a `*' and a repeat count.  The repeat
6209 
count is itself sent encoded, to avoid binary characters in DATA: a
6210 
value of N is sent as `N+29'.  For a repeat count greater or equal to
6211 
3, this produces a printable ASCII character, e.g. a space (ASCII code
6212 
32) for a repeat count of 3.  (This is because run-length encoding
6213 
starts to win for counts 3 or more.)  Thus, for example, `0* ' is a
6214 
run-length encoding of "0000": the space character after `*' means
6215 
repeat the leading `0' `32 - 29 = 3' more times.
6216 
 
6217 
   The printable characters `#' and `$' or with a numeric value greater
6218 
than 126 must not be used.  Runs of six repeats (`#') or seven repeats
6219 
(`$') can be expanded using a repeat count of only five (`"').  For
6220 
example, `00000000' can be encoded as `0*"00'.
6221 
 
6222 
   The error response returned for some packets includes a two character
6223 
error number.  That number is not well defined.
6224 
 
6225 
   For any COMMAND not supported by the stub, an empty response
6226 
(`$#00') should be returned.  That way it is possible to extend the
6227 
protocol.  A newer GDB can tell if a packet is supported based on that
6228 
response.
6229 
 
6230 
   A stub is required to support the `g', `G', `m', `M', `c', and `s'
6231 
COMMANDs.  All other COMMANDs are optional.
6232 
 
6233 

6234 
File: gdb.info,  Node: Packets,  Next: Stop Reply Packets,  Prev: Overview,  Up: Remote Protocol
6235 
 
6236 
D.2 Packets
6237 
===========
6238 
 
6239 
The following table provides a complete list of all currently defined
6240 
COMMANDs and their corresponding response DATA.  *Note File-I/O Remote
6241 
Protocol Extension::, for details about the File I/O extension of the
6242 
remote protocol.
6243 
 
6244 
   Each packet's description has a template showing the packet's overall
6245 
syntax, followed by an explanation of the packet's meaning.  We include
6246 
spaces in some of the templates for clarity; these are not part of the
6247 
packet's syntax.  No GDB packet uses spaces to separate its components.
6248 
For example, a template like `foo BAR BAZ' describes a packet
6249 
beginning with the three ASCII bytes `foo', followed by a BAR, followed
6250 
directly by a BAZ.  GDB does not transmit a space character between the
6251 
`foo' and the BAR, or between the BAR and the BAZ.
6252 
 
6253 
   Note that all packet forms beginning with an upper- or lower-case
6254 
letter, other than those described here, are reserved for future use.
6255 
 
6256 
   Here are the packet descriptions.
6257 
 
6258 
`!'
6259 
     Enable extended mode.  In extended mode, the remote server is made
6260 
     persistent.  The `R' packet is used to restart the program being
6261 
     debugged.
6262 
 
6263 
     Reply:
6264 
    `OK'
6265 
          The remote target both supports and has enabled extended mode.
6266 
 
6267 
`?'
6268 
     Indicate the reason the target halted.  The reply is the same as
6269 
     for step and continue.
6270 
 
6271 
     Reply: *Note Stop Reply Packets::, for the reply specifications.
6272 
 
6273 
`A ARGLEN,ARGNUM,ARG,...'
6274 
     Initialized `argv[]' array passed into program. ARGLEN specifies
6275 
     the number of bytes in the hex encoded byte stream ARG.  See
6276 
     `gdbserver' for more details.
6277 
 
6278 
     Reply:
6279 
    `OK'
6280 
          The arguments were set.
6281 
 
6282 
    `E NN'
6283 
          An error occurred.
6284 
 
6285 
`b BAUD'
6286 
     (Don't use this packet; its behavior is not well-defined.)  Change
6287 
     the serial line speed to BAUD.
6288 
 
6289 
     JTC: _When does the transport layer state change?  When it's
6290 
     received, or after the ACK is transmitted.  In either case, there
6291 
     are problems if the command or the acknowledgment packet is
6292 
     dropped._
6293 
 
6294 
     Stan: _If people really wanted to add something like this, and get
6295 
     it working for the first time, they ought to modify ser-unix.c to
6296 
     send some kind of out-of-band message to a specially-setup stub
6297 
     and have the switch happen "in between" packets, so that from
6298 
     remote protocol's point of view, nothing actually happened._
6299 
 
6300 
`B ADDR,MODE'
6301 
     Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
6302 
 
6303 
     Don't use this packet.  Use the `Z' and `z' packets instead (*note
6304 
     insert breakpoint or watchpoint packet::).
6305 
 
6306 
`c [ADDR]'
6307 
     Continue.  ADDR is address to resume.  If ADDR is omitted, resume
6308 
     at current address.
6309 
 
6310 
     Reply: *Note Stop Reply Packets::, for the reply specifications.
6311 
 
6312 
`C SIG[;ADDR]'
6313 
     Continue with signal SIG (hex signal number).  If `;ADDR' is
6314 
     omitted, resume at same address.
6315 
 
6316 
     Reply: *Note Stop Reply Packets::, for the reply specifications.
6317 
 
6318 
`d'
6319 
     Toggle debug flag.
6320 
 
6321 
     Don't use this packet; instead, define a general set packet (*note
6322 
     General Query Packets::).
6323 
 
6324 
`D'
6325 
     Detach GDB from the remote system.  Sent to the remote target
6326 
     before GDB disconnects via the `detach' command.
6327 
 
6328 
     Reply:
6329 
    `OK'
6330 
          for success
6331 
 
6332 
    `E NN'
6333 
          for an error
6334 
 
6335 
`F RC,EE,CF;XX'
6336 
     A reply from GDB to an `F' packet sent by the target.  This is
6337 
     part of the File-I/O protocol extension.  *Note File-I/O Remote
6338 
     Protocol Extension::, for the specification.
6339 
 
6340 
`g'
6341 
     Read general registers.
6342 
 
6343 
     Reply:
6344 
    `XX...'
6345 
          Each byte of register data is described by two hex digits.
6346 
          The bytes with the register are transmitted in target byte
6347 
          order.  The size of each register and their position within
6348 
          the `g' packet are determined by the GDB internal gdbarch
6349 
          functions `DEPRECATED_REGISTER_RAW_SIZE' and
6350 
          `gdbarch_register_name'.  The specification of several
6351 
          standard `g' packets is specified below.
6352 
 
6353 
    `E NN'
6354 
          for an error.
6355 
 
6356 
`G XX...'
6357 
     Write general registers.  *Note read registers packet::, for a
6358 
     description of the XX... data.
6359 
 
6360 
     Reply:
6361 
    `OK'
6362 
          for success
6363 
 
6364 
    `E NN'
6365 
          for an error
6366 
 
6367 
`H C T'
6368 
     Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
6369 
     C depends on the operation to be performed: it should be `c' for
6370 
     step and continue operations, `g' for other operations.  The
6371 
     thread designator T may be `-1', meaning all the threads, a thread
6372 
     number, or `0' which means pick any thread.
6373 
 
6374 
     Reply:
6375 
    `OK'
6376 
          for success
6377 
 
6378 
    `E NN'
6379 
          for an error
6380 
 
6381 
`i [ADDR[,NNN]]'
6382 
     Step the remote target by a single clock cycle.  If `,NNN' is
6383 
     present, cycle step NNN cycles.  If ADDR is present, cycle step
6384 
     starting at that address.
6385 
 
6386 
`I'
6387 
     Signal, then cycle step.  *Note step with signal packet::.  *Note
6388 
     cycle step packet::.
6389 
 
6390 
`k'
6391 
     Kill request.
6392 
 
6393 
     FIXME: _There is no description of how to operate when a specific
6394 
     thread context has been selected (i.e. does 'k' kill only that
6395 
     thread?)_.
6396 
 
6397 
`m ADDR,LENGTH'
6398 
     Read LENGTH bytes of memory starting at address ADDR.  Note that
6399 
     ADDR may not be aligned to any particular boundary.
6400 
 
6401 
     The stub need not use any particular size or alignment when
6402 
     gathering data from memory for the response; even if ADDR is
6403 
     word-aligned and LENGTH is a multiple of the word size, the stub
6404 
     is free to use byte accesses, or not.  For this reason, this
6405 
     packet may not be suitable for accessing memory-mapped I/O devices.
6406 
 
6407 
     Reply:
6408 
    `XX...'
6409 
          Memory contents; each byte is transmitted as a two-digit
6410 
          hexadecimal number.  The reply may contain fewer bytes than
6411 
          requested if the server was able to read only part of the
6412 
          region of memory.
6413 
 
6414 
    `E NN'
6415 
          NN is errno
6416 
 
6417 
`M ADDR,LENGTH:XX...'
6418 
     Write LENGTH bytes of memory starting at address ADDR.  XX... is
6419 
     the data; each byte is transmitted as a two-digit hexadecimal
6420 
     number.
6421 
 
6422 
     Reply:
6423 
    `OK'
6424 
          for success
6425 
 
6426 
    `E NN'
6427 
          for an error (this includes the case where only part of the
6428 
          data was written).
6429 
 
6430 
`p N'
6431 
     Read the value of register N; N is in hex.  *Note read registers
6432 
     packet::, for a description of how the returned register value is
6433 
     encoded.
6434 
 
6435 
     Reply:
6436 
    `XX...'
6437 
          the register's value
6438 
 
6439 
    `E NN'
6440 
          for an error
6441 
 
6442 
    `'
6443 
          Indicating an unrecognized QUERY.
6444 
 
6445 
`P N...=R...'
6446 
     Write register N... with value R....  The register number N is in
6447 
     hexadecimal, and R... contains two hex digits for each byte in the
6448 
     register (target byte order).
6449 
 
6450 
     Reply:
6451 
    `OK'
6452 
          for success
6453 
 
6454 
    `E NN'
6455 
          for an error
6456 
 
6457 
`q NAME PARAMS...'
6458 
`Q NAME PARAMS...'
6459 
     General query (`q') and set (`Q').  These packets are described
6460 
     fully in *Note General Query Packets::.
6461 
 
6462 
`r'
6463 
     Reset the entire system.
6464 
 
6465 
     Don't use this packet; use the `R' packet instead.
6466 
 
6467 
`R XX'
6468 
     Restart the program being debugged.  XX, while needed, is ignored.
6469 
     This packet is only available in extended mode (*note extended
6470 
     mode::).
6471 
 
6472 
     The `R' packet has no reply.
6473 
 
6474 
`s [ADDR]'
6475 
     Single step.  ADDR is the address at which to resume.  If ADDR is
6476 
     omitted, resume at same address.
6477 
 
6478 
     Reply: *Note Stop Reply Packets::, for the reply specifications.
6479 
 
6480 
`S SIG[;ADDR]'
6481 
     Step with signal.  This is analogous to the `C' packet, but
6482 
     requests a single-step, rather than a normal resumption of
6483 
     execution.
6484 
 
6485 
     Reply: *Note Stop Reply Packets::, for the reply specifications.
6486 
 
6487 
`t ADDR:PP,MM'
6488 
     Search backwards starting at address ADDR for a match with pattern
6489 
     PP and mask MM.  PP and MM are 4 bytes.  ADDR must be at least 3
6490 
     digits.
6491 
 
6492 
`T XX'
6493 
     Find out if the thread XX is alive.
6494 
 
6495 
     Reply:
6496 
    `OK'
6497 
          thread is still alive
6498 
 
6499 
    `E NN'
6500 
          thread is dead
6501 
 
6502 
`v'
6503 
     Packets starting with `v' are identified by a multi-letter name,
6504 
     up to the first `;' or `?' (or the end of the packet).
6505 
 
6506 
`vAttach;PID'
6507 
     Attach to a new process with the specified process ID.  PID is a
6508 
     hexadecimal integer identifying the process.  The attached process
6509 
     is stopped.
6510 
 
6511 
     This packet is only available in extended mode (*note extended
6512 
     mode::).
6513 
 
6514 
     Reply:
6515 
    `E NN'
6516 
          for an error
6517 
 
6518 
    `Any stop packet'
6519 
          for success (*note Stop Reply Packets::)
6520 
 
6521 
`vCont[;ACTION[:TID]]...'
6522 
     Resume the inferior, specifying different actions for each thread.
6523 
     If an action is specified with no TID, then it is applied to any
6524 
     threads that don't have a specific action specified; if no default
6525 
     action is specified then other threads should remain stopped.
6526 
     Specifying multiple default actions is an error; specifying no
6527 
     actions is also an error.  Thread IDs are specified in
6528 
     hexadecimal.  Currently supported actions are:
6529 
 
6530 
    `c'
6531 
          Continue.
6532 
 
6533 
    `C SIG'
6534 
          Continue with signal SIG.  SIG should be two hex digits.
6535 
 
6536 
    `s'
6537 
          Step.
6538 
 
6539 
    `S SIG'
6540 
          Step with signal SIG.  SIG should be two hex digits.
6541 
 
6542 
     The optional ADDR argument normally associated with these packets
6543 
     is not supported in `vCont'.
6544 
 
6545 
     Reply: *Note Stop Reply Packets::, for the reply specifications.
6546 
 
6547 
`vCont?'
6548 
     Request a list of actions supported by the `vCont' packet.
6549 
 
6550 
     Reply:
6551 
    `vCont[;ACTION...]'
6552 
          The `vCont' packet is supported.  Each ACTION is a supported
6553 
          command in the `vCont' packet.
6554 
 
6555 
    `'
6556 
          The `vCont' packet is not supported.
6557 
 
6558 
`vFile:OPERATION:PARAMETER...'
6559 
     Perform a file operation on the target system.  For details, see
6560 
     *Note Host I/O Packets::.
6561 
 
6562 
`vFlashErase:ADDR,LENGTH'
6563 
     Direct the stub to erase LENGTH bytes of flash starting at ADDR.
6564 
     The region may enclose any number of flash blocks, but its start
6565 
     and end must fall on block boundaries, as indicated by the flash
6566 
     block size appearing in the memory map (*note Memory Map
6567 
     Format::).  GDB groups flash memory programming operations
6568 
     together, and sends a `vFlashDone' request after each group; the
6569 
     stub is allowed to delay erase operation until the `vFlashDone'
6570 
     packet is received.
6571 
 
6572 
     Reply:
6573 
    `OK'
6574 
          for success
6575 
 
6576 
    `E NN'
6577 
          for an error
6578 
 
6579 
`vFlashWrite:ADDR:XX...'
6580 
     Direct the stub to write data to flash address ADDR.  The data is
6581 
     passed in binary form using the same encoding as for the `X'
6582 
     packet (*note Binary Data::).  The memory ranges specified by
6583 
     `vFlashWrite' packets preceding a `vFlashDone' packet must not
6584 
     overlap, and must appear in order of increasing addresses
6585 
     (although `vFlashErase' packets for higher addresses may already
6586 
     have been received; the ordering is guaranteed only between
6587 
     `vFlashWrite' packets).  If a packet writes to an address that was
6588 
     neither erased by a preceding `vFlashErase' packet nor by some
6589 
     other target-specific method, the results are unpredictable.
6590 
 
6591 
     Reply:
6592 
    `OK'
6593 
          for success
6594 
 
6595 
    `E.memtype'
6596 
          for vFlashWrite addressing non-flash memory
6597 
 
6598 
    `E NN'
6599 
          for an error
6600 
 
6601 
`vFlashDone'
6602 
     Indicate to the stub that flash programming operation is finished.
6603 
     The stub is permitted to delay or batch the effects of a group of
6604 
     `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
6605 
     packet is received.  The contents of the affected regions of flash
6606 
     memory are unpredictable until the `vFlashDone' request is
6607 
     completed.
6608 
 
6609 
`vRun;FILENAME[;ARGUMENT]...'
6610 
     Run the program FILENAME, passing it each ARGUMENT on its command
6611 
     line.  The file and arguments are hex-encoded strings.  If
6612 
     FILENAME is an empty string, the stub may use a default program
6613 
     (e.g. the last program run).  The program is created in the stopped
6614 
     state.
6615 
 
6616 
     This packet is only available in extended mode (*note extended
6617 
     mode::).
6618 
 
6619 
     Reply:
6620 
    `E NN'
6621 
          for an error
6622 
 
6623 
    `Any stop packet'
6624 
          for success (*note Stop Reply Packets::)
6625 
 
6626 
`X ADDR,LENGTH:XX...'
6627 
     Write data to memory, where the data is transmitted in binary.
6628 
     ADDR is address, LENGTH is number of bytes, `XX...' is binary data
6629 
     (*note Binary Data::).
6630 
 
6631 
     Reply:
6632 
    `OK'
6633 
          for success
6634 
 
6635 
    `E NN'
6636 
          for an error
6637 
 
6638 
`z TYPE,ADDR,LENGTH'
6639 
`Z TYPE,ADDR,LENGTH'
6640 
     Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
6641 
     starting at address ADDRESS and covering the next LENGTH bytes.
6642 
 
6643 
     Each breakpoint and watchpoint packet TYPE is documented
6644 
     separately.
6645 
 
6646 
     _Implementation notes: A remote target shall return an empty string
6647 
     for an unrecognized breakpoint or watchpoint packet TYPE.  A
6648 
     remote target shall support either both or neither of a given
6649 
     `ZTYPE...' and `zTYPE...' packet pair.  To avoid potential
6650 
     problems with duplicate packets, the operations should be
6651 
     implemented in an idempotent way._
6652 
 
6653 
`z0,ADDR,LENGTH'
6654 
`Z0,ADDR,LENGTH'
6655 
     Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
6656 
     of size LENGTH.
6657 
 
6658 
     A memory breakpoint is implemented by replacing the instruction at
6659 
     ADDR with a software breakpoint or trap instruction.  The LENGTH
6660 
     is used by targets that indicates the size of the breakpoint (in
6661 
     bytes) that should be inserted (e.g., the ARM and MIPS can insert
6662 
     either a 2 or 4 byte breakpoint).
6663 
 
6664 
     _Implementation note: It is possible for a target to copy or move
6665 
     code that contains memory breakpoints (e.g., when implementing
6666 
     overlays).  The behavior of this packet, in the presence of such a
6667 
     target, is not defined._
6668 
 
6669 
     Reply:
6670 
    `OK'
6671 
          success
6672 
 
6673 
    `'
6674 
          not supported
6675 
 
6676 
    `E NN'
6677 
          for an error
6678 
 
6679 
`z1,ADDR,LENGTH'
6680 
`Z1,ADDR,LENGTH'
6681 
     Insert (`Z1') or remove (`z1') a hardware breakpoint at address
6682 
     ADDR of size LENGTH.
6683 
 
6684 
     A hardware breakpoint is implemented using a mechanism that is not
6685 
     dependant on being able to modify the target's memory.
6686 
 
6687 
     _Implementation note: A hardware breakpoint is not affected by code
6688 
     movement._
6689 
 
6690 
     Reply:
6691 
    `OK'
6692 
          success
6693 
 
6694 
    `'
6695 
          not supported
6696 
 
6697 
    `E NN'
6698 
          for an error
6699 
 
6700 
`z2,ADDR,LENGTH'
6701 
`Z2,ADDR,LENGTH'
6702 
     Insert (`Z2') or remove (`z2') a write watchpoint.
6703 
 
6704 
     Reply:
6705 
    `OK'
6706 
          success
6707 
 
6708 
    `'
6709 
          not supported
6710 
 
6711 
    `E NN'
6712 
          for an error
6713 
 
6714 
`z3,ADDR,LENGTH'
6715 
`Z3,ADDR,LENGTH'
6716 
     Insert (`Z3') or remove (`z3') a read watchpoint.
6717 
 
6718 
     Reply:
6719 
    `OK'
6720 
          success
6721 
 
6722 
    `'
6723 
          not supported
6724 
 
6725 
    `E NN'
6726 
          for an error
6727 
 
6728 
`z4,ADDR,LENGTH'
6729 
`Z4,ADDR,LENGTH'
6730 
     Insert (`Z4') or remove (`z4') an access watchpoint.
6731 
 
6732 
     Reply:
6733 
    `OK'
6734 
          success
6735 
 
6736 
    `'
6737 
          not supported
6738 
 
6739 
    `E NN'
6740 
          for an error
6741 
 
6742 
 
6743 

6744 
File: gdb.info,  Node: Stop Reply Packets,  Next: General Query Packets,  Prev: Packets,  Up: Remote Protocol
6745 
 
6746 
D.3 Stop Reply Packets
6747 
======================
6748 
 
6749 
The `C', `c', `S', `s' and `?' packets can receive any of the below as
6750 
a reply.  In the case of the `C', `c', `S' and `s' packets, that reply
6751 
is only returned when the target halts.  In the below the exact meaning
6752 
of "signal number" is defined by the header `include/gdb/signals.h' in
6753 
the GDB source code.
6754 
 
6755 
   As in the description of request packets, we include spaces in the
6756 
reply templates for clarity; these are not part of the reply packet's
6757 
syntax.  No GDB stop reply packet uses spaces to separate its
6758 
components.
6759 
 
6760 
`S AA'
6761 
     The program received signal number AA (a two-digit hexadecimal
6762 
     number).  This is equivalent to a `T' response with no N:R pairs.
6763 
 
6764 
`T AA N1:R1;N2:R2;...'
6765 
     The program received signal number AA (a two-digit hexadecimal
6766 
     number).  This is equivalent to an `S' response, except that the
6767 
     `N:R' pairs can carry values of important registers and other
6768 
     information directly in the stop reply packet, reducing round-trip
6769 
     latency.  Single-step and breakpoint traps are reported this way.
6770 
     Each `N:R' pair is interpreted as follows:
6771 
 
6772 
        * If N is a hexadecimal number, it is a register number, and the
6773 
          corresponding R gives that register's value.  R is a series
6774 
          of bytes in target byte order, with each byte given by a
6775 
          two-digit hex number.
6776 
 
6777 
        * If N is `thread', then R is the thread process ID, in hex.
6778 
 
6779 
        * If N is a recognized "stop reason", it describes a more
6780 
          specific event that stopped the target.  The currently
6781 
          defined stop reasons are listed below.  AA should be `05',
6782 
          the trap signal.  At most one stop reason should be present.
6783 
 
6784 
        * Otherwise, GDB should ignore this `N:R' pair and go on to the
6785 
          next; this allows us to extend the protocol in the future.
6786 
 
6787 
     The currently defined stop reasons are:
6788 
 
6789 
    `watch'
6790 
    `rwatch'
6791 
    `awatch'
6792 
          The packet indicates a watchpoint hit, and R is the data
6793 
          address, in hex.
6794 
 
6795 
    `library'
6796 
          The packet indicates that the loaded libraries have changed.
6797 
          GDB should use `qXfer:libraries:read' to fetch a new list of
6798 
          loaded libraries.  R is ignored.
6799 
 
6800 
`W AA'
6801 
     The process exited, and AA is the exit status.  This is only
6802 
     applicable to certain targets.
6803 
 
6804 
`X AA'
6805 
     The process terminated with signal AA.
6806 
 
6807 
`O XX...'
6808 
     `XX...' is hex encoding of ASCII data, to be written as the
6809 
     program's console output.  This can happen at any time while the
6810 
     program is running and the debugger should continue to wait for
6811 
     `W', `T', etc.
6812 
 
6813 
`F CALL-ID,PARAMETER...'
6814 
     CALL-ID is the identifier which says which host system call should
6815 
     be called.  This is just the name of the function.  Translation
6816 
     into the correct system call is only applicable as it's defined in
6817 
     GDB.  *Note File-I/O Remote Protocol Extension::, for a list of
6818 
     implemented system calls.
6819 
 
6820 
     `PARAMETER...' is a list of parameters as defined for this very
6821 
     system call.
6822 
 
6823 
     The target replies with this packet when it expects GDB to call a
6824 
     host system call on behalf of the target.  GDB replies with an
6825 
     appropriate `F' packet and keeps up waiting for the next reply
6826 
     packet from the target.  The latest `C', `c', `S' or `s' action is
6827 
     expected to be continued.  *Note File-I/O Remote Protocol
6828 
     Extension::, for more details.
6829 
 
6830 
 
6831 

6832 
File: gdb.info,  Node: General Query Packets,  Next: Register Packet Format,  Prev: Stop Reply Packets,  Up: Remote Protocol
6833 
 
6834 
D.4 General Query Packets
6835 
=========================
6836 
 
6837 
Packets starting with `q' are "general query packets"; packets starting
6838 
with `Q' are "general set packets".  General query and set packets are
6839 
a semi-unified form for retrieving and sending information to and from
6840 
the stub.
6841 
 
6842 
   The initial letter of a query or set packet is followed by a name
6843 
indicating what sort of thing the packet applies to.  For example, GDB
6844 
may use a `qSymbol' packet to exchange symbol definitions with the
6845 
stub.  These packet names follow some conventions:
6846 
 
6847 
   * The name must not contain commas, colons or semicolons.
6848 
 
6849 
   * Most GDB query and set packets have a leading upper case letter.
6850 
 
6851 
   * The names of custom vendor packets should use a company prefix, in
6852 
     lower case, followed by a period.  For example, packets designed at
6853 
     the Acme Corporation might begin with `qacme.foo' (for querying
6854 
     foos) or `Qacme.bar' (for setting bars).
6855 
 
6856 
   The name of a query or set packet should be separated from any
6857 
parameters by a `:'; the parameters themselves should be separated by
6858 
`,' or `;'.  Stubs must be careful to match the full packet name, and
6859 
check for a separator or the end of the packet, in case two packet
6860 
names share a common prefix.  New packets should not begin with `qC',
6861 
`qP', or `qL'(1).
6862 
 
6863 
   Like the descriptions of the other packets, each description here
6864 
has a template showing the packet's overall syntax, followed by an
6865 
explanation of the packet's meaning.  We include spaces in some of the
6866 
templates for clarity; these are not part of the packet's syntax.  No
6867 
GDB packet uses spaces to separate its components.
6868 
 
6869 
   Here are the currently defined query and set packets:
6870 
 
6871 
`qC'
6872 
     Return the current thread id.
6873 
 
6874 
     Reply:
6875 
    `QC PID'
6876 
          Where PID is an unsigned hexadecimal process id.
6877 
 
6878 
    `(anything else)'
6879 
          Any other reply implies the old pid.
6880 
 
6881 
`qCRC:ADDR,LENGTH'
6882 
     Compute the CRC checksum of a block of memory.  Reply:
6883 
    `E NN'
6884 
          An error (such as memory fault)
6885 
 
6886 
    `C CRC32'
6887 
          The specified memory region's checksum is CRC32.
6888 
 
6889 
`qfThreadInfo'
6890 
`qsThreadInfo'
6891 
     Obtain a list of all active thread ids from the target (OS).
6892 
     Since there may be too many active threads to fit into one reply
6893 
     packet, this query works iteratively: it may require more than one
6894 
     query/reply sequence to obtain the entire list of threads.  The
6895 
     first query of the sequence will be the `qfThreadInfo' query;
6896 
     subsequent queries in the sequence will be the `qsThreadInfo'
6897 
     query.
6898 
 
6899 
     NOTE: This packet replaces the `qL' query (see below).
6900 
 
6901 
     Reply:
6902 
    `m ID'
6903 
          A single thread id
6904 
 
6905 
    `m ID,ID...'
6906 
          a comma-separated list of thread ids
6907 
 
6908 
    `l'
6909 
          (lower case letter `L') denotes end of list.
6910 
 
6911 
     In response to each query, the target will reply with a list of
6912 
     one or more thread ids, in big-endian unsigned hex, separated by
6913 
     commas.  GDB will respond to each reply with a request for more
6914 
     thread ids (using the `qs' form of the query), until the target
6915 
     responds with `l' (lower-case el, for "last").
6916 
 
6917 
`qGetTLSAddr:THREAD-ID,OFFSET,LM'
6918 
     Fetch the address associated with thread local storage specified
6919 
     by THREAD-ID, OFFSET, and LM.
6920 
 
6921 
     THREAD-ID is the (big endian, hex encoded) thread id associated
6922 
     with the thread for which to fetch the TLS address.
6923 
 
6924 
     OFFSET is the (big endian, hex encoded) offset associated with the
6925 
     thread local variable.  (This offset is obtained from the debug
6926 
     information associated with the variable.)
6927 
 
6928 
     LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
6929 
     the load module associated with the thread local storage.  For
6930 
     example, a GNU/Linux system will pass the link map address of the
6931 
     shared object associated with the thread local storage under
6932 
     consideration.  Other operating environments may choose to
6933 
     represent the load module differently, so the precise meaning of
6934 
     this parameter will vary.
6935 
 
6936 
     Reply:
6937 
    `XX...'
6938 
          Hex encoded (big endian) bytes representing the address of
6939 
          the thread local storage requested.
6940 
 
6941 
    `E NN'
6942 
          An error occurred.  NN are hex digits.
6943 
 
6944 
    `'
6945 
          An empty reply indicates that `qGetTLSAddr' is not supported
6946 
          by the stub.
6947 
 
6948 
`qL STARTFLAG THREADCOUNT NEXTTHREAD'
6949 
     Obtain thread information from RTOS.  Where: STARTFLAG (one hex
6950 
     digit) is one to indicate the first query and zero to indicate a
6951 
     subsequent query; THREADCOUNT (two hex digits) is the maximum
6952 
     number of threads the response packet can contain; and NEXTTHREAD
6953 
     (eight hex digits), for subsequent queries (STARTFLAG is zero), is
6954 
     returned in the response as ARGTHREAD.
6955 
 
6956 
     Don't use this packet; use the `qfThreadInfo' query instead (see
6957 
     above).
6958 
 
6959 
     Reply:
6960 
    `qM COUNT DONE ARGTHREAD THREAD...'
6961 
          Where: COUNT (two hex digits) is the number of threads being
6962 
          returned; DONE (one hex digit) is zero to indicate more
6963 
          threads and one indicates no further threads; ARGTHREADID
6964 
          (eight hex digits) is NEXTTHREAD from the request packet;
6965 
          THREAD...  is a sequence of thread IDs from the target.
6966 
          THREADID (eight hex digits).  See
6967 
          `remote.c:parse_threadlist_response()'.
6968 
 
6969 
`qOffsets'
6970 
     Get section offsets that the target used when relocating the
6971 
     downloaded image.
6972 
 
6973 
     Reply:
6974 
    `Text=XXX;Data=YYY[;Bss=ZZZ]'
6975 
          Relocate the `Text' section by XXX from its original address.
6976 
          Relocate the `Data' section by YYY from its original address.
6977 
          If the object file format provides segment information (e.g.
6978 
          ELF `PT_LOAD' program headers), GDB will relocate entire
6979 
          segments by the supplied offsets.
6980 
 
6981 
          _Note: while a `Bss' offset may be included in the response,
6982 
          GDB ignores this and instead applies the `Data' offset to the
6983 
          `Bss' section._
6984 
 
6985 
    `TextSeg=XXX[;DataSeg=YYY]'
6986 
          Relocate the first segment of the object file, which
6987 
          conventionally contains program code, to a starting address
6988 
          of XXX.  If `DataSeg' is specified, relocate the second
6989 
          segment, which conventionally contains modifiable data, to a
6990 
          starting address of YYY.  GDB will report an error if the
6991 
          object file does not contain segment information, or does not
6992 
          contain at least as many segments as mentioned in the reply.
6993 
          Extra segments are kept at fixed offsets relative to the last
6994 
          relocated segment.
6995 
 
6996 
`qP MODE THREADID'
6997 
     Returns information on THREADID.  Where: MODE is a hex encoded 32
6998 
     bit mode; THREADID is a hex encoded 64 bit thread ID.
6999 
 
7000 
     Don't use this packet; use the `qThreadExtraInfo' query instead
7001 
     (see below).
7002 
 
7003 
     Reply: see `remote.c:remote_unpack_thread_info_response()'.
7004 
 
7005 
`QPassSignals: SIGNAL [;SIGNAL]...'
7006 
     Each listed SIGNAL should be passed directly to the inferior
7007 
     process.  Signals are numbered identically to continue packets and
7008 
     stop replies (*note Stop Reply Packets::).  Each SIGNAL list item
7009 
     should be strictly greater than the previous item.  These signals
7010 
     do not need to stop the inferior, or be reported to GDB.  All
7011 
     other signals should be reported to GDB.  Multiple `QPassSignals'
7012 
     packets do not combine; any earlier `QPassSignals' list is
7013 
     completely replaced by the new list.  This packet improves
7014 
     performance when using `handle SIGNAL nostop noprint pass'.
7015 
 
7016 
     Reply:
7017 
    `OK'
7018 
          The request succeeded.
7019 
 
7020 
    `E NN'
7021 
          An error occurred.  NN are hex digits.
7022 
 
7023 
    `'
7024 
          An empty reply indicates that `QPassSignals' is not supported
7025 
          by the stub.
7026 
 
7027 
     Use of this packet is controlled by the `set remote pass-signals'
7028 
     command (*note set remote pass-signals: Remote Configuration.).
7029 
     This packet is not probed by default; the remote stub must request
7030 
     it, by supplying an appropriate `qSupported' response (*note
7031 
     qSupported::).
7032 
 
7033 
`qRcmd,COMMAND'
7034 
     COMMAND (hex encoded) is passed to the local interpreter for
7035 
     execution.  Invalid commands should be reported using the output
7036 
     string.  Before the final result packet, the target may also
7037 
     respond with a number of intermediate `OOUTPUT' console output
7038 
     packets.  _Implementors should note that providing access to a
7039 
     stubs's interpreter may have security implications_.
7040 
 
7041 
     Reply:
7042 
    `OK'
7043 
          A command response with no output.
7044 
 
7045 
    `OUTPUT'
7046 
          A command response with the hex encoded output string OUTPUT.
7047 
 
7048 
    `E NN'
7049 
          Indicate a badly formed request.
7050 
 
7051 
    `'
7052 
          An empty reply indicates that `qRcmd' is not recognized.
7053 
 
7054 
     (Note that the `qRcmd' packet's name is separated from the command
7055 
     by a `,', not a `:', contrary to the naming conventions above.
7056 
     Please don't use this packet as a model for new packets.)
7057 
 
7058 
`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
7059 
     Tell the remote stub about features supported by GDB, and query
7060 
     the stub for features it supports.  This packet allows GDB and the
7061 
     remote stub to take advantage of each others' features.
7062 
     `qSupported' also consolidates multiple feature probes at startup,
7063 
     to improve GDB performance--a single larger packet performs better
7064 
     than multiple smaller probe packets on high-latency links.  Some
7065 
     features may enable behavior which must not be on by default, e.g.
7066 
     because it would confuse older clients or stubs.  Other features
7067 
     may describe packets which could be automatically probed for, but
7068 
     are not.  These features must be reported before GDB will use
7069 
     them.  This "default unsupported" behavior is not appropriate for
7070 
     all packets, but it helps to keep the initial connection time
7071 
     under control with new versions of GDB which support increasing
7072 
     numbers of packets.
7073 
 
7074 
     Reply:
7075 
    `STUBFEATURE [;STUBFEATURE]...'
7076 
          The stub supports or does not support each returned
7077 
          STUBFEATURE, depending on the form of each STUBFEATURE (see
7078 
          below for the possible forms).
7079 
 
7080 
    `'
7081 
          An empty reply indicates that `qSupported' is not recognized,
7082 
          or that no features needed to be reported to GDB.
7083 
 
7084 
     The allowed forms for each feature (either a GDBFEATURE in the
7085 
     `qSupported' packet, or a STUBFEATURE in the response) are:
7086 
 
7087 
    `NAME=VALUE'
7088 
          The remote protocol feature NAME is supported, and associated
7089 
          with the specified VALUE.  The format of VALUE depends on the
7090 
          feature, but it must not include a semicolon.
7091 
 
7092 
    `NAME+'
7093 
          The remote protocol feature NAME is supported, and does not
7094 
          need an associated value.
7095 
 
7096 
    `NAME-'
7097 
          The remote protocol feature NAME is not supported.
7098 
 
7099 
    `NAME?'
7100 
          The remote protocol feature NAME may be supported, and GDB
7101 
          should auto-detect support in some other way when it is
7102 
          needed.  This form will not be used for GDBFEATURE
7103 
          notifications, but may be used for STUBFEATURE responses.
7104 
 
7105 
     Whenever the stub receives a `qSupported' request, the supplied
7106 
     set of GDB features should override any previous request.  This
7107 
     allows GDB to put the stub in a known state, even if the stub had
7108 
     previously been communicating with a different version of GDB.
7109 
 
7110 
     No values of GDBFEATURE (for the packet sent by GDB) are defined
7111 
     yet.  Stubs should ignore any unknown values for GDBFEATURE.  Any
7112 
     GDB which sends a `qSupported' packet supports receiving packets
7113 
     of unlimited length (earlier versions of GDB may reject overly
7114 
     long responses).  Values for GDBFEATURE may be defined in the
7115 
     future to let the stub take advantage of new features in GDB, e.g.
7116 
     incompatible improvements in the remote protocol--support for
7117 
     unlimited length responses would be a GDBFEATURE example, if it
7118 
     were not implied by the `qSupported' query.  The stub's reply
7119 
     should be independent of the GDBFEATURE entries sent by GDB; first
7120 
     GDB describes all the features it supports, and then the stub
7121 
     replies with all the features it supports.
7122 
 
7123 
     Similarly, GDB will silently ignore unrecognized stub feature
7124 
     responses, as long as each response uses one of the standard forms.
7125 
 
7126 
     Some features are flags.  A stub which supports a flag feature
7127 
     should respond with a `+' form response.  Other features require
7128 
     values, and the stub should respond with an `=' form response.
7129 
 
7130 
     Each feature has a default value, which GDB will use if
7131 
     `qSupported' is not available or if the feature is not mentioned
7132 
     in the `qSupported' response.  The default values are fixed; a
7133 
     stub is free to omit any feature responses that match the defaults.
7134 
 
7135 
     Not all features can be probed, but for those which can, the
7136 
     probing mechanism is useful: in some cases, a stub's internal
7137 
     architecture may not allow the protocol layer to know some
7138 
     information about the underlying target in advance.  This is
7139 
     especially common in stubs which may be configured for multiple
7140 
     targets.
7141 
 
7142 
     These are the currently defined stub features and their properties:
7143 
 
7144 
     Feature Name            Value         Default  Probe Allowed
7145 
                             Required
7146 
     `PacketSize'            Yes           `-'      No
7147 
     `qXfer:auxv:read'       No            `-'      Yes
7148 
     `qXfer:features:read'   No            `-'      Yes
7149 
     `qXfer:libraries:read'  No            `-'      Yes
7150 
     `qXfer:memory-map:read' No            `-'      Yes
7151 
     `qXfer:spu:read'        No            `-'      Yes
7152 
     `qXfer:spu:write'       No            `-'      Yes
7153 
     `QPassSignals'          No            `-'      Yes
7154 
 
7155 
     These are the currently defined stub features, in more detail:
7156 
 
7157 
    `PacketSize=BYTES'
7158 
          The remote stub can accept packets up to at least BYTES in
7159 
          length.  GDB will send packets up to this size for bulk
7160 
          transfers, and will never send larger packets.  This is a
7161 
          limit on the data characters in the packet, including the
7162 
          frame and checksum.  There is no trailing NUL byte in a
7163 
          remote protocol packet; if the stub stores packets in a
7164 
          NUL-terminated format, it should allow an extra byte in its
7165 
          buffer for the NUL.  If this stub feature is not supported,
7166 
          GDB guesses based on the size of the `g' packet response.
7167 
 
7168 
    `qXfer:auxv:read'
7169 
          The remote stub understands the `qXfer:auxv:read' packet
7170 
          (*note qXfer auxiliary vector read::).
7171 
 
7172 
    `qXfer:features:read'
7173 
          The remote stub understands the `qXfer:features:read' packet
7174 
          (*note qXfer target description read::).
7175 
 
7176 
    `qXfer:libraries:read'
7177 
          The remote stub understands the `qXfer:libraries:read' packet
7178 
          (*note qXfer library list read::).
7179 
 
7180 
    `qXfer:memory-map:read'
7181 
          The remote stub understands the `qXfer:memory-map:read' packet
7182 
          (*note qXfer memory map read::).
7183 
 
7184 
    `qXfer:spu:read'
7185 
          The remote stub understands the `qXfer:spu:read' packet
7186 
          (*note qXfer spu read::).
7187 
 
7188 
    `qXfer:spu:write'
7189 
          The remote stub understands the `qXfer:spu:write' packet
7190 
          (*note qXfer spu write::).
7191 
 
7192 
    `QPassSignals'
7193 
          The remote stub understands the `QPassSignals' packet (*note
7194 
          QPassSignals::).
7195 
 
7196 
 
7197 
`qSymbol::'
7198 
     Notify the target that GDB is prepared to serve symbol lookup
7199 
     requests.  Accept requests from the target for the values of
7200 
     symbols.
7201 
 
7202 
     Reply:
7203 
    `OK'
7204 
          The target does not need to look up any (more) symbols.
7205 
 
7206 
    `qSymbol:SYM_NAME'
7207 
          The target requests the value of symbol SYM_NAME (hex
7208 
          encoded).  GDB may provide the value by using the
7209 
          `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
7210 
 
7211 
`qSymbol:SYM_VALUE:SYM_NAME'
7212 
     Set the value of SYM_NAME to SYM_VALUE.
7213 
 
7214 
     SYM_NAME (hex encoded) is the name of a symbol whose value the
7215 
     target has previously requested.
7216 
 
7217 
     SYM_VALUE (hex) is the value for symbol SYM_NAME.  If GDB cannot
7218 
     supply a value for SYM_NAME, then this field will be empty.
7219 
 
7220 
     Reply:
7221 
    `OK'
7222 
          The target does not need to look up any (more) symbols.
7223 
 
7224 
    `qSymbol:SYM_NAME'
7225 
          The target requests the value of a new symbol SYM_NAME (hex
7226 
          encoded).  GDB will continue to supply the values of symbols
7227 
          (if available), until the target ceases to request them.
7228 
 
7229 
`QTDP'
7230 
`QTFrame'
7231 
     *Note Tracepoint Packets::.
7232 
 
7233 
`qThreadExtraInfo,ID'
7234 
     Obtain a printable string description of a thread's attributes from
7235 
     the target OS.  ID is a thread-id in big-endian hex.  This string
7236 
     may contain anything that the target OS thinks is interesting for
7237 
     GDB to tell the user about the thread.  The string is displayed in
7238 
     GDB's `info threads' display.  Some examples of possible thread
7239 
     extra info strings are `Runnable', or `Blocked on Mutex'.
7240 
 
7241 
     Reply:
7242 
    `XX...'
7243 
          Where `XX...' is a hex encoding of ASCII data, comprising the
7244 
          printable string containing the extra information about the
7245 
          thread's attributes.
7246 
 
7247 
     (Note that the `qThreadExtraInfo' packet's name is separated from
7248 
     the command by a `,', not a `:', contrary to the naming
7249 
     conventions above.  Please don't use this packet as a model for new
7250 
     packets.)
7251 
 
7252 
`QTStart'
7253 
`QTStop'
7254 
`QTinit'
7255 
`QTro'
7256 
`qTStatus'
7257 
     *Note Tracepoint Packets::.
7258 
 
7259 
`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
7260 
     Read uninterpreted bytes from the target's special data area
7261 
     identified by the keyword OBJECT.  Request LENGTH bytes starting
7262 
     at OFFSET bytes into the data.  The content and encoding of ANNEX
7263 
     is specific to OBJECT; it can supply additional details about what
7264 
     data to access.
7265 
 
7266 
     Here are the specific requests of this form defined so far.  All
7267 
     `qXfer:OBJECT:read:...' requests use the same reply formats,
7268 
     listed below.
7269 
 
7270 
    `qXfer:auxv:read::OFFSET,LENGTH'
7271 
          Access the target's "auxiliary vector".  *Note auxiliary
7272 
          vector: OS Information.  Note ANNEX must be empty.
7273 
 
7274 
          This packet is not probed by default; the remote stub must
7275 
          request it, by supplying an appropriate `qSupported' response
7276 
          (*note qSupported::).
7277 
 
7278 
    `qXfer:features:read:ANNEX:OFFSET,LENGTH'
7279 
          Access the "target description".  *Note Target
7280 
          Descriptions::.  The annex specifies which XML document to
7281 
          access.  The main description is always loaded from the
7282 
          `target.xml' annex.
7283 
 
7284 
          This packet is not probed by default; the remote stub must
7285 
          request it, by supplying an appropriate `qSupported' response
7286 
          (*note qSupported::).
7287 
 
7288 
    `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
7289 
          Access the target's list of loaded libraries.  *Note Library
7290 
          List Format::.  The annex part of the generic `qXfer' packet
7291 
          must be empty (*note qXfer read::).
7292 
 
7293 
          Targets which maintain a list of libraries in the program's
7294 
          memory do not need to implement this packet; it is designed
7295 
          for platforms where the operating system manages the list of
7296 
          loaded libraries.
7297 
 
7298 
          This packet is not probed by default; the remote stub must
7299 
          request it, by supplying an appropriate `qSupported' response
7300 
          (*note qSupported::).
7301 
 
7302 
    `qXfer:memory-map:read::OFFSET,LENGTH'
7303 
          Access the target's "memory-map".  *Note Memory Map Format::.
7304 
          The annex part of the generic `qXfer' packet must be empty
7305 
          (*note qXfer read::).
7306 
 
7307 
          This packet is not probed by default; the remote stub must
7308 
          request it, by supplying an appropriate `qSupported' response
7309 
          (*note qSupported::).
7310 
 
7311 
    `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
7312 
          Read contents of an `spufs' file on the target system.  The
7313 
          annex specifies which file to read; it must be of the form
7314 
          `ID/NAME', where ID specifies an SPU context ID in the target
7315 
          process, and NAME identifes the `spufs' file in that context
7316 
          to be accessed.
7317 
 
7318 
          This packet is not probed by default; the remote stub must
7319 
          request it, by supplying an appropriate `qSupported' response
7320 
          (*note qSupported::).
7321 
 
7322 
     Reply:
7323 
    `m DATA'
7324 
          Data DATA (*note Binary Data::) has been read from the
7325 
          target.  There may be more data at a higher address (although
7326 
          it is permitted to return `m' even for the last valid block
7327 
          of data, as long as at least one byte of data was read).
7328 
          DATA may have fewer bytes than the LENGTH in the request.
7329 
 
7330 
    `l DATA'
7331 
          Data DATA (*note Binary Data::) has been read from the target.
7332 
          There is no more data to be read.  DATA may have fewer bytes
7333 
          than the LENGTH in the request.
7334 
 
7335 
    `l'
7336 
          The OFFSET in the request is at the end of the data.  There
7337 
          is no more data to be read.
7338 
 
7339 
    `E00'
7340 
          The request was malformed, or ANNEX was invalid.
7341 
 
7342 
    `E NN'
7343 
          The offset was invalid, or there was an error encountered
7344 
          reading the data.  NN is a hex-encoded `errno' value.
7345 
 
7346 
    `'
7347 
          An empty reply indicates the OBJECT string was not recognized
7348 
          by the stub, or that the object does not support reading.
7349 
 
7350 
`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
7351 
     Write uninterpreted bytes into the target's special data area
7352 
     identified by the keyword OBJECT, starting at OFFSET bytes into
7353 
     the data.  DATA... is the binary-encoded data (*note Binary
7354 
     Data::) to be written.  The content and encoding of ANNEX is
7355 
     specific to OBJECT; it can supply additional details about what
7356 
     data to access.
7357 
 
7358 
     Here are the specific requests of this form defined so far.  All
7359 
     `qXfer:OBJECT:write:...' requests use the same reply formats,
7360 
     listed below.
7361 
 
7362 
    `qXfer:SPU:write:ANNEX:OFFSET:DATA...'
7363 
          Write DATA to an `spufs' file on the target system.  The
7364 
          annex specifies which file to write; it must be of the form
7365 
          `ID/NAME', where ID specifies an SPU context ID in the target
7366 
          process, and NAME identifes the `spufs' file in that context
7367 
          to be accessed.
7368 
 
7369 
          This packet is not probed by default; the remote stub must
7370 
          request it, by supplying an appropriate `qSupported' response
7371 
          (*note qSupported::).
7372 
 
7373 
     Reply:
7374 
    `NN'
7375 
          NN (hex encoded) is the number of bytes written.  This may be
7376 
          fewer bytes than supplied in the request.
7377 
 
7378 
    `E00'
7379 
          The request was malformed, or ANNEX was invalid.
7380 
 
7381 
    `E NN'
7382 
          The offset was invalid, or there was an error encountered
7383 
          writing the data.  NN is a hex-encoded `errno' value.
7384 
 
7385 
    `'
7386 
          An empty reply indicates the OBJECT string was not recognized
7387 
          by the stub, or that the object does not support writing.
7388 
 
7389 
`qXfer:OBJECT:OPERATION:...'
7390 
     Requests of this form may be added in the future.  When a stub does
7391 
     not recognize the OBJECT keyword, or its support for OBJECT does
7392 
     not recognize the OPERATION keyword, the stub must respond with an
7393 
     empty packet.
7394 
 
7395 
 
7396 
   ---------- Footnotes ----------
7397 
 
7398 
   (1) The `qP' and `qL' packets predate these conventions, and have
7399 
arguments without any terminator for the packet name; we suspect they
7400 
are in widespread use in places that are difficult to upgrade.  The
7401 
`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
7402 
are known to not check for the end of the packet.
7403 
 
7404 

7405 
File: gdb.info,  Node: Register Packet Format,  Next: Tracepoint Packets,  Prev: General Query Packets,  Up: Remote Protocol
7406 
 
7407 
D.5 Register Packet Format
7408 
==========================
7409 
 
7410 
The following `g'/`G' packets have previously been defined.  In the
7411 
below, some thirty-two bit registers are transferred as sixty-four
7412 
bits.  Those registers should be zero/sign extended (which?)  to fill
7413 
the space allocated.  Register bytes are transferred in target byte
7414 
order.  The two nibbles within a register byte are transferred
7415 
most-significant - least-significant.
7416 
 
7417 
MIPS32
7418 
     All registers are transferred as thirty-two bit quantities in the
7419 
     order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
7420 
     floating-point registers; fsr; fir; fp.
7421 
 
7422 
MIPS64
7423 
     All registers are transferred as sixty-four bit quantities
7424 
     (including thirty-two bit registers such as `sr').  The ordering
7425 
     is the same as `MIPS32'.
7426 
 
7427 
 
7428 

7429 
File: gdb.info,  Node: Tracepoint Packets,  Next: Host I/O Packets,  Prev: Register Packet Format,  Up: Remote Protocol
7430 
 
7431 
D.6 Tracepoint Packets
7432 
======================
7433 
 
7434 
Here we describe the packets GDB uses to implement tracepoints (*note
7435 
Tracepoints::).
7436 
 
7437 
`QTDP:N:ADDR:ENA:STEP:PASS[-]'
7438 
     Create a new tracepoint, number N, at ADDR.  If ENA is `E', then
7439 
     the tracepoint is enabled; if it is `D', then the tracepoint is
7440 
     disabled.  STEP is the tracepoint's step count, and PASS is its
7441 
     pass count.  If the trailing `-' is present, further `QTDP'
7442 
     packets will follow to specify this tracepoint's actions.
7443 
 
7444 
     Replies:
7445 
    `OK'
7446 
          The packet was understood and carried out.
7447 
 
7448 
    `'
7449 
          The packet was not recognized.
7450 
 
7451 
`QTDP:-N:ADDR:[S]ACTION...[-]'
7452 
     Define actions to be taken when a tracepoint is hit.  N and ADDR
7453 
     must be the same as in the initial `QTDP' packet for this
7454 
     tracepoint.  This packet may only be sent immediately after
7455 
     another `QTDP' packet that ended with a `-'.  If the trailing `-'
7456 
     is present, further `QTDP' packets will follow, specifying more
7457 
     actions for this tracepoint.
7458 
 
7459 
     In the series of action packets for a given tracepoint, at most one
7460 
     can have an `S' before its first ACTION.  If such a packet is
7461 
     sent, it and the following packets define "while-stepping"
7462 
     actions.  Any prior packets define ordinary actions -- that is,
7463 
     those taken when the tracepoint is first hit.  If no action packet
7464 
     has an `S', then all the packets in the series specify ordinary
7465 
     tracepoint actions.
7466 
 
7467 
     The `ACTION...' portion of the packet is a series of actions,
7468 
     concatenated without separators.  Each action has one of the
7469 
     following forms:
7470 
 
7471 
    `R MASK'
7472 
          Collect the registers whose bits are set in MASK.  MASK is a
7473 
          hexadecimal number whose I'th bit is set if register number I
7474 
          should be collected.  (The least significant bit is numbered
7475 
          zero.)  Note that MASK may be any number of digits long; it
7476 
          may not fit in a 32-bit word.
7477 
 
7478 
    `M BASEREG,OFFSET,LEN'
7479 
          Collect LEN bytes of memory starting at the address in
7480 
          register number BASEREG, plus OFFSET.  If BASEREG is `-1',
7481 
          then the range has a fixed address: OFFSET is the address of
7482 
          the lowest byte to collect.  The BASEREG, OFFSET, and LEN
7483 
          parameters are all unsigned hexadecimal values (the `-1'
7484 
          value for BASEREG is a special case).
7485 
 
7486 
    `X LEN,EXPR'
7487 
          Evaluate EXPR, whose length is LEN, and collect memory as it
7488 
          directs.  EXPR is an agent expression, as described in *Note
7489 
          Agent Expressions::.  Each byte of the expression is encoded
7490 
          as a two-digit hex number in the packet; LEN is the number of
7491 
          bytes in the expression (and thus one-half the number of hex
7492 
          digits in the packet).
7493 
 
7494 
 
7495 
     Any number of actions may be packed together in a single `QTDP'
7496 
     packet, as long as the packet does not exceed the maximum packet
7497 
     length (400 bytes, for many stubs).  There may be only one `R'
7498 
     action per tracepoint, and it must precede any `M' or `X' actions.
7499 
     Any registers referred to by `M' and `X' actions must be
7500 
     collected by a preceding `R' action.  (The "while-stepping"
7501 
     actions are treated as if they were attached to a separate
7502 
     tracepoint, as far as these restrictions are concerned.)
7503 
 
7504 
     Replies:
7505 
    `OK'
7506 
          The packet was understood and carried out.
7507 
 
7508 
    `'
7509 
          The packet was not recognized.
7510 
 
7511 
`QTFrame:N'
7512 
     Select the N'th tracepoint frame from the buffer, and use the
7513 
     register and memory contents recorded there to answer subsequent
7514 
     request packets from GDB.
7515 
 
7516 
     A successful reply from the stub indicates that the stub has found
7517 
     the requested frame.  The response is a series of parts,
7518 
     concatenated without separators, describing the frame we selected.
7519 
     Each part has one of the following forms:
7520 
 
7521 
    `F F'
7522 
          The selected frame is number N in the trace frame buffer; F
7523 
          is a hexadecimal number.  If F is `-1', then there was no
7524 
          frame matching the criteria in the request packet.
7525 
 
7526 
    `T T'
7527 
          The selected trace frame records a hit of tracepoint number T;
7528 
          T is a hexadecimal number.
7529 
 
7530 
 
7531 
`QTFrame:pc:ADDR'
7532 
     Like `QTFrame:N', but select the first tracepoint frame after the
7533 
     currently selected frame whose PC is ADDR; ADDR is a hexadecimal
7534 
     number.
7535 
 
7536 
`QTFrame:tdp:T'
7537 
     Like `QTFrame:N', but select the first tracepoint frame after the
7538 
     currently selected frame that is a hit of tracepoint T; T is a
7539 
     hexadecimal number.
7540 
 
7541 
`QTFrame:range:START:END'
7542 
     Like `QTFrame:N', but select the first tracepoint frame after the
7543 
     currently selected frame whose PC is between START (inclusive) and
7544 
     END (exclusive); START and END are hexadecimal numbers.
7545 
 
7546 
`QTFrame:outside:START:END'
7547 
     Like `QTFrame:range:START:END', but select the first frame
7548 
     _outside_ the given range of addresses.
7549 
 
7550 
`QTStart'
7551 
     Begin the tracepoint experiment.  Begin collecting data from
7552 
     tracepoint hits in the trace frame buffer.
7553 
 
7554 
`QTStop'
7555 
     End the tracepoint experiment.  Stop collecting trace frames.
7556 
 
7557 
`QTinit'
7558 
     Clear the table of tracepoints, and empty the trace frame buffer.
7559 
 
7560 
`QTro:START1,END1:START2,END2:...'
7561 
     Establish the given ranges of memory as "transparent".  The stub
7562 
     will answer requests for these ranges from memory's current
7563 
     contents, if they were not collected as part of the tracepoint hit.
7564 
 
7565 
     GDB uses this to mark read-only regions of memory, like those
7566 
     containing program code.  Since these areas never change, they
7567 
     should still have the same contents they did when the tracepoint
7568 
     was hit, so there's no reason for the stub to refuse to provide
7569 
     their contents.
7570 
 
7571 
`qTStatus'
7572 
     Ask the stub if there is a trace experiment running right now.
7573 
 
7574 
     Replies:
7575 
    `T0'
7576 
          There is no trace experiment running.
7577 
 
7578 
    `T1'
7579 
          There is a trace experiment running.
7580 
 
7581 
 
7582 

7583 
File: gdb.info,  Node: Host I/O Packets,  Next: Interrupts,  Prev: Tracepoint Packets,  Up: Remote Protocol
7584 
 
7585 
D.7 Host I/O Packets
7586 
====================
7587 
 
7588 
The "Host I/O" packets allow GDB to perform I/O operations on the far
7589 
side of a remote link.  For example, Host I/O is used to upload and
7590 
download files to a remote target with its own filesystem.  Host I/O
7591 
uses the same constant values and data structure layout as the
7592 
target-initiated File-I/O protocol.  However, the Host I/O packets are
7593 
structured differently.  The target-initiated protocol relies on target
7594 
memory to store parameters and buffers.  Host I/O requests are
7595 
initiated by GDB, and the target's memory is not involved.  *Note
7596 
File-I/O Remote Protocol Extension::, for more details on the
7597 
target-initiated protocol.
7598 
 
7599 
   The Host I/O request packets all encode a single operation along with
7600 
its arguments.  They have this format:
7601 
 
7602 
`vFile:OPERATION: PARAMETER...'
7603 
     OPERATION is the name of the particular request; the target should
7604 
     compare the entire packet name up to the second colon when checking
7605 
     for a supported operation.  The format of PARAMETER depends on the
7606 
     operation.  Numbers are always passed in hexadecimal.  Negative
7607 
     numbers have an explicit minus sign (i.e. two's complement is not
7608 
     used).  Strings (e.g. filenames) are encoded as a series of
7609 
     hexadecimal bytes.  The last argument to a system call may be a
7610 
     buffer of escaped binary data (*note Binary Data::).
7611 
 
7612 
 
7613 
   The valid responses to Host I/O packets are:
7614 
 
7615 
`F RESULT [, ERRNO] [; ATTACHMENT]'
7616 
     RESULT is the integer value returned by this operation, usually
7617 
     non-negative for success and -1 for errors.  If an error has
7618 
     occured, ERRNO will be included in the result.  ERRNO will have a
7619 
     value defined by the File-I/O protocol (*note Errno Values::).  For
7620 
     operations which return data, ATTACHMENT supplies the data as a
7621 
     binary buffer.  Binary buffers in response packets are escaped in
7622 
     the normal way (*note Binary Data::).  See the individual packet
7623 
     documentation for the interpretation of RESULT and ATTACHMENT.
7624 
 
7625 
`'
7626 
     An empty response indicates that this operation is not recognized.
7627 
 
7628 
 
7629 
   These are the supported Host I/O operations:
7630 
 
7631 
`vFile:open: PATHNAME, FLAGS, MODE'
7632 
     Open a file at PATHNAME and return a file descriptor for it, or
7633 
     return -1 if an error occurs.  PATHNAME is a string, FLAGS is an
7634 
     integer indicating a mask of open flags (*note Open Flags::), and
7635 
     MODE is an integer indicating a mask of mode bits to use if the
7636 
     file is created (*note mode_t Values::).  *Note open::, for
7637 
     details of the open flags and mode values.
7638 
 
7639 
`vFile:close: FD'
7640 
     Close the open file corresponding to FD and return 0, or -1 if an
7641 
     error occurs.
7642 
 
7643 
`vFile:pread: FD, COUNT, OFFSET'
7644 
     Read data from the open file corresponding to FD.  Up to COUNT
7645 
     bytes will be read from the file, starting at OFFSET relative to
7646 
     the start of the file.  The target may read fewer bytes; common
7647 
     reasons include packet size limits and an end-of-file condition.
7648 
     The number of bytes read is returned.  Zero should only be
7649 
     returned for a successful read at the end of the file, or if COUNT
7650 
     was zero.
7651 
 
7652 
     The data read should be returned as a binary attachment on success.
7653 
     If zero bytes were read, the response should include an empty
7654 
     binary attachment (i.e. a trailing semicolon).  The return value
7655 
     is the number of target bytes read; the binary attachment may be
7656 
     longer if some characters were escaped.
7657 
 
7658 
`vFile:pwrite: FD, OFFSET, DATA'
7659 
     Write DATA (a binary buffer) to the open file corresponding to FD.
7660 
     Start the write at OFFSET from the start of the file.  Unlike
7661 
     many `write' system calls, there is no separate COUNT argument;
7662 
     the length of DATA in the packet is used.  `vFile:write' returns
7663 
     the number of bytes written, which may be shorter than the length
7664 
     of DATA, or -1 if an error occurred.
7665 
 
7666 
`vFile:unlink: PATHNAME'
7667 
     Delete the file at PATHNAME on the target.  Return 0, or -1 if an
7668 
     error occurs.  PATHNAME is a string.
7669 
 
7670 
 
7671 

7672 
File: gdb.info,  Node: Interrupts,  Next: Examples,  Prev: Host I/O Packets,  Up: Remote Protocol
7673 
 
7674 
D.8 Interrupts
7675 
==============
7676 
 
7677 
When a program on the remote target is running, GDB may attempt to
7678 
interrupt it by sending a `Ctrl-C' or a `BREAK', control of which is
7679 
specified via GDB's `remotebreak' setting (*note set remotebreak::).
7680 
 
7681 
   The precise meaning of `BREAK' is defined by the transport mechanism
7682 
and may, in fact, be undefined.  GDB does not currently define a
7683 
`BREAK' mechanism for any of the network interfaces.
7684 
 
7685 
   `Ctrl-C', on the other hand, is defined and implemented for all
7686 
transport mechanisms.  It is represented by sending the single byte
7687 
`0x03' without any of the usual packet overhead described in the
7688 
Overview section (*note Overview::).  When a `0x03' byte is transmitted
7689 
as part of a packet, it is considered to be packet data and does _not_
7690 
represent an interrupt.  E.g., an `X' packet (*note X packet::), used
7691 
for binary downloads, may include an unescaped `0x03' as part of its
7692 
packet.
7693 
 
7694 
   Stubs are not required to recognize these interrupt mechanisms and
7695 
the precise meaning associated with receipt of the interrupt is
7696 
implementation defined.  If the stub is successful at interrupting the
7697 
running program, it is expected that it will send one of the Stop Reply
7698 
Packets (*note Stop Reply Packets::) to GDB as a result of successfully
7699 
stopping the program.  Interrupts received while the program is stopped
7700 
will be discarded.
7701 
 
7702 

7703 
File: gdb.info,  Node: Examples,  Next: File-I/O Remote Protocol Extension,  Prev: Interrupts,  Up: Remote Protocol
7704 
 
7705 
D.9 Examples
7706 
============
7707 
 
7708 
Example sequence of a target being re-started.  Notice how the restart
7709 
does not get any direct output:
7710 
 
7711 
     -> `R00'
7712 
     <- `+'
7713 
     _target restarts_
7714 
     -> `?'
7715 
     <- `+'
7716 
     <- `T001:1234123412341234'
7717 
     -> `+'
7718 
 
7719 
   Example sequence of a target being stepped by a single instruction:
7720 
 
7721 
     -> `G1445...'
7722 
     <- `+'
7723 
     -> `s'
7724 
     <- `+'
7725 
     _time passes_
7726 
     <- `T001:1234123412341234'
7727 
     -> `+'
7728 
     -> `g'
7729 
     <- `+'
7730 
     <- `1455...'
7731 
     -> `+'
7732 
 
7733 

7734 
File: gdb.info,  Node: File-I/O Remote Protocol Extension,  Next: Library List Format,  Prev: Examples,  Up: Remote Protocol
7735 
 
7736 
D.10 File-I/O Remote Protocol Extension
7737 
=======================================
7738 
 
7739 
* Menu:
7740 
 
7741 
* File-I/O Overview::
7742 
* Protocol Basics::
7743 
* The F Request Packet::
7744 
* The F Reply Packet::
7745 
* The Ctrl-C Message::
7746 
* Console I/O::
7747 
* List of Supported Calls::
7748 
* Protocol-specific Representation of Datatypes::
7749 
* Constants::
7750 
* File-I/O Examples::
7751 
 
7752 

7753 
File: gdb.info,  Node: File-I/O Overview,  Next: Protocol Basics,  Up: File-I/O Remote Protocol Extension
7754 
 
7755 
D.10.1 File-I/O Overview
7756 
------------------------
7757 
 
7758 
The "File I/O remote protocol extension" (short: File-I/O) allows the
7759 
target to use the host's file system and console I/O to perform various
7760 
system calls.  System calls on the target system are translated into a
7761 
remote protocol packet to the host system, which then performs the
7762 
needed actions and returns a response packet to the target system.
7763 
This simulates file system operations even on targets that lack file
7764 
systems.
7765 
 
7766 
   The protocol is defined to be independent of both the host and
7767 
target systems.  It uses its own internal representation of datatypes
7768 
and values.  Both GDB and the target's GDB stub are responsible for
7769 
translating the system-dependent value representations into the internal
7770 
protocol representations when data is transmitted.
7771 
 
7772 
   The communication is synchronous.  A system call is possible only
7773 
when GDB is waiting for a response from the `C', `c', `S' or `s'
7774 
packets.  While GDB handles the request for a system call, the target
7775 
is stopped to allow deterministic access to the target's memory.
7776 
Therefore File-I/O is not interruptible by target signals.  On the
7777 
other hand, it is possible to interrupt File-I/O by a user interrupt
7778 
(`Ctrl-C') within GDB.
7779 
 
7780 
   The target's request to perform a host system call does not finish
7781 
the latest `C', `c', `S' or `s' action.  That means, after finishing
7782 
the system call, the target returns to continuing the previous activity
7783 
(continue, step).  No additional continue or step request from GDB is
7784 
required.
7785 
 
7786 
     (gdb) continue
7787 
       <- target requests 'system call X'
7788 
       target is stopped, GDB executes system call
7789 
       -> GDB returns result
7790 
       ... target continues, GDB returns to wait for the target
7791 
       <- target hits breakpoint and sends a Txx packet
7792 
 
7793 
   The protocol only supports I/O on the console and to regular files on
7794 
the host file system.  Character or block special devices, pipes, named
7795 
pipes, sockets or any other communication method on the host system are
7796 
not supported by this protocol.
7797 
 
7798 

7799 
File: gdb.info,  Node: Protocol Basics,  Next: The F Request Packet,  Prev: File-I/O Overview,  Up: File-I/O Remote Protocol Extension
7800 
 
7801 
D.10.2 Protocol Basics
7802 
----------------------
7803 
 
7804 
The File-I/O protocol uses the `F' packet as the request as well as
7805 
reply packet.  Since a File-I/O system call can only occur when GDB is
7806 
waiting for a response from the continuing or stepping target, the
7807 
File-I/O request is a reply that GDB has to expect as a result of a
7808 
previous `C', `c', `S' or `s' packet.  This `F' packet contains all
7809 
information needed to allow GDB to call the appropriate host system
7810 
call:
7811 
 
7812 
   * A unique identifier for the requested system call.
7813 
 
7814 
   * All parameters to the system call.  Pointers are given as addresses
7815 
     in the target memory address space.  Pointers to strings are given
7816 
     as pointer/length pair.  Numerical values are given as they are.
7817 
     Numerical control flags are given in a protocol-specific
7818 
     representation.
7819 
 
7820 
 
7821 
   At this point, GDB has to perform the following actions.
7822 
 
7823 
   * If the parameters include pointer values to data needed as input
7824 
     to a system call, GDB requests this data from the target with a
7825 
     standard `m' packet request.  This additional communication has to
7826 
     be expected by the target implementation and is handled as any
7827 
     other `m' packet.
7828 
 
7829 
   * GDB translates all value from protocol representation to host
7830 
     representation as needed.  Datatypes are coerced into the host
7831 
     types.
7832 
 
7833 
   * GDB calls the system call.
7834 
 
7835 
   * It then coerces datatypes back to protocol representation.
7836 
 
7837 
   * If the system call is expected to return data in buffer space
7838 
     specified by pointer parameters to the call, the data is
7839 
     transmitted to the target using a `M' or `X' packet.  This packet
7840 
     has to be expected by the target implementation and is handled as
7841 
     any other `M' or `X' packet.
7842 
 
7843 
 
7844 
   Eventually GDB replies with another `F' packet which contains all
7845 
necessary information for the target to continue.  This at least
7846 
contains
7847 
 
7848 
   * Return value.
7849 
 
7850 
   * `errno', if has been changed by the system call.
7851 
 
7852 
   * "Ctrl-C" flag.
7853 
 
7854 
 
7855 
   After having done the needed type and value coercion, the target
7856 
continues the latest continue or step action.
7857 
 
7858 

7859 
File: gdb.info,  Node: The F Request Packet,  Next: The F Reply Packet,  Prev: Protocol Basics,  Up: File-I/O Remote Protocol Extension
7860 
 
7861 
D.10.3 The `F' Request Packet
7862 
-----------------------------
7863 
 
7864 
The `F' request packet has the following format:
7865 
 
7866 
`FCALL-ID,PARAMETER...'
7867 
     CALL-ID is the identifier to indicate the host system call to be
7868 
     called.  This is just the name of the function.
7869 
 
7870 
     PARAMETER... are the parameters to the system call.  Parameters
7871 
     are hexadecimal integer values, either the actual values in case
7872 
     of scalar datatypes, pointers to target buffer space in case of
7873 
     compound datatypes and unspecified memory areas, or pointer/length
7874 
     pairs in case of string parameters.  These are appended to the
7875 
     CALL-ID as a comma-delimited list.  All values are transmitted in
7876 
     ASCII string representation, pointer/length pairs separated by a
7877 
     slash.
7878 
 
7879 
 
7880 

7881 
File: gdb.info,  Node: The F Reply Packet,  Next: The Ctrl-C Message,  Prev: The F Request Packet,  Up: File-I/O Remote Protocol Extension
7882 
 
7883 
D.10.4 The `F' Reply Packet
7884 
---------------------------
7885 
 
7886 
The `F' reply packet has the following format:
7887 
 
7888 
`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
7889 
     RETCODE is the return code of the system call as hexadecimal value.
7890 
 
7891 
     ERRNO is the `errno' set by the call, in protocol-specific
7892 
     representation.  This parameter can be omitted if the call was
7893 
     successful.
7894 
 
7895 
     CTRL-C FLAG is only sent if the user requested a break.  In this
7896 
     case, ERRNO must be sent as well, even if the call was successful.
7897 
     The CTRL-C FLAG itself consists of the character `C':
7898 
 
7899 
          F0,0,C
7900 
 
7901 
     or, if the call was interrupted before the host call has been
7902 
     performed:
7903 
 
7904 
          F-1,4,C
7905 
 
7906 
     assuming 4 is the protocol-specific representation of `EINTR'.
7907 
 
7908 
 
7909 

7910 
File: gdb.info,  Node: The Ctrl-C Message,  Next: Console I/O,  Prev: The F Reply Packet,  Up: File-I/O Remote Protocol Extension
7911 
 
7912 
D.10.5 The `Ctrl-C' Message
7913 
---------------------------
7914 
 
7915 
If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
7916 
Packet::), the target should behave as if it had gotten a break
7917 
message.  The meaning for the target is "system call interrupted by
7918 
`SIGINT'".  Consequentially, the target should actually stop (as with a
7919 
break message) and return to GDB with a `T02' packet.
7920 
 
7921 
   It's important for the target to know in which state the system call
7922 
was interrupted.  There are two possible cases:
7923 
 
7924 
   * The system call hasn't been performed on the host yet.
7925 
 
7926 
   * The system call on the host has been finished.
7927 
 
7928 
 
7929 
   These two states can be distinguished by the target by the value of
7930 
the returned `errno'.  If it's the protocol representation of `EINTR',
7931 
the system call hasn't been performed.  This is equivalent to the
7932 
`EINTR' handling on POSIX systems.  In any other case, the target may
7933 
presume that the system call has been finished -- successfully or not
7934 
-- and should behave as if the break message arrived right after the
7935 
system call.
7936 
 
7937 
   GDB must behave reliably.  If the system call has not been called
7938 
yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
7939 
in the packet.  If the system call on the host has been finished before
7940 
the user requests a break, the full action must be finished by GDB.
7941 
This requires sending `M' or `X' packets as necessary.  The `F' packet
7942 
may only be sent when either nothing has happened or the full action
7943 
has been completed.
7944 
 
7945 

7946 
File: gdb.info,  Node: Console I/O,  Next: List of Supported Calls,  Prev: The Ctrl-C Message,  Up: File-I/O Remote Protocol Extension
7947 
 
7948 
D.10.6 Console I/O
7949 
------------------
7950 
 
7951 
By default and if not explicitly closed by the target system, the file
7952 
descriptors 0, 1 and 2 are connected to the GDB console.  Output on the
7953 
GDB console is handled as any other file output operation (`write(1,
7954 
...)' or `write(2, ...)').  Console input is handled by GDB so that
7955 
after the target read request from file descriptor 0 all following
7956 
typing is buffered until either one of the following conditions is met:
7957 
 
7958 
   * The user types `Ctrl-c'.  The behaviour is as explained above, and
7959 
     the `read' system call is treated as finished.
7960 
 
7961 
   * The user presses .  This is treated as end of input with a
7962 
     trailing newline.
7963 
 
7964 
   * The user types `Ctrl-d'.  This is treated as end of input.  No
7965 
     trailing character (neither newline nor `Ctrl-D') is appended to
7966 
     the input.
7967 
 
7968 
 
7969 
   If the user has typed more characters than fit in the buffer given to
7970 
the `read' call, the trailing characters are buffered in GDB until
7971 
either another `read(0, ...)' is requested by the target, or debugging
7972 
is stopped at the user's request.
7973 
 
7974 

7975 
File: gdb.info,  Node: List of Supported Calls,  Next: Protocol-specific Representation of Datatypes,  Prev: Console I/O,  Up: File-I/O Remote Protocol Extension
7976 
 
7977 
D.10.7 List of Supported Calls
7978 
------------------------------
7979 
 
7980 
* Menu:
7981 
 
7982 
* open::
7983 
* close::
7984 
* read::
7985 
* write::
7986 
* lseek::
7987 
* rename::
7988 
* unlink::
7989 
* stat/fstat::
7990 
* gettimeofday::
7991 
* isatty::
7992 
* system::
7993 
 
7994 

7995 
File: gdb.info,  Node: open,  Next: close,  Up: List of Supported Calls
7996 
 
7997 
open
7998 
....
7999 
 
8000 
Synopsis:
8001 
          int open(const char *pathname, int flags);
8002 
          int open(const char *pathname, int flags, mode_t mode);
8003 
 
8004 
Request:
8005 
     `Fopen,PATHPTR/LEN,FLAGS,MODE'
8006 
 
8007 
     FLAGS is the bitwise `OR' of the following values:
8008 
 
8009 
    `O_CREAT'
8010 
          If the file does not exist it will be created.  The host
8011 
          rules apply as far as file ownership and time stamps are
8012 
          concerned.
8013 
 
8014 
    `O_EXCL'
8015 
          When used with `O_CREAT', if the file already exists it is an
8016 
          error and open() fails.
8017 
 
8018 
    `O_TRUNC'
8019 
          If the file already exists and the open mode allows writing
8020 
          (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
8021 
          zero length.
8022 
 
8023 
    `O_APPEND'
8024 
          The file is opened in append mode.
8025 
 
8026 
    `O_RDONLY'
8027 
          The file is opened for reading only.
8028 
 
8029 
    `O_WRONLY'
8030 
          The file is opened for writing only.
8031 
 
8032 
    `O_RDWR'
8033 
          The file is opened for reading and writing.
8034 
 
8035 
     Other bits are silently ignored.
8036 
 
8037 
     MODE is the bitwise `OR' of the following values:
8038 
 
8039 
    `S_IRUSR'
8040 
          User has read permission.
8041 
 
8042 
    `S_IWUSR'
8043 
          User has write permission.
8044 
 
8045 
    `S_IRGRP'
8046 
          Group has read permission.
8047 
 
8048 
    `S_IWGRP'
8049 
          Group has write permission.
8050 
 
8051 
    `S_IROTH'
8052 
          Others have read permission.
8053 
 
8054 
    `S_IWOTH'
8055 
          Others have write permission.
8056 
 
8057 
     Other bits are silently ignored.
8058 
 
8059 
Return value:
8060 
     `open' returns the new file descriptor or -1 if an error occurred.
8061 
 
8062 
Errors:
8063 
 
8064 
    `EEXIST'
8065 
          PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
8066 
 
8067 
    `EISDIR'
8068 
          PATHNAME refers to a directory.
8069 
 
8070 
    `EACCES'
8071 
          The requested access is not allowed.
8072 
 
8073 
    `ENAMETOOLONG'
8074 
          PATHNAME was too long.
8075 
 
8076 
    `ENOENT'
8077 
          A directory component in PATHNAME does not exist.
8078 
 
8079 
    `ENODEV'
8080 
          PATHNAME refers to a device, pipe, named pipe or socket.
8081 
 
8082 
    `EROFS'
8083 
          PATHNAME refers to a file on a read-only filesystem and write
8084 
          access was requested.
8085 
 
8086 
    `EFAULT'
8087 
          PATHNAME is an invalid pointer value.
8088 
 
8089 
    `ENOSPC'
8090 
          No space on device to create the file.
8091 
 
8092 
    `EMFILE'
8093 
          The process already has the maximum number of files open.
8094 
 
8095 
    `ENFILE'
8096 
          The limit on the total number of files open on the system has
8097 
          been reached.
8098 
 
8099 
    `EINTR'
8100 
          The call was interrupted by the user.
8101 
 
8102 
 
8103 

8104 
File: gdb.info,  Node: close,  Next: read,  Prev: open,  Up: List of Supported Calls
8105 
 
8106 
close
8107 
.....
8108 
 
8109 
Synopsis:
8110 
          int close(int fd);
8111 
 
8112 
Request:
8113 
     `Fclose,FD'
8114 
 
8115 
Return value:
8116 
     `close' returns zero on success, or -1 if an error occurred.
8117 
 
8118 
Errors:
8119 
 
8120 
    `EBADF'
8121 
          FD isn't a valid open file descriptor.
8122 
 
8123 
    `EINTR'
8124 
          The call was interrupted by the user.
8125 
 
8126 
 
8127 

8128 
File: gdb.info,  Node: read,  Next: write,  Prev: close,  Up: List of Supported Calls
8129 
 
8130 
read
8131 
....
8132 
 
8133 
Synopsis:
8134 
          int read(int fd, void *buf, unsigned int count);
8135 
 
8136 
Request:
8137 
     `Fread,FD,BUFPTR,COUNT'
8138 
 
8139 
Return value:
8140 
     On success, the number of bytes read is returned.  Zero indicates
8141 
     end of file.  If count is zero, read returns zero as well.  On
8142 
     error, -1 is returned.
8143 
 
8144 
Errors:
8145 
 
8146 
    `EBADF'
8147 
          FD is not a valid file descriptor or is not open for reading.
8148 
 
8149 
    `EFAULT'
8150 
          BUFPTR is an invalid pointer value.
8151 
 
8152 
    `EINTR'
8153 
          The call was interrupted by the user.
8154 
 
8155 
 
8156 

8157 
File: gdb.info,  Node: write,  Next: lseek,  Prev: read,  Up: List of Supported Calls
8158 
 
8159 
write
8160 
.....
8161 
 
8162 
Synopsis:
8163 
          int write(int fd, const void *buf, unsigned int count);
8164 
 
8165 
Request:
8166 
     `Fwrite,FD,BUFPTR,COUNT'
8167 
 
8168 
Return value:
8169 
     On success, the number of bytes written are returned.  Zero
8170 
     indicates nothing was written.  On error, -1 is returned.
8171 
 
8172 
Errors:
8173 
 
8174 
    `EBADF'
8175 
          FD is not a valid file descriptor or is not open for writing.
8176 
 
8177 
    `EFAULT'
8178 
          BUFPTR is an invalid pointer value.
8179 
 
8180 
    `EFBIG'
8181 
          An attempt was made to write a file that exceeds the
8182 
          host-specific maximum file size allowed.
8183 
 
8184 
    `ENOSPC'
8185 
          No space on device to write the data.
8186 
 
8187 
    `EINTR'
8188 
          The call was interrupted by the user.
8189 
 
8190 
 
8191 

8192 
File: gdb.info,  Node: lseek,  Next: rename,  Prev: write,  Up: List of Supported Calls
8193 
 
8194 
lseek
8195 
.....
8196 
 
8197 
Synopsis:
8198 
          long lseek (int fd, long offset, int flag);
8199 
 
8200 
Request:
8201 
     `Flseek,FD,OFFSET,FLAG'
8202 
 
8203 
     FLAG is one of:
8204 
 
8205 
    `SEEK_SET'
8206 
          The offset is set to OFFSET bytes.
8207 
 
8208 
    `SEEK_CUR'
8209 
          The offset is set to its current location plus OFFSET bytes.
8210 
 
8211 
    `SEEK_END'
8212 
          The offset is set to the size of the file plus OFFSET bytes.
8213 
 
8214 
Return value:
8215 
     On success, the resulting unsigned offset in bytes from the
8216 
     beginning of the file is returned.  Otherwise, a value of -1 is
8217 
     returned.
8218 
 
8219 
Errors:
8220 
 
8221 
    `EBADF'
8222 
          FD is not a valid open file descriptor.
8223 
 
8224 
    `ESPIPE'
8225 
          FD is associated with the GDB console.
8226 
 
8227 
    `EINVAL'
8228 
          FLAG is not a proper value.
8229 
 
8230 
    `EINTR'
8231 
          The call was interrupted by the user.
8232 
 
8233 
 
8234 

8235 
File: gdb.info,  Node: rename,  Next: unlink,  Prev: lseek,  Up: List of Supported Calls
8236 
 
8237 
rename
8238 
......
8239 
 
8240 
Synopsis:
8241 
          int rename(const char *oldpath, const char *newpath);
8242 
 
8243 
Request:
8244 
     `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
8245 
 
8246 
Return value:
8247 
     On success, zero is returned.  On error, -1 is returned.
8248 
 
8249 
Errors:
8250 
 
8251 
    `EISDIR'
8252 
          NEWPATH is an existing directory, but OLDPATH is not a
8253 
          directory.
8254 
 
8255 
    `EEXIST'
8256 
          NEWPATH is a non-empty directory.
8257 
 
8258 
    `EBUSY'
8259 
          OLDPATH or NEWPATH is a directory that is in use by some
8260 
          process.
8261 
 
8262 
    `EINVAL'
8263 
          An attempt was made to make a directory a subdirectory of
8264 
          itself.
8265 
 
8266 
    `ENOTDIR'
8267 
          A  component used as a directory in OLDPATH or new path is
8268 
          not a directory.  Or OLDPATH is a directory and NEWPATH
8269 
          exists but is not a directory.
8270 
 
8271 
    `EFAULT'
8272 
          OLDPATHPTR or NEWPATHPTR are invalid pointer values.
8273 
 
8274 
    `EACCES'
8275 
          No access to the file or the path of the file.
8276 
 
8277 
    `ENAMETOOLONG'
8278 
          OLDPATH or NEWPATH was too long.
8279 
 
8280 
    `ENOENT'
8281 
          A directory component in OLDPATH or NEWPATH does not exist.
8282 
 
8283 
    `EROFS'
8284 
          The file is on a read-only filesystem.
8285 
 
8286 
    `ENOSPC'
8287 
          The device containing the file has no room for the new
8288 
          directory entry.
8289 
 
8290 
    `EINTR'
8291 
          The call was interrupted by the user.
8292 
 
8293 
 
8294 

8295 
File: gdb.info,  Node: unlink,  Next: stat/fstat,  Prev: rename,  Up: List of Supported Calls
8296 
 
8297 
unlink
8298 
......
8299 
 
8300 
Synopsis:
8301 
          int unlink(const char *pathname);
8302 
 
8303 
Request:
8304 
     `Funlink,PATHNAMEPTR/LEN'
8305 
 
8306 
Return value:
8307 
     On success, zero is returned.  On error, -1 is returned.
8308 
 
8309 
Errors:
8310 
 
8311 
    `EACCES'
8312 
          No access to the file or the path of the file.
8313 
 
8314 
    `EPERM'
8315 
          The system does not allow unlinking of directories.
8316 
 
8317 
    `EBUSY'
8318 
          The file PATHNAME cannot be unlinked because it's being used
8319 
          by another process.
8320 
 
8321 
    `EFAULT'
8322 
          PATHNAMEPTR is an invalid pointer value.
8323 
 
8324 
    `ENAMETOOLONG'
8325 
          PATHNAME was too long.
8326 
 
8327 
    `ENOENT'
8328 
          A directory component in PATHNAME does not exist.
8329 
 
8330 
    `ENOTDIR'
8331 
          A component of the path is not a directory.
8332 
 
8333 
    `EROFS'
8334 
          The file is on a read-only filesystem.
8335 
 
8336 
    `EINTR'
8337 
          The call was interrupted by the user.
8338 
 
8339 
 
8340 

8341 
File: gdb.info,  Node: stat/fstat,  Next: gettimeofday,  Prev: unlink,  Up: List of Supported Calls
8342 
 
8343 
stat/fstat
8344 
..........
8345 
 
8346 
Synopsis:
8347 
          int stat(const char *pathname, struct stat *buf);
8348 
          int fstat(int fd, struct stat *buf);
8349 
 
8350 
Request:
8351 
     `Fstat,PATHNAMEPTR/LEN,BUFPTR'
8352 
     `Ffstat,FD,BUFPTR'
8353 
 
8354 
Return value:
8355 
     On success, zero is returned.  On error, -1 is returned.
8356 
 
8357 
Errors:
8358 
 
8359 
    `EBADF'
8360 
          FD is not a valid open file.
8361 
 
8362 
    `ENOENT'
8363 
          A directory component in PATHNAME does not exist or the path
8364 
          is an empty string.
8365 
 
8366 
    `ENOTDIR'
8367 
          A component of the path is not a directory.
8368 
 
8369 
    `EFAULT'
8370 
          PATHNAMEPTR is an invalid pointer value.
8371 
 
8372 
    `EACCES'
8373 
          No access to the file or the path of the file.
8374 
 
8375 
    `ENAMETOOLONG'
8376 
          PATHNAME was too long.
8377 
 
8378 
    `EINTR'
8379 
          The call was interrupted by the user.
8380 
 
8381 
 
8382 

8383 
File: gdb.info,  Node: gettimeofday,  Next: isatty,  Prev: stat/fstat,  Up: List of Supported Calls
8384 
 
8385 
gettimeofday
8386 
............
8387 
 
8388 
Synopsis:
8389 
          int gettimeofday(struct timeval *tv, void *tz);
8390 
 
8391 
Request:
8392 
     `Fgettimeofday,TVPTR,TZPTR'
8393 
 
8394 
Return value:
8395 
     On success, 0 is returned, -1 otherwise.
8396 
 
8397 
Errors:
8398 
 
8399 
    `EINVAL'
8400 
          TZ is a non-NULL pointer.
8401 
 
8402 
    `EFAULT'
8403 
          TVPTR and/or TZPTR is an invalid pointer value.
8404 
 
8405 
 
8406 

8407 
File: gdb.info,  Node: isatty,  Next: system,  Prev: gettimeofday,  Up: List of Supported Calls
8408 
 
8409 
isatty
8410 
......
8411 
 
8412 
Synopsis:
8413 
          int isatty(int fd);
8414 
 
8415 
Request:
8416 
     `Fisatty,FD'
8417 
 
8418 
Return value:
8419 
     Returns 1 if FD refers to the GDB console, 0 otherwise.
8420 
 
8421 
Errors:
8422 
 
8423 
    `EINTR'
8424 
          The call was interrupted by the user.
8425 
 
8426 
 
8427 
   Note that the `isatty' call is treated as a special case: it returns
8428 
1 to the target if the file descriptor is attached to the GDB console,
8429 
 
8430 
implementing `ioctl' and would be more complex than needed.
8431 
 
8432 

8433 
File: gdb.info,  Node: system,  Prev: isatty,  Up: List of Supported Calls
8434 
 
8435 
system
8436 
......
8437 
 
8438 
Synopsis:
8439 
          int system(const char *command);
8440 
 
8441 
Request:
8442 
     `Fsystem,COMMANDPTR/LEN'
8443 
 
8444 
Return value:
8445 
     If LEN is zero, the return value indicates whether a shell is
8446 
     available.  A zero return value indicates a shell is not available.
8447 
     For non-zero LEN, the value returned is -1 on error and the return
8448 
     status of the command otherwise.  Only the exit status of the
8449 
     command is returned, which is extracted from the host's `system'
8450 
     return value by calling `WEXITSTATUS(retval)'.  In case `/bin/sh'
8451 
     could not be executed, 127 is returned.
8452 
 
8453 
Errors:
8454 
 
8455 
    `EINTR'
8456 
          The call was interrupted by the user.
8457 
 
8458 
 
8459 
   GDB takes over the full task of calling the necessary host calls to
8460 
perform the `system' call.  The return value of `system' on the host is
8461 
simplified before it's returned to the target.  Any termination signal
8462 
information from the child process is discarded, and the return value
8463 
consists entirely of the exit status of the called command.
8464 
 
8465 
   Due to security concerns, the `system' call is by default refused by
8466 
GDB.  The user has to allow this call explicitly with the `set remote
8467 
system-call-allowed 1' command.
8468 
 
8469 
`set remote system-call-allowed'
8470 
     Control whether to allow the `system' calls in the File I/O
8471 
     protocol for the remote target.  The default is zero (disabled).
8472 
 
8473 
`show remote system-call-allowed'
8474 
     Show whether the `system' calls are allowed in the File I/O
8475 
     protocol.
8476 
 
8477 

8478 
File: gdb.info,  Node: Protocol-specific Representation of Datatypes,  Next: Constants,  Prev: List of Supported Calls,  Up: File-I/O Remote Protocol Extension
8479 
 
8480 
D.10.8 Protocol-specific Representation of Datatypes
8481 
----------------------------------------------------
8482 
 
8483 
* Menu:
8484 
 
8485 
* Integral Datatypes::
8486 
* Pointer Values::
8487 
* Memory Transfer::
8488 
* struct stat::
8489 
* struct timeval::
8490 
 
8491 

8492 
File: gdb.info,  Node: Integral Datatypes,  Next: Pointer Values,  Up: Protocol-specific Representation of Datatypes
8493 
 
8494 
Integral Datatypes
8495 
..................
8496 
 
8497 
The integral datatypes used in the system calls are `int', `unsigned
8498 
int', `long', `unsigned long', `mode_t', and `time_t'.
8499 
 
8500 
   `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
8501 
bit values in this protocol.
8502 
 
8503 
   `long' and `unsigned long' are implemented as 64 bit types.
8504 
 
8505 
   *Note Limits::, for corresponding MIN and MAX values (similar to
8506 
those in `limits.h') to allow range checking on host and target.
8507 
 
8508 
   `time_t' datatypes are defined as seconds since the Epoch.
8509 
 
8510 
   All integral datatypes transferred as part of a memory read or write
8511 
of a structured datatype e.g. a `struct stat' have to be given in big
8512 
endian byte order.
8513 
 
8514 

8515 
File: gdb.info,  Node: Pointer Values,  Next: Memory Transfer,  Prev: Integral Datatypes,  Up: Protocol-specific Representation of Datatypes
8516 
 
8517 
Pointer Values
8518 
..............
8519 
 
8520 
Pointers to target data are transmitted as they are.  An exception is
8521 
made for pointers to buffers for which the length isn't transmitted as
8522 
part of the function call, namely strings.  Strings are transmitted as
8523 
a pointer/length pair, both as hex values, e.g.
8524 
 
8525 
     `1aaf/12'
8526 
 
8527 
which is a pointer to data of length 18 bytes at position 0x1aaf.  The
8528 
length is defined as the full string length in bytes, including the
8529 
trailing null byte.  For example, the string `"hello world"' at address
8530 
0x123456 is transmitted as
8531 
 
8532 
     `123456/d'
8533 
 
8534 

8535 
File: gdb.info,  Node: Memory Transfer,  Next: struct stat,  Prev: Pointer Values,  Up: Protocol-specific Representation of Datatypes
8536 
 
8537 
Memory Transfer
8538 
...............
8539 
 
8540 
Structured data which is transferred using a memory read or write (for
8541 
example, a `struct stat') is expected to be in a protocol-specific
8542 
format with all scalar multibyte datatypes being big endian.
8543 
Translation to this representation needs to be done both by the target
8544 
before the `F' packet is sent, and by GDB before it transfers memory to
8545 
the target.  Transferred pointers to structured data should point to
8546 
the already-coerced data at any time.
8547 
 
8548 

8549 
File: gdb.info,  Node: struct stat,  Next: struct timeval,  Prev: Memory Transfer,  Up: Protocol-specific Representation of Datatypes
8550 
 
8551 
struct stat
8552 
...........
8553 
 
8554 
The buffer of type `struct stat' used by the target and GDB is defined
8555 
as follows:
8556 
 
8557 
     struct stat {
8558 
         unsigned int  st_dev;      /* device */
8559 
         unsigned int  st_ino;      /* inode */
8560 
         mode_t        st_mode;     /* protection */
8561 
         unsigned int  st_nlink;    /* number of hard links */
8562 
         unsigned int  st_uid;      /* user ID of owner */
8563 
         unsigned int  st_gid;      /* group ID of owner */
8564 
         unsigned int  st_rdev;     /* device type (if inode device) */
8565 
         unsigned long st_size;     /* total size, in bytes */
8566 
         unsigned long st_blksize;  /* blocksize for filesystem I/O */
8567 
         unsigned long st_blocks;   /* number of blocks allocated */
8568 
         time_t        st_atime;    /* time of last access */
8569 
         time_t        st_mtime;    /* time of last modification */
8570 
         time_t        st_ctime;    /* time of last change */
8571 
     };
8572 
 
8573 
   The integral datatypes conform to the definitions given in the
8574 
appropriate section (see *Note Integral Datatypes::, for details) so
8575 
this structure is of size 64 bytes.
8576 
 
8577 
   The values of several fields have a restricted meaning and/or range
8578 
of values.
8579 
 
8580 
`st_dev'
8581 
     A value of 0 represents a file, 1 the console.
8582 
 
8583 
`st_ino'
8584 
     No valid meaning for the target.  Transmitted unchanged.
8585 
 
8586 
`st_mode'
8587 
     Valid mode bits are described in *Note Constants::.  Any other
8588 
     bits have currently no meaning for the target.
8589 
 
8590 
`st_uid'
8591 
`st_gid'
8592 
`st_rdev'
8593 
     No valid meaning for the target.  Transmitted unchanged.
8594 
 
8595 
`st_atime'
8596 
`st_mtime'
8597 
`st_ctime'
8598 
     These values have a host and file system dependent accuracy.
8599 
     Especially on Windows hosts, the file system may not support exact
8600 
     timing values.
8601 
 
8602 
   The target gets a `struct stat' of the above representation and is
8603 
responsible for coercing it to the target representation before
8604 
continuing.
8605 
 
8606 
   Note that due to size differences between the host, target, and
8607 
protocol representations of `struct stat' members, these members could
8608 
eventually get truncated on the target.
8609 
 
8610 

8611 
File: gdb.info,  Node: struct timeval,  Prev: struct stat,  Up: Protocol-specific Representation of Datatypes
8612 
 
8613 
struct timeval
8614 
..............
8615 
 
8616 
The buffer of type `struct timeval' used by the File-I/O protocol is
8617 
defined as follows:
8618 
 
8619 
     struct timeval {
8620 
         time_t tv_sec;  /* second */
8621 
         long   tv_usec; /* microsecond */
8622 
     };
8623 
 
8624 
   The integral datatypes conform to the definitions given in the
8625 
appropriate section (see *Note Integral Datatypes::, for details) so
8626 
this structure is of size 8 bytes.
8627 
 
8628 

8629 
File: gdb.info,  Node: Constants,  Next: File-I/O Examples,  Prev: Protocol-specific Representation of Datatypes,  Up: File-I/O Remote Protocol Extension
8630 
 
8631 
D.10.9 Constants
8632 
----------------
8633 
 
8634 
The following values are used for the constants inside of the protocol.
8635 
GDB and target are responsible for translating these values before and
8636 
after the call as needed.
8637 
 
8638 
* Menu:
8639 
 
8640 
* Open Flags::
8641 
* mode_t Values::
8642 
* Errno Values::
8643 
* Lseek Flags::
8644 
* Limits::
8645 
 
8646 

8647 
File: gdb.info,  Node: Open Flags,  Next: mode_t Values,  Up: Constants
8648 
 
8649 
Open Flags
8650 
..........
8651 
 
8652 
All values are given in hexadecimal representation.
8653 
 
8654 
       O_RDONLY        0x0
8655 
       O_WRONLY        0x1
8656 
       O_RDWR          0x2
8657 
       O_APPEND        0x8
8658 
       O_CREAT       0x200
8659 
       O_TRUNC       0x400
8660 
       O_EXCL        0x800
8661 
 
8662 

8663 
File: gdb.info,  Node: mode_t Values,  Next: Errno Values,  Prev: Open Flags,  Up: Constants
8664 
 
8665 
mode_t Values
8666 
.............
8667 
 
8668 
All values are given in octal representation.
8669 
 
8670 
       S_IFREG       0100000
8671 
       S_IFDIR        040000
8672 
       S_IRUSR          0400
8673 
       S_IWUSR          0200
8674 
       S_IXUSR          0100
8675 
       S_IRGRP           040
8676 
       S_IWGRP           020
8677 
       S_IXGRP           010
8678 
       S_IROTH            04
8679 
       S_IWOTH            02
8680 
       S_IXOTH            01
8681 
 
8682 

8683 
File: gdb.info,  Node: Errno Values,  Next: Lseek Flags,  Prev: mode_t Values,  Up: Constants
8684 
 
8685 
Errno Values
8686 
............
8687 
 
8688 
All values are given in decimal representation.
8689 
 
8690 
       EPERM           1
8691 
       ENOENT          2
8692 
       EINTR           4
8693 
       EBADF           9
8694 
       EACCES         13
8695 
       EFAULT         14
8696 
       EBUSY          16
8697 
       EEXIST         17
8698 
       ENODEV         19
8699 
       ENOTDIR        20
8700 
       EISDIR         21
8701 
       EINVAL         22
8702 
       ENFILE         23
8703 
       EMFILE         24
8704 
       EFBIG          27
8705 
       ENOSPC         28
8706 
       ESPIPE         29
8707 
       EROFS          30
8708 
       ENAMETOOLONG   91
8709 
       EUNKNOWN       9999
8710 
 
8711 
   `EUNKNOWN' is used as a fallback error value if a host system returns
8712 
 any error value not in the list of supported error numbers.
8713 
 
8714 

8715 
File: gdb.info,  Node: Lseek Flags,  Next: Limits,  Prev: Errno Values,  Up: Constants
8716 
 
8717 
Lseek Flags
8718 
...........
8719 
 
8720 
       SEEK_SET      0
8721 
       SEEK_CUR      1
8722 
       SEEK_END      2
8723 
 
8724 

8725 
File: gdb.info,  Node: Limits,  Prev: Lseek Flags,  Up: Constants
8726 
 
8727 
Limits
8728 
......
8729 
 
8730 
All values are given in decimal representation.
8731 
 
8732 
       INT_MIN       -2147483648
8733 
       INT_MAX        2147483647
8734 
       UINT_MAX       4294967295
8735 
       LONG_MIN      -9223372036854775808
8736 
       LONG_MAX       9223372036854775807
8737 
       ULONG_MAX      18446744073709551615
8738 
 
8739 

8740 
File: gdb.info,  Node: File-I/O Examples,  Prev: Constants,  Up: File-I/O Remote Protocol Extension
8741 
 
8742 
D.10.10 File-I/O Examples
8743 
-------------------------
8744 
 
8745 
Example sequence of a write call, file descriptor 3, buffer is at target
8746 
address 0x1234, 6 bytes should be written:
8747 
 
8748 
     <- `Fwrite,3,1234,6'
8749 
     _request memory read from target_
8750 
     -> `m1234,6'
8751 
     <- XXXXXX
8752 
     _return "6 bytes written"_
8753 
     -> `F6'
8754 
 
8755 
   Example sequence of a read call, file descriptor 3, buffer is at
8756 
target address 0x1234, 6 bytes should be read:
8757 
 
8758 
     <- `Fread,3,1234,6'
8759 
     _request memory write to target_
8760 
     -> `X1234,6:XXXXXX'
8761 
     _return "6 bytes read"_
8762 
     -> `F6'
8763 
 
8764 
   Example sequence of a read call, call fails on the host due to
8765 
invalid file descriptor (`EBADF'):
8766 
 
8767 
     <- `Fread,3,1234,6'
8768 
     -> `F-1,9'
8769 
 
8770 
   Example sequence of a read call, user presses `Ctrl-c' before
8771 
syscall on host is called:
8772 
 
8773 
     <- `Fread,3,1234,6'
8774 
     -> `F-1,4,C'
8775 
     <- `T02'
8776 
 
8777 
   Example sequence of a read call, user presses `Ctrl-c' after syscall
8778 
on host is called:
8779 
 
8780 
     <- `Fread,3,1234,6'
8781 
     -> `X1234,6:XXXXXX'
8782 
     <- `T02'
8783 
 
8784 

8785 
File: gdb.info,  Node: Library List Format,  Next: Memory Map Format,  Prev: File-I/O Remote Protocol Extension,  Up: Remote Protocol
8786 
 
8787 
D.11 Library List Format
8788 
========================
8789 
 
8790 
On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
8791 
process as your application to manage libraries.  In this case, GDB can
8792 
use the loader's symbol table and normal memory operations to maintain
8793 
a list of shared libraries.  On other platforms, the operating system
8794 
manages loaded libraries.  GDB can not retrieve the list of currently
8795 
loaded libraries through memory operations, so it uses the
8796 
`qXfer:libraries:read' packet (*note qXfer library list read::)
8797 
instead.  The remote stub queries the target's operating system and
8798 
reports which libraries are loaded.
8799 
 
8800 
   The `qXfer:libraries:read' packet returns an XML document which
8801 
lists loaded libraries and their offsets.  Each library has an
8802 
associated name and one or more segment base addresses, which report
8803 
where the library was loaded in memory.  The segment bases are start
8804 
addresses, not relocation offsets; they do not depend on the library's
8805 
link-time base addresses.
8806 
 
8807 
   GDB must be linked with the Expat library to support XML library
8808 
lists.  *Note Expat::.
8809 
 
8810 
   A simple memory map, with one loaded library relocated by a single
8811 
offset, looks like this:
8812 
 
8813
8814
8815
8816
8817
8818 
 
8819 
   The format of a library list is described by this DTD:
8820 
 
8821
8822
8823
8824
8825
8826
8827
8828 
 
8829 

8830 
File: gdb.info,  Node: Memory Map Format,  Prev: Library List Format,  Up: Remote Protocol
8831 
 
8832 
D.12 Memory Map Format
8833 
======================
8834 
 
8835 
To be able to write into flash memory, GDB needs to obtain a memory map
8836 
from the target.  This section describes the format of the memory map.
8837 
 
8838 
   The memory map is obtained using the `qXfer:memory-map:read' (*note
8839 
qXfer memory map read::) packet and is an XML document that lists
8840 
memory regions.
8841 
 
8842 
   GDB must be linked with the Expat library to support XML memory
8843 
maps.  *Note Expat::.
8844 
 
8845 
   The top-level structure of the document is shown below:
8846 
 
8847
8848
8849 
               PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
8850 
                      "http://sourceware.org/gdb/gdb-memory-map.dtd">
8851
8852 
         region...
8853
8854 
 
8855 
   Each region can be either:
8856 
 
8857 
   * A region of RAM starting at ADDR and extending for LENGTH bytes
8858 
     from there:
8859 
 
8860
8861 
 
8862 
   * A region of read-only memory:
8863 
 
8864
8865 
 
8866 
   * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
8867 
     length:
8868 
 
8869
8870 
            BLOCKSIZE
8871
8872 
 
8873 
 
8874 
   Regions must not overlap.  GDB assumes that areas of memory not
8875 
covered by the memory map are RAM, and uses the ordinary `M' and `X'
8876 
packets to write to addresses in such ranges.
8877 
 
8878 
   The formal DTD for memory map format is given below:
8879 
 
8880
8881
8882
8883
8884
8885
8886
8887
8888
8889
8891
8892 
                             start   CDATA   #REQUIRED
8893 
                             length  CDATA   #REQUIRED
8894 
                             device  CDATA   #IMPLIED>
8895
8896
8897
8898 
 
8899 

8900 
File: gdb.info,  Node: Agent Expressions,  Next: Target Descriptions,  Prev: Remote Protocol,  Up: Top
8901 
 
8902 
Appendix E The GDB Agent Expression Mechanism
8903 
*********************************************
8904 
 
8905 
In some applications, it is not feasible for the debugger to interrupt
8906 
the program's execution long enough for the developer to learn anything
8907 
helpful about its behavior.  If the program's correctness depends on its
8908 
real-time behavior, delays introduced by a debugger might cause the
8909 
program to fail, even when the code itself is correct.  It is useful to
8910 
be able to observe the program's behavior without interrupting it.
8911 
 
8912 
   Using GDB's `trace' and `collect' commands, the user can specify
8913 
locations in the program, and arbitrary expressions to evaluate when
8914 
those locations are reached.  Later, using the `tfind' command, she can
8915 
examine the values those expressions had when the program hit the trace
8916 
points.  The expressions may also denote objects in memory --
8917 
structures or arrays, for example -- whose values GDB should record;
8918 
while visiting a particular tracepoint, the user may inspect those
8919 
objects as if they were in memory at that moment.  However, because GDB
8920 
records these values without interacting with the user, it can do so
8921 
quickly and unobtrusively, hopefully not disturbing the program's
8922 
behavior.
8923 
 
8924 
   When GDB is debugging a remote target, the GDB "agent" code running
8925 
on the target computes the values of the expressions itself.  To avoid
8926 
having a full symbolic expression evaluator on the agent, GDB translates
8927 
expressions in the source language into a simpler bytecode language, and
8928 
then sends the bytecode to the agent; the agent then executes the
8929 
bytecode, and records the values for GDB to retrieve later.
8930 
 
8931 
   The bytecode language is simple; there are forty-odd opcodes, the
8932 
bulk of which are the usual vocabulary of C operands (addition,
8933 
subtraction, shifts, and so on) and various sizes of literals and
8934 
memory reference operations.  The bytecode interpreter operates
8935 
strictly on machine-level values -- various sizes of integers and
8936 
floating point numbers -- and requires no information about types or
8937 
symbols; thus, the interpreter's internal data structures are simple,
8938 
and each bytecode requires only a few native machine instructions to
8939 
implement it.  The interpreter is small, and strict limits on the
8940 
memory and time required to evaluate an expression are easy to
8941 
determine, making it suitable for use by the debugging agent in
8942 
real-time applications.
8943 
 
8944 
* Menu:
8945 
 
8946 
* General Bytecode Design::     Overview of the interpreter.
8947 
* Bytecode Descriptions::       What each one does.
8948 
* Using Agent Expressions::     How agent expressions fit into the big picture.
8949 
* Varying Target Capabilities:: How to discover what the target can do.
8950 
* Tracing on Symmetrix::        Special info for implementation on EMC's
8951 
                                boxes.
8952 
* Rationale::                   Why we did it this way.
8953 
 
8954 

8955 
File: gdb.info,  Node: General Bytecode Design,  Next: Bytecode Descriptions,  Up: Agent Expressions
8956 
 
8957 
E.1 General Bytecode Design
8958 
===========================
8959 
 
8960 
The agent represents bytecode expressions as an array of bytes.  Each
8961 
instruction is one byte long (thus the term "bytecode").  Some
8962 
instructions are followed by operand bytes; for example, the `goto'
8963 
instruction is followed by a destination for the jump.
8964 
 
8965 
   The bytecode interpreter is a stack-based machine; most instructions
8966 
pop their operands off the stack, perform some operation, and push the
8967 
result back on the stack for the next instruction to consume.  Each
8968 
element of the stack may contain either a integer or a floating point
8969 
value; these values are as many bits wide as the largest integer that
8970 
can be directly manipulated in the source language.  Stack elements
8971 
carry no record of their type; bytecode could push a value as an
8972 
integer, then pop it as a floating point value.  However, GDB will not
8973 
generate code which does this.  In C, one might define the type of a
8974 
stack element as follows:
8975 
     union agent_val {
8976 
       LONGEST l;
8977 
       DOUBLEST d;
8978 
     };
8979 
   where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
8980 
integer and floating point types on the machine.
8981 
 
8982 
   By the time the bytecode interpreter reaches the end of the
8983 
expression, the value of the expression should be the only value left
8984 
on the stack.  For tracing applications, `trace' bytecodes in the
8985 
expression will have recorded the necessary data, and the value on the
8986 
stack may be discarded.  For other applications, like conditional
8987 
breakpoints, the value may be useful.
8988 
 
8989 
   Separate from the stack, the interpreter has two registers:
8990 
`pc'
8991 
     The address of the next bytecode to execute.
8992 
 
8993 
`start'
8994 
     The address of the start of the bytecode expression, necessary for
8995 
     interpreting the `goto' and `if_goto' instructions.
8996 
 
8997 
   Neither of these registers is directly visible to the bytecode
8998 
language itself, but they are useful for defining the meanings of the
8999 
bytecode operations.
9000 
 
9001 
   There are no instructions to perform side effects on the running
9002 
program, or call the program's functions; we assume that these
9003 
expressions are only used for unobtrusive debugging, not for patching
9004 
the running code.
9005 
 
9006 
   Most bytecode instructions do not distinguish between the various
9007 
sizes of values, and operate on full-width values; the upper bits of the
9008 
values are simply ignored, since they do not usually make a difference
9009 
to the value computed.  The exceptions to this rule are:
9010 
memory reference instructions (`ref'N)
9011 
     There are distinct instructions to fetch different word sizes from
9012 
     memory.  Once on the stack, however, the values are treated as
9013 
     full-size integers.  They may need to be sign-extended; the `ext'
9014 
     instruction exists for this purpose.
9015 
 
9016 
the sign-extension instruction (`ext' N)
9017 
     These clearly need to know which portion of their operand is to be
9018 
     extended to occupy the full length of the word.
9019 
 
9020 
 
9021 
   If the interpreter is unable to evaluate an expression completely for
9022 
some reason (a memory location is inaccessible, or a divisor is zero,
9023 
for example), we say that interpretation "terminates with an error".
9024 
This means that the problem is reported back to the interpreter's caller
9025 
in some helpful way.  In general, code using agent expressions should
9026 
assume that they may attempt to divide by zero, fetch arbitrary memory
9027 
locations, and misbehave in other ways.
9028 
 
9029 
   Even complicated C expressions compile to a few bytecode
9030 
instructions; for example, the expression `x + y * z' would typically
9031 
produce code like the following, assuming that `x' and `y' live in
9032 
registers, and `z' is a global variable holding a 32-bit `int':
9033 
     reg 1
9034 
     reg 2
9035 
     const32 address of z
9036 
     ref32
9037 
     ext 32
9038 
     mul
9039 
     add
9040 
     end
9041 
 
9042 
   In detail, these mean:
9043 
`reg 1'
9044 
     Push the value of register 1 (presumably holding `x') onto the
9045 
     stack.
9046 
 
9047 
`reg 2'
9048 
     Push the value of register 2 (holding `y').
9049 
 
9050 
`const32 address of z'
9051 
     Push the address of `z' onto the stack.
9052 
 
9053 
`ref32'
9054 
     Fetch a 32-bit word from the address at the top of the stack;
9055 
     replace the address on the stack with the value.  Thus, we replace
9056 
     the address of `z' with `z''s value.
9057 
 
9058 
`ext 32'
9059 
     Sign-extend the value on the top of the stack from 32 bits to full
9060 
     length.  This is necessary because `z' is a signed integer.
9061 
 
9062 
`mul'
9063 
     Pop the top two numbers on the stack, multiply them, and push their
9064 
     product.  Now the top of the stack contains the value of the
9065 
     expression `y * z'.
9066 
 
9067 
`add'
9068 
     Pop the top two numbers, add them, and push the sum.  Now the top
9069 
     of the stack contains the value of `x + y * z'.
9070 
 
9071 
`end'
9072 
     Stop executing; the value left on the stack top is the value to be
9073 
     recorded.
9074 
 
9075 
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.