OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [gnu-src/] [gdb-7.2/] [gdb/] [doc/] [gdb.info-4] - Blame information for rev 512

Details | Compare with Previous | View Log

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

44
File: gdb.info,  Node: GDB/MI Data Manipulation,  Next: GDB/MI Tracepoint Commands,  Prev: GDB/MI Variable Objects,  Up: GDB/MI
45
 
46
27.14 GDB/MI Data Manipulation
47
==============================
48
 
49
This section describes the GDB/MI commands that manipulate data:
50
examine memory and registers, evaluate expressions, etc.
51
 
52
The `-data-disassemble' Command
53
-------------------------------
54
 
55
Synopsis
56
........
57
 
58
      -data-disassemble
59
         [ -s START-ADDR -e END-ADDR ]
60
       | [ -f FILENAME -l LINENUM [ -n LINES ] ]
61
       -- MODE
62
 
63
Where:
64
 
65
`START-ADDR'
66
     is the beginning address (or `$pc')
67
 
68
`END-ADDR'
69
     is the end address
70
 
71
`FILENAME'
72
     is the name of the file to disassemble
73
 
74
`LINENUM'
75
     is the line number to disassemble around
76
 
77
`LINES'
78
     is the number of disassembly lines to be produced.  If it is -1,
79
     the whole function will be disassembled, in case no END-ADDR is
80
     specified.  If END-ADDR is specified as a non-zero value, and
81
     LINES is lower than the number of disassembly lines between
82
     START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
83
     is higher than the number of lines between START-ADDR and
84
     END-ADDR, only the lines up to END-ADDR are displayed.
85
 
86
`MODE'
87
     is either 0 (meaning only disassembly) or 1 (meaning mixed source
88
     and disassembly).
89
 
90
Result
91
......
92
 
93
The output for each instruction is composed of four fields:
94
 
95
   * Address
96
 
97
   * Func-name
98
 
99
   * Offset
100
 
101
   * Instruction
102
 
103
   Note that whatever included in the instruction field, is not
104
manipulated directly by GDB/MI, i.e., it is not possible to adjust its
105
format.
106
 
107
GDB Command
108
...........
109
 
110
There's no direct mapping from this command to the CLI.
111
 
112
Example
113
.......
114
 
115
Disassemble from the current value of `$pc' to `$pc + 20':
116
 
117
     (gdb)
118
     -data-disassemble -s $pc -e "$pc + 20" -- 0
119
     ^done,
120
     asm_insns=[
121
     {address="0x000107c0",func-name="main",offset="4",
122
     inst="mov  2, %o0"},
123
     {address="0x000107c4",func-name="main",offset="8",
124
     inst="sethi  %hi(0x11800), %o2"},
125
     {address="0x000107c8",func-name="main",offset="12",
126
     inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
127
     {address="0x000107cc",func-name="main",offset="16",
128
     inst="sethi  %hi(0x11800), %o2"},
129
     {address="0x000107d0",func-name="main",offset="20",
130
     inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
131
     (gdb)
132
 
133
   Disassemble the whole `main' function.  Line 32 is part of `main'.
134
 
135
     -data-disassemble -f basics.c -l 32 -- 0
136
     ^done,asm_insns=[
137
     {address="0x000107bc",func-name="main",offset="0",
138
     inst="save  %sp, -112, %sp"},
139
     {address="0x000107c0",func-name="main",offset="4",
140
     inst="mov   2, %o0"},
141
     {address="0x000107c4",func-name="main",offset="8",
142
     inst="sethi %hi(0x11800), %o2"},
143
     [...]
144
     {address="0x0001081c",func-name="main",offset="96",inst="ret "},
145
     {address="0x00010820",func-name="main",offset="100",inst="restore "}]
146
     (gdb)
147
 
148
   Disassemble 3 instructions from the start of `main':
149
 
150
     (gdb)
151
     -data-disassemble -f basics.c -l 32 -n 3 -- 0
152
     ^done,asm_insns=[
153
     {address="0x000107bc",func-name="main",offset="0",
154
     inst="save  %sp, -112, %sp"},
155
     {address="0x000107c0",func-name="main",offset="4",
156
     inst="mov  2, %o0"},
157
     {address="0x000107c4",func-name="main",offset="8",
158
     inst="sethi  %hi(0x11800), %o2"}]
159
     (gdb)
160
 
161
   Disassemble 3 instructions from the start of `main' in mixed mode:
162
 
163
     (gdb)
164
     -data-disassemble -f basics.c -l 32 -n 3 -- 1
165
     ^done,asm_insns=[
166
     src_and_asm_line={line="31",
167
     file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
168
       testsuite/gdb.mi/basics.c",line_asm_insn=[
169
     {address="0x000107bc",func-name="main",offset="0",
170
     inst="save  %sp, -112, %sp"}]},
171
     src_and_asm_line={line="32",
172
     file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
173
       testsuite/gdb.mi/basics.c",line_asm_insn=[
174
     {address="0x000107c0",func-name="main",offset="4",
175
     inst="mov  2, %o0"},
176
     {address="0x000107c4",func-name="main",offset="8",
177
     inst="sethi  %hi(0x11800), %o2"}]}]
178
     (gdb)
179
 
180
The `-data-evaluate-expression' Command
181
---------------------------------------
182
 
183
Synopsis
184
........
185
 
186
      -data-evaluate-expression EXPR
187
 
188
   Evaluate EXPR as an expression.  The expression could contain an
189
inferior function call.  The function call will execute synchronously.
190
If the expression contains spaces, it must be enclosed in double quotes.
191
 
192
GDB Command
193
...........
194
 
195
The corresponding GDB commands are `print', `output', and `call'.  In
196
`gdbtk' only, there's a corresponding `gdb_eval' command.
197
 
198
Example
199
.......
200
 
201
In the following example, the numbers that precede the commands are the
202 342 jeremybenn
"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command
203 330 jeremybenn
Syntax.  Notice how GDB/MI returns the same tokens in its output.
204
 
205
     211-data-evaluate-expression A
206
     211^done,value="1"
207
     (gdb)
208
     311-data-evaluate-expression &A
209
     311^done,value="0xefffeb7c"
210
     (gdb)
211
     411-data-evaluate-expression A+3
212
     411^done,value="4"
213
     (gdb)
214
     511-data-evaluate-expression "A + 3"
215
     511^done,value="4"
216
     (gdb)
217
 
218
The `-data-list-changed-registers' Command
219
------------------------------------------
220
 
221
Synopsis
222
........
223
 
224
      -data-list-changed-registers
225
 
226
   Display a list of the registers that have changed.
227
 
228
GDB Command
229
...........
230
 
231
GDB doesn't have a direct analog for this command; `gdbtk' has the
232
corresponding command `gdb_changed_register_list'.
233
 
234
Example
235
.......
236
 
237
On a PPC MBX board:
238
 
239
     (gdb)
240
     -exec-continue
241
     ^running
242
 
243
     (gdb)
244
     *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={
245
     func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
246
     line="5"}
247
     (gdb)
248
     -data-list-changed-registers
249
     ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
250
     "10","11","13","14","15","16","17","18","19","20","21","22","23",
251
     "24","25","26","27","28","30","31","64","65","66","67","69"]
252
     (gdb)
253
 
254
The `-data-list-register-names' Command
255
---------------------------------------
256
 
257
Synopsis
258
........
259
 
260
      -data-list-register-names [ ( REGNO )+ ]
261
 
262
   Show a list of register names for the current target.  If no
263
arguments are given, it shows a list of the names of all the registers.
264
If integer numbers are given as arguments, it will print a list of the
265
names of the registers corresponding to the arguments.  To ensure
266
consistency between a register name and its number, the output list may
267
include empty register names.
268
 
269
GDB Command
270
...........
271
 
272
GDB does not have a command which corresponds to
273
`-data-list-register-names'.  In `gdbtk' there is a corresponding
274
command `gdb_regnames'.
275
 
276
Example
277
.......
278
 
279
For the PPC MBX board:
280
     (gdb)
281
     -data-list-register-names
282
     ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
283
     "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
284
     "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
285
     "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
286
     "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
287
     "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
288
     "", "pc","ps","cr","lr","ctr","xer"]
289
     (gdb)
290
     -data-list-register-names 1 2 3
291
     ^done,register-names=["r1","r2","r3"]
292
     (gdb)
293
 
294
The `-data-list-register-values' Command
295
----------------------------------------
296
 
297
Synopsis
298
........
299
 
300
      -data-list-register-values FMT [ ( REGNO )*]
301
 
302
   Display the registers' contents.  FMT is the format according to
303
which the registers' contents are to be returned, followed by an
304
optional list of numbers specifying the registers to display.  A
305
missing list of numbers indicates that the contents of all the
306
registers must be returned.
307
 
308
   Allowed formats for FMT are:
309
 
310
`x'
311
     Hexadecimal
312
 
313
`o'
314
     Octal
315
 
316
`t'
317
     Binary
318
 
319
`d'
320
     Decimal
321
 
322
`r'
323
     Raw
324
 
325
`N'
326
     Natural
327
 
328
GDB Command
329
...........
330
 
331
The corresponding GDB commands are `info reg', `info all-reg', and (in
332
`gdbtk') `gdb_fetch_registers'.
333
 
334
Example
335
.......
336
 
337
For a PPC MBX board (note: line breaks are for readability only, they
338
don't appear in the actual output):
339
 
340
     (gdb)
341
     -data-list-register-values r 64 65
342
     ^done,register-values=[{number="64",value="0xfe00a300"},
343
     {number="65",value="0x00029002"}]
344
     (gdb)
345
     -data-list-register-values x
346
     ^done,register-values=[{number="0",value="0xfe0043c8"},
347
     {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
348
     {number="3",value="0x0"},{number="4",value="0xa"},
349
     {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
350
     {number="7",value="0xfe011e98"},{number="8",value="0x2"},
351
     {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
352
     {number="11",value="0x1"},{number="12",value="0x0"},
353
     {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
354
     {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
355
     {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
356
     {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
357
     {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
358
     {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
359
     {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
360
     {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
361
     {number="29",value="0x0"},{number="30",value="0xfe010000"},
362
     {number="31",value="0x0"},{number="32",value="0x0"},
363
     {number="33",value="0x0"},{number="34",value="0x0"},
364
     {number="35",value="0x0"},{number="36",value="0x0"},
365
     {number="37",value="0x0"},{number="38",value="0x0"},
366
     {number="39",value="0x0"},{number="40",value="0x0"},
367
     {number="41",value="0x0"},{number="42",value="0x0"},
368
     {number="43",value="0x0"},{number="44",value="0x0"},
369
     {number="45",value="0x0"},{number="46",value="0x0"},
370
     {number="47",value="0x0"},{number="48",value="0x0"},
371
     {number="49",value="0x0"},{number="50",value="0x0"},
372
     {number="51",value="0x0"},{number="52",value="0x0"},
373
     {number="53",value="0x0"},{number="54",value="0x0"},
374
     {number="55",value="0x0"},{number="56",value="0x0"},
375
     {number="57",value="0x0"},{number="58",value="0x0"},
376
     {number="59",value="0x0"},{number="60",value="0x0"},
377
     {number="61",value="0x0"},{number="62",value="0x0"},
378
     {number="63",value="0x0"},{number="64",value="0xfe00a300"},
379
     {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
380
     {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
381
     {number="69",value="0x20002b03"}]
382
     (gdb)
383
 
384
The `-data-read-memory' Command
385
-------------------------------
386
 
387
Synopsis
388
........
389
 
390
      -data-read-memory [ -o BYTE-OFFSET ]
391
        ADDRESS WORD-FORMAT WORD-SIZE
392
        NR-ROWS NR-COLS [ ASCHAR ]
393
 
394
where:
395
 
396
`ADDRESS'
397
     An expression specifying the address of the first memory word to be
398
     read.  Complex expressions containing embedded white space should
399
     be quoted using the C convention.
400
 
401
`WORD-FORMAT'
402
     The format to be used to print the memory words.  The notation is
403
     the same as for GDB's `print' command (*note Output Formats:
404
     Output Formats.).
405
 
406
`WORD-SIZE'
407
     The size of each memory word in bytes.
408
 
409
`NR-ROWS'
410
     The number of rows in the output table.
411
 
412
`NR-COLS'
413
     The number of columns in the output table.
414
 
415
`ASCHAR'
416
     If present, indicates that each row should include an ASCII dump.
417
     The value of ASCHAR is used as a padding character when a byte is
418
     not a member of the printable ASCII character set (printable ASCII
419
     characters are those whose code is between 32 and 126,
420
     inclusively).
421
 
422
`BYTE-OFFSET'
423
     An offset to add to the ADDRESS before fetching memory.
424
 
425
   This command displays memory contents as a table of NR-ROWS by
426
NR-COLS words, each word being WORD-SIZE bytes.  In total, `NR-ROWS *
427
NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
428
Should less than the requested number of bytes be returned by the
429
target, the missing words are identified using `N/A'.  The number of
430
bytes read from the target is returned in `nr-bytes' and the starting
431
address used to read memory in `addr'.
432
 
433
   The address of the next/previous row or page is available in
434
`next-row' and `prev-row', `next-page' and `prev-page'.
435
 
436
GDB Command
437
...........
438
 
439
The corresponding GDB command is `x'.  `gdbtk' has `gdb_get_mem' memory
440
read command.
441
 
442
Example
443
.......
444
 
445
Read six bytes of memory starting at `bytes+6' but then offset by `-6'
446
bytes.  Format as three rows of two columns.  One byte per word.
447
Display each word in hex.
448
 
449
     (gdb)
450
     9-data-read-memory -o -6 -- bytes+6 x 1 3 2
451
     9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
452
     next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
453
     prev-page="0x0000138a",memory=[
454
     {addr="0x00001390",data=["0x00","0x01"]},
455
     {addr="0x00001392",data=["0x02","0x03"]},
456
     {addr="0x00001394",data=["0x04","0x05"]}]
457
     (gdb)
458
 
459
   Read two bytes of memory starting at address `shorts + 64' and
460
display as a single word formatted in decimal.
461
 
462
     (gdb)
463
     5-data-read-memory shorts+64 d 2 1 1
464
     5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
465
     next-row="0x00001512",prev-row="0x0000150e",
466
     next-page="0x00001512",prev-page="0x0000150e",memory=[
467
     {addr="0x00001510",data=["128"]}]
468
     (gdb)
469
 
470
   Read thirty two bytes of memory starting at `bytes+16' and format as
471
eight rows of four columns.  Include a string encoding with `x' used as
472
the non-printable character.
473
 
474
     (gdb)
475
     4-data-read-memory bytes+16 x 1 8 4 x
476
     4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
477
     next-row="0x000013c0",prev-row="0x0000139c",
478
     next-page="0x000013c0",prev-page="0x00001380",memory=[
479
     {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
480
     {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
481
     {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
482
     {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
483
     {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
484
     {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
485
     {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
486
     {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
487
     (gdb)
488
 
489

490
File: gdb.info,  Node: GDB/MI Tracepoint Commands,  Next: GDB/MI Symbol Query,  Prev: GDB/MI Data Manipulation,  Up: GDB/MI
491
 
492
27.15 GDB/MI Tracepoint Commands
493
================================
494
 
495
The commands defined in this section implement MI support for
496 342 jeremybenn
tracepoints.  For detailed introduction, see *note Tracepoints::.
497 330 jeremybenn
 
498
The `-trace-find' Command
499
-------------------------
500
 
501
Synopsis
502
........
503
 
504
      -trace-find MODE [PARAMETERS...]
505
 
506
   Find a trace frame using criteria defined by MODE and PARAMETERS.
507
The following table lists permissible modes and their parameters.  For
508 342 jeremybenn
details of operation, see *note tfind::.
509 330 jeremybenn
 
510
`none'
511
     No parameters are required.  Stops examining trace frames.
512
 
513
`frame-number'
514
     An integer is required as parameter.  Selects tracepoint frame with
515
     that index.
516
 
517
`tracepoint-number'
518
     An integer is required as parameter.  Finds next trace frame that
519
     corresponds to tracepoint with the specified number.
520
 
521
`pc'
522
     An address is required as parameter.  Finds next trace frame that
523
     corresponds to any tracepoint at the specified address.
524
 
525
`pc-inside-range'
526
     Two addresses are required as parameters.  Finds next trace frame
527
     that corresponds to a tracepoint at an address inside the
528
     specified range.  Both bounds are considered to be inside the
529
     range.
530
 
531
`pc-outside-range'
532
     Two addresses are required as parameters.  Finds next trace frame
533
     that corresponds to a tracepoint at an address outside the
534
     specified range.  Both bounds are considered to be inside the
535
     range.
536
 
537
`line'
538
     Line specification is required as parameter.  *Note Specify
539
     Location::.  Finds next trace frame that corresponds to a
540
     tracepoint at the specified location.
541
 
542
 
543
   If `none' was passed as MODE, the response does not have fields.
544
Otherwise, the response may have the following fields:
545
 
546
`found'
547
     This field has either `0' or `1' as the value, depending on
548
     whether a matching tracepoint was found.
549
 
550
`traceframe'
551
     The index of the found traceframe.  This field is present iff the
552
     `found' field has value of `1'.
553
 
554
`tracepoint'
555
     The index of the found tracepoint.  This field is present iff the
556
     `found' field has value of `1'.
557
 
558
`frame'
559
     The information about the frame corresponding to the found trace
560
     frame.  This field is present only if a trace frame was found.
561
     *Note GDB/MI Frame Information::, for description of this field.
562
 
563
 
564
GDB Command
565
...........
566
 
567
The corresponding GDB command is `tfind'.
568
 
569
-trace-define-variable
570
----------------------
571
 
572
Synopsis
573
........
574
 
575
      -trace-define-variable NAME [ VALUE ]
576
 
577
   Create trace variable NAME if it does not exist.  If VALUE is
578
specified, sets the initial value of the specified trace variable to
579
that value.  Note that the NAME should start with the `$' character.
580
 
581
GDB Command
582
...........
583
 
584
The corresponding GDB command is `tvariable'.
585
 
586
-trace-list-variables
587
---------------------
588
 
589
Synopsis
590
........
591
 
592
      -trace-list-variables
593
 
594
   Return a table of all defined trace variables.  Each element of the
595
table has the following fields:
596
 
597
`name'
598
     The name of the trace variable.  This field is always present.
599
 
600
`initial'
601
     The initial value.  This is a 64-bit signed integer.  This field
602
     is always present.
603
 
604
`current'
605
     The value the trace variable has at the moment.  This is a 64-bit
606
     signed integer.  This field is absent iff current value is not
607
     defined, for example if the trace was never run, or is presently
608
     running.
609
 
610
 
611
GDB Command
612
...........
613
 
614
The corresponding GDB command is `tvariables'.
615
 
616
Example
617
.......
618
 
619
     (gdb)
620
     -trace-list-variables
621
     ^done,trace-variables={nr_rows="1",nr_cols="3",
622
     hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"},
623
          {width="11",alignment="-1",col_name="initial",colhdr="Initial"},
624
          {width="11",alignment="-1",col_name="current",colhdr="Current"}],
625
     body=[variable={name="$trace_timestamp",initial="0"}
626
           variable={name="$foo",initial="10",current="15"}]}
627
     (gdb)
628
 
629
-trace-save
630
-----------
631
 
632
Synopsis
633
........
634
 
635
      -trace-save [-r ] FILENAME
636
 
637
   Saves the collected trace data to FILENAME.  Without the `-r'
638
option, the data is downloaded from the target and saved in a local
639
file.  With the `-r' option the target is asked to perform the save.
640
 
641
GDB Command
642
...........
643
 
644
The corresponding GDB command is `tsave'.
645
 
646
-trace-start
647
------------
648
 
649
Synopsis
650
........
651
 
652
      -trace-start
653
 
654
   Starts a tracing experiments.  The result of this command does not
655
have any fields.
656
 
657
GDB Command
658
...........
659
 
660
The corresponding GDB command is `tstart'.
661
 
662
-trace-status
663
-------------
664
 
665
Synopsis
666
........
667
 
668
      -trace-status
669
 
670
   Obtains the status of a tracing experiment.  The result may include
671
the following fields:
672
 
673
`supported'
674
     May have a value of either `0', when no tracing operations are
675
     supported, `1', when all tracing operations are supported, or
676
     `file' when examining trace file.  In the latter case, examining
677
     of trace frame is possible but new tracing experiement cannot be
678
     started.  This field is always present.
679
 
680
`running'
681
     May have a value of either `0' or `1' depending on whether tracing
682
     experiement is in progress on target.  This field is present if
683
     `supported' field is not `0'.
684
 
685
`stop-reason'
686
     Report the reason why the tracing was stopped last time.  This
687
     field may be absent iff tracing was never stopped on target yet.
688
     The value of `request' means the tracing was stopped as result of
689
     the `-trace-stop' command.  The value of `overflow' means the
690
     tracing buffer is full.  The value of `disconnection' means
691
     tracing was automatically stopped when GDB has disconnected.  The
692
     value of `passcount' means tracing was stopped when a tracepoint
693
     was passed a maximal number of times for that tracepoint.  This
694
     field is present if `supported' field is not `0'.
695
 
696
`stopping-tracepoint'
697
     The number of tracepoint whose passcount as exceeded.  This field
698
     is present iff the `stop-reason' field has the value of
699
     `passcount'.
700
 
701
`frames'
702
`frames-created'
703
     The `frames' field is a count of the total number of trace frames
704
     in the trace buffer, while `frames-created' is the total created
705
     during the run, including ones that were discarded, such as when a
706
     circular trace buffer filled up.  Both fields are optional.
707
 
708
`buffer-size'
709
`buffer-free'
710
     These fields tell the current size of the tracing buffer and the
711
     remaining space.  These fields are optional.
712
 
713
`circular'
714
     The value of the circular trace buffer flag.  `1' means that the
715
     trace buffer is circular and old trace frames will be discarded if
716
     necessary to make room, `0' means that the trace buffer is linear
717
     and may fill up.
718
 
719
`disconnected'
720
     The value of the disconnected tracing flag.  `1' means that
721
     tracing will continue after GDB disconnects, `0' means that the
722
     trace run will stop.
723
 
724
 
725
GDB Command
726
...........
727
 
728
The corresponding GDB command is `tstatus'.
729
 
730
-trace-stop
731
-----------
732
 
733
Synopsis
734
........
735
 
736
      -trace-stop
737
 
738
   Stops a tracing experiment.  The result of this command has the same
739
fields as `-trace-status', except that the `supported' and `running'
740
fields are not output.
741
 
742
GDB Command
743
...........
744
 
745
The corresponding GDB command is `tstop'.
746
 
747

748
File: gdb.info,  Node: GDB/MI Symbol Query,  Next: GDB/MI File Commands,  Prev: GDB/MI Tracepoint Commands,  Up: GDB/MI
749
 
750
27.16 GDB/MI Symbol Query Commands
751
==================================
752
 
753
The `-symbol-list-lines' Command
754
--------------------------------
755
 
756
Synopsis
757
........
758
 
759
      -symbol-list-lines FILENAME
760
 
761
   Print the list of lines that contain code and their associated
762
program addresses for the given source filename.  The entries are
763
sorted in ascending PC order.
764
 
765
GDB Command
766
...........
767
 
768
There is no corresponding GDB command.
769
 
770
Example
771
.......
772
 
773
     (gdb)
774
     -symbol-list-lines basics.c
775
     ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
776
     (gdb)
777
 
778

779
File: gdb.info,  Node: GDB/MI File Commands,  Next: GDB/MI Target Manipulation,  Prev: GDB/MI Symbol Query,  Up: GDB/MI
780
 
781
27.17 GDB/MI File Commands
782
==========================
783
 
784
This section describes the GDB/MI commands to specify executable file
785
names and to read in and obtain symbol table information.
786
 
787
The `-file-exec-and-symbols' Command
788
------------------------------------
789
 
790
Synopsis
791
........
792
 
793
      -file-exec-and-symbols FILE
794
 
795
   Specify the executable file to be debugged.  This file is the one
796
from which the symbol table is also read.  If no file is specified, the
797
command clears the executable and symbol information.  If breakpoints
798
are set when using this command with no arguments, GDB will produce
799
error messages.  Otherwise, no output is produced, except a completion
800
notification.
801
 
802
GDB Command
803
...........
804
 
805
The corresponding GDB command is `file'.
806
 
807
Example
808
.......
809
 
810
     (gdb)
811
     -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
812
     ^done
813
     (gdb)
814
 
815
The `-file-exec-file' Command
816
-----------------------------
817
 
818
Synopsis
819
........
820
 
821
      -file-exec-file FILE
822
 
823
   Specify the executable file to be debugged.  Unlike
824
`-file-exec-and-symbols', the symbol table is _not_ read from this
825
file.  If used without argument, GDB clears the information about the
826
executable file.  No output is produced, except a completion
827
notification.
828
 
829
GDB Command
830
...........
831
 
832
The corresponding GDB command is `exec-file'.
833
 
834
Example
835
.......
836
 
837
     (gdb)
838
     -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
839
     ^done
840
     (gdb)
841
 
842
The `-file-list-exec-source-file' Command
843
-----------------------------------------
844
 
845
Synopsis
846
........
847
 
848
      -file-list-exec-source-file
849
 
850
   List the line number, the current source file, and the absolute path
851
to the current source file for the current executable.  The macro
852
information field has a value of `1' or `0' depending on whether or not
853
the file includes preprocessor macro information.
854
 
855
GDB Command
856
...........
857
 
858
The GDB equivalent is `info source'
859
 
860
Example
861
.......
862
 
863
     (gdb)
864
     123-file-list-exec-source-file
865
     123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
866
     (gdb)
867
 
868
The `-file-list-exec-source-files' Command
869
------------------------------------------
870
 
871
Synopsis
872
........
873
 
874
      -file-list-exec-source-files
875
 
876
   List the source files for the current executable.
877
 
878
   It will always output the filename, but only when GDB can find the
879
absolute file name of a source file, will it output the fullname.
880
 
881
GDB Command
882
...........
883
 
884
The GDB equivalent is `info sources'.  `gdbtk' has an analogous command
885
`gdb_listfiles'.
886
 
887
Example
888
.......
889
 
890
     (gdb)
891
     -file-list-exec-source-files
892
     ^done,files=[
893
     {file=foo.c,fullname=/home/foo.c},
894
     {file=/home/bar.c,fullname=/home/bar.c},
895
     {file=gdb_could_not_find_fullpath.c}]
896
     (gdb)
897
 
898
The `-file-symbol-file' Command
899
-------------------------------
900
 
901
Synopsis
902
........
903
 
904
      -file-symbol-file FILE
905
 
906
   Read symbol table info from the specified FILE argument.  When used
907
without arguments, clears GDB's symbol table info.  No output is
908
produced, except for a completion notification.
909
 
910
GDB Command
911
...........
912
 
913
The corresponding GDB command is `symbol-file'.
914
 
915
Example
916
.......
917
 
918
     (gdb)
919
     -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
920
     ^done
921
     (gdb)
922
 
923

924
File: gdb.info,  Node: GDB/MI Target Manipulation,  Next: GDB/MI File Transfer Commands,  Prev: GDB/MI File Commands,  Up: GDB/MI
925
 
926
27.18 GDB/MI Target Manipulation Commands
927
=========================================
928
 
929
The `-target-attach' Command
930
----------------------------
931
 
932
Synopsis
933
........
934
 
935
      -target-attach PID | GID | FILE
936
 
937
   Attach to a process PID or a file FILE outside of GDB, or a thread
938
group GID.  If attaching to a thread group, the id previously returned
939
by `-list-thread-groups --available' must be used.
940
 
941
GDB Command
942
...........
943
 
944
The corresponding GDB command is `attach'.
945
 
946
Example
947
.......
948
 
949
     (gdb)
950
     -target-attach 34
951
     =thread-created,id="1"
952
     *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}
953
     ^done
954
     (gdb)
955
 
956
The `-target-detach' Command
957
----------------------------
958
 
959
Synopsis
960
........
961
 
962
      -target-detach [ PID | GID ]
963
 
964
   Detach from the remote target which normally resumes its execution.
965
If either PID or GID is specified, detaches from either the specified
966
process, or specified thread group.  There's no output.
967
 
968
GDB Command
969
...........
970
 
971
The corresponding GDB command is `detach'.
972
 
973
Example
974
.......
975
 
976
     (gdb)
977
     -target-detach
978
     ^done
979
     (gdb)
980
 
981
The `-target-disconnect' Command
982
--------------------------------
983
 
984
Synopsis
985
........
986
 
987
      -target-disconnect
988
 
989
   Disconnect from the remote target.  There's no output and the target
990
is generally not resumed.
991
 
992
GDB Command
993
...........
994
 
995
The corresponding GDB command is `disconnect'.
996
 
997
Example
998
.......
999
 
1000
     (gdb)
1001
     -target-disconnect
1002
     ^done
1003
     (gdb)
1004
 
1005
The `-target-download' Command
1006
------------------------------
1007
 
1008
Synopsis
1009
........
1010
 
1011
      -target-download
1012
 
1013
   Loads the executable onto the remote target.  It prints out an
1014
update message every half second, which includes the fields:
1015
 
1016
`section'
1017
     The name of the section.
1018
 
1019
`section-sent'
1020
     The size of what has been sent so far for that section.
1021
 
1022
`section-size'
1023
     The size of the section.
1024
 
1025
`total-sent'
1026
     The total size of what was sent so far (the current and the
1027
     previous sections).
1028
 
1029
`total-size'
1030
     The size of the overall executable to download.
1031
 
1032
Each message is sent as status record (*note GDB/MI Output Syntax:
1033
GDB/MI Output Syntax.).
1034
 
1035
   In addition, it prints the name and size of the sections, as they are
1036
downloaded.  These messages include the following fields:
1037
 
1038
`section'
1039
     The name of the section.
1040
 
1041
`section-size'
1042
     The size of the section.
1043
 
1044
`total-size'
1045
     The size of the overall executable to download.
1046
 
1047
At the end, a summary is printed.
1048
 
1049
GDB Command
1050
...........
1051
 
1052
The corresponding GDB command is `load'.
1053
 
1054
Example
1055
.......
1056
 
1057
Note: each status message appears on a single line.  Here the messages
1058
have been broken down so that they can fit onto a page.
1059
 
1060
     (gdb)
1061
     -target-download
1062
     +download,{section=".text",section-size="6668",total-size="9880"}
1063
     +download,{section=".text",section-sent="512",section-size="6668",
1064
     total-sent="512",total-size="9880"}
1065
     +download,{section=".text",section-sent="1024",section-size="6668",
1066
     total-sent="1024",total-size="9880"}
1067
     +download,{section=".text",section-sent="1536",section-size="6668",
1068
     total-sent="1536",total-size="9880"}
1069
     +download,{section=".text",section-sent="2048",section-size="6668",
1070
     total-sent="2048",total-size="9880"}
1071
     +download,{section=".text",section-sent="2560",section-size="6668",
1072
     total-sent="2560",total-size="9880"}
1073
     +download,{section=".text",section-sent="3072",section-size="6668",
1074
     total-sent="3072",total-size="9880"}
1075
     +download,{section=".text",section-sent="3584",section-size="6668",
1076
     total-sent="3584",total-size="9880"}
1077
     +download,{section=".text",section-sent="4096",section-size="6668",
1078
     total-sent="4096",total-size="9880"}
1079
     +download,{section=".text",section-sent="4608",section-size="6668",
1080
     total-sent="4608",total-size="9880"}
1081
     +download,{section=".text",section-sent="5120",section-size="6668",
1082
     total-sent="5120",total-size="9880"}
1083
     +download,{section=".text",section-sent="5632",section-size="6668",
1084
     total-sent="5632",total-size="9880"}
1085
     +download,{section=".text",section-sent="6144",section-size="6668",
1086
     total-sent="6144",total-size="9880"}
1087
     +download,{section=".text",section-sent="6656",section-size="6668",
1088
     total-sent="6656",total-size="9880"}
1089
     +download,{section=".init",section-size="28",total-size="9880"}
1090
     +download,{section=".fini",section-size="28",total-size="9880"}
1091
     +download,{section=".data",section-size="3156",total-size="9880"}
1092
     +download,{section=".data",section-sent="512",section-size="3156",
1093
     total-sent="7236",total-size="9880"}
1094
     +download,{section=".data",section-sent="1024",section-size="3156",
1095
     total-sent="7748",total-size="9880"}
1096
     +download,{section=".data",section-sent="1536",section-size="3156",
1097
     total-sent="8260",total-size="9880"}
1098
     +download,{section=".data",section-sent="2048",section-size="3156",
1099
     total-sent="8772",total-size="9880"}
1100
     +download,{section=".data",section-sent="2560",section-size="3156",
1101
     total-sent="9284",total-size="9880"}
1102
     +download,{section=".data",section-sent="3072",section-size="3156",
1103
     total-sent="9796",total-size="9880"}
1104
     ^done,address="0x10004",load-size="9880",transfer-rate="6586",
1105
     write-rate="429"
1106
     (gdb)
1107
 
1108
GDB Command
1109
...........
1110
 
1111
No equivalent.
1112
 
1113
Example
1114
.......
1115
 
1116
N.A.
1117
 
1118
The `-target-select' Command
1119
----------------------------
1120
 
1121
Synopsis
1122
........
1123
 
1124
      -target-select TYPE PARAMETERS ...
1125
 
1126
   Connect GDB to the remote target.  This command takes two args:
1127
 
1128
`TYPE'
1129
     The type of target, for instance `remote', etc.
1130
 
1131
`PARAMETERS'
1132
     Device names, host names and the like.  *Note Commands for
1133
     Managing Targets: Target Commands, for more details.
1134
 
1135
   The output is a connection notification, followed by the address at
1136
which the target program is, in the following form:
1137
 
1138
     ^connected,addr="ADDRESS",func="FUNCTION NAME",
1139
       args=[ARG LIST]
1140
 
1141
GDB Command
1142
...........
1143
 
1144
The corresponding GDB command is `target'.
1145
 
1146
Example
1147
.......
1148
 
1149
     (gdb)
1150
     -target-select remote /dev/ttya
1151
     ^connected,addr="0xfe00a300",func="??",args=[]
1152
     (gdb)
1153
 
1154

1155
File: gdb.info,  Node: GDB/MI File Transfer Commands,  Next: GDB/MI Miscellaneous Commands,  Prev: GDB/MI Target Manipulation,  Up: GDB/MI
1156
 
1157
27.19 GDB/MI File Transfer Commands
1158
===================================
1159
 
1160
The `-target-file-put' Command
1161
------------------------------
1162
 
1163
Synopsis
1164
........
1165
 
1166
      -target-file-put HOSTFILE TARGETFILE
1167
 
1168
   Copy file HOSTFILE from the host system (the machine running GDB) to
1169
TARGETFILE on the target system.
1170
 
1171
GDB Command
1172
...........
1173
 
1174
The corresponding GDB command is `remote put'.
1175
 
1176
Example
1177
.......
1178
 
1179
     (gdb)
1180
     -target-file-put localfile remotefile
1181
     ^done
1182
     (gdb)
1183
 
1184
The `-target-file-get' Command
1185
------------------------------
1186
 
1187
Synopsis
1188
........
1189
 
1190
      -target-file-get TARGETFILE HOSTFILE
1191
 
1192
   Copy file TARGETFILE from the target system to HOSTFILE on the host
1193
system.
1194
 
1195
GDB Command
1196
...........
1197
 
1198
The corresponding GDB command is `remote get'.
1199
 
1200
Example
1201
.......
1202
 
1203
     (gdb)
1204
     -target-file-get remotefile localfile
1205
     ^done
1206
     (gdb)
1207
 
1208
The `-target-file-delete' Command
1209
---------------------------------
1210
 
1211
Synopsis
1212
........
1213
 
1214
      -target-file-delete TARGETFILE
1215
 
1216
   Delete TARGETFILE from the target system.
1217
 
1218
GDB Command
1219
...........
1220
 
1221
The corresponding GDB command is `remote delete'.
1222
 
1223
Example
1224
.......
1225
 
1226
     (gdb)
1227
     -target-file-delete remotefile
1228
     ^done
1229
     (gdb)
1230
 
1231

1232
File: gdb.info,  Node: GDB/MI Miscellaneous Commands,  Prev: GDB/MI File Transfer Commands,  Up: GDB/MI
1233
 
1234
27.20 Miscellaneous GDB/MI Commands
1235
===================================
1236
 
1237
The `-gdb-exit' Command
1238
-----------------------
1239
 
1240
Synopsis
1241
........
1242
 
1243
      -gdb-exit
1244
 
1245
   Exit GDB immediately.
1246
 
1247
GDB Command
1248
...........
1249
 
1250
Approximately corresponds to `quit'.
1251
 
1252
Example
1253
.......
1254
 
1255
     (gdb)
1256
     -gdb-exit
1257
     ^exit
1258
 
1259
The `-gdb-set' Command
1260
----------------------
1261
 
1262
Synopsis
1263
........
1264
 
1265
      -gdb-set
1266
 
1267
   Set an internal GDB variable.
1268
 
1269
GDB Command
1270
...........
1271
 
1272
The corresponding GDB command is `set'.
1273
 
1274
Example
1275
.......
1276
 
1277
     (gdb)
1278
     -gdb-set $foo=3
1279
     ^done
1280
     (gdb)
1281
 
1282
The `-gdb-show' Command
1283
-----------------------
1284
 
1285
Synopsis
1286
........
1287
 
1288
      -gdb-show
1289
 
1290
   Show the current value of a GDB variable.
1291
 
1292
GDB Command
1293
...........
1294
 
1295
The corresponding GDB command is `show'.
1296
 
1297
Example
1298
.......
1299
 
1300
     (gdb)
1301
     -gdb-show annotate
1302
     ^done,value="0"
1303
     (gdb)
1304
 
1305
The `-gdb-version' Command
1306
--------------------------
1307
 
1308
Synopsis
1309
........
1310
 
1311
      -gdb-version
1312
 
1313
   Show version information for GDB.  Used mostly in testing.
1314
 
1315
GDB Command
1316
...........
1317
 
1318
The GDB equivalent is `show version'.  GDB by default shows this
1319
information when you start an interactive session.
1320
 
1321
Example
1322
.......
1323
 
1324
     (gdb)
1325
     -gdb-version
1326
     ~GNU gdb 5.2.1
1327
     ~Copyright 2000 Free Software Foundation, Inc.
1328
     ~GDB is free software, covered by the GNU General Public License, and
1329
     ~you are welcome to change it and/or distribute copies of it under
1330
     ~ certain conditions.
1331
     ~Type "show copying" to see the conditions.
1332
     ~There is absolutely no warranty for GDB.  Type "show warranty" for
1333
     ~ details.
1334
     ~This GDB was configured as
1335
      "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
1336
     ^done
1337
     (gdb)
1338
 
1339
The `-list-features' Command
1340
----------------------------
1341
 
1342
Returns a list of particular features of the MI protocol that this
1343
version of gdb implements.  A feature can be a command, or a new field
1344
in an output of some command, or even an important bugfix.  While a
1345
frontend can sometimes detect presence of a feature at runtime, it is
1346
easier to perform detection at debugger startup.
1347
 
1348
   The command returns a list of strings, with each string naming an
1349
available feature.  Each returned string is just a name, it does not
1350
have any internal structure.  The list of possible feature names is
1351
given below.
1352
 
1353
   Example output:
1354
 
1355
     (gdb) -list-features
1356
     ^done,result=["feature1","feature2"]
1357
 
1358
   The current list of features is:
1359
 
1360
`frozen-varobjs'
1361
     Indicates presence of the `-var-set-frozen' command, as well as
1362
     possible presense of the `frozen' field in the output of
1363
     `-varobj-create'.
1364
 
1365
`pending-breakpoints'
1366
     Indicates presence of the `-f' option to the `-break-insert'
1367
     command.
1368
 
1369
`python'
1370
     Indicates presence of Python scripting support, Python-based
1371
     pretty-printing commands, and possible presence of the
1372
     `display_hint' field in the output of `-var-list-children'
1373
 
1374
`thread-info'
1375
     Indicates presence of the `-thread-info' command.
1376
 
1377
 
1378
The `-list-target-features' Command
1379
-----------------------------------
1380
 
1381
Returns a list of particular features that are supported by the target.
1382
Those features affect the permitted MI commands, but unlike the
1383
features reported by the `-list-features' command, the features depend
1384
on which target GDB is using at the moment.  Whenever a target can
1385
change, due to commands such as `-target-select', `-target-attach' or
1386
`-exec-run', the list of target features may change, and the frontend
1387
should obtain it again.  Example output:
1388
 
1389
     (gdb) -list-features
1390
     ^done,result=["async"]
1391
 
1392
   The current list of features is:
1393
 
1394
`async'
1395
     Indicates that the target is capable of asynchronous command
1396
     execution, which means that GDB will accept further commands while
1397
     the target is running.
1398
 
1399
`reverse'
1400
     Indicates that the target is capable of reverse execution.  *Note
1401
     Reverse Execution::, for more information.
1402
 
1403
 
1404
The `-list-thread-groups' Command
1405
---------------------------------
1406
 
1407
Synopsis
1408
--------
1409
 
1410
     -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
1411
 
1412
   Lists thread groups (*note Thread groups::).  When a single thread
1413
group is passed as the argument, lists the children of that group.
1414
When several thread group are passed, lists information about those
1415
thread groups.  Without any parameters, lists information about all
1416
top-level thread groups.
1417
 
1418
   Normally, thread groups that are being debugged are reported.  With
1419
the `--available' option, GDB reports thread groups available on the
1420
target.
1421
 
1422
   The output of this command may have either a `threads' result or a
1423
`groups' result.  The `thread' result has a list of tuples as value,
1424
with each tuple describing a thread (*note GDB/MI Thread
1425
Information::).  The `groups' result has a list of tuples as value,
1426
each tuple describing a thread group.  If top-level groups are
1427
requested (that is, no parameter is passed), or when several groups are
1428
passed, the output always has a `groups' result.  The format of the
1429
`group' result is described below.
1430
 
1431
   To reduce the number of roundtrips it's possible to list thread
1432
groups together with their children, by passing the `--recurse' option
1433
and the recursion depth.  Presently, only recursion depth of 1 is
1434
permitted.  If this option is present, then every reported thread group
1435
will also include its children, either as `group' or `threads' field.
1436
 
1437
   In general, any combination of option and parameters is permitted,
1438
with the following caveats:
1439
 
1440
   * When a single thread group is passed, the output will typically be
1441
     the `threads' result.  Because threads may not contain anything,
1442
     the `recurse' option will be ignored.
1443
 
1444
   * When the `--available' option is passed, limited information may
1445
     be available.  In particular, the list of threads of a process
1446
     might be inaccessible.  Further, specifying specific thread groups
1447
     might not give any performance advantage over listing all thread
1448
     groups.  The frontend should assume that `-list-thread-groups
1449
     --available' is always an expensive operation and cache the
1450
     results.
1451
 
1452
 
1453
   The `groups' result is a list of tuples, where each tuple may have
1454
the following fields:
1455
 
1456
`id'
1457
     Identifier of the thread group.  This field is always present.
1458
     The identifier is an opaque string; frontends should not try to
1459
     convert it to an integer, even though it might look like one.
1460
 
1461
`type'
1462
     The type of the thread group.  At present, only `process' is a
1463
     valid type.
1464
 
1465
`pid'
1466
     The target-specific process identifier.  This field is only present
1467
     for thread groups of type `process' and only if the process exists.
1468
 
1469
`num_children'
1470
     The number of children this thread group has.  This field may be
1471
     absent for an available thread group.
1472
 
1473
`threads'
1474
     This field has a list of tuples as value, each tuple describing a
1475
     thread.  It may be present if the `--recurse' option is specified,
1476
     and it's actually possible to obtain the threads.
1477
 
1478
`cores'
1479
     This field is a list of integers, each identifying a core that one
1480
     thread of the group is running on.  This field may be absent if
1481
     such information is not available.
1482
 
1483
`executable'
1484
     The name of the executable file that corresponds to this thread
1485
     group.  The field is only present for thread groups of type
1486
     `process', and only if there is a corresponding executable file.
1487
 
1488
 
1489
Example
1490
-------
1491
 
1492
     gdb
1493
     -list-thread-groups
1494
     ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
1495
     -list-thread-groups 17
1496
     ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
1497
        frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
1498
     {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
1499
        frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
1500
                file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
1501
     -list-thread-groups --available
1502
     ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
1503
     -list-thread-groups --available --recurse 1
1504
      ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
1505
                     threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
1506
                              {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
1507
     -list-thread-groups --available --recurse 1 17 18
1508
     ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
1509
                    threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
1510
                             {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
1511
 
1512
The `-add-inferior' Command
1513
---------------------------
1514
 
1515
Synopsis
1516
--------
1517
 
1518
     -add-inferior
1519
 
1520
   Creates a new inferior (*note Inferiors and Programs::).  The created
1521
inferior is not associated with any executable.  Such association may
1522
be established with the `-file-exec-and-symbols' command (*note GDB/MI
1523
File Commands::).  The command response has a single field,
1524
`thread-group', whose value is the identifier of the thread group
1525
corresponding to the new inferior.
1526
 
1527
Example
1528
-------
1529
 
1530
     gdb
1531
     -add-inferior
1532
     ^done,thread-group="i3"
1533
 
1534
The `-interpreter-exec' Command
1535
-------------------------------
1536
 
1537
Synopsis
1538
--------
1539
 
1540
     -interpreter-exec INTERPRETER COMMAND
1541 342 jeremybenn
Execute the specified COMMAND in the given INTERPRETER.
1542 330 jeremybenn
 
1543
GDB Command
1544
-----------
1545
 
1546
The corresponding GDB command is `interpreter-exec'.
1547
 
1548
Example
1549
-------
1550
 
1551
     (gdb)
1552
     -interpreter-exec console "break main"
1553
     &"During symbol reading, couldn't parse type; debugger out of date?.\n"
1554
     &"During symbol reading, bad structure-type format.\n"
1555
     ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
1556
     ^done
1557
     (gdb)
1558
 
1559
The `-inferior-tty-set' Command
1560
-------------------------------
1561
 
1562
Synopsis
1563
--------
1564
 
1565
     -inferior-tty-set /dev/pts/1
1566
 
1567
   Set terminal for future runs of the program being debugged.
1568
 
1569
GDB Command
1570
-----------
1571
 
1572
The corresponding GDB command is `set inferior-tty' /dev/pts/1.
1573
 
1574
Example
1575
-------
1576
 
1577
     (gdb)
1578
     -inferior-tty-set /dev/pts/1
1579
     ^done
1580
     (gdb)
1581
 
1582
The `-inferior-tty-show' Command
1583
--------------------------------
1584
 
1585
Synopsis
1586
--------
1587
 
1588
     -inferior-tty-show
1589
 
1590
   Show terminal for future runs of program being debugged.
1591
 
1592
GDB Command
1593
-----------
1594
 
1595
The corresponding GDB command is `show inferior-tty'.
1596
 
1597
Example
1598
-------
1599
 
1600
     (gdb)
1601
     -inferior-tty-set /dev/pts/1
1602
     ^done
1603
     (gdb)
1604
     -inferior-tty-show
1605
     ^done,inferior_tty_terminal="/dev/pts/1"
1606
     (gdb)
1607
 
1608
The `-enable-timings' Command
1609
-----------------------------
1610
 
1611
Synopsis
1612
--------
1613
 
1614
     -enable-timings [yes | no]
1615
 
1616
   Toggle the printing of the wallclock, user and system times for an MI
1617
command as a field in its output.  This command is to help frontend
1618
developers optimize the performance of their code.  No argument is
1619
equivalent to `yes'.
1620
 
1621
GDB Command
1622
-----------
1623
 
1624
No equivalent.
1625
 
1626
Example
1627
-------
1628
 
1629
     (gdb)
1630
     -enable-timings
1631
     ^done
1632
     (gdb)
1633
     -break-insert main
1634
     ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
1635
     addr="0x080484ed",func="main",file="myprog.c",
1636
     fullname="/home/nickrob/myprog.c",line="73",times="0"},
1637
     time={wallclock="0.05185",user="0.00800",system="0.00000"}
1638
     (gdb)
1639
     -enable-timings no
1640
     ^done
1641
     (gdb)
1642
     -exec-run
1643
     ^running
1644
     (gdb)
1645
     *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
1646
     frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
1647
     {name="argv",value="0xbfb60364"}],file="myprog.c",
1648
     fullname="/home/nickrob/myprog.c",line="73"}
1649
     (gdb)
1650
 
1651

1652
File: gdb.info,  Node: Annotations,  Next: JIT Interface,  Prev: GDB/MI,  Up: Top
1653
 
1654
28 GDB Annotations
1655
******************
1656
 
1657
This chapter describes annotations in GDB.  Annotations were designed
1658
to interface GDB to graphical user interfaces or other similar programs
1659
which want to interact with GDB at a relatively high level.
1660
 
1661
   The annotation mechanism has largely been superseded by GDB/MI
1662
(*note GDB/MI::).
1663
 
1664
* Menu:
1665
 
1666
* Annotations Overview::  What annotations are; the general syntax.
1667
* Server Prefix::       Issuing a command without affecting user state.
1668
* Prompting::           Annotations marking GDB's need for input.
1669
* Errors::              Annotations for error messages.
1670
* Invalidation::        Some annotations describe things now invalid.
1671
* Annotations for Running::
1672
                        Whether the program is running, how it stopped, etc.
1673
* Source Annotations::  Annotations describing source code.
1674
 
1675

1676
File: gdb.info,  Node: Annotations Overview,  Next: Server Prefix,  Up: Annotations
1677
 
1678
28.1 What is an Annotation?
1679
===========================
1680
 
1681
Annotations start with a newline character, two `control-z' characters,
1682
and the name of the annotation.  If there is no additional information
1683
associated with this annotation, the name of the annotation is followed
1684
immediately by a newline.  If there is additional information, the name
1685
of the annotation is followed by a space, the additional information,
1686
and a newline.  The additional information cannot contain newline
1687
characters.
1688
 
1689
   Any output not beginning with a newline and two `control-z'
1690
characters denotes literal output from GDB.  Currently there is no need
1691
for GDB to output a newline followed by two `control-z' characters, but
1692
if there was such a need, the annotations could be extended with an
1693
`escape' annotation which means those three characters as output.
1694
 
1695
   The annotation LEVEL, which is specified using the `--annotate'
1696
command line option (*note Mode Options::), controls how much
1697
information GDB prints together with its prompt, values of expressions,
1698
source lines, and other types of output.  Level 0 is for no
1699
annotations, level 1 is for use when GDB is run as a subprocess of GNU
1700
Emacs, level 3 is the maximum annotation suitable for programs that
1701
control GDB, and level 2 annotations have been made obsolete (*note
1702
Limitations of the Annotation Interface: (annotate)Limitations.).
1703
 
1704
`set annotate LEVEL'
1705
     The GDB command `set annotate' sets the level of annotations to
1706
     the specified LEVEL.
1707
 
1708
`show annotate'
1709
     Show the current annotation level.
1710
 
1711
   This chapter describes level 3 annotations.
1712
 
1713
   A simple example of starting up GDB with annotations is:
1714
 
1715
     $ gdb --annotate=3
1716
     GNU gdb 6.0
1717
     Copyright 2003 Free Software Foundation, Inc.
1718
     GDB is free software, covered by the GNU General Public License,
1719
     and you are welcome to change it and/or distribute copies of it
1720
     under certain conditions.
1721
     Type "show copying" to see the conditions.
1722
     There is absolutely no warranty for GDB.  Type "show warranty"
1723
     for details.
1724
     This GDB was configured as "i386-pc-linux-gnu"
1725
 
1726
     ^Z^Zpre-prompt
1727
     (gdb)
1728
     ^Z^Zprompt
1729
     quit
1730
 
1731
     ^Z^Zpost-prompt
1732
     $
1733
 
1734
   Here `quit' is input to GDB; the rest is output from GDB.  The three
1735
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
1736
annotations; the rest is output from GDB.
1737
 
1738

1739
File: gdb.info,  Node: Server Prefix,  Next: Prompting,  Prev: Annotations Overview,  Up: Annotations
1740
 
1741
28.2 The Server Prefix
1742
======================
1743
 
1744
If you prefix a command with `server ' then it will not affect the
1745
command history, nor will it affect GDB's notion of which command to
1746
repeat if  is pressed on a line by itself.  This means that
1747
commands can be run behind a user's back by a front-end in a
1748
transparent manner.
1749
 
1750
   The `server ' prefix does not affect the recording of values into
1751
the value history; to print a value without recording it into the value
1752
history, use the `output' command instead of the `print' command.
1753
 
1754
   Using this prefix also disables confirmation requests (*note
1755
confirmation requests::).
1756
 
1757

1758
File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Server Prefix,  Up: Annotations
1759
 
1760
28.3 Annotation for GDB Input
1761
=============================
1762
 
1763
When GDB prompts for input, it annotates this fact so it is possible to
1764
know when to send output, when the output from a given command is over,
1765
etc.
1766
 
1767
   Different kinds of input each have a different "input type".  Each
1768
input type has three annotations: a `pre-' annotation, which denotes
1769
the beginning of any prompt which is being output, a plain annotation,
1770
which denotes the end of the prompt, and then a `post-' annotation
1771
which denotes the end of any echo which may (or may not) be associated
1772
with the input.  For example, the `prompt' input type features the
1773
following annotations:
1774
 
1775
     ^Z^Zpre-prompt
1776
     ^Z^Zprompt
1777
     ^Z^Zpost-prompt
1778
 
1779
   The input types are
1780
 
1781
`prompt'
1782
     When GDB is prompting for a command (the main GDB prompt).
1783
 
1784
`commands'
1785
     When GDB prompts for a set of commands, like in the `commands'
1786
     command.  The annotations are repeated for each command which is
1787
     input.
1788
 
1789
`overload-choice'
1790
     When GDB wants the user to select between various overloaded
1791
     functions.
1792
 
1793
`query'
1794
     When GDB wants the user to confirm a potentially dangerous
1795
     operation.
1796
 
1797
`prompt-for-continue'
1798
     When GDB is asking the user to press return to continue.  Note:
1799
     Don't expect this to work well; instead use `set height 0' to
1800
     disable prompting.  This is because the counting of lines is buggy
1801
     in the presence of annotations.
1802
 
1803

1804
File: gdb.info,  Node: Errors,  Next: Invalidation,  Prev: Prompting,  Up: Annotations
1805
 
1806
28.4 Errors
1807
===========
1808
 
1809
     ^Z^Zquit
1810
 
1811
   This annotation occurs right before GDB responds to an interrupt.
1812
 
1813
     ^Z^Zerror
1814
 
1815
   This annotation occurs right before GDB responds to an error.
1816
 
1817
   Quit and error annotations indicate that any annotations which GDB
1818
was in the middle of may end abruptly.  For example, if a
1819
`value-history-begin' annotation is followed by a `error', one cannot
1820
expect to receive the matching `value-history-end'.  One cannot expect
1821
not to receive it either, however; an error annotation does not
1822
necessarily mean that GDB is immediately returning all the way to the
1823
top level.
1824
 
1825
   A quit or error annotation may be preceded by
1826
 
1827
     ^Z^Zerror-begin
1828
 
1829
   Any output between that and the quit or error annotation is the error
1830
message.
1831
 
1832
   Warning messages are not yet annotated.
1833
 
1834

1835
File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Errors,  Up: Annotations
1836
 
1837
28.5 Invalidation Notices
1838
=========================
1839
 
1840
The following annotations say that certain pieces of state may have
1841
changed.
1842
 
1843
`^Z^Zframes-invalid'
1844
     The frames (for example, output from the `backtrace' command) may
1845
     have changed.
1846
 
1847
`^Z^Zbreakpoints-invalid'
1848
     The breakpoints may have changed.  For example, the user just
1849
     added or deleted a breakpoint.
1850
 
1851

1852
File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations
1853
 
1854
28.6 Running the Program
1855
========================
1856
 
1857
When the program starts executing due to a GDB command such as `step'
1858
or `continue',
1859
 
1860
     ^Z^Zstarting
1861
 
1862
   is output.  When the program stops,
1863
 
1864
     ^Z^Zstopped
1865
 
1866
   is output.  Before the `stopped' annotation, a variety of
1867
annotations describe how the program stopped.
1868
 
1869
`^Z^Zexited EXIT-STATUS'
1870
     The program exited, and EXIT-STATUS is the exit status (zero for
1871
     successful exit, otherwise nonzero).
1872
 
1873
`^Z^Zsignalled'
1874
     The program exited with a signal.  After the `^Z^Zsignalled', the
1875
     annotation continues:
1876
 
1877
          INTRO-TEXT
1878
          ^Z^Zsignal-name
1879
          NAME
1880
          ^Z^Zsignal-name-end
1881
          MIDDLE-TEXT
1882
          ^Z^Zsignal-string
1883
          STRING
1884
          ^Z^Zsignal-string-end
1885
          END-TEXT
1886
 
1887
     where NAME is the name of the signal, such as `SIGILL' or
1888
     `SIGSEGV', and STRING is the explanation of the signal, such as
1889
     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,
1890
     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
1891
     particular format.
1892
 
1893
`^Z^Zsignal'
1894
     The syntax of this annotation is just like `signalled', but GDB is
1895
     just saying that the program received the signal, not that it was
1896
     terminated with it.
1897
 
1898
`^Z^Zbreakpoint NUMBER'
1899
     The program hit breakpoint number NUMBER.
1900
 
1901
`^Z^Zwatchpoint NUMBER'
1902
     The program hit watchpoint number NUMBER.
1903
 
1904

1905
File: gdb.info,  Node: Source Annotations,  Prev: Annotations for Running,  Up: Annotations
1906
 
1907
28.7 Displaying Source
1908
======================
1909
 
1910
The following annotation is used instead of displaying source code:
1911
 
1912
     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
1913
 
1914
   where FILENAME is an absolute file name indicating which source
1915
file, LINE is the line number within that file (where 1 is the first
1916
line in the file), CHARACTER is the character position within the file
1917
(where 0 is the first character in the file) (for most debug formats
1918
this will necessarily point to the beginning of a line), MIDDLE is
1919
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
1920
the beginning of the line, and ADDR is the address in the target
1921
program associated with the source which is being displayed.  ADDR is
1922
in the form `0x' followed by one or more lowercase hex digits (note
1923
that this does not depend on the language).
1924
 
1925

1926
File: gdb.info,  Node: JIT Interface,  Next: GDB Bugs,  Prev: Annotations,  Up: Top
1927
 
1928
29 JIT Compilation Interface
1929
****************************
1930
 
1931
This chapter documents GDB's "just-in-time" (JIT) compilation
1932
interface.  A JIT compiler is a program or library that generates native
1933
executable code at runtime and executes it, usually in order to achieve
1934
good performance while maintaining platform independence.
1935
 
1936
   Programs that use JIT compilation are normally difficult to debug
1937
because portions of their code are generated at runtime, instead of
1938
being loaded from object files, which is where GDB normally finds the
1939
program's symbols and debug information.  In order to debug programs
1940
that use JIT compilation, GDB has an interface that allows the program
1941
to register in-memory symbol files with GDB at runtime.
1942
 
1943
   If you are using GDB to debug a program that uses this interface,
1944
then it should work transparently so long as you have not stripped the
1945
binary.  If you are developing a JIT compiler, then the interface is
1946
documented in the rest of this chapter.  At this time, the only known
1947
client of this interface is the LLVM JIT.
1948
 
1949
   Broadly speaking, the JIT interface mirrors the dynamic loader
1950
interface.  The JIT compiler communicates with GDB by writing data into
1951
a global variable and calling a fuction at a well-known symbol.  When
1952
GDB attaches, it reads a linked list of symbol files from the global
1953
variable to find existing code, and puts a breakpoint in the function
1954
so that it can find out about additional code.
1955
 
1956
* Menu:
1957
 
1958
* Declarations::                Relevant C struct declarations
1959
* Registering Code::            Steps to register code
1960
* Unregistering Code::          Steps to unregister code
1961
 
1962

1963
File: gdb.info,  Node: Declarations,  Next: Registering Code,  Up: JIT Interface
1964
 
1965
29.1 JIT Declarations
1966
=====================
1967
 
1968
These are the relevant struct declarations that a C program should
1969
include to implement the interface:
1970
 
1971
     typedef enum
1972
     {
1973
       JIT_NOACTION = 0,
1974
       JIT_REGISTER_FN,
1975
       JIT_UNREGISTER_FN
1976
     } jit_actions_t;
1977
 
1978
     struct jit_code_entry
1979
     {
1980
       struct jit_code_entry *next_entry;
1981
       struct jit_code_entry *prev_entry;
1982
       const char *symfile_addr;
1983
       uint64_t symfile_size;
1984
     };
1985
 
1986
     struct jit_descriptor
1987
     {
1988
       uint32_t version;
1989
       /* This type should be jit_actions_t, but we use uint32_t
1990
          to be explicit about the bitwidth.  */
1991
       uint32_t action_flag;
1992
       struct jit_code_entry *relevant_entry;
1993
       struct jit_code_entry *first_entry;
1994
     };
1995
 
1996
     /* GDB puts a breakpoint in this function.  */
1997
     void __attribute__((noinline)) __jit_debug_register_code() { };
1998
 
1999
     /* Make sure to specify the version statically, because the
2000
        debugger may check the version before we can set it.  */
2001
     struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
2002
 
2003
   If the JIT is multi-threaded, then it is important that the JIT
2004
synchronize any modifications to this global data properly, which can
2005
easily be done by putting a global mutex around modifications to these
2006
structures.
2007
 
2008

2009
File: gdb.info,  Node: Registering Code,  Next: Unregistering Code,  Prev: Declarations,  Up: JIT Interface
2010
 
2011
29.2 Registering Code
2012
=====================
2013
 
2014
To register code with GDB, the JIT should follow this protocol:
2015
 
2016
   * Generate an object file in memory with symbols and other desired
2017
     debug information.  The file must include the virtual addresses of
2018
     the sections.
2019
 
2020
   * Create a code entry for the file, which gives the start and size
2021
     of the symbol file.
2022
 
2023
   * Add it to the linked list in the JIT descriptor.
2024
 
2025
   * Point the relevant_entry field of the descriptor at the entry.
2026
 
2027
   * Set `action_flag' to `JIT_REGISTER' and call
2028
     `__jit_debug_register_code'.
2029
 
2030
   When GDB is attached and the breakpoint fires, GDB uses the
2031
`relevant_entry' pointer so it doesn't have to walk the list looking for
2032
new code.  However, the linked list must still be maintained in order
2033
to allow GDB to attach to a running process and still find the symbol
2034
files.
2035
 
2036

2037
File: gdb.info,  Node: Unregistering Code,  Prev: Registering Code,  Up: JIT Interface
2038
 
2039
29.3 Unregistering Code
2040
=======================
2041
 
2042
If code is freed, then the JIT should use the following protocol:
2043
 
2044
   * Remove the code entry corresponding to the code from the linked
2045
     list.
2046
 
2047
   * Point the `relevant_entry' field of the descriptor at the code
2048
     entry.
2049
 
2050
   * Set `action_flag' to `JIT_UNREGISTER' and call
2051
     `__jit_debug_register_code'.
2052
 
2053
   If the JIT frees or recompiles code without unregistering it, then
2054
GDB and the JIT will leak the memory used for the associated symbol
2055
files.
2056
 
2057

2058
File: gdb.info,  Node: GDB Bugs,  Next: Command Line Editing,  Prev: JIT Interface,  Up: Top
2059
 
2060
30 Reporting Bugs in GDB
2061
************************
2062
 
2063
Your bug reports play an essential role in making GDB reliable.
2064
 
2065
   Reporting a bug may help you by bringing a solution to your problem,
2066
or it may not.  But in any case the principal function of a bug report
2067
is to help the entire community by making the next version of GDB work
2068
better.  Bug reports are your contribution to the maintenance of GDB.
2069
 
2070
   In order for a bug report to serve its purpose, you must include the
2071
information that enables us to fix the bug.
2072
 
2073
* Menu:
2074
 
2075
* Bug Criteria::                Have you found a bug?
2076
* Bug Reporting::               How to report bugs
2077
 
2078

2079
File: gdb.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: GDB Bugs
2080
 
2081
30.1 Have You Found a Bug?
2082
==========================
2083
 
2084
If you are not sure whether you have found a bug, here are some
2085
guidelines:
2086
 
2087
   * If the debugger gets a fatal signal, for any input whatever, that
2088
     is a GDB bug.  Reliable debuggers never crash.
2089
 
2090
   * If GDB produces an error message for valid input, that is a bug.
2091
     (Note that if you're cross debugging, the problem may also be
2092
     somewhere in the connection to the target.)
2093
 
2094
   * If GDB does not produce an error message for invalid input, that
2095
     is a bug.  However, you should note that your idea of "invalid
2096
     input" might be our idea of "an extension" or "support for
2097
     traditional practice".
2098
 
2099
   * If you are an experienced user of debugging tools, your suggestions
2100
     for improvement of GDB are welcome in any case.
2101
 
2102

2103
File: gdb.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: GDB Bugs
2104
 
2105
30.2 How to Report Bugs
2106
=======================
2107
 
2108
A number of companies and individuals offer support for GNU products.
2109
If you obtained GDB from a support organization, we recommend you
2110
contact that organization first.
2111
 
2112
   You can find contact information for many support companies and
2113
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
2114
 
2115
   In any event, we also recommend that you submit bug reports for GDB.
2116
The preferred method is to submit them directly using GDB's Bugs web
2117
page (http://www.gnu.org/software/gdb/bugs/).  Alternatively, the
2118
e-mail gateway  can be used.
2119
 
2120
   *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
2121
newsgroups.*  Most users of GDB do not want to receive bug reports.
2122
Those that do have arranged to receive `bug-gdb'.
2123
 
2124
   The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
2125
serves as a repeater.  The mailing list and the newsgroup carry exactly
2126
the same messages.  Often people think of posting bug reports to the
2127
newsgroup instead of mailing them.  This appears to work, but it has one
2128
problem which can be crucial: a newsgroup posting often lacks a mail
2129
path back to the sender.  Thus, if we need to ask for more information,
2130
we may be unable to reach you.  For this reason, it is better to send
2131
bug reports to the mailing list.
2132
 
2133
   The fundamental principle of reporting bugs usefully is this:
2134
*report all the facts*.  If you are not sure whether to state a fact or
2135
leave it out, state it!
2136
 
2137
   Often people omit facts because they think they know what causes the
2138
problem and assume that some details do not matter.  Thus, you might
2139
assume that the name of the variable you use in an example does not
2140
matter.  Well, probably it does not, but one cannot be sure.  Perhaps
2141
the bug is a stray memory reference which happens to fetch from the
2142
location where that name is stored in memory; perhaps, if the name were
2143
different, the contents of that location would fool the debugger into
2144
doing the right thing despite the bug.  Play it safe and give a
2145
specific, complete example.  That is the easiest thing for you to do,
2146
and the most helpful.
2147
 
2148
   Keep in mind that the purpose of a bug report is to enable us to fix
2149
the bug.  It may be that the bug has been reported previously, but
2150
neither you nor we can know that unless your bug report is complete and
2151
self-contained.
2152
 
2153
   Sometimes people give a few sketchy facts and ask, "Does this ring a
2154
bell?"  Those bug reports are useless, and we urge everyone to _refuse
2155
to respond to them_ except to chide the sender to report bugs properly.
2156
 
2157
   To enable us to fix the bug, you should include all these things:
2158
 
2159
   * The version of GDB.  GDB announces it if you start with no
2160
     arguments; you can also print it at any time using `show version'.
2161
 
2162
     Without this, we will not know whether there is any point in
2163
     looking for the bug in the current version of GDB.
2164
 
2165
   * The type of machine you are using, and the operating system name
2166
     and version number.
2167
 
2168
   * What compiler (and its version) was used to compile GDB--e.g.
2169
     "gcc-2.8.1".
2170
 
2171
   * What compiler (and its version) was used to compile the program
2172
     you are debugging--e.g.  "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
2173
     C Compiler".  For GCC, you can say `gcc --version' to get this
2174
     information; for other compilers, see the documentation for those
2175
     compilers.
2176
 
2177
   * The command arguments you gave the compiler to compile your
2178
     example and observe the bug.  For example, did you use `-O'?  To
2179
     guarantee you will not omit something important, list them all.  A
2180
     copy of the Makefile (or the output from make) is sufficient.
2181
 
2182
     If we were to try to guess the arguments, we would probably guess
2183
     wrong and then we might not encounter the bug.
2184
 
2185
   * A complete input script, and all necessary source files, that will
2186
     reproduce the bug.
2187
 
2188
   * A description of what behavior you observe that you believe is
2189
     incorrect.  For example, "It gets a fatal signal."
2190
 
2191
     Of course, if the bug is that GDB gets a fatal signal, then we
2192
     will certainly notice it.  But if the bug is incorrect output, we
2193
     might not notice unless it is glaringly wrong.  You might as well
2194
     not give us a chance to make a mistake.
2195
 
2196
     Even if the problem you experience is a fatal signal, you should
2197
     still say so explicitly.  Suppose something strange is going on,
2198
     such as, your copy of GDB is out of synch, or you have encountered
2199
     a bug in the C library on your system.  (This has happened!)  Your
2200
     copy might crash and ours would not.  If you told us to expect a
2201
     crash, then when ours fails to crash, we would know that the bug
2202
     was not happening for us.  If you had not told us to expect a
2203
     crash, then we would not be able to draw any conclusion from our
2204
     observations.
2205
 
2206
     To collect all this information, you can use a session recording
2207
     program such as `script', which is available on many Unix systems.
2208
     Just run your GDB session inside `script' and then include the
2209
     `typescript' file with your bug report.
2210
 
2211
     Another way to record a GDB session is to run GDB inside Emacs and
2212
     then save the entire buffer to a file.
2213
 
2214
   * If you wish to suggest changes to the GDB source, send us context
2215
     diffs.  If you even discuss something in the GDB source, refer to
2216
     it by context, not by line number.
2217
 
2218
     The line numbers in our development sources will not match those
2219
     in your sources.  Your line numbers would convey no useful
2220
     information to us.
2221
 
2222
 
2223
   Here are some things that are not necessary:
2224
 
2225
   * A description of the envelope of the bug.
2226
 
2227
     Often people who encounter a bug spend a lot of time investigating
2228
     which changes to the input file will make the bug go away and which
2229
     changes will not affect it.
2230
 
2231
     This is often time consuming and not very useful, because the way
2232
     we will find the bug is by running a single example under the
2233
     debugger with breakpoints, not by pure deduction from a series of
2234
     examples.  We recommend that you save your time for something else.
2235
 
2236
     Of course, if you can find a simpler example to report _instead_
2237
     of the original one, that is a convenience for us.  Errors in the
2238
     output will be easier to spot, running under the debugger will take
2239
     less time, and so on.
2240
 
2241
     However, simplification is not vital; if you do not want to do
2242
     this, report the bug anyway and send us the entire test case you
2243
     used.
2244
 
2245
   * A patch for the bug.
2246
 
2247
     A patch for the bug does help us if it is a good one.  But do not
2248
     omit the necessary information, such as the test case, on the
2249
     assumption that a patch is all we need.  We might see problems
2250
     with your patch and decide to fix the problem another way, or we
2251
     might not understand it at all.
2252
 
2253
     Sometimes with a program as complicated as GDB it is very hard to
2254
     construct an example that will make the program follow a certain
2255
     path through the code.  If you do not send us the example, we will
2256
     not be able to construct one, so we will not be able to verify
2257
     that the bug is fixed.
2258
 
2259
     And if we cannot understand what bug you are trying to fix, or why
2260
     your patch should be an improvement, we will not install it.  A
2261
     test case will help us to understand.
2262
 
2263
   * A guess about what the bug is or what it depends on.
2264
 
2265
     Such guesses are usually wrong.  Even we cannot guess right about
2266
     such things without first using the debugger to find the facts.
2267
 
2268

2269
File: gdb.info,  Node: Command Line Editing,  Next: Using History Interactively,  Prev: GDB Bugs,  Up: Top
2270
 
2271
31 Command Line Editing
2272
***********************
2273
 
2274
This chapter describes the basic features of the GNU command line
2275
editing interface.
2276
 
2277
* Menu:
2278
 
2279
* Introduction and Notation::   Notation used in this text.
2280
* Readline Interaction::        The minimum set of commands for editing a line.
2281
* Readline Init File::          Customizing Readline from a user's view.
2282
* Bindable Readline Commands::  A description of most of the Readline commands
2283
                                available for binding
2284
* Readline vi Mode::            A short description of how to make Readline
2285
                                behave like the vi editor.
2286
 
2287

2288
File: gdb.info,  Node: Introduction and Notation,  Next: Readline Interaction,  Up: Command Line Editing
2289
 
2290
31.1 Introduction to Line Editing
2291
=================================
2292
 
2293
The following paragraphs describe the notation used to represent
2294
keystrokes.
2295
 
2296
   The text `C-k' is read as `Control-K' and describes the character
2297
produced when the  key is pressed while the Control key is depressed.
2298
 
2299
   The text `M-k' is read as `Meta-K' and describes the character
2300
produced when the Meta key (if you have one) is depressed, and the 
2301
key is pressed.  The Meta key is labeled  on many keyboards.  On
2302
keyboards with two keys labeled  (usually to either side of the
2303
space bar), the  on the left side is generally set to work as a
2304
Meta key.  The  key on the right may also be configured to work as
2305
a Meta key or may be configured as some other modifier, such as a
2306
Compose key for typing accented characters.
2307
 
2308
   If you do not have a Meta or  key, or another key working as a
2309
Meta key, the identical keystroke can be generated by typing 
2310
_first_, and then typing .  Either process is known as "metafying"
2311
the  key.
2312
 
2313
   The text `M-C-k' is read as `Meta-Control-k' and describes the
2314
character produced by "metafying" `C-k'.
2315
 
2316
   In addition, several keys have their own names.  Specifically,
2317
, , , , , and  all stand for themselves
2318
when seen in this text, or in an init file (*note Readline Init File::).
2319
If your keyboard lacks a  key, typing  will produce the
2320
desired character.  The  key may be labeled  or  on
2321
some keyboards.
2322
 
2323

2324
File: gdb.info,  Node: Readline Interaction,  Next: Readline Init File,  Prev: Introduction and Notation,  Up: Command Line Editing
2325
 
2326
31.2 Readline Interaction
2327
=========================
2328
 
2329
Often during an interactive session you type in a long line of text,
2330
only to notice that the first word on the line is misspelled.  The
2331
Readline library gives you a set of commands for manipulating the text
2332
as you type it in, allowing you to just fix your typo, and not forcing
2333
you to retype the majority of the line.  Using these editing commands,
2334
you move the cursor to the place that needs correction, and delete or
2335
insert the text of the corrections.  Then, when you are satisfied with
2336
the line, you simply press .  You do not have to be at the end of
2337
the line to press ; the entire line is accepted regardless of the
2338
location of the cursor within the line.
2339
 
2340
* Menu:
2341
 
2342
* Readline Bare Essentials::    The least you need to know about Readline.
2343
* Readline Movement Commands::  Moving about the input line.
2344
* Readline Killing Commands::   How to delete text, and how to get it back!
2345
* Readline Arguments::          Giving numeric arguments to commands.
2346
* Searching::                   Searching through previous lines.
2347
 
2348

2349
File: gdb.info,  Node: Readline Bare Essentials,  Next: Readline Movement Commands,  Up: Readline Interaction
2350
 
2351
31.2.1 Readline Bare Essentials
2352
-------------------------------
2353
 
2354
In order to enter characters into the line, simply type them.  The typed
2355
character appears where the cursor was, and then the cursor moves one
2356
space to the right.  If you mistype a character, you can use your erase
2357
character to back up and delete the mistyped character.
2358
 
2359
   Sometimes you may mistype a character, and not notice the error
2360
until you have typed several other characters.  In that case, you can
2361
type `C-b' to move the cursor to the left, and then correct your
2362
mistake.  Afterwards, you can move the cursor to the right with `C-f'.
2363
 
2364
   When you add text in the middle of a line, you will notice that
2365
characters to the right of the cursor are `pushed over' to make room
2366
for the text that you have inserted.  Likewise, when you delete text
2367
behind the cursor, characters to the right of the cursor are `pulled
2368
back' to fill in the blank space created by the removal of the text.  A
2369
list of the bare essentials for editing the text of an input line
2370
follows.
2371
 
2372
`C-b'
2373
     Move back one character.
2374
 
2375
`C-f'
2376
     Move forward one character.
2377
 
2378
 or 
2379
     Delete the character to the left of the cursor.
2380
 
2381
`C-d'
2382
     Delete the character underneath the cursor.
2383
 
2384
Printing characters
2385
     Insert the character into the line at the cursor.
2386
 
2387
`C-_' or `C-x C-u'
2388
     Undo the last editing command.  You can undo all the way back to an
2389
     empty line.
2390
 
2391
(Depending on your configuration, the  key be set to delete
2392
the character to the left of the cursor and the  key set to delete
2393
the character underneath the cursor, like `C-d', rather than the
2394
character to the left of the cursor.)
2395
 
2396

2397
File: gdb.info,  Node: Readline Movement Commands,  Next: Readline Killing Commands,  Prev: Readline Bare Essentials,  Up: Readline Interaction
2398
 
2399
31.2.2 Readline Movement Commands
2400
---------------------------------
2401
 
2402
The above table describes the most basic keystrokes that you need in
2403
order to do editing of the input line.  For your convenience, many
2404
other commands have been added in addition to `C-b', `C-f', `C-d', and
2405
.  Here are some commands for moving more rapidly about the line.
2406
 
2407
`C-a'
2408
     Move to the start of the line.
2409
 
2410
`C-e'
2411
     Move to the end of the line.
2412
 
2413
`M-f'
2414
     Move forward a word, where a word is composed of letters and
2415
     digits.
2416
 
2417
`M-b'
2418
     Move backward a word.
2419
 
2420
`C-l'
2421
     Clear the screen, reprinting the current line at the top.
2422
 
2423
   Notice how `C-f' moves forward a character, while `M-f' moves
2424
forward a word.  It is a loose convention that control keystrokes
2425
operate on characters while meta keystrokes operate on words.
2426
 
2427

2428
File: gdb.info,  Node: Readline Killing Commands,  Next: Readline Arguments,  Prev: Readline Movement Commands,  Up: Readline Interaction
2429
 
2430
31.2.3 Readline Killing Commands
2431
--------------------------------
2432
 
2433
"Killing" text means to delete the text from the line, but to save it
2434
away for later use, usually by "yanking" (re-inserting) it back into
2435
the line.  (`Cut' and `paste' are more recent jargon for `kill' and
2436
`yank'.)
2437
 
2438
   If the description for a command says that it `kills' text, then you
2439
can be sure that you can get the text back in a different (or the same)
2440
place later.
2441
 
2442
   When you use a kill command, the text is saved in a "kill-ring".
2443
Any number of consecutive kills save all of the killed text together, so
2444
that when you yank it back, you get it all.  The kill ring is not line
2445
specific; the text that you killed on a previously typed line is
2446
available to be yanked back later, when you are typing another line.
2447
 
2448
   Here is the list of commands for killing text.
2449
 
2450
`C-k'
2451
     Kill the text from the current cursor position to the end of the
2452
     line.
2453
 
2454
`M-d'
2455
     Kill from the cursor to the end of the current word, or, if between
2456
     words, to the end of the next word.  Word boundaries are the same
2457
     as those used by `M-f'.
2458
 
2459
`M-'
2460
     Kill from the cursor the start of the current word, or, if between
2461
     words, to the start of the previous word.  Word boundaries are the
2462
     same as those used by `M-b'.
2463
 
2464
`C-w'
2465
     Kill from the cursor to the previous whitespace.  This is
2466
     different than `M-' because the word boundaries differ.
2467
 
2468
 
2469
   Here is how to "yank" the text back into the line.  Yanking means to
2470
copy the most-recently-killed text from the kill buffer.
2471
 
2472
`C-y'
2473
     Yank the most recently killed text back into the buffer at the
2474
     cursor.
2475
 
2476
`M-y'
2477
     Rotate the kill-ring, and yank the new top.  You can only do this
2478
     if the prior command is `C-y' or `M-y'.
2479
 
2480

2481
File: gdb.info,  Node: Readline Arguments,  Next: Searching,  Prev: Readline Killing Commands,  Up: Readline Interaction
2482
 
2483
31.2.4 Readline Arguments
2484
-------------------------
2485
 
2486
You can pass numeric arguments to Readline commands.  Sometimes the
2487
argument acts as a repeat count, other times it is the sign of the
2488
argument that is significant.  If you pass a negative argument to a
2489
command which normally acts in a forward direction, that command will
2490
act in a backward direction.  For example, to kill text back to the
2491
start of the line, you might type `M-- C-k'.
2492
 
2493
   The general way to pass numeric arguments to a command is to type
2494
meta digits before the command.  If the first `digit' typed is a minus
2495
sign (`-'), then the sign of the argument will be negative.  Once you
2496
have typed one meta digit to get the argument started, you can type the
2497
remainder of the digits, and then the command.  For example, to give
2498
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
2499
will delete the next ten characters on the input line.
2500
 
2501

2502
File: gdb.info,  Node: Searching,  Prev: Readline Arguments,  Up: Readline Interaction
2503
 
2504
31.2.5 Searching for Commands in the History
2505
--------------------------------------------
2506
 
2507
Readline provides commands for searching through the command history
2508
for lines containing a specified string.  There are two search modes:
2509
"incremental" and "non-incremental".
2510
 
2511
   Incremental searches begin before the user has finished typing the
2512
search string.  As each character of the search string is typed,
2513
Readline displays the next entry from the history matching the string
2514
typed so far.  An incremental search requires only as many characters
2515
as needed to find the desired history entry.  To search backward in the
2516
history for a particular string, type `C-r'.  Typing `C-s' searches
2517
forward through the history.  The characters present in the value of
2518
the `isearch-terminators' variable are used to terminate an incremental
2519
search.  If that variable has not been assigned a value, the  and
2520
`C-J' characters will terminate an incremental search.  `C-g' will
2521
abort an incremental search and restore the original line.  When the
2522
search is terminated, the history entry containing the search string
2523
becomes the current line.
2524
 
2525
   To find other matching entries in the history list, type `C-r' or
2526
`C-s' as appropriate.  This will search backward or forward in the
2527
history for the next entry matching the search string typed so far.
2528
Any other key sequence bound to a Readline command will terminate the
2529
search and execute that command.  For instance, a  will terminate
2530
the search and accept the line, thereby executing the command from the
2531
history list.  A movement command will terminate the search, make the
2532
last line found the current line, and begin editing.
2533
 
2534
   Readline remembers the last incremental search string.  If two
2535
`C-r's are typed without any intervening characters defining a new
2536
search string, any remembered search string is used.
2537
 
2538
   Non-incremental searches read the entire search string before
2539
starting to search for matching history lines.  The search string may be
2540
typed by the user or be part of the contents of the current line.
2541
 
2542

2543
File: gdb.info,  Node: Readline Init File,  Next: Bindable Readline Commands,  Prev: Readline Interaction,  Up: Command Line Editing
2544
 
2545
31.3 Readline Init File
2546
=======================
2547
 
2548
Although the Readline library comes with a set of Emacs-like
2549
keybindings installed by default, it is possible to use a different set
2550
of keybindings.  Any user can customize programs that use Readline by
2551
putting commands in an "inputrc" file, conventionally in his home
2552
directory.  The name of this file is taken from the value of the
2553
environment variable `INPUTRC'.  If that variable is unset, the default
2554
is `~/.inputrc'.
2555
 
2556
   When a program which uses the Readline library starts up, the init
2557
file is read, and the key bindings are set.
2558
 
2559
   In addition, the `C-x C-r' command re-reads this init file, thus
2560
incorporating any changes that you might have made to it.
2561
 
2562
* Menu:
2563
 
2564
* Readline Init File Syntax::   Syntax for the commands in the inputrc file.
2565
 
2566
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
2567
 
2568
* Sample Init File::            An example inputrc file.
2569
 
2570

2571
File: gdb.info,  Node: Readline Init File Syntax,  Next: Conditional Init Constructs,  Up: Readline Init File
2572
 
2573
31.3.1 Readline Init File Syntax
2574
--------------------------------
2575
 
2576
There are only a few basic constructs allowed in the Readline init
2577
file.  Blank lines are ignored.  Lines beginning with a `#' are
2578
comments.  Lines beginning with a `$' indicate conditional constructs
2579
(*note Conditional Init Constructs::).  Other lines denote variable
2580
settings and key bindings.
2581
 
2582
Variable Settings
2583
     You can modify the run-time behavior of Readline by altering the
2584
     values of variables in Readline using the `set' command within the
2585
     init file.  The syntax is simple:
2586
 
2587
          set VARIABLE VALUE
2588
 
2589
     Here, for example, is how to change from the default Emacs-like
2590
     key binding to use `vi' line editing commands:
2591
 
2592
          set editing-mode vi
2593
 
2594
     Variable names and values, where appropriate, are recognized
2595
     without regard to case.  Unrecognized variable names are ignored.
2596
 
2597
     Boolean variables (those that can be set to on or off) are set to
2598
     on if the value is null or empty, ON (case-insensitive), or 1.
2599
     Any other value results in the variable being set to off.
2600
 
2601
     A great deal of run-time behavior is changeable with the following
2602
     variables.
2603
 
2604
    `bell-style'
2605
          Controls what happens when Readline wants to ring the
2606
          terminal bell.  If set to `none', Readline never rings the
2607
          bell.  If set to `visible', Readline uses a visible bell if
2608
          one is available.  If set to `audible' (the default),
2609
          Readline attempts to ring the terminal's bell.
2610
 
2611
    `bind-tty-special-chars'
2612
          If set to `on', Readline attempts to bind the control
2613
          characters treated specially by the kernel's terminal driver
2614
          to their Readline equivalents.
2615
 
2616
    `comment-begin'
2617
          The string to insert at the beginning of the line when the
2618
          `insert-comment' command is executed.  The default value is
2619
          `"#"'.
2620
 
2621
    `completion-ignore-case'
2622
          If set to `on', Readline performs filename matching and
2623
          completion in a case-insensitive fashion.  The default value
2624
          is `off'.
2625
 
2626
    `completion-query-items'
2627
          The number of possible completions that determines when the
2628
          user is asked whether the list of possibilities should be
2629
          displayed.  If the number of possible completions is greater
2630
          than this value, Readline will ask the user whether or not he
2631
          wishes to view them; otherwise, they are simply listed.  This
2632
          variable must be set to an integer value greater than or
2633
          equal to 0.  A negative value means Readline should never ask.
2634
          The default limit is `100'.
2635
 
2636
    `convert-meta'
2637
          If set to `on', Readline will convert characters with the
2638
          eighth bit set to an ASCII key sequence by stripping the
2639
          eighth bit and prefixing an  character, converting them
2640
          to a meta-prefixed key sequence.  The default value is `on'.
2641
 
2642
    `disable-completion'
2643
          If set to `On', Readline will inhibit word completion.
2644
          Completion  characters will be inserted into the line as if
2645
          they had been mapped to `self-insert'.  The default is `off'.
2646
 
2647
    `editing-mode'
2648
          The `editing-mode' variable controls which default set of key
2649
          bindings is used.  By default, Readline starts up in Emacs
2650
          editing mode, where the keystrokes are most similar to Emacs.
2651
          This variable can be set to either `emacs' or `vi'.
2652
 
2653
    `enable-keypad'
2654
          When set to `on', Readline will try to enable the application
2655
          keypad when it is called.  Some systems need this to enable
2656
          the arrow keys.  The default is `off'.
2657
 
2658
    `expand-tilde'
2659
          If set to `on', tilde expansion is performed when Readline
2660
          attempts word completion.  The default is `off'.
2661
 
2662
    `history-preserve-point'
2663
          If set to `on', the history code attempts to place point at
2664
          the same location on each history line retrieved with
2665
          `previous-history' or `next-history'.  The default is `off'.
2666
 
2667
    `horizontal-scroll-mode'
2668
          This variable can be set to either `on' or `off'.  Setting it
2669
          to `on' means that the text of the lines being edited will
2670
          scroll horizontally on a single screen line when they are
2671
          longer than the width of the screen, instead of wrapping onto
2672
          a new screen line.  By default, this variable is set to `off'.
2673
 
2674
    `input-meta'
2675
          If set to `on', Readline will enable eight-bit input (it will
2676
          not clear the eighth bit in the characters it reads),
2677
          regardless of what the terminal claims it can support.  The
2678
          default value is `off'.  The name `meta-flag' is a synonym
2679
          for this variable.
2680
 
2681
    `isearch-terminators'
2682
          The string of characters that should terminate an incremental
2683
          search without subsequently executing the character as a
2684
          command (*note Searching::).  If this variable has not been
2685
          given a value, the characters  and `C-J' will terminate
2686
          an incremental search.
2687
 
2688
    `keymap'
2689
          Sets Readline's idea of the current keymap for key binding
2690
          commands.  Acceptable `keymap' names are `emacs',
2691
          `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
2692
          `vi-command', and `vi-insert'.  `vi' is equivalent to
2693
          `vi-command'; `emacs' is equivalent to `emacs-standard'.  The
2694
          default value is `emacs'.  The value of the `editing-mode'
2695
          variable also affects the default keymap.
2696
 
2697
    `mark-directories'
2698
          If set to `on', completed directory names have a slash
2699
          appended.  The default is `on'.
2700
 
2701
    `mark-modified-lines'
2702
          This variable, when set to `on', causes Readline to display an
2703
          asterisk (`*') at the start of history lines which have been
2704
          modified.  This variable is `off' by default.
2705
 
2706
    `mark-symlinked-directories'
2707
          If set to `on', completed names which are symbolic links to
2708
          directories have a slash appended (subject to the value of
2709
          `mark-directories').  The default is `off'.
2710
 
2711
    `match-hidden-files'
2712
          This variable, when set to `on', causes Readline to match
2713
          files whose names begin with a `.' (hidden files) when
2714
          performing filename completion, unless the leading `.' is
2715
          supplied by the user in the filename to be completed.  This
2716
          variable is `on' by default.
2717
 
2718
    `output-meta'
2719
          If set to `on', Readline will display characters with the
2720
          eighth bit set directly rather than as a meta-prefixed escape
2721
          sequence.  The default is `off'.
2722
 
2723
    `page-completions'
2724
          If set to `on', Readline uses an internal `more'-like pager
2725
          to display a screenful of possible completions at a time.
2726
          This variable is `on' by default.
2727
 
2728
    `print-completions-horizontally'
2729
          If set to `on', Readline will display completions with matches
2730
          sorted horizontally in alphabetical order, rather than down
2731
          the screen.  The default is `off'.
2732
 
2733
    `show-all-if-ambiguous'
2734
          This alters the default behavior of the completion functions.
2735
          If set to `on', words which have more than one possible
2736
          completion cause the matches to be listed immediately instead
2737
          of ringing the bell.  The default value is `off'.
2738
 
2739
    `show-all-if-unmodified'
2740
          This alters the default behavior of the completion functions
2741
          in a fashion similar to SHOW-ALL-IF-AMBIGUOUS.  If set to
2742
          `on', words which have more than one possible completion
2743
          without any possible partial completion (the possible
2744
          completions don't share a common prefix) cause the matches to
2745
          be listed immediately instead of ringing the bell.  The
2746
          default value is `off'.
2747
 
2748
    `visible-stats'
2749
          If set to `on', a character denoting a file's type is
2750
          appended to the filename when listing possible completions.
2751
          The default is `off'.
2752
 
2753
 
2754
Key Bindings
2755
     The syntax for controlling key bindings in the init file is
2756
     simple.  First you need to find the name of the command that you
2757
     want to change.  The following sections contain tables of the
2758
     command name, the default keybinding, if any, and a short
2759
     description of what the command does.
2760
 
2761
     Once you know the name of the command, simply place on a line in
2762
     the init file the name of the key you wish to bind the command to,
2763
     a colon, and then the name of the command.  The name of the key
2764
     can be expressed in different ways, depending on what you find most
2765
     comfortable.
2766
 
2767
     In addition to command names, readline allows keys to be bound to
2768
     a string that is inserted when the key is pressed (a MACRO).
2769
 
2770
    KEYNAME: FUNCTION-NAME or MACRO
2771
          KEYNAME is the name of a key spelled out in English.  For
2772
          example:
2773
               Control-u: universal-argument
2774
               Meta-Rubout: backward-kill-word
2775
               Control-o: "> output"
2776
 
2777
          In the above example, `C-u' is bound to the function
2778
          `universal-argument', `M-DEL' is bound to the function
2779
          `backward-kill-word', and `C-o' is bound to run the macro
2780
          expressed on the right hand side (that is, to insert the text
2781
          `> output' into the line).
2782
 
2783
          A number of symbolic character names are recognized while
2784
          processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
2785
          NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
2786
 
2787
    "KEYSEQ": FUNCTION-NAME or MACRO
2788
          KEYSEQ differs from KEYNAME above in that strings denoting an
2789
          entire key sequence can be specified, by placing the key
2790
          sequence in double quotes.  Some GNU Emacs style key escapes
2791
          can be used, as in the following example, but the special
2792
          character names are not recognized.
2793
 
2794
               "\C-u": universal-argument
2795
               "\C-x\C-r": re-read-init-file
2796
               "\e[11~": "Function Key 1"
2797
 
2798
          In the above example, `C-u' is again bound to the function
2799
          `universal-argument' (just as it was in the first example),
2800
          `C-x C-r' is bound to the function `re-read-init-file', and
2801
          ` <[> <1> <1> <~>' is bound to insert the text `Function
2802
          Key 1'.
2803
 
2804
 
2805
     The following GNU Emacs style escape sequences are available when
2806
     specifying key sequences:
2807
 
2808
    `\C-'
2809
          control prefix
2810
 
2811
    `\M-'
2812
          meta prefix
2813
 
2814
    `\e'
2815
          an escape character
2816
 
2817
    `\\'
2818
          backslash
2819
 
2820
    `\"'
2821
          <">, a double quotation mark
2822
 
2823
    `\''
2824
          <'>, a single quote or apostrophe
2825
 
2826
     In addition to the GNU Emacs style escape sequences, a second set
2827
     of backslash escapes is available:
2828
 
2829
    `\a'
2830
          alert (bell)
2831
 
2832
    `\b'
2833
          backspace
2834
 
2835
    `\d'
2836
          delete
2837
 
2838
    `\f'
2839
          form feed
2840
 
2841
    `\n'
2842
          newline
2843
 
2844
    `\r'
2845
          carriage return
2846
 
2847
    `\t'
2848
          horizontal tab
2849
 
2850
    `\v'
2851
          vertical tab
2852
 
2853
    `\NNN'
2854
          the eight-bit character whose value is the octal value NNN
2855
          (one to three digits)
2856
 
2857
    `\xHH'
2858
          the eight-bit character whose value is the hexadecimal value
2859
          HH (one or two hex digits)
2860
 
2861
     When entering the text of a macro, single or double quotes must be
2862
     used to indicate a macro definition.  Unquoted text is assumed to
2863
     be a function name.  In the macro body, the backslash escapes
2864
     described above are expanded.  Backslash will quote any other
2865
     character in the macro text, including `"' and `''.  For example,
2866
     the following binding will make `C-x \' insert a single `\' into
2867
     the line:
2868
          "\C-x\\": "\\"
2869
 
2870
 
2871

2872
File: gdb.info,  Node: Conditional Init Constructs,  Next: Sample Init File,  Prev: Readline Init File Syntax,  Up: Readline Init File
2873
 
2874
31.3.2 Conditional Init Constructs
2875
----------------------------------
2876
 
2877
Readline implements a facility similar in spirit to the conditional
2878
compilation features of the C preprocessor which allows key bindings
2879
and variable settings to be performed as the result of tests.  There
2880
are four parser directives used.
2881
 
2882
`$if'
2883
     The `$if' construct allows bindings to be made based on the
2884
     editing mode, the terminal being used, or the application using
2885
     Readline.  The text of the test extends to the end of the line; no
2886
     characters are required to isolate it.
2887
 
2888
    `mode'
2889
          The `mode=' form of the `$if' directive is used to test
2890
          whether Readline is in `emacs' or `vi' mode.  This may be
2891
          used in conjunction with the `set keymap' command, for
2892
          instance, to set bindings in the `emacs-standard' and
2893
          `emacs-ctlx' keymaps only if Readline is starting out in
2894
          `emacs' mode.
2895
 
2896
    `term'
2897
          The `term=' form may be used to include terminal-specific key
2898
          bindings, perhaps to bind the key sequences output by the
2899
          terminal's function keys.  The word on the right side of the
2900
          `=' is tested against both the full name of the terminal and
2901
          the portion of the terminal name before the first `-'.  This
2902
          allows `sun' to match both `sun' and `sun-cmd', for instance.
2903
 
2904
    `application'
2905
          The APPLICATION construct is used to include
2906
          application-specific settings.  Each program using the
2907
          Readline library sets the APPLICATION NAME, and you can test
2908
          for a particular value.  This could be used to bind key
2909
          sequences to functions useful for a specific program.  For
2910
          instance, the following command adds a key sequence that
2911
          quotes the current or previous word in Bash:
2912
               $if Bash
2913
               # Quote the current or previous word
2914
               "\C-xq": "\eb\"\ef\""
2915
               $endif
2916
 
2917
`$endif'
2918
     This command, as seen in the previous example, terminates an `$if'
2919
     command.
2920
 
2921
`$else'
2922
     Commands in this branch of the `$if' directive are executed if the
2923
     test fails.
2924
 
2925
`$include'
2926
     This directive takes a single filename as an argument and reads
2927
     commands and bindings from that file.  For example, the following
2928
     directive reads from `/etc/inputrc':
2929
          $include /etc/inputrc
2930
 
2931

2932
File: gdb.info,  Node: Sample Init File,  Prev: Conditional Init Constructs,  Up: Readline Init File
2933
 
2934
31.3.3 Sample Init File
2935
-----------------------
2936
 
2937
Here is an example of an INPUTRC file.  This illustrates key binding,
2938
variable assignment, and conditional syntax.
2939
 
2940
 
2941
     # This file controls the behaviour of line input editing for
2942
     # programs that use the GNU Readline library.  Existing
2943
     # programs include FTP, Bash, and GDB.
2944
     #
2945
     # You can re-read the inputrc file with C-x C-r.
2946
     # Lines beginning with '#' are comments.
2947
     #
2948
     # First, include any systemwide bindings and variable
2949
     # assignments from /etc/Inputrc
2950
     $include /etc/Inputrc
2951
 
2952
     #
2953
     # Set various bindings for emacs mode.
2954
 
2955
     set editing-mode emacs
2956
 
2957
     $if mode=emacs
2958
 
2959
     Meta-Control-h:    backward-kill-word      Text after the function name is ignored
2960
 
2961
     #
2962
     # Arrow keys in keypad mode
2963
     #
2964
     #"\M-OD":        backward-char
2965
     #"\M-OC":        forward-char
2966
     #"\M-OA":        previous-history
2967
     #"\M-OB":        next-history
2968
     #
2969
     # Arrow keys in ANSI mode
2970
     #
2971
     "\M-[D":        backward-char
2972
     "\M-[C":        forward-char
2973
     "\M-[A":        previous-history
2974
     "\M-[B":        next-history
2975
     #
2976
     # Arrow keys in 8 bit keypad mode
2977
     #
2978
     #"\M-\C-OD":       backward-char
2979
     #"\M-\C-OC":       forward-char
2980
     #"\M-\C-OA":       previous-history
2981
     #"\M-\C-OB":       next-history
2982
     #
2983
     # Arrow keys in 8 bit ANSI mode
2984
     #
2985
     #"\M-\C-[D":       backward-char
2986
     #"\M-\C-[C":       forward-char
2987
     #"\M-\C-[A":       previous-history
2988
     #"\M-\C-[B":       next-history
2989
 
2990
     C-q: quoted-insert
2991
 
2992
     $endif
2993
 
2994
     # An old-style binding.  This happens to be the default.
2995
     TAB: complete
2996
 
2997
     # Macros that are convenient for shell interaction
2998
     $if Bash
2999
     # edit the path
3000
     "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
3001
     # prepare to type a quoted word --
3002
     # insert open and close double quotes
3003
     # and move to just after the open quote
3004
     "\C-x\"": "\"\"\C-b"
3005
     # insert a backslash (testing backslash escapes
3006
     # in sequences and macros)
3007
     "\C-x\\": "\\"
3008
     # Quote the current or previous word
3009
     "\C-xq": "\eb\"\ef\""
3010
     # Add a binding to refresh the line, which is unbound
3011
     "\C-xr": redraw-current-line
3012
     # Edit variable on current line.
3013
     "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
3014
     $endif
3015
 
3016
     # use a visible bell if one is available
3017
     set bell-style visible
3018
 
3019
     # don't strip characters to 7 bits when reading
3020
     set input-meta on
3021
 
3022
     # allow iso-latin1 characters to be inserted rather
3023
     # than converted to prefix-meta sequences
3024
     set convert-meta off
3025
 
3026
     # display characters with the eighth bit set directly
3027
     # rather than as meta-prefixed characters
3028
     set output-meta on
3029
 
3030
     # if there are more than 150 possible completions for
3031
     # a word, ask the user if he wants to see all of them
3032
     set completion-query-items 150
3033
 
3034
     # For FTP
3035
     $if Ftp
3036
     "\C-xg": "get \M-?"
3037
     "\C-xt": "put \M-?"
3038
     "\M-.": yank-last-arg
3039
     $endif
3040
 
3041

3042
File: gdb.info,  Node: Bindable Readline Commands,  Next: Readline vi Mode,  Prev: Readline Init File,  Up: Command Line Editing
3043
 
3044
31.4 Bindable Readline Commands
3045
===============================
3046
 
3047
* Menu:
3048
 
3049
* Commands For Moving::         Moving about the line.
3050
* Commands For History::        Getting at previous lines.
3051
* Commands For Text::           Commands for changing text.
3052
* Commands For Killing::        Commands for killing and yanking.
3053
* Numeric Arguments::           Specifying numeric arguments, repeat counts.
3054
* Commands For Completion::     Getting Readline to do the typing for you.
3055
* Keyboard Macros::             Saving and re-executing typed characters
3056
* Miscellaneous Commands::      Other miscellaneous commands.
3057
 
3058
   This section describes Readline commands that may be bound to key
3059
sequences.  Command names without an accompanying key sequence are
3060
unbound by default.
3061
 
3062
   In the following descriptions, "point" refers to the current cursor
3063
position, and "mark" refers to a cursor position saved by the
3064
`set-mark' command.  The text between the point and mark is referred to
3065
as the "region".
3066
 
3067

3068
File: gdb.info,  Node: Commands For Moving,  Next: Commands For History,  Up: Bindable Readline Commands
3069
 
3070
31.4.1 Commands For Moving
3071
--------------------------
3072
 
3073
`beginning-of-line (C-a)'
3074
     Move to the start of the current line.
3075
 
3076
`end-of-line (C-e)'
3077
     Move to the end of the line.
3078
 
3079
`forward-char (C-f)'
3080
     Move forward a character.
3081
 
3082
`backward-char (C-b)'
3083
     Move back a character.
3084
 
3085
`forward-word (M-f)'
3086
     Move forward to the end of the next word.  Words are composed of
3087
     letters and digits.
3088
 
3089
`backward-word (M-b)'
3090
     Move back to the start of the current or previous word.  Words are
3091
     composed of letters and digits.
3092
 
3093
`clear-screen (C-l)'
3094
     Clear the screen and redraw the current line, leaving the current
3095
     line at the top of the screen.
3096
 
3097
`redraw-current-line ()'
3098
     Refresh the current line.  By default, this is unbound.
3099
 
3100
 
3101

3102
File: gdb.info,  Node: Commands For History,  Next: Commands For Text,  Prev: Commands For Moving,  Up: Bindable Readline Commands
3103
 
3104
31.4.2 Commands For Manipulating The History
3105
--------------------------------------------
3106
 
3107
`accept-line (Newline or Return)'
3108
     Accept the line regardless of where the cursor is.  If this line is
3109
     non-empty, it may be added to the history list for future recall
3110
     with `add_history()'.  If this line is a modified history line,
3111
     the history line is restored to its original state.
3112
 
3113
`previous-history (C-p)'
3114
     Move `back' through the history list, fetching the previous
3115
     command.
3116
 
3117
`next-history (C-n)'
3118
     Move `forward' through the history list, fetching the next command.
3119
 
3120
`beginning-of-history (M-<)'
3121
     Move to the first line in the history.
3122
 
3123
`end-of-history (M->)'
3124
     Move to the end of the input history, i.e., the line currently
3125
     being entered.
3126
 
3127
`reverse-search-history (C-r)'
3128
     Search backward starting at the current line and moving `up'
3129
     through the history as necessary.  This is an incremental search.
3130
 
3131
`forward-search-history (C-s)'
3132
     Search forward starting at the current line and moving `down'
3133
     through the the history as necessary.  This is an incremental
3134
     search.
3135
 
3136
`non-incremental-reverse-search-history (M-p)'
3137
     Search backward starting at the current line and moving `up'
3138
     through the history as necessary using a non-incremental search
3139
     for a string supplied by the user.
3140
 
3141
`non-incremental-forward-search-history (M-n)'
3142
     Search forward starting at the current line and moving `down'
3143
     through the the history as necessary using a non-incremental search
3144
     for a string supplied by the user.
3145
 
3146
`history-search-forward ()'
3147
     Search forward through the history for the string of characters
3148
     between the start of the current line and the point.  This is a
3149
     non-incremental search.  By default, this command is unbound.
3150
 
3151
`history-search-backward ()'
3152
     Search backward through the history for the string of characters
3153
     between the start of the current line and the point.  This is a
3154
     non-incremental search.  By default, this command is unbound.
3155
 
3156
`yank-nth-arg (M-C-y)'
3157
     Insert the first argument to the previous command (usually the
3158
     second word on the previous line) at point.  With an argument N,
3159
     insert the Nth word from the previous command (the words in the
3160
     previous command begin with word 0).  A negative argument inserts
3161
     the Nth word from the end of the previous command.  Once the
3162
     argument N is computed, the argument is extracted as if the `!N'
3163
     history expansion had been specified.
3164
 
3165
`yank-last-arg (M-. or M-_)'
3166
     Insert last argument to the previous command (the last word of the
3167
     previous history entry).  With an argument, behave exactly like
3168
     `yank-nth-arg'.  Successive calls to `yank-last-arg' move back
3169
     through the history list, inserting the last argument of each line
3170
     in turn.  The history expansion facilities are used to extract the
3171
     last argument, as if the `!$' history expansion had been specified.
3172
 
3173
 
3174

3175
File: gdb.info,  Node: Commands For Text,  Next: Commands For Killing,  Prev: Commands For History,  Up: Bindable Readline Commands
3176
 
3177
31.4.3 Commands For Changing Text
3178
---------------------------------
3179
 
3180
`delete-char (C-d)'
3181
     Delete the character at point.  If point is at the beginning of
3182
     the line, there are no characters in the line, and the last
3183
     character typed was not bound to `delete-char', then return EOF.
3184
 
3185
`backward-delete-char (Rubout)'
3186
     Delete the character behind the cursor.  A numeric argument means
3187
     to kill the characters instead of deleting them.
3188
 
3189
`forward-backward-delete-char ()'
3190
     Delete the character under the cursor, unless the cursor is at the
3191
     end of the line, in which case the character behind the cursor is
3192
     deleted.  By default, this is not bound to a key.
3193
 
3194
`quoted-insert (C-q or C-v)'
3195
     Add the next character typed to the line verbatim.  This is how to
3196
     insert key sequences like `C-q', for example.
3197
 
3198
`tab-insert (M-)'
3199
     Insert a tab character.
3200
 
3201
`self-insert (a, b, A, 1, !, ...)'
3202
     Insert yourself.
3203
 
3204
`transpose-chars (C-t)'
3205
     Drag the character before the cursor forward over the character at
3206
     the cursor, moving the cursor forward as well.  If the insertion
3207
     point is at the end of the line, then this transposes the last two
3208
     characters of the line.  Negative arguments have no effect.
3209
 
3210
`transpose-words (M-t)'
3211
     Drag the word before point past the word after point, moving point
3212
     past that word as well.  If the insertion point is at the end of
3213
     the line, this transposes the last two words on the line.
3214
 
3215
`upcase-word (M-u)'
3216
     Uppercase the current (or following) word.  With a negative
3217
     argument, uppercase the previous word, but do not move the cursor.
3218
 
3219
`downcase-word (M-l)'
3220
     Lowercase the current (or following) word.  With a negative
3221
     argument, lowercase the previous word, but do not move the cursor.
3222
 
3223
`capitalize-word (M-c)'
3224
     Capitalize the current (or following) word.  With a negative
3225
     argument, capitalize the previous word, but do not move the cursor.
3226
 
3227
`overwrite-mode ()'
3228
     Toggle overwrite mode.  With an explicit positive numeric argument,
3229
     switches to overwrite mode.  With an explicit non-positive numeric
3230
     argument, switches to insert mode.  This command affects only
3231
     `emacs' mode; `vi' mode does overwrite differently.  Each call to
3232
     `readline()' starts in insert mode.
3233
 
3234
     In overwrite mode, characters bound to `self-insert' replace the
3235
     text at point rather than pushing the text to the right.
3236
     Characters bound to `backward-delete-char' replace the character
3237
     before point with a space.
3238
 
3239
     By default, this command is unbound.
3240
 
3241
 
3242

3243
File: gdb.info,  Node: Commands For Killing,  Next: Numeric Arguments,  Prev: Commands For Text,  Up: Bindable Readline Commands
3244
 
3245
31.4.4 Killing And Yanking
3246
--------------------------
3247
 
3248
`kill-line (C-k)'
3249
     Kill the text from point to the end of the line.
3250
 
3251
`backward-kill-line (C-x Rubout)'
3252
     Kill backward to the beginning of the line.
3253
 
3254
`unix-line-discard (C-u)'
3255
     Kill backward from the cursor to the beginning of the current line.
3256
 
3257
`kill-whole-line ()'
3258
     Kill all characters on the current line, no matter where point is.
3259
     By default, this is unbound.
3260
 
3261
`kill-word (M-d)'
3262
     Kill from point to the end of the current word, or if between
3263
     words, to the end of the next word.  Word boundaries are the same
3264
     as `forward-word'.
3265
 
3266
`backward-kill-word (M-)'
3267
     Kill the word behind point.  Word boundaries are the same as
3268
     `backward-word'.
3269
 
3270
`unix-word-rubout (C-w)'
3271
     Kill the word behind point, using white space as a word boundary.
3272
     The killed text is saved on the kill-ring.
3273
 
3274
`unix-filename-rubout ()'
3275
     Kill the word behind point, using white space and the slash
3276
     character as the word boundaries.  The killed text is saved on the
3277
     kill-ring.
3278
 
3279
`delete-horizontal-space ()'
3280
     Delete all spaces and tabs around point.  By default, this is
3281
     unbound.
3282
 
3283
`kill-region ()'
3284
     Kill the text in the current region.  By default, this command is
3285
     unbound.
3286
 
3287
`copy-region-as-kill ()'
3288
     Copy the text in the region to the kill buffer, so it can be yanked
3289
     right away.  By default, this command is unbound.
3290
 
3291
`copy-backward-word ()'
3292
     Copy the word before point to the kill buffer.  The word
3293
     boundaries are the same as `backward-word'.  By default, this
3294
     command is unbound.
3295
 
3296
`copy-forward-word ()'
3297
     Copy the word following point to the kill buffer.  The word
3298
     boundaries are the same as `forward-word'.  By default, this
3299
     command is unbound.
3300
 
3301
`yank (C-y)'
3302
     Yank the top of the kill ring into the buffer at point.
3303
 
3304
`yank-pop (M-y)'
3305
     Rotate the kill-ring, and yank the new top.  You can only do this
3306
     if the prior command is `yank' or `yank-pop'.
3307
 
3308

3309
File: gdb.info,  Node: Numeric Arguments,  Next: Commands For Completion,  Prev: Commands For Killing,  Up: Bindable Readline Commands
3310
 
3311
31.4.5 Specifying Numeric Arguments
3312
-----------------------------------
3313
 
3314
`digit-argument (M-0, M-1, ... M--)'
3315
     Add this digit to the argument already accumulating, or start a new
3316
     argument.  `M--' starts a negative argument.
3317
 
3318
`universal-argument ()'
3319
     This is another way to specify an argument.  If this command is
3320
     followed by one or more digits, optionally with a leading minus
3321
     sign, those digits define the argument.  If the command is
3322
     followed by digits, executing `universal-argument' again ends the
3323
     numeric argument, but is otherwise ignored.  As a special case, if
3324
     this command is immediately followed by a character that is
3325
     neither a digit or minus sign, the argument count for the next
3326
     command is multiplied by four.  The argument count is initially
3327
     one, so executing this function the first time makes the argument
3328
     count four, a second time makes the argument count sixteen, and so
3329
     on.  By default, this is not bound to a key.
3330
 
3331

3332
File: gdb.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Prev: Numeric Arguments,  Up: Bindable Readline Commands
3333
 
3334
31.4.6 Letting Readline Type For You
3335
------------------------------------
3336
 
3337
`complete ()'
3338
     Attempt to perform completion on the text before point.  The
3339
     actual completion performed is application-specific.  The default
3340
     is filename completion.
3341
 
3342
`possible-completions (M-?)'
3343
     List the possible completions of the text before point.
3344
 
3345
`insert-completions (M-*)'
3346
     Insert all completions of the text before point that would have
3347
     been generated by `possible-completions'.
3348
 
3349
`menu-complete ()'
3350
     Similar to `complete', but replaces the word to be completed with
3351
     a single match from the list of possible completions.  Repeated
3352
     execution of `menu-complete' steps through the list of possible
3353
     completions, inserting each match in turn.  At the end of the list
3354
     of completions, the bell is rung (subject to the setting of
3355
     `bell-style') and the original text is restored.  An argument of N
3356
     moves N positions forward in the list of matches; a negative
3357
     argument may be used to move backward through the list.  This
3358
     command is intended to be bound to , but is unbound by
3359
     default.
3360
 
3361
`delete-char-or-list ()'
3362
     Deletes the character under the cursor if not at the beginning or
3363
     end of the line (like `delete-char').  If at the end of the line,
3364
     behaves identically to `possible-completions'.  This command is
3365
     unbound by default.
3366
 
3367
 
3368

3369
File: gdb.info,  Node: Keyboard Macros,  Next: Miscellaneous Commands,  Prev: Commands For Completion,  Up: Bindable Readline Commands
3370
 
3371
31.4.7 Keyboard Macros
3372
----------------------
3373
 
3374
`start-kbd-macro (C-x ()'
3375
     Begin saving the characters typed into the current keyboard macro.
3376
 
3377
`end-kbd-macro (C-x ))'
3378
     Stop saving the characters typed into the current keyboard macro
3379
     and save the definition.
3380
 
3381
`call-last-kbd-macro (C-x e)'
3382
     Re-execute the last keyboard macro defined, by making the
3383
     characters in the macro appear as if typed at the keyboard.
3384
 
3385
 
3386

3387
File: gdb.info,  Node: Miscellaneous Commands,  Prev: Keyboard Macros,  Up: Bindable Readline Commands
3388
 
3389
31.4.8 Some Miscellaneous Commands
3390
----------------------------------
3391
 
3392
`re-read-init-file (C-x C-r)'
3393
     Read in the contents of the INPUTRC file, and incorporate any
3394
     bindings or variable assignments found there.
3395
 
3396
`abort (C-g)'
3397
     Abort the current editing command and ring the terminal's bell
3398
     (subject to the setting of `bell-style').
3399
 
3400
`do-uppercase-version (M-a, M-b, M-X, ...)'
3401
     If the metafied character X is lowercase, run the command that is
3402
     bound to the corresponding uppercase character.
3403
 
3404
`prefix-meta ()'
3405
     Metafy the next character typed.  This is for keyboards without a
3406
     meta key.  Typing ` f' is equivalent to typing `M-f'.
3407
 
3408
`undo (C-_ or C-x C-u)'
3409
     Incremental undo, separately remembered for each line.
3410
 
3411
`revert-line (M-r)'
3412
     Undo all changes made to this line.  This is like executing the
3413
     `undo' command enough times to get back to the beginning.
3414
 
3415
`tilde-expand (M-~)'
3416
     Perform tilde expansion on the current word.
3417
 
3418
`set-mark (C-@)'
3419
     Set the mark to the point.  If a numeric argument is supplied, the
3420
     mark is set to that position.
3421
 
3422
`exchange-point-and-mark (C-x C-x)'
3423
     Swap the point with the mark.  The current cursor position is set
3424
     to the saved position, and the old cursor position is saved as the
3425
     mark.
3426
 
3427
`character-search (C-])'
3428
     A character is read and point is moved to the next occurrence of
3429
     that character.  A negative count searches for previous
3430
     occurrences.
3431
 
3432
`character-search-backward (M-C-])'
3433
     A character is read and point is moved to the previous occurrence
3434
     of that character.  A negative count searches for subsequent
3435
     occurrences.
3436
 
3437
`insert-comment (M-#)'
3438
     Without a numeric argument, the value of the `comment-begin'
3439
     variable is inserted at the beginning of the current line.  If a
3440
     numeric argument is supplied, this command acts as a toggle:  if
3441
     the characters at the beginning of the line do not match the value
3442
     of `comment-begin', the value is inserted, otherwise the
3443
     characters in `comment-begin' are deleted from the beginning of
3444
     the line.  In either case, the line is accepted as if a newline
3445
     had been typed.
3446
 
3447
`dump-functions ()'
3448
     Print all of the functions and their key bindings to the Readline
3449
     output stream.  If a numeric argument is supplied, the output is
3450
     formatted in such a way that it can be made part of an INPUTRC
3451
     file.  This command is unbound by default.
3452
 
3453
`dump-variables ()'
3454
     Print all of the settable variables and their values to the
3455
     Readline output stream.  If a numeric argument is supplied, the
3456
     output is formatted in such a way that it can be made part of an
3457
     INPUTRC file.  This command is unbound by default.
3458
 
3459
`dump-macros ()'
3460
     Print all of the Readline key sequences bound to macros and the
3461
     strings they output.  If a numeric argument is supplied, the
3462
     output is formatted in such a way that it can be made part of an
3463
     INPUTRC file.  This command is unbound by default.
3464
 
3465
`emacs-editing-mode (C-e)'
3466
     When in `vi' command mode, this causes a switch to `emacs' editing
3467
     mode.
3468
 
3469
`vi-editing-mode (M-C-j)'
3470
     When in `emacs' editing mode, this causes a switch to `vi' editing
3471
     mode.
3472
 
3473
 
3474

3475
File: gdb.info,  Node: Readline vi Mode,  Prev: Bindable Readline Commands,  Up: Command Line Editing
3476
 
3477
31.5 Readline vi Mode
3478
=====================
3479
 
3480
While the Readline library does not have a full set of `vi' editing
3481
functions, it does contain enough to allow simple editing of the line.
3482
The Readline `vi' mode behaves as specified in the POSIX 1003.2
3483
standard.
3484
 
3485
   In order to switch interactively between `emacs' and `vi' editing
3486
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
3487
`vi' mode and to vi-editing-mode in `emacs' mode).  The Readline
3488
default is `emacs' mode.
3489
 
3490
   When you enter a line in `vi' mode, you are already placed in
3491
`insertion' mode, as if you had typed an `i'.  Pressing  switches
3492
you into `command' mode, where you can edit the text of the line with
3493
the standard `vi' movement keys, move to previous history lines with
3494
`k' and subsequent lines with `j', and so forth.
3495
 
3496

3497
File: gdb.info,  Node: Using History Interactively,  Next: Formatting Documentation,  Prev: Command Line Editing,  Up: Top
3498
 
3499
32 Using History Interactively
3500
******************************
3501
 
3502
This chapter describes how to use the GNU History Library interactively,
3503
from a user's standpoint.  It should be considered a user's guide.  For
3504
information on using the GNU History Library in other programs, see the
3505
GNU Readline Library Manual.
3506
 
3507
* Menu:
3508
 
3509
* History Interaction::         What it feels like using History as a user.
3510
 
3511

3512
File: gdb.info,  Node: History Interaction,  Up: Using History Interactively
3513
 
3514
32.1 History Expansion
3515
======================
3516
 
3517
The History library provides a history expansion feature that is similar
3518
to the history expansion provided by `csh'.  This section describes the
3519
syntax used to manipulate the history information.
3520
 
3521
   History expansions introduce words from the history list into the
3522
input stream, making it easy to repeat commands, insert the arguments
3523
to a previous command into the current input line, or fix errors in
3524
previous commands quickly.
3525
 
3526
   History expansion takes place in two parts.  The first is to
3527
determine which line from the history list should be used during
3528
substitution.  The second is to select portions of that line for
3529
inclusion into the current one.  The line selected from the history is
3530
called the "event", and the portions of that line that are acted upon
3531
are called "words".  Various "modifiers" are available to manipulate
3532
the selected words.  The line is broken into words in the same fashion
3533
that Bash does, so that several words surrounded by quotes are
3534
considered one word.  History expansions are introduced by the
3535
appearance of the history expansion character, which is `!' by default.
3536
 
3537
* Menu:
3538
 
3539
* Event Designators::   How to specify which history line to use.
3540
* Word Designators::    Specifying which words are of interest.
3541
* Modifiers::           Modifying the results of substitution.
3542
 
3543

3544
File: gdb.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction
3545
 
3546
32.1.1 Event Designators
3547
------------------------
3548
 
3549
An event designator is a reference to a command line entry in the
3550
history list.
3551
 
3552
`!'
3553
     Start a history substitution, except when followed by a space, tab,
3554
     the end of the line, or `='.
3555
 
3556
`!N'
3557
     Refer to command line N.
3558
 
3559
`!-N'
3560
     Refer to the command N lines back.
3561
 
3562
`!!'
3563
     Refer to the previous command.  This is a synonym for `!-1'.
3564
 
3565
`!STRING'
3566
     Refer to the most recent command starting with STRING.
3567
 
3568
`!?STRING[?]'
3569
     Refer to the most recent command containing STRING.  The trailing
3570
     `?' may be omitted if the STRING is followed immediately by a
3571
     newline.
3572
 
3573
`^STRING1^STRING2^'
3574
     Quick Substitution.  Repeat the last command, replacing STRING1
3575
     with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.
3576
 
3577
`!#'
3578
     The entire command line typed so far.
3579
 
3580
 
3581

3582
File: gdb.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction
3583
 
3584
32.1.2 Word Designators
3585
-----------------------
3586
 
3587
Word designators are used to select desired words from the event.  A
3588
`:' separates the event specification from the word designator.  It may
3589
be omitted if the word designator begins with a `^', `$', `*', `-', or
3590
`%'.  Words are numbered from the beginning of the line, with the first
3591
word being denoted by 0 (zero).  Words are inserted into the current
3592
line separated by single spaces.
3593
 
3594
   For example,
3595
 
3596
`!!'
3597
     designates the preceding command.  When you type this, the
3598
     preceding command is repeated in toto.
3599
 
3600
`!!:$'
3601
     designates the last argument of the preceding command.  This may be
3602
     shortened to `!$'.
3603
 
3604
`!fi:2'
3605
     designates the second argument of the most recent command starting
3606
     with the letters `fi'.
3607
 
3608
   Here are the word designators:
3609
 
3610
`0 (zero)'
3611
     The `0'th word.  For many applications, this is the command word.
3612
 
3613
`N'
3614
     The Nth word.
3615
 
3616
`^'
3617
     The first argument; that is, word 1.
3618
 
3619
`$'
3620
     The last argument.
3621
 
3622
`%'
3623
     The word matched by the most recent `?STRING?' search.
3624
 
3625
`X-Y'
3626
     A range of words; `-Y' abbreviates `0-Y'.
3627
 
3628
`*'
3629
     All of the words, except the `0'th.  This is a synonym for `1-$'.
3630
     It is not an error to use `*' if there is just one word in the
3631
     event; the empty string is returned in that case.
3632
 
3633
`X*'
3634
     Abbreviates `X-$'
3635
 
3636
`X-'
3637
     Abbreviates `X-$' like `X*', but omits the last word.
3638
 
3639
 
3640
   If a word designator is supplied without an event specification, the
3641
previous command is used as the event.
3642
 
3643

3644
File: gdb.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction
3645
 
3646
32.1.3 Modifiers
3647
----------------
3648
 
3649
After the optional word designator, you can add a sequence of one or
3650
more of the following modifiers, each preceded by a `:'.
3651
 
3652
`h'
3653
     Remove a trailing pathname component, leaving only the head.
3654
 
3655
`t'
3656
     Remove all leading  pathname  components, leaving the tail.
3657
 
3658
`r'
3659
     Remove a trailing suffix of the form `.SUFFIX', leaving the
3660
     basename.
3661
 
3662
`e'
3663
     Remove all but the trailing suffix.
3664
 
3665
`p'
3666
     Print the new command but do not execute it.
3667
 
3668
`s/OLD/NEW/'
3669
     Substitute NEW for the first occurrence of OLD in the event line.
3670
     Any delimiter may be used in place of `/'.  The delimiter may be
3671
     quoted in OLD and NEW with a single backslash.  If `&' appears in
3672
     NEW, it is replaced by OLD.  A single backslash will quote the
3673
     `&'.  The final delimiter is optional if it is the last character
3674
     on the input line.
3675
 
3676
`&'
3677
     Repeat the previous substitution.
3678
 
3679
`g'
3680
`a'
3681
     Cause changes to be applied over the entire event line.  Used in
3682
     conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
3683
 
3684
`G'
3685
     Apply the following `s' modifier once to each word in the event.
3686
 
3687
 
3688

3689
File: gdb.info,  Node: Formatting Documentation,  Next: Installing GDB,  Prev: Using History Interactively,  Up: Top
3690
 
3691
Appendix A Formatting Documentation
3692
***********************************
3693
 
3694
The GDB 4 release includes an already-formatted reference card, ready
3695
for printing with PostScript or Ghostscript, in the `gdb' subdirectory
3696
of the main source directory(1).  If you can use PostScript or
3697
Ghostscript with your printer, you can print the reference card
3698
immediately with `refcard.ps'.
3699
 
3700
   The release also includes the source for the reference card.  You
3701
can format it, using TeX, by typing:
3702
 
3703
     make refcard.dvi
3704
 
3705
   The GDB reference card is designed to print in "landscape" mode on
3706
US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
3707
high.  You will need to specify this form of printing as an option to
3708
your DVI output program.
3709
 
3710
   All the documentation for GDB comes as part of the machine-readable
3711
distribution.  The documentation is written in Texinfo format, which is
3712
a documentation system that uses a single source file to produce both
3713
on-line information and a printed manual.  You can use one of the Info
3714
formatting commands to create the on-line version of the documentation
3715
and TeX (or `texi2roff') to typeset the printed version.
3716
 
3717
   GDB includes an already formatted copy of the on-line Info version
3718
of this manual in the `gdb' subdirectory.  The main Info file is
3719 512 jeremybenn
`gdb-7.2-or32-1.0rc3/gdb/gdb.info', and it refers to subordinate files
3720 342 jeremybenn
matching `gdb.info*' in the same directory.  If necessary, you can
3721
print out these files, or read them with any editor; but they are
3722
easier to read using the `info' subsystem in GNU Emacs or the
3723
standalone `info' program, available as part of the GNU Texinfo
3724
distribution.
3725 330 jeremybenn
 
3726
   If you want to format these Info files yourself, you need one of the
3727
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
3728
 
3729
   If you have `makeinfo' installed, and are in the top level GDB
3730 512 jeremybenn
source directory (`gdb-7.2-or32-1.0rc3', in the case of version
3731
7.2-or32-1.0rc3), you can make the Info file by typing:
3732 330 jeremybenn
 
3733
     cd gdb
3734
     make gdb.info
3735
 
3736
   If you want to typeset and print copies of this manual, you need TeX,
3737
a program to print its DVI output files, and `texinfo.tex', the Texinfo
3738
definitions file.
3739
 
3740
   TeX is a typesetting program; it does not print files directly, but
3741
produces output files called DVI files.  To print a typeset document,
3742
you need a program to print DVI files.  If your system has TeX
3743
installed, chances are it has such a program.  The precise command to
3744
use depends on your system; `lpr -d' is common; another (for PostScript
3745
devices) is `dvips'.  The DVI print command may require a file name
3746
without any extension or a `.dvi' extension.
3747
 
3748
   TeX also requires a macro definitions file called `texinfo.tex'.
3749
This file tells TeX how to typeset a document written in Texinfo
3750
format.  On its own, TeX cannot either read or typeset a Texinfo file.
3751
`texinfo.tex' is distributed with GDB and is located in the
3752
`gdb-VERSION-NUMBER/texinfo' directory.
3753
 
3754
   If you have TeX and a DVI printer program installed, you can typeset
3755
and print this manual.  First switch to the `gdb' subdirectory of the
3756 512 jeremybenn
main source directory (for example, to `gdb-7.2-or32-1.0rc3/gdb') and
3757 342 jeremybenn
type:
3758 330 jeremybenn
 
3759
     make gdb.dvi
3760
 
3761
   Then give `gdb.dvi' to your DVI printing program.
3762
 
3763
   ---------- Footnotes ----------
3764
 
3765 512 jeremybenn
   (1) In `gdb-7.2-or32-1.0rc3/gdb/refcard.ps' of the version
3766
7.2-or32-1.0rc3 release.
3767 330 jeremybenn
 
3768

3769
File: gdb.info,  Node: Installing GDB,  Next: Maintenance Commands,  Prev: Formatting Documentation,  Up: Top
3770
 
3771
Appendix B Installing GDB
3772
*************************
3773
 
3774
* Menu:
3775
 
3776
* Requirements::                Requirements for building GDB
3777
* Running Configure::           Invoking the GDB `configure' script
3778
* Separate Objdir::             Compiling GDB in another directory
3779
* Config Names::                Specifying names for hosts and targets
3780
* Configure Options::           Summary of options for configure
3781
* System-wide configuration::   Having a system-wide init file
3782
 
3783

3784
File: gdb.info,  Node: Requirements,  Next: Running Configure,  Up: Installing GDB
3785
 
3786
B.1 Requirements for Building GDB
3787
=================================
3788
 
3789
Building GDB requires various tools and packages to be available.
3790
Other packages will be used only if they are found.
3791
 
3792
Tools/Packages Necessary for Building GDB
3793
=========================================
3794
 
3795
ISO C90 compiler
3796
     GDB is written in ISO C90.  It should be buildable with any
3797
     working C90 compiler, e.g. GCC.
3798
 
3799
 
3800
Tools/Packages Optional for Building GDB
3801
========================================
3802
 
3803
Expat
3804
     GDB can use the Expat XML parsing library.  This library may be
3805
     included with your operating system distribution; if it is not, you
3806
     can get the latest version from `http://expat.sourceforge.net'.
3807
     The `configure' script will search for this library in several
3808
     standard locations; if it is installed in an unusual path, you can
3809
     use the `--with-libexpat-prefix' option to specify its location.
3810
 
3811
     Expat is used for:
3812
 
3813
        * Remote protocol memory maps (*note Memory Map Format::)
3814
 
3815
        * Target descriptions (*note Target Descriptions::)
3816
 
3817
        * Remote shared library lists (*note Library List Format::)
3818
 
3819
        * MS-Windows shared libraries (*note Shared Libraries::)
3820
 
3821
zlib
3822
     GDB will use the `zlib' library, if available, to read compressed
3823
     debug sections.  Some linkers, such as GNU gold, are capable of
3824
     producing binaries with compressed debug sections.  If GDB is
3825
     compiled with `zlib', it will be able to read the debug
3826
     information in such binaries.
3827
 
3828
     The `zlib' library is likely included with your operating system
3829
     distribution; if it is not, you can get the latest version from
3830
     `http://zlib.net'.
3831
 
3832
iconv
3833
     GDB's features related to character sets (*note Character Sets::)
3834
     require a functioning `iconv' implementation.  If you are on a GNU
3835
     system, then this is provided by the GNU C Library.  Some other
3836
     systems also provide a working `iconv'.
3837
 
3838
     On systems with `iconv', you can install GNU Libiconv.  If you
3839
     have previously installed Libiconv, you can use the
3840
     `--with-libiconv-prefix' option to configure.
3841
 
3842
     GDB's top-level `configure' and `Makefile' will arrange to build
3843
     Libiconv if a directory named `libiconv' appears in the top-most
3844
     source directory.  If Libiconv is built this way, and if the
3845
     operating system does not provide a suitable `iconv'
3846
     implementation, then the just-built library will automatically be
3847
     used by GDB.  One easy way to set this up is to download GNU
3848
     Libiconv, unpack it, and then rename the directory holding the
3849
     Libiconv source code to `libiconv'.
3850
 
3851

3852
File: gdb.info,  Node: Running Configure,  Next: Separate Objdir,  Prev: Requirements,  Up: Installing GDB
3853
 
3854
B.2 Invoking the GDB `configure' Script
3855
=======================================
3856
 
3857
GDB comes with a `configure' script that automates the process of
3858
preparing GDB for installation; you can then use `make' to build the
3859
`gdb' program.
3860
 
3861
   The GDB distribution includes all the source code you need for GDB
3862
in a single directory, whose name is usually composed by appending the
3863
version number to `gdb'.
3864
 
3865 512 jeremybenn
   For example, the GDB version 7.2-or32-1.0rc3 distribution is in the
3866
`gdb-7.2-or32-1.0rc3' directory.  That directory contains:
3867 330 jeremybenn
 
3868 512 jeremybenn
`gdb-7.2-or32-1.0rc3/configure (and supporting files)'
3869 330 jeremybenn
     script for configuring GDB and all its supporting libraries
3870
 
3871 512 jeremybenn
`gdb-7.2-or32-1.0rc3/gdb'
3872 330 jeremybenn
     the source specific to GDB itself
3873
 
3874 512 jeremybenn
`gdb-7.2-or32-1.0rc3/bfd'
3875 330 jeremybenn
     source for the Binary File Descriptor library
3876
 
3877 512 jeremybenn
`gdb-7.2-or32-1.0rc3/include'
3878 330 jeremybenn
     GNU include files
3879
 
3880 512 jeremybenn
`gdb-7.2-or32-1.0rc3/libiberty'
3881 330 jeremybenn
     source for the `-liberty' free software library
3882
 
3883 512 jeremybenn
`gdb-7.2-or32-1.0rc3/opcodes'
3884 330 jeremybenn
     source for the library of opcode tables and disassemblers
3885
 
3886 512 jeremybenn
`gdb-7.2-or32-1.0rc3/readline'
3887 330 jeremybenn
     source for the GNU command-line interface
3888
 
3889 512 jeremybenn
`gdb-7.2-or32-1.0rc3/glob'
3890 330 jeremybenn
     source for the GNU filename pattern-matching subroutine
3891
 
3892 512 jeremybenn
`gdb-7.2-or32-1.0rc3/mmalloc'
3893 330 jeremybenn
     source for the GNU memory-mapped malloc package
3894
 
3895
   The simplest way to configure and build GDB is to run `configure'
3896
from the `gdb-VERSION-NUMBER' source directory, which in this example
3897 512 jeremybenn
is the `gdb-7.2-or32-1.0rc3' directory.
3898 330 jeremybenn
 
3899
   First switch to the `gdb-VERSION-NUMBER' source directory if you are
3900
not already in it; then run `configure'.  Pass the identifier for the
3901
platform on which GDB will run as an argument.
3902
 
3903
   For example:
3904
 
3905 512 jeremybenn
     cd gdb-7.2-or32-1.0rc3
3906 330 jeremybenn
     ./configure HOST
3907
     make
3908
 
3909
where HOST is an identifier such as `sun4' or `decstation', that
3910
identifies the platform where GDB will run.  (You can often leave off
3911
HOST; `configure' tries to guess the correct value by examining your
3912
system.)
3913
 
3914
   Running `configure HOST' and then running `make' builds the `bfd',
3915
`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
3916
The configured source files, and the binaries, are left in the
3917
corresponding source directories.
3918
 
3919
   `configure' is a Bourne-shell (`/bin/sh') script; if your system
3920
does not recognize this automatically when you run a different shell,
3921
you may need to run `sh' on it explicitly:
3922
 
3923
     sh configure HOST
3924
 
3925
   If you run `configure' from a directory that contains source
3926 342 jeremybenn
directories for multiple libraries or programs, such as the
3927 512 jeremybenn
`gdb-7.2-or32-1.0rc3' source directory for version 7.2-or32-1.0rc3,
3928 342 jeremybenn
`configure' creates configuration files for every directory level
3929
underneath (unless you tell it not to, with the `--norecursion' option).
3930 330 jeremybenn
 
3931
   You should run the `configure' script from the top directory in the
3932
source tree, the `gdb-VERSION-NUMBER' directory.  If you run
3933
`configure' from one of the subdirectories, you will configure only
3934
that subdirectory.  That is usually not what you want.  In particular,
3935
if you run the first `configure' from the `gdb' subdirectory of the
3936
`gdb-VERSION-NUMBER' directory, you will omit the configuration of
3937
`bfd', `readline', and other sibling directories of the `gdb'
3938
subdirectory.  This leads to build errors about missing include files
3939
such as `bfd/bfd.h'.
3940
 
3941
   You can install `gdb' anywhere; it has no hardwired paths.  However,
3942
you should make sure that the shell on your path (named by the `SHELL'
3943
environment variable) is publicly readable.  Remember that GDB uses the
3944
shell to start your program--some systems refuse to let GDB debug child
3945
processes whose programs are not readable.
3946
 
3947

3948
File: gdb.info,  Node: Separate Objdir,  Next: Config Names,  Prev: Running Configure,  Up: Installing GDB
3949
 
3950
B.3 Compiling GDB in Another Directory
3951
======================================
3952
 
3953
If you want to run GDB versions for several host or target machines,
3954
you need a different `gdb' compiled for each combination of host and
3955
target.  `configure' is designed to make this easy by allowing you to
3956
generate each configuration in a separate subdirectory, rather than in
3957
the source directory.  If your `make' program handles the `VPATH'
3958
feature (GNU `make' does), running `make' in each of these directories
3959
builds the `gdb' program specified there.
3960
 
3961
   To build `gdb' in a separate directory, run `configure' with the
3962
`--srcdir' option to specify where to find the source.  (You also need
3963
to specify a path to find `configure' itself from your working
3964
directory.  If the path to `configure' would be the same as the
3965
argument to `--srcdir', you can leave out the `--srcdir' option; it is
3966
assumed.)
3967
 
3968 512 jeremybenn
   For example, with version 7.2-or32-1.0rc3, you can build GDB in a
3969 342 jeremybenn
separate directory for a Sun 4 like this:
3970 330 jeremybenn
 
3971 512 jeremybenn
     cd gdb-7.2-or32-1.0rc3
3972 330 jeremybenn
     mkdir ../gdb-sun4
3973
     cd ../gdb-sun4
3974 512 jeremybenn
     ../gdb-7.2-or32-1.0rc3/configure sun4
3975 330 jeremybenn
     make
3976
 
3977
   When `configure' builds a configuration using a remote source
3978
directory, it creates a tree for the binaries with the same structure
3979
(and using the same names) as the tree under the source directory.  In
3980
the example, you'd find the Sun 4 library `libiberty.a' in the
3981
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
3982
 
3983
   Make sure that your path to the `configure' script has just one
3984
instance of `gdb' in it.  If your path to `configure' looks like
3985 512 jeremybenn
`../gdb-7.2-or32-1.0rc3/gdb/configure', you are configuring only one
3986 342 jeremybenn
subdirectory of GDB, not the whole package.  This leads to build errors
3987
about missing include files such as `bfd/bfd.h'.
3988 330 jeremybenn
 
3989
   One popular reason to build several GDB configurations in separate
3990
directories is to configure GDB for cross-compiling (where GDB runs on
3991
one machine--the "host"--while debugging programs that run on another
3992
machine--the "target").  You specify a cross-debugging target by giving
3993
the `--target=TARGET' option to `configure'.
3994
 
3995
   When you run `make' to build a program or library, you must run it
3996
in a configured directory--whatever directory you were in when you
3997
called `configure' (or one of its subdirectories).
3998
 
3999
   The `Makefile' that `configure' generates in each source directory
4000
also runs recursively.  If you type `make' in a source directory such
4001 512 jeremybenn
as `gdb-7.2-or32-1.0rc3' (or in a separate configured directory
4002
configured with `--srcdir=DIRNAME/gdb-7.2-or32-1.0rc3'), you will build
4003 342 jeremybenn
all the required libraries, and then build GDB.
4004 330 jeremybenn
 
4005
   When you have multiple hosts or targets configured in separate
4006
directories, you can run `make' on them in parallel (for example, if
4007
they are NFS-mounted on each of the hosts); they will not interfere
4008
with each other.
4009
 
4010

4011
File: gdb.info,  Node: Config Names,  Next: Configure Options,  Prev: Separate Objdir,  Up: Installing GDB
4012
 
4013
B.4 Specifying Names for Hosts and Targets
4014
==========================================
4015
 
4016
The specifications used for hosts and targets in the `configure' script
4017
are based on a three-part naming scheme, but some short predefined
4018
aliases are also supported.  The full naming scheme encodes three pieces
4019
of information in the following pattern:
4020
 
4021
     ARCHITECTURE-VENDOR-OS
4022
 
4023
   For example, you can use the alias `sun4' as a HOST argument, or as
4024
the value for TARGET in a `--target=TARGET' option.  The equivalent
4025
full name is `sparc-sun-sunos4'.
4026
 
4027
   The `configure' script accompanying GDB does not provide any query
4028
facility to list all supported host and target names or aliases.
4029
`configure' calls the Bourne shell script `config.sub' to map
4030
abbreviations to full names; you can read the script, if you wish, or
4031
you can use it to test your guesses on abbreviations--for example:
4032
 
4033
     % sh config.sub i386-linux
4034
     i386-pc-linux-gnu
4035
     % sh config.sub alpha-linux
4036
     alpha-unknown-linux-gnu
4037
     % sh config.sub hp9k700
4038
     hppa1.1-hp-hpux
4039
     % sh config.sub sun4
4040
     sparc-sun-sunos4.1.1
4041
     % sh config.sub sun3
4042
     m68k-sun-sunos4.1.1
4043
     % sh config.sub i986v
4044
     Invalid configuration `i986v': machine `i986v' not recognized
4045
 
4046
`config.sub' is also distributed in the GDB source directory
4047 512 jeremybenn
(`gdb-7.2-or32-1.0rc3', for version 7.2-or32-1.0rc3).
4048 330 jeremybenn
 
4049

4050
File: gdb.info,  Node: Configure Options,  Next: System-wide configuration,  Prev: Config Names,  Up: Installing GDB
4051
 
4052
B.5 `configure' Options
4053
=======================
4054
 
4055
Here is a summary of the `configure' options and arguments that are
4056
most often useful for building GDB.  `configure' also has several other
4057
options not listed here.  *note (configure.info)What Configure Does::,
4058
for a full explanation of `configure'.
4059
 
4060
     configure [--help]
4061
               [--prefix=DIR]
4062
               [--exec-prefix=DIR]
4063
               [--srcdir=DIRNAME]
4064
               [--norecursion] [--rm]
4065
               [--target=TARGET]
4066
               HOST
4067
 
4068
You may introduce options with a single `-' rather than `--' if you
4069
prefer; but you may abbreviate option names if you use `--'.
4070
 
4071
`--help'
4072
     Display a quick summary of how to invoke `configure'.
4073
 
4074
`--prefix=DIR'
4075
     Configure the source to install programs and files under directory
4076
     `DIR'.
4077
 
4078
`--exec-prefix=DIR'
4079
     Configure the source to install programs under directory `DIR'.
4080
 
4081
`--srcdir=DIRNAME'
4082
     *Warning: using this option requires GNU `make', or another `make'
4083
     that implements the `VPATH' feature.*
4084
     Use this option to make configurations in directories separate
4085
     from the GDB source directories.  Among other things, you can use
4086
     this to build (or maintain) several configurations simultaneously,
4087
     in separate directories.  `configure' writes
4088
     configuration-specific files in the current directory, but
4089
     arranges for them to use the source in the directory DIRNAME.
4090
     `configure' creates directories under the working directory in
4091
     parallel to the source directories below DIRNAME.
4092
 
4093
`--norecursion'
4094
     Configure only the directory level where `configure' is executed;
4095
     do not propagate configuration to subdirectories.
4096
 
4097
`--target=TARGET'
4098
     Configure GDB for cross-debugging programs running on the specified
4099
     TARGET.  Without this option, GDB is configured to debug programs
4100
     that run on the same machine (HOST) as GDB itself.
4101
 
4102
     There is no convenient way to generate a list of all available
4103
     targets.
4104
 
4105
`HOST ...'
4106
     Configure GDB to run on the specified HOST.
4107
 
4108
     There is no convenient way to generate a list of all available
4109
     hosts.
4110
 
4111
   There are many other options available as well, but they are
4112
generally needed for special purposes only.
4113
 
4114

4115
File: gdb.info,  Node: System-wide configuration,  Prev: Configure Options,  Up: Installing GDB
4116
 
4117
B.6 System-wide configuration and settings
4118
==========================================
4119
 
4120
GDB can be configured to have a system-wide init file; this file will
4121
be read and executed at startup (*note What GDB does during startup:
4122
Startup.).
4123
 
4124
   Here is the corresponding configure option:
4125
 
4126
`--with-system-gdbinit=FILE'
4127
     Specify that the default location of the system-wide init file is
4128
     FILE.
4129
 
4130
   If GDB has been configured with the option `--prefix=$prefix', it
4131
may be subject to relocation.  Two possible cases:
4132
 
4133
   * If the default location of this init file contains `$prefix', it
4134
     will be subject to relocation.  Suppose that the configure options
4135
     are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
4136
     if GDB is moved from `$prefix' to `$install', the system init file
4137
     is looked for as `$install/etc/gdbinit' instead of
4138
     `$prefix/etc/gdbinit'.
4139
 
4140
   * By contrast, if the default location does not contain the prefix,
4141
     it will not be relocated.  E.g. if GDB has been configured with
4142
     `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
4143
     then GDB will always look for `/usr/share/gdb/gdbinit', wherever
4144
     GDB is installed.
4145
 
4146

4147
File: gdb.info,  Node: Maintenance Commands,  Next: Remote Protocol,  Prev: Installing GDB,  Up: Top
4148
 
4149
Appendix C Maintenance Commands
4150
*******************************
4151
 
4152
In addition to commands intended for GDB users, GDB includes a number
4153
of commands intended for GDB developers, that are not documented
4154
elsewhere in this manual.  These commands are provided here for
4155 342 jeremybenn
reference.  (For commands that turn on debugging messages, see *note
4156 330 jeremybenn
Debugging Output::.)
4157
 
4158
`maint agent EXPRESSION'
4159
`maint agent-eval EXPRESSION'
4160
     Translate the given EXPRESSION into remote agent bytecodes.  This
4161
     command is useful for debugging the Agent Expression mechanism
4162
     (*note Agent Expressions::).  The `agent' version produces an
4163
     expression useful for data collection, such as by tracepoints,
4164
     while `maint agent-eval' produces an expression that evaluates
4165
     directly to a result.  For instance, a collection expression for
4166
     `globa + globb' will include bytecodes to record four bytes of
4167
     memory at each of the addresses of `globa' and `globb', while
4168
     discarding the result of the addition, while an evaluation
4169
     expression will do the addition and return the sum.
4170
 
4171
`maint info breakpoints'
4172
     Using the same format as `info breakpoints', display both the
4173
     breakpoints you've set explicitly, and those GDB is using for
4174
     internal purposes.  Internal breakpoints are shown with negative
4175
     breakpoint numbers.  The type column identifies what kind of
4176
     breakpoint is shown:
4177
 
4178
    `breakpoint'
4179
          Normal, explicitly set breakpoint.
4180
 
4181
    `watchpoint'
4182
          Normal, explicitly set watchpoint.
4183
 
4184
    `longjmp'
4185
          Internal breakpoint, used to handle correctly stepping through
4186
          `longjmp' calls.
4187
 
4188
    `longjmp resume'
4189
          Internal breakpoint at the target of a `longjmp'.
4190
 
4191
    `until'
4192
          Temporary internal breakpoint used by the GDB `until' command.
4193
 
4194
    `finish'
4195
          Temporary internal breakpoint used by the GDB `finish'
4196
          command.
4197
 
4198
    `shlib events'
4199
          Shared library events.
4200
 
4201
 
4202
`set displaced-stepping'
4203
`show displaced-stepping'
4204
     Control whether or not GDB will do "displaced stepping" if the
4205
     target supports it.  Displaced stepping is a way to single-step
4206
     over breakpoints without removing them from the inferior, by
4207
     executing an out-of-line copy of the instruction that was
4208
     originally at the breakpoint location.  It is also known as
4209
     out-of-line single-stepping.
4210
 
4211
    `set displaced-stepping on'
4212
          If the target architecture supports it, GDB will use
4213
          displaced stepping to step over breakpoints.
4214
 
4215
    `set displaced-stepping off'
4216
          GDB will not use displaced stepping to step over breakpoints,
4217
          even if such is supported by the target architecture.
4218
 
4219
    `set displaced-stepping auto'
4220
          This is the default mode.  GDB will use displaced stepping
4221
          only if non-stop mode is active (*note Non-Stop Mode::) and
4222
          the target architecture supports displaced stepping.
4223
 
4224
`maint check-symtabs'
4225
     Check the consistency of psymtabs and symtabs.
4226
 
4227
`maint cplus first_component NAME'
4228
     Print the first C++ class/namespace component of NAME.
4229
 
4230
`maint cplus namespace'
4231
     Print the list of possible C++ namespaces.
4232
 
4233
`maint demangle NAME'
4234
     Demangle a C++ or Objective-C mangled NAME.
4235
 
4236
`maint deprecate COMMAND [REPLACEMENT]'
4237
`maint undeprecate COMMAND'
4238
     Deprecate or undeprecate the named COMMAND.  Deprecated commands
4239
     cause GDB to issue a warning when you use them.  The optional
4240
     argument REPLACEMENT says which newer command should be used in
4241
     favor of the deprecated one; if it is given, GDB will mention the
4242
     replacement as part of the warning.
4243
 
4244
`maint dump-me'
4245
     Cause a fatal signal in the debugger and force it to dump its core.
4246
     This is supported only on systems which support aborting a program
4247
     with the `SIGQUIT' signal.
4248
 
4249
`maint internal-error [MESSAGE-TEXT]'
4250
`maint internal-warning [MESSAGE-TEXT]'
4251
     Cause GDB to call the internal function `internal_error' or
4252
     `internal_warning' and hence behave as though an internal error or
4253
     internal warning has been detected.  In addition to reporting the
4254
     internal problem, these functions give the user the opportunity to
4255
     either quit GDB or create a core file of the current GDB session.
4256
 
4257
     These commands take an optional parameter MESSAGE-TEXT that is
4258
     used as the text of the error or warning message.
4259
 
4260
     Here's an example of using `internal-error':
4261
 
4262
          (gdb) maint internal-error testing, 1, 2
4263
          .../maint.c:121: internal-error: testing, 1, 2
4264
          A problem internal to GDB has been detected.  Further
4265
          debugging may prove unreliable.
4266
          Quit this debugging session? (y or n) n
4267
          Create a core file? (y or n) n
4268
          (gdb)
4269
 
4270
`maint set internal-error ACTION [ask|yes|no]'
4271
`maint show internal-error ACTION'
4272
`maint set internal-warning ACTION [ask|yes|no]'
4273
`maint show internal-warning ACTION'
4274
     When GDB reports an internal problem (error or warning) it gives
4275
     the user the opportunity to both quit GDB and create a core file
4276
     of the current GDB session.  These commands let you override the
4277
     default behaviour for each particular ACTION, described in the
4278
     table below.
4279
 
4280
    `quit'
4281
          You can specify that GDB should always (yes) or never (no)
4282
          quit.  The default is to ask the user what to do.
4283
 
4284
    `corefile'
4285
          You can specify that GDB should always (yes) or never (no)
4286
          create a core file.  The default is to ask the user what to
4287
          do.
4288
 
4289
`maint packet TEXT'
4290
     If GDB is talking to an inferior via the serial protocol, then
4291
     this command sends the string TEXT to the inferior, and displays
4292
     the response packet.  GDB supplies the initial `$' character, the
4293
     terminating `#' character, and the checksum.
4294
 
4295
`maint print architecture [FILE]'
4296
     Print the entire architecture configuration.  The optional argument
4297
     FILE names the file where the output goes.
4298
 
4299
`maint print c-tdesc'
4300
     Print the current target description (*note Target Descriptions::)
4301
     as a C source file.  The created source file can be used in GDB
4302
     when an XML parser is not available to parse the description.
4303
 
4304
`maint print dummy-frames'
4305
     Prints the contents of GDB's internal dummy-frame stack.
4306
 
4307
          (gdb) b add
4308
          ...
4309
          (gdb) print add(2,3)
4310
          Breakpoint 2, add (a=2, b=3) at ...
4311
          58      return (a + b);
4312
          The program being debugged stopped while in a function called from GDB.
4313
          ...
4314
          (gdb) maint print dummy-frames
4315
          0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
4316
           top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
4317
           call_lo=0x01014000 call_hi=0x01014001
4318
          (gdb)
4319
 
4320
     Takes an optional file parameter.
4321
 
4322
`maint print registers [FILE]'
4323
`maint print raw-registers [FILE]'
4324
`maint print cooked-registers [FILE]'
4325
`maint print register-groups [FILE]'
4326
     Print GDB's internal register data structures.
4327
 
4328
     The command `maint print raw-registers' includes the contents of
4329
     the raw register cache; the command `maint print cooked-registers'
4330
     includes the (cooked) value of all registers, including registers
4331
     which aren't available on the target nor visible to user; and the
4332
     command `maint print register-groups' includes the groups that each
4333
     register is a member of.  *Note Registers: (gdbint)Registers.
4334
 
4335
     These commands take an optional parameter, a file name to which to
4336
     write the information.
4337
 
4338
`maint print reggroups [FILE]'
4339
     Print GDB's internal register group data structures.  The optional
4340
     argument FILE tells to what file to write the information.
4341
 
4342
     The register groups info looks like this:
4343
 
4344
          (gdb) maint print reggroups
4345
           Group      Type
4346
           general    user
4347
           float      user
4348
           all        user
4349
           vector     user
4350
           system     user
4351
           save       internal
4352
           restore    internal
4353
 
4354
`flushregs'
4355
     This command forces GDB to flush its internal register cache.
4356
 
4357
`maint print objfiles'
4358
     Print a dump of all known object files.  For each object file, this
4359
     command prints its name, address in memory, and all of its psymtabs
4360
     and symtabs.
4361
 
4362
`maint print section-scripts [REGEXP]'
4363
     Print a dump of scripts specified in the `.debug_gdb_section'
4364
     section.  If REGEXP is specified, only print scripts loaded by
4365
     object files matching REGEXP.  For each script, this command
4366
     prints its name as specified in the objfile, and the full path if
4367
     known.  *Note .debug_gdb_scripts section::.
4368
 
4369
`maint print statistics'
4370
     This command prints, for each object file in the program, various
4371
     data about that object file followed by the byte cache ("bcache")
4372
     statistics for the object file.  The objfile data includes the
4373
     number of minimal, partial, full, and stabs symbols, the number of
4374
     types defined by the objfile, the number of as yet unexpanded psym
4375
     tables, the number of line tables and string tables, and the
4376
     amount of memory used by the various tables.  The bcache
4377
     statistics include the counts, sizes, and counts of duplicates of
4378
     all and unique objects, max, average, and median entry size, total
4379
     memory used and its overhead and savings, and various measures of
4380
     the hash table size and chain lengths.
4381
 
4382
`maint print target-stack'
4383
     A "target" is an interface between the debugger and a particular
4384
     kind of file or process.  Targets can be stacked in "strata", so
4385
     that more than one target can potentially respond to a request.
4386
     In particular, memory accesses will walk down the stack of targets
4387
     until they find a target that is interested in handling that
4388
     particular address.
4389
 
4390
     This command prints a short description of each layer that was
4391
     pushed on the "target stack", starting from the top layer down to
4392
     the bottom one.
4393
 
4394
`maint print type EXPR'
4395
     Print the type chain for a type specified by EXPR.  The argument
4396
     can be either a type name or a symbol.  If it is a symbol, the
4397
     type of that symbol is described.  The type chain produced by this
4398
     command is a recursive definition of the data type as stored in
4399
     GDB's data structures, including its flags and contained types.
4400
 
4401
`maint set dwarf2 always-disassemble'
4402
 
4403
`maint show dwarf2 always-disassemble'
4404
     Control the behavior of `info address' when using DWARF debugging
4405
     information.
4406
 
4407
     The default is `off', which means that GDB should try to describe
4408
     a variable's location in an easily readable format.  When `on',
4409
     GDB will instead display the DWARF location expression in an
4410
     assembly-like format.  Note that some locations are too complex
4411
     for GDB to describe simply; in this case you will always see the
4412
     disassembly form.
4413
 
4414
     Here is an example of the resulting disassembly:
4415
 
4416
          (gdb) info addr argc
4417
          Symbol "argc" is a complex DWARF expression:
4418
               1: DW_OP_fbreg 0
4419
 
4420
     For more information on these expressions, see the DWARF standard
4421
     (http://www.dwarfstd.org/).
4422
 
4423
`maint set dwarf2 max-cache-age'
4424
`maint show dwarf2 max-cache-age'
4425
     Control the DWARF 2 compilation unit cache.
4426
 
4427
     In object files with inter-compilation-unit references, such as
4428
     those produced by the GCC option `-feliminate-dwarf2-dups', the
4429
     DWARF 2 reader needs to frequently refer to previously read
4430
     compilation units.  This setting controls how long a compilation
4431
     unit will remain in the cache if it is not referenced.  A higher
4432
     limit means that cached compilation units will be stored in memory
4433
     longer, and more total memory will be used.  Setting it to zero
4434
     disables caching, which will slow down GDB startup, but reduce
4435
     memory consumption.
4436
 
4437
`maint set profile'
4438
`maint show profile'
4439
     Control profiling of GDB.
4440
 
4441
     Profiling will be disabled until you use the `maint set profile'
4442
     command to enable it.  When you enable profiling, the system will
4443
     begin collecting timing and execution count data; when you disable
4444
     profiling or exit GDB, the results will be written to a log file.
4445
     Remember that if you use profiling, GDB will overwrite the
4446
     profiling log file (often called `gmon.out').  If you have a
4447
     record of important profiling data in a `gmon.out' file, be sure
4448
     to move it to a safe location.
4449
 
4450
     Configuring with `--enable-profiling' arranges for GDB to be
4451
     compiled with the `-pg' compiler option.
4452
 
4453
`maint set show-debug-regs'
4454
`maint show show-debug-regs'
4455
     Control whether to show variables that mirror the hardware debug
4456
     registers.  Use `ON' to enable, `OFF' to disable.  If enabled, the
4457
     debug registers values are shown when GDB inserts or removes a
4458
     hardware breakpoint or watchpoint, and when the inferior triggers
4459
     a hardware-assisted breakpoint or watchpoint.
4460
 
4461
`maint set show-all-tib'
4462
`maint show show-all-tib'
4463
     Control whether to show all non zero areas within a 1k block
4464
     starting at thread local base, when using the `info w32
4465
     thread-information-block' command.
4466
 
4467
`maint space'
4468
     Control whether to display memory usage for each command.  If set
4469
     to a nonzero value, GDB will display how much memory each command
4470
     took, following the command's own output.  This can also be
4471
     requested by invoking GDB with the `--statistics' command-line
4472
     switch (*note Mode Options::).
4473
 
4474
`maint time'
4475
     Control whether to display the execution time for each command.  If
4476
     set to a nonzero value, GDB will display how much time it took to
4477
     execute each command, following the command's own output.  The
4478
     time is not printed for the commands that run the target, since
4479
     there's no mechanism currently to compute how much time was spend
4480
     by GDB and how much time was spend by the program been debugged.
4481
     it's not possibly currently This can also be requested by invoking
4482
     GDB with the `--statistics' command-line switch (*note Mode
4483
     Options::).
4484
 
4485
`maint translate-address [SECTION] ADDR'
4486
     Find the symbol stored at the location specified by the address
4487
     ADDR and an optional section name SECTION.  If found, GDB prints
4488
     the name of the closest symbol and an offset from the symbol's
4489
     location to the specified address.  This is similar to the `info
4490
     address' command (*note Symbols::), except that this command also
4491
     allows to find symbols in other sections.
4492
 
4493
     If section was not specified, the section in which the symbol was
4494
     found is also printed.  For dynamically linked executables, the
4495
     name of executable or shared library containing the symbol is
4496
     printed as well.
4497
 
4498
 
4499
   The following command is useful for non-interactive invocations of
4500
GDB, such as in the test suite.
4501
 
4502
`set watchdog NSEC'
4503
     Set the maximum number of seconds GDB will wait for the target
4504
     operation to finish.  If this time expires, GDB reports and error
4505
     and the command is aborted.
4506
 
4507
`show watchdog'
4508
     Show the current setting of the target wait timeout.
4509
 
4510

4511
File: gdb.info,  Node: Remote Protocol,  Next: Agent Expressions,  Prev: Maintenance Commands,  Up: Top
4512
 
4513
Appendix D GDB Remote Serial Protocol
4514
*************************************
4515
 
4516
* Menu:
4517
 
4518
* Overview::
4519
* Packets::
4520
* Stop Reply Packets::
4521
* General Query Packets::
4522
* Architecture-Specific Protocol Details::
4523
* Tracepoint Packets::
4524
* Host I/O Packets::
4525
* Interrupts::
4526
* Notification Packets::
4527
* Remote Non-Stop::
4528
* Packet Acknowledgment::
4529
* Examples::
4530
* File-I/O Remote Protocol Extension::
4531
* Library List Format::
4532
* Memory Map Format::
4533
* Thread List Format::
4534
 
4535

4536
File: gdb.info,  Node: Overview,  Next: Packets,  Up: Remote Protocol
4537
 
4538
D.1 Overview
4539
============
4540
 
4541
There may be occasions when you need to know something about the
4542
protocol--for example, if there is only one serial port to your target
4543
machine, you might want your program to do something special if it
4544
recognizes a packet meant for GDB.
4545
 
4546
   In the examples below, `->' and `<-' are used to indicate
4547
transmitted and received data, respectively.
4548
 
4549
   All GDB commands and responses (other than acknowledgments and
4550 342 jeremybenn
notifications, see *note Notification Packets::) are sent as a PACKET.
4551 330 jeremybenn
A PACKET is introduced with the character `$', the actual PACKET-DATA,
4552
and the terminating character `#' followed by a two-digit CHECKSUM:
4553
 
4554
     `$'PACKET-DATA`#'CHECKSUM
4555
   The two-digit CHECKSUM is computed as the modulo 256 sum of all
4556
characters between the leading `$' and the trailing `#' (an eight bit
4557
unsigned checksum).
4558
 
4559
   Implementors should note that prior to GDB 5.0 the protocol
4560
specification also included an optional two-digit SEQUENCE-ID:
4561
 
4562
     `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
4563
 
4564
That SEQUENCE-ID was appended to the acknowledgment.  GDB has never
4565
output SEQUENCE-IDs.  Stubs that handle packets added since GDB 5.0
4566
must not accept SEQUENCE-ID.
4567
 
4568
   When either the host or the target machine receives a packet, the
4569
first response expected is an acknowledgment: either `+' (to indicate
4570
the package was received correctly) or `-' (to request retransmission):
4571
 
4572
     -> `$'PACKET-DATA`#'CHECKSUM
4573
     <- `+'
4574
   The `+'/`-' acknowledgments can be disabled once a connection is
4575
established.  *Note Packet Acknowledgment::, for details.
4576
 
4577
   The host (GDB) sends COMMANDs, and the target (the debugging stub
4578
incorporated in your program) sends a RESPONSE.  In the case of step
4579
and continue COMMANDs, the response is only sent when the operation has
4580
completed, and the target has again stopped all threads in all attached
4581
processes.  This is the default all-stop mode behavior, but the remote
4582 342 jeremybenn
protocol also supports GDB's non-stop execution mode; see *note Remote
4583 330 jeremybenn
Non-Stop::, for details.
4584
 
4585
   PACKET-DATA consists of a sequence of characters with the exception
4586
of `#' and `$' (see `X' packet for additional exceptions).
4587
 
4588
   Fields within the packet should be separated using `,' `;' or `:'.
4589
Except where otherwise noted all numbers are represented in HEX with
4590
leading zeros suppressed.
4591
 
4592
   Implementors should note that prior to GDB 5.0, the character `:'
4593
could not appear as the third character in a packet (as it would
4594
potentially conflict with the SEQUENCE-ID).
4595
 
4596
   Binary data in most packets is encoded either as two hexadecimal
4597
digits per byte of binary data.  This allowed the traditional remote
4598
protocol to work over connections which were only seven-bit clean.
4599
Some packets designed more recently assume an eight-bit clean
4600
connection, and use a more efficient encoding to send and receive
4601
binary data.
4602
 
4603
   The binary data representation uses `7d' (ASCII `}') as an escape
4604
character.  Any escaped byte is transmitted as the escape character
4605
followed by the original character XORed with `0x20'.  For example, the
4606
byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'.  The
4607
bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
4608
must always be escaped.  Responses sent by the stub must also escape
4609
`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
4610
run-length encoded sequence (described next).
4611
 
4612
   Response DATA can be run-length encoded to save space.  Run-length
4613
encoding replaces runs of identical characters with one instance of the
4614
repeated character, followed by a `*' and a repeat count.  The repeat
4615
count is itself sent encoded, to avoid binary characters in DATA: a
4616
value of N is sent as `N+29'.  For a repeat count greater or equal to
4617
3, this produces a printable ASCII character, e.g. a space (ASCII code
4618
32) for a repeat count of 3.  (This is because run-length encoding
4619
starts to win for counts 3 or more.)  Thus, for example, `0* ' is a
4620
run-length encoding of "0000": the space character after `*' means
4621
repeat the leading `0' `32 - 29 = 3' more times.
4622
 
4623
   The printable characters `#' and `$' or with a numeric value greater
4624
than 126 must not be used.  Runs of six repeats (`#') or seven repeats
4625
(`$') can be expanded using a repeat count of only five (`"').  For
4626
example, `00000000' can be encoded as `0*"00'.
4627
 
4628
   The error response returned for some packets includes a two character
4629
error number.  That number is not well defined.
4630
 
4631
   For any COMMAND not supported by the stub, an empty response
4632
(`$#00') should be returned.  That way it is possible to extend the
4633
protocol.  A newer GDB can tell if a packet is supported based on that
4634
response.
4635
 
4636
   A stub is required to support the `g', `G', `m', `M', `c', and `s'
4637
COMMANDs.  All other COMMANDs are optional.
4638
 
4639

4640
File: gdb.info,  Node: Packets,  Next: Stop Reply Packets,  Prev: Overview,  Up: Remote Protocol
4641
 
4642
D.2 Packets
4643
===========
4644
 
4645
The following table provides a complete list of all currently defined
4646
COMMANDs and their corresponding response DATA.  *Note File-I/O Remote
4647
Protocol Extension::, for details about the File I/O extension of the
4648
remote protocol.
4649
 
4650
   Each packet's description has a template showing the packet's overall
4651
syntax, followed by an explanation of the packet's meaning.  We include
4652
spaces in some of the templates for clarity; these are not part of the
4653
packet's syntax.  No GDB packet uses spaces to separate its components.
4654 342 jeremybenn
For example, a template like `foo BAR BAZ' describes a packet beginning
4655
with the three ASCII bytes `foo', followed by a BAR, followed directly
4656
by a BAZ.  GDB does not transmit a space character between the `foo'
4657
and the BAR, or between the BAR and the BAZ.
4658 330 jeremybenn
 
4659
   Several packets and replies include a THREAD-ID field to identify a
4660
thread.  Normally these are positive numbers with a target-specific
4661
interpretation, formatted as big-endian hex strings.  A THREAD-ID can
4662
also be a literal `-1' to indicate all threads, or `0' to pick any
4663
thread.
4664
 
4665
   In addition, the remote protocol supports a multiprocess feature in
4666
which the THREAD-ID syntax is extended to optionally include both
4667
process and thread ID fields, as `pPID.TID'.  The PID (process) and TID
4668
(thread) components each have the format described above: a positive
4669
number with target-specific interpretation formatted as a big-endian
4670
hex string, literal `-1' to indicate all processes or threads
4671
(respectively), or `0' to indicate an arbitrary process or thread.
4672
Specifying just a process, as `pPID', is equivalent to `pPID.-1'.  It
4673
is an error to specify all processes but a specific thread, such as
4674
`p-1.TID'.  Note that the `p' prefix is _not_ used for those packets
4675
and replies explicitly documented to include a process ID, rather than
4676
a THREAD-ID.
4677
 
4678
   The multiprocess THREAD-ID syntax extensions are only used if both
4679
GDB and the stub report support for the `multiprocess' feature using
4680
`qSupported'.  *Note multiprocess extensions::, for more information.
4681
 
4682
   Note that all packet forms beginning with an upper- or lower-case
4683
letter, other than those described here, are reserved for future use.
4684
 
4685
   Here are the packet descriptions.
4686
 
4687
`!'
4688
     Enable extended mode.  In extended mode, the remote server is made
4689
     persistent.  The `R' packet is used to restart the program being
4690
     debugged.
4691
 
4692
     Reply:
4693
    `OK'
4694
          The remote target both supports and has enabled extended mode.
4695
 
4696
`?'
4697
     Indicate the reason the target halted.  The reply is the same as
4698
     for step and continue.  This packet has a special interpretation
4699 342 jeremybenn
     when the target is in non-stop mode; see *note Remote Non-Stop::.
4700 330 jeremybenn
 
4701
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4702
 
4703
`A ARGLEN,ARGNUM,ARG,...'
4704
     Initialized `argv[]' array passed into program. ARGLEN specifies
4705
     the number of bytes in the hex encoded byte stream ARG.  See
4706
     `gdbserver' for more details.
4707
 
4708
     Reply:
4709
    `OK'
4710
          The arguments were set.
4711
 
4712
    `E NN'
4713
          An error occurred.
4714
 
4715
`b BAUD'
4716
     (Don't use this packet; its behavior is not well-defined.)  Change
4717
     the serial line speed to BAUD.
4718
 
4719
     JTC: _When does the transport layer state change?  When it's
4720
     received, or after the ACK is transmitted.  In either case, there
4721
     are problems if the command or the acknowledgment packet is
4722
     dropped._
4723
 
4724
     Stan: _If people really wanted to add something like this, and get
4725
     it working for the first time, they ought to modify ser-unix.c to
4726
     send some kind of out-of-band message to a specially-setup stub
4727
     and have the switch happen "in between" packets, so that from
4728
     remote protocol's point of view, nothing actually happened._
4729
 
4730
`B ADDR,MODE'
4731
     Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
4732
 
4733
     Don't use this packet.  Use the `Z' and `z' packets instead (*note
4734
     insert breakpoint or watchpoint packet::).
4735
 
4736
`bc'
4737
     Backward continue.  Execute the target system in reverse.  No
4738
     parameter.  *Note Reverse Execution::, for more information.
4739
 
4740
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4741
 
4742
`bs'
4743
     Backward single step.  Execute one instruction in reverse.  No
4744
     parameter.  *Note Reverse Execution::, for more information.
4745
 
4746
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4747
 
4748
`c [ADDR]'
4749
     Continue.  ADDR is address to resume.  If ADDR is omitted, resume
4750
     at current address.
4751
 
4752
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4753
 
4754
`C SIG[;ADDR]'
4755
     Continue with signal SIG (hex signal number).  If `;ADDR' is
4756
     omitted, resume at same address.
4757
 
4758
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4759
 
4760
`d'
4761
     Toggle debug flag.
4762
 
4763
     Don't use this packet; instead, define a general set packet (*note
4764
     General Query Packets::).
4765
 
4766
`D'
4767
`D;PID'
4768
     The first form of the packet is used to detach GDB from the remote
4769
     system.  It is sent to the remote target before GDB disconnects
4770
     via the `detach' command.
4771
 
4772
     The second form, including a process ID, is used when multiprocess
4773
     protocol extensions are enabled (*note multiprocess extensions::),
4774
     to detach only a specific process.  The PID is specified as a
4775
     big-endian hex string.
4776
 
4777
     Reply:
4778
    `OK'
4779
          for success
4780
 
4781
    `E NN'
4782
          for an error
4783
 
4784
`F RC,EE,CF;XX'
4785
     A reply from GDB to an `F' packet sent by the target.  This is
4786
     part of the File-I/O protocol extension.  *Note File-I/O Remote
4787
     Protocol Extension::, for the specification.
4788
 
4789
`g'
4790
     Read general registers.
4791
 
4792
     Reply:
4793
    `XX...'
4794
          Each byte of register data is described by two hex digits.
4795
          The bytes with the register are transmitted in target byte
4796
          order.  The size of each register and their position within
4797
          the `g' packet are determined by the GDB internal gdbarch
4798
          functions `DEPRECATED_REGISTER_RAW_SIZE' and
4799
          `gdbarch_register_name'.  The specification of several
4800
          standard `g' packets is specified below.
4801
 
4802
    `E NN'
4803
          for an error.
4804
 
4805
`G XX...'
4806
     Write general registers.  *Note read registers packet::, for a
4807
     description of the XX... data.
4808
 
4809
     Reply:
4810
    `OK'
4811
          for success
4812
 
4813
    `E NN'
4814
          for an error
4815
 
4816
`H C THREAD-ID'
4817
     Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
4818
     C depends on the operation to be performed: it should be `c' for
4819
     step and continue operations, `g' for other operations.  The
4820
     thread designator THREAD-ID has the format and interpretation
4821 342 jeremybenn
     described in *note thread-id syntax::.
4822 330 jeremybenn
 
4823
     Reply:
4824
    `OK'
4825
          for success
4826
 
4827
    `E NN'
4828
          for an error
4829
 
4830
`i [ADDR[,NNN]]'
4831
     Step the remote target by a single clock cycle.  If `,NNN' is
4832
     present, cycle step NNN cycles.  If ADDR is present, cycle step
4833
     starting at that address.
4834
 
4835
`I'
4836
     Signal, then cycle step.  *Note step with signal packet::.  *Note
4837
     cycle step packet::.
4838
 
4839
`k'
4840
     Kill request.
4841
 
4842
     FIXME: _There is no description of how to operate when a specific
4843
     thread context has been selected (i.e. does 'k' kill only that
4844
     thread?)_.
4845
 
4846
`m ADDR,LENGTH'
4847
     Read LENGTH bytes of memory starting at address ADDR.  Note that
4848
     ADDR may not be aligned to any particular boundary.
4849
 
4850
     The stub need not use any particular size or alignment when
4851
     gathering data from memory for the response; even if ADDR is
4852
     word-aligned and LENGTH is a multiple of the word size, the stub
4853
     is free to use byte accesses, or not.  For this reason, this
4854
     packet may not be suitable for accessing memory-mapped I/O devices.
4855
 
4856
     Reply:
4857
    `XX...'
4858
          Memory contents; each byte is transmitted as a two-digit
4859
          hexadecimal number.  The reply may contain fewer bytes than
4860
          requested if the server was able to read only part of the
4861
          region of memory.
4862
 
4863
    `E NN'
4864
          NN is errno
4865
 
4866
`M ADDR,LENGTH:XX...'
4867
     Write LENGTH bytes of memory starting at address ADDR.  XX... is
4868
     the data; each byte is transmitted as a two-digit hexadecimal
4869
     number.
4870
 
4871
     Reply:
4872
    `OK'
4873
          for success
4874
 
4875
    `E NN'
4876
          for an error (this includes the case where only part of the
4877
          data was written).
4878
 
4879
`p N'
4880
     Read the value of register N; N is in hex.  *Note read registers
4881
     packet::, for a description of how the returned register value is
4882
     encoded.
4883
 
4884
     Reply:
4885
    `XX...'
4886
          the register's value
4887
 
4888
    `E NN'
4889
          for an error
4890
 
4891
    `'
4892
          Indicating an unrecognized QUERY.
4893
 
4894
`P N...=R...'
4895
     Write register N... with value R....  The register number N is in
4896
     hexadecimal, and R... contains two hex digits for each byte in the
4897
     register (target byte order).
4898
 
4899
     Reply:
4900
    `OK'
4901
          for success
4902
 
4903
    `E NN'
4904
          for an error
4905
 
4906
`q NAME PARAMS...'
4907
`Q NAME PARAMS...'
4908
     General query (`q') and set (`Q').  These packets are described
4909 342 jeremybenn
     fully in *note General Query Packets::.
4910 330 jeremybenn
 
4911
`r'
4912
     Reset the entire system.
4913
 
4914
     Don't use this packet; use the `R' packet instead.
4915
 
4916
`R XX'
4917
     Restart the program being debugged.  XX, while needed, is ignored.
4918
     This packet is only available in extended mode (*note extended
4919
     mode::).
4920
 
4921
     The `R' packet has no reply.
4922
 
4923
`s [ADDR]'
4924
     Single step.  ADDR is the address at which to resume.  If ADDR is
4925
     omitted, resume at same address.
4926
 
4927
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4928
 
4929
`S SIG[;ADDR]'
4930
     Step with signal.  This is analogous to the `C' packet, but
4931
     requests a single-step, rather than a normal resumption of
4932
     execution.
4933
 
4934
     Reply: *Note Stop Reply Packets::, for the reply specifications.
4935
 
4936
`t ADDR:PP,MM'
4937
     Search backwards starting at address ADDR for a match with pattern
4938
     PP and mask MM.  PP and MM are 4 bytes.  ADDR must be at least 3
4939
     digits.
4940
 
4941
`T THREAD-ID'
4942
     Find out if the thread THREAD-ID is alive.  *Note thread-id
4943
     syntax::.
4944
 
4945
     Reply:
4946
    `OK'
4947
          thread is still alive
4948
 
4949
    `E NN'
4950
          thread is dead
4951
 
4952
`v'
4953
     Packets starting with `v' are identified by a multi-letter name,
4954
     up to the first `;' or `?' (or the end of the packet).
4955
 
4956
`vAttach;PID'
4957
     Attach to a new process with the specified process ID PID.  The
4958
     process ID is a hexadecimal integer identifying the process.  In
4959
     all-stop mode, all threads in the attached process are stopped; in
4960
     non-stop mode, it may be attached without being stopped if that is
4961
     supported by the target.
4962
 
4963
     This packet is only available in extended mode (*note extended
4964
     mode::).
4965
 
4966
     Reply:
4967
    `E NN'
4968
          for an error
4969
 
4970
    `Any stop packet'
4971
          for success in all-stop mode (*note Stop Reply Packets::)
4972
 
4973
    `OK'
4974
          for success in non-stop mode (*note Remote Non-Stop::)
4975
 
4976
`vCont[;ACTION[:THREAD-ID]]...'
4977
     Resume the inferior, specifying different actions for each thread.
4978
     If an action is specified with no THREAD-ID, then it is applied to
4979
     any threads that don't have a specific action specified; if no
4980
     default action is specified then other threads should remain
4981
     stopped in all-stop mode and in their current state in non-stop
4982
     mode.  Specifying multiple default actions is an error; specifying
4983
     no actions is also an error.  Thread IDs are specified using the
4984 342 jeremybenn
     syntax described in *note thread-id syntax::.
4985 330 jeremybenn
 
4986
     Currently supported actions are:
4987
 
4988
    `c'
4989
          Continue.
4990
 
4991
    `C SIG'
4992
          Continue with signal SIG.  The signal SIG should be two hex
4993
          digits.
4994
 
4995
    `s'
4996
          Step.
4997
 
4998
    `S SIG'
4999
          Step with signal SIG.  The signal SIG should be two hex
5000
          digits.
5001
 
5002
    `t'
5003
          Stop.
5004
 
5005
     The optional argument ADDR normally associated with the `c', `C',
5006
     `s', and `S' packets is not supported in `vCont'.
5007
 
5008
     The `t' action is only relevant in non-stop mode (*note Remote
5009
     Non-Stop::) and may be ignored by the stub otherwise.  A stop
5010
     reply should be generated for any affected thread not already
5011
     stopped.  When a thread is stopped by means of a `t' action, the
5012
     corresponding stop reply should indicate that the thread has
5013
     stopped with signal `0', regardless of whether the target uses
5014
     some other signal as an implementation detail.
5015
 
5016
     Reply: *Note Stop Reply Packets::, for the reply specifications.
5017
 
5018
`vCont?'
5019
     Request a list of actions supported by the `vCont' packet.
5020
 
5021
     Reply:
5022
    `vCont[;ACTION...]'
5023
          The `vCont' packet is supported.  Each ACTION is a supported
5024
          command in the `vCont' packet.
5025
 
5026
    `'
5027
          The `vCont' packet is not supported.
5028
 
5029
`vFile:OPERATION:PARAMETER...'
5030
     Perform a file operation on the target system.  For details, see
5031 342 jeremybenn
     *note Host I/O Packets::.
5032 330 jeremybenn
 
5033
`vFlashErase:ADDR,LENGTH'
5034
     Direct the stub to erase LENGTH bytes of flash starting at ADDR.
5035
     The region may enclose any number of flash blocks, but its start
5036
     and end must fall on block boundaries, as indicated by the flash
5037
     block size appearing in the memory map (*note Memory Map
5038
     Format::).  GDB groups flash memory programming operations
5039
     together, and sends a `vFlashDone' request after each group; the
5040
     stub is allowed to delay erase operation until the `vFlashDone'
5041
     packet is received.
5042
 
5043
     The stub must support `vCont' if it reports support for
5044
     multiprocess extensions (*note multiprocess extensions::).  Note
5045
     that in this case `vCont' actions can be specified to apply to all
5046
     threads in a process by using the `pPID.-1' form of the THREAD-ID.
5047
 
5048
     Reply:
5049
    `OK'
5050
          for success
5051
 
5052
    `E NN'
5053
          for an error
5054
 
5055
`vFlashWrite:ADDR:XX...'
5056
     Direct the stub to write data to flash address ADDR.  The data is
5057
     passed in binary form using the same encoding as for the `X'
5058
     packet (*note Binary Data::).  The memory ranges specified by
5059
     `vFlashWrite' packets preceding a `vFlashDone' packet must not
5060
     overlap, and must appear in order of increasing addresses
5061
     (although `vFlashErase' packets for higher addresses may already
5062
     have been received; the ordering is guaranteed only between
5063
     `vFlashWrite' packets).  If a packet writes to an address that was
5064
     neither erased by a preceding `vFlashErase' packet nor by some
5065
     other target-specific method, the results are unpredictable.
5066
 
5067
     Reply:
5068
    `OK'
5069
          for success
5070
 
5071
    `E.memtype'
5072
          for vFlashWrite addressing non-flash memory
5073
 
5074
    `E NN'
5075
          for an error
5076
 
5077
`vFlashDone'
5078
     Indicate to the stub that flash programming operation is finished.
5079
     The stub is permitted to delay or batch the effects of a group of
5080
     `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
5081
     packet is received.  The contents of the affected regions of flash
5082
     memory are unpredictable until the `vFlashDone' request is
5083
     completed.
5084
 
5085
`vKill;PID'
5086
     Kill the process with the specified process ID.  PID is a
5087
     hexadecimal integer identifying the process.  This packet is used
5088
     in preference to `k' when multiprocess protocol extensions are
5089 342 jeremybenn
     supported; see *note multiprocess extensions::.
5090 330 jeremybenn
 
5091
     Reply:
5092
    `E NN'
5093
          for an error
5094
 
5095
    `OK'
5096
          for success
5097
 
5098
`vRun;FILENAME[;ARGUMENT]...'
5099
     Run the program FILENAME, passing it each ARGUMENT on its command
5100
     line.  The file and arguments are hex-encoded strings.  If
5101
     FILENAME is an empty string, the stub may use a default program
5102
     (e.g. the last program run).  The program is created in the stopped
5103
     state.
5104
 
5105
     This packet is only available in extended mode (*note extended
5106
     mode::).
5107
 
5108
     Reply:
5109
    `E NN'
5110
          for an error
5111
 
5112
    `Any stop packet'
5113
          for success (*note Stop Reply Packets::)
5114
 
5115
`vStopped'
5116
     In non-stop mode (*note Remote Non-Stop::), acknowledge a previous
5117
     stop reply and prompt for the stub to report another one.
5118
 
5119
     Reply:
5120
    `Any stop packet'
5121
          if there is another unreported stop event (*note Stop Reply
5122
          Packets::)
5123
 
5124
    `OK'
5125
          if there are no unreported stop events
5126
 
5127
`X ADDR,LENGTH:XX...'
5128
     Write data to memory, where the data is transmitted in binary.
5129
     ADDR is address, LENGTH is number of bytes, `XX...' is binary data
5130
     (*note Binary Data::).
5131
 
5132
     Reply:
5133
    `OK'
5134
          for success
5135
 
5136
    `E NN'
5137
          for an error
5138
 
5139
`z TYPE,ADDR,KIND'
5140
`Z TYPE,ADDR,KIND'
5141
     Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
5142
     starting at address ADDRESS of kind KIND.
5143
 
5144
     Each breakpoint and watchpoint packet TYPE is documented
5145
     separately.
5146
 
5147
     _Implementation notes: A remote target shall return an empty string
5148
     for an unrecognized breakpoint or watchpoint packet TYPE.  A
5149
     remote target shall support either both or neither of a given
5150
     `ZTYPE...' and `zTYPE...' packet pair.  To avoid potential
5151
     problems with duplicate packets, the operations should be
5152
     implemented in an idempotent way._
5153
 
5154
`z0,ADDR,KIND'
5155
`Z0,ADDR,KIND'
5156
     Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
5157
     of type KIND.
5158
 
5159
     A memory breakpoint is implemented by replacing the instruction at
5160
     ADDR with a software breakpoint or trap instruction.  The KIND is
5161
     target-specific and typically indicates the size of the breakpoint
5162
     in bytes that should be inserted.  E.g., the ARM and MIPS can
5163
     insert either a 2 or 4 byte breakpoint.  Some architectures have
5164 342 jeremybenn
     additional meanings for KIND; see *note Architecture-Specific
5165 330 jeremybenn
     Protocol Details::.
5166
 
5167
     _Implementation note: It is possible for a target to copy or move
5168
     code that contains memory breakpoints (e.g., when implementing
5169
     overlays).  The behavior of this packet, in the presence of such a
5170
     target, is not defined._
5171
 
5172
     Reply:
5173
    `OK'
5174
          success
5175
 
5176
    `'
5177
          not supported
5178
 
5179
    `E NN'
5180
          for an error
5181
 
5182
`z1,ADDR,KIND'
5183
`Z1,ADDR,KIND'
5184
     Insert (`Z1') or remove (`z1') a hardware breakpoint at address
5185
     ADDR.
5186
 
5187
     A hardware breakpoint is implemented using a mechanism that is not
5188
     dependant on being able to modify the target's memory.  KIND has
5189
     the same meaning as in `Z0' packets.
5190
 
5191
     _Implementation note: A hardware breakpoint is not affected by code
5192
     movement._
5193
 
5194
     Reply:
5195
    `OK'
5196
          success
5197
 
5198
    `'
5199
          not supported
5200
 
5201
    `E NN'
5202
          for an error
5203
 
5204
`z2,ADDR,KIND'
5205
`Z2,ADDR,KIND'
5206
     Insert (`Z2') or remove (`z2') a write watchpoint at ADDR.  KIND
5207
     is interpreted as the number of bytes to watch.
5208
 
5209
     Reply:
5210
    `OK'
5211
          success
5212
 
5213
    `'
5214
          not supported
5215
 
5216
    `E NN'
5217
          for an error
5218
 
5219
`z3,ADDR,KIND'
5220
`Z3,ADDR,KIND'
5221
     Insert (`Z3') or remove (`z3') a read watchpoint at ADDR.  KIND is
5222
     interpreted as the number of bytes to watch.
5223
 
5224
     Reply:
5225
    `OK'
5226
          success
5227
 
5228
    `'
5229
          not supported
5230
 
5231
    `E NN'
5232
          for an error
5233
 
5234
`z4,ADDR,KIND'
5235
`Z4,ADDR,KIND'
5236
     Insert (`Z4') or remove (`z4') an access watchpoint at ADDR.  KIND
5237
     is interpreted as the number of bytes to watch.
5238
 
5239
     Reply:
5240
    `OK'
5241
          success
5242
 
5243
    `'
5244
          not supported
5245
 
5246
    `E NN'
5247
          for an error
5248
 
5249
 
5250

5251
File: gdb.info,  Node: Stop Reply Packets,  Next: General Query Packets,  Prev: Packets,  Up: Remote Protocol
5252
 
5253
D.3 Stop Reply Packets
5254
======================
5255
 
5256
The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
5257
packets can receive any of the below as a reply.  Except for `?' and
5258
`vStopped', that reply is only returned when the target halts.  In the
5259
below the exact meaning of "signal number" is defined by the header
5260
`include/gdb/signals.h' in the GDB source code.
5261
 
5262
   As in the description of request packets, we include spaces in the
5263
reply templates for clarity; these are not part of the reply packet's
5264
syntax.  No GDB stop reply packet uses spaces to separate its
5265
components.
5266
 
5267
`S AA'
5268
     The program received signal number AA (a two-digit hexadecimal
5269
     number).  This is equivalent to a `T' response with no N:R pairs.
5270
 
5271
`T AA N1:R1;N2:R2;...'
5272
     The program received signal number AA (a two-digit hexadecimal
5273
     number).  This is equivalent to an `S' response, except that the
5274
     `N:R' pairs can carry values of important registers and other
5275
     information directly in the stop reply packet, reducing round-trip
5276
     latency.  Single-step and breakpoint traps are reported this way.
5277
     Each `N:R' pair is interpreted as follows:
5278
 
5279
        * If N is a hexadecimal number, it is a register number, and the
5280
          corresponding R gives that register's value.  R is a series
5281
          of bytes in target byte order, with each byte given by a
5282
          two-digit hex number.
5283
 
5284
        * If N is `thread', then R is the THREAD-ID of the stopped
5285 342 jeremybenn
          thread, as specified in *note thread-id syntax::.
5286 330 jeremybenn
 
5287
        * If N is `core', then R is the hexadecimal number of the core
5288
          on which the stop event was detected.
5289
 
5290
        * If N is a recognized "stop reason", it describes a more
5291
          specific event that stopped the target.  The currently
5292
          defined stop reasons are listed below.  AA should be `05',
5293
          the trap signal.  At most one stop reason should be present.
5294
 
5295
        * Otherwise, GDB should ignore this `N:R' pair and go on to the
5296
          next; this allows us to extend the protocol in the future.
5297
 
5298
     The currently defined stop reasons are:
5299
 
5300
    `watch'
5301
    `rwatch'
5302
    `awatch'
5303
          The packet indicates a watchpoint hit, and R is the data
5304
          address, in hex.
5305
 
5306
    `library'
5307
          The packet indicates that the loaded libraries have changed.
5308
          GDB should use `qXfer:libraries:read' to fetch a new list of
5309
          loaded libraries.  R is ignored.
5310
 
5311
    `replaylog'
5312
          The packet indicates that the target cannot continue replaying
5313
          logged execution events, because it has reached the end (or
5314
          the beginning when executing backward) of the log.  The value
5315
          of R will be either `begin' or `end'.  *Note Reverse
5316
          Execution::, for more information.
5317
 
5318
`W AA'
5319
`W AA ; process:PID'
5320
     The process exited, and AA is the exit status.  This is only
5321
     applicable to certain targets.
5322
 
5323
     The second form of the response, including the process ID of the
5324
     exited process, can be used only when GDB has reported support for
5325 342 jeremybenn
     multiprocess protocol extensions; see *note multiprocess
5326 330 jeremybenn
     extensions::.  The PID is formatted as a big-endian hex string.
5327
 
5328
`X AA'
5329
`X AA ; process:PID'
5330
     The process terminated with signal AA.
5331
 
5332
     The second form of the response, including the process ID of the
5333
     terminated process, can be used only when GDB has reported support
5334 342 jeremybenn
     for multiprocess protocol extensions; see *note multiprocess
5335 330 jeremybenn
     extensions::.  The PID is formatted as a big-endian hex string.
5336
 
5337
`O XX...'
5338
     `XX...' is hex encoding of ASCII data, to be written as the
5339
     program's console output.  This can happen at any time while the
5340
     program is running and the debugger should continue to wait for
5341
     `W', `T', etc.  This reply is not permitted in non-stop mode.
5342
 
5343
`F CALL-ID,PARAMETER...'
5344
     CALL-ID is the identifier which says which host system call should
5345
     be called.  This is just the name of the function.  Translation
5346
     into the correct system call is only applicable as it's defined in
5347
     GDB.  *Note File-I/O Remote Protocol Extension::, for a list of
5348
     implemented system calls.
5349
 
5350
     `PARAMETER...' is a list of parameters as defined for this very
5351
     system call.
5352
 
5353
     The target replies with this packet when it expects GDB to call a
5354
     host system call on behalf of the target.  GDB replies with an
5355
     appropriate `F' packet and keeps up waiting for the next reply
5356
     packet from the target.  The latest `C', `c', `S' or `s' action is
5357
     expected to be continued.  *Note File-I/O Remote Protocol
5358
     Extension::, for more details.
5359
 
5360
 
5361

5362
File: gdb.info,  Node: General Query Packets,  Next: Architecture-Specific Protocol Details,  Prev: Stop Reply Packets,  Up: Remote Protocol
5363
 
5364
D.4 General Query Packets
5365
=========================
5366
 
5367
Packets starting with `q' are "general query packets"; packets starting
5368
with `Q' are "general set packets".  General query and set packets are
5369
a semi-unified form for retrieving and sending information to and from
5370
the stub.
5371
 
5372
   The initial letter of a query or set packet is followed by a name
5373
indicating what sort of thing the packet applies to.  For example, GDB
5374
may use a `qSymbol' packet to exchange symbol definitions with the
5375
stub.  These packet names follow some conventions:
5376
 
5377
   * The name must not contain commas, colons or semicolons.
5378
 
5379
   * Most GDB query and set packets have a leading upper case letter.
5380
 
5381
   * The names of custom vendor packets should use a company prefix, in
5382
     lower case, followed by a period.  For example, packets designed at
5383
     the Acme Corporation might begin with `qacme.foo' (for querying
5384
     foos) or `Qacme.bar' (for setting bars).
5385
 
5386
   The name of a query or set packet should be separated from any
5387
parameters by a `:'; the parameters themselves should be separated by
5388
`,' or `;'.  Stubs must be careful to match the full packet name, and
5389
check for a separator or the end of the packet, in case two packet
5390
names share a common prefix.  New packets should not begin with `qC',
5391
`qP', or `qL'(1).
5392
 
5393
   Like the descriptions of the other packets, each description here
5394
has a template showing the packet's overall syntax, followed by an
5395
explanation of the packet's meaning.  We include spaces in some of the
5396
templates for clarity; these are not part of the packet's syntax.  No
5397
GDB packet uses spaces to separate its components.
5398
 
5399
   Here are the currently defined query and set packets:
5400
 
5401
`QAllow:OP:VAL...'
5402
     Specify which operations GDB expects to request of the target, as
5403
     a semicolon-separated list of operation name and value pairs.
5404
     Possible values for OP include `WriteReg', `WriteMem',
5405
     `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL
5406
     is either 0, indicating that GDB will not request the operation,
5407
     or 1, indicating that it may.  (The target can then use this to
5408
     set up its own internals optimally, for instance if the debugger
5409
     never expects to insert breakpoints, it may not need to install
5410
     its own trap handler.)
5411
 
5412
`qC'
5413
     Return the current thread ID.
5414
 
5415
     Reply:
5416
    `QC THREAD-ID'
5417 342 jeremybenn
          Where THREAD-ID is a thread ID as documented in *note
5418 330 jeremybenn
          thread-id syntax::.
5419
 
5420
    `(anything else)'
5421
          Any other reply implies the old thread ID.
5422
 
5423
`qCRC:ADDR,LENGTH'
5424
     Compute the CRC checksum of a block of memory using CRC-32 defined
5425
     in IEEE 802.3.  The CRC is computed byte at a time, taking the most
5426
     significant bit of each byte first.  The initial pattern code
5427
     `0xffffffff' is used to ensure leading zeros affect the CRC.
5428
 
5429
     _Note:_ This is the same CRC used in validating separate debug
5430
     files (*note Debugging Information in Separate Files: Separate
5431
     Debug Files.).  However the algorithm is slightly different.  When
5432
     validating separate debug files, the CRC is computed taking the
5433
     _least_ significant bit of each byte first, and the final result
5434
     is inverted to detect trailing zeros.
5435
 
5436
     Reply:
5437
    `E NN'
5438
          An error (such as memory fault)
5439
 
5440
    `C CRC32'
5441
          The specified memory region's checksum is CRC32.
5442
 
5443
`qfThreadInfo'
5444
`qsThreadInfo'
5445
     Obtain a list of all active thread IDs from the target (OS).
5446
     Since there may be too many active threads to fit into one reply
5447
     packet, this query works iteratively: it may require more than one
5448
     query/reply sequence to obtain the entire list of threads.  The
5449
     first query of the sequence will be the `qfThreadInfo' query;
5450
     subsequent queries in the sequence will be the `qsThreadInfo'
5451
     query.
5452
 
5453
     NOTE: This packet replaces the `qL' query (see below).
5454
 
5455
     Reply:
5456
    `m THREAD-ID'
5457
          A single thread ID
5458
 
5459
    `m THREAD-ID,THREAD-ID...'
5460
          a comma-separated list of thread IDs
5461
 
5462
    `l'
5463
          (lower case letter `L') denotes end of list.
5464
 
5465
     In response to each query, the target will reply with a list of
5466
     one or more thread IDs, separated by commas.  GDB will respond to
5467
     each reply with a request for more thread ids (using the `qs' form
5468
     of the query), until the target responds with `l' (lower-case ell,
5469 342 jeremybenn
     for "last").  Refer to *note thread-id syntax::, for the format of
5470 330 jeremybenn
     the THREAD-ID fields.
5471
 
5472
`qGetTLSAddr:THREAD-ID,OFFSET,LM'
5473
     Fetch the address associated with thread local storage specified
5474
     by THREAD-ID, OFFSET, and LM.
5475
 
5476
     THREAD-ID is the thread ID associated with the thread for which to
5477
     fetch the TLS address.  *Note thread-id syntax::.
5478
 
5479
     OFFSET is the (big endian, hex encoded) offset associated with the
5480
     thread local variable.  (This offset is obtained from the debug
5481
     information associated with the variable.)
5482
 
5483
     LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
5484
     the load module associated with the thread local storage.  For
5485
     example, a GNU/Linux system will pass the link map address of the
5486
     shared object associated with the thread local storage under
5487
     consideration.  Other operating environments may choose to
5488
     represent the load module differently, so the precise meaning of
5489
     this parameter will vary.
5490
 
5491
     Reply:
5492
    `XX...'
5493
          Hex encoded (big endian) bytes representing the address of
5494
          the thread local storage requested.
5495
 
5496
    `E NN'
5497
          An error occurred.  NN are hex digits.
5498
 
5499
    `'
5500
          An empty reply indicates that `qGetTLSAddr' is not supported
5501
          by the stub.
5502
 
5503
`qGetTIBAddr:THREAD-ID'
5504
     Fetch address of the Windows OS specific Thread Information Block.
5505
 
5506
     THREAD-ID is the thread ID associated with the thread.
5507
 
5508
     Reply:
5509
    `XX...'
5510
          Hex encoded (big endian) bytes representing the linear
5511
          address of the thread information block.
5512
 
5513
    `E NN'
5514
          An error occured.  This means that either the thread was not
5515
          found, or the address could not be retrieved.
5516
 
5517
    `'
5518
          An empty reply indicates that `qGetTIBAddr' is not supported
5519
          by the stub.
5520
 
5521
`qL STARTFLAG THREADCOUNT NEXTTHREAD'
5522
     Obtain thread information from RTOS.  Where: STARTFLAG (one hex
5523
     digit) is one to indicate the first query and zero to indicate a
5524
     subsequent query; THREADCOUNT (two hex digits) is the maximum
5525
     number of threads the response packet can contain; and NEXTTHREAD
5526
     (eight hex digits), for subsequent queries (STARTFLAG is zero), is
5527
     returned in the response as ARGTHREAD.
5528
 
5529
     Don't use this packet; use the `qfThreadInfo' query instead (see
5530
     above).
5531
 
5532
     Reply:
5533
    `qM COUNT DONE ARGTHREAD THREAD...'
5534
          Where: COUNT (two hex digits) is the number of threads being
5535
          returned; DONE (one hex digit) is zero to indicate more
5536
          threads and one indicates no further threads; ARGTHREADID
5537
          (eight hex digits) is NEXTTHREAD from the request packet;
5538
          THREAD...  is a sequence of thread IDs from the target.
5539
          THREADID (eight hex digits).  See
5540
          `remote.c:parse_threadlist_response()'.
5541
 
5542
`qOffsets'
5543
     Get section offsets that the target used when relocating the
5544
     downloaded image.
5545
 
5546
     Reply:
5547
    `Text=XXX;Data=YYY[;Bss=ZZZ]'
5548
          Relocate the `Text' section by XXX from its original address.
5549
          Relocate the `Data' section by YYY from its original address.
5550
          If the object file format provides segment information (e.g.
5551
          ELF `PT_LOAD' program headers), GDB will relocate entire
5552
          segments by the supplied offsets.
5553
 
5554
          _Note: while a `Bss' offset may be included in the response,
5555
          GDB ignores this and instead applies the `Data' offset to the
5556
          `Bss' section._
5557
 
5558
    `TextSeg=XXX[;DataSeg=YYY]'
5559
          Relocate the first segment of the object file, which
5560
          conventionally contains program code, to a starting address
5561
          of XXX.  If `DataSeg' is specified, relocate the second
5562
          segment, which conventionally contains modifiable data, to a
5563
          starting address of YYY.  GDB will report an error if the
5564
          object file does not contain segment information, or does not
5565
          contain at least as many segments as mentioned in the reply.
5566
          Extra segments are kept at fixed offsets relative to the last
5567
          relocated segment.
5568
 
5569
`qP MODE THREAD-ID'
5570
     Returns information on THREAD-ID.  Where: MODE is a hex encoded 32
5571
     bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
5572
 
5573
     Don't use this packet; use the `qThreadExtraInfo' query instead
5574
     (see below).
5575
 
5576
     Reply: see `remote.c:remote_unpack_thread_info_response()'.
5577
 
5578
`QNonStop:1'
5579
 
5580
`QNonStop:0'
5581
     Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode.
5582
     *Note Remote Non-Stop::, for more information.
5583
 
5584
     Reply:
5585
    `OK'
5586
          The request succeeded.
5587
 
5588
    `E NN'
5589
          An error occurred.  NN are hex digits.
5590
 
5591
    `'
5592
          An empty reply indicates that `QNonStop' is not supported by
5593
          the stub.
5594
 
5595
     This packet is not probed by default; the remote stub must request
5596
     it, by supplying an appropriate `qSupported' response (*note
5597
     qSupported::).  Use of this packet is controlled by the `set
5598
     non-stop' command; *note Non-Stop Mode::.
5599
 
5600
`QPassSignals: SIGNAL [;SIGNAL]...'
5601
     Each listed SIGNAL should be passed directly to the inferior
5602
     process.  Signals are numbered identically to continue packets and
5603
     stop replies (*note Stop Reply Packets::).  Each SIGNAL list item
5604
     should be strictly greater than the previous item.  These signals
5605
     do not need to stop the inferior, or be reported to GDB.  All
5606
     other signals should be reported to GDB.  Multiple `QPassSignals'
5607
     packets do not combine; any earlier `QPassSignals' list is
5608
     completely replaced by the new list.  This packet improves
5609
     performance when using `handle SIGNAL nostop noprint pass'.
5610
 
5611
     Reply:
5612
    `OK'
5613
          The request succeeded.
5614
 
5615
    `E NN'
5616
          An error occurred.  NN are hex digits.
5617
 
5618
    `'
5619
          An empty reply indicates that `QPassSignals' is not supported
5620
          by the stub.
5621
 
5622
     Use of this packet is controlled by the `set remote pass-signals'
5623
     command (*note set remote pass-signals: Remote Configuration.).
5624
     This packet is not probed by default; the remote stub must request
5625
     it, by supplying an appropriate `qSupported' response (*note
5626
     qSupported::).
5627
 
5628
`qRcmd,COMMAND'
5629
     COMMAND (hex encoded) is passed to the local interpreter for
5630
     execution.  Invalid commands should be reported using the output
5631
     string.  Before the final result packet, the target may also
5632
     respond with a number of intermediate `OOUTPUT' console output
5633
     packets.  _Implementors should note that providing access to a
5634
     stubs's interpreter may have security implications_.
5635
 
5636
     Reply:
5637
    `OK'
5638
          A command response with no output.
5639
 
5640
    `OUTPUT'
5641
          A command response with the hex encoded output string OUTPUT.
5642
 
5643
    `E NN'
5644
          Indicate a badly formed request.
5645
 
5646
    `'
5647
          An empty reply indicates that `qRcmd' is not recognized.
5648
 
5649
     (Note that the `qRcmd' packet's name is separated from the command
5650
     by a `,', not a `:', contrary to the naming conventions above.
5651
     Please don't use this packet as a model for new packets.)
5652
 
5653
`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
5654
     Search LENGTH bytes at ADDRESS for SEARCH-PATTERN.  ADDRESS and
5655
     LENGTH are encoded in hex.  SEARCH-PATTERN is a sequence of bytes,
5656
     hex encoded.
5657
 
5658
     Reply:
5659
    `0'
5660
          The pattern was not found.
5661
 
5662
    `1,address'
5663
          The pattern was found at ADDRESS.
5664
 
5665
    `E NN'
5666
          A badly formed request or an error was encountered while
5667
          searching memory.
5668
 
5669
    `'
5670
          An empty reply indicates that `qSearch:memory' is not
5671
          recognized.
5672
 
5673
`QStartNoAckMode'
5674
     Request that the remote stub disable the normal `+'/`-' protocol
5675
     acknowledgments (*note Packet Acknowledgment::).
5676
 
5677
     Reply:
5678
    `OK'
5679
          The stub has switched to no-acknowledgment mode.  GDB
5680
          acknowledges this reponse, but neither the stub nor GDB shall
5681
          send or expect further `+'/`-' acknowledgments in the current
5682
          connection.
5683
 
5684
    `'
5685
          An empty reply indicates that the stub does not support
5686
          no-acknowledgment mode.
5687
 
5688
`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
5689
     Tell the remote stub about features supported by GDB, and query
5690
     the stub for features it supports.  This packet allows GDB and the
5691
     remote stub to take advantage of each others' features.
5692
     `qSupported' also consolidates multiple feature probes at startup,
5693
     to improve GDB performance--a single larger packet performs better
5694
     than multiple smaller probe packets on high-latency links.  Some
5695
     features may enable behavior which must not be on by default, e.g.
5696
     because it would confuse older clients or stubs.  Other features
5697
     may describe packets which could be automatically probed for, but
5698
     are not.  These features must be reported before GDB will use
5699
     them.  This "default unsupported" behavior is not appropriate for
5700
     all packets, but it helps to keep the initial connection time
5701
     under control with new versions of GDB which support increasing
5702
     numbers of packets.
5703
 
5704
     Reply:
5705
    `STUBFEATURE [;STUBFEATURE]...'
5706
          The stub supports or does not support each returned
5707
          STUBFEATURE, depending on the form of each STUBFEATURE (see
5708
          below for the possible forms).
5709
 
5710
    `'
5711
          An empty reply indicates that `qSupported' is not recognized,
5712
          or that no features needed to be reported to GDB.
5713
 
5714
     The allowed forms for each feature (either a GDBFEATURE in the
5715
     `qSupported' packet, or a STUBFEATURE in the response) are:
5716
 
5717
    `NAME=VALUE'
5718
          The remote protocol feature NAME is supported, and associated
5719
          with the specified VALUE.  The format of VALUE depends on the
5720
          feature, but it must not include a semicolon.
5721
 
5722
    `NAME+'
5723
          The remote protocol feature NAME is supported, and does not
5724
          need an associated value.
5725
 
5726
    `NAME-'
5727
          The remote protocol feature NAME is not supported.
5728
 
5729
    `NAME?'
5730
          The remote protocol feature NAME may be supported, and GDB
5731
          should auto-detect support in some other way when it is
5732
          needed.  This form will not be used for GDBFEATURE
5733
          notifications, but may be used for STUBFEATURE responses.
5734
 
5735
     Whenever the stub receives a `qSupported' request, the supplied
5736
     set of GDB features should override any previous request.  This
5737
     allows GDB to put the stub in a known state, even if the stub had
5738
     previously been communicating with a different version of GDB.
5739
 
5740
     The following values of GDBFEATURE (for the packet sent by GDB)
5741
     are defined:
5742
 
5743
    `multiprocess'
5744
          This feature indicates whether GDB supports multiprocess
5745
          extensions to the remote protocol.  GDB does not use such
5746
          extensions unless the stub also reports that it supports them
5747
          by including `multiprocess+' in its `qSupported' reply.
5748
          *Note multiprocess extensions::, for details.
5749
 
5750
    `xmlRegisters'
5751
          This feature indicates that GDB supports the XML target
5752
          description.  If the stub sees `xmlRegisters=' with target
5753
          specific strings separated by a comma, it will report register
5754
          description.
5755
 
5756
    `qRelocInsn'
5757
          This feature indicates whether GDB supports the `qRelocInsn'
5758
          packet (*note Relocate instruction reply packet: Tracepoint
5759
          Packets.).
5760
 
5761
     Stubs should ignore any unknown values for GDBFEATURE.  Any GDB
5762
     which sends a `qSupported' packet supports receiving packets of
5763
     unlimited length (earlier versions of GDB may reject overly long
5764
     responses).  Additional values for GDBFEATURE may be defined in
5765
     the future to let the stub take advantage of new features in GDB,
5766
     e.g. incompatible improvements in the remote protocol--the
5767
     `multiprocess' feature is an example of such a feature.  The
5768
     stub's reply should be independent of the GDBFEATURE entries sent
5769
     by GDB; first GDB describes all the features it supports, and then
5770
     the stub replies with all the features it supports.
5771
 
5772
     Similarly, GDB will silently ignore unrecognized stub feature
5773
     responses, as long as each response uses one of the standard forms.
5774
 
5775
     Some features are flags.  A stub which supports a flag feature
5776
     should respond with a `+' form response.  Other features require
5777
     values, and the stub should respond with an `=' form response.
5778
 
5779
     Each feature has a default value, which GDB will use if
5780
     `qSupported' is not available or if the feature is not mentioned
5781
     in the `qSupported' response.  The default values are fixed; a
5782
     stub is free to omit any feature responses that match the defaults.
5783
 
5784
     Not all features can be probed, but for those which can, the
5785
     probing mechanism is useful: in some cases, a stub's internal
5786
     architecture may not allow the protocol layer to know some
5787
     information about the underlying target in advance.  This is
5788
     especially common in stubs which may be configured for multiple
5789
     targets.
5790
 
5791
     These are the currently defined stub features and their properties:
5792
 
5793
     Feature Name            Value         Default  Probe Allowed
5794
                             Required
5795
     `PacketSize'            Yes           `-'      No
5796
     `qXfer:auxv:read'       No            `-'      Yes
5797
     `qXfer:features:read'   No            `-'      Yes
5798
     `qXfer:libraries:read'  No            `-'      Yes
5799
     `qXfer:memory-map:read' No            `-'      Yes
5800
     `qXfer:sdata:read'      No            `-'      Yes
5801
     `qXfer:spu:read'        No            `-'      Yes
5802
     `qXfer:spu:write'       No            `-'      Yes
5803
     `qXfer:siginfo:read'    No            `-'      Yes
5804
     `qXfer:siginfo:write'   No            `-'      Yes
5805
     `qXfer:threads:read'    No            `-'      Yes
5806
     `QNonStop'              No            `-'      Yes
5807
     `QPassSignals'          No            `-'      Yes
5808
     `QStartNoAckMode'       No            `-'      Yes
5809
     `multiprocess'          No            `-'      No
5810
     `ConditionalTracepoints'No            `-'      No
5811
     `ReverseContinue'       No            `-'      No
5812
     `ReverseStep'           No            `-'      No
5813
     `TracepointSource'      No            `-'      No
5814
     `QAllow'                No            `-'      No
5815
 
5816
     These are the currently defined stub features, in more detail:
5817
 
5818
    `PacketSize=BYTES'
5819
          The remote stub can accept packets up to at least BYTES in
5820
          length.  GDB will send packets up to this size for bulk
5821
          transfers, and will never send larger packets.  This is a
5822
          limit on the data characters in the packet, including the
5823
          frame and checksum.  There is no trailing NUL byte in a
5824
          remote protocol packet; if the stub stores packets in a
5825
          NUL-terminated format, it should allow an extra byte in its
5826
          buffer for the NUL.  If this stub feature is not supported,
5827
          GDB guesses based on the size of the `g' packet response.
5828
 
5829
    `qXfer:auxv:read'
5830
          The remote stub understands the `qXfer:auxv:read' packet
5831
          (*note qXfer auxiliary vector read::).
5832
 
5833
    `qXfer:features:read'
5834
          The remote stub understands the `qXfer:features:read' packet
5835
          (*note qXfer target description read::).
5836
 
5837
    `qXfer:libraries:read'
5838
          The remote stub understands the `qXfer:libraries:read' packet
5839
          (*note qXfer library list read::).
5840
 
5841
    `qXfer:memory-map:read'
5842
          The remote stub understands the `qXfer:memory-map:read' packet
5843
          (*note qXfer memory map read::).
5844
 
5845
    `qXfer:sdata:read'
5846
          The remote stub understands the `qXfer:sdata:read' packet
5847
          (*note qXfer sdata read::).
5848
 
5849
    `qXfer:spu:read'
5850
          The remote stub understands the `qXfer:spu:read' packet
5851
          (*note qXfer spu read::).
5852
 
5853
    `qXfer:spu:write'
5854
          The remote stub understands the `qXfer:spu:write' packet
5855
          (*note qXfer spu write::).
5856
 
5857
    `qXfer:siginfo:read'
5858
          The remote stub understands the `qXfer:siginfo:read' packet
5859
          (*note qXfer siginfo read::).
5860
 
5861
    `qXfer:siginfo:write'
5862
          The remote stub understands the `qXfer:siginfo:write' packet
5863
          (*note qXfer siginfo write::).
5864
 
5865
    `qXfer:threads:read'
5866
          The remote stub understands the `qXfer:threads:read' packet
5867
          (*note qXfer threads read::).
5868
 
5869
    `QNonStop'
5870
          The remote stub understands the `QNonStop' packet (*note
5871
          QNonStop::).
5872
 
5873
    `QPassSignals'
5874
          The remote stub understands the `QPassSignals' packet (*note
5875
          QPassSignals::).
5876
 
5877
    `QStartNoAckMode'
5878
          The remote stub understands the `QStartNoAckMode' packet and
5879
          prefers to operate in no-acknowledgment mode.  *Note Packet
5880
          Acknowledgment::.
5881
 
5882
    `multiprocess'
5883
          The remote stub understands the multiprocess extensions to
5884
          the remote protocol syntax.  The multiprocess extensions
5885
          affect the syntax of thread IDs in both packets and replies
5886
          (*note thread-id syntax::), and add process IDs to the `D'
5887
          packet and `W' and `X' replies.  Note that reporting this
5888
          feature indicates support for the syntactic extensions only,
5889
          not that the stub necessarily supports debugging of more than
5890
          one process at a time.  The stub must not use multiprocess
5891
          extensions in packet replies unless GDB has also indicated it
5892
          supports them in its `qSupported' request.
5893
 
5894
    `qXfer:osdata:read'
5895
          The remote stub understands the `qXfer:osdata:read' packet
5896
          ((*note qXfer osdata read::).
5897
 
5898
    `ConditionalTracepoints'
5899
          The remote stub accepts and implements conditional
5900
          expressions defined for tracepoints (*note Tracepoint
5901
          Conditions::).
5902
 
5903
    `ReverseContinue'
5904
          The remote stub accepts and implements the reverse continue
5905
          packet (*note bc::).
5906
 
5907
    `ReverseStep'
5908
          The remote stub accepts and implements the reverse step packet
5909
          (*note bs::).
5910
 
5911
    `TracepointSource'
5912
          The remote stub understands the `QTDPsrc' packet that supplies
5913
          the source form of tracepoint definitions.
5914
 
5915
    `QAllow'
5916
          The remote stub understands the `QAllow' packet.
5917
 
5918
    `StaticTracepoint'
5919
          The remote stub supports static tracepoints.
5920
 
5921
 
5922
`qSymbol::'
5923
     Notify the target that GDB is prepared to serve symbol lookup
5924
     requests.  Accept requests from the target for the values of
5925
     symbols.
5926
 
5927
     Reply:
5928
    `OK'
5929
          The target does not need to look up any (more) symbols.
5930
 
5931
    `qSymbol:SYM_NAME'
5932
          The target requests the value of symbol SYM_NAME (hex
5933
          encoded).  GDB may provide the value by using the
5934
          `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
5935
 
5936
`qSymbol:SYM_VALUE:SYM_NAME'
5937
     Set the value of SYM_NAME to SYM_VALUE.
5938
 
5939
     SYM_NAME (hex encoded) is the name of a symbol whose value the
5940
     target has previously requested.
5941
 
5942
     SYM_VALUE (hex) is the value for symbol SYM_NAME.  If GDB cannot
5943
     supply a value for SYM_NAME, then this field will be empty.
5944
 
5945
     Reply:
5946
    `OK'
5947
          The target does not need to look up any (more) symbols.
5948
 
5949
    `qSymbol:SYM_NAME'
5950
          The target requests the value of a new symbol SYM_NAME (hex
5951
          encoded).  GDB will continue to supply the values of symbols
5952
          (if available), until the target ceases to request them.
5953
 
5954
`qTBuffer'
5955
 
5956
`QTBuffer'
5957
 
5958
`QTDisconnected'
5959
`QTDP'
5960
`QTDPsrc'
5961
`QTDV'
5962
`qTfP'
5963
`qTfV'
5964
`QTFrame'
5965
     *Note Tracepoint Packets::.
5966
 
5967
`qThreadExtraInfo,THREAD-ID'
5968
     Obtain a printable string description of a thread's attributes from
5969 342 jeremybenn
     the target OS.  THREAD-ID is a thread ID; see *note thread-id
5970 330 jeremybenn
     syntax::.  This string may contain anything that the target OS
5971
     thinks is interesting for GDB to tell the user about the thread.
5972
     The string is displayed in GDB's `info threads' display.  Some
5973
     examples of possible thread extra info strings are `Runnable', or
5974
     `Blocked on Mutex'.
5975
 
5976
     Reply:
5977
    `XX...'
5978
          Where `XX...' is a hex encoding of ASCII data, comprising the
5979
          printable string containing the extra information about the
5980
          thread's attributes.
5981
 
5982
     (Note that the `qThreadExtraInfo' packet's name is separated from
5983
     the command by a `,', not a `:', contrary to the naming
5984
     conventions above.  Please don't use this packet as a model for new
5985
     packets.)
5986
 
5987
`QTSave'
5988
 
5989
`qTsP'
5990
 
5991
`qTsV'
5992
`QTStart'
5993
`QTStop'
5994
`QTinit'
5995
`QTro'
5996
`qTStatus'
5997
`qTV'
5998
`qTfSTM'
5999
`qTsSTM'
6000
`qTSTMat'
6001
     *Note Tracepoint Packets::.
6002
 
6003
`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
6004
     Read uninterpreted bytes from the target's special data area
6005
     identified by the keyword OBJECT.  Request LENGTH bytes starting
6006
     at OFFSET bytes into the data.  The content and encoding of ANNEX
6007
     is specific to OBJECT; it can supply additional details about what
6008
     data to access.
6009
 
6010
     Here are the specific requests of this form defined so far.  All
6011
     `qXfer:OBJECT:read:...' requests use the same reply formats,
6012
     listed below.
6013
 
6014
    `qXfer:auxv:read::OFFSET,LENGTH'
6015
          Access the target's "auxiliary vector".  *Note auxiliary
6016
          vector: OS Information.  Note ANNEX must be empty.
6017
 
6018
          This packet is not probed by default; the remote stub must
6019
          request it, by supplying an appropriate `qSupported' response
6020
          (*note qSupported::).
6021
 
6022
    `qXfer:features:read:ANNEX:OFFSET,LENGTH'
6023
          Access the "target description".  *Note Target
6024
          Descriptions::.  The annex specifies which XML document to
6025
          access.  The main description is always loaded from the
6026
          `target.xml' annex.
6027
 
6028
          This packet is not probed by default; the remote stub must
6029
          request it, by supplying an appropriate `qSupported' response
6030
          (*note qSupported::).
6031
 
6032
    `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
6033
          Access the target's list of loaded libraries.  *Note Library
6034
          List Format::.  The annex part of the generic `qXfer' packet
6035
          must be empty (*note qXfer read::).
6036
 
6037
          Targets which maintain a list of libraries in the program's
6038
          memory do not need to implement this packet; it is designed
6039
          for platforms where the operating system manages the list of
6040
          loaded libraries.
6041
 
6042
          This packet is not probed by default; the remote stub must
6043
          request it, by supplying an appropriate `qSupported' response
6044
          (*note qSupported::).
6045
 
6046
    `qXfer:memory-map:read::OFFSET,LENGTH'
6047
          Access the target's "memory-map".  *Note Memory Map Format::.
6048
          The annex part of the generic `qXfer' packet must be empty
6049
          (*note qXfer read::).
6050
 
6051
          This packet is not probed by default; the remote stub must
6052
          request it, by supplying an appropriate `qSupported' response
6053
          (*note qSupported::).
6054
 
6055
    `qXfer:sdata:read::OFFSET,LENGTH'
6056
          Read contents of the extra collected static tracepoint marker
6057
          information.  The annex part of the generic `qXfer' packet
6058
          must be empty (*note qXfer read::).  *Note Tracepoint Action
6059
          Lists: Tracepoint Actions.
6060
 
6061
          This packet is not probed by default; the remote stub must
6062
          request it, by supplying an appropriate `qSupported' response
6063
          (*note qSupported::).
6064
 
6065
    `qXfer:siginfo:read::OFFSET,LENGTH'
6066
          Read contents of the extra signal information on the target
6067
          system.  The annex part of the generic `qXfer' packet must be
6068
          empty (*note qXfer read::).
6069
 
6070
          This packet is not probed by default; the remote stub must
6071
          request it, by supplying an appropriate `qSupported' response
6072
          (*note qSupported::).
6073
 
6074
    `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
6075
          Read contents of an `spufs' file on the target system.  The
6076
          annex specifies which file to read; it must be of the form
6077
          `ID/NAME', where ID specifies an SPU context ID in the target
6078
          process, and NAME identifes the `spufs' file in that context
6079
          to be accessed.
6080
 
6081
          This packet is not probed by default; the remote stub must
6082
          request it, by supplying an appropriate `qSupported' response
6083
          (*note qSupported::).
6084
 
6085
    `qXfer:threads:read::OFFSET,LENGTH'
6086
          Access the list of threads on target.  *Note Thread List
6087
          Format::.  The annex part of the generic `qXfer' packet must
6088
          be empty (*note qXfer read::).
6089
 
6090
          This packet is not probed by default; the remote stub must
6091
          request it, by supplying an appropriate `qSupported' response
6092
          (*note qSupported::).
6093
 
6094
    `qXfer:osdata:read::OFFSET,LENGTH'
6095
          Access the target's "operating system information".  *Note
6096
          Operating System Information::.
6097
 
6098
 
6099
     Reply:
6100
    `m DATA'
6101
          Data DATA (*note Binary Data::) has been read from the
6102
          target.  There may be more data at a higher address (although
6103
          it is permitted to return `m' even for the last valid block
6104
          of data, as long as at least one byte of data was read).
6105
          DATA may have fewer bytes than the LENGTH in the request.
6106
 
6107
    `l DATA'
6108
          Data DATA (*note Binary Data::) has been read from the target.
6109
          There is no more data to be read.  DATA may have fewer bytes
6110
          than the LENGTH in the request.
6111
 
6112
    `l'
6113
          The OFFSET in the request is at the end of the data.  There
6114
          is no more data to be read.
6115
 
6116
    `E00'
6117
          The request was malformed, or ANNEX was invalid.
6118
 
6119
    `E NN'
6120
          The offset was invalid, or there was an error encountered
6121
          reading the data.  NN is a hex-encoded `errno' value.
6122
 
6123
    `'
6124
          An empty reply indicates the OBJECT string was not recognized
6125
          by the stub, or that the object does not support reading.
6126
 
6127
`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
6128
     Write uninterpreted bytes into the target's special data area
6129
     identified by the keyword OBJECT, starting at OFFSET bytes into
6130
     the data.  DATA... is the binary-encoded data (*note Binary
6131
     Data::) to be written.  The content and encoding of ANNEX is
6132
     specific to OBJECT; it can supply additional details about what
6133
     data to access.
6134
 
6135
     Here are the specific requests of this form defined so far.  All
6136
     `qXfer:OBJECT:write:...' requests use the same reply formats,
6137
     listed below.
6138
 
6139
    `qXfer:siginfo:write::OFFSET:DATA...'
6140
          Write DATA to the extra signal information on the target
6141
          system.  The annex part of the generic `qXfer' packet must be
6142
          empty (*note qXfer write::).
6143
 
6144
          This packet is not probed by default; the remote stub must
6145
          request it, by supplying an appropriate `qSupported' response
6146
          (*note qSupported::).
6147
 
6148
    `qXfer:spu:write:ANNEX:OFFSET:DATA...'
6149
          Write DATA to an `spufs' file on the target system.  The
6150
          annex specifies which file to write; it must be of the form
6151
          `ID/NAME', where ID specifies an SPU context ID in the target
6152
          process, and NAME identifes the `spufs' file in that context
6153
          to be accessed.
6154
 
6155
          This packet is not probed by default; the remote stub must
6156
          request it, by supplying an appropriate `qSupported' response
6157
          (*note qSupported::).
6158
 
6159
     Reply:
6160
    `NN'
6161
          NN (hex encoded) is the number of bytes written.  This may be
6162
          fewer bytes than supplied in the request.
6163
 
6164
    `E00'
6165
          The request was malformed, or ANNEX was invalid.
6166
 
6167
    `E NN'
6168
          The offset was invalid, or there was an error encountered
6169
          writing the data.  NN is a hex-encoded `errno' value.
6170
 
6171
    `'
6172
          An empty reply indicates the OBJECT string was not recognized
6173
          by the stub, or that the object does not support writing.
6174
 
6175
`qXfer:OBJECT:OPERATION:...'
6176
     Requests of this form may be added in the future.  When a stub does
6177
     not recognize the OBJECT keyword, or its support for OBJECT does
6178
     not recognize the OPERATION keyword, the stub must respond with an
6179
     empty packet.
6180
 
6181
`qAttached:PID'
6182
     Return an indication of whether the remote server attached to an
6183
     existing process or created a new process.  When the multiprocess
6184
     protocol extensions are supported (*note multiprocess
6185
     extensions::), PID is an integer in hexadecimal format identifying
6186
     the target process.  Otherwise, GDB will omit the PID field and
6187
     the query packet will be simplified as `qAttached'.
6188
 
6189
     This query is used, for example, to know whether the remote process
6190
     should be detached or killed when a GDB session is ended with the
6191
     `quit' command.
6192
 
6193
     Reply:
6194
    `1'
6195
          The remote server attached to an existing process.
6196
 
6197
    `0'
6198
          The remote server created a new process.
6199
 
6200
    `E NN'
6201
          A badly formed request or an error was encountered.
6202
 
6203
 
6204
   ---------- Footnotes ----------
6205
 
6206
   (1) The `qP' and `qL' packets predate these conventions, and have
6207
arguments without any terminator for the packet name; we suspect they
6208
are in widespread use in places that are difficult to upgrade.  The
6209
`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
6210
are known to not check for the end of the packet.
6211
 
6212

6213
File: gdb.info,  Node: Architecture-Specific Protocol Details,  Next: Tracepoint Packets,  Prev: General Query Packets,  Up: Remote Protocol
6214
 
6215
D.5 Architecture-Specific Protocol Details
6216
==========================================
6217
 
6218
This section describes how the remote protocol is applied to specific
6219 342 jeremybenn
target architectures.  Also see *note Standard Target Features::, for
6220 330 jeremybenn
details of XML target descriptions for each architecture.
6221
 
6222
D.5.1 ARM
6223
---------
6224
 
6225
D.5.1.1 Breakpoint Kinds
6226
........................
6227
 
6228
These breakpoint kinds are defined for the `Z0' and `Z1' packets.
6229
 
6230
2
6231
     16-bit Thumb mode breakpoint.
6232
 
6233
3
6234
     32-bit Thumb mode (Thumb-2) breakpoint.
6235
 
6236
4
6237
     32-bit ARM mode breakpoint.
6238
 
6239
 
6240
D.5.2 MIPS
6241
----------
6242
 
6243
D.5.2.1 Register Packet Format
6244
..............................
6245
 
6246
The following `g'/`G' packets have previously been defined.  In the
6247
below, some thirty-two bit registers are transferred as sixty-four
6248
bits.  Those registers should be zero/sign extended (which?)  to fill
6249
the space allocated.  Register bytes are transferred in target byte
6250
order.  The two nibbles within a register byte are transferred
6251
most-significant - least-significant.
6252
 
6253
MIPS32
6254
     All registers are transferred as thirty-two bit quantities in the
6255
     order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
6256
     floating-point registers; fsr; fir; fp.
6257
 
6258
MIPS64
6259
     All registers are transferred as sixty-four bit quantities
6260
     (including thirty-two bit registers such as `sr').  The ordering
6261
     is the same as `MIPS32'.
6262
 
6263
 
6264

6265
File: gdb.info,  Node: Tracepoint Packets,  Next: Host I/O Packets,  Prev: Architecture-Specific Protocol Details,  Up: Remote Protocol
6266
 
6267
D.6 Tracepoint Packets
6268
======================
6269
 
6270
Here we describe the packets GDB uses to implement tracepoints (*note
6271
Tracepoints::).
6272
 
6273
`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
6274
     Create a new tracepoint, number N, at ADDR.  If ENA is `E', then
6275
     the tracepoint is enabled; if it is `D', then the tracepoint is
6276
     disabled.  STEP is the tracepoint's step count, and PASS is its
6277
     pass count.  If an `F' is present, then the tracepoint is to be a
6278
     fast tracepoint, and the FLEN is the number of bytes that the
6279
     target should copy elsewhere to make room for the tracepoint.  If
6280
     an `X' is present, it introduces a tracepoint condition, which
6281
     consists of a hexadecimal length, followed by a comma and
6282
     hex-encoded bytes, in a manner similar to action encodings as
6283
     described below.  If the trailing `-' is present, further `QTDP'
6284
     packets will follow to specify this tracepoint's actions.
6285
 
6286
     Replies:
6287
    `OK'
6288
          The packet was understood and carried out.
6289
 
6290
    `qRelocInsn'
6291
          *Note Relocate instruction reply packet: Tracepoint Packets.
6292
 
6293
    `'
6294
          The packet was not recognized.
6295
 
6296
`QTDP:-N:ADDR:[S]ACTION...[-]'
6297
     Define actions to be taken when a tracepoint is hit.  N and ADDR
6298
     must be the same as in the initial `QTDP' packet for this
6299
     tracepoint.  This packet may only be sent immediately after
6300
     another `QTDP' packet that ended with a `-'.  If the trailing `-'
6301
     is present, further `QTDP' packets will follow, specifying more
6302
     actions for this tracepoint.
6303
 
6304
     In the series of action packets for a given tracepoint, at most one
6305
     can have an `S' before its first ACTION.  If such a packet is
6306
     sent, it and the following packets define "while-stepping"
6307
     actions.  Any prior packets define ordinary actions -- that is,
6308
     those taken when the tracepoint is first hit.  If no action packet
6309
     has an `S', then all the packets in the series specify ordinary
6310
     tracepoint actions.
6311
 
6312
     The `ACTION...' portion of the packet is a series of actions,
6313
     concatenated without separators.  Each action has one of the
6314
     following forms:
6315
 
6316
    `R MASK'
6317
          Collect the registers whose bits are set in MASK.  MASK is a
6318
          hexadecimal number whose I'th bit is set if register number I
6319
          should be collected.  (The least significant bit is numbered
6320
          zero.)  Note that MASK may be any number of digits long; it
6321
          may not fit in a 32-bit word.
6322
 
6323
    `M BASEREG,OFFSET,LEN'
6324
          Collect LEN bytes of memory starting at the address in
6325
          register number BASEREG, plus OFFSET.  If BASEREG is `-1',
6326
          then the range has a fixed address: OFFSET is the address of
6327
          the lowest byte to collect.  The BASEREG, OFFSET, and LEN
6328
          parameters are all unsigned hexadecimal values (the `-1'
6329
          value for BASEREG is a special case).
6330
 
6331
    `X LEN,EXPR'
6332
          Evaluate EXPR, whose length is LEN, and collect memory as it
6333 342 jeremybenn
          directs.  EXPR is an agent expression, as described in *note
6334 330 jeremybenn
          Agent Expressions::.  Each byte of the expression is encoded
6335
          as a two-digit hex number in the packet; LEN is the number of
6336
          bytes in the expression (and thus one-half the number of hex
6337
          digits in the packet).
6338
 
6339
 
6340
     Any number of actions may be packed together in a single `QTDP'
6341
     packet, as long as the packet does not exceed the maximum packet
6342
     length (400 bytes, for many stubs).  There may be only one `R'
6343
     action per tracepoint, and it must precede any `M' or `X' actions.
6344 342 jeremybenn
     Any registers referred to by `M' and `X' actions must be collected
6345
     by a preceding `R' action.  (The "while-stepping" actions are
6346
     treated as if they were attached to a separate tracepoint, as far
6347
     as these restrictions are concerned.)
6348 330 jeremybenn
 
6349
     Replies:
6350
    `OK'
6351
          The packet was understood and carried out.
6352
 
6353
    `qRelocInsn'
6354
          *Note Relocate instruction reply packet: Tracepoint Packets.
6355
 
6356
    `'
6357
          The packet was not recognized.
6358
 
6359
`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
6360
     Specify a source string of tracepoint N at address ADDR.  This is
6361
     useful to get accurate reproduction of the tracepoints originally
6362
     downloaded at the beginning of the trace run.  TYPE is the name of
6363
     the tracepoint part, such as `cond' for the tracepoint's
6364
     conditional expression (see below for a list of types), while
6365
     BYTES is the string, encoded in hexadecimal.
6366
 
6367
     START is the offset of the BYTES within the overall source string,
6368
     while SLEN is the total length of the source string.  This is
6369
     intended for handling source strings that are longer than will fit
6370
     in a single packet.
6371
 
6372
     The available string types are `at' for the location, `cond' for
6373
     the conditional, and `cmd' for an action command.  GDB sends a
6374
     separate packet for each command in the action list, in the same
6375
     order in which the commands are stored in the list.
6376
 
6377
     The target does not need to do anything with source strings except
6378
     report them back as part of the replies to the `qTfP'/`qTsP' query
6379
     packets.
6380
 
6381
     Although this packet is optional, and GDB will only send it if the
6382
     target replies with `TracepointSource' *Note General Query
6383
     Packets::, it makes both disconnected tracing and trace files much
6384
     easier to use.  Otherwise the user must be careful that the
6385
     tracepoints in effect while looking at trace frames are identical
6386
     to the ones in effect during the trace run; even a small
6387
     discrepancy could cause `tdump' not to work, or a particular trace
6388
     frame not be found.
6389
 
6390
`QTDV:N:VALUE'
6391
     Create a new trace state variable, number N, with an initial value
6392
     of VALUE, which is a 64-bit signed integer.  Both N and VALUE are
6393
     encoded as hexadecimal values. GDB has the option of not using
6394
     this packet for initial values of zero; the target should simply
6395
     create the trace state variables as they are mentioned in
6396
     expressions.
6397
 
6398
`QTFrame:N'
6399
     Select the N'th tracepoint frame from the buffer, and use the
6400
     register and memory contents recorded there to answer subsequent
6401
     request packets from GDB.
6402
 
6403
     A successful reply from the stub indicates that the stub has found
6404
     the requested frame.  The response is a series of parts,
6405
     concatenated without separators, describing the frame we selected.
6406
     Each part has one of the following forms:
6407
 
6408
    `F F'
6409
          The selected frame is number N in the trace frame buffer; F
6410
          is a hexadecimal number.  If F is `-1', then there was no
6411
          frame matching the criteria in the request packet.
6412
 
6413
    `T T'
6414
          The selected trace frame records a hit of tracepoint number T;
6415
          T is a hexadecimal number.
6416
 
6417
 
6418
`QTFrame:pc:ADDR'
6419
     Like `QTFrame:N', but select the first tracepoint frame after the
6420
     currently selected frame whose PC is ADDR; ADDR is a hexadecimal
6421
     number.
6422
 
6423
`QTFrame:tdp:T'
6424
     Like `QTFrame:N', but select the first tracepoint frame after the
6425
     currently selected frame that is a hit of tracepoint T; T is a
6426
     hexadecimal number.
6427
 
6428
`QTFrame:range:START:END'
6429
     Like `QTFrame:N', but select the first tracepoint frame after the
6430
     currently selected frame whose PC is between START (inclusive) and
6431
     END (inclusive); START and END are hexadecimal numbers.
6432
 
6433
`QTFrame:outside:START:END'
6434
     Like `QTFrame:range:START:END', but select the first frame
6435
     _outside_ the given range of addresses (exclusive).
6436
 
6437
`QTStart'
6438
     Begin the tracepoint experiment.  Begin collecting data from
6439
     tracepoint hits in the trace frame buffer.  This packet supports
6440
     the `qRelocInsn' reply (*note Relocate instruction reply packet:
6441
     Tracepoint Packets.).
6442
 
6443
`QTStop'
6444
     End the tracepoint experiment.  Stop collecting trace frames.
6445
 
6446
`QTinit'
6447
     Clear the table of tracepoints, and empty the trace frame buffer.
6448
 
6449
`QTro:START1,END1:START2,END2:...'
6450
     Establish the given ranges of memory as "transparent".  The stub
6451
     will answer requests for these ranges from memory's current
6452
     contents, if they were not collected as part of the tracepoint hit.
6453
 
6454
     GDB uses this to mark read-only regions of memory, like those
6455
     containing program code.  Since these areas never change, they
6456
     should still have the same contents they did when the tracepoint
6457
     was hit, so there's no reason for the stub to refuse to provide
6458
     their contents.
6459
 
6460
`QTDisconnected:VALUE'
6461
     Set the choice to what to do with the tracing run when GDB
6462
     disconnects from the target.  A VALUE of 1 directs the target to
6463
     continue the tracing run, while 0 tells the target to stop tracing
6464
     if GDB is no longer in the picture.
6465
 
6466
`qTStatus'
6467
     Ask the stub if there is a trace experiment running right now.
6468
 
6469
     The reply has the form:
6470
 
6471
    `TRUNNING[;FIELD]...'
6472
          RUNNING is a single digit `1' if the trace is presently
6473
          running, or `0' if not.  It is followed by semicolon-separated
6474
          optional fields that an agent may use to report additional
6475
          status.
6476
 
6477
 
6478
     If the trace is not running, the agent may report any of several
6479
     explanations as one of the optional fields:
6480
 
6481
    `tnotrun:0'
6482
          No trace has been run yet.
6483
 
6484
    `tstop:0'
6485
          The trace was stopped by a user-originated stop command.
6486
 
6487
    `tfull:0'
6488
          The trace stopped because the trace buffer filled up.
6489
 
6490
    `tdisconnected:0'
6491
          The trace stopped because GDB disconnected from the target.
6492
 
6493
    `tpasscount:TPNUM'
6494
          The trace stopped because tracepoint TPNUM exceeded its pass
6495
          count.
6496
 
6497
    `terror:TEXT:TPNUM'
6498
          The trace stopped because tracepoint TPNUM had an error.  The
6499
          string TEXT is available to describe the nature of the error
6500
          (for instance, a divide by zero in the condition expression).
6501
          TEXT is hex encoded.
6502
 
6503
    `tunknown:0'
6504
          The trace stopped for some other reason.
6505
 
6506
 
6507
     Additional optional fields supply statistical and other
6508
     information.  Although not required, they are extremely useful for
6509
     users monitoring the progress of a trace run.  If a trace has
6510
     stopped, and these numbers are reported, they must reflect the
6511
     state of the just-stopped trace.
6512
 
6513
    `tframes:N'
6514
          The number of trace frames in the buffer.
6515
 
6516
    `tcreated:N'
6517
          The total number of trace frames created during the run. This
6518
          may be larger than the trace frame count, if the buffer is
6519
          circular.
6520
 
6521
    `tsize:N'
6522
          The total size of the trace buffer, in bytes.
6523
 
6524
    `tfree:N'
6525
          The number of bytes still unused in the buffer.
6526
 
6527
    `circular:N'
6528
          The value of the circular trace buffer flag.  `1' means that
6529
          the trace buffer is circular and old trace frames will be
6530
          discarded if necessary to make room, `0' means that the trace
6531
          buffer is linear and may fill up.
6532
 
6533
    `disconn:N'
6534
          The value of the disconnected tracing flag.  `1' means that
6535
          tracing will continue after GDB disconnects, `0' means that
6536
          the trace run will stop.
6537
 
6538
 
6539
`qTV:VAR'
6540
     Ask the stub for the value of the trace state variable number VAR.
6541
 
6542
     Replies:
6543
    `VVALUE'
6544
          The value of the variable is VALUE.  This will be the current
6545
          value of the variable if the user is examining a running
6546
          target, or a saved value if the variable was collected in the
6547
          trace frame that the user is looking at.  Note that multiple
6548
          requests may result in different reply values, such as when
6549
          requesting values while the program is running.
6550
 
6551
    `U'
6552
          The value of the variable is unknown.  This would occur, for
6553
          example, if the user is examining a trace frame in which the
6554
          requested variable was not collected.
6555
 
6556
`qTfP'
6557
`qTsP'
6558
     These packets request data about tracepoints that are being used by
6559
     the target.  GDB sends `qTfP' to get the first piece of data, and
6560
     multiple `qTsP' to get additional pieces.  Replies to these
6561
     packets generally take the form of the `QTDP' packets that define
6562
     tracepoints. (FIXME add detailed syntax)
6563
 
6564
`qTfV'
6565
`qTsV'
6566
     These packets request data about trace state variables that are on
6567
     the target.  GDB sends `qTfV' to get the first vari of data, and
6568
     multiple `qTsV' to get additional variables.  Replies to these
6569
     packets follow the syntax of the `QTDV' packets that define trace
6570
     state variables.
6571
 
6572
`qTfSTM'
6573
`qTsSTM'
6574
     These packets request data about static tracepoint markers that
6575
     exist in the target program.  GDB sends `qTfSTM' to get the first
6576
     piece of data, and multiple `qTsSTM' to get additional pieces.
6577
     Replies to these packets take the following form:
6578
 
6579
     Reply:
6580
    `m ADDRESS:ID:EXTRA'
6581
          A single marker
6582
 
6583
    `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
6584
          a comma-separated list of markers
6585
 
6586
    `l'
6587
          (lower case letter `L') denotes end of list.
6588
 
6589
    `E NN'
6590
          An error occurred.  NN are hex digits.
6591
 
6592
    `'
6593
          An empty reply indicates that the request is not supported by
6594
          the stub.
6595
 
6596
     ADDRESS is encoded in hex.  ID and EXTRA are strings encoded in
6597
     hex.
6598
 
6599
     In response to each query, the target will reply with a list of
6600
     one or more markers, separated by commas.  GDB will respond to each
6601
     reply with a request for more markers (using the `qs' form of the
6602
     query), until the target responds with `l' (lower-case ell, for
6603
     "last").
6604
 
6605
`qTSTMat:ADDRESS'
6606
     This packets requests data about static tracepoint markers in the
6607
     target program at ADDRESS.  Replies to this packet follow the
6608
     syntax of the `qTfSTM' and `qTsSTM' packets that list static
6609
     tracepoint markers.
6610
 
6611
`QTSave:FILENAME'
6612
     This packet directs the target to save trace data to the file name
6613
     FILENAME in the target's filesystem.  FILENAME is encoded as a hex
6614
     string; the interpretation of the file name (relative vs absolute,
6615
     wild cards, etc) is up to the target.
6616
 
6617
`qTBuffer:OFFSET,LEN'
6618
     Return up to LEN bytes of the current contents of trace buffer,
6619
     starting at OFFSET.  The trace buffer is treated as if it were a
6620
     contiguous collection of traceframes, as per the trace file format.
6621
     The reply consists as many hex-encoded bytes as the target can
6622
     deliver in a packet; it is not an error to return fewer than were
6623
     asked for.  A reply consisting of just `l' indicates that no bytes
6624
     are available.
6625
 
6626
`QTBuffer:circular:VALUE'
6627
     This packet directs the target to use a circular trace buffer if
6628
     VALUE is 1, or a linear buffer if the value is 0.
6629
 
6630
 
6631
D.6.1 Relocate instruction reply packet
6632
---------------------------------------
6633
 
6634
When installing fast tracepoints in memory, the target may need to
6635
relocate the instruction currently at the tracepoint address to a
6636
different address in memory.  For most instructions, a simple copy is
6637
enough, but, for example, call instructions that implicitly push the
6638
return address on the stack, and relative branches or other PC-relative
6639
instructions require offset adjustment, so that the effect of executing
6640
the instruction at a different address is the same as if it had
6641
executed in the original location.
6642
 
6643
   In response to several of the tracepoint packets, the target may also
6644
respond with a number of intermediate `qRelocInsn' request packets
6645
before the final result packet, to have GDB handle this relocation
6646
operation.  If a packet supports this mechanism, its documentation will
6647
explicitly say so.  See for example the above descriptions for the
6648
`QTStart' and `QTDP' packets.  The format of the request is:
6649
 
6650
`qRelocInsn:FROM;TO'
6651
     This requests GDB to copy instruction at address FROM to address
6652
     TO, possibly adjusted so that executing the instruction at TO has
6653
     the same effect as executing it at FROM.  GDB writes the adjusted
6654
     instruction to target memory starting at TO.
6655
 
6656
   Replies:
6657
`qRelocInsn:ADJUSTED_SIZE'
6658
     Informs the stub the relocation is complete.  ADJUSTED_SIZE is the
6659
     length in bytes of resulting relocated instruction sequence.
6660
 
6661
`E NN'
6662
     A badly formed request was detected, or an error was encountered
6663
     while relocating the instruction.
6664
 
6665

6666
File: gdb.info,  Node: Host I/O Packets,  Next: Interrupts,  Prev: Tracepoint Packets,  Up: Remote Protocol
6667
 
6668
D.7 Host I/O Packets
6669
====================
6670
 
6671
The "Host I/O" packets allow GDB to perform I/O operations on the far
6672
side of a remote link.  For example, Host I/O is used to upload and
6673
download files to a remote target with its own filesystem.  Host I/O
6674
uses the same constant values and data structure layout as the
6675
target-initiated File-I/O protocol.  However, the Host I/O packets are
6676
structured differently.  The target-initiated protocol relies on target
6677
memory to store parameters and buffers.  Host I/O requests are
6678
initiated by GDB, and the target's memory is not involved.  *Note
6679
File-I/O Remote Protocol Extension::, for more details on the
6680
target-initiated protocol.
6681
 
6682
   The Host I/O request packets all encode a single operation along with
6683
its arguments.  They have this format:
6684
 
6685
`vFile:OPERATION: PARAMETER...'
6686
     OPERATION is the name of the particular request; the target should
6687
     compare the entire packet name up to the second colon when checking
6688
     for a supported operation.  The format of PARAMETER depends on the
6689
     operation.  Numbers are always passed in hexadecimal.  Negative
6690
     numbers have an explicit minus sign (i.e. two's complement is not
6691
     used).  Strings (e.g. filenames) are encoded as a series of
6692
     hexadecimal bytes.  The last argument to a system call may be a
6693
     buffer of escaped binary data (*note Binary Data::).
6694
 
6695
 
6696
   The valid responses to Host I/O packets are:
6697
 
6698
`F RESULT [, ERRNO] [; ATTACHMENT]'
6699
     RESULT is the integer value returned by this operation, usually
6700
     non-negative for success and -1 for errors.  If an error has
6701
     occured, ERRNO will be included in the result.  ERRNO will have a
6702
     value defined by the File-I/O protocol (*note Errno Values::).  For
6703
     operations which return data, ATTACHMENT supplies the data as a
6704
     binary buffer.  Binary buffers in response packets are escaped in
6705
     the normal way (*note Binary Data::).  See the individual packet
6706
     documentation for the interpretation of RESULT and ATTACHMENT.
6707
 
6708
`'
6709
     An empty response indicates that this operation is not recognized.
6710
 
6711
 
6712
   These are the supported Host I/O operations:
6713
 
6714
`vFile:open: PATHNAME, FLAGS, MODE'
6715
     Open a file at PATHNAME and return a file descriptor for it, or
6716
     return -1 if an error occurs.  PATHNAME is a string, FLAGS is an
6717
     integer indicating a mask of open flags (*note Open Flags::), and
6718
     MODE is an integer indicating a mask of mode bits to use if the
6719
     file is created (*note mode_t Values::).  *Note open::, for
6720
     details of the open flags and mode values.
6721
 
6722
`vFile:close: FD'
6723
     Close the open file corresponding to FD and return 0, or -1 if an
6724
     error occurs.
6725
 
6726
`vFile:pread: FD, COUNT, OFFSET'
6727
     Read data from the open file corresponding to FD.  Up to COUNT
6728
     bytes will be read from the file, starting at OFFSET relative to
6729
     the start of the file.  The target may read fewer bytes; common
6730
     reasons include packet size limits and an end-of-file condition.
6731
     The number of bytes read is returned.  Zero should only be
6732
     returned for a successful read at the end of the file, or if COUNT
6733
     was zero.
6734
 
6735
     The data read should be returned as a binary attachment on success.
6736
     If zero bytes were read, the response should include an empty
6737
     binary attachment (i.e. a trailing semicolon).  The return value
6738
     is the number of target bytes read; the binary attachment may be
6739
     longer if some characters were escaped.
6740
 
6741
`vFile:pwrite: FD, OFFSET, DATA'
6742
     Write DATA (a binary buffer) to the open file corresponding to FD.
6743 342 jeremybenn
     Start the write at OFFSET from the start of the file.  Unlike many
6744
     `write' system calls, there is no separate COUNT argument; the
6745
     length of DATA in the packet is used.  `vFile:write' returns the
6746
     number of bytes written, which may be shorter than the length of
6747
     DATA, or -1 if an error occurred.
6748 330 jeremybenn
 
6749
`vFile:unlink: PATHNAME'
6750
     Delete the file at PATHNAME on the target.  Return 0, or -1 if an
6751
     error occurs.  PATHNAME is a string.
6752
 
6753
 
6754

6755
File: gdb.info,  Node: Interrupts,  Next: Notification Packets,  Prev: Host I/O Packets,  Up: Remote Protocol
6756
 
6757
D.8 Interrupts
6758
==============
6759
 
6760
When a program on the remote target is running, GDB may attempt to
6761
interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by
6762
`g', control of which is specified via GDB's `interrupt-sequence'.
6763
 
6764
   The precise meaning of `BREAK' is defined by the transport mechanism
6765
and may, in fact, be undefined.  GDB does not currently define a
6766
`BREAK' mechanism for any of the network interfaces except for TCP, in
6767
which case GDB sends the `telnet' BREAK sequence.
6768
 
6769
   `Ctrl-C', on the other hand, is defined and implemented for all
6770
transport mechanisms.  It is represented by sending the single byte
6771
`0x03' without any of the usual packet overhead described in the
6772
Overview section (*note Overview::).  When a `0x03' byte is transmitted
6773
as part of a packet, it is considered to be packet data and does _not_
6774
represent an interrupt.  E.g., an `X' packet (*note X packet::), used
6775
for binary downloads, may include an unescaped `0x03' as part of its
6776
packet.
6777
 
6778
   `BREAK' followed by `g' is also known as Magic SysRq g.  When Linux
6779
kernel receives this sequence from serial port, it stops execution and
6780
connects to gdb.
6781
 
6782
   Stubs are not required to recognize these interrupt mechanisms and
6783
the precise meaning associated with receipt of the interrupt is
6784
implementation defined.  If the target supports debugging of multiple
6785
threads and/or processes, it should attempt to interrupt all
6786
currently-executing threads and processes.  If the stub is successful
6787
at interrupting the running program, it should send one of the stop
6788
reply packets (*note Stop Reply Packets::) to GDB as a result of
6789
successfully stopping the program in all-stop mode, and a stop reply
6790
for each stopped thread in non-stop mode.  Interrupts received while the
6791
program is stopped are discarded.
6792
 
6793

6794
File: gdb.info,  Node: Notification Packets,  Next: Remote Non-Stop,  Prev: Interrupts,  Up: Remote Protocol
6795
 
6796
D.9 Notification Packets
6797
========================
6798
 
6799
The GDB remote serial protocol includes "notifications", packets that
6800
require no acknowledgment.  Both the GDB and the stub may send
6801
notifications (although the only notifications defined at present are
6802
sent by the stub).  Notifications carry information without incurring
6803
the round-trip latency of an acknowledgment, and so are useful for
6804
low-impact communications where occasional packet loss is not a problem.
6805
 
6806
   A notification packet has the form `% DATA # CHECKSUM', where DATA
6807
is the content of the notification, and CHECKSUM is a checksum of DATA,
6808
computed and formatted as for ordinary GDB packets.  A notification's
6809
DATA never contains `$', `%' or `#' characters.  Upon receiving a
6810
notification, the recipient sends no `+' or `-' to acknowledge the
6811
notification's receipt or to report its corruption.
6812
 
6813
   Every notification's DATA begins with a name, which contains no
6814
colon characters, followed by a colon character.
6815
 
6816
   Recipients should silently ignore corrupted notifications and
6817
notifications they do not understand.  Recipients should restart
6818
timeout periods on receipt of a well-formed notification, whether or
6819
not they understand it.
6820
 
6821
   Senders should only send the notifications described here when this
6822
protocol description specifies that they are permitted.  In the future,
6823
we may extend the protocol to permit existing notifications in new
6824
contexts; this rule helps older senders avoid confusing newer
6825
recipients.
6826
 
6827
   (Older versions of GDB ignore bytes received until they see the `$'
6828
byte that begins an ordinary packet, so new stubs may transmit
6829
notifications without fear of confusing older clients.  There are no
6830
notifications defined for GDB to send at the moment, but we assume that
6831
most older stubs would ignore them, as well.)
6832
 
6833
   The following notification packets from the stub to GDB are defined:
6834
 
6835
`Stop: REPLY'
6836
     Report an asynchronous stop event in non-stop mode.  The REPLY has
6837 342 jeremybenn
     the form of a stop reply, as described in *note Stop Reply
6838
     Packets::.  Refer to *note Remote Non-Stop::, for information on
6839 330 jeremybenn
     how these notifications are acknowledged by GDB.
6840
 
6841

6842
File: gdb.info,  Node: Remote Non-Stop,  Next: Packet Acknowledgment,  Prev: Notification Packets,  Up: Remote Protocol
6843
 
6844
D.10 Remote Protocol Support for Non-Stop Mode
6845
==============================================
6846
 
6847
GDB's remote protocol supports non-stop debugging of multi-threaded
6848 342 jeremybenn
programs, as described in *note Non-Stop Mode::.  If the stub supports
6849 330 jeremybenn
non-stop mode, it should report that to GDB by including `QNonStop+' in
6850
its `qSupported' response (*note qSupported::).
6851
 
6852
   GDB typically sends a `QNonStop' packet only when establishing a new
6853
connection with the stub.  Entering non-stop mode does not alter the
6854
state of any currently-running threads, but targets must stop all
6855
threads in any already-attached processes when entering all-stop mode.
6856
GDB uses the `?' packet as necessary to probe the target state after a
6857
mode change.
6858
 
6859
   In non-stop mode, when an attached process encounters an event that
6860
would otherwise be reported with a stop reply, it uses the asynchronous
6861
notification mechanism (*note Notification Packets::) to inform GDB.
6862
In contrast to all-stop mode, where all threads in all processes are
6863
stopped when a stop reply is sent, in non-stop mode only the thread
6864
reporting the stop event is stopped.  That is, when reporting a `S' or
6865
`T' response to indicate completion of a step operation, hitting a
6866
breakpoint, or a fault, only the affected thread is stopped; any other
6867
still-running threads continue to run.  When reporting a `W' or `X'
6868
response, all running threads belonging to other attached processes
6869
continue to run.
6870
 
6871
   Only one stop reply notification at a time may be pending; if
6872
additional stop events occur before GDB has acknowledged the previous
6873
notification, they must be queued by the stub for later synchronous
6874
transmission in response to `vStopped' packets from GDB.  Because the
6875
notification mechanism is unreliable, the stub is permitted to resend a
6876
stop reply notification if it believes GDB may not have received it.
6877
GDB ignores additional stop reply notifications received before it has
6878
finished processing a previous notification and the stub has completed
6879
sending any queued stop events.
6880
 
6881
   Otherwise, GDB must be prepared to receive a stop reply notification
6882
at any time.  Specifically, they may appear when GDB is not otherwise
6883
reading input from the stub, or when GDB is expecting to read a normal
6884
synchronous response or a `+'/`-' acknowledgment to a packet it has
6885
sent.  Notification packets are distinct from any other communication
6886
from the stub so there is no ambiguity.
6887
 
6888
   After receiving a stop reply notification, GDB shall acknowledge it
6889
by sending a `vStopped' packet (*note vStopped packet::) as a regular,
6890
synchronous request to the stub.  Such acknowledgment is not required
6891
to happen immediately, as GDB is permitted to send other, unrelated
6892
packets to the stub first, which the stub should process normally.
6893
 
6894
   Upon receiving a `vStopped' packet, if the stub has other queued
6895
stop events to report to GDB, it shall respond by sending a normal stop
6896
reply response.  GDB shall then send another `vStopped' packet to
6897
solicit further responses; again, it is permitted to send other,
6898
unrelated packets as well which the stub should process normally.
6899
 
6900
   If the stub receives a `vStopped' packet and there are no additional
6901
stop events to report, the stub shall return an `OK' response.  At this
6902
point, if further stop events occur, the stub shall send a new stop
6903
reply notification, GDB shall accept the notification, and the process
6904
shall be repeated.
6905
 
6906
   In non-stop mode, the target shall respond to the `?' packet as
6907
follows.  First, any incomplete stop reply notification/`vStopped'
6908
sequence in progress is abandoned.  The target must begin a new
6909
sequence reporting stop events for all stopped threads, whether or not
6910
it has previously reported those events to GDB.  The first stop reply
6911
is sent as a synchronous reply to the `?' packet, and subsequent stop
6912
replies are sent as responses to `vStopped' packets using the mechanism
6913
described above.  The target must not send asynchronous stop reply
6914
notifications until the sequence is complete.  If all threads are
6915
running when the target receives the `?' packet, or if the target is
6916
not attached to any process, it shall respond `OK'.
6917
 
6918

6919
File: gdb.info,  Node: Packet Acknowledgment,  Next: Examples,  Prev: Remote Non-Stop,  Up: Remote Protocol
6920
 
6921
D.11 Packet Acknowledgment
6922
==========================
6923
 
6924
By default, when either the host or the target machine receives a
6925
packet, the first response expected is an acknowledgment: either `+'
6926
(to indicate the package was received correctly) or `-' (to request
6927
retransmission).  This mechanism allows the GDB remote protocol to
6928
operate over unreliable transport mechanisms, such as a serial line.
6929
 
6930
   In cases where the transport mechanism is itself reliable (such as a
6931
pipe or TCP connection), the `+'/`-' acknowledgments are redundant.  It
6932
may be desirable to disable them in that case to reduce communication
6933
overhead, or for other reasons.  This can be accomplished by means of
6934
the `QStartNoAckMode' packet; *note QStartNoAckMode::.
6935
 
6936
   When in no-acknowledgment mode, neither the stub nor GDB shall send
6937
or expect `+'/`-' protocol acknowledgments.  The packet and response
6938 342 jeremybenn
format still includes the normal checksum, as described in *note
6939 330 jeremybenn
Overview::, but the checksum may be ignored by the receiver.
6940
 
6941
   If the stub supports `QStartNoAckMode' and prefers to operate in
6942
no-acknowledgment mode, it should report that to GDB by including
6943
`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::.
6944
If GDB also supports `QStartNoAckMode' and it has not been disabled via
6945
the `set remote noack-packet off' command (*note Remote
6946
Configuration::), GDB may then send a `QStartNoAckMode' packet to the
6947
stub.  Only then may the stub actually turn off packet acknowledgments.
6948
GDB sends a final `+' acknowledgment of the stub's `OK' response, which
6949
can be safely ignored by the stub.
6950
 
6951
   Note that `set remote noack-packet' command only affects negotiation
6952
between GDB and the stub when subsequent connections are made; it does
6953
not affect the protocol acknowledgment state for any current connection.
6954
Since `+'/`-' acknowledgments are enabled by default when a new
6955
connection is established, there is also no protocol request to
6956
re-enable the acknowledgments for the current connection, once disabled.
6957
 
6958

6959
File: gdb.info,  Node: Examples,  Next: File-I/O Remote Protocol Extension,  Prev: Packet Acknowledgment,  Up: Remote Protocol
6960
 
6961
D.12 Examples
6962
=============
6963
 
6964
Example sequence of a target being re-started.  Notice how the restart
6965
does not get any direct output:
6966
 
6967
     -> `R00'
6968
     <- `+'
6969
     _target restarts_
6970
     -> `?'
6971
     <- `+'
6972
     <- `T001:1234123412341234'
6973
     -> `+'
6974
 
6975
   Example sequence of a target being stepped by a single instruction:
6976
 
6977
     -> `G1445...'
6978
     <- `+'
6979
     -> `s'
6980
     <- `+'
6981
     _time passes_
6982
     <- `T001:1234123412341234'
6983
     -> `+'
6984
     -> `g'
6985
     <- `+'
6986
     <- `1455...'
6987
     -> `+'
6988
 
6989

6990
File: gdb.info,  Node: File-I/O Remote Protocol Extension,  Next: Library List Format,  Prev: Examples,  Up: Remote Protocol
6991
 
6992
D.13 File-I/O Remote Protocol Extension
6993
=======================================
6994
 
6995
* Menu:
6996
 
6997
* File-I/O Overview::
6998
* Protocol Basics::
6999
* The F Request Packet::
7000
* The F Reply Packet::
7001
* The Ctrl-C Message::
7002
* Console I/O::
7003
* List of Supported Calls::
7004
* Protocol-specific Representation of Datatypes::
7005
* Constants::
7006
* File-I/O Examples::
7007
 
7008

7009
File: gdb.info,  Node: File-I/O Overview,  Next: Protocol Basics,  Up: File-I/O Remote Protocol Extension
7010
 
7011
D.13.1 File-I/O Overview
7012
------------------------
7013
 
7014
The "File I/O remote protocol extension" (short: File-I/O) allows the
7015
target to use the host's file system and console I/O to perform various
7016
system calls.  System calls on the target system are translated into a
7017
remote protocol packet to the host system, which then performs the
7018
needed actions and returns a response packet to the target system.
7019
This simulates file system operations even on targets that lack file
7020
systems.
7021
 
7022
   The protocol is defined to be independent of both the host and
7023
target systems.  It uses its own internal representation of datatypes
7024
and values.  Both GDB and the target's GDB stub are responsible for
7025
translating the system-dependent value representations into the internal
7026
protocol representations when data is transmitted.
7027
 
7028
   The communication is synchronous.  A system call is possible only
7029
when GDB is waiting for a response from the `C', `c', `S' or `s'
7030
packets.  While GDB handles the request for a system call, the target
7031
is stopped to allow deterministic access to the target's memory.
7032
Therefore File-I/O is not interruptible by target signals.  On the
7033
other hand, it is possible to interrupt File-I/O by a user interrupt
7034
(`Ctrl-C') within GDB.
7035
 
7036
   The target's request to perform a host system call does not finish
7037
the latest `C', `c', `S' or `s' action.  That means, after finishing
7038
the system call, the target returns to continuing the previous activity
7039
(continue, step).  No additional continue or step request from GDB is
7040
required.
7041
 
7042
     (gdb) continue
7043
       <- target requests 'system call X'
7044
       target is stopped, GDB executes system call
7045
       -> GDB returns result
7046
       ... target continues, GDB returns to wait for the target
7047
       <- target hits breakpoint and sends a Txx packet
7048
 
7049
   The protocol only supports I/O on the console and to regular files on
7050
the host file system.  Character or block special devices, pipes, named
7051
pipes, sockets or any other communication method on the host system are
7052
not supported by this protocol.
7053
 
7054
   File I/O is not supported in non-stop mode.
7055
 
7056

7057
File: gdb.info,  Node: Protocol Basics,  Next: The F Request Packet,  Prev: File-I/O Overview,  Up: File-I/O Remote Protocol Extension
7058
 
7059
D.13.2 Protocol Basics
7060
----------------------
7061
 
7062
The File-I/O protocol uses the `F' packet as the request as well as
7063
reply packet.  Since a File-I/O system call can only occur when GDB is
7064
waiting for a response from the continuing or stepping target, the
7065
File-I/O request is a reply that GDB has to expect as a result of a
7066
previous `C', `c', `S' or `s' packet.  This `F' packet contains all
7067
information needed to allow GDB to call the appropriate host system
7068
call:
7069
 
7070
   * A unique identifier for the requested system call.
7071
 
7072
   * All parameters to the system call.  Pointers are given as addresses
7073
     in the target memory address space.  Pointers to strings are given
7074
     as pointer/length pair.  Numerical values are given as they are.
7075
     Numerical control flags are given in a protocol-specific
7076
     representation.
7077
 
7078
 
7079
   At this point, GDB has to perform the following actions.
7080
 
7081
   * If the parameters include pointer values to data needed as input
7082
     to a system call, GDB requests this data from the target with a
7083
     standard `m' packet request.  This additional communication has to
7084
     be expected by the target implementation and is handled as any
7085
     other `m' packet.
7086
 
7087
   * GDB translates all value from protocol representation to host
7088
     representation as needed.  Datatypes are coerced into the host
7089
     types.
7090
 
7091
   * GDB calls the system call.
7092
 
7093
   * It then coerces datatypes back to protocol representation.
7094
 
7095
   * If the system call is expected to return data in buffer space
7096
     specified by pointer parameters to the call, the data is
7097
     transmitted to the target using a `M' or `X' packet.  This packet
7098
     has to be expected by the target implementation and is handled as
7099
     any other `M' or `X' packet.
7100
 
7101
 
7102
   Eventually GDB replies with another `F' packet which contains all
7103
necessary information for the target to continue.  This at least
7104
contains
7105
 
7106
   * Return value.
7107
 
7108
   * `errno', if has been changed by the system call.
7109
 
7110
   * "Ctrl-C" flag.
7111
 
7112
 
7113
   After having done the needed type and value coercion, the target
7114
continues the latest continue or step action.
7115
 
7116

7117
File: gdb.info,  Node: The F Request Packet,  Next: The F Reply Packet,  Prev: Protocol Basics,  Up: File-I/O Remote Protocol Extension
7118
 
7119
D.13.3 The `F' Request Packet
7120
-----------------------------
7121
 
7122
The `F' request packet has the following format:
7123
 
7124
`FCALL-ID,PARAMETER...'
7125
     CALL-ID is the identifier to indicate the host system call to be
7126
     called.  This is just the name of the function.
7127
 
7128
     PARAMETER... are the parameters to the system call.  Parameters
7129
     are hexadecimal integer values, either the actual values in case
7130
     of scalar datatypes, pointers to target buffer space in case of
7131
     compound datatypes and unspecified memory areas, or pointer/length
7132
     pairs in case of string parameters.  These are appended to the
7133
     CALL-ID as a comma-delimited list.  All values are transmitted in
7134
     ASCII string representation, pointer/length pairs separated by a
7135
     slash.
7136
 
7137
 
7138

7139
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
7140
 
7141
D.13.4 The `F' Reply Packet
7142
---------------------------
7143
 
7144
The `F' reply packet has the following format:
7145
 
7146
`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
7147
     RETCODE is the return code of the system call as hexadecimal value.
7148
 
7149
     ERRNO is the `errno' set by the call, in protocol-specific
7150
     representation.  This parameter can be omitted if the call was
7151
     successful.
7152
 
7153
     CTRL-C FLAG is only sent if the user requested a break.  In this
7154
     case, ERRNO must be sent as well, even if the call was successful.
7155
     The CTRL-C FLAG itself consists of the character `C':
7156
 
7157
          F0,0,C
7158
 
7159
     or, if the call was interrupted before the host call has been
7160
     performed:
7161
 
7162
          F-1,4,C
7163
 
7164
     assuming 4 is the protocol-specific representation of `EINTR'.
7165
 
7166
 
7167

7168
File: gdb.info,  Node: The Ctrl-C Message,  Next: Console I/O,  Prev: The F Reply Packet,  Up: File-I/O Remote Protocol Extension
7169
 
7170
D.13.5 The `Ctrl-C' Message
7171
---------------------------
7172
 
7173
If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
7174
Packet::), the target should behave as if it had gotten a break
7175
message.  The meaning for the target is "system call interrupted by
7176
`SIGINT'".  Consequentially, the target should actually stop (as with a
7177
break message) and return to GDB with a `T02' packet.
7178
 
7179
   It's important for the target to know in which state the system call
7180
was interrupted.  There are two possible cases:
7181
 
7182
   * The system call hasn't been performed on the host yet.
7183
 
7184
   * The system call on the host has been finished.
7185
 
7186
 
7187
   These two states can be distinguished by the target by the value of
7188
the returned `errno'.  If it's the protocol representation of `EINTR',
7189
the system call hasn't been performed.  This is equivalent to the
7190
`EINTR' handling on POSIX systems.  In any other case, the target may
7191
presume that the system call has been finished -- successfully or not
7192
-- and should behave as if the break message arrived right after the
7193
system call.
7194
 
7195
   GDB must behave reliably.  If the system call has not been called
7196
yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
7197
in the packet.  If the system call on the host has been finished before
7198
the user requests a break, the full action must be finished by GDB.
7199
This requires sending `M' or `X' packets as necessary.  The `F' packet
7200
may only be sent when either nothing has happened or the full action
7201
has been completed.
7202
 
7203

7204
File: gdb.info,  Node: Console I/O,  Next: List of Supported Calls,  Prev: The Ctrl-C Message,  Up: File-I/O Remote Protocol Extension
7205
 
7206
D.13.6 Console I/O
7207
------------------
7208
 
7209
By default and if not explicitly closed by the target system, the file
7210
descriptors 0, 1 and 2 are connected to the GDB console.  Output on the
7211
GDB console is handled as any other file output operation (`write(1,
7212
...)' or `write(2, ...)').  Console input is handled by GDB so that
7213
after the target read request from file descriptor 0 all following
7214
typing is buffered until either one of the following conditions is met:
7215
 
7216
   * The user types `Ctrl-c'.  The behaviour is as explained above, and
7217
     the `read' system call is treated as finished.
7218
 
7219
   * The user presses .  This is treated as end of input with a
7220
     trailing newline.
7221
 
7222
   * The user types `Ctrl-d'.  This is treated as end of input.  No
7223
     trailing character (neither newline nor `Ctrl-D') is appended to
7224
     the input.
7225
 
7226
 
7227
   If the user has typed more characters than fit in the buffer given to
7228
the `read' call, the trailing characters are buffered in GDB until
7229
either another `read(0, ...)' is requested by the target, or debugging
7230
is stopped at the user's request.
7231
 
7232

7233
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
7234
 
7235
D.13.7 List of Supported Calls
7236
------------------------------
7237
 
7238
* Menu:
7239
 
7240
* open::
7241
* close::
7242
* read::
7243
* write::
7244
* lseek::
7245
* rename::
7246
* unlink::
7247
* stat/fstat::
7248
* gettimeofday::
7249
* isatty::
7250
* system::
7251
 
7252

7253
File: gdb.info,  Node: open,  Next: close,  Up: List of Supported Calls
7254
 
7255
open
7256
....
7257
 
7258
Synopsis:
7259
          int open(const char *pathname, int flags);
7260
          int open(const char *pathname, int flags, mode_t mode);
7261
 
7262
Request:
7263
     `Fopen,PATHPTR/LEN,FLAGS,MODE'
7264
 
7265
     FLAGS is the bitwise `OR' of the following values:
7266
 
7267
    `O_CREAT'
7268
          If the file does not exist it will be created.  The host
7269
          rules apply as far as file ownership and time stamps are
7270
          concerned.
7271
 
7272
    `O_EXCL'
7273
          When used with `O_CREAT', if the file already exists it is an
7274
          error and open() fails.
7275
 
7276
    `O_TRUNC'
7277
          If the file already exists and the open mode allows writing
7278
          (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
7279
          zero length.
7280
 
7281
    `O_APPEND'
7282
          The file is opened in append mode.
7283
 
7284
    `O_RDONLY'
7285
          The file is opened for reading only.
7286
 
7287
    `O_WRONLY'
7288
          The file is opened for writing only.
7289
 
7290
    `O_RDWR'
7291
          The file is opened for reading and writing.
7292
 
7293
     Other bits are silently ignored.
7294
 
7295
     MODE is the bitwise `OR' of the following values:
7296
 
7297
    `S_IRUSR'
7298
          User has read permission.
7299
 
7300
    `S_IWUSR'
7301
          User has write permission.
7302
 
7303
    `S_IRGRP'
7304
          Group has read permission.
7305
 
7306
    `S_IWGRP'
7307
          Group has write permission.
7308
 
7309
    `S_IROTH'
7310
          Others have read permission.
7311
 
7312
    `S_IWOTH'
7313
          Others have write permission.
7314
 
7315
     Other bits are silently ignored.
7316
 
7317
Return value:
7318
     `open' returns the new file descriptor or -1 if an error occurred.
7319
 
7320
Errors:
7321
 
7322
    `EEXIST'
7323
          PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
7324
 
7325
    `EISDIR'
7326
          PATHNAME refers to a directory.
7327
 
7328
    `EACCES'
7329
          The requested access is not allowed.
7330
 
7331
    `ENAMETOOLONG'
7332
          PATHNAME was too long.
7333
 
7334
    `ENOENT'
7335
          A directory component in PATHNAME does not exist.
7336
 
7337
    `ENODEV'
7338
          PATHNAME refers to a device, pipe, named pipe or socket.
7339
 
7340
    `EROFS'
7341
          PATHNAME refers to a file on a read-only filesystem and write
7342
          access was requested.
7343
 
7344
    `EFAULT'
7345
          PATHNAME is an invalid pointer value.
7346
 
7347
    `ENOSPC'
7348
          No space on device to create the file.
7349
 
7350
    `EMFILE'
7351
          The process already has the maximum number of files open.
7352
 
7353
    `ENFILE'
7354
          The limit on the total number of files open on the system has
7355
          been reached.
7356
 
7357
    `EINTR'
7358
          The call was interrupted by the user.
7359
 
7360
 
7361

7362
File: gdb.info,  Node: close,  Next: read,  Prev: open,  Up: List of Supported Calls
7363
 
7364
close
7365
.....
7366
 
7367
Synopsis:
7368
          int close(int fd);
7369
 
7370
Request:
7371
     `Fclose,FD'
7372
 
7373
Return value:
7374
     `close' returns zero on success, or -1 if an error occurred.
7375
 
7376
Errors:
7377
 
7378
    `EBADF'
7379
          FD isn't a valid open file descriptor.
7380
 
7381
    `EINTR'
7382
          The call was interrupted by the user.
7383
 
7384
 
7385

7386
File: gdb.info,  Node: read,  Next: write,  Prev: close,  Up: List of Supported Calls
7387
 
7388
read
7389
....
7390
 
7391
Synopsis:
7392
          int read(int fd, void *buf, unsigned int count);
7393
 
7394
Request:
7395
     `Fread,FD,BUFPTR,COUNT'
7396
 
7397
Return value:
7398
     On success, the number of bytes read is returned.  Zero indicates
7399
     end of file.  If count is zero, read returns zero as well.  On
7400
     error, -1 is returned.
7401
 
7402
Errors:
7403
 
7404
    `EBADF'
7405
          FD is not a valid file descriptor or is not open for reading.
7406
 
7407
    `EFAULT'
7408
          BUFPTR is an invalid pointer value.
7409
 
7410
    `EINTR'
7411
          The call was interrupted by the user.
7412
 
7413
 
7414

7415
File: gdb.info,  Node: write,  Next: lseek,  Prev: read,  Up: List of Supported Calls
7416
 
7417
write
7418
.....
7419
 
7420
Synopsis:
7421
          int write(int fd, const void *buf, unsigned int count);
7422
 
7423
Request:
7424
     `Fwrite,FD,BUFPTR,COUNT'
7425
 
7426
Return value:
7427
     On success, the number of bytes written are returned.  Zero
7428
     indicates nothing was written.  On error, -1 is returned.
7429
 
7430
Errors:
7431
 
7432
    `EBADF'
7433
          FD is not a valid file descriptor or is not open for writing.
7434
 
7435
    `EFAULT'
7436
          BUFPTR is an invalid pointer value.
7437
 
7438
    `EFBIG'
7439
          An attempt was made to write a file that exceeds the
7440
          host-specific maximum file size allowed.
7441
 
7442
    `ENOSPC'
7443
          No space on device to write the data.
7444
 
7445
    `EINTR'
7446
          The call was interrupted by the user.
7447
 
7448
 
7449

7450
File: gdb.info,  Node: lseek,  Next: rename,  Prev: write,  Up: List of Supported Calls
7451
 
7452
lseek
7453
.....
7454
 
7455
Synopsis:
7456
          long lseek (int fd, long offset, int flag);
7457
 
7458
Request:
7459
     `Flseek,FD,OFFSET,FLAG'
7460
 
7461
     FLAG is one of:
7462
 
7463
    `SEEK_SET'
7464
          The offset is set to OFFSET bytes.
7465
 
7466
    `SEEK_CUR'
7467
          The offset is set to its current location plus OFFSET bytes.
7468
 
7469
    `SEEK_END'
7470
          The offset is set to the size of the file plus OFFSET bytes.
7471
 
7472
Return value:
7473
     On success, the resulting unsigned offset in bytes from the
7474
     beginning of the file is returned.  Otherwise, a value of -1 is
7475
     returned.
7476
 
7477
Errors:
7478
 
7479
    `EBADF'
7480
          FD is not a valid open file descriptor.
7481
 
7482
    `ESPIPE'
7483
          FD is associated with the GDB console.
7484
 
7485
    `EINVAL'
7486
          FLAG is not a proper value.
7487
 
7488
    `EINTR'
7489
          The call was interrupted by the user.
7490
 
7491
 
7492

7493
File: gdb.info,  Node: rename,  Next: unlink,  Prev: lseek,  Up: List of Supported Calls
7494
 
7495
rename
7496
......
7497
 
7498
Synopsis:
7499
          int rename(const char *oldpath, const char *newpath);
7500
 
7501
Request:
7502
     `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
7503
 
7504
Return value:
7505
     On success, zero is returned.  On error, -1 is returned.
7506
 
7507
Errors:
7508
 
7509
    `EISDIR'
7510
          NEWPATH is an existing directory, but OLDPATH is not a
7511
          directory.
7512
 
7513
    `EEXIST'
7514
          NEWPATH is a non-empty directory.
7515
 
7516
    `EBUSY'
7517
          OLDPATH or NEWPATH is a directory that is in use by some
7518
          process.
7519
 
7520
    `EINVAL'
7521
          An attempt was made to make a directory a subdirectory of
7522
          itself.
7523
 
7524
    `ENOTDIR'
7525
          A  component used as a directory in OLDPATH or new path is
7526
          not a directory.  Or OLDPATH is a directory and NEWPATH
7527
          exists but is not a directory.
7528
 
7529
    `EFAULT'
7530
          OLDPATHPTR or NEWPATHPTR are invalid pointer values.
7531
 
7532
    `EACCES'
7533
          No access to the file or the path of the file.
7534
 
7535
    `ENAMETOOLONG'
7536
          OLDPATH or NEWPATH was too long.
7537
 
7538
    `ENOENT'
7539
          A directory component in OLDPATH or NEWPATH does not exist.
7540
 
7541
    `EROFS'
7542
          The file is on a read-only filesystem.
7543
 
7544
    `ENOSPC'
7545
          The device containing the file has no room for the new
7546
          directory entry.
7547
 
7548
    `EINTR'
7549
          The call was interrupted by the user.
7550
 
7551
 
7552

7553
File: gdb.info,  Node: unlink,  Next: stat/fstat,  Prev: rename,  Up: List of Supported Calls
7554
 
7555
unlink
7556
......
7557
 
7558
Synopsis:
7559
          int unlink(const char *pathname);
7560
 
7561
Request:
7562
     `Funlink,PATHNAMEPTR/LEN'
7563
 
7564
Return value:
7565
     On success, zero is returned.  On error, -1 is returned.
7566
 
7567
Errors:
7568
 
7569
    `EACCES'
7570
          No access to the file or the path of the file.
7571
 
7572
    `EPERM'
7573
          The system does not allow unlinking of directories.
7574
 
7575
    `EBUSY'
7576
          The file PATHNAME cannot be unlinked because it's being used
7577
          by another process.
7578
 
7579
    `EFAULT'
7580
          PATHNAMEPTR is an invalid pointer value.
7581
 
7582
    `ENAMETOOLONG'
7583
          PATHNAME was too long.
7584
 
7585
    `ENOENT'
7586
          A directory component in PATHNAME does not exist.
7587
 
7588
    `ENOTDIR'
7589
          A component of the path is not a directory.
7590
 
7591
    `EROFS'
7592
          The file is on a read-only filesystem.
7593
 
7594
    `EINTR'
7595
          The call was interrupted by the user.
7596
 
7597
 
7598

7599
File: gdb.info,  Node: stat/fstat,  Next: gettimeofday,  Prev: unlink,  Up: List of Supported Calls
7600
 
7601
stat/fstat
7602
..........
7603
 
7604
Synopsis:
7605
          int stat(const char *pathname, struct stat *buf);
7606
          int fstat(int fd, struct stat *buf);
7607
 
7608
Request:
7609
     `Fstat,PATHNAMEPTR/LEN,BUFPTR'
7610
     `Ffstat,FD,BUFPTR'
7611
 
7612
Return value:
7613
     On success, zero is returned.  On error, -1 is returned.
7614
 
7615
Errors:
7616
 
7617
    `EBADF'
7618
          FD is not a valid open file.
7619
 
7620
    `ENOENT'
7621
          A directory component in PATHNAME does not exist or the path
7622
          is an empty string.
7623
 
7624
    `ENOTDIR'
7625
          A component of the path is not a directory.
7626
 
7627
    `EFAULT'
7628
          PATHNAMEPTR is an invalid pointer value.
7629
 
7630
    `EACCES'
7631
          No access to the file or the path of the file.
7632
 
7633
    `ENAMETOOLONG'
7634
          PATHNAME was too long.
7635
 
7636
    `EINTR'
7637
          The call was interrupted by the user.
7638
 
7639
 
7640

7641
File: gdb.info,  Node: gettimeofday,  Next: isatty,  Prev: stat/fstat,  Up: List of Supported Calls
7642
 
7643
gettimeofday
7644
............
7645
 
7646
Synopsis:
7647
          int gettimeofday(struct timeval *tv, void *tz);
7648
 
7649
Request:
7650
     `Fgettimeofday,TVPTR,TZPTR'
7651
 
7652
Return value:
7653
     On success, 0 is returned, -1 otherwise.
7654
 
7655
Errors:
7656
 
7657
    `EINVAL'
7658
          TZ is a non-NULL pointer.
7659
 
7660
    `EFAULT'
7661
          TVPTR and/or TZPTR is an invalid pointer value.
7662
 
7663
 
7664

7665
File: gdb.info,  Node: isatty,  Next: system,  Prev: gettimeofday,  Up: List of Supported Calls
7666
 
7667
isatty
7668
......
7669
 
7670
Synopsis:
7671
          int isatty(int fd);
7672
 
7673
Request:
7674
     `Fisatty,FD'
7675
 
7676
Return value:
7677
     Returns 1 if FD refers to the GDB console, 0 otherwise.
7678
 
7679
Errors:
7680
 
7681
    `EINTR'
7682
          The call was interrupted by the user.
7683
 
7684
 
7685
   Note that the `isatty' call is treated as a special case: it returns
7686
1 to the target if the file descriptor is attached to the GDB console,
7687
 
7688
implementing `ioctl' and would be more complex than needed.
7689
 
7690

7691
File: gdb.info,  Node: system,  Prev: isatty,  Up: List of Supported Calls
7692
 
7693
system
7694
......
7695
 
7696
Synopsis:
7697
          int system(const char *command);
7698
 
7699
Request:
7700
     `Fsystem,COMMANDPTR/LEN'
7701
 
7702
Return value:
7703
     If LEN is zero, the return value indicates whether a shell is
7704
     available.  A zero return value indicates a shell is not available.
7705
     For non-zero LEN, the value returned is -1 on error and the return
7706
     status of the command otherwise.  Only the exit status of the
7707
     command is returned, which is extracted from the host's `system'
7708
     return value by calling `WEXITSTATUS(retval)'.  In case `/bin/sh'
7709
     could not be executed, 127 is returned.
7710
 
7711
Errors:
7712
 
7713
    `EINTR'
7714
          The call was interrupted by the user.
7715
 
7716
 
7717
   GDB takes over the full task of calling the necessary host calls to
7718
perform the `system' call.  The return value of `system' on the host is
7719
simplified before it's returned to the target.  Any termination signal
7720
information from the child process is discarded, and the return value
7721
consists entirely of the exit status of the called command.
7722
 
7723
   Due to security concerns, the `system' call is by default refused by
7724
GDB.  The user has to allow this call explicitly with the `set remote
7725
system-call-allowed 1' command.
7726
 
7727
`set remote system-call-allowed'
7728
     Control whether to allow the `system' calls in the File I/O
7729
     protocol for the remote target.  The default is zero (disabled).
7730
 
7731
`show remote system-call-allowed'
7732
     Show whether the `system' calls are allowed in the File I/O
7733
     protocol.
7734
 
7735

7736
File: gdb.info,  Node: Protocol-specific Representation of Datatypes,  Next: Constants,  Prev: List of Supported Calls,  Up: File-I/O Remote Protocol Extension
7737
 
7738
D.13.8 Protocol-specific Representation of Datatypes
7739
----------------------------------------------------
7740
 
7741
* Menu:
7742
 
7743
* Integral Datatypes::
7744
* Pointer Values::
7745
* Memory Transfer::
7746
* struct stat::
7747
* struct timeval::
7748
 
7749

7750
File: gdb.info,  Node: Integral Datatypes,  Next: Pointer Values,  Up: Protocol-specific Representation of Datatypes
7751
 
7752
Integral Datatypes
7753
..................
7754
 
7755
The integral datatypes used in the system calls are `int', `unsigned
7756
int', `long', `unsigned long', `mode_t', and `time_t'.
7757
 
7758
   `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
7759
bit values in this protocol.
7760
 
7761
   `long' and `unsigned long' are implemented as 64 bit types.
7762
 
7763
   *Note Limits::, for corresponding MIN and MAX values (similar to
7764
those in `limits.h') to allow range checking on host and target.
7765
 
7766
   `time_t' datatypes are defined as seconds since the Epoch.
7767
 
7768
   All integral datatypes transferred as part of a memory read or write
7769
of a structured datatype e.g. a `struct stat' have to be given in big
7770
endian byte order.
7771
 
7772

7773
File: gdb.info,  Node: Pointer Values,  Next: Memory Transfer,  Prev: Integral Datatypes,  Up: Protocol-specific Representation of Datatypes
7774
 
7775
Pointer Values
7776
..............
7777
 
7778
Pointers to target data are transmitted as they are.  An exception is
7779
made for pointers to buffers for which the length isn't transmitted as
7780
part of the function call, namely strings.  Strings are transmitted as
7781
a pointer/length pair, both as hex values, e.g.
7782
 
7783
     `1aaf/12'
7784
 
7785
which is a pointer to data of length 18 bytes at position 0x1aaf.  The
7786
length is defined as the full string length in bytes, including the
7787
trailing null byte.  For example, the string `"hello world"' at address
7788
0x123456 is transmitted as
7789
 
7790
     `123456/d'
7791
 
7792

7793
File: gdb.info,  Node: Memory Transfer,  Next: struct stat,  Prev: Pointer Values,  Up: Protocol-specific Representation of Datatypes
7794
 
7795
Memory Transfer
7796
...............
7797
 
7798
Structured data which is transferred using a memory read or write (for
7799
example, a `struct stat') is expected to be in a protocol-specific
7800
format with all scalar multibyte datatypes being big endian.
7801
Translation to this representation needs to be done both by the target
7802
before the `F' packet is sent, and by GDB before it transfers memory to
7803
the target.  Transferred pointers to structured data should point to
7804
the already-coerced data at any time.
7805
 
7806

7807
File: gdb.info,  Node: struct stat,  Next: struct timeval,  Prev: Memory Transfer,  Up: Protocol-specific Representation of Datatypes
7808
 
7809
struct stat
7810
...........
7811
 
7812
The buffer of type `struct stat' used by the target and GDB is defined
7813
as follows:
7814
 
7815
     struct stat {
7816
         unsigned int  st_dev;      /* device */
7817
         unsigned int  st_ino;      /* inode */
7818
         mode_t        st_mode;     /* protection */
7819
         unsigned int  st_nlink;    /* number of hard links */
7820
         unsigned int  st_uid;      /* user ID of owner */
7821
         unsigned int  st_gid;      /* group ID of owner */
7822
         unsigned int  st_rdev;     /* device type (if inode device) */
7823
         unsigned long st_size;     /* total size, in bytes */
7824
         unsigned long st_blksize;  /* blocksize for filesystem I/O */
7825
         unsigned long st_blocks;   /* number of blocks allocated */
7826
         time_t        st_atime;    /* time of last access */
7827
         time_t        st_mtime;    /* time of last modification */
7828
         time_t        st_ctime;    /* time of last change */
7829
     };
7830
 
7831
   The integral datatypes conform to the definitions given in the
7832 342 jeremybenn
appropriate section (see *note Integral Datatypes::, for details) so
7833 330 jeremybenn
this structure is of size 64 bytes.
7834
 
7835
   The values of several fields have a restricted meaning and/or range
7836
of values.
7837
 
7838
`st_dev'
7839
     A value of 0 represents a file, 1 the console.
7840
 
7841
`st_ino'
7842
     No valid meaning for the target.  Transmitted unchanged.
7843
 
7844
`st_mode'
7845 342 jeremybenn
     Valid mode bits are described in *note Constants::.  Any other
7846 330 jeremybenn
     bits have currently no meaning for the target.
7847
 
7848
`st_uid'
7849
`st_gid'
7850
`st_rdev'
7851
     No valid meaning for the target.  Transmitted unchanged.
7852
 
7853
`st_atime'
7854
`st_mtime'
7855
`st_ctime'
7856
     These values have a host and file system dependent accuracy.
7857
     Especially on Windows hosts, the file system may not support exact
7858
     timing values.
7859
 
7860
   The target gets a `struct stat' of the above representation and is
7861
responsible for coercing it to the target representation before
7862
continuing.
7863
 
7864
   Note that due to size differences between the host, target, and
7865
protocol representations of `struct stat' members, these members could
7866
eventually get truncated on the target.
7867
 
7868

7869
File: gdb.info,  Node: struct timeval,  Prev: struct stat,  Up: Protocol-specific Representation of Datatypes
7870
 
7871
struct timeval
7872
..............
7873
 
7874
The buffer of type `struct timeval' used by the File-I/O protocol is
7875
defined as follows:
7876
 
7877
     struct timeval {
7878
         time_t tv_sec;  /* second */
7879
         long   tv_usec; /* microsecond */
7880
     };
7881
 
7882
   The integral datatypes conform to the definitions given in the
7883 342 jeremybenn
appropriate section (see *note Integral Datatypes::, for details) so
7884 330 jeremybenn
this structure is of size 8 bytes.
7885
 
7886

7887
File: gdb.info,  Node: Constants,  Next: File-I/O Examples,  Prev: Protocol-specific Representation of Datatypes,  Up: File-I/O Remote Protocol Extension
7888
 
7889
D.13.9 Constants
7890
----------------
7891
 
7892
The following values are used for the constants inside of the protocol.
7893
GDB and target are responsible for translating these values before and
7894
after the call as needed.
7895
 
7896
* Menu:
7897
 
7898
* Open Flags::
7899
* mode_t Values::
7900
* Errno Values::
7901
* Lseek Flags::
7902
* Limits::
7903
 
7904

7905
File: gdb.info,  Node: Open Flags,  Next: mode_t Values,  Up: Constants
7906
 
7907
Open Flags
7908
..........
7909
 
7910
All values are given in hexadecimal representation.
7911
 
7912
       O_RDONLY        0x0
7913
       O_WRONLY        0x1
7914
       O_RDWR          0x2
7915
       O_APPEND        0x8
7916
       O_CREAT       0x200
7917
       O_TRUNC       0x400
7918
       O_EXCL        0x800
7919
 
7920

7921
File: gdb.info,  Node: mode_t Values,  Next: Errno Values,  Prev: Open Flags,  Up: Constants
7922
 
7923
mode_t Values
7924
.............
7925
 
7926
All values are given in octal representation.
7927
 
7928
       S_IFREG       0100000
7929
       S_IFDIR        040000
7930
       S_IRUSR          0400
7931
       S_IWUSR          0200
7932
       S_IXUSR          0100
7933
       S_IRGRP           040
7934
       S_IWGRP           020
7935
       S_IXGRP           010
7936
       S_IROTH            04
7937
       S_IWOTH            02
7938
       S_IXOTH            01
7939
 
7940

7941
File: gdb.info,  Node: Errno Values,  Next: Lseek Flags,  Prev: mode_t Values,  Up: Constants
7942
 
7943
Errno Values
7944
............
7945
 
7946
All values are given in decimal representation.
7947
 
7948
       EPERM           1
7949
       ENOENT          2
7950
       EINTR           4
7951
       EBADF           9
7952
       EACCES         13
7953
       EFAULT         14
7954
       EBUSY          16
7955
       EEXIST         17
7956
       ENODEV         19
7957
       ENOTDIR        20
7958
       EISDIR         21
7959
       EINVAL         22
7960
       ENFILE         23
7961
       EMFILE         24
7962
       EFBIG          27
7963
       ENOSPC         28
7964
       ESPIPE         29
7965
       EROFS          30
7966
       ENAMETOOLONG   91
7967
       EUNKNOWN       9999
7968
 
7969
   `EUNKNOWN' is used as a fallback error value if a host system returns
7970
 any error value not in the list of supported error numbers.
7971
 
7972

7973
File: gdb.info,  Node: Lseek Flags,  Next: Limits,  Prev: Errno Values,  Up: Constants
7974
 
7975
Lseek Flags
7976
...........
7977
 
7978
       SEEK_SET      0
7979
       SEEK_CUR      1
7980
       SEEK_END      2
7981
 
7982

7983
File: gdb.info,  Node: Limits,  Prev: Lseek Flags,  Up: Constants
7984
 
7985
Limits
7986
......
7987
 
7988
All values are given in decimal representation.
7989
 
7990
       INT_MIN       -2147483648
7991
       INT_MAX        2147483647
7992
       UINT_MAX       4294967295
7993
       LONG_MIN      -9223372036854775808
7994
       LONG_MAX       9223372036854775807
7995
       ULONG_MAX      18446744073709551615
7996
 
7997

7998
File: gdb.info,  Node: File-I/O Examples,  Prev: Constants,  Up: File-I/O Remote Protocol Extension
7999
 
8000
D.13.10 File-I/O Examples
8001
-------------------------
8002
 
8003
Example sequence of a write call, file descriptor 3, buffer is at target
8004
address 0x1234, 6 bytes should be written:
8005
 
8006
     <- `Fwrite,3,1234,6'
8007
     _request memory read from target_
8008
     -> `m1234,6'
8009
     <- XXXXXX
8010
     _return "6 bytes written"_
8011
     -> `F6'
8012
 
8013
   Example sequence of a read call, file descriptor 3, buffer is at
8014
target address 0x1234, 6 bytes should be read:
8015
 
8016
     <- `Fread,3,1234,6'
8017
     _request memory write to target_
8018
     -> `X1234,6:XXXXXX'
8019
     _return "6 bytes read"_
8020
     -> `F6'
8021
 
8022
   Example sequence of a read call, call fails on the host due to
8023
invalid file descriptor (`EBADF'):
8024
 
8025
     <- `Fread,3,1234,6'
8026
     -> `F-1,9'
8027
 
8028
   Example sequence of a read call, user presses `Ctrl-c' before
8029
syscall on host is called:
8030
 
8031
     <- `Fread,3,1234,6'
8032
     -> `F-1,4,C'
8033
     <- `T02'
8034
 
8035
   Example sequence of a read call, user presses `Ctrl-c' after syscall
8036
on host is called:
8037
 
8038
     <- `Fread,3,1234,6'
8039
     -> `X1234,6:XXXXXX'
8040
     <- `T02'
8041
 
8042

8043
File: gdb.info,  Node: Library List Format,  Next: Memory Map Format,  Prev: File-I/O Remote Protocol Extension,  Up: Remote Protocol
8044
 
8045
D.14 Library List Format
8046
========================
8047
 
8048
On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
8049
process as your application to manage libraries.  In this case, GDB can
8050
use the loader's symbol table and normal memory operations to maintain
8051
a list of shared libraries.  On other platforms, the operating system
8052
manages loaded libraries.  GDB can not retrieve the list of currently
8053
loaded libraries through memory operations, so it uses the
8054
`qXfer:libraries:read' packet (*note qXfer library list read::)
8055
instead.  The remote stub queries the target's operating system and
8056
reports which libraries are loaded.
8057
 
8058
   The `qXfer:libraries:read' packet returns an XML document which
8059
lists loaded libraries and their offsets.  Each library has an
8060
associated name and one or more segment or section base addresses,
8061
which report where the library was loaded in memory.
8062
 
8063
   For the common case of libraries that are fully linked binaries, the
8064
library should have a list of segments.  If the target supports dynamic
8065
linking of a relocatable object file, its library XML element should
8066
instead include a list of allocated sections.  The segment or section
8067
bases are start addresses, not relocation offsets; they do not depend
8068
on the library's link-time base addresses.
8069
 
8070
   GDB must be linked with the Expat library to support XML library
8071
lists.  *Note Expat::.
8072
 
8073
   A simple memory map, with one loaded library relocated by a single
8074
offset, looks like this:
8075
 
8076
     
8077
       
8078
         
8079
       
8080
     
8081
 
8082
   Another simple memory map, with one loaded library with three
8083
allocated sections (.text, .data, .bss), looks like this:
8084
 
8085
     
8086
       
8087
         
8088
         
8089
         
8090
       
8091
     
8092
 
8093
   The format of a library list is described by this DTD:
8094
 
8095
     
8096
     
8097
     
8098
     
8099
     
8100
     
8101
     
8102
     
8103
     
8104
 
8105
   In addition, segments and section descriptors cannot be mixed within
8106
a single library element, and you must supply at least one segment or
8107
section for each library.
8108
 
8109

8110
File: gdb.info,  Node: Memory Map Format,  Next: Thread List Format,  Prev: Library List Format,  Up: Remote Protocol
8111
 
8112
D.15 Memory Map Format
8113
======================
8114
 
8115
To be able to write into flash memory, GDB needs to obtain a memory map
8116
from the target.  This section describes the format of the memory map.
8117
 
8118
   The memory map is obtained using the `qXfer:memory-map:read' (*note
8119
qXfer memory map read::) packet and is an XML document that lists
8120
memory regions.
8121
 
8122
   GDB must be linked with the Expat library to support XML memory
8123
maps.  *Note Expat::.
8124
 
8125
   The top-level structure of the document is shown below:
8126
 
8127
     
8128
     
8129
               PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
8130
                      "http://sourceware.org/gdb/gdb-memory-map.dtd">
8131
     
8132
         region...
8133
     
8134
 
8135
   Each region can be either:
8136
 
8137
   * A region of RAM starting at ADDR and extending for LENGTH bytes
8138
     from there:
8139
 
8140
          
8141
 
8142
   * A region of read-only memory:
8143
 
8144
          
8145
 
8146
   * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
8147
     length:
8148
 
8149
          
8150
            BLOCKSIZE
8151
          
8152
 
8153
 
8154
   Regions must not overlap.  GDB assumes that areas of memory not
8155
covered by the memory map are RAM, and uses the ordinary `M' and `X'
8156
packets to write to addresses in such ranges.
8157
 
8158
   The formal DTD for memory map format is given below:
8159
 
8160
     
8161
     
8162
     
8163
     
8164
     
8165
     
8166
     
8167
     
8168
     
8169
     
8171
     
8172
                             start   CDATA   #REQUIRED
8173
                             length  CDATA   #REQUIRED
8174
                             device  CDATA   #IMPLIED>
8175
     
8176
     
8177
     
8178
 
8179

8180
File: gdb.info,  Node: Thread List Format,  Prev: Memory Map Format,  Up: Remote Protocol
8181
 
8182
D.16 Thread List Format
8183
=======================
8184
 
8185
To efficiently update the list of threads and their attributes, GDB
8186
issues the `qXfer:threads:read' packet (*note qXfer threads read::) and
8187
obtains the XML document with the following structure:
8188
 
8189
     
8190
     
8191
         
8192
         ... description ...
8193
         
8194
     
8195
 
8196
   Each `thread' element must have the `id' attribute that identifies
8197
the thread (*note thread-id syntax::).  The `core' attribute, if
8198
present, specifies which processor core the thread was last executing
8199
on.  The content of the of `thread' element is interpreted as
8200
human-readable auxilliary information.
8201
 
8202

8203
File: gdb.info,  Node: Agent Expressions,  Next: Target Descriptions,  Prev: Remote Protocol,  Up: Top
8204
 
8205
Appendix E The GDB Agent Expression Mechanism
8206
*********************************************
8207
 
8208
In some applications, it is not feasible for the debugger to interrupt
8209
the program's execution long enough for the developer to learn anything
8210
helpful about its behavior.  If the program's correctness depends on its
8211
real-time behavior, delays introduced by a debugger might cause the
8212
program to fail, even when the code itself is correct.  It is useful to
8213
be able to observe the program's behavior without interrupting it.
8214
 
8215
   Using GDB's `trace' and `collect' commands, the user can specify
8216
locations in the program, and arbitrary expressions to evaluate when
8217
those locations are reached.  Later, using the `tfind' command, she can
8218
examine the values those expressions had when the program hit the trace
8219
points.  The expressions may also denote objects in memory --
8220
structures or arrays, for example -- whose values GDB should record;
8221
while visiting a particular tracepoint, the user may inspect those
8222
objects as if they were in memory at that moment.  However, because GDB
8223
records these values without interacting with the user, it can do so
8224
quickly and unobtrusively, hopefully not disturbing the program's
8225
behavior.
8226
 
8227
   When GDB is debugging a remote target, the GDB "agent" code running
8228
on the target computes the values of the expressions itself.  To avoid
8229
having a full symbolic expression evaluator on the agent, GDB translates
8230
expressions in the source language into a simpler bytecode language, and
8231
then sends the bytecode to the agent; the agent then executes the
8232
bytecode, and records the values for GDB to retrieve later.
8233
 
8234
   The bytecode language is simple; there are forty-odd opcodes, the
8235
bulk of which are the usual vocabulary of C operands (addition,
8236
subtraction, shifts, and so on) and various sizes of literals and
8237
memory reference operations.  The bytecode interpreter operates
8238
strictly on machine-level values -- various sizes of integers and
8239
floating point numbers -- and requires no information about types or
8240
symbols; thus, the interpreter's internal data structures are simple,
8241
and each bytecode requires only a few native machine instructions to
8242
implement it.  The interpreter is small, and strict limits on the
8243
memory and time required to evaluate an expression are easy to
8244
determine, making it suitable for use by the debugging agent in
8245
real-time applications.
8246
 
8247
* Menu:
8248
 
8249
* General Bytecode Design::     Overview of the interpreter.
8250
* Bytecode Descriptions::       What each one does.
8251
* Using Agent Expressions::     How agent expressions fit into the big picture.
8252
* Varying Target Capabilities:: How to discover what the target can do.
8253
* Rationale::                   Why we did it this way.
8254
 
8255

8256
File: gdb.info,  Node: General Bytecode Design,  Next: Bytecode Descriptions,  Up: Agent Expressions
8257
 
8258
E.1 General Bytecode Design
8259
===========================
8260
 
8261
The agent represents bytecode expressions as an array of bytes.  Each
8262
instruction is one byte long (thus the term "bytecode").  Some
8263
instructions are followed by operand bytes; for example, the `goto'
8264
instruction is followed by a destination for the jump.
8265
 
8266
   The bytecode interpreter is a stack-based machine; most instructions
8267
pop their operands off the stack, perform some operation, and push the
8268
result back on the stack for the next instruction to consume.  Each
8269
element of the stack may contain either a integer or a floating point
8270
value; these values are as many bits wide as the largest integer that
8271
can be directly manipulated in the source language.  Stack elements
8272
carry no record of their type; bytecode could push a value as an
8273
integer, then pop it as a floating point value.  However, GDB will not
8274
generate code which does this.  In C, one might define the type of a
8275
stack element as follows:
8276
     union agent_val {
8277
       LONGEST l;
8278
       DOUBLEST d;
8279
     };
8280
   where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
8281
integer and floating point types on the machine.
8282
 
8283
   By the time the bytecode interpreter reaches the end of the
8284
expression, the value of the expression should be the only value left
8285
on the stack.  For tracing applications, `trace' bytecodes in the
8286
expression will have recorded the necessary data, and the value on the
8287
stack may be discarded.  For other applications, like conditional
8288
breakpoints, the value may be useful.
8289
 
8290
   Separate from the stack, the interpreter has two registers:
8291
`pc'
8292
     The address of the next bytecode to execute.
8293
 
8294
`start'
8295
     The address of the start of the bytecode expression, necessary for
8296
     interpreting the `goto' and `if_goto' instructions.
8297
 
8298
   Neither of these registers is directly visible to the bytecode
8299
language itself, but they are useful for defining the meanings of the
8300
bytecode operations.
8301
 
8302
   There are no instructions to perform side effects on the running
8303
program, or call the program's functions; we assume that these
8304
expressions are only used for unobtrusive debugging, not for patching
8305
the running code.
8306
 
8307
   Most bytecode instructions do not distinguish between the various
8308
sizes of values, and operate on full-width values; the upper bits of the
8309
values are simply ignored, since they do not usually make a difference
8310
to the value computed.  The exceptions to this rule are:
8311
memory reference instructions (`ref'N)
8312
     There are distinct instructions to fetch different word sizes from
8313
     memory.  Once on the stack, however, the values are treated as
8314
     full-size integers.  They may need to be sign-extended; the `ext'
8315
     instruction exists for this purpose.
8316
 
8317
the sign-extension instruction (`ext' N)
8318
     These clearly need to know which portion of their operand is to be
8319
     extended to occupy the full length of the word.
8320
 
8321
 
8322
   If the interpreter is unable to evaluate an expression completely for
8323
some reason (a memory location is inaccessible, or a divisor is zero,
8324
for example), we say that interpretation "terminates with an error".
8325
This means that the problem is reported back to the interpreter's caller
8326
in some helpful way.  In general, code using agent expressions should
8327
assume that they may attempt to divide by zero, fetch arbitrary memory
8328
locations, and misbehave in other ways.
8329
 
8330
   Even complicated C expressions compile to a few bytecode
8331
instructions; for example, the expression `x + y * z' would typically
8332
produce code like the following, assuming that `x' and `y' live in
8333
registers, and `z' is a global variable holding a 32-bit `int':
8334
     reg 1
8335
     reg 2
8336
     const32 address of z
8337
     ref32
8338
     ext 32
8339
     mul
8340
     add
8341
     end
8342
 
8343
   In detail, these mean:
8344
`reg 1'
8345
     Push the value of register 1 (presumably holding `x') onto the
8346
     stack.
8347
 
8348
`reg 2'
8349
     Push the value of register 2 (holding `y').
8350
 
8351
`const32 address of z'
8352
     Push the address of `z' onto the stack.
8353
 
8354
`ref32'
8355
     Fetch a 32-bit word from the address at the top of the stack;
8356
     replace the address on the stack with the value.  Thus, we replace
8357
     the address of `z' with `z''s value.
8358
 
8359
`ext 32'
8360
     Sign-extend the value on the top of the stack from 32 bits to full
8361
     length.  This is necessary because `z' is a signed integer.
8362
 
8363
`mul'
8364
     Pop the top two numbers on the stack, multiply them, and push their
8365
     product.  Now the top of the stack contains the value of the
8366
     expression `y * z'.
8367
 
8368
`add'
8369
     Pop the top two numbers, add them, and push the sum.  Now the top
8370
     of the stack contains the value of `x + y * z'.
8371
 
8372
`end'
8373
     Stop executing; the value left on the stack top is the value to be
8374
     recorded.
8375
 
8376
 

powered by: WebSVN 2.1.0

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