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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gdb-7.1/] [gdb/] [doc/] [gdb.info-2] - Blame information for rev 855

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

Line No. Rev Author Line
1 227 jeremybenn
This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
2
 
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.1 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
Source-Level Debugger' for GDB (GDB) Version 7.1.
27
 
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.1 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: Dump/Restore Files,  Next: Core File Generation,  Prev: Memory Region Attributes,  Up: Data
45
 
46
10.16 Copy Between Memory and a File
47
====================================
48
 
49
You can use the commands `dump', `append', and `restore' to copy data
50
between target memory and a file.  The `dump' and `append' commands
51
write data to a file, and the `restore' command reads data from a file
52
back into the inferior's memory.  Files may be in binary, Motorola
53
S-record, Intel hex, or Tektronix Hex format; however, GDB can only
54
append to binary files.
55
 
56
`dump [FORMAT] memory FILENAME START_ADDR END_ADDR'
57
`dump [FORMAT] value FILENAME EXPR'
58
     Dump the contents of memory from START_ADDR to END_ADDR, or the
59
     value of EXPR, to FILENAME in the given format.
60
 
61
     The FORMAT parameter may be any one of:
62
    `binary'
63
          Raw binary form.
64
 
65
    `ihex'
66
          Intel hex format.
67
 
68
    `srec'
69
          Motorola S-record format.
70
 
71
    `tekhex'
72
          Tektronix Hex format.
73
 
74
     GDB uses the same definitions of these formats as the GNU binary
75
     utilities, like `objdump' and `objcopy'.  If FORMAT is omitted,
76
     GDB dumps the data in raw binary form.
77
 
78
`append [binary] memory FILENAME START_ADDR END_ADDR'
79
`append [binary] value FILENAME EXPR'
80
     Append the contents of memory from START_ADDR to END_ADDR, or the
81
     value of EXPR, to the file FILENAME, in raw binary form.  (GDB can
82
     only append data to files in raw binary form.)
83
 
84
`restore FILENAME [binary] BIAS START END'
85
     Restore the contents of file FILENAME into memory.  The `restore'
86
     command can automatically recognize any known BFD file format,
87
     except for raw binary.  To restore a raw binary file you must
88
     specify the optional keyword `binary' after the filename.
89
 
90
     If BIAS is non-zero, its value will be added to the addresses
91
     contained in the file.  Binary files always start at address zero,
92
     so they will be restored at address BIAS.  Other bfd files have a
93
     built-in location; they will be restored at offset BIAS from that
94
     location.
95
 
96
     If START and/or END are non-zero, then only data between file
97
     offset START and file offset END will be restored.  These offsets
98
     are relative to the addresses in the file, before the BIAS
99
     argument is applied.
100
 
101
 
102

103
File: gdb.info,  Node: Core File Generation,  Next: Character Sets,  Prev: Dump/Restore Files,  Up: Data
104
 
105
10.17 How to Produce a Core File from Your Program
106
==================================================
107
 
108
A "core file" or "core dump" is a file that records the memory image of
109
a running process and its process status (register values etc.).  Its
110
primary use is post-mortem debugging of a program that crashed while it
111
ran outside a debugger.  A program that crashes automatically produces
112
a core file, unless this feature is disabled by the user.  *Note
113
Files::, for information on invoking GDB in the post-mortem debugging
114
mode.
115
 
116
   Occasionally, you may wish to produce a core file of the program you
117
are debugging in order to preserve a snapshot of its state.  GDB has a
118
special command for that.
119
 
120
`generate-core-file [FILE]'
121
`gcore [FILE]'
122
     Produce a core dump of the inferior process.  The optional argument
123
     FILE specifies the file name where to put the core dump.  If not
124
     specified, the file name defaults to `core.PID', where PID is the
125
     inferior process ID.
126
 
127
     Note that this command is implemented only for some systems (as of
128
     this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390).
129
 
130

131
File: gdb.info,  Node: Character Sets,  Next: Caching Remote Data,  Prev: Core File Generation,  Up: Data
132
 
133
10.18 Character Sets
134
====================
135
 
136
If the program you are debugging uses a different character set to
137
represent characters and strings than the one GDB uses itself, GDB can
138
automatically translate between the character sets for you.  The
139
character set GDB uses we call the "host character set"; the one the
140
inferior program uses we call the "target character set".
141
 
142
   For example, if you are running GDB on a GNU/Linux system, which
143
uses the ISO Latin 1 character set, but you are using GDB's remote
144
protocol (*note Remote Debugging::) to debug a program running on an
145
IBM mainframe, which uses the EBCDIC character set, then the host
146
character set is Latin-1, and the target character set is EBCDIC.  If
147
you give GDB the command `set target-charset EBCDIC-US', then GDB
148
translates between EBCDIC and Latin 1 as you print character or string
149
values, or use character and string literals in expressions.
150
 
151
   GDB has no way to automatically recognize which character set the
152
inferior program uses; you must tell it, using the `set target-charset'
153
command, described below.
154
 
155
   Here are the commands for controlling GDB's character set support:
156
 
157
`set target-charset CHARSET'
158
     Set the current target character set to CHARSET.  To display the
159
     list of supported target character sets, type
160
     `set target-charset '.
161
 
162
`set host-charset CHARSET'
163
     Set the current host character set to CHARSET.
164
 
165
     By default, GDB uses a host character set appropriate to the
166
     system it is running on; you can override that default using the
167
     `set host-charset' command.  On some systems, GDB cannot
168
     automatically determine the appropriate host character set.  In
169
     this case, GDB uses `UTF-8'.
170
 
171
     GDB can only use certain character sets as its host character set.
172
     If you type `set target-charset ', GDB will list the
173
     host character sets it supports.
174
 
175
`set charset CHARSET'
176
     Set the current host and target character sets to CHARSET.  As
177
     above, if you type `set charset ', GDB will list the
178
     names of the character sets that can be used for both host and
179
     target.
180
 
181
`show charset'
182
     Show the names of the current host and target character sets.
183
 
184
`show host-charset'
185
     Show the name of the current host character set.
186
 
187
`show target-charset'
188
     Show the name of the current target character set.
189
 
190
`set target-wide-charset CHARSET'
191
     Set the current target's wide character set to CHARSET.  This is
192
     the character set used by the target's `wchar_t' type.  To display
193
     the list of supported wide character sets, type
194
     `set target-wide-charset '.
195
 
196
`show target-wide-charset'
197
     Show the name of the current target's wide character set.
198
 
199
   Here is an example of GDB's character set support in action.  Assume
200
that the following source code has been placed in the file
201
`charset-test.c':
202
 
203
     #include 
204
 
205
     char ascii_hello[]
206
       = {72, 101, 108, 108, 111, 44, 32, 119,
207
          111, 114, 108, 100, 33, 10, 0};
208
     char ibm1047_hello[]
209
       = {200, 133, 147, 147, 150, 107, 64, 166,
210
          150, 153, 147, 132, 90, 37, 0};
211
 
212
     main ()
213
     {
214
       printf ("Hello, world!\n");
215
     }
216
 
217
   In this program, `ascii_hello' and `ibm1047_hello' are arrays
218
containing the string `Hello, world!' followed by a newline, encoded in
219
the ASCII and IBM1047 character sets.
220
 
221
   We compile the program, and invoke the debugger on it:
222
 
223
     $ gcc -g charset-test.c -o charset-test
224
     $ gdb -nw charset-test
225
     GNU gdb 2001-12-19-cvs
226
     Copyright 2001 Free Software Foundation, Inc.
227
     ...
228
     (gdb)
229
 
230
   We can use the `show charset' command to see what character sets GDB
231
is currently using to interpret and display characters and strings:
232
 
233
     (gdb) show charset
234
     The current host and target character set is `ISO-8859-1'.
235
     (gdb)
236
 
237
   For the sake of printing this manual, let's use ASCII as our initial
238
character set:
239
     (gdb) set charset ASCII
240
     (gdb) show charset
241
     The current host and target character set is `ASCII'.
242
     (gdb)
243
 
244
   Let's assume that ASCII is indeed the correct character set for our
245
host system -- in other words, let's assume that if GDB prints
246
characters using the ASCII character set, our terminal will display
247
them properly.  Since our current target character set is also ASCII,
248
the contents of `ascii_hello' print legibly:
249
 
250
     (gdb) print ascii_hello
251
     $1 = 0x401698 "Hello, world!\n"
252
     (gdb) print ascii_hello[0]
253
     $2 = 72 'H'
254
     (gdb)
255
 
256
   GDB uses the target character set for character and string literals
257
you use in expressions:
258
 
259
     (gdb) print '+'
260
     $3 = 43 '+'
261
     (gdb)
262
 
263
   The ASCII character set uses the number 43 to encode the `+'
264
character.
265
 
266
   GDB relies on the user to tell it which character set the target
267
program uses.  If we print `ibm1047_hello' while our target character
268
set is still ASCII, we get jibberish:
269
 
270
     (gdb) print ibm1047_hello
271
     $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%"
272
     (gdb) print ibm1047_hello[0]
273
     $5 = 200 '\310'
274
     (gdb)
275
 
276
   If we invoke the `set target-charset' followed by , GDB
277
tells us the character sets it supports:
278
 
279
     (gdb) set target-charset
280
     ASCII       EBCDIC-US   IBM1047     ISO-8859-1
281
     (gdb) set target-charset
282
 
283
   We can select IBM1047 as our target character set, and examine the
284
program's strings again.  Now the ASCII string is wrong, but GDB
285
translates the contents of `ibm1047_hello' from the target character
286
set, IBM1047, to the host character set, ASCII, and they display
287
correctly:
288
 
289
     (gdb) set target-charset IBM1047
290
     (gdb) show charset
291
     The current host character set is `ASCII'.
292
     The current target character set is `IBM1047'.
293
     (gdb) print ascii_hello
294
     $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
295
     (gdb) print ascii_hello[0]
296
     $7 = 72 '\110'
297
     (gdb) print ibm1047_hello
298
     $8 = 0x4016a8 "Hello, world!\n"
299
     (gdb) print ibm1047_hello[0]
300
     $9 = 200 'H'
301
     (gdb)
302
 
303
   As above, GDB uses the target character set for character and string
304
literals you use in expressions:
305
 
306
     (gdb) print '+'
307
     $10 = 78 '+'
308
     (gdb)
309
 
310
   The IBM1047 character set uses the number 78 to encode the `+'
311
character.
312
 
313

314
File: gdb.info,  Node: Caching Remote Data,  Next: Searching Memory,  Prev: Character Sets,  Up: Data
315
 
316
10.19 Caching Data of Remote Targets
317
====================================
318
 
319
GDB caches data exchanged between the debugger and a remote target
320
(*note Remote Debugging::).  Such caching generally improves
321
performance, because it reduces the overhead of the remote protocol by
322
bundling memory reads and writes into large chunks.  Unfortunately,
323
simply caching everything would lead to incorrect results, since GDB
324
does not necessarily know anything about volatile values, memory-mapped
325
I/O addresses, etc.  Furthermore, in non-stop mode (*note Non-Stop
326
Mode::) memory can be changed _while_ a gdb command is executing.
327
Therefore, by default, GDB only caches data known to be on the stack(1).
328
Other regions of memory can be explicitly marked as cacheable; see
329
*note Memory Region Attributes::.
330
 
331
`set remotecache on'
332
`set remotecache off'
333
     This option no longer does anything; it exists for compatibility
334
     with old scripts.
335
 
336
`show remotecache'
337
     Show the current state of the obsolete remotecache flag.
338
 
339
`set stack-cache on'
340
`set stack-cache off'
341
     Enable or disable caching of stack accesses.  When `ON', use
342
     caching.  By default, this option is `ON'.
343
 
344
`show stack-cache'
345
     Show the current state of data caching for memory accesses.
346
 
347
`info dcache [line]'
348
     Print the information about the data cache performance.  The
349
     information displayed includes the dcache width and depth, and for
350
     each cache line, its number, address, and how many times it was
351
     referenced.  This command is useful for debugging the data cache
352
     operation.
353
 
354
     If a line number is specified, the contents of that line will be
355
     printed in hex.
356
 
357
   ---------- Footnotes ----------
358
 
359
   (1) In non-stop mode, it is moderately rare for a running thread to
360
modify the stack of a stopped thread in a way that would interfere with
361
a backtrace, and caching of stack reads provides a significant speed up
362
of remote backtraces.
363
 
364

365
File: gdb.info,  Node: Searching Memory,  Prev: Caching Remote Data,  Up: Data
366
 
367
10.20 Search Memory
368
===================
369
 
370
Memory can be searched for a particular sequence of bytes with the
371
`find' command.
372
 
373
`find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]'
374
`find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]'
375
     Search memory for the sequence of bytes specified by VAL1, VAL2,
376
     etc.  The search begins at address START_ADDR and continues for
377
     either LEN bytes or through to END_ADDR inclusive.
378
 
379
   S and N are optional parameters.  They may be specified in either
380
order, apart or together.
381
 
382
S, search query size
383
     The size of each search query value.
384
 
385
    `b'
386
          bytes
387
 
388
    `h'
389
          halfwords (two bytes)
390
 
391
    `w'
392
          words (four bytes)
393
 
394
    `g'
395
          giant words (eight bytes)
396
 
397
     All values are interpreted in the current language.  This means,
398
     for example, that if the current source language is C/C++ then
399
     searching for the string "hello" includes the trailing '\0'.
400
 
401
     If the value size is not specified, it is taken from the value's
402
     type in the current language.  This is useful when one wants to
403
     specify the search pattern as a mixture of types.  Note that this
404
     means, for example, that in the case of C-like languages a search
405
     for an untyped 0x42 will search for `(int) 0x42' which is
406
     typically four bytes.
407
 
408
N, maximum number of finds
409
     The maximum number of matches to print.  The default is to print
410
     all finds.
411
 
412
   You can use strings as search values.  Quote them with double-quotes
413
(`"').  The string value is copied into the search pattern byte by
414
byte, regardless of the endianness of the target and the size
415
specification.
416
 
417
   The address of each match found is printed as well as a count of the
418
number of matches found.
419
 
420
   The address of the last value found is stored in convenience variable
421
`$_'.  A count of the number of matches is stored in `$numfound'.
422
 
423
   For example, if stopped at the `printf' in this function:
424
 
425
     void
426
     hello ()
427
     {
428
       static char hello[] = "hello-hello";
429
       static struct { char c; short s; int i; }
430
         __attribute__ ((packed)) mixed
431
         = { 'c', 0x1234, 0x87654321 };
432
       printf ("%s\n", hello);
433
     }
434
 
435
you get during debugging:
436
 
437
     (gdb) find &hello[0], +sizeof(hello), "hello"
438
     0x804956d 
439
     1 pattern found
440
     (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
441
     0x8049567 
442
     0x804956d 
443
     2 patterns found
444
     (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
445
     0x8049567 
446
     1 pattern found
447
     (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
448
     0x8049560 
449
     1 pattern found
450
     (gdb) print $numfound
451
     $1 = 1
452
     (gdb) print $_
453
     $2 = (void *) 0x8049560
454
 
455

456
File: gdb.info,  Node: Optimized Code,  Next: Macros,  Prev: Data,  Up: Top
457
 
458
11 Debugging Optimized Code
459
***************************
460
 
461
Almost all compilers support optimization.  With optimization disabled,
462
the compiler generates assembly code that corresponds directly to your
463
source code, in a simplistic way.  As the compiler applies more
464
powerful optimizations, the generated assembly code diverges from your
465
original source code.  With help from debugging information generated
466
by the compiler, GDB can map from the running program back to
467
constructs from your original source.
468
 
469
   GDB is more accurate with optimization disabled.  If you can
470
recompile without optimization, it is easier to follow the progress of
471
your program during debugging.  But, there are many cases where you may
472
need to debug an optimized version.
473
 
474
   When you debug a program compiled with `-g -O', remember that the
475
optimizer has rearranged your code; the debugger shows you what is
476
really there.  Do not be too surprised when the execution path does not
477
exactly match your source file!  An extreme example: if you define a
478
variable, but never use it, GDB never sees that variable--because the
479
compiler optimizes it out of existence.
480
 
481
   Some things do not work as well with `-g -O' as with just `-g',
482
particularly on machines with instruction scheduling.  If in doubt,
483
recompile with `-g' alone, and if this fixes the problem, please report
484
it to us as a bug (including a test case!).  *Note Variables::, for
485
more information about debugging optimized code.
486
 
487
* Menu:
488
 
489
* Inline Functions::            How GDB presents inlining
490
 
491

492
File: gdb.info,  Node: Inline Functions,  Up: Optimized Code
493
 
494
11.1 Inline Functions
495
=====================
496
 
497
"Inlining" is an optimization that inserts a copy of the function body
498
directly at each call site, instead of jumping to a shared routine.
499
GDB displays inlined functions just like non-inlined functions.  They
500
appear in backtraces.  You can view their arguments and local
501
variables, step into them with `step', skip them with `next', and
502
escape from them with `finish'.  You can check whether a function was
503
inlined by using the `info frame' command.
504
 
505
   For GDB to support inlined functions, the compiler must record
506
information about inlining in the debug information -- GCC using the
507
DWARF 2 format does this, and several other compilers do also.  GDB
508
only supports inlined functions when using DWARF 2.  Versions of GCC
509
before 4.1 do not emit two required attributes (`DW_AT_call_file' and
510
`DW_AT_call_line'); GDB does not display inlined function calls with
511
earlier versions of GCC.  It instead displays the arguments and local
512
variables of inlined functions as local variables in the caller.
513
 
514
   The body of an inlined function is directly included at its call
515
site; unlike a non-inlined function, there are no instructions devoted
516
to the call.  GDB still pretends that the call site and the start of
517
the inlined function are different instructions.  Stepping to the call
518
site shows the call site, and then stepping again shows the first line
519
of the inlined function, even though no additional instructions are
520
executed.
521
 
522
   This makes source-level debugging much clearer; you can see both the
523
context of the call and then the effect of the call.  Only stepping by
524
a single instruction using `stepi' or `nexti' does not do this; single
525
instruction steps always show the inlined body.
526
 
527
   There are some ways that GDB does not pretend that inlined function
528
calls are the same as normal calls:
529
 
530
   * You cannot set breakpoints on inlined functions.  GDB either
531
     reports that there is no symbol with that name, or else sets the
532
     breakpoint only on non-inlined copies of the function.  This
533
     limitation will be removed in a future version of GDB; until then,
534
     set a breakpoint by line number on the first line of the inlined
535
     function instead.
536
 
537
   * Setting breakpoints at the call site of an inlined function may not
538
     work, because the call site does not contain any code.  GDB may
539
     incorrectly move the breakpoint to the next line of the enclosing
540
     function, after the call.  This limitation will be removed in a
541
     future version of GDB; until then, set a breakpoint on an earlier
542
     line or inside the inlined function instead.
543
 
544
   * GDB cannot locate the return value of inlined calls after using
545
     the `finish' command.  This is a limitation of compiler-generated
546
     debugging information; after `finish', you can step to the next
547
     line and print a variable where your program stored the return
548
     value.
549
 
550
 
551

552
File: gdb.info,  Node: Macros,  Next: Tracepoints,  Prev: Optimized Code,  Up: Top
553
 
554
12 C Preprocessor Macros
555
************************
556
 
557
Some languages, such as C and C++, provide a way to define and invoke
558
"preprocessor macros" which expand into strings of tokens.  GDB can
559
evaluate expressions containing macro invocations, show the result of
560
macro expansion, and show a macro's definition, including where it was
561
defined.
562
 
563
   You may need to compile your program specially to provide GDB with
564
information about preprocessor macros.  Most compilers do not include
565
macros in their debugging information, even when you compile with the
566
`-g' flag.  *Note Compilation::.
567
 
568
   A program may define a macro at one point, remove that definition
569
later, and then provide a different definition after that.  Thus, at
570
different points in the program, a macro may have different
571
definitions, or have no definition at all.  If there is a current stack
572
frame, GDB uses the macros in scope at that frame's source code line.
573
Otherwise, GDB uses the macros in scope at the current listing location;
574
see *Note List::.
575
 
576
   Whenever GDB evaluates an expression, it always expands any macro
577
invocations present in the expression.  GDB also provides the following
578
commands for working with macros explicitly.
579
 
580
`macro expand EXPRESSION'
581
`macro exp EXPRESSION'
582
     Show the results of expanding all preprocessor macro invocations in
583
     EXPRESSION.  Since GDB simply expands macros, but does not parse
584
     the result, EXPRESSION need not be a valid expression; it can be
585
     any string of tokens.
586
 
587
`macro expand-once EXPRESSION'
588
`macro exp1 EXPRESSION'
589
     (This command is not yet implemented.)  Show the results of
590
     expanding those preprocessor macro invocations that appear
591
     explicitly in EXPRESSION.  Macro invocations appearing in that
592
     expansion are left unchanged.  This command allows you to see the
593
     effect of a particular macro more clearly, without being confused
594
     by further expansions.  Since GDB simply expands macros, but does
595
     not parse the result, EXPRESSION need not be a valid expression; it
596
     can be any string of tokens.
597
 
598
`info macro MACRO'
599
     Show the definition of the macro named MACRO, and describe the
600
     source location or compiler command-line where that definition was
601
     established.
602
 
603
`macro define MACRO REPLACEMENT-LIST'
604
`macro define MACRO(ARGLIST) REPLACEMENT-LIST'
605
     Introduce a definition for a preprocessor macro named MACRO,
606
     invocations of which are replaced by the tokens given in
607
     REPLACEMENT-LIST.  The first form of this command defines an
608
     "object-like" macro, which takes no arguments; the second form
609
     defines a "function-like" macro, which takes the arguments given in
610
     ARGLIST.
611
 
612
     A definition introduced by this command is in scope in every
613
     expression evaluated in GDB, until it is removed with the `macro
614
     undef' command, described below.  The definition overrides all
615
     definitions for MACRO present in the program being debugged, as
616
     well as any previous user-supplied definition.
617
 
618
`macro undef MACRO'
619
     Remove any user-supplied definition for the macro named MACRO.
620
     This command only affects definitions provided with the `macro
621
     define' command, described above; it cannot remove definitions
622
     present in the program being debugged.
623
 
624
`macro list'
625
     List all the macros defined using the `macro define' command.
626
 
627
   Here is a transcript showing the above commands in action.  First, we
628
show our source files:
629
 
630
     $ cat sample.c
631
     #include 
632
     #include "sample.h"
633
 
634
     #define M 42
635
     #define ADD(x) (M + x)
636
 
637
     main ()
638
     {
639
     #define N 28
640
       printf ("Hello, world!\n");
641
     #undef N
642
       printf ("We're so creative.\n");
643
     #define N 1729
644
       printf ("Goodbye, world!\n");
645
     }
646
     $ cat sample.h
647
     #define Q <
648
     $
649
 
650
   Now, we compile the program using the GNU C compiler, GCC.  We pass
651
the `-gdwarf-2' and `-g3' flags to ensure the compiler includes
652
information about preprocessor macros in the debugging information.
653
 
654
     $ gcc -gdwarf-2 -g3 sample.c -o sample
655
     $
656
 
657
   Now, we start GDB on our sample program:
658
 
659
     $ gdb -nw sample
660
     GNU gdb 2002-05-06-cvs
661
     Copyright 2002 Free Software Foundation, Inc.
662
     GDB is free software, ...
663
     (gdb)
664
 
665
   We can expand macros and examine their definitions, even when the
666
program is not running.  GDB uses the current listing position to
667
decide which macro definitions are in scope:
668
 
669
     (gdb) list main
670
     3
671
     4       #define M 42
672
     5       #define ADD(x) (M + x)
673
     6
674
     7       main ()
675
     8       {
676
     9       #define N 28
677
     10        printf ("Hello, world!\n");
678
     11      #undef N
679
     12        printf ("We're so creative.\n");
680
     (gdb) info macro ADD
681
     Defined at /home/jimb/gdb/macros/play/sample.c:5
682
     #define ADD(x) (M + x)
683
     (gdb) info macro Q
684
     Defined at /home/jimb/gdb/macros/play/sample.h:1
685
       included at /home/jimb/gdb/macros/play/sample.c:2
686
     #define Q <
687
     (gdb) macro expand ADD(1)
688
     expands to: (42 + 1)
689
     (gdb) macro expand-once ADD(1)
690
     expands to: once (M + 1)
691
     (gdb)
692
 
693
   In the example above, note that `macro expand-once' expands only the
694
macro invocation explicit in the original text -- the invocation of
695
`ADD' -- but does not expand the invocation of the macro `M', which was
696
introduced by `ADD'.
697
 
698
   Once the program is running, GDB uses the macro definitions in force
699
at the source line of the current stack frame:
700
 
701
     (gdb) break main
702
     Breakpoint 1 at 0x8048370: file sample.c, line 10.
703
     (gdb) run
704
     Starting program: /home/jimb/gdb/macros/play/sample
705
 
706
     Breakpoint 1, main () at sample.c:10
707
     10        printf ("Hello, world!\n");
708
     (gdb)
709
 
710
   At line 10, the definition of the macro `N' at line 9 is in force:
711
 
712
     (gdb) info macro N
713
     Defined at /home/jimb/gdb/macros/play/sample.c:9
714
     #define N 28
715
     (gdb) macro expand N Q M
716
     expands to: 28 < 42
717
     (gdb) print N Q M
718
     $1 = 1
719
     (gdb)
720
 
721
   As we step over directives that remove `N''s definition, and then
722
give it a new definition, GDB finds the definition (or lack thereof) in
723
force at each point:
724
 
725
     (gdb) next
726
     Hello, world!
727
     12        printf ("We're so creative.\n");
728
     (gdb) info macro N
729
     The symbol `N' has no definition as a C/C++ preprocessor macro
730
     at /home/jimb/gdb/macros/play/sample.c:12
731
     (gdb) next
732
     We're so creative.
733
     14        printf ("Goodbye, world!\n");
734
     (gdb) info macro N
735
     Defined at /home/jimb/gdb/macros/play/sample.c:13
736
     #define N 1729
737
     (gdb) macro expand N Q M
738
     expands to: 1729 < 42
739
     (gdb) print N Q M
740
     $2 = 0
741
     (gdb)
742
 
743
   In addition to source files, macros can be defined on the
744
compilation command line using the `-DNAME=VALUE' syntax.  For macros
745
defined in such a way, GDB displays the location of their definition as
746
line zero of the source file submitted to the compiler.
747
 
748
     (gdb) info macro __STDC__
749
     Defined at /home/jimb/gdb/macros/play/sample.c:0
750
     -D__STDC__=1
751
     (gdb)
752
 
753

754
File: gdb.info,  Node: Tracepoints,  Next: Overlays,  Prev: Macros,  Up: Top
755
 
756
13 Tracepoints
757
**************
758
 
759
In some applications, it is not feasible for the debugger to interrupt
760
the program's execution long enough for the developer to learn anything
761
helpful about its behavior.  If the program's correctness depends on
762
its real-time behavior, delays introduced by a debugger might cause the
763
program to change its behavior drastically, or perhaps fail, even when
764
the code itself is correct.  It is useful to be able to observe the
765
program's behavior without interrupting it.
766
 
767
   Using GDB's `trace' and `collect' commands, you can specify
768
locations in the program, called "tracepoints", and arbitrary
769
expressions to evaluate when those tracepoints are reached.  Later,
770
using the `tfind' command, you can examine the values those expressions
771
had when the program hit the tracepoints.  The expressions may also
772
denote objects in memory--structures or arrays, for example--whose
773
values GDB should record; while visiting a particular tracepoint, you
774
may inspect those objects as if they were in memory at that moment.
775
However, because GDB records these values without interacting with you,
776
it can do so quickly and unobtrusively, hopefully not disturbing the
777
program's behavior.
778
 
779
   The tracepoint facility is currently available only for remote
780
targets.  *Note Targets::.  In addition, your remote target must know
781
how to collect trace data.  This functionality is implemented in the
782
remote stub; however, none of the stubs distributed with GDB support
783
tracepoints as of this writing.  The format of the remote packets used
784
to implement tracepoints are described in *Note Tracepoint Packets::.
785
 
786
   It is also possible to get trace data from a file, in a manner
787
reminiscent of corefiles; you specify the filename, and use `tfind' to
788
search through the file.  *Note Trace Files::, for more details.
789
 
790
   This chapter describes the tracepoint commands and features.
791
 
792
* Menu:
793
 
794
* Set Tracepoints::
795
* Analyze Collected Data::
796
* Tracepoint Variables::
797
* Trace Files::
798
 
799

800
File: gdb.info,  Node: Set Tracepoints,  Next: Analyze Collected Data,  Up: Tracepoints
801
 
802
13.1 Commands to Set Tracepoints
803
================================
804
 
805
Before running such a "trace experiment", an arbitrary number of
806
tracepoints can be set.  A tracepoint is actually a special type of
807
breakpoint (*note Set Breaks::), so you can manipulate it using
808
standard breakpoint commands.  For instance, as with breakpoints,
809
tracepoint numbers are successive integers starting from one, and many
810
of the commands associated with tracepoints take the tracepoint number
811
as their argument, to identify which tracepoint to work on.
812
 
813
   For each tracepoint, you can specify, in advance, some arbitrary set
814
of data that you want the target to collect in the trace buffer when it
815
hits that tracepoint.  The collected data can include registers, local
816
variables, or global data.  Later, you can use GDB commands to examine
817
the values these data had at the time the tracepoint was hit.
818
 
819
   Tracepoints do not support every breakpoint feature.  Conditional
820
expressions and ignore counts on tracepoints have no effect, and
821
tracepoints cannot run GDB commands when they are hit.  Tracepoints may
822
not be thread-specific either.
823
 
824
   Some targets may support "fast tracepoints", which are inserted in a
825
different way (such as with a jump instead of a trap), that is faster
826
but possibly restricted in where they may be installed.
827
 
828
   This section describes commands to set tracepoints and associated
829
conditions and actions.
830
 
831
* Menu:
832
 
833
* Create and Delete Tracepoints::
834
* Enable and Disable Tracepoints::
835
* Tracepoint Passcounts::
836
* Tracepoint Conditions::
837
* Trace State Variables::
838
* Tracepoint Actions::
839
* Listing Tracepoints::
840
* Starting and Stopping Trace Experiments::
841
 
842

843
File: gdb.info,  Node: Create and Delete Tracepoints,  Next: Enable and Disable Tracepoints,  Up: Set Tracepoints
844
 
845
13.1.1 Create and Delete Tracepoints
846
------------------------------------
847
 
848
`trace LOCATION'
849
     The `trace' command is very similar to the `break' command.  Its
850
     argument LOCATION can be a source line, a function name, or an
851
     address in the target program.  *Note Specify Location::.  The
852
     `trace' command defines a tracepoint, which is a point in the
853
     target program where the debugger will briefly stop, collect some
854
     data, and then allow the program to continue.  Setting a
855
     tracepoint or changing its actions doesn't take effect until the
856
     next `tstart' command, and once a trace experiment is running,
857
     further changes will not have any effect until the next trace
858
     experiment starts.
859
 
860
     Here are some examples of using the `trace' command:
861
 
862
          (gdb) trace foo.c:121    // a source file and line number
863
 
864
          (gdb) trace +2           // 2 lines forward
865
 
866
          (gdb) trace my_function  // first source line of function
867
 
868
          (gdb) trace *my_function // EXACT start address of function
869
 
870
          (gdb) trace *0x2117c4    // an address
871
 
872
     You can abbreviate `trace' as `tr'.
873
 
874
`trace LOCATION if COND'
875
     Set a tracepoint with condition COND; evaluate the expression COND
876
     each time the tracepoint is reached, and collect data only if the
877
     value is nonzero--that is, if COND evaluates as true.  *Note
878
     Tracepoint Conditions: Tracepoint Conditions, for more information
879
     on tracepoint conditions.
880
 
881
`ftrace LOCATION [ if COND ]'
882
     The `ftrace' command sets a fast tracepoint.  For targets that
883
     support them, fast tracepoints will use a more efficient but
884
     possibly less general technique to trigger data collection, such
885
     as a jump instruction instead of a trap, or some sort of hardware
886
     support.  It may not be possible to create a fast tracepoint at
887
     the desired location, in which case the command will exit with an
888
     explanatory message.
889
 
890
     GDB handles arguments to `ftrace' exactly as for `trace'.
891
 
892
     The convenience variable `$tpnum' records the tracepoint number of
893
     the most recently set tracepoint.
894
 
895
`delete tracepoint [NUM]'
896
     Permanently delete one or more tracepoints.  With no argument, the
897
     default is to delete all tracepoints.  Note that the regular
898
     `delete' command can remove tracepoints also.
899
 
900
     Examples:
901
 
902
          (gdb) delete trace 1 2 3 // remove three tracepoints
903
 
904
          (gdb) delete trace       // remove all tracepoints
905
 
906
     You can abbreviate this command as `del tr'.
907
 
908

909
File: gdb.info,  Node: Enable and Disable Tracepoints,  Next: Tracepoint Passcounts,  Prev: Create and Delete Tracepoints,  Up: Set Tracepoints
910
 
911
13.1.2 Enable and Disable Tracepoints
912
-------------------------------------
913
 
914
These commands are deprecated; they are equivalent to plain `disable'
915
and `enable'.
916
 
917
`disable tracepoint [NUM]'
918
     Disable tracepoint NUM, or all tracepoints if no argument NUM is
919
     given.  A disabled tracepoint will have no effect during the next
920
     trace experiment, but it is not forgotten.  You can re-enable a
921
     disabled tracepoint using the `enable tracepoint' command.
922
 
923
`enable tracepoint [NUM]'
924
     Enable tracepoint NUM, or all tracepoints.  The enabled
925
     tracepoints will become effective the next time a trace experiment
926
     is run.
927
 
928

929
File: gdb.info,  Node: Tracepoint Passcounts,  Next: Tracepoint Conditions,  Prev: Enable and Disable Tracepoints,  Up: Set Tracepoints
930
 
931
13.1.3 Tracepoint Passcounts
932
----------------------------
933
 
934
`passcount [N [NUM]]'
935
     Set the "passcount" of a tracepoint.  The passcount is a way to
936
     automatically stop a trace experiment.  If a tracepoint's
937
     passcount is N, then the trace experiment will be automatically
938
     stopped on the N'th time that tracepoint is hit.  If the
939
     tracepoint number NUM is not specified, the `passcount' command
940
     sets the passcount of the most recently defined tracepoint.  If no
941
     passcount is given, the trace experiment will run until stopped
942
     explicitly by the user.
943
 
944
     Examples:
945
 
946
          (gdb) passcount 5 2 // Stop on the 5th execution of
947
                                        `// tracepoint 2'
948
 
949
          (gdb) passcount 12  // Stop on the 12th execution of the
950
                                        `// most recently defined tracepoint.'
951
          (gdb) trace foo
952
          (gdb) pass 3
953
          (gdb) trace bar
954
          (gdb) pass 2
955
          (gdb) trace baz
956
          (gdb) pass 1        // Stop tracing when foo has been
957
                                         `// executed 3 times OR when bar has'
958
                                         `// been executed 2 times'
959
                                         `// OR when baz has been executed 1 time.'
960
 
961
 
962

963
File: gdb.info,  Node: Tracepoint Conditions,  Next: Trace State Variables,  Prev: Tracepoint Passcounts,  Up: Set Tracepoints
964
 
965
13.1.4 Tracepoint Conditions
966
----------------------------
967
 
968
The simplest sort of tracepoint collects data every time your program
969
reaches a specified place.  You can also specify a "condition" for a
970
tracepoint.  A condition is just a Boolean expression in your
971
programming language (*note Expressions: Expressions.).  A tracepoint
972
with a condition evaluates the expression each time your program
973
reaches it, and data collection happens only if the condition is true.
974
 
975
   Tracepoint conditions can be specified when a tracepoint is set, by
976
using `if' in the arguments to the `trace' command.  *Note Setting
977
Tracepoints: Create and Delete Tracepoints.  They can also be set or
978
changed at any time with the `condition' command, just as with
979
breakpoints.
980
 
981
   Unlike breakpoint conditions, GDB does not actually evaluate the
982
conditional expression itself.  Instead, GDB encodes the expression
983
into an agent expression (*note Agent Expressions:: suitable for
984
execution on the target, independently of GDB.  Global variables become
985
raw memory locations, locals become stack accesses, and so forth.
986
 
987
   For instance, suppose you have a function that is usually called
988
frequently, but should not be called after an error has occurred.  You
989
could use the following tracepoint command to collect data about calls
990
of that function that happen while the error code is propagating
991
through the program; an unconditional tracepoint could end up
992
collecting thousands of useless trace frames that you would have to
993
search through.
994
 
995
     (gdb) trace normal_operation if errcode > 0
996
 
997

998
File: gdb.info,  Node: Trace State Variables,  Next: Tracepoint Actions,  Prev: Tracepoint Conditions,  Up: Set Tracepoints
999
 
1000
13.1.5 Trace State Variables
1001
----------------------------
1002
 
1003
A "trace state variable" is a special type of variable that is created
1004
and managed by target-side code.  The syntax is the same as that for
1005
GDB's convenience variables (a string prefixed with "$"), but they are
1006
stored on the target.  They must be created explicitly, using a
1007
`tvariable' command.  They are always 64-bit signed integers.
1008
 
1009
   Trace state variables are remembered by GDB, and downloaded to the
1010
target along with tracepoint information when the trace experiment
1011
starts.  There are no intrinsic limits on the number of trace state
1012
variables, beyond memory limitations of the target.
1013
 
1014
   Although trace state variables are managed by the target, you can use
1015
them in print commands and expressions as if they were convenience
1016
variables; GDB will get the current value from the target while the
1017
trace experiment is running.  Trace state variables share the same
1018
namespace as other "$" variables, which means that you cannot have
1019
trace state variables with names like `$23' or `$pc', nor can you have
1020
a trace state variable and a convenience variable with the same name.
1021
 
1022
`tvariable $NAME [ = EXPRESSION ]'
1023
     The `tvariable' command creates a new trace state variable named
1024
     `$NAME', and optionally gives it an initial value of EXPRESSION.
1025
     EXPRESSION is evaluated when this command is entered; the result
1026
     will be converted to an integer if possible, otherwise GDB will
1027
     report an error. A subsequent `tvariable' command specifying the
1028
     same name does not create a variable, but instead assigns the
1029
     supplied initial value to the existing variable of that name,
1030
     overwriting any previous initial value. The default initial value
1031
     is 0.
1032
 
1033
`info tvariables'
1034
     List all the trace state variables along with their initial values.
1035
     Their current values may also be displayed, if the trace
1036
     experiment is currently running.
1037
 
1038
`delete tvariable [ $NAME ... ]'
1039
     Delete the given trace state variables, or all of them if no
1040
     arguments are specified.
1041
 
1042
 
1043

1044
File: gdb.info,  Node: Tracepoint Actions,  Next: Listing Tracepoints,  Prev: Trace State Variables,  Up: Set Tracepoints
1045
 
1046
13.1.6 Tracepoint Action Lists
1047
------------------------------
1048
 
1049
`actions [NUM]'
1050
     This command will prompt for a list of actions to be taken when the
1051
     tracepoint is hit.  If the tracepoint number NUM is not specified,
1052
     this command sets the actions for the one that was most recently
1053
     defined (so that you can define a tracepoint and then say
1054
     `actions' without bothering about its number).  You specify the
1055
     actions themselves on the following lines, one action at a time,
1056
     and terminate the actions list with a line containing just `end'.
1057
     So far, the only defined actions are `collect' and
1058
     `while-stepping'.
1059
 
1060
     To remove all actions from a tracepoint, type `actions NUM' and
1061
     follow it immediately with `end'.
1062
 
1063
          (gdb) collect DATA // collect some data
1064
 
1065
          (gdb) while-stepping 5 // single-step 5 times, collect data
1066
 
1067
          (gdb) end              // signals the end of actions.
1068
 
1069
     In the following example, the action list begins with `collect'
1070
     commands indicating the things to be collected when the tracepoint
1071
     is hit.  Then, in order to single-step and collect additional data
1072
     following the tracepoint, a `while-stepping' command is used,
1073
     followed by the list of things to be collected while stepping.  The
1074
     `while-stepping' command is terminated by its own separate `end'
1075
     command.  Lastly, the action list is terminated by an `end'
1076
     command.
1077
 
1078
          (gdb) trace foo
1079
          (gdb) actions
1080
          Enter actions for tracepoint 1, one per line:
1081
          > collect bar,baz
1082
          > collect $regs
1083
          > while-stepping 12
1084
            > collect $fp, $sp
1085
            > end
1086
          end
1087
 
1088
`collect EXPR1, EXPR2, ...'
1089
     Collect values of the given expressions when the tracepoint is hit.
1090
     This command accepts a comma-separated list of any valid
1091
     expressions.  In addition to global, static, or local variables,
1092
     the following special arguments are supported:
1093
 
1094
    `$regs'
1095
          collect all registers
1096
 
1097
    `$args'
1098
          collect all function arguments
1099
 
1100
    `$locals'
1101
          collect all local variables.
1102
 
1103
     You can give several consecutive `collect' commands, each one with
1104
     a single argument, or one `collect' command with several arguments
1105
     separated by commas: the effect is the same.
1106
 
1107
     The command `info scope' (*note info scope: Symbols.) is
1108
     particularly useful for figuring out what data to collect.
1109
 
1110
`teval EXPR1, EXPR2, ...'
1111
     Evaluate the given expressions when the tracepoint is hit.  This
1112
     command accepts a comma-separated list of expressions.  The results
1113
     are discarded, so this is mainly useful for assigning values to
1114
     trace state variables (*note Trace State Variables::) without
1115
     adding those values to the trace buffer, as would be the case if
1116
     the `collect' action were used.
1117
 
1118
`while-stepping N'
1119
     Perform N single-step traces after the tracepoint, collecting new
1120
     data at each step.  The `while-stepping' command is followed by
1121
     the list of what to collect while stepping (followed by its own
1122
     `end' command):
1123
 
1124
          > while-stepping 12
1125
            > collect $regs, myglobal
1126
            > end
1127
          >
1128
 
1129
     You may abbreviate `while-stepping' as `ws' or `stepping'.
1130
 
1131
`set default-collect EXPR1, EXPR2, ...'
1132
     This variable is a list of expressions to collect at each
1133
     tracepoint hit.  It is effectively an additional `collect' action
1134
     prepended to every tracepoint action list.  The expressions are
1135
     parsed individually for each tracepoint, so for instance a
1136
     variable named `xyz' may be interpreted as a global for one
1137
     tracepoint, and a local for another, as appropriate to the
1138
     tracepoint's location.
1139
 
1140
`show default-collect'
1141
     Show the list of expressions that are collected by default at each
1142
     tracepoint hit.
1143
 
1144
 
1145

1146
File: gdb.info,  Node: Listing Tracepoints,  Next: Starting and Stopping Trace Experiments,  Prev: Tracepoint Actions,  Up: Set Tracepoints
1147
 
1148
13.1.7 Listing Tracepoints
1149
--------------------------
1150
 
1151
`info tracepoints [NUM]'
1152
     Display information about the tracepoint NUM.  If you don't
1153
     specify a tracepoint number, displays information about all the
1154
     tracepoints defined so far.  The format is similar to that used for
1155
     `info breakpoints'; in fact, `info tracepoints' is the same
1156
     command, simply restricting itself to tracepoints.
1157
 
1158
     A tracepoint's listing may include additional information specific
1159
     to tracing:
1160
 
1161
        * its passcount as given by the `passcount N' command
1162
 
1163
        * its step count as given by the `while-stepping N' command
1164
 
1165
        * its action list as given by the `actions' command.  The
1166
          actions are prefixed with an `A' so as to distinguish them
1167
          from commands.
1168
 
1169
          (gdb) info trace
1170
          Num     Type           Disp Enb Address    What
1171
          1       tracepoint     keep y   0x0804ab57 in foo() at main.cxx:7
1172
                  pass count 1200
1173
                  step count 20
1174
                A while-stepping 20
1175
                A collect globfoo, $regs
1176
                A end
1177
                A collect globfoo2
1178
                A end
1179
          (gdb)
1180
 
1181
     This command can be abbreviated `info tp'.
1182
 
1183

1184
File: gdb.info,  Node: Starting and Stopping Trace Experiments,  Prev: Listing Tracepoints,  Up: Set Tracepoints
1185
 
1186
13.1.8 Starting and Stopping Trace Experiments
1187
----------------------------------------------
1188
 
1189
`tstart'
1190
     This command takes no arguments.  It starts the trace experiment,
1191
     and begins collecting data.  This has the side effect of
1192
     discarding all the data collected in the trace buffer during the
1193
     previous trace experiment.
1194
 
1195
`tstop'
1196
     This command takes no arguments.  It ends the trace experiment, and
1197
     stops collecting data.
1198
 
1199
     *Note*: a trace experiment and data collection may stop
1200
     automatically if any tracepoint's passcount is reached (*note
1201
     Tracepoint Passcounts::), or if the trace buffer becomes full.
1202
 
1203
`tstatus'
1204
     This command displays the status of the current trace data
1205
     collection.
1206
 
1207
   Here is an example of the commands we described so far:
1208
 
1209
     (gdb) trace gdb_c_test
1210
     (gdb) actions
1211
     Enter actions for tracepoint #1, one per line.
1212
     > collect $regs,$locals,$args
1213
     > while-stepping 11
1214
       > collect $regs
1215
       > end
1216
     > end
1217
     (gdb) tstart
1218
        [time passes ...]
1219
     (gdb) tstop
1220
 
1221
   You can choose to continue running the trace experiment even if GDB
1222
disconnects from the target, voluntarily or involuntarily.  For
1223
commands such as `detach', the debugger will ask what you want to do
1224
with the trace.  But for unexpected terminations (GDB crash, network
1225
outage), it would be unfortunate to lose hard-won trace data, so the
1226
variable `disconnected-tracing' lets you decide whether the trace should
1227
continue running without GDB.
1228
 
1229
`set disconnected-tracing on'
1230
`set disconnected-tracing off'
1231
     Choose whether a tracing run should continue to run if GDB has
1232
     disconnected from the target.  Note that `detach' or `quit' will
1233
     ask you directly what to do about a running trace no matter what
1234
     this variable's setting, so the variable is mainly useful for
1235
     handling unexpected situations, such as loss of the network.
1236
 
1237
`show disconnected-tracing'
1238
     Show the current choice for disconnected tracing.
1239
 
1240
 
1241
   When you reconnect to the target, the trace experiment may or may not
1242
still be running; it might have filled the trace buffer in the
1243
meantime, or stopped for one of the other reasons.  If it is running,
1244
it will continue after reconnection.
1245
 
1246
   Upon reconnection, the target will upload information about the
1247
tracepoints in effect.  GDB will then compare that information to the
1248
set of tracepoints currently defined, and attempt to match them up,
1249
allowing for the possibility that the numbers may have changed due to
1250
creation and deletion in the meantime.  If one of the target's
1251
tracepoints does not match any in GDB, the debugger will create a new
1252
tracepoint, so that you have a number with which to specify that
1253
tracepoint.  This matching-up process is necessarily heuristic, and it
1254
may result in useless tracepoints being created; you may simply delete
1255
them if they are of no use.
1256
 
1257

1258
File: gdb.info,  Node: Analyze Collected Data,  Next: Tracepoint Variables,  Prev: Set Tracepoints,  Up: Tracepoints
1259
 
1260
13.2 Using the Collected Data
1261
=============================
1262
 
1263
After the tracepoint experiment ends, you use GDB commands for
1264
examining the trace data.  The basic idea is that each tracepoint
1265
collects a trace "snapshot" every time it is hit and another snapshot
1266
every time it single-steps.  All these snapshots are consecutively
1267
numbered from zero and go into a buffer, and you can examine them
1268
later.  The way you examine them is to "focus" on a specific trace
1269
snapshot.  When the remote stub is focused on a trace snapshot, it will
1270
respond to all GDB requests for memory and registers by reading from
1271
the buffer which belongs to that snapshot, rather than from _real_
1272
memory or registers of the program being debugged.  This means that
1273
*all* GDB commands (`print', `info registers', `backtrace', etc.) will
1274
behave as if we were currently debugging the program state as it was
1275
when the tracepoint occurred.  Any requests for data that are not in
1276
the buffer will fail.
1277
 
1278
* Menu:
1279
 
1280
* tfind::                       How to select a trace snapshot
1281
* tdump::                       How to display all data for a snapshot
1282
* save-tracepoints::            How to save tracepoints for a future run
1283
 
1284

1285
File: gdb.info,  Node: tfind,  Next: tdump,  Up: Analyze Collected Data
1286
 
1287
13.2.1 `tfind N'
1288
----------------
1289
 
1290
The basic command for selecting a trace snapshot from the buffer is
1291
`tfind N', which finds trace snapshot number N, counting from zero.  If
1292
no argument N is given, the next snapshot is selected.
1293
 
1294
   Here are the various forms of using the `tfind' command.
1295
 
1296
`tfind start'
1297
     Find the first snapshot in the buffer.  This is a synonym for
1298
     `tfind 0' (since 0 is the number of the first snapshot).
1299
 
1300
`tfind none'
1301
     Stop debugging trace snapshots, resume _live_ debugging.
1302
 
1303
`tfind end'
1304
     Same as `tfind none'.
1305
 
1306
`tfind'
1307
     No argument means find the next trace snapshot.
1308
 
1309
`tfind -'
1310
     Find the previous trace snapshot before the current one.  This
1311
     permits retracing earlier steps.
1312
 
1313
`tfind tracepoint NUM'
1314
     Find the next snapshot associated with tracepoint NUM.  Search
1315
     proceeds forward from the last examined trace snapshot.  If no
1316
     argument NUM is given, it means find the next snapshot collected
1317
     for the same tracepoint as the current snapshot.
1318
 
1319
`tfind pc ADDR'
1320
     Find the next snapshot associated with the value ADDR of the
1321
     program counter.  Search proceeds forward from the last examined
1322
     trace snapshot.  If no argument ADDR is given, it means find the
1323
     next snapshot with the same value of PC as the current snapshot.
1324
 
1325
`tfind outside ADDR1, ADDR2'
1326
     Find the next snapshot whose PC is outside the given range of
1327
     addresses (exclusive).
1328
 
1329
`tfind range ADDR1, ADDR2'
1330
     Find the next snapshot whose PC is between ADDR1 and ADDR2
1331
     (inclusive).
1332
 
1333
`tfind line [FILE:]N'
1334
     Find the next snapshot associated with the source line N.  If the
1335
     optional argument FILE is given, refer to line N in that source
1336
     file.  Search proceeds forward from the last examined trace
1337
     snapshot.  If no argument N is given, it means find the next line
1338
     other than the one currently being examined; thus saying `tfind
1339
     line' repeatedly can appear to have the same effect as stepping
1340
     from line to line in a _live_ debugging session.
1341
 
1342
   The default arguments for the `tfind' commands are specifically
1343
designed to make it easy to scan through the trace buffer.  For
1344
instance, `tfind' with no argument selects the next trace snapshot, and
1345
`tfind -' with no argument selects the previous trace snapshot.  So, by
1346
giving one `tfind' command, and then simply hitting  repeatedly
1347
you can examine all the trace snapshots in order.  Or, by saying `tfind
1348
-' and then hitting  repeatedly you can examine the snapshots in
1349
reverse order.  The `tfind line' command with no argument selects the
1350
snapshot for the next source line executed.  The `tfind pc' command with
1351
no argument selects the next snapshot with the same program counter
1352
(PC) as the current frame.  The `tfind tracepoint' command with no
1353
argument selects the next trace snapshot collected by the same
1354
tracepoint as the current one.
1355
 
1356
   In addition to letting you scan through the trace buffer manually,
1357
these commands make it easy to construct GDB scripts that scan through
1358
the trace buffer and print out whatever collected data you are
1359
interested in.  Thus, if we want to examine the PC, FP, and SP
1360
registers from each trace frame in the buffer, we can say this:
1361
 
1362
     (gdb) tfind start
1363
     (gdb) while ($trace_frame != -1)
1364
     > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
1365
               $trace_frame, $pc, $sp, $fp
1366
     > tfind
1367
     > end
1368
 
1369
     Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
1370
     Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
1371
     Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
1372
     Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
1373
     Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
1374
     Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
1375
     Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
1376
     Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
1377
     Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
1378
     Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
1379
     Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
1380
 
1381
   Or, if we want to examine the variable `X' at each source line in
1382
the buffer:
1383
 
1384
     (gdb) tfind start
1385
     (gdb) while ($trace_frame != -1)
1386
     > printf "Frame %d, X == %d\n", $trace_frame, X
1387
     > tfind line
1388
     > end
1389
 
1390
     Frame 0, X = 1
1391
     Frame 7, X = 2
1392
     Frame 13, X = 255
1393
 
1394

1395
File: gdb.info,  Node: tdump,  Next: save-tracepoints,  Prev: tfind,  Up: Analyze Collected Data
1396
 
1397
13.2.2 `tdump'
1398
--------------
1399
 
1400
This command takes no arguments.  It prints all the data collected at
1401
the current trace snapshot.
1402
 
1403
     (gdb) trace 444
1404
     (gdb) actions
1405
     Enter actions for tracepoint #2, one per line:
1406
     > collect $regs, $locals, $args, gdb_long_test
1407
     > end
1408
 
1409
     (gdb) tstart
1410
 
1411
     (gdb) tfind line 444
1412
     #0  gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
1413
     at gdb_test.c:444
1414
     444        printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
1415
 
1416
     (gdb) tdump
1417
     Data collected at tracepoint 2, trace frame 1:
1418
     d0             0xc4aa0085       -995491707
1419
     d1             0x18     24
1420
     d2             0x80     128
1421
     d3             0x33     51
1422
     d4             0x71aea3d        119204413
1423
     d5             0x22     34
1424
     d6             0xe0     224
1425
     d7             0x380035 3670069
1426
     a0             0x19e24a 1696330
1427
     a1             0x3000668        50333288
1428
     a2             0x100    256
1429
     a3             0x322000 3284992
1430
     a4             0x3000698        50333336
1431
     a5             0x1ad3cc 1758156
1432
     fp             0x30bf3c 0x30bf3c
1433
     sp             0x30bf34 0x30bf34
1434
     ps             0x0      0
1435
     pc             0x20b2c8 0x20b2c8
1436
     fpcontrol      0x0      0
1437
     fpstatus       0x0      0
1438
     fpiaddr        0x0      0
1439
     p = 0x20e5b4 "gdb-test"
1440
     p1 = (void *) 0x11
1441
     p2 = (void *) 0x22
1442
     p3 = (void *) 0x33
1443
     p4 = (void *) 0x44
1444
     p5 = (void *) 0x55
1445
     p6 = (void *) 0x66
1446
     gdb_long_test = 17 '\021'
1447
 
1448
     (gdb)
1449
 
1450

1451
File: gdb.info,  Node: save-tracepoints,  Prev: tdump,  Up: Analyze Collected Data
1452
 
1453
13.2.3 `save-tracepoints FILENAME'
1454
----------------------------------
1455
 
1456
This command saves all current tracepoint definitions together with
1457
their actions and passcounts, into a file `FILENAME' suitable for use
1458
in a later debugging session.  To read the saved tracepoint
1459
definitions, use the `source' command (*note Command Files::).
1460
 
1461

1462
File: gdb.info,  Node: Tracepoint Variables,  Next: Trace Files,  Prev: Analyze Collected Data,  Up: Tracepoints
1463
 
1464
13.3 Convenience Variables for Tracepoints
1465
==========================================
1466
 
1467
`(int) $trace_frame'
1468
     The current trace snapshot (a.k.a. "frame") number, or -1 if no
1469
     snapshot is selected.
1470
 
1471
`(int) $tracepoint'
1472
     The tracepoint for the current trace snapshot.
1473
 
1474
`(int) $trace_line'
1475
     The line number for the current trace snapshot.
1476
 
1477
`(char []) $trace_file'
1478
     The source file for the current trace snapshot.
1479
 
1480
`(char []) $trace_func'
1481
     The name of the function containing `$tracepoint'.
1482
 
1483
   Note: `$trace_file' is not suitable for use in `printf', use
1484
`output' instead.
1485
 
1486
   Here's a simple example of using these convenience variables for
1487
stepping through all the trace snapshots and printing some of their
1488
data.  Note that these are not the same as trace state variables, which
1489
are managed by the target.
1490
 
1491
     (gdb) tfind start
1492
 
1493
     (gdb) while $trace_frame != -1
1494
     > output $trace_file
1495
     > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
1496
     > tfind
1497
     > end
1498
 
1499

1500
File: gdb.info,  Node: Trace Files,  Prev: Tracepoint Variables,  Up: Tracepoints
1501
 
1502
13.4 Using Trace Files
1503
======================
1504
 
1505
In some situations, the target running a trace experiment may no longer
1506
be available; perhaps it crashed, or the hardware was needed for a
1507
different activity.  To handle these cases, you can arrange to dump the
1508
trace data into a file, and later use that file as a source of trace
1509
data, via the `target tfile' command.
1510
 
1511
`tsave [ -r ] FILENAME'
1512
     Save the trace data to FILENAME.  By default, this command assumes
1513
     that FILENAME refers to the host filesystem, so if necessary GDB
1514
     will copy raw trace data up from the target and then save it.  If
1515
     the target supports it, you can also supply the optional argument
1516
     `-r' ("remote") to direct the target to save the data directly
1517
     into FILENAME in its own filesystem, which may be more efficient
1518
     if the trace buffer is very large.  (Note, however, that `target
1519
     tfile' can only read from files accessible to the host.)
1520
 
1521
`target tfile FILENAME'
1522
     Use the file named FILENAME as a source of trace data.  Commands
1523
     that examine data work as they do with a live target, but it is not
1524
     possible to run any new trace experiments.  `tstatus' will report
1525
     the state of the trace run at the moment the data was saved, as
1526
     well as the current trace frame you are examining.  FILENAME must
1527
     be on a filesystem accessible to the host.
1528
 
1529
 
1530

1531
File: gdb.info,  Node: Overlays,  Next: Languages,  Prev: Tracepoints,  Up: Top
1532
 
1533
14 Debugging Programs That Use Overlays
1534
***************************************
1535
 
1536
If your program is too large to fit completely in your target system's
1537
memory, you can sometimes use "overlays" to work around this problem.
1538
GDB provides some support for debugging programs that use overlays.
1539
 
1540
* Menu:
1541
 
1542
* How Overlays Work::              A general explanation of overlays.
1543
* Overlay Commands::               Managing overlays in GDB.
1544
* Automatic Overlay Debugging::    GDB can find out which overlays are
1545
                                   mapped by asking the inferior.
1546
* Overlay Sample Program::         A sample program using overlays.
1547
 
1548

1549
File: gdb.info,  Node: How Overlays Work,  Next: Overlay Commands,  Up: Overlays
1550
 
1551
14.1 How Overlays Work
1552
======================
1553
 
1554
Suppose you have a computer whose instruction address space is only 64
1555
kilobytes long, but which has much more memory which can be accessed by
1556
other means: special instructions, segment registers, or memory
1557
management hardware, for example.  Suppose further that you want to
1558
adapt a program which is larger than 64 kilobytes to run on this system.
1559
 
1560
   One solution is to identify modules of your program which are
1561
relatively independent, and need not call each other directly; call
1562
these modules "overlays".  Separate the overlays from the main program,
1563
and place their machine code in the larger memory.  Place your main
1564
program in instruction memory, but leave at least enough space there to
1565
hold the largest overlay as well.
1566
 
1567
   Now, to call a function located in an overlay, you must first copy
1568
that overlay's machine code from the large memory into the space set
1569
aside for it in the instruction memory, and then jump to its entry point
1570
there.
1571
 
1572
         Data             Instruction            Larger
1573
     Address Space       Address Space        Address Space
1574
     +-----------+       +-----------+        +-----------+
1575
     |           |       |           |        |           |
1576
     +-----------+       +-----------+        +-----------+<-- overlay 1
1577
     | program   |       |   main    |   .----| overlay 1 | load address
1578
     | variables |       |  program  |   |    +-----------+
1579
     | and heap  |       |           |   |    |           |
1580
     +-----------+       |           |   |    +-----------+<-- overlay 2
1581
     |           |       +-----------+   |    |           | load address
1582
     +-----------+       |           |   |  .-| overlay 2 |
1583
                         |           |   |  | |           |
1584
              mapped --->+-----------+   |  | +-----------+
1585
              address    |           |   |  | |           |
1586
                         |  overlay  | <-'  | |           |
1587
                         |   area    |  <---' +-----------+<-- overlay 3
1588
                         |           | <---.  |           | load address
1589
                         +-----------+     `--| overlay 3 |
1590
                         |           |        |           |
1591
                         +-----------+        |           |
1592
                                              +-----------+
1593
                                              |           |
1594
                                              +-----------+
1595
 
1596
                         A code overlay
1597
 
1598
   The diagram (*note A code overlay::) shows a system with separate
1599
data and instruction address spaces.  To map an overlay, the program
1600
copies its code from the larger address space to the instruction
1601
address space.  Since the overlays shown here all use the same mapped
1602
address, only one may be mapped at a time.  For a system with a single
1603
address space for data and instructions, the diagram would be similar,
1604
except that the program variables and heap would share an address space
1605
with the main program and the overlay area.
1606
 
1607
   An overlay loaded into instruction memory and ready for use is
1608
called a "mapped" overlay; its "mapped address" is its address in the
1609
instruction memory.  An overlay not present (or only partially present)
1610
in instruction memory is called "unmapped"; its "load address" is its
1611
address in the larger memory.  The mapped address is also called the
1612
"virtual memory address", or "VMA"; the load address is also called the
1613
"load memory address", or "LMA".
1614
 
1615
   Unfortunately, overlays are not a completely transparent way to
1616
adapt a program to limited instruction memory.  They introduce a new
1617
set of global constraints you must keep in mind as you design your
1618
program:
1619
 
1620
   * Before calling or returning to a function in an overlay, your
1621
     program must make sure that overlay is actually mapped.
1622
     Otherwise, the call or return will transfer control to the right
1623
     address, but in the wrong overlay, and your program will probably
1624
     crash.
1625
 
1626
   * If the process of mapping an overlay is expensive on your system,
1627
     you will need to choose your overlays carefully to minimize their
1628
     effect on your program's performance.
1629
 
1630
   * The executable file you load onto your system must contain each
1631
     overlay's instructions, appearing at the overlay's load address,
1632
     not its mapped address.  However, each overlay's instructions must
1633
     be relocated and its symbols defined as if the overlay were at its
1634
     mapped address.  You can use GNU linker scripts to specify
1635
     different load and relocation addresses for pieces of your
1636
     program; see *Note Overlay Description: (ld.info)Overlay
1637
     Description.
1638
 
1639
   * The procedure for loading executable files onto your system must
1640
     be able to load their contents into the larger address space as
1641
     well as the instruction and data spaces.
1642
 
1643
 
1644
   The overlay system described above is rather simple, and could be
1645
improved in many ways:
1646
 
1647
   * If your system has suitable bank switch registers or memory
1648
     management hardware, you could use those facilities to make an
1649
     overlay's load area contents simply appear at their mapped address
1650
     in instruction space.  This would probably be faster than copying
1651
     the overlay to its mapped area in the usual way.
1652
 
1653
   * If your overlays are small enough, you could set aside more than
1654
     one overlay area, and have more than one overlay mapped at a time.
1655
 
1656
   * You can use overlays to manage data, as well as instructions.  In
1657
     general, data overlays are even less transparent to your design
1658
     than code overlays: whereas code overlays only require care when
1659
     you call or return to functions, data overlays require care every
1660
     time you access the data.  Also, if you change the contents of a
1661
     data overlay, you must copy its contents back out to its load
1662
     address before you can copy a different data overlay into the same
1663
     mapped area.
1664
 
1665
 
1666

1667
File: gdb.info,  Node: Overlay Commands,  Next: Automatic Overlay Debugging,  Prev: How Overlays Work,  Up: Overlays
1668
 
1669
14.2 Overlay Commands
1670
=====================
1671
 
1672
To use GDB's overlay support, each overlay in your program must
1673
correspond to a separate section of the executable file.  The section's
1674
virtual memory address and load memory address must be the overlay's
1675
mapped and load addresses.  Identifying overlays with sections allows
1676
GDB to determine the appropriate address of a function or variable,
1677
depending on whether the overlay is mapped or not.
1678
 
1679
   GDB's overlay commands all start with the word `overlay'; you can
1680
abbreviate this as `ov' or `ovly'.  The commands are:
1681
 
1682
`overlay off'
1683
     Disable GDB's overlay support.  When overlay support is disabled,
1684
     GDB assumes that all functions and variables are always present at
1685
     their mapped addresses.  By default, GDB's overlay support is
1686
     disabled.
1687
 
1688
`overlay manual'
1689
     Enable "manual" overlay debugging.  In this mode, GDB relies on
1690
     you to tell it which overlays are mapped, and which are not, using
1691
     the `overlay map-overlay' and `overlay unmap-overlay' commands
1692
     described below.
1693
 
1694
`overlay map-overlay OVERLAY'
1695
`overlay map OVERLAY'
1696
     Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of
1697
     the object file section containing the overlay.  When an overlay
1698
     is mapped, GDB assumes it can find the overlay's functions and
1699
     variables at their mapped addresses.  GDB assumes that any other
1700
     overlays whose mapped ranges overlap that of OVERLAY are now
1701
     unmapped.
1702
 
1703
`overlay unmap-overlay OVERLAY'
1704
`overlay unmap OVERLAY'
1705
     Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the
1706
     name of the object file section containing the overlay.  When an
1707
     overlay is unmapped, GDB assumes it can find the overlay's
1708
     functions and variables at their load addresses.
1709
 
1710
`overlay auto'
1711
     Enable "automatic" overlay debugging.  In this mode, GDB consults
1712
     a data structure the overlay manager maintains in the inferior to
1713
     see which overlays are mapped.  For details, see *Note Automatic
1714
     Overlay Debugging::.
1715
 
1716
`overlay load-target'
1717
`overlay load'
1718
     Re-read the overlay table from the inferior.  Normally, GDB
1719
     re-reads the table GDB automatically each time the inferior stops,
1720
     so this command should only be necessary if you have changed the
1721
     overlay mapping yourself using GDB.  This command is only useful
1722
     when using automatic overlay debugging.
1723
 
1724
`overlay list-overlays'
1725
`overlay list'
1726
     Display a list of the overlays currently mapped, along with their
1727
     mapped addresses, load addresses, and sizes.
1728
 
1729
 
1730
   Normally, when GDB prints a code address, it includes the name of
1731
the function the address falls in:
1732
 
1733
     (gdb) print main
1734
     $3 = {int ()} 0x11a0 
1735
   When overlay debugging is enabled, GDB recognizes code in unmapped
1736
overlays, and prints the names of unmapped functions with asterisks
1737
around them.  For example, if `foo' is a function in an unmapped
1738
overlay, GDB prints it this way:
1739
 
1740
     (gdb) overlay list
1741
     No sections are mapped.
1742
     (gdb) print foo
1743
     $5 = {int (int)} 0x100000 <*foo*>
1744
   When `foo''s overlay is mapped, GDB prints the function's name
1745
normally:
1746
 
1747
     (gdb) overlay list
1748
     Section .ov.foo.text, loaded at 0x100000 - 0x100034,
1749
             mapped at 0x1016 - 0x104a
1750
     (gdb) print foo
1751
     $6 = {int (int)} 0x1016 
1752
 
1753
   When overlay debugging is enabled, GDB can find the correct address
1754
for functions and variables in an overlay, whether or not the overlay
1755
is mapped.  This allows most GDB commands, like `break' and
1756
`disassemble', to work normally, even on unmapped code.  However, GDB's
1757
breakpoint support has some limitations:
1758
 
1759
   * You can set breakpoints in functions in unmapped overlays, as long
1760
     as GDB can write to the overlay at its load address.
1761
 
1762
   * GDB can not set hardware or simulator-based breakpoints in
1763
     unmapped overlays.  However, if you set a breakpoint at the end of
1764
     your overlay manager (and tell GDB which overlays are now mapped,
1765
     if you are using manual overlay management), GDB will re-set its
1766
     breakpoints properly.
1767
 
1768

1769
File: gdb.info,  Node: Automatic Overlay Debugging,  Next: Overlay Sample Program,  Prev: Overlay Commands,  Up: Overlays
1770
 
1771
14.3 Automatic Overlay Debugging
1772
================================
1773
 
1774
GDB can automatically track which overlays are mapped and which are
1775
not, given some simple co-operation from the overlay manager in the
1776
inferior.  If you enable automatic overlay debugging with the `overlay
1777
auto' command (*note Overlay Commands::), GDB looks in the inferior's
1778
memory for certain variables describing the current state of the
1779
overlays.
1780
 
1781
   Here are the variables your overlay manager must define to support
1782
GDB's automatic overlay debugging:
1783
 
1784
`_ovly_table':
1785
     This variable must be an array of the following structures:
1786
 
1787
          struct
1788
          {
1789
            /* The overlay's mapped address.  */
1790
            unsigned long vma;
1791
 
1792
            /* The size of the overlay, in bytes.  */
1793
            unsigned long size;
1794
 
1795
            /* The overlay's load address.  */
1796
            unsigned long lma;
1797
 
1798
            /* Non-zero if the overlay is currently mapped;
1799
               zero otherwise.  */
1800
            unsigned long mapped;
1801
          }
1802
 
1803
`_novlys':
1804
     This variable must be a four-byte signed integer, holding the total
1805
     number of elements in `_ovly_table'.
1806
 
1807
 
1808
   To decide whether a particular overlay is mapped or not, GDB looks
1809
for an entry in `_ovly_table' whose `vma' and `lma' members equal the
1810
VMA and LMA of the overlay's section in the executable file.  When GDB
1811
finds a matching entry, it consults the entry's `mapped' member to
1812
determine whether the overlay is currently mapped.
1813
 
1814
   In addition, your overlay manager may define a function called
1815
`_ovly_debug_event'.  If this function is defined, GDB will silently
1816
set a breakpoint there.  If the overlay manager then calls this
1817
function whenever it has changed the overlay table, this will enable
1818
GDB to accurately keep track of which overlays are in program memory,
1819
and update any breakpoints that may be set in overlays.  This will
1820
allow breakpoints to work even if the overlays are kept in ROM or other
1821
non-writable memory while they are not being executed.
1822
 
1823

1824
File: gdb.info,  Node: Overlay Sample Program,  Prev: Automatic Overlay Debugging,  Up: Overlays
1825
 
1826
14.4 Overlay Sample Program
1827
===========================
1828
 
1829
When linking a program which uses overlays, you must place the overlays
1830
at their load addresses, while relocating them to run at their mapped
1831
addresses.  To do this, you must write a linker script (*note Overlay
1832
Description: (ld.info)Overlay Description.).  Unfortunately, since
1833
linker scripts are specific to a particular host system, target
1834
architecture, and target memory layout, this manual cannot provide
1835
portable sample code demonstrating GDB's overlay support.
1836
 
1837
   However, the GDB source distribution does contain an overlaid
1838
program, with linker scripts for a few systems, as part of its test
1839
suite.  The program consists of the following files from
1840
`gdb/testsuite/gdb.base':
1841
 
1842
`overlays.c'
1843
     The main program file.
1844
 
1845
`ovlymgr.c'
1846
     A simple overlay manager, used by `overlays.c'.
1847
 
1848
`foo.c'
1849
`bar.c'
1850
`baz.c'
1851
`grbx.c'
1852
     Overlay modules, loaded and used by `overlays.c'.
1853
 
1854
`d10v.ld'
1855
`m32r.ld'
1856
     Linker scripts for linking the test program on the `d10v-elf' and
1857
     `m32r-elf' targets.
1858
 
1859
   You can build the test program using the `d10v-elf' GCC
1860
cross-compiler like this:
1861
 
1862
     $ d10v-elf-gcc -g -c overlays.c
1863
     $ d10v-elf-gcc -g -c ovlymgr.c
1864
     $ d10v-elf-gcc -g -c foo.c
1865
     $ d10v-elf-gcc -g -c bar.c
1866
     $ d10v-elf-gcc -g -c baz.c
1867
     $ d10v-elf-gcc -g -c grbx.c
1868
     $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
1869
                       baz.o grbx.o -Wl,-Td10v.ld -o overlays
1870
 
1871
   The build process is identical for any other architecture, except
1872
that you must substitute the appropriate compiler and linker script for
1873
the target system for `d10v-elf-gcc' and `d10v.ld'.
1874
 
1875

1876
File: gdb.info,  Node: Languages,  Next: Symbols,  Prev: Overlays,  Up: Top
1877
 
1878
15 Using GDB with Different Languages
1879
*************************************
1880
 
1881
Although programming languages generally have common aspects, they are
1882
rarely expressed in the same manner.  For instance, in ANSI C,
1883
dereferencing a pointer `p' is accomplished by `*p', but in Modula-2,
1884
it is accomplished by `p^'.  Values can also be represented (and
1885
displayed) differently.  Hex numbers in C appear as `0x1ae', while in
1886
Modula-2 they appear as `1AEH'.
1887
 
1888
   Language-specific information is built into GDB for some languages,
1889
allowing you to express operations like the above in your program's
1890
native language, and allowing GDB to output values in a manner
1891
consistent with the syntax of your program's native language.  The
1892
language you use to build expressions is called the "working language".
1893
 
1894
* Menu:
1895
 
1896
* Setting::                     Switching between source languages
1897
* Show::                        Displaying the language
1898
* Checks::                      Type and range checks
1899
* Supported Languages::         Supported languages
1900
* Unsupported Languages::       Unsupported languages
1901
 
1902

1903
File: gdb.info,  Node: Setting,  Next: Show,  Up: Languages
1904
 
1905
15.1 Switching Between Source Languages
1906
=======================================
1907
 
1908
There are two ways to control the working language--either have GDB set
1909
it automatically, or select it manually yourself.  You can use the `set
1910
language' command for either purpose.  On startup, GDB defaults to
1911
setting the language automatically.  The working language is used to
1912
determine how expressions you type are interpreted, how values are
1913
printed, etc.
1914
 
1915
   In addition to the working language, every source file that GDB
1916
knows about has its own working language.  For some object file
1917
formats, the compiler might indicate which language a particular source
1918
file is in.  However, most of the time GDB infers the language from the
1919
name of the file.  The language of a source file controls whether C++
1920
names are demangled--this way `backtrace' can show each frame
1921
appropriately for its own language.  There is no way to set the
1922
language of a source file from within GDB, but you can set the language
1923
associated with a filename extension.  *Note Displaying the Language:
1924
Show.
1925
 
1926
   This is most commonly a problem when you use a program, such as
1927
`cfront' or `f2c', that generates C but is written in another language.
1928
In that case, make the program use `#line' directives in its C output;
1929
that way GDB will know the correct language of the source code of the
1930
original program, and will display that source code, not the generated
1931
C code.
1932
 
1933
* Menu:
1934
 
1935
* Filenames::                   Filename extensions and languages.
1936
* Manually::                    Setting the working language manually
1937
* Automatically::               Having GDB infer the source language
1938
 
1939

1940
File: gdb.info,  Node: Filenames,  Next: Manually,  Up: Setting
1941
 
1942
15.1.1 List of Filename Extensions and Languages
1943
------------------------------------------------
1944
 
1945
If a source file name ends in one of the following extensions, then GDB
1946
infers that its language is the one indicated.
1947
 
1948
`.ada'
1949
`.ads'
1950
`.adb'
1951
`.a'
1952
     Ada source file.
1953
 
1954
`.c'
1955
     C source file
1956
 
1957
`.C'
1958
`.cc'
1959
`.cp'
1960
`.cpp'
1961
`.cxx'
1962
`.c++'
1963
     C++ source file
1964
 
1965
`.m'
1966
     Objective-C source file
1967
 
1968
`.f'
1969
`.F'
1970
     Fortran source file
1971
 
1972
`.mod'
1973
     Modula-2 source file
1974
 
1975
`.s'
1976
`.S'
1977
     Assembler source file.  This actually behaves almost like C, but
1978
     GDB does not skip over function prologues when stepping.
1979
 
1980
   In addition, you may set the language associated with a filename
1981
extension.  *Note Displaying the Language: Show.
1982
 
1983

1984
File: gdb.info,  Node: Manually,  Next: Automatically,  Prev: Filenames,  Up: Setting
1985
 
1986
15.1.2 Setting the Working Language
1987
-----------------------------------
1988
 
1989
If you allow GDB to set the language automatically, expressions are
1990
interpreted the same way in your debugging session and your program.
1991
 
1992
   If you wish, you may set the language manually.  To do this, issue
1993
the command `set language LANG', where LANG is the name of a language,
1994
such as `c' or `modula-2'.  For a list of the supported languages, type
1995
`set language'.
1996
 
1997
   Setting the language manually prevents GDB from updating the working
1998
language automatically.  This can lead to confusion if you try to debug
1999
a program when the working language is not the same as the source
2000
language, when an expression is acceptable to both languages--but means
2001
different things.  For instance, if the current source file were
2002
written in C, and GDB was parsing Modula-2, a command such as:
2003
 
2004
     print a = b + c
2005
 
2006
might not have the effect you intended.  In C, this means to add `b'
2007
and `c' and place the result in `a'.  The result printed would be the
2008
value of `a'.  In Modula-2, this means to compare `a' to the result of
2009
`b+c', yielding a `BOOLEAN' value.
2010
 
2011

2012
File: gdb.info,  Node: Automatically,  Prev: Manually,  Up: Setting
2013
 
2014
15.1.3 Having GDB Infer the Source Language
2015
-------------------------------------------
2016
 
2017
To have GDB set the working language automatically, use `set language
2018
local' or `set language auto'.  GDB then infers the working language.
2019
That is, when your program stops in a frame (usually by encountering a
2020
breakpoint), GDB sets the working language to the language recorded for
2021
the function in that frame.  If the language for a frame is unknown
2022
(that is, if the function or block corresponding to the frame was
2023
defined in a source file that does not have a recognized extension),
2024
the current working language is not changed, and GDB issues a warning.
2025
 
2026
   This may not seem necessary for most programs, which are written
2027
entirely in one source language.  However, program modules and libraries
2028
written in one source language can be used by a main program written in
2029
a different source language.  Using `set language auto' in this case
2030
frees you from having to set the working language manually.
2031
 
2032

2033
File: gdb.info,  Node: Show,  Next: Checks,  Prev: Setting,  Up: Languages
2034
 
2035
15.2 Displaying the Language
2036
============================
2037
 
2038
The following commands help you find out which language is the working
2039
language, and also what language source files were written in.
2040
 
2041
`show language'
2042
     Display the current working language.  This is the language you
2043
     can use with commands such as `print' to build and compute
2044
     expressions that may involve variables in your program.
2045
 
2046
`info frame'
2047
     Display the source language for this frame.  This language becomes
2048
     the working language if you use an identifier from this frame.
2049
     *Note Information about a Frame: Frame Info, to identify the other
2050
     information listed here.
2051
 
2052
`info source'
2053
     Display the source language of this source file.  *Note Examining
2054
     the Symbol Table: Symbols, to identify the other information
2055
     listed here.
2056
 
2057
   In unusual circumstances, you may have source files with extensions
2058
not in the standard list.  You can then set the extension associated
2059
with a language explicitly:
2060
 
2061
`set extension-language EXT LANGUAGE'
2062
     Tell GDB that source files with extension EXT are to be assumed as
2063
     written in the source language LANGUAGE.
2064
 
2065
`info extensions'
2066
     List all the filename extensions and the associated languages.
2067
 
2068

2069
File: gdb.info,  Node: Checks,  Next: Supported Languages,  Prev: Show,  Up: Languages
2070
 
2071
15.3 Type and Range Checking
2072
============================
2073
 
2074
     _Warning:_ In this release, the GDB commands for type and range
2075
     checking are included, but they do not yet have any effect.  This
2076
     section documents the intended facilities.
2077
 
2078
   Some languages are designed to guard you against making seemingly
2079
common errors through a series of compile- and run-time checks.  These
2080
include checking the type of arguments to functions and operators, and
2081
making sure mathematical overflows are caught at run time.  Checks such
2082
as these help to ensure a program's correctness once it has been
2083
compiled by eliminating type mismatches, and providing active checks
2084
for range errors when your program is running.
2085
 
2086
   GDB can check for conditions like the above if you wish.  Although
2087
GDB does not check the statements in your program, it can check
2088
expressions entered directly into GDB for evaluation via the `print'
2089
command, for example.  As with the working language, GDB can also
2090
decide whether or not to check automatically based on your program's
2091
source language.  *Note Supported Languages: Supported Languages, for
2092
the default settings of supported languages.
2093
 
2094
* Menu:
2095
 
2096
* Type Checking::               An overview of type checking
2097
* Range Checking::              An overview of range checking
2098
 
2099

2100
File: gdb.info,  Node: Type Checking,  Next: Range Checking,  Up: Checks
2101
 
2102
15.3.1 An Overview of Type Checking
2103
-----------------------------------
2104
 
2105
Some languages, such as Modula-2, are strongly typed, meaning that the
2106
arguments to operators and functions have to be of the correct type,
2107
otherwise an error occurs.  These checks prevent type mismatch errors
2108
from ever causing any run-time problems.  For example,
2109
 
2110
     1 + 2 => 3
2111
but
2112
     error--> 1 + 2.3
2113
 
2114
   The second example fails because the `CARDINAL' 1 is not
2115
type-compatible with the `REAL' 2.3.
2116
 
2117
   For the expressions you use in GDB commands, you can tell the GDB
2118
type checker to skip checking; to treat any mismatches as errors and
2119
abandon the expression; or to only issue warnings when type mismatches
2120
occur, but evaluate the expression anyway.  When you choose the last of
2121
these, GDB evaluates expressions like the second example above, but
2122
also issues a warning.
2123
 
2124
   Even if you turn type checking off, there may be other reasons
2125
related to type that prevent GDB from evaluating an expression.  For
2126
instance, GDB does not know how to add an `int' and a `struct foo'.
2127
These particular type errors have nothing to do with the language in
2128
use, and usually arise from expressions, such as the one described
2129
above, which make little sense to evaluate anyway.
2130
 
2131
   Each language defines to what degree it is strict about type.  For
2132
instance, both Modula-2 and C require the arguments to arithmetical
2133
operators to be numbers.  In C, enumerated types and pointers can be
2134
represented as numbers, so that they are valid arguments to mathematical
2135
operators.  *Note Supported Languages: Supported Languages, for further
2136
details on specific languages.
2137
 
2138
   GDB provides some additional commands for controlling the type
2139
checker:
2140
 
2141
`set check type auto'
2142
     Set type checking on or off based on the current working language.
2143
     *Note Supported Languages: Supported Languages, for the default
2144
     settings for each language.
2145
 
2146
`set check type on'
2147
`set check type off'
2148
     Set type checking on or off, overriding the default setting for the
2149
     current working language.  Issue a warning if the setting does not
2150
     match the language default.  If any type mismatches occur in
2151
     evaluating an expression while type checking is on, GDB prints a
2152
     message and aborts evaluation of the expression.
2153
 
2154
`set check type warn'
2155
     Cause the type checker to issue warnings, but to always attempt to
2156
     evaluate the expression.  Evaluating the expression may still be
2157
     impossible for other reasons.  For example, GDB cannot add numbers
2158
     and structures.
2159
 
2160
`show type'
2161
     Show the current setting of the type checker, and whether or not
2162
     GDB is setting it automatically.
2163
 
2164

2165
File: gdb.info,  Node: Range Checking,  Prev: Type Checking,  Up: Checks
2166
 
2167
15.3.2 An Overview of Range Checking
2168
------------------------------------
2169
 
2170
In some languages (such as Modula-2), it is an error to exceed the
2171
bounds of a type; this is enforced with run-time checks.  Such range
2172
checking is meant to ensure program correctness by making sure
2173
computations do not overflow, or indices on an array element access do
2174
not exceed the bounds of the array.
2175
 
2176
   For expressions you use in GDB commands, you can tell GDB to treat
2177
range errors in one of three ways: ignore them, always treat them as
2178
errors and abandon the expression, or issue warnings but evaluate the
2179
expression anyway.
2180
 
2181
   A range error can result from numerical overflow, from exceeding an
2182
array index bound, or when you type a constant that is not a member of
2183
any type.  Some languages, however, do not treat overflows as an error.
2184
In many implementations of C, mathematical overflow causes the result
2185
to "wrap around" to lower values--for example, if M is the largest
2186
integer value, and S is the smallest, then
2187
 
2188
     M + 1 => S
2189
 
2190
   This, too, is specific to individual languages, and in some cases
2191
specific to individual compilers or machines.  *Note Supported
2192
Languages: Supported Languages, for further details on specific
2193
languages.
2194
 
2195
   GDB provides some additional commands for controlling the range
2196
checker:
2197
 
2198
`set check range auto'
2199
     Set range checking on or off based on the current working language.
2200
     *Note Supported Languages: Supported Languages, for the default
2201
     settings for each language.
2202
 
2203
`set check range on'
2204
`set check range off'
2205
     Set range checking on or off, overriding the default setting for
2206
     the current working language.  A warning is issued if the setting
2207
     does not match the language default.  If a range error occurs and
2208
     range checking is on, then a message is printed and evaluation of
2209
     the expression is aborted.
2210
 
2211
`set check range warn'
2212
     Output messages when the GDB range checker detects a range error,
2213
     but attempt to evaluate the expression anyway.  Evaluating the
2214
     expression may still be impossible for other reasons, such as
2215
     accessing memory that the process does not own (a typical example
2216
     from many Unix systems).
2217
 
2218
`show range'
2219
     Show the current setting of the range checker, and whether or not
2220
     it is being set automatically by GDB.
2221
 
2222

2223
File: gdb.info,  Node: Supported Languages,  Next: Unsupported Languages,  Prev: Checks,  Up: Languages
2224
 
2225
15.4 Supported Languages
2226
========================
2227
 
2228
GDB supports C, C++, Objective-C, Fortran, Java, Pascal, assembly,
2229
Modula-2, and Ada.  Some GDB features may be used in expressions
2230
regardless of the language you use: the GDB `@' and `::' operators, and
2231
the `{type}addr' construct (*note Expressions: Expressions.) can be
2232
used with the constructs of any supported language.
2233
 
2234
   The following sections detail to what degree each source language is
2235
supported by GDB.  These sections are not meant to be language
2236
tutorials or references, but serve only as a reference guide to what the
2237
GDB expression parser accepts, and what input and output formats should
2238
look like for different languages.  There are many good books written
2239
on each of these languages; please look to these for a language
2240
reference or tutorial.
2241
 
2242
* Menu:
2243
 
2244
* C::                           C and C++
2245
* Objective-C::                 Objective-C
2246
* Fortran::                     Fortran
2247
* Pascal::                      Pascal
2248
* Modula-2::                    Modula-2
2249
* Ada::                         Ada
2250
 
2251

2252
File: gdb.info,  Node: C,  Next: Objective-C,  Up: Supported Languages
2253
 
2254
15.4.1 C and C++
2255
----------------
2256
 
2257
Since C and C++ are so closely related, many features of GDB apply to
2258
both languages.  Whenever this is the case, we discuss those languages
2259
together.
2260
 
2261
   The C++ debugging facilities are jointly implemented by the C++
2262
compiler and GDB.  Therefore, to debug your C++ code effectively, you
2263
must compile your C++ programs with a supported C++ compiler, such as
2264
GNU `g++', or the HP ANSI C++ compiler (`aCC').
2265
 
2266
   For best results when using GNU C++, use the DWARF 2 debugging
2267
format; if it doesn't work on your system, try the stabs+ debugging
2268
format.  You can select those formats explicitly with the `g++'
2269
command-line options `-gdwarf-2' and `-gstabs+'.  *Note Options for
2270
Debugging Your Program or GCC: (gcc.info)Debugging Options.
2271
 
2272
* Menu:
2273
 
2274
* C Operators::                 C and C++ operators
2275
* C Constants::                 C and C++ constants
2276
* C Plus Plus Expressions::     C++ expressions
2277
* C Defaults::                  Default settings for C and C++
2278
* C Checks::                    C and C++ type and range checks
2279
* Debugging C::                 GDB and C
2280
* Debugging C Plus Plus::       GDB features for C++
2281
* Decimal Floating Point::      Numbers in Decimal Floating Point format
2282
 
2283

2284
File: gdb.info,  Node: C Operators,  Next: C Constants,  Up: C
2285
 
2286
15.4.1.1 C and C++ Operators
2287
............................
2288
 
2289
Operators must be defined on values of specific types.  For instance,
2290
`+' is defined on numbers, but not on structures.  Operators are often
2291
defined on groups of types.
2292
 
2293
   For the purposes of C and C++, the following definitions hold:
2294
 
2295
   * _Integral types_ include `int' with any of its storage-class
2296
     specifiers; `char'; `enum'; and, for C++, `bool'.
2297
 
2298
   * _Floating-point types_ include `float', `double', and `long
2299
     double' (if supported by the target platform).
2300
 
2301
   * _Pointer types_ include all types defined as `(TYPE *)'.
2302
 
2303
   * _Scalar types_ include all of the above.
2304
 
2305
 
2306
The following operators are supported.  They are listed here in order
2307
of increasing precedence:
2308
 
2309
`,'
2310
     The comma or sequencing operator.  Expressions in a
2311
     comma-separated list are evaluated from left to right, with the
2312
     result of the entire expression being the last expression
2313
     evaluated.
2314
 
2315
`='
2316
     Assignment.  The value of an assignment expression is the value
2317
     assigned.  Defined on scalar types.
2318
 
2319
`OP='
2320
     Used in an expression of the form `A OP= B', and translated to
2321
     `A = A OP B'.  `OP=' and `=' have the same precedence.  OP is any
2322
     one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*',
2323
     `/', `%'.
2324
 
2325
`?:'
2326
     The ternary operator.  `A ? B : C' can be thought of as:  if A
2327
     then B else C.  A should be of an integral type.
2328
 
2329
`||'
2330
     Logical OR.  Defined on integral types.
2331
 
2332
`&&'
2333
     Logical AND.  Defined on integral types.
2334
 
2335
`|'
2336
     Bitwise OR.  Defined on integral types.
2337
 
2338
`^'
2339
     Bitwise exclusive-OR.  Defined on integral types.
2340
 
2341
`&'
2342
     Bitwise AND.  Defined on integral types.
2343
 
2344
`==, !='
2345
     Equality and inequality.  Defined on scalar types.  The value of
2346
     these expressions is 0 for false and non-zero for true.
2347
 
2348
`<, >, <=, >='
2349
     Less than, greater than, less than or equal, greater than or equal.
2350
     Defined on scalar types.  The value of these expressions is 0 for
2351
     false and non-zero for true.
2352
 
2353
`<<, >>'
2354
     left shift, and right shift.  Defined on integral types.
2355
 
2356
`@'
2357
     The GDB "artificial array" operator (*note Expressions:
2358
     Expressions.).
2359
 
2360
`+, -'
2361
     Addition and subtraction.  Defined on integral types,
2362
     floating-point types and pointer types.
2363
 
2364
`*, /, %'
2365
     Multiplication, division, and modulus.  Multiplication and
2366
     division are defined on integral and floating-point types.
2367
     Modulus is defined on integral types.
2368
 
2369
`++, --'
2370
     Increment and decrement.  When appearing before a variable, the
2371
     operation is performed before the variable is used in an
2372
     expression; when appearing after it, the variable's value is used
2373
     before the operation takes place.
2374
 
2375
`*'
2376
     Pointer dereferencing.  Defined on pointer types.  Same precedence
2377
     as `++'.
2378
 
2379
`&'
2380
     Address operator.  Defined on variables.  Same precedence as `++'.
2381
 
2382
     For debugging C++, GDB implements a use of `&' beyond what is
2383
     allowed in the C++ language itself: you can use `&(&REF)' to
2384
     examine the address where a C++ reference variable (declared with
2385
     `&REF') is stored.
2386
 
2387
`-'
2388
     Negative.  Defined on integral and floating-point types.  Same
2389
     precedence as `++'.
2390
 
2391
`!'
2392
     Logical negation.  Defined on integral types.  Same precedence as
2393
     `++'.
2394
 
2395
`~'
2396
     Bitwise complement operator.  Defined on integral types.  Same
2397
     precedence as `++'.
2398
 
2399
`., ->'
2400
     Structure member, and pointer-to-structure member.  For
2401
     convenience, GDB regards the two as equivalent, choosing whether
2402
     to dereference a pointer based on the stored type information.
2403
     Defined on `struct' and `union' data.
2404
 
2405
`.*, ->*'
2406
     Dereferences of pointers to members.
2407
 
2408
`[]'
2409
     Array indexing.  `A[I]' is defined as `*(A+I)'.  Same precedence
2410
     as `->'.
2411
 
2412
`()'
2413
     Function parameter list.  Same precedence as `->'.
2414
 
2415
`::'
2416
     C++ scope resolution operator.  Defined on `struct', `union', and
2417
     `class' types.
2418
 
2419
`::'
2420
     Doubled colons also represent the GDB scope operator (*note
2421
     Expressions: Expressions.).  Same precedence as `::', above.
2422
 
2423
   If an operator is redefined in the user code, GDB usually attempts
2424
to invoke the redefined version instead of using the operator's
2425
predefined meaning.
2426
 
2427

2428
File: gdb.info,  Node: C Constants,  Next: C Plus Plus Expressions,  Prev: C Operators,  Up: C
2429
 
2430
15.4.1.2 C and C++ Constants
2431
............................
2432
 
2433
GDB allows you to express the constants of C and C++ in the following
2434
ways:
2435
 
2436
   * Integer constants are a sequence of digits.  Octal constants are
2437
     specified by a leading `0' (i.e. zero), and hexadecimal constants
2438
     by a leading `0x' or `0X'.  Constants may also end with a letter
2439
     `l', specifying that the constant should be treated as a `long'
2440
     value.
2441
 
2442
   * Floating point constants are a sequence of digits, followed by a
2443
     decimal point, followed by a sequence of digits, and optionally
2444
     followed by an exponent.  An exponent is of the form:
2445
     `e[[+]|-]NNN', where NNN is another sequence of digits.  The `+'
2446
     is optional for positive exponents.  A floating-point constant may
2447
     also end with a letter `f' or `F', specifying that the constant
2448
     should be treated as being of the `float' (as opposed to the
2449
     default `double') type; or with a letter `l' or `L', which
2450
     specifies a `long double' constant.
2451
 
2452
   * Enumerated constants consist of enumerated identifiers, or their
2453
     integral equivalents.
2454
 
2455
   * Character constants are a single character surrounded by single
2456
     quotes (`''), or a number--the ordinal value of the corresponding
2457
     character (usually its ASCII value).  Within quotes, the single
2458
     character may be represented by a letter or by "escape sequences",
2459
     which are of the form `\NNN', where NNN is the octal representation
2460
     of the character's ordinal value; or of the form `\X', where `X'
2461
     is a predefined special character--for example, `\n' for newline.
2462
 
2463
   * String constants are a sequence of character constants surrounded
2464
     by double quotes (`"').  Any valid character constant (as described
2465
     above) may appear.  Double quotes within the string must be
2466
     preceded by a backslash, so for instance `"a\"b'c"' is a string of
2467
     five characters.
2468
 
2469
   * Pointer constants are an integral value.  You can also write
2470
     pointers to constants using the C operator `&'.
2471
 
2472
   * Array constants are comma-separated lists surrounded by braces `{'
2473
     and `}'; for example, `{1,2,3}' is a three-element array of
2474
     integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and
2475
     `{&"hi", &"there", &"fred"}' is a three-element array of pointers.
2476
 
2477

2478
File: gdb.info,  Node: C Plus Plus Expressions,  Next: C Defaults,  Prev: C Constants,  Up: C
2479
 
2480
15.4.1.3 C++ Expressions
2481
........................
2482
 
2483
GDB expression handling can interpret most C++ expressions.
2484
 
2485
     _Warning:_ GDB can only debug C++ code if you use the proper
2486
     compiler and the proper debug format.  Currently, GDB works best
2487
     when debugging C++ code that is compiled with GCC 2.95.3 or with
2488
     GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'.
2489
     DWARF 2 is preferred over stabs+.  Most configurations of GCC emit
2490
     either DWARF 2 or stabs+ as their default debug format, so you
2491
     usually don't need to specify a debug format explicitly.  Other
2492
     compilers and/or debug formats are likely to work badly or not at
2493
     all when using GDB to debug C++ code.
2494
 
2495
  1. Member function calls are allowed; you can use expressions like
2496
 
2497
          count = aml->GetOriginal(x, y)
2498
 
2499
  2. While a member function is active (in the selected stack frame),
2500
     your expressions have the same namespace available as the member
2501
     function; that is, GDB allows implicit references to the class
2502
     instance pointer `this' following the same rules as C++.
2503
 
2504
  3. You can call overloaded functions; GDB resolves the function call
2505
     to the right definition, with some restrictions.  GDB does not
2506
     perform overload resolution involving user-defined type
2507
     conversions, calls to constructors, or instantiations of templates
2508
     that do not exist in the program.  It also cannot handle ellipsis
2509
     argument lists or default arguments.
2510
 
2511
     It does perform integral conversions and promotions, floating-point
2512
     promotions, arithmetic conversions, pointer conversions,
2513
     conversions of class objects to base classes, and standard
2514
     conversions such as those of functions or arrays to pointers; it
2515
     requires an exact match on the number of function arguments.
2516
 
2517
     Overload resolution is always performed, unless you have specified
2518
     `set overload-resolution off'.  *Note GDB Features for C++:
2519
     Debugging C Plus Plus.
2520
 
2521
     You must specify `set overload-resolution off' in order to use an
2522
     explicit function signature to call an overloaded function, as in
2523
          p 'foo(char,int)'('x', 13)
2524
 
2525
     The GDB command-completion facility can simplify this; see *Note
2526
     Command Completion: Completion.
2527
 
2528
  4. GDB understands variables declared as C++ references; you can use
2529
     them in expressions just as you do in C++ source--they are
2530
     automatically dereferenced.
2531
 
2532
     In the parameter list shown when GDB displays a frame, the values
2533
     of reference variables are not displayed (unlike other variables);
2534
     this avoids clutter, since references are often used for large
2535
     structures.  The _address_ of a reference variable is always
2536
     shown, unless you have specified `set print address off'.
2537
 
2538
  5. GDB supports the C++ name resolution operator `::'--your
2539
     expressions can use it just as expressions in your program do.
2540
     Since one scope may be defined in another, you can use `::'
2541
     repeatedly if necessary, for example in an expression like
2542
     `SCOPE1::SCOPE2::NAME'.  GDB also allows resolving name scope by
2543
     reference to source files, in both C and C++ debugging (*note
2544
     Program Variables: Variables.).
2545
 
2546
   In addition, when used with HP's C++ compiler, GDB supports calling
2547
virtual functions correctly, printing out virtual bases of objects,
2548
calling functions in a base subobject, casting objects, and invoking
2549
user-defined operators.
2550
 
2551

2552
File: gdb.info,  Node: C Defaults,  Next: C Checks,  Prev: C Plus Plus Expressions,  Up: C
2553
 
2554
15.4.1.4 C and C++ Defaults
2555
...........................
2556
 
2557
If you allow GDB to set type and range checking automatically, they
2558
both default to `off' whenever the working language changes to C or
2559
C++.  This happens regardless of whether you or GDB selects the working
2560
language.
2561
 
2562
   If you allow GDB to set the language automatically, it recognizes
2563
source files whose names end with `.c', `.C', or `.cc', etc, and when
2564
GDB enters code compiled from one of these files, it sets the working
2565
language to C or C++.  *Note Having GDB Infer the Source Language:
2566
Automatically, for further details.
2567
 
2568

2569
File: gdb.info,  Node: C Checks,  Next: Debugging C,  Prev: C Defaults,  Up: C
2570
 
2571
15.4.1.5 C and C++ Type and Range Checks
2572
........................................
2573
 
2574
By default, when GDB parses C or C++ expressions, type checking is not
2575
used.  However, if you turn type checking on, GDB considers two
2576
variables type equivalent if:
2577
 
2578
   * The two variables are structured and have the same structure,
2579
     union, or enumerated tag.
2580
 
2581
   * The two variables have the same type name, or types that have been
2582
     declared equivalent through `typedef'.
2583
 
2584
 
2585
   Range checking, if turned on, is done on mathematical operations.
2586
Array indices are not checked, since they are often used to index a
2587
pointer that is not itself an array.
2588
 
2589

2590
File: gdb.info,  Node: Debugging C,  Next: Debugging C Plus Plus,  Prev: C Checks,  Up: C
2591
 
2592
15.4.1.6 GDB and C
2593
..................
2594
 
2595
The `set print union' and `show print union' commands apply to the
2596
`union' type.  When set to `on', any `union' that is inside a `struct'
2597
or `class' is also printed.  Otherwise, it appears as `{...}'.
2598
 
2599
   The `@' operator aids in the debugging of dynamic arrays, formed
2600
with pointers and a memory allocation function.  *Note Expressions:
2601
Expressions.
2602
 
2603

2604
File: gdb.info,  Node: Debugging C Plus Plus,  Next: Decimal Floating Point,  Prev: Debugging C,  Up: C
2605
 
2606
15.4.1.7 GDB Features for C++
2607
.............................
2608
 
2609
Some GDB commands are particularly useful with C++, and some are
2610
designed specifically for use with C++.  Here is a summary:
2611
 
2612
`breakpoint menus'
2613
     When you want a breakpoint in a function whose name is overloaded,
2614
     GDB has the capability to display a menu of possible breakpoint
2615
     locations to help you specify which function definition you want.
2616
     *Note Ambiguous Expressions: Ambiguous Expressions.
2617
 
2618
`rbreak REGEX'
2619
     Setting breakpoints using regular expressions is helpful for
2620
     setting breakpoints on overloaded functions that are not members
2621
     of any special classes.  *Note Setting Breakpoints: Set Breaks.
2622
 
2623
`catch throw'
2624
`catch catch'
2625
     Debug C++ exception handling using these commands.  *Note Setting
2626
     Catchpoints: Set Catchpoints.
2627
 
2628
`ptype TYPENAME'
2629
     Print inheritance relationships as well as other information for
2630
     type TYPENAME.  *Note Examining the Symbol Table: Symbols.
2631
 
2632
`set print demangle'
2633
`show print demangle'
2634
`set print asm-demangle'
2635
`show print asm-demangle'
2636
     Control whether C++ symbols display in their source form, both when
2637
     displaying code as C++ source and when displaying disassemblies.
2638
     *Note Print Settings: Print Settings.
2639
 
2640
`set print object'
2641
`show print object'
2642
     Choose whether to print derived (actual) or declared types of
2643
     objects.  *Note Print Settings: Print Settings.
2644
 
2645
`set print vtbl'
2646
`show print vtbl'
2647
     Control the format for printing virtual function tables.  *Note
2648
     Print Settings: Print Settings.  (The `vtbl' commands do not work
2649
     on programs compiled with the HP ANSI C++ compiler (`aCC').)
2650
 
2651
`set overload-resolution on'
2652
     Enable overload resolution for C++ expression evaluation.  The
2653
     default is on.  For overloaded functions, GDB evaluates the
2654
     arguments and searches for a function whose signature matches the
2655
     argument types, using the standard C++ conversion rules (see *Note
2656
     C++ Expressions: C Plus Plus Expressions, for details).  If it
2657
     cannot find a match, it emits a message.
2658
 
2659
`set overload-resolution off'
2660
     Disable overload resolution for C++ expression evaluation.  For
2661
     overloaded functions that are not class member functions, GDB
2662
     chooses the first function of the specified name that it finds in
2663
     the symbol table, whether or not its arguments are of the correct
2664
     type.  For overloaded functions that are class member functions,
2665
     GDB searches for a function whose signature _exactly_ matches the
2666
     argument types.
2667
 
2668
`show overload-resolution'
2669
     Show the current setting of overload resolution.
2670
 
2671
`Overloaded symbol names'
2672
     You can specify a particular definition of an overloaded symbol,
2673
     using the same notation that is used to declare such symbols in
2674
     C++: type `SYMBOL(TYPES)' rather than just SYMBOL.  You can also
2675
     use the GDB command-line word completion facilities to list the
2676
     available choices, or to finish the type list for you.  *Note
2677
     Command Completion: Completion, for details on how to do this.
2678
 
2679

2680
File: gdb.info,  Node: Decimal Floating Point,  Prev: Debugging C Plus Plus,  Up: C
2681
 
2682
15.4.1.8 Decimal Floating Point format
2683
......................................
2684
 
2685
GDB can examine, set and perform computations with numbers in decimal
2686
floating point format, which in the C language correspond to the
2687
`_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the
2688
extension to support decimal floating-point arithmetic.
2689
 
2690
   There are two encodings in use, depending on the architecture: BID
2691
(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed
2692
Decimal) for PowerPC.  GDB will use the appropriate encoding for the
2693
configured target.
2694
 
2695
   Because of a limitation in `libdecnumber', the library used by GDB
2696
to manipulate decimal floating point numbers, it is not possible to
2697
convert (using a cast, for example) integers wider than 32-bit to
2698
decimal float.
2699
 
2700
   In addition, in order to imitate GDB's behaviour with binary floating
2701
point computations, error checking in decimal float operations ignores
2702
underflow, overflow and divide by zero exceptions.
2703
 
2704
   In the PowerPC architecture, GDB provides a set of pseudo-registers
2705
to inspect `_Decimal128' values stored in floating point registers.
2706
See *Note PowerPC: PowerPC. for more details.
2707
 
2708

2709
File: gdb.info,  Node: Objective-C,  Next: Fortran,  Prev: C,  Up: Supported Languages
2710
 
2711
15.4.2 Objective-C
2712
------------------
2713
 
2714
This section provides information about some commands and command
2715
options that are useful for debugging Objective-C code.  See also *Note
2716
info classes: Symbols, and *Note info selectors: Symbols, for a few
2717
more commands specific to Objective-C support.
2718
 
2719
* Menu:
2720
 
2721
* Method Names in Commands::
2722
* The Print Command with Objective-C::
2723
 
2724

2725
File: gdb.info,  Node: Method Names in Commands,  Next: The Print Command with Objective-C,  Up: Objective-C
2726
 
2727
15.4.2.1 Method Names in Commands
2728
.................................
2729
 
2730
The following commands have been extended to accept Objective-C method
2731
names as line specifications:
2732
 
2733
   * `clear'
2734
 
2735
   * `break'
2736
 
2737
   * `info line'
2738
 
2739
   * `jump'
2740
 
2741
   * `list'
2742
 
2743
   A fully qualified Objective-C method name is specified as
2744
 
2745
     -[CLASS METHODNAME]
2746
 
2747
   where the minus sign is used to indicate an instance method and a
2748
plus sign (not shown) is used to indicate a class method.  The class
2749
name CLASS and method name METHODNAME are enclosed in brackets, similar
2750
to the way messages are specified in Objective-C source code.  For
2751
example, to set a breakpoint at the `create' instance method of class
2752
`Fruit' in the program currently being debugged, enter:
2753
 
2754
     break -[Fruit create]
2755
 
2756
   To list ten program lines around the `initialize' class method,
2757
enter:
2758
 
2759
     list +[NSText initialize]
2760
 
2761
   In the current version of GDB, the plus or minus sign is required.
2762
In future versions of GDB, the plus or minus sign will be optional, but
2763
you can use it to narrow the search.  It is also possible to specify
2764
just a method name:
2765
 
2766
     break create
2767
 
2768
   You must specify the complete method name, including any colons.  If
2769
your program's source files contain more than one `create' method,
2770
you'll be presented with a numbered list of classes that implement that
2771
method.  Indicate your choice by number, or type `0' to exit if none
2772
apply.
2773
 
2774
   As another example, to clear a breakpoint established at the
2775
`makeKeyAndOrderFront:' method of the `NSWindow' class, enter:
2776
 
2777
     clear -[NSWindow makeKeyAndOrderFront:]
2778
 
2779

2780
File: gdb.info,  Node: The Print Command with Objective-C,  Prev: Method Names in Commands,  Up: Objective-C
2781
 
2782
15.4.2.2 The Print Command With Objective-C
2783
...........................................
2784
 
2785
The print command has also been extended to accept methods.  For
2786
example:
2787
 
2788
     print -[OBJECT hash]
2789
 
2790
will tell GDB to send the `hash' message to OBJECT and print the
2791
result.  Also, an additional command has been added, `print-object' or
2792
`po' for short, which is meant to print the description of an object.
2793
However, this command may only work with certain Objective-C libraries
2794
that have a particular hook function, `_NSPrintForDebugger', defined.
2795
 
2796

2797
File: gdb.info,  Node: Fortran,  Next: Pascal,  Prev: Objective-C,  Up: Supported Languages
2798
 
2799
15.4.3 Fortran
2800
--------------
2801
 
2802
GDB can be used to debug programs written in Fortran, but it currently
2803
supports only the features of Fortran 77 language.
2804
 
2805
   Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers
2806
among them) append an underscore to the names of variables and
2807
functions.  When you debug programs compiled by those compilers, you
2808
will need to refer to variables and functions with a trailing
2809
underscore.
2810
 
2811
* Menu:
2812
 
2813
* Fortran Operators::           Fortran operators and expressions
2814
* Fortran Defaults::            Default settings for Fortran
2815
* Special Fortran Commands::    Special GDB commands for Fortran
2816
 
2817

2818
File: gdb.info,  Node: Fortran Operators,  Next: Fortran Defaults,  Up: Fortran
2819
 
2820
15.4.3.1 Fortran Operators and Expressions
2821
..........................................
2822
 
2823
Operators must be defined on values of specific types.  For instance,
2824
`+' is defined on numbers, but not on characters or other non-
2825
arithmetic types.  Operators are often defined on groups of types.
2826
 
2827
`**'
2828
     The exponentiation operator.  It raises the first operand to the
2829
     power of the second one.
2830
 
2831
`:'
2832
     The range operator.  Normally used in the form of array(low:high)
2833
     to represent a section of array.
2834
 
2835
`%'
2836
     The access component operator.  Normally used to access elements
2837
     in derived types.  Also suitable for unions.  As unions aren't
2838
     part of regular Fortran, this can only happen when accessing a
2839
     register that uses a gdbarch-defined union type.
2840
 
2841

2842
File: gdb.info,  Node: Fortran Defaults,  Next: Special Fortran Commands,  Prev: Fortran Operators,  Up: Fortran
2843
 
2844
15.4.3.2 Fortran Defaults
2845
.........................
2846
 
2847
Fortran symbols are usually case-insensitive, so GDB by default uses
2848
case-insensitive matches for Fortran symbols.  You can change that with
2849
the `set case-insensitive' command, see *Note Symbols::, for the
2850
details.
2851
 
2852

2853
File: gdb.info,  Node: Special Fortran Commands,  Prev: Fortran Defaults,  Up: Fortran
2854
 
2855
15.4.3.3 Special Fortran Commands
2856
.................................
2857
 
2858
GDB has some commands to support Fortran-specific features, such as
2859
displaying common blocks.
2860
 
2861
`info common [COMMON-NAME]'
2862
     This command prints the values contained in the Fortran `COMMON'
2863
     block whose name is COMMON-NAME.  With no argument, the names of
2864
     all `COMMON' blocks visible at the current program location are
2865
     printed.
2866
 
2867

2868
File: gdb.info,  Node: Pascal,  Next: Modula-2,  Prev: Fortran,  Up: Supported Languages
2869
 
2870
15.4.4 Pascal
2871
-------------
2872
 
2873
Debugging Pascal programs which use sets, subranges, file variables, or
2874
nested functions does not currently work.  GDB does not support
2875
entering expressions, printing values, or similar features using Pascal
2876
syntax.
2877
 
2878
   The Pascal-specific command `set print pascal_static-members'
2879
controls whether static members of Pascal objects are displayed.  *Note
2880
pascal_static-members: Print Settings.
2881
 
2882

2883
File: gdb.info,  Node: Modula-2,  Next: Ada,  Prev: Pascal,  Up: Supported Languages
2884
 
2885
15.4.5 Modula-2
2886
---------------
2887
 
2888
The extensions made to GDB to support Modula-2 only support output from
2889
the GNU Modula-2 compiler (which is currently being developed).  Other
2890
Modula-2 compilers are not currently supported, and attempting to debug
2891
executables produced by them is most likely to give an error as GDB
2892
reads in the executable's symbol table.
2893
 
2894
* Menu:
2895
 
2896
* M2 Operators::                Built-in operators
2897
* Built-In Func/Proc::          Built-in functions and procedures
2898
* M2 Constants::                Modula-2 constants
2899
* M2 Types::                    Modula-2 types
2900
* M2 Defaults::                 Default settings for Modula-2
2901
* Deviations::                  Deviations from standard Modula-2
2902
* M2 Checks::                   Modula-2 type and range checks
2903
* M2 Scope::                    The scope operators `::' and `.'
2904
* GDB/M2::                      GDB and Modula-2
2905
 
2906

2907
File: gdb.info,  Node: M2 Operators,  Next: Built-In Func/Proc,  Up: Modula-2
2908
 
2909
15.4.5.1 Operators
2910
..................
2911
 
2912
Operators must be defined on values of specific types.  For instance,
2913
`+' is defined on numbers, but not on structures.  Operators are often
2914
defined on groups of types.  For the purposes of Modula-2, the
2915
following definitions hold:
2916
 
2917
   * _Integral types_ consist of `INTEGER', `CARDINAL', and their
2918
     subranges.
2919
 
2920
   * _Character types_ consist of `CHAR' and its subranges.
2921
 
2922
   * _Floating-point types_ consist of `REAL'.
2923
 
2924
   * _Pointer types_ consist of anything declared as `POINTER TO TYPE'.
2925
 
2926
   * _Scalar types_ consist of all of the above.
2927
 
2928
   * _Set types_ consist of `SET' and `BITSET' types.
2929
 
2930
   * _Boolean types_ consist of `BOOLEAN'.
2931
 
2932
The following operators are supported, and appear in order of
2933
increasing precedence:
2934
 
2935
`,'
2936
     Function argument or array index separator.
2937
 
2938
`:='
2939
     Assignment.  The value of VAR `:=' VALUE is VALUE.
2940
 
2941
`<, >'
2942
     Less than, greater than on integral, floating-point, or enumerated
2943
     types.
2944
 
2945
`<=, >='
2946
     Less than or equal to, greater than or equal to on integral,
2947
     floating-point and enumerated types, or set inclusion on set
2948
     types.  Same precedence as `<'.
2949
 
2950
`=, <>, #'
2951
     Equality and two ways of expressing inequality, valid on scalar
2952
     types.  Same precedence as `<'.  In GDB scripts, only `<>' is
2953
     available for inequality, since `#' conflicts with the script
2954
     comment character.
2955
 
2956
`IN'
2957
     Set membership.  Defined on set types and the types of their
2958
     members.  Same precedence as `<'.
2959
 
2960
`OR'
2961
     Boolean disjunction.  Defined on boolean types.
2962
 
2963
`AND, &'
2964
     Boolean conjunction.  Defined on boolean types.
2965
 
2966
`@'
2967
     The GDB "artificial array" operator (*note Expressions:
2968
     Expressions.).
2969
 
2970
`+, -'
2971
     Addition and subtraction on integral and floating-point types, or
2972
     union and difference on set types.
2973
 
2974
`*'
2975
     Multiplication on integral and floating-point types, or set
2976
     intersection on set types.
2977
 
2978
`/'
2979
     Division on floating-point types, or symmetric set difference on
2980
     set types.  Same precedence as `*'.
2981
 
2982
`DIV, MOD'
2983
     Integer division and remainder.  Defined on integral types.  Same
2984
     precedence as `*'.
2985
 
2986
`-'
2987
     Negative.  Defined on `INTEGER' and `REAL' data.
2988
 
2989
`^'
2990
     Pointer dereferencing.  Defined on pointer types.
2991
 
2992
`NOT'
2993
     Boolean negation.  Defined on boolean types.  Same precedence as
2994
     `^'.
2995
 
2996
`.'
2997
     `RECORD' field selector.  Defined on `RECORD' data.  Same
2998
     precedence as `^'.
2999
 
3000
`[]'
3001
     Array indexing.  Defined on `ARRAY' data.  Same precedence as `^'.
3002
 
3003
`()'
3004
     Procedure argument list.  Defined on `PROCEDURE' objects.  Same
3005
     precedence as `^'.
3006
 
3007
`::, .'
3008
     GDB and Modula-2 scope operators.
3009
 
3010
     _Warning:_ Set expressions and their operations are not yet
3011
     supported, so GDB treats the use of the operator `IN', or the use
3012
     of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>='
3013
     on sets as an error.
3014
 
3015

3016
File: gdb.info,  Node: Built-In Func/Proc,  Next: M2 Constants,  Prev: M2 Operators,  Up: Modula-2
3017
 
3018
15.4.5.2 Built-in Functions and Procedures
3019
..........................................
3020
 
3021
Modula-2 also makes available several built-in procedures and functions.
3022
In describing these, the following metavariables are used:
3023
 
3024
A
3025
     represents an `ARRAY' variable.
3026
 
3027
C
3028
     represents a `CHAR' constant or variable.
3029
 
3030
I
3031
     represents a variable or constant of integral type.
3032
 
3033
M
3034
     represents an identifier that belongs to a set.  Generally used in
3035
     the same function with the metavariable S.  The type of S should
3036
     be `SET OF MTYPE' (where MTYPE is the type of M).
3037
 
3038
N
3039
     represents a variable or constant of integral or floating-point
3040
     type.
3041
 
3042
R
3043
     represents a variable or constant of floating-point type.
3044
 
3045
T
3046
     represents a type.
3047
 
3048
V
3049
     represents a variable.
3050
 
3051
X
3052
     represents a variable or constant of one of many types.  See the
3053
     explanation of the function for details.
3054
 
3055
   All Modula-2 built-in procedures also return a result, described
3056
below.
3057
 
3058
`ABS(N)'
3059
     Returns the absolute value of N.
3060
 
3061
`CAP(C)'
3062
     If C is a lower case letter, it returns its upper case equivalent,
3063
     otherwise it returns its argument.
3064
 
3065
`CHR(I)'
3066
     Returns the character whose ordinal value is I.
3067
 
3068
`DEC(V)'
3069
     Decrements the value in the variable V by one.  Returns the new
3070
     value.
3071
 
3072
`DEC(V,I)'
3073
     Decrements the value in the variable V by I.  Returns the new
3074
     value.
3075
 
3076
`EXCL(M,S)'
3077
     Removes the element M from the set S.  Returns the new set.
3078
 
3079
`FLOAT(I)'
3080
     Returns the floating point equivalent of the integer I.
3081
 
3082
`HIGH(A)'
3083
     Returns the index of the last member of A.
3084
 
3085
`INC(V)'
3086
     Increments the value in the variable V by one.  Returns the new
3087
     value.
3088
 
3089
`INC(V,I)'
3090
     Increments the value in the variable V by I.  Returns the new
3091
     value.
3092
 
3093
`INCL(M,S)'
3094
     Adds the element M to the set S if it is not already there.
3095
     Returns the new set.
3096
 
3097
`MAX(T)'
3098
     Returns the maximum value of the type T.
3099
 
3100
`MIN(T)'
3101
     Returns the minimum value of the type T.
3102
 
3103
`ODD(I)'
3104
     Returns boolean TRUE if I is an odd number.
3105
 
3106
`ORD(X)'
3107
     Returns the ordinal value of its argument.  For example, the
3108
     ordinal value of a character is its ASCII value (on machines
3109
     supporting the ASCII character set).  X must be of an ordered
3110
     type, which include integral, character and enumerated types.
3111
 
3112
`SIZE(X)'
3113
     Returns the size of its argument.  X can be a variable or a type.
3114
 
3115
`TRUNC(R)'
3116
     Returns the integral part of R.
3117
 
3118
`TSIZE(X)'
3119
     Returns the size of its argument.  X can be a variable or a type.
3120
 
3121
`VAL(T,I)'
3122
     Returns the member of the type T whose ordinal value is I.
3123
 
3124
     _Warning:_  Sets and their operations are not yet supported, so
3125
     GDB treats the use of procedures `INCL' and `EXCL' as an error.
3126
 
3127

3128
File: gdb.info,  Node: M2 Constants,  Next: M2 Types,  Prev: Built-In Func/Proc,  Up: Modula-2
3129
 
3130
15.4.5.3 Constants
3131
..................
3132
 
3133
GDB allows you to express the constants of Modula-2 in the following
3134
ways:
3135
 
3136
   * Integer constants are simply a sequence of digits.  When used in an
3137
     expression, a constant is interpreted to be type-compatible with
3138
     the rest of the expression.  Hexadecimal integers are specified by
3139
     a trailing `H', and octal integers by a trailing `B'.
3140
 
3141
   * Floating point constants appear as a sequence of digits, followed
3142
     by a decimal point and another sequence of digits.  An optional
3143
     exponent can then be specified, in the form `E[+|-]NNN', where
3144
     `[+|-]NNN' is the desired exponent.  All of the digits of the
3145
     floating point constant must be valid decimal (base 10) digits.
3146
 
3147
   * Character constants consist of a single character enclosed by a
3148
     pair of like quotes, either single (`'') or double (`"').  They may
3149
     also be expressed by their ordinal value (their ASCII value,
3150
     usually) followed by a `C'.
3151
 
3152
   * String constants consist of a sequence of characters enclosed by a
3153
     pair of like quotes, either single (`'') or double (`"').  Escape
3154
     sequences in the style of C are also allowed.  *Note C and C++
3155
     Constants: C Constants, for a brief explanation of escape
3156
     sequences.
3157
 
3158
   * Enumerated constants consist of an enumerated identifier.
3159
 
3160
   * Boolean constants consist of the identifiers `TRUE' and `FALSE'.
3161
 
3162
   * Pointer constants consist of integral values only.
3163
 
3164
   * Set constants are not yet supported.
3165
 
3166

3167
File: gdb.info,  Node: M2 Types,  Next: M2 Defaults,  Prev: M2 Constants,  Up: Modula-2
3168
 
3169
15.4.5.4 Modula-2 Types
3170
.......................
3171
 
3172
Currently GDB can print the following data types in Modula-2 syntax:
3173
array types, record types, set types, pointer types, procedure types,
3174
enumerated types, subrange types and base types.  You can also print
3175
the contents of variables declared using these type.  This section
3176
gives a number of simple source code examples together with sample GDB
3177
sessions.
3178
 
3179
   The first example contains the following section of code:
3180
 
3181
     VAR
3182
        s: SET OF CHAR ;
3183
        r: [20..40] ;
3184
 
3185
and you can request GDB to interrogate the type and value of `r' and
3186
`s'.
3187
 
3188
     (gdb) print s
3189
     {'A'..'C', 'Z'}
3190
     (gdb) ptype s
3191
     SET OF CHAR
3192
     (gdb) print r
3193
     21
3194
     (gdb) ptype r
3195
     [20..40]
3196
 
3197
Likewise if your source code declares `s' as:
3198
 
3199
     VAR
3200
        s: SET ['A'..'Z'] ;
3201
 
3202
then you may query the type of `s' by:
3203
 
3204
     (gdb) ptype s
3205
     type = SET ['A'..'Z']
3206
 
3207
Note that at present you cannot interactively manipulate set
3208
expressions using the debugger.
3209
 
3210
   The following example shows how you might declare an array in
3211
Modula-2 and how you can interact with GDB to print its type and
3212
contents:
3213
 
3214
     VAR
3215
        s: ARRAY [-10..10] OF CHAR ;
3216
 
3217
     (gdb) ptype s
3218
     ARRAY [-10..10] OF CHAR
3219
 
3220
   Note that the array handling is not yet complete and although the
3221
type is printed correctly, expression handling still assumes that all
3222
arrays have a lower bound of zero and not `-10' as in the example above.
3223
 
3224
   Here are some more type related Modula-2 examples:
3225
 
3226
     TYPE
3227
        colour = (blue, red, yellow, green) ;
3228
        t = [blue..yellow] ;
3229
     VAR
3230
        s: t ;
3231
     BEGIN
3232
        s := blue ;
3233
 
3234
The GDB interaction shows how you can query the data type and value of
3235
a variable.
3236
 
3237
     (gdb) print s
3238
     $1 = blue
3239
     (gdb) ptype t
3240
     type = [blue..yellow]
3241
 
3242
In this example a Modula-2 array is declared and its contents
3243
displayed.  Observe that the contents are written in the same way as
3244
their `C' counterparts.
3245
 
3246
     VAR
3247
        s: ARRAY [1..5] OF CARDINAL ;
3248
     BEGIN
3249
        s[1] := 1 ;
3250
 
3251
     (gdb) print s
3252
     $1 = {1, 0, 0, 0, 0}
3253
     (gdb) ptype s
3254
     type = ARRAY [1..5] OF CARDINAL
3255
 
3256
   The Modula-2 language interface to GDB also understands pointer
3257
types as shown in this example:
3258
 
3259
     VAR
3260
        s: POINTER TO ARRAY [1..5] OF CARDINAL ;
3261
     BEGIN
3262
        NEW(s) ;
3263
        s^[1] := 1 ;
3264
 
3265
and you can request that GDB describes the type of `s'.
3266
 
3267
     (gdb) ptype s
3268
     type = POINTER TO ARRAY [1..5] OF CARDINAL
3269
 
3270
   GDB handles compound types as we can see in this example.  Here we
3271
combine array types, record types, pointer types and subrange types:
3272
 
3273
     TYPE
3274
        foo = RECORD
3275
                 f1: CARDINAL ;
3276
                 f2: CHAR ;
3277
                 f3: myarray ;
3278
              END ;
3279
 
3280
        myarray = ARRAY myrange OF CARDINAL ;
3281
        myrange = [-2..2] ;
3282
     VAR
3283
        s: POINTER TO ARRAY myrange OF foo ;
3284
 
3285
and you can ask GDB to describe the type of `s' as shown below.
3286
 
3287
     (gdb) ptype s
3288
     type = POINTER TO ARRAY [-2..2] OF foo = RECORD
3289
         f1 : CARDINAL;
3290
         f2 : CHAR;
3291
         f3 : ARRAY [-2..2] OF CARDINAL;
3292
     END
3293
 
3294

3295
File: gdb.info,  Node: M2 Defaults,  Next: Deviations,  Prev: M2 Types,  Up: Modula-2
3296
 
3297
15.4.5.5 Modula-2 Defaults
3298
..........................
3299
 
3300
If type and range checking are set automatically by GDB, they both
3301
default to `on' whenever the working language changes to Modula-2.
3302
This happens regardless of whether you or GDB selected the working
3303
language.
3304
 
3305
   If you allow GDB to set the language automatically, then entering
3306
code compiled from a file whose name ends with `.mod' sets the working
3307
language to Modula-2.  *Note Having GDB Infer the Source Language:
3308
Automatically, for further details.
3309
 
3310

3311
File: gdb.info,  Node: Deviations,  Next: M2 Checks,  Prev: M2 Defaults,  Up: Modula-2
3312
 
3313
15.4.5.6 Deviations from Standard Modula-2
3314
..........................................
3315
 
3316
A few changes have been made to make Modula-2 programs easier to debug.
3317
This is done primarily via loosening its type strictness:
3318
 
3319
   * Unlike in standard Modula-2, pointer constants can be formed by
3320
     integers.  This allows you to modify pointer variables during
3321
     debugging.  (In standard Modula-2, the actual address contained in
3322
     a pointer variable is hidden from you; it can only be modified
3323
     through direct assignment to another pointer variable or
3324
     expression that returned a pointer.)
3325
 
3326
   * C escape sequences can be used in strings and characters to
3327
     represent non-printable characters.  GDB prints out strings with
3328
     these escape sequences embedded.  Single non-printable characters
3329
     are printed using the `CHR(NNN)' format.
3330
 
3331
   * The assignment operator (`:=') returns the value of its right-hand
3332
     argument.
3333
 
3334
   * All built-in procedures both modify _and_ return their argument.
3335
 
3336

3337
File: gdb.info,  Node: M2 Checks,  Next: M2 Scope,  Prev: Deviations,  Up: Modula-2
3338
 
3339
15.4.5.7 Modula-2 Type and Range Checks
3340
.......................................
3341
 
3342
     _Warning:_ in this release, GDB does not yet perform type or range
3343
     checking.
3344
 
3345
   GDB considers two Modula-2 variables type equivalent if:
3346
 
3347
   * They are of types that have been declared equivalent via a `TYPE
3348
     T1 = T2' statement
3349
 
3350
   * They have been declared on the same line.  (Note:  This is true of
3351
     the GNU Modula-2 compiler, but it may not be true of other
3352
     compilers.)
3353
 
3354
   As long as type checking is enabled, any attempt to combine variables
3355
whose types are not equivalent is an error.
3356
 
3357
   Range checking is done on all mathematical operations, assignment,
3358
array index bounds, and all built-in functions and procedures.
3359
 
3360

3361
File: gdb.info,  Node: M2 Scope,  Next: GDB/M2,  Prev: M2 Checks,  Up: Modula-2
3362
 
3363
15.4.5.8 The Scope Operators `::' and `.'
3364
.........................................
3365
 
3366
There are a few subtle differences between the Modula-2 scope operator
3367
(`.') and the GDB scope operator (`::').  The two have similar syntax:
3368
 
3369
 
3370
     MODULE . ID
3371
     SCOPE :: ID
3372
 
3373
where SCOPE is the name of a module or a procedure, MODULE the name of
3374
a module, and ID is any declared identifier within your program, except
3375
another module.
3376
 
3377
   Using the `::' operator makes GDB search the scope specified by
3378
SCOPE for the identifier ID.  If it is not found in the specified
3379
scope, then GDB searches all scopes enclosing the one specified by
3380
SCOPE.
3381
 
3382
   Using the `.' operator makes GDB search the current scope for the
3383
identifier specified by ID that was imported from the definition module
3384
specified by MODULE.  With this operator, it is an error if the
3385
identifier ID was not imported from definition module MODULE, or if ID
3386
is not an identifier in MODULE.
3387
 
3388

3389
File: gdb.info,  Node: GDB/M2,  Prev: M2 Scope,  Up: Modula-2
3390
 
3391
15.4.5.9 GDB and Modula-2
3392
.........................
3393
 
3394
Some GDB commands have little use when debugging Modula-2 programs.
3395
Five subcommands of `set print' and `show print' apply specifically to
3396
C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'.
3397
The first four apply to C++, and the last to the C `union' type, which
3398
has no direct analogue in Modula-2.
3399
 
3400
   The `@' operator (*note Expressions: Expressions.), while available
3401
with any language, is not useful with Modula-2.  Its intent is to aid
3402
the debugging of "dynamic arrays", which cannot be created in Modula-2
3403
as they can in C or C++.  However, because an address can be specified
3404
by an integral constant, the construct `{TYPE}ADREXP' is still useful.
3405
 
3406
   In GDB scripts, the Modula-2 inequality operator `#' is interpreted
3407
as the beginning of a comment.  Use `<>' instead.
3408
 
3409

3410
File: gdb.info,  Node: Ada,  Prev: Modula-2,  Up: Supported Languages
3411
 
3412
15.4.6 Ada
3413
----------
3414
 
3415
The extensions made to GDB for Ada only support output from the GNU Ada
3416
(GNAT) compiler.  Other Ada compilers are not currently supported, and
3417
attempting to debug executables produced by them is most likely to be
3418
difficult.
3419
 
3420
* Menu:
3421
 
3422
* Ada Mode Intro::              General remarks on the Ada syntax
3423
                                   and semantics supported by Ada mode
3424
                                   in GDB.
3425
* Omissions from Ada::          Restrictions on the Ada expression syntax.
3426
* Additions to Ada::            Extensions of the Ada expression syntax.
3427
* Stopping Before Main Program:: Debugging the program during elaboration.
3428
* Ada Tasks::                   Listing and setting breakpoints in tasks.
3429
* Ada Tasks and Core Files::    Tasking Support when Debugging Core Files
3430
* Ada Glitches::                Known peculiarities of Ada mode.
3431
 
3432

3433
File: gdb.info,  Node: Ada Mode Intro,  Next: Omissions from Ada,  Up: Ada
3434
 
3435
15.4.6.1 Introduction
3436
.....................
3437
 
3438
The Ada mode of GDB supports a fairly large subset of Ada expression
3439
syntax, with some extensions.  The philosophy behind the design of this
3440
subset is
3441
 
3442
   * That GDB should provide basic literals and access to operations for
3443
     arithmetic, dereferencing, field selection, indexing, and
3444
     subprogram calls, leaving more sophisticated computations to
3445
     subprograms written into the program (which therefore may be
3446
     called from GDB).
3447
 
3448
   * That type safety and strict adherence to Ada language restrictions
3449
     are not particularly important to the GDB user.
3450
 
3451
   * That brevity is important to the GDB user.
3452
 
3453
   Thus, for brevity, the debugger acts as if all names declared in
3454
user-written packages are directly visible, even if they are not visible
3455
according to Ada rules, thus making it unnecessary to fully qualify most
3456
names with their packages, regardless of context.  Where this causes
3457
ambiguity, GDB asks the user's intent.
3458
 
3459
   The debugger will start in Ada mode if it detects an Ada main
3460
program.  As for other languages, it will enter Ada mode when stopped
3461
in a program that was translated from an Ada source file.
3462
 
3463
   While in Ada mode, you may use `-' for comments.  This is useful
3464
mostly for documenting command files.  The standard GDB comment (`#')
3465
still works at the beginning of a line in Ada mode, but not in the
3466
middle (to allow based literals).
3467
 
3468
   The debugger supports limited overloading.  Given a subprogram call
3469
in which the function symbol has multiple definitions, it will use the
3470
number of actual parameters and some information about their types to
3471
attempt to narrow the set of definitions.  It also makes very limited
3472
use of context, preferring procedures to functions in the context of
3473
the `call' command, and functions to procedures elsewhere.
3474
 
3475

3476
File: gdb.info,  Node: Omissions from Ada,  Next: Additions to Ada,  Prev: Ada Mode Intro,  Up: Ada
3477
 
3478
15.4.6.2 Omissions from Ada
3479
...........................
3480
 
3481
Here are the notable omissions from the subset:
3482
 
3483
   * Only a subset of the attributes are supported:
3484
 
3485
        - 'First, 'Last, and 'Length  on array objects (not on types
3486
          and subtypes).
3487
 
3488
        - 'Min and 'Max.
3489
 
3490
        - 'Pos and 'Val.
3491
 
3492
        - 'Tag.
3493
 
3494
        - 'Range on array objects (not subtypes), but only as the right
3495
          operand of the membership (`in') operator.
3496
 
3497
        - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT
3498
          extension).
3499
 
3500
        - 'Address.
3501
 
3502
   * The names in `Characters.Latin_1' are not available and
3503
     concatenation is not implemented.  Thus, escape characters in
3504
     strings are not currently available.
3505
 
3506
   * Equality tests (`=' and `/=') on arrays test for bitwise equality
3507
     of representations.  They will generally work correctly for
3508
     strings and arrays whose elements have integer or enumeration
3509
     types.  They may not work correctly for arrays whose element types
3510
     have user-defined equality, for arrays of real values (in
3511
     particular, IEEE-conformant floating point, because of negative
3512
     zeroes and NaNs), and for arrays whose elements contain unused
3513
     bits with indeterminate values.
3514
 
3515
   * The other component-by-component array operations (`and', `or',
3516
     `xor', `not', and relational tests other than equality) are not
3517
     implemented.
3518
 
3519
   * There is limited support for array and record aggregates.  They are
3520
     permitted only on the right sides of assignments, as in these
3521
     examples:
3522
 
3523
          (gdb) set An_Array := (1, 2, 3, 4, 5, 6)
3524
          (gdb) set An_Array := (1, others => 0)
3525
          (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
3526
          (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
3527
          (gdb) set A_Record := (1, "Peter", True);
3528
          (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True)
3529
 
3530
     Changing a discriminant's value by assigning an aggregate has an
3531
     undefined effect if that discriminant is used within the record.
3532
     However, you can first modify discriminants by directly assigning
3533
     to them (which normally would not be allowed in Ada), and then
3534
     performing an aggregate assignment.  For example, given a variable
3535
     `A_Rec' declared to have a type such as:
3536
 
3537
          type Rec (Len : Small_Integer := 0) is record
3538
              Id : Integer;
3539
              Vals : IntArray (1 .. Len);
3540
          end record;
3541
 
3542
     you can assign a value with a different size of `Vals' with two
3543
     assignments:
3544
 
3545
          (gdb) set A_Rec.Len := 4
3546
          (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
3547
 
3548
     As this example also illustrates, GDB is very loose about the usual
3549
     rules concerning aggregates.  You may leave out some of the
3550
     components of an array or record aggregate (such as the `Len'
3551
     component in the assignment to `A_Rec' above); they will retain
3552
     their original values upon assignment.  You may freely use dynamic
3553
     values as indices in component associations.  You may even use
3554
     overlapping or redundant component associations, although which
3555
     component values are assigned in such cases is not defined.
3556
 
3557
   * Calls to dispatching subprograms are not implemented.
3558
 
3559
   * The overloading algorithm is much more limited (i.e., less
3560
     selective) than that of real Ada.  It makes only limited use of
3561
     the context in which a subexpression appears to resolve its
3562
     meaning, and it is much looser in its rules for allowing type
3563
     matches.  As a result, some function calls will be ambiguous, and
3564
     the user will be asked to choose the proper resolution.
3565
 
3566
   * The `new' operator is not implemented.
3567
 
3568
   * Entry calls are not implemented.
3569
 
3570
   * Aside from printing, arithmetic operations on the native VAX
3571
     floating-point formats are not supported.
3572
 
3573
   * It is not possible to slice a packed array.
3574
 
3575
   * The names `True' and `False', when not part of a qualified name,
3576
     are interpreted as if implicitly prefixed by `Standard',
3577
     regardless of context.  Should your program redefine these names
3578
     in a package or procedure (at best a dubious practice), you will
3579
     have to use fully qualified names to access their new definitions.
3580
 
3581

3582
File: gdb.info,  Node: Additions to Ada,  Next: Stopping Before Main Program,  Prev: Omissions from Ada,  Up: Ada
3583
 
3584
15.4.6.3 Additions to Ada
3585
.........................
3586
 
3587
As it does for other languages, GDB makes certain generic extensions to
3588
Ada (*note Expressions::):
3589
 
3590
   * If the expression E is a variable residing in memory (typically a
3591
     local variable or array element) and N is a positive integer, then
3592
     `E@N' displays the values of E and the N-1 adjacent variables
3593
     following it in memory as an array.  In Ada, this operator is
3594
     generally not necessary, since its prime use is in displaying
3595
     parts of an array, and slicing will usually do this in Ada.
3596
     However, there are occasional uses when debugging programs in
3597
     which certain debugging information has been optimized away.
3598
 
3599
   * `B::VAR' means "the variable named VAR that appears in function or
3600
     file B."  When B is a file name, you must typically surround it in
3601
     single quotes.
3602
 
3603
   * The expression `{TYPE} ADDR' means "the variable of type TYPE that
3604
     appears at address ADDR."
3605
 
3606
   * A name starting with `$' is a convenience variable (*note
3607
     Convenience Vars::) or a machine register (*note Registers::).
3608
 
3609
   In addition, GDB provides a few other shortcuts and outright
3610
additions specific to Ada:
3611
 
3612
   * The assignment statement is allowed as an expression, returning
3613
     its right-hand operand as its value.  Thus, you may enter
3614
 
3615
          (gdb) set x := y + 3
3616
          (gdb) print A(tmp := y + 1)
3617
 
3618
   * The semicolon is allowed as an "operator,"  returning as its value
3619
     the value of its right-hand operand.  This allows, for example,
3620
     complex conditional breaks:
3621
 
3622
          (gdb) break f
3623
          (gdb) condition 1 (report(i); k += 1; A(k) > 100)
3624
 
3625
   * Rather than use catenation and symbolic character names to
3626
     introduce special characters into strings, one may instead use a
3627
     special bracket notation, which is also used to print strings.  A
3628
     sequence of characters of the form `["XX"]' within a string or
3629
     character literal denotes the (single) character whose numeric
3630
     encoding is XX in hexadecimal.  The sequence of characters `["""]'
3631
     also denotes a single quotation mark in strings.   For example,
3632
             "One line.["0a"]Next line.["0a"]"
3633
     contains an ASCII newline character (`Ada.Characters.Latin_1.LF')
3634
     after each period.
3635
 
3636
   * The subtype used as a prefix for the attributes 'Pos, 'Min, and
3637
     'Max is optional (and is ignored in any case).  For example, it is
3638
     valid to write
3639
 
3640
          (gdb) print 'max(x, y)
3641
 
3642
   * When printing arrays, GDB uses positional notation when the array
3643
     has a lower bound of 1, and uses a modified named notation
3644
     otherwise.  For example, a one-dimensional array of three integers
3645
     with a lower bound of 3 might print as
3646
 
3647
          (3 => 10, 17, 1)
3648
 
3649
     That is, in contrast to valid Ada, only the first component has a
3650
     `=>' clause.
3651
 
3652
   * You may abbreviate attributes in expressions with any unique,
3653
     multi-character subsequence of their names (an exact match gets
3654
     preference).  For example, you may use a'len, a'gth, or a'lh in
3655
     place of  a'length.
3656
 
3657
   * Since Ada is case-insensitive, the debugger normally maps
3658
     identifiers you type to lower case.  The GNAT compiler uses
3659
     upper-case characters for some of its internal identifiers, which
3660
     are normally of no interest to users.  For the rare occasions when
3661
     you actually have to look at them, enclose them in angle brackets
3662
     to avoid the lower-case mapping.  For example,
3663
          (gdb) print [0]
3664
 
3665
   * Printing an object of class-wide type or dereferencing an
3666
     access-to-class-wide value will display all the components of the
3667
     object's specific type (as indicated by its run-time tag).
3668
     Likewise, component selection on such a value will operate on the
3669
     specific type of the object.
3670
 
3671
 
3672

3673
File: gdb.info,  Node: Stopping Before Main Program,  Next: Ada Tasks,  Prev: Additions to Ada,  Up: Ada
3674
 
3675
15.4.6.4 Stopping at the Very Beginning
3676
.......................................
3677
 
3678
It is sometimes necessary to debug the program during elaboration, and
3679
before reaching the main procedure.  As defined in the Ada Reference
3680
Manual, the elaboration code is invoked from a procedure called
3681
`adainit'.  To run your program up to the beginning of elaboration,
3682
simply use the following two commands: `tbreak adainit' and `run'.
3683
 
3684

3685
File: gdb.info,  Node: Ada Tasks,  Next: Ada Tasks and Core Files,  Prev: Stopping Before Main Program,  Up: Ada
3686
 
3687
15.4.6.5 Extensions for Ada Tasks
3688
.................................
3689
 
3690
Support for Ada tasks is analogous to that for threads (*note
3691
Threads::).  GDB provides the following task-related commands:
3692
 
3693
`info tasks'
3694
     This command shows a list of current Ada tasks, as in the
3695
     following example:
3696
 
3697
          (gdb) info tasks
3698
            ID       TID P-ID Pri State                 Name
3699
             1   8088000   0   15 Child Activation Wait main_task
3700
             2   80a4000   1   15 Accept Statement      b
3701
             3   809a800   1   15 Child Activation Wait a
3702
          *  4   80ae800   3   15 Runnable              c
3703
 
3704
     In this listing, the asterisk before the last task indicates it to
3705
     be the task currently being inspected.
3706
 
3707
    ID
3708
          Represents GDB's internal task number.
3709
 
3710
    TID
3711
          The Ada task ID.
3712
 
3713
    P-ID
3714
          The parent's task ID (GDB's internal task number).
3715
 
3716
    Pri
3717
          The base priority of the task.
3718
 
3719
    State
3720
          Current state of the task.
3721
 
3722
         `Unactivated'
3723
               The task has been created but has not been activated.
3724
               It cannot be executing.
3725
 
3726
         `Runnable'
3727
               The task is not blocked for any reason known to Ada.
3728
               (It may be waiting for a mutex, though.) It is
3729
               conceptually "executing" in normal mode.
3730
 
3731
         `Terminated'
3732
               The task is terminated, in the sense of ARM 9.3 (5).
3733
               Any dependents that were waiting on terminate
3734
               alternatives have been awakened and have terminated
3735
               themselves.
3736
 
3737
         `Child Activation Wait'
3738
               The task is waiting for created tasks to complete
3739
               activation.
3740
 
3741
         `Accept Statement'
3742
               The task is waiting on an accept or selective wait
3743
               statement.
3744
 
3745
         `Waiting on entry call'
3746
               The task is waiting on an entry call.
3747
 
3748
         `Async Select Wait'
3749
               The task is waiting to start the abortable part of an
3750
               asynchronous select statement.
3751
 
3752
         `Delay Sleep'
3753
               The task is waiting on a select statement with only a
3754
               delay alternative open.
3755
 
3756
         `Child Termination Wait'
3757
               The task is sleeping having completed a master within
3758
               itself, and is waiting for the tasks dependent on that
3759
               master to become terminated or waiting on a terminate
3760
               Phase.
3761
 
3762
         `Wait Child in Term Alt'
3763
               The task is sleeping waiting for tasks on terminate
3764
               alternatives to finish terminating.
3765
 
3766
         `Accepting RV with TASKNO'
3767
               The task is accepting a rendez-vous with the task TASKNO.
3768
 
3769
    Name
3770
          Name of the task in the program.
3771
 
3772
 
3773
`info task TASKNO'
3774
     This command shows detailled informations on the specified task,
3775
     as in the following example:
3776
          (gdb) info tasks
3777
            ID       TID P-ID Pri State                  Name
3778
             1   8077880    0  15 Child Activation Wait  main_task
3779
          *  2   807c468    1  15 Runnable               task_1
3780
          (gdb) info task 2
3781
          Ada Task: 0x807c468
3782
          Name: task_1
3783
          Thread: 0x807f378
3784
          Parent: 1 (main_task)
3785
          Base Priority: 15
3786
          State: Runnable
3787
 
3788
`task'
3789
     This command prints the ID of the current task.
3790
 
3791
          (gdb) info tasks
3792
            ID       TID P-ID Pri State                  Name
3793
             1   8077870    0  15 Child Activation Wait  main_task
3794
          *  2   807c458    1  15 Runnable               t
3795
          (gdb) task
3796
          [Current task is 2]
3797
 
3798
`task TASKNO'
3799
     This command is like the `thread THREADNO' command (*note
3800
     Threads::).  It switches the context of debugging from the current
3801
     task to the given task.
3802
 
3803
          (gdb) info tasks
3804
            ID       TID P-ID Pri State                  Name
3805
             1   8077870    0  15 Child Activation Wait  main_task
3806
          *  2   807c458    1  15 Runnable               t
3807
          (gdb) task 1
3808
          [Switching to task 1]
3809
          #0  0x8067726 in pthread_cond_wait ()
3810
          (gdb) bt
3811
          #0  0x8067726 in pthread_cond_wait ()
3812
          #1  0x8056714 in system.os_interface.pthread_cond_wait ()
3813
          #2  0x805cb63 in system.task_primitives.operations.sleep ()
3814
          #3  0x806153e in system.tasking.stages.activate_tasks ()
3815
          #4  0x804aacc in un () at un.adb:5
3816
 
3817
`break LINESPEC task TASKNO'
3818
`break LINESPEC task TASKNO if ...'
3819
     These commands are like the `break ... thread ...' command (*note
3820
     Thread Stops::).  LINESPEC specifies source lines, as described in
3821
     *Note Specify Location::.
3822
 
3823
     Use the qualifier `task TASKNO' with a breakpoint command to
3824
     specify that you only want GDB to stop the program when a
3825
     particular Ada task reaches this breakpoint.  TASKNO is one of the
3826
     numeric task identifiers assigned by GDB, shown in the first
3827
     column of the `info tasks' display.
3828
 
3829
     If you do not specify `task TASKNO' when you set a breakpoint, the
3830
     breakpoint applies to _all_ tasks of your program.
3831
 
3832
     You can use the `task' qualifier on conditional breakpoints as
3833
     well; in this case, place `task TASKNO' before the breakpoint
3834
     condition (before the `if').
3835
 
3836
     For example,
3837
 
3838
          (gdb) info tasks
3839
            ID       TID P-ID Pri State                 Name
3840
             1 140022020   0   15 Child Activation Wait main_task
3841
             2 140045060   1   15 Accept/Select Wait    t2
3842
             3 140044840   1   15 Runnable              t1
3843
          *  4 140056040   1   15 Runnable              t3
3844
          (gdb) b 15 task 2
3845
          Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
3846
          (gdb) cont
3847
          Continuing.
3848
          task # 1 running
3849
          task # 2 running
3850
 
3851
          Breakpoint 5, test_task_debug () at test_task_debug.adb:15
3852
          15               flush;
3853
          (gdb) info tasks
3854
            ID       TID P-ID Pri State                 Name
3855
             1 140022020   0   15 Child Activation Wait main_task
3856
          *  2 140045060   1   15 Runnable              t2
3857
             3 140044840   1   15 Runnable              t1
3858
             4 140056040   1   15 Delay Sleep           t3
3859
 
3860

3861
File: gdb.info,  Node: Ada Tasks and Core Files,  Next: Ada Glitches,  Prev: Ada Tasks,  Up: Ada
3862
 
3863
15.4.6.6 Tasking Support when Debugging Core Files
3864
..................................................
3865
 
3866
When inspecting a core file, as opposed to debugging a live program,
3867
tasking support may be limited or even unavailable, depending on the
3868
platform being used.  For instance, on x86-linux, the list of tasks is
3869
available, but task switching is not supported.  On Tru64, however,
3870
task switching will work as usual.
3871
 
3872
   On certain platforms, including Tru64, the debugger needs to perform
3873
some memory writes in order to provide Ada tasking support.  When
3874
inspecting a core file, this means that the core file must be opened
3875
with read-write privileges, using the command `"set write on"' (*note
3876
Patching::).  Under these circumstances, you should make a backup copy
3877
of the core file before inspecting it with GDB.
3878
 
3879

3880
File: gdb.info,  Node: Ada Glitches,  Prev: Ada Tasks and Core Files,  Up: Ada
3881
 
3882
15.4.6.7 Known Peculiarities of Ada Mode
3883
........................................
3884
 
3885
Besides the omissions listed previously (*note Omissions from Ada::),
3886
we know of several problems with and limitations of Ada mode in GDB,
3887
some of which will be fixed with planned future releases of the debugger
3888
and the GNU Ada compiler.
3889
 
3890
   * Currently, the debugger has insufficient information to determine
3891
     whether certain pointers represent pointers to objects or the
3892
     objects themselves.  Thus, the user may have to tack an extra
3893
     `.all' after an expression to get it printed properly.
3894
 
3895
   * Static constants that the compiler chooses not to materialize as
3896
     objects in storage are invisible to the debugger.
3897
 
3898
   * Named parameter associations in function argument lists are
3899
     ignored (the argument lists are treated as positional).
3900
 
3901
   * Many useful library packages are currently invisible to the
3902
     debugger.
3903
 
3904
   * Fixed-point arithmetic, conversions, input, and output is carried
3905
     out using floating-point arithmetic, and may give results that
3906
     only approximate those on the host machine.
3907
 
3908
   * The GNAT compiler never generates the prefix `Standard' for any of
3909
     the standard symbols defined by the Ada language.  GDB knows about
3910
     this: it will strip the prefix from names when you use it, and
3911
     will never look for a name you have so qualified among local
3912
     symbols, nor match against symbols in other packages or
3913
     subprograms.  If you have defined entities anywhere in your
3914
     program other than parameters and local variables whose simple
3915
     names match names in `Standard', GNAT's lack of qualification here
3916
     can cause confusion.  When this happens, you can usually resolve
3917
     the confusion by qualifying the problematic names with package
3918
     `Standard' explicitly.
3919
 
3920
   Older versions of the compiler sometimes generate erroneous debugging
3921
information, resulting in the debugger incorrectly printing the value
3922
of affected entities.  In some cases, the debugger is able to work
3923
around an issue automatically. In other cases, the debugger is able to
3924
work around the issue, but the work-around has to be specifically
3925
enabled.
3926
 
3927
`set ada trust-PAD-over-XVS on'
3928
     Configure GDB to strictly follow the GNAT encoding when computing
3929
     the value of Ada entities, particularly when `PAD' and `PAD___XVS'
3930
     types are involved (see `ada/exp_dbug.ads' in the GCC sources for
3931
     a complete description of the encoding used by the GNAT compiler).
3932
     This is the default.
3933
 
3934
`set ada trust-PAD-over-XVS off'
3935
     This is related to the encoding using by the GNAT compiler.  If
3936
     GDB sometimes prints the wrong value for certain entities,
3937
     changing `ada trust-PAD-over-XVS' to `off' activates a work-around
3938
     which may fix the issue.  It is always safe to set `ada
3939
     trust-PAD-over-XVS' to `off', but this incurs a slight performance
3940
     penalty, so it is recommended to leave this setting to `on' unless
3941
     necessary.
3942
 
3943
 
3944

3945
File: gdb.info,  Node: Unsupported Languages,  Prev: Supported Languages,  Up: Languages
3946
 
3947
15.5 Unsupported Languages
3948
==========================
3949
 
3950
In addition to the other fully-supported programming languages, GDB
3951
also provides a pseudo-language, called `minimal'.  It does not
3952
represent a real programming language, but provides a set of
3953
capabilities close to what the C or assembly languages provide.  This
3954
should allow most simple operations to be performed while debugging an
3955
application that uses a language currently not supported by GDB.
3956
 
3957
   If the language is set to `auto', GDB will automatically select this
3958
language if the current frame corresponds to an unsupported language.
3959
 
3960

3961
File: gdb.info,  Node: Symbols,  Next: Altering,  Prev: Languages,  Up: Top
3962
 
3963
16 Examining the Symbol Table
3964
*****************************
3965
 
3966
The commands described in this chapter allow you to inquire about the
3967
symbols (names of variables, functions and types) defined in your
3968
program.  This information is inherent in the text of your program and
3969
does not change as your program executes.  GDB finds it in your
3970
program's symbol table, in the file indicated when you started GDB
3971
(*note Choosing Files: File Options.), or by one of the file-management
3972
commands (*note Commands to Specify Files: Files.).
3973
 
3974
   Occasionally, you may need to refer to symbols that contain unusual
3975
characters, which GDB ordinarily treats as word delimiters.  The most
3976
frequent case is in referring to static variables in other source files
3977
(*note Program Variables: Variables.).  File names are recorded in
3978
object files as debugging symbols, but GDB would ordinarily parse a
3979
typical file name, like `foo.c', as the three words `foo' `.' `c'.  To
3980
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
3981
quotes; for example,
3982
 
3983
     p 'foo.c'::x
3984
 
3985
looks up the value of `x' in the scope of the file `foo.c'.
3986
 
3987
`set case-sensitive on'
3988
`set case-sensitive off'
3989
`set case-sensitive auto'
3990
     Normally, when GDB looks up symbols, it matches their names with
3991
     case sensitivity determined by the current source language.
3992
     Occasionally, you may wish to control that.  The command `set
3993
     case-sensitive' lets you do that by specifying `on' for
3994
     case-sensitive matches or `off' for case-insensitive ones.  If you
3995
     specify `auto', case sensitivity is reset to the default suitable
3996
     for the source language.  The default is case-sensitive matches
3997
     for all languages except for Fortran, for which the default is
3998
     case-insensitive matches.
3999
 
4000
`show case-sensitive'
4001
     This command shows the current setting of case sensitivity for
4002
     symbols lookups.
4003
 
4004
`info address SYMBOL'
4005
     Describe where the data for SYMBOL is stored.  For a register
4006
     variable, this says which register it is kept in.  For a
4007
     non-register local variable, this prints the stack-frame offset at
4008
     which the variable is always stored.
4009
 
4010
     Note the contrast with `print &SYMBOL', which does not work at all
4011
     for a register variable, and for a stack local variable prints the
4012
     exact address of the current instantiation of the variable.
4013
 
4014
`info symbol ADDR'
4015
     Print the name of a symbol which is stored at the address ADDR.
4016
     If no symbol is stored exactly at ADDR, GDB prints the nearest
4017
     symbol and an offset from it:
4018
 
4019
          (gdb) info symbol 0x54320
4020
          _initialize_vx + 396 in section .text
4021
 
4022
     This is the opposite of the `info address' command.  You can use
4023
     it to find out the name of a variable or a function given its
4024
     address.
4025
 
4026
     For dynamically linked executables, the name of executable or
4027
     shared library containing the symbol is also printed:
4028
 
4029
          (gdb) info symbol 0x400225
4030
          _start + 5 in section .text of /tmp/a.out
4031
          (gdb) info symbol 0x2aaaac2811cf
4032
          __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
4033
 
4034
`whatis [ARG]'
4035
     Print the data type of ARG, which can be either an expression or a
4036
     data type.  With no argument, print the data type of `$', the last
4037
     value in the value history.  If ARG is an expression, it is not
4038
     actually evaluated, and any side-effecting operations (such as
4039
     assignments or function calls) inside it do not take place.  If
4040
     ARG is a type name, it may be the name of a type or typedef, or
4041
     for C code it may have the form `class CLASS-NAME', `struct
4042
     STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'.  *Note
4043
     Expressions: Expressions.
4044
 
4045
`ptype [ARG]'
4046
     `ptype' accepts the same arguments as `whatis', but prints a
4047
     detailed description of the type, instead of just the name of the
4048
     type.  *Note Expressions: Expressions.
4049
 
4050
     For example, for this variable declaration:
4051
 
4052
          struct complex {double real; double imag;} v;
4053
 
4054
     the two commands give this output:
4055
 
4056
          (gdb) whatis v
4057
          type = struct complex
4058
          (gdb) ptype v
4059
          type = struct complex {
4060
              double real;
4061
              double imag;
4062
          }
4063
 
4064
     As with `whatis', using `ptype' without an argument refers to the
4065
     type of `$', the last value in the value history.
4066
 
4067
     Sometimes, programs use opaque data types or incomplete
4068
     specifications of complex data structure.  If the debug
4069
     information included in the program does not allow GDB to display
4070
     a full declaration of the data type, it will say `
4071
     type>'.  For example, given these declarations:
4072
 
4073
              struct foo;
4074
              struct foo *fooptr;
4075
 
4076
     but no definition for `struct foo' itself, GDB will say:
4077
 
4078
            (gdb) ptype foo
4079
            $1 = 
4080
 
4081
     "Incomplete type" is C terminology for data types that are not
4082
     completely specified.
4083
 
4084
`info types REGEXP'
4085
`info types'
4086
     Print a brief description of all types whose names match the
4087
     regular expression REGEXP (or all types in your program, if you
4088
     supply no argument).  Each complete typename is matched as though
4089
     it were a complete line; thus, `i type value' gives information on
4090
     all types in your program whose names include the string `value',
4091
     but `i type ^value$' gives information only on types whose complete
4092
     name is `value'.
4093
 
4094
     This command differs from `ptype' in two ways: first, like
4095
     `whatis', it does not print a detailed description; second, it
4096
     lists all source files where a type is defined.
4097
 
4098
`info scope LOCATION'
4099
     List all the variables local to a particular scope.  This command
4100
     accepts a LOCATION argument--a function name, a source line, or an
4101
     address preceded by a `*', and prints all the variables local to
4102
     the scope defined by that location.  (*Note Specify Location::, for
4103
     details about supported forms of LOCATION.)  For example:
4104
 
4105
          (gdb) info scope command_line_handler
4106
          Scope for command_line_handler:
4107
          Symbol rl is an argument at stack/frame offset 8, length 4.
4108
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
4109
          Symbol linelength is in static storage at address 0x150a1c, length 4.
4110
          Symbol p is a local variable in register $esi, length 4.
4111
          Symbol p1 is a local variable in register $ebx, length 4.
4112
          Symbol nline is a local variable in register $edx, length 4.
4113
          Symbol repeat is a local variable at frame offset -8, length 4.
4114
 
4115
     This command is especially useful for determining what data to
4116
     collect during a "trace experiment", see *Note collect: Tracepoint
4117
     Actions.
4118
 
4119
`info source'
4120
     Show information about the current source file--that is, the
4121
     source file for the function containing the current point of
4122
     execution:
4123
        * the name of the source file, and the directory containing it,
4124
 
4125
        * the directory it was compiled in,
4126
 
4127
        * its length, in lines,
4128
 
4129
        * which programming language it is written in,
4130
 
4131
        * whether the executable includes debugging information for
4132
          that file, and if so, what format the information is in
4133
          (e.g., STABS, Dwarf 2, etc.), and
4134
 
4135
        * whether the debugging information includes information about
4136
          preprocessor macros.
4137
 
4138
`info sources'
4139
     Print the names of all source files in your program for which
4140
     there is debugging information, organized into two lists: files
4141
     whose symbols have already been read, and files whose symbols will
4142
     be read when needed.
4143
 
4144
`info functions'
4145
     Print the names and data types of all defined functions.
4146
 
4147
`info functions REGEXP'
4148
     Print the names and data types of all defined functions whose
4149
     names contain a match for regular expression REGEXP.  Thus, `info
4150
     fun step' finds all functions whose names include `step'; `info
4151
     fun ^step' finds those whose names start with `step'.  If a
4152
     function name contains characters that conflict with the regular
4153
     expression language (e.g.  `operator*()'), they may be quoted with
4154
     a backslash.
4155
 
4156
`info variables'
4157
     Print the names and data types of all variables that are defined
4158
     outside of functions (i.e. excluding local variables).
4159
 
4160
`info variables REGEXP'
4161
     Print the names and data types of all variables (except for local
4162
     variables) whose names contain a match for regular expression
4163
     REGEXP.
4164
 
4165
`info classes'
4166
`info classes REGEXP'
4167
     Display all Objective-C classes in your program, or (with the
4168
     REGEXP argument) all those matching a particular regular
4169
     expression.
4170
 
4171
`info selectors'
4172
`info selectors REGEXP'
4173
     Display all Objective-C selectors in your program, or (with the
4174
     REGEXP argument) all those matching a particular regular
4175
     expression.
4176
 
4177
     Some systems allow individual object files that make up your
4178
     program to be replaced without stopping and restarting your
4179
     program.  For example, in VxWorks you can simply recompile a
4180
     defective object file and keep on running.  If you are running on
4181
     one of these systems, you can allow GDB to reload the symbols for
4182
     automatically relinked modules:
4183
 
4184
    `set symbol-reloading on'
4185
          Replace symbol definitions for the corresponding source file
4186
          when an object file with a particular name is seen again.
4187
 
4188
    `set symbol-reloading off'
4189
          Do not replace symbol definitions when encountering object
4190
          files of the same name more than once.  This is the default
4191
          state; if you are not running on a system that permits
4192
          automatic relinking of modules, you should leave
4193
          `symbol-reloading' off, since otherwise GDB may discard
4194
          symbols when linking large programs, that may contain several
4195
          modules (from different directories or libraries) with the
4196
          same name.
4197
 
4198
    `show symbol-reloading'
4199
          Show the current `on' or `off' setting.
4200
 
4201
`set opaque-type-resolution on'
4202
     Tell GDB to resolve opaque types.  An opaque type is a type
4203
     declared as a pointer to a `struct', `class', or `union'--for
4204
     example, `struct MyType *'--that is used in one source file
4205
     although the full declaration of `struct MyType' is in another
4206
     source file.  The default is on.
4207
 
4208
     A change in the setting of this subcommand will not take effect
4209
     until the next time symbols for a file are loaded.
4210
 
4211
`set opaque-type-resolution off'
4212
     Tell GDB not to resolve opaque types.  In this case, the type is
4213
     printed as follows:
4214
          {}
4215
 
4216
`show opaque-type-resolution'
4217
     Show whether opaque types are resolved or not.
4218
 
4219
`maint print symbols FILENAME'
4220
`maint print psymbols FILENAME'
4221
`maint print msymbols FILENAME'
4222
     Write a dump of debugging symbol data into the file FILENAME.
4223
     These commands are used to debug the GDB symbol-reading code.  Only
4224
     symbols with debugging data are included.  If you use `maint print
4225
     symbols', GDB includes all the symbols for which it has already
4226
     collected full details: that is, FILENAME reflects symbols for
4227
     only those files whose symbols GDB has read.  You can use the
4228
     command `info sources' to find out which files these are.  If you
4229
     use `maint print psymbols' instead, the dump shows information
4230
     about symbols that GDB only knows partially--that is, symbols
4231
     defined in files that GDB has skimmed, but not yet read
4232
     completely.  Finally, `maint print msymbols' dumps just the
4233
     minimal symbol information required for each object file from
4234
     which GDB has read some symbols.  *Note Commands to Specify Files:
4235
     Files, for a discussion of how GDB reads symbols (in the
4236
     description of `symbol-file').
4237
 
4238
`maint info symtabs [ REGEXP ]'
4239
`maint info psymtabs [ REGEXP ]'
4240
     List the `struct symtab' or `struct partial_symtab' structures
4241
     whose names match REGEXP.  If REGEXP is not given, list them all.
4242
     The output includes expressions which you can copy into a GDB
4243
     debugging this one to examine a particular structure in more
4244
     detail.  For example:
4245
 
4246
          (gdb) maint info psymtabs dwarf2read
4247
          { objfile /home/gnu/build/gdb/gdb
4248
            ((struct objfile *) 0x82e69d0)
4249
            { psymtab /home/gnu/src/gdb/dwarf2read.c
4250
              ((struct partial_symtab *) 0x8474b10)
4251
              readin no
4252
              fullname (null)
4253
              text addresses 0x814d3c8 -- 0x8158074
4254
              globals (* (struct partial_symbol **) 0x8507a08 @ 9)
4255
              statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
4256
              dependencies (none)
4257
            }
4258
          }
4259
          (gdb) maint info symtabs
4260
          (gdb)
4261
     We see that there is one partial symbol table whose filename
4262
     contains the string `dwarf2read', belonging to the `gdb'
4263
     executable; and we see that GDB has not read in any symtabs yet at
4264
     all.  If we set a breakpoint on a function, that will cause GDB to
4265
     read the symtab for the compilation unit containing that function:
4266
 
4267
          (gdb) break dwarf2_psymtab_to_symtab
4268
          Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
4269
          line 1574.
4270
          (gdb) maint info symtabs
4271
          { objfile /home/gnu/build/gdb/gdb
4272
            ((struct objfile *) 0x82e69d0)
4273
            { symtab /home/gnu/src/gdb/dwarf2read.c
4274
              ((struct symtab *) 0x86c1f38)
4275
              dirname (null)
4276
              fullname (null)
4277
              blockvector ((struct blockvector *) 0x86c1bd0) (primary)
4278
              linetable ((struct linetable *) 0x8370fa0)
4279
              debugformat DWARF 2
4280
            }
4281
          }
4282
          (gdb)
4283
 
4284

4285
File: gdb.info,  Node: Altering,  Next: GDB Files,  Prev: Symbols,  Up: Top
4286
 
4287
17 Altering Execution
4288
*********************
4289
 
4290
Once you think you have found an error in your program, you might want
4291
to find out for certain whether correcting the apparent error would
4292
lead to correct results in the rest of the run.  You can find the
4293
answer by experiment, using the GDB features for altering execution of
4294
the program.
4295
 
4296
   For example, you can store new values into variables or memory
4297
locations, give your program a signal, restart it at a different
4298
address, or even return prematurely from a function.
4299
 
4300
* Menu:
4301
 
4302
* Assignment::                  Assignment to variables
4303
* Jumping::                     Continuing at a different address
4304
* Signaling::                   Giving your program a signal
4305
* Returning::                   Returning from a function
4306
* Calling::                     Calling your program's functions
4307
* Patching::                    Patching your program
4308
 
4309

4310
File: gdb.info,  Node: Assignment,  Next: Jumping,  Up: Altering
4311
 
4312
17.1 Assignment to Variables
4313
============================
4314
 
4315
To alter the value of a variable, evaluate an assignment expression.
4316
*Note Expressions: Expressions.  For example,
4317
 
4318
     print x=4
4319
 
4320
stores the value 4 into the variable `x', and then prints the value of
4321
the assignment expression (which is 4).  *Note Using GDB with Different
4322
Languages: Languages, for more information on operators in supported
4323
languages.
4324
 
4325
   If you are not interested in seeing the value of the assignment, use
4326
the `set' command instead of the `print' command.  `set' is really the
4327
same as `print' except that the expression's value is not printed and
4328
is not put in the value history (*note Value History: Value History.).
4329
The expression is evaluated only for its effects.
4330
 
4331
   If the beginning of the argument string of the `set' command appears
4332
identical to a `set' subcommand, use the `set variable' command instead
4333
of just `set'.  This command is identical to `set' except for its lack
4334
of subcommands.  For example, if your program has a variable `width',
4335
you get an error if you try to set a new value with just `set
4336
width=13', because GDB has the command `set width':
4337
 
4338
     (gdb) whatis width
4339
     type = double
4340
     (gdb) p width
4341
     $4 = 13
4342
     (gdb) set width=47
4343
     Invalid syntax in expression.
4344
 
4345
The invalid expression, of course, is `=47'.  In order to actually set
4346
the program's variable `width', use
4347
 
4348
     (gdb) set var width=47
4349
 
4350
   Because the `set' command has many subcommands that can conflict
4351
with the names of program variables, it is a good idea to use the `set
4352
variable' command instead of just `set'.  For example, if your program
4353
has a variable `g', you run into problems if you try to set a new value
4354
with just `set g=4', because GDB has the command `set gnutarget',
4355
abbreviated `set g':
4356
 
4357
     (gdb) whatis g
4358
     type = double
4359
     (gdb) p g
4360
     $1 = 1
4361
     (gdb) set g=4
4362
     (gdb) p g
4363
     $2 = 1
4364
     (gdb) r
4365
     The program being debugged has been started already.
4366
     Start it from the beginning? (y or n) y
4367
     Starting program: /home/smith/cc_progs/a.out
4368
     "/home/smith/cc_progs/a.out": can't open to read symbols:
4369
                                      Invalid bfd target.
4370
     (gdb) show g
4371
     The current BFD target is "=4".
4372
 
4373
The program variable `g' did not change, and you silently set the
4374
`gnutarget' to an invalid value.  In order to set the variable `g', use
4375
 
4376
     (gdb) set var g=4
4377
 
4378
   GDB allows more implicit conversions in assignments than C; you can
4379
freely store an integer value into a pointer variable or vice versa,
4380
and you can convert any structure to any other structure that is the
4381
same length or shorter.
4382
 
4383
   To store values into arbitrary places in memory, use the `{...}'
4384
construct to generate a value of specified type at a specified address
4385
(*note Expressions: Expressions.).  For example, `{int}0x83040' refers
4386
to memory location `0x83040' as an integer (which implies a certain size
4387
and representation in memory), and
4388
 
4389
     set {int}0x83040 = 4
4390
 
4391
stores the value 4 into that memory location.
4392
 
4393

4394
File: gdb.info,  Node: Jumping,  Next: Signaling,  Prev: Assignment,  Up: Altering
4395
 
4396
17.2 Continuing at a Different Address
4397
======================================
4398
 
4399
Ordinarily, when you continue your program, you do so at the place where
4400
it stopped, with the `continue' command.  You can instead continue at
4401
an address of your own choosing, with the following commands:
4402
 
4403
`jump LINESPEC'
4404
`jump LOCATION'
4405
     Resume execution at line LINESPEC or at address given by LOCATION.
4406
     Execution stops again immediately if there is a breakpoint there.
4407
     *Note Specify Location::, for a description of the different
4408
     forms of LINESPEC and LOCATION.  It is common practice to use the
4409
     `tbreak' command in conjunction with `jump'.  *Note Setting
4410
     Breakpoints: Set Breaks.
4411
 
4412
     The `jump' command does not change the current stack frame, or the
4413
     stack pointer, or the contents of any memory location or any
4414
     register other than the program counter.  If line LINESPEC is in a
4415
     different function from the one currently executing, the results
4416
     may be bizarre if the two functions expect different patterns of
4417
     arguments or of local variables.  For this reason, the `jump'
4418
     command requests confirmation if the specified line is not in the
4419
     function currently executing.  However, even bizarre results are
4420
     predictable if you are well acquainted with the machine-language
4421
     code of your program.
4422
 
4423
   On many systems, you can get much the same effect as the `jump'
4424
command by storing a new value into the register `$pc'.  The difference
4425
is that this does not start your program running; it only changes the
4426
address of where it _will_ run when you continue.  For example,
4427
 
4428
     set $pc = 0x485
4429
 
4430
makes the next `continue' command or stepping command execute at
4431
address `0x485', rather than at the address where your program stopped.
4432
*Note Continuing and Stepping: Continuing and Stepping.
4433
 
4434
   The most common occasion to use the `jump' command is to back
4435
up--perhaps with more breakpoints set--over a portion of a program that
4436
has already executed, in order to examine its execution in more detail.
4437
 
4438

4439
File: gdb.info,  Node: Signaling,  Next: Returning,  Prev: Jumping,  Up: Altering
4440
 
4441
17.3 Giving your Program a Signal
4442
=================================
4443
 
4444
`signal SIGNAL'
4445
     Resume execution where your program stopped, but immediately give
4446
     it the signal SIGNAL.  SIGNAL can be the name or the number of a
4447
     signal.  For example, on many systems `signal 2' and `signal
4448
     SIGINT' are both ways of sending an interrupt signal.
4449
 
4450
     Alternatively, if SIGNAL is zero, continue execution without
4451
     giving a signal.  This is useful when your program stopped on
4452
     account of a signal and would ordinary see the signal when resumed
4453
     with the `continue' command; `signal 0' causes it to resume
4454
     without a signal.
4455
 
4456
     `signal' does not repeat when you press  a second time after
4457
     executing the command.
4458
 
4459
   Invoking the `signal' command is not the same as invoking the `kill'
4460
utility from the shell.  Sending a signal with `kill' causes GDB to
4461
decide what to do with the signal depending on the signal handling
4462
tables (*note Signals::).  The `signal' command passes the signal
4463
directly to your program.
4464
 
4465

4466
File: gdb.info,  Node: Returning,  Next: Calling,  Prev: Signaling,  Up: Altering
4467
 
4468
17.4 Returning from a Function
4469
==============================
4470
 
4471
`return'
4472
`return EXPRESSION'
4473
     You can cancel execution of a function call with the `return'
4474
     command.  If you give an EXPRESSION argument, its value is used as
4475
     the function's return value.
4476
 
4477
   When you use `return', GDB discards the selected stack frame (and
4478
all frames within it).  You can think of this as making the discarded
4479
frame return prematurely.  If you wish to specify a value to be
4480
returned, give that value as the argument to `return'.
4481
 
4482
   This pops the selected stack frame (*note Selecting a Frame:
4483
Selection.), and any other frames inside of it, leaving its caller as
4484
the innermost remaining frame.  That frame becomes selected.  The
4485
specified value is stored in the registers used for returning values of
4486
functions.
4487
 
4488
   The `return' command does not resume execution; it leaves the
4489
program stopped in the state that would exist if the function had just
4490
returned.  In contrast, the `finish' command (*note Continuing and
4491
Stepping: Continuing and Stepping.) resumes execution until the
4492
selected stack frame returns naturally.
4493
 
4494
   GDB needs to know how the EXPRESSION argument should be set for the
4495
inferior.  The concrete registers assignment depends on the OS ABI and
4496
the type being returned by the selected stack frame.  For example it is
4497
common for OS ABI to return floating point values in FPU registers
4498
while integer values in CPU registers.  Still some ABIs return even
4499
floating point values in CPU registers.  Larger integer widths (such as
4500
`long long int') also have specific placement rules.  GDB already knows
4501
the OS ABI from its current target so it needs to find out also the
4502
type being returned to make the assignment into the right register(s).
4503
 
4504
   Normally, the selected stack frame has debug info.  GDB will always
4505
use the debug info instead of the implicit type of EXPRESSION when the
4506
debug info is available.  For example, if you type `return -1', and the
4507
function in the current stack frame is declared to return a `long long
4508
int', GDB transparently converts the implicit `int' value of -1 into a
4509
`long long int':
4510
 
4511
     Breakpoint 1, func () at gdb.base/return-nodebug.c:29
4512
     29        return 31;
4513
     (gdb) return -1
4514
     Make func return now? (y or n) y
4515
     #0  0x004004f6 in main () at gdb.base/return-nodebug.c:43
4516
     43        printf ("result=%lld\n", func ());
4517
     (gdb)
4518
 
4519
   However, if the selected stack frame does not have a debug info,
4520
e.g., if the function was compiled without debug info, GDB has to find
4521
out the type to return from user.  Specifying a different type by
4522
mistake may set the value in different inferior registers than the
4523
caller code expects.  For example, typing `return -1' with its implicit
4524
type `int' would set only a part of a `long long int' result for a
4525
debug info less function (on 32-bit architectures).  Therefore the user
4526
is required to specify the return type by an appropriate cast
4527
explicitly:
4528
 
4529
     Breakpoint 2, 0x0040050b in func ()
4530
     (gdb) return -1
4531
     Return value type not available for selected stack frame.
4532
     Please use an explicit cast of the value to return.
4533
     (gdb) return (long long int) -1
4534
     Make selected stack frame return now? (y or n) y
4535
     #0  0x00400526 in main ()
4536
     (gdb)
4537
 
4538

4539
File: gdb.info,  Node: Calling,  Next: Patching,  Prev: Returning,  Up: Altering
4540
 
4541
17.5 Calling Program Functions
4542
==============================
4543
 
4544
`print EXPR'
4545
     Evaluate the expression EXPR and display the resulting value.
4546
     EXPR may include calls to functions in the program being debugged.
4547
 
4548
`call EXPR'
4549
     Evaluate the expression EXPR without displaying `void' returned
4550
     values.
4551
 
4552
     You can use this variant of the `print' command if you want to
4553
     execute a function from your program that does not return anything
4554
     (a.k.a. "a void function"), but without cluttering the output with
4555
     `void' returned values that GDB will otherwise print.  If the
4556
     result is not void, it is printed and saved in the value history.
4557
 
4558
   It is possible for the function you call via the `print' or `call'
4559
command to generate a signal (e.g., if there's a bug in the function,
4560
or if you passed it incorrect arguments).  What happens in that case is
4561
controlled by the `set unwindonsignal' command.
4562
 
4563
   Similarly, with a C++ program it is possible for the function you
4564
call via the `print' or `call' command to generate an exception that is
4565
not handled due to the constraints of the dummy frame.  In this case,
4566
any exception that is raised in the frame, but has an out-of-frame
4567
exception handler will not be found.  GDB builds a dummy-frame for the
4568
inferior function call, and the unwinder cannot seek for exception
4569
handlers outside of this dummy-frame.  What happens in that case is
4570
controlled by the `set unwind-on-terminating-exception' command.
4571
 
4572
`set unwindonsignal'
4573
     Set unwinding of the stack if a signal is received while in a
4574
     function that GDB called in the program being debugged.  If set to
4575
     on, GDB unwinds the stack it created for the call and restores the
4576
     context to what it was before the call.  If set to off (the
4577
     default), GDB stops in the frame where the signal was received.
4578
 
4579
`show unwindonsignal'
4580
     Show the current setting of stack unwinding in the functions
4581
     called by GDB.
4582
 
4583
`set unwind-on-terminating-exception'
4584
     Set unwinding of the stack if a C++ exception is raised, but left
4585
     unhandled while in a function that GDB called in the program being
4586
     debugged.  If set to on (the default), GDB unwinds the stack it
4587
     created for the call and restores the context to what it was before
4588
     the call.  If set to off, GDB the exception is delivered to the
4589
     default C++ exception handler and the inferior terminated.
4590
 
4591
`show unwind-on-terminating-exception'
4592
     Show the current setting of stack unwinding in the functions
4593
     called by GDB.
4594
 
4595
 
4596
   Sometimes, a function you wish to call is actually a "weak alias"
4597
for another function.  In such case, GDB might not pick up the type
4598
information, including the types of the function arguments, which
4599
causes GDB to call the inferior function incorrectly.  As a result, the
4600
called function will function erroneously and may even crash.  A
4601
solution to that is to use the name of the aliased function instead.
4602
 
4603

4604
File: gdb.info,  Node: Patching,  Prev: Calling,  Up: Altering
4605
 
4606
17.6 Patching Programs
4607
======================
4608
 
4609
By default, GDB opens the file containing your program's executable
4610
code (or the corefile) read-only.  This prevents accidental alterations
4611
to machine code; but it also prevents you from intentionally patching
4612
your program's binary.
4613
 
4614
   If you'd like to be able to patch the binary, you can specify that
4615
explicitly with the `set write' command.  For example, you might want
4616
to turn on internal debugging flags, or even to make emergency repairs.
4617
 
4618
`set write on'
4619
`set write off'
4620
     If you specify `set write on', GDB opens executable and core files
4621
     for both reading and writing; if you specify `set write off' (the
4622
     default), GDB opens them read-only.
4623
 
4624
     If you have already loaded a file, you must load it again (using
4625
     the `exec-file' or `core-file' command) after changing `set
4626
     write', for your new setting to take effect.
4627
 
4628
`show write'
4629
     Display whether executable files and core files are opened for
4630
     writing as well as reading.
4631
 
4632

4633
File: gdb.info,  Node: GDB Files,  Next: Targets,  Prev: Altering,  Up: Top
4634
 
4635
18 GDB Files
4636
************
4637
 
4638
GDB needs to know the file name of the program to be debugged, both in
4639
order to read its symbol table and in order to start your program.  To
4640
debug a core dump of a previous run, you must also tell GDB the name of
4641
the core dump file.
4642
 
4643
* Menu:
4644
 
4645
* Files::                       Commands to specify files
4646
* Separate Debug Files::        Debugging information in separate files
4647
* Symbol Errors::               Errors reading symbol files
4648
* Data Files::                  GDB data files
4649
 
4650

4651
File: gdb.info,  Node: Files,  Next: Separate Debug Files,  Up: GDB Files
4652
 
4653
18.1 Commands to Specify Files
4654
==============================
4655
 
4656
You may want to specify executable and core dump file names.  The usual
4657
way to do this is at start-up time, using the arguments to GDB's
4658
start-up commands (*note Getting In and Out of GDB: Invocation.).
4659
 
4660
   Occasionally it is necessary to change to a different file during a
4661
GDB session.  Or you may run GDB and forget to specify a file you want
4662
to use.  Or you are debugging a remote target via `gdbserver' (*note
4663
file: Server.).  In these situations the GDB commands to specify new
4664
files are useful.
4665
 
4666
`file FILENAME'
4667
     Use FILENAME as the program to be debugged.  It is read for its
4668
     symbols and for the contents of pure memory.  It is also the
4669
     program executed when you use the `run' command.  If you do not
4670
     specify a directory and the file is not found in the GDB working
4671
     directory, GDB uses the environment variable `PATH' as a list of
4672
     directories to search, just as the shell does when looking for a
4673
     program to run.  You can change the value of this variable, for
4674
     both GDB and your program, using the `path' command.
4675
 
4676
     You can load unlinked object `.o' files into GDB using the `file'
4677
     command.  You will not be able to "run" an object file, but you
4678
     can disassemble functions and inspect variables.  Also, if the
4679
     underlying BFD functionality supports it, you could use `gdb
4680
     -write' to patch object files using this technique.  Note that GDB
4681
     can neither interpret nor modify relocations in this case, so
4682
     branches and some initialized variables will appear to go to the
4683
     wrong place.  But this feature is still handy from time to time.
4684
 
4685
`file'
4686
     `file' with no argument makes GDB discard any information it has
4687
     on both executable file and the symbol table.
4688
 
4689
`exec-file [ FILENAME ]'
4690
     Specify that the program to be run (but not the symbol table) is
4691
     found in FILENAME.  GDB searches the environment variable `PATH'
4692
     if necessary to locate your program.  Omitting FILENAME means to
4693
     discard information on the executable file.
4694
 
4695
`symbol-file [ FILENAME ]'
4696
     Read symbol table information from file FILENAME.  `PATH' is
4697
     searched when necessary.  Use the `file' command to get both symbol
4698
     table and program to run from the same file.
4699
 
4700
     `symbol-file' with no argument clears out GDB information on your
4701
     program's symbol table.
4702
 
4703
     The `symbol-file' command causes GDB to forget the contents of
4704
     some breakpoints and auto-display expressions.  This is because
4705
     they may contain pointers to the internal data recording symbols
4706
     and data types, which are part of the old symbol table data being
4707
     discarded inside GDB.
4708
 
4709
     `symbol-file' does not repeat if you press  again after
4710
     executing it once.
4711
 
4712
     When GDB is configured for a particular environment, it
4713
     understands debugging information in whatever format is the
4714
     standard generated for that environment; you may use either a GNU
4715
     compiler, or other compilers that adhere to the local conventions.
4716
     Best results are usually obtained from GNU compilers; for example,
4717
     using `GCC' you can generate debugging information for optimized
4718
     code.
4719
 
4720
     For most kinds of object files, with the exception of old SVR3
4721
     systems using COFF, the `symbol-file' command does not normally
4722
     read the symbol table in full right away.  Instead, it scans the
4723
     symbol table quickly to find which source files and which symbols
4724
     are present.  The details are read later, one source file at a
4725
     time, as they are needed.
4726
 
4727
     The purpose of this two-stage reading strategy is to make GDB
4728
     start up faster.  For the most part, it is invisible except for
4729
     occasional pauses while the symbol table details for a particular
4730
     source file are being read.  (The `set verbose' command can turn
4731
     these pauses into messages if desired.  *Note Optional Warnings
4732
     and Messages: Messages/Warnings.)
4733
 
4734
     We have not implemented the two-stage strategy for COFF yet.  When
4735
     the symbol table is stored in COFF format, `symbol-file' reads the
4736
     symbol table data in full right away.  Note that "stabs-in-COFF"
4737
     still does the two-stage strategy, since the debug info is actually
4738
     in stabs format.
4739
 
4740
`symbol-file [ -readnow ] FILENAME'
4741
`file [ -readnow ] FILENAME'
4742
     You can override the GDB two-stage strategy for reading symbol
4743
     tables by using the `-readnow' option with any of the commands that
4744
     load symbol table information, if you want to be sure GDB has the
4745
     entire symbol table available.
4746
 
4747
`core-file [FILENAME]'
4748
`core'
4749
     Specify the whereabouts of a core dump file to be used as the
4750
     "contents of memory".  Traditionally, core files contain only some
4751
     parts of the address space of the process that generated them; GDB
4752
     can access the executable file itself for other parts.
4753
 
4754
     `core-file' with no argument specifies that no core file is to be
4755
     used.
4756
 
4757
     Note that the core file is ignored when your program is actually
4758
     running under GDB.  So, if you have been running your program and
4759
     you wish to debug a core file instead, you must kill the
4760
     subprocess in which the program is running.  To do this, use the
4761
     `kill' command (*note Killing the Child Process: Kill Process.).
4762
 
4763
`add-symbol-file FILENAME ADDRESS'
4764
`add-symbol-file FILENAME ADDRESS [ -readnow ]'
4765
`add-symbol-file FILENAME -sSECTION ADDRESS ...'
4766
     The `add-symbol-file' command reads additional symbol table
4767
     information from the file FILENAME.  You would use this command
4768
     when FILENAME has been dynamically loaded (by some other means)
4769
     into the program that is running.  ADDRESS should be the memory
4770
     address at which the file has been loaded; GDB cannot figure this
4771
     out for itself.  You can additionally specify an arbitrary number
4772
     of `-sSECTION ADDRESS' pairs, to give an explicit section name and
4773
     base address for that section.  You can specify any ADDRESS as an
4774
     expression.
4775
 
4776
     The symbol table of the file FILENAME is added to the symbol table
4777
     originally read with the `symbol-file' command.  You can use the
4778
     `add-symbol-file' command any number of times; the new symbol data
4779
     thus read keeps adding to the old.  To discard all old symbol data
4780
     instead, use the `symbol-file' command without any arguments.
4781
 
4782
     Although FILENAME is typically a shared library file, an
4783
     executable file, or some other object file which has been fully
4784
     relocated for loading into a process, you can also load symbolic
4785
     information from relocatable `.o' files, as long as:
4786
 
4787
        * the file's symbolic information refers only to linker symbols
4788
          defined in that file, not to symbols defined by other object
4789
          files,
4790
 
4791
        * every section the file's symbolic information refers to has
4792
          actually been loaded into the inferior, as it appears in the
4793
          file, and
4794
 
4795
        * you can determine the address at which every section was
4796
          loaded, and provide these to the `add-symbol-file' command.
4797
 
4798
     Some embedded operating systems, like Sun Chorus and VxWorks, can
4799
     load relocatable files into an already running program; such
4800
     systems typically make the requirements above easy to meet.
4801
     However, it's important to recognize that many native systems use
4802
     complex link procedures (`.linkonce' section factoring and C++
4803
     constructor table assembly, for example) that make the
4804
     requirements difficult to meet.  In general, one cannot assume
4805
     that using `add-symbol-file' to read a relocatable object file's
4806
     symbolic information will have the same effect as linking the
4807
     relocatable object file into the program in the normal way.
4808
 
4809
     `add-symbol-file' does not repeat if you press  after using
4810
     it.
4811
 
4812
`add-symbol-file-from-memory ADDRESS'
4813
     Load symbols from the given ADDRESS in a dynamically loaded object
4814
     file whose image is mapped directly into the inferior's memory.
4815
     For example, the Linux kernel maps a `syscall DSO' into each
4816
     process's address space; this DSO provides kernel-specific code for
4817
     some system calls.  The argument can be any expression whose
4818
     evaluation yields the address of the file's shared object file
4819
     header.  For this command to work, you must have used
4820
     `symbol-file' or `exec-file' commands in advance.
4821
 
4822
`add-shared-symbol-files LIBRARY-FILE'
4823
`assf LIBRARY-FILE'
4824
     The `add-shared-symbol-files' command can currently be used only
4825
     in the Cygwin build of GDB on MS-Windows OS, where it is an alias
4826
     for the `dll-symbols' command (*note Cygwin Native::).  GDB
4827
     automatically looks for shared libraries, however if GDB does not
4828
     find yours, you can invoke `add-shared-symbol-files'.  It takes
4829
     one argument: the shared library's file name.  `assf' is a
4830
     shorthand alias for `add-shared-symbol-files'.
4831
 
4832
`section SECTION ADDR'
4833
     The `section' command changes the base address of the named
4834
     SECTION of the exec file to ADDR.  This can be used if the exec
4835
     file does not contain section addresses, (such as in the `a.out'
4836
     format), or when the addresses specified in the file itself are
4837
     wrong.  Each section must be changed separately.  The `info files'
4838
     command, described below, lists all the sections and their
4839
     addresses.
4840
 
4841
`info files'
4842
`info target'
4843
     `info files' and `info target' are synonymous; both print the
4844
     current target (*note Specifying a Debugging Target: Targets.),
4845
     including the names of the executable and core dump files
4846
     currently in use by GDB, and the files from which symbols were
4847
     loaded.  The command `help target' lists all possible targets
4848
     rather than current ones.
4849
 
4850
`maint info sections'
4851
     Another command that can give you extra information about program
4852
     sections is `maint info sections'.  In addition to the section
4853
     information displayed by `info files', this command displays the
4854
     flags and file offset of each section in the executable and core
4855
     dump files.  In addition, `maint info sections' provides the
4856
     following command options (which may be arbitrarily combined):
4857
 
4858
    `ALLOBJ'
4859
          Display sections for all loaded object files, including
4860
          shared libraries.
4861
 
4862
    `SECTIONS'
4863
          Display info only for named SECTIONS.
4864
 
4865
    `SECTION-FLAGS'
4866
          Display info only for sections for which SECTION-FLAGS are
4867
          true.  The section flags that GDB currently knows about are:
4868
         `ALLOC'
4869
               Section will have space allocated in the process when
4870
               loaded.  Set for all sections except those containing
4871
               debug information.
4872
 
4873
         `LOAD'
4874
               Section will be loaded from the file into the child
4875
               process memory.  Set for pre-initialized code and data,
4876
               clear for `.bss' sections.
4877
 
4878
         `RELOC'
4879
               Section needs to be relocated before loading.
4880
 
4881
         `READONLY'
4882
               Section cannot be modified by the child process.
4883
 
4884
         `CODE'
4885
               Section contains executable code only.
4886
 
4887
         `DATA'
4888
               Section contains data only (no executable code).
4889
 
4890
         `ROM'
4891
               Section will reside in ROM.
4892
 
4893
         `CONSTRUCTOR'
4894
               Section contains data for constructor/destructor lists.
4895
 
4896
         `HAS_CONTENTS'
4897
               Section is not empty.
4898
 
4899
         `NEVER_LOAD'
4900
               An instruction to the linker to not output the section.
4901
 
4902
         `COFF_SHARED_LIBRARY'
4903
               A notification to the linker that the section contains
4904
               COFF shared library information.
4905
 
4906
         `IS_COMMON'
4907
               Section contains common symbols.
4908
 
4909
`set trust-readonly-sections on'
4910
     Tell GDB that readonly sections in your object file really are
4911
     read-only (i.e. that their contents will not change).  In that
4912
     case, GDB can fetch values from these sections out of the object
4913
     file, rather than from the target program.  For some targets
4914
     (notably embedded ones), this can be a significant enhancement to
4915
     debugging performance.
4916
 
4917
     The default is off.
4918
 
4919
`set trust-readonly-sections off'
4920
     Tell GDB not to trust readonly sections.  This means that the
4921
     contents of the section might change while the program is running,
4922
     and must therefore be fetched from the target when needed.
4923
 
4924
`show trust-readonly-sections'
4925
     Show the current setting of trusting readonly sections.
4926
 
4927
   All file-specifying commands allow both absolute and relative file
4928
names as arguments.  GDB always converts the file name to an absolute
4929
file name and remembers it that way.
4930
 
4931
   GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and
4932
IBM RS/6000 AIX shared libraries.
4933
 
4934
   On MS-Windows GDB must be linked with the Expat library to support
4935
shared libraries.  *Note Expat::.
4936
 
4937
   GDB automatically loads symbol definitions from shared libraries
4938
when you use the `run' command, or when you examine a core file.
4939
(Before you issue the `run' command, GDB does not understand references
4940
to a function in a shared library, however--unless you are debugging a
4941
core file).
4942
 
4943
   On HP-UX, if the program loads a library explicitly, GDB
4944
automatically loads the symbols at the time of the `shl_load' call.
4945
 
4946
   There are times, however, when you may wish to not automatically load
4947
symbol definitions from shared libraries, such as when they are
4948
particularly large or there are many of them.
4949
 
4950
   To control the automatic loading of shared library symbols, use the
4951
commands:
4952
 
4953
`set auto-solib-add MODE'
4954
     If MODE is `on', symbols from all shared object libraries will be
4955
     loaded automatically when the inferior begins execution, you
4956
     attach to an independently started inferior, or when the dynamic
4957
     linker informs GDB that a new library has been loaded.  If MODE is
4958
     `off', symbols must be loaded manually, using the `sharedlibrary'
4959
     command.  The default value is `on'.
4960
 
4961
     If your program uses lots of shared libraries with debug info that
4962
     takes large amounts of memory, you can decrease the GDB memory
4963
     footprint by preventing it from automatically loading the symbols
4964
     from shared libraries.  To that end, type `set auto-solib-add off'
4965
     before running the inferior, then load each library whose debug
4966
     symbols you do need with `sharedlibrary REGEXP', where REGEXP is a
4967
     regular expression that matches the libraries whose symbols you
4968
     want to be loaded.
4969
 
4970
`show auto-solib-add'
4971
     Display the current autoloading mode.
4972
 
4973
   To explicitly load shared library symbols, use the `sharedlibrary'
4974
command:
4975
 
4976
`info share REGEX'
4977
`info sharedlibrary REGEX'
4978
     Print the names of the shared libraries which are currently loaded
4979
     that match REGEX.  If REGEX is omitted then print all shared
4980
     libraries that are loaded.
4981
 
4982
`sharedlibrary REGEX'
4983
`share REGEX'
4984
     Load shared object library symbols for files matching a Unix
4985
     regular expression.  As with files loaded automatically, it only
4986
     loads shared libraries required by your program for a core file or
4987
     after typing `run'.  If REGEX is omitted all shared libraries
4988
     required by your program are loaded.
4989
 
4990
`nosharedlibrary'
4991
     Unload all shared object library symbols.  This discards all
4992
     symbols that have been loaded from all shared libraries.  Symbols
4993
     from shared libraries that were loaded by explicit user requests
4994
     are not discarded.
4995
 
4996
   Sometimes you may wish that GDB stops and gives you control when any
4997
of shared library events happen.  Use the `set stop-on-solib-events'
4998
command for this:
4999
 
5000
`set stop-on-solib-events'
5001
     This command controls whether GDB should give you control when the
5002
     dynamic linker notifies it about some shared library event.  The
5003
     most common event of interest is loading or unloading of a new
5004
     shared library.
5005
 
5006
`show stop-on-solib-events'
5007
     Show whether GDB stops and gives you control when shared library
5008
     events happen.
5009
 
5010
   Shared libraries are also supported in many cross or remote debugging
5011
configurations.  GDB needs to have access to the target's libraries;
5012
this can be accomplished either by providing copies of the libraries on
5013
the host system, or by asking GDB to automatically retrieve the
5014
libraries from the target.  If copies of the target libraries are
5015
provided, they need to be the same as the target libraries, although the
5016
copies on the target can be stripped as long as the copies on the host
5017
are not.
5018
 
5019
   For remote debugging, you need to tell GDB where the target
5020
libraries are, so that it can load the correct copies--otherwise, it
5021
may try to load the host's libraries.  GDB has two variables to specify
5022
the search directories for target libraries.
5023
 
5024
`set sysroot PATH'
5025
     Use PATH as the system root for the program being debugged.  Any
5026
     absolute shared library paths will be prefixed with PATH; many
5027
     runtime loaders store the absolute paths to the shared library in
5028
     the target program's memory.  If you use `set sysroot' to find
5029
     shared libraries, they need to be laid out in the same way that
5030
     they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy
5031
     under PATH.
5032
 
5033
     If PATH starts with the sequence `remote:', GDB will retrieve the
5034
     target libraries from the remote system.  This is only supported
5035
     when using a remote target that supports the `remote get' command
5036
     (*note Sending files to a remote system: File Transfer.).  The
5037
     part of PATH following the initial `remote:' (if present) is used
5038
     as system root prefix on the remote file system.  (1)
5039
 
5040
     The `set solib-absolute-prefix' command is an alias for `set
5041
     sysroot'.
5042
 
5043
     You can set the default system root by using the configure-time
5044
     `--with-sysroot' option.  If the system root is inside GDB's
5045
     configured binary prefix (set with `--prefix' or `--exec-prefix'),
5046
     then the default system root will be updated automatically if the
5047
     installed GDB is moved to a new location.
5048
 
5049
`show sysroot'
5050
     Display the current shared library prefix.
5051
 
5052
`set solib-search-path PATH'
5053
     If this variable is set, PATH is a colon-separated list of
5054
     directories to search for shared libraries.  `solib-search-path'
5055
     is used after `sysroot' fails to locate the library, or if the
5056
     path to the library is relative instead of absolute.  If you want
5057
     to use `solib-search-path' instead of `sysroot', be sure to set
5058
     `sysroot' to a nonexistent directory to prevent GDB from finding
5059
     your host's libraries.  `sysroot' is preferred; setting it to a
5060
     nonexistent directory may interfere with automatic loading of
5061
     shared library symbols.
5062
 
5063
`show solib-search-path'
5064
     Display the current shared library search path.
5065
 
5066
   ---------- Footnotes ----------
5067
 
5068
   (1) If you want to specify a local system root using a directory
5069
that happens to be named `remote:', you need to use some equivalent
5070
variant of the name like `./remote:'.
5071
 
5072

5073
File: gdb.info,  Node: Separate Debug Files,  Next: Symbol Errors,  Prev: Files,  Up: GDB Files
5074
 
5075
18.2 Debugging Information in Separate Files
5076
============================================
5077
 
5078
GDB allows you to put a program's debugging information in a file
5079
separate from the executable itself, in a way that allows GDB to find
5080
and load the debugging information automatically.  Since debugging
5081
information can be very large--sometimes larger than the executable
5082
code itself--some systems distribute debugging information for their
5083
executables in separate files, which users can install only when they
5084
need to debug a problem.
5085
 
5086
   GDB supports two ways of specifying the separate debug info file:
5087
 
5088
   * The executable contains a "debug link" that specifies the name of
5089
     the separate debug info file.  The separate debug file's name is
5090
     usually `EXECUTABLE.debug', where EXECUTABLE is the name of the
5091
     corresponding executable file without leading directories (e.g.,
5092
     `ls.debug' for `/usr/bin/ls').  In addition, the debug link
5093
     specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for
5094
     the debug file, which GDB uses to validate that the executable and
5095
     the debug file came from the same build.
5096
 
5097
   * The executable contains a "build ID", a unique bit string that is
5098
     also present in the corresponding debug info file.  (This is
5099
     supported only on some operating systems, notably those which use
5100
     the ELF format for binary files and the GNU Binutils.)  For more
5101
     details about this feature, see the description of the `--build-id'
5102
     command-line option in *Note Command Line Options:
5103
     (ld.info)Options.  The debug info file's name is not specified
5104
     explicitly by the build ID, but can be computed from the build ID,
5105
     see below.
5106
 
5107
   Depending on the way the debug info file is specified, GDB uses two
5108
different methods of looking for the debug file:
5109
 
5110
   * For the "debug link" method, GDB looks up the named file in the
5111
     directory of the executable file, then in a subdirectory of that
5112
     directory named `.debug', and finally under the global debug
5113
     directory, in a subdirectory whose name is identical to the leading
5114
     directories of the executable's absolute file name.
5115
 
5116
   * For the "build ID" method, GDB looks in the `.build-id'
5117
     subdirectory of the global debug directory for a file named
5118
     `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of
5119
     the build ID bit string, and NNNNNNNN are the rest of the bit
5120
     string.  (Real build ID strings are 32 or more hex characters, not
5121
     10.)
5122
 
5123
   So, for example, suppose you ask GDB to debug `/usr/bin/ls', which
5124
has a debug link that specifies the file `ls.debug', and a build ID
5125
whose value in hex is `abcdef1234'.  If the global debug directory is
5126
`/usr/lib/debug', then GDB will look for the following debug
5127
information files, in the indicated order:
5128
 
5129
   - `/usr/lib/debug/.build-id/ab/cdef1234.debug'
5130
 
5131
   - `/usr/bin/ls.debug'
5132
 
5133
   - `/usr/bin/.debug/ls.debug'
5134
 
5135
   - `/usr/lib/debug/usr/bin/ls.debug'.
5136
 
5137
   You can set the global debugging info directory's name, and view the
5138
name GDB is currently using.
5139
 
5140
`set debug-file-directory DIRECTORIES'
5141
     Set the directories which GDB searches for separate debugging
5142
     information files to DIRECTORY.  Multiple directory components can
5143
     be set concatenating them by a directory separator.
5144
 
5145
`show debug-file-directory'
5146
     Show the directories GDB searches for separate debugging
5147
     information files.
5148
 
5149
 
5150
   A debug link is a special section of the executable file named
5151
`.gnu_debuglink'.  The section must contain:
5152
 
5153
   * A filename, with any leading directory components removed,
5154
     followed by a zero byte,
5155
 
5156
   * zero to three bytes of padding, as needed to reach the next
5157
     four-byte boundary within the section, and
5158
 
5159
   * a four-byte CRC checksum, stored in the same endianness used for
5160
     the executable file itself.  The checksum is computed on the
5161
     debugging information file's full contents by the function given
5162
     below, passing zero as the CRC argument.
5163
 
5164
   Any executable file format can carry a debug link, as long as it can
5165
contain a section named `.gnu_debuglink' with the contents described
5166
above.
5167
 
5168
   The build ID is a special section in the executable file (and in
5169
other ELF binary files that GDB may consider).  This section is often
5170
named `.note.gnu.build-id', but that name is not mandatory.  It
5171
contains unique identification for the built files--the ID remains the
5172
same across multiple builds of the same build tree.  The default
5173
algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
5174
content for the build ID string.  The same section with an identical
5175
value is present in the original built binary with symbols, in its
5176
stripped variant, and in the separate debugging information file.
5177
 
5178
   The debugging information file itself should be an ordinary
5179
executable, containing a full set of linker symbols, sections, and
5180
debugging information.  The sections of the debugging information file
5181
should have the same names, addresses, and sizes as the original file,
5182
but they need not contain any data--much like a `.bss' section in an
5183
ordinary executable.
5184
 
5185
   The GNU binary utilities (Binutils) package includes the `objcopy'
5186
utility that can produce the separated executable / debugging
5187
information file pairs using the following commands:
5188
 
5189
     objcopy --only-keep-debug foo foo.debug
5190
     strip -g foo
5191
 
5192
These commands remove the debugging information from the executable
5193
file `foo' and place it in the file `foo.debug'.  You can use the
5194
first, second or both methods to link the two files:
5195
 
5196
   * The debug link method needs the following additional command to
5197
     also leave behind a debug link in `foo':
5198
 
5199
          objcopy --add-gnu-debuglink=foo.debug foo
5200
 
5201
     Ulrich Drepper's `elfutils' package, starting with version 0.53,
5202
     contains a version of the `strip' command such that the command
5203
     `strip foo -f foo.debug' has the same functionality as the two
5204
     `objcopy' commands and the `ln -s' command above, together.
5205
 
5206
   * Build ID gets embedded into the main executable using `ld
5207
     --build-id' or the GCC counterpart `gcc -Wl,--build-id'.  Build ID
5208
     support plus compatibility fixes for debug files separation are
5209
     present in GNU binary utilities (Binutils) package since version
5210
     2.18.
5211
 
5212
The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3
5213
using the polynomial:
5214
 
5215
      x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11
5216
      + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
5217
 
5218
   The function is computed byte at a time, taking the least
5219
significant bit of each byte first.  The initial pattern `0xffffffff'
5220
is used, to ensure leading zeros affect the CRC and the final result is
5221
inverted to ensure trailing zeros also affect the CRC.
5222
 
5223
   _Note:_ This is the same CRC polynomial as used in handling the
5224
"Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial
5225
Protocol: Remote Protocol.).  However in the case of the Remote Serial
5226
Protocol, the CRC is computed _most_ significant bit first, and the
5227
result is not inverted, so trailing zeros have no effect on the CRC
5228
value.
5229
 
5230
   To complete the description, we show below the code of the function
5231
which produces the CRC used in `.gnu_debuglink'.  Inverting the
5232
initially supplied `crc' argument means that an initial call to this
5233
function passing in zero will start computing the CRC using
5234
`0xffffffff'.
5235
 
5236
     unsigned long
5237
     gnu_debuglink_crc32 (unsigned long crc,
5238
                          unsigned char *buf, size_t len)
5239
     {
5240
       static const unsigned long crc32_table[256] =
5241
         {
5242
           0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
5243
           0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
5244
           0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
5245
           0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
5246
           0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
5247
           0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
5248
           0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
5249
           0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
5250
           0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
5251
           0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
5252
           0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
5253
           0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
5254
           0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
5255
           0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
5256
           0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
5257
           0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
5258
           0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
5259
           0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
5260
           0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
5261
           0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
5262
           0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
5263
           0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
5264
           0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
5265
           0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
5266
           0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
5267
           0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
5268
           0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
5269
           0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
5270
           0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
5271
           0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
5272
           0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
5273
           0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
5274
           0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
5275
           0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
5276
           0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
5277
           0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
5278
           0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
5279
           0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
5280
           0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
5281
           0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
5282
           0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
5283
           0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
5284
           0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
5285
           0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
5286
           0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
5287
           0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
5288
           0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
5289
           0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
5290
           0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
5291
           0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
5292
           0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
5293
           0x2d02ef8d
5294
         };
5295
       unsigned char *end;
5296
 
5297
       crc = ~crc & 0xffffffff;
5298
       for (end = buf + len; buf < end; ++buf)
5299
         crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
5300
       return ~crc & 0xffffffff;
5301
     }
5302
 
5303
This computation does not apply to the "build ID" method.
5304
 
5305

5306
File: gdb.info,  Node: Symbol Errors,  Next: Data Files,  Prev: Separate Debug Files,  Up: GDB Files
5307
 
5308
18.3 Errors Reading Symbol Files
5309
================================
5310
 
5311
While reading a symbol file, GDB occasionally encounters problems, such
5312
as symbol types it does not recognize, or known bugs in compiler
5313
output.  By default, GDB does not notify you of such problems, since
5314
they are relatively common and primarily of interest to people
5315
debugging compilers.  If you are interested in seeing information about
5316
ill-constructed symbol tables, you can either ask GDB to print only one
5317
message about each such type of problem, no matter how many times the
5318
problem occurs; or you can ask GDB to print more messages, to see how
5319
many times the problems occur, with the `set complaints' command (*note
5320
Optional Warnings and Messages: Messages/Warnings.).
5321
 
5322
   The messages currently printed, and their meanings, include:
5323
 
5324
`inner block not inside outer block in SYMBOL'
5325
     The symbol information shows where symbol scopes begin and end
5326
     (such as at the start of a function or a block of statements).
5327
     This error indicates that an inner scope block is not fully
5328
     contained in its outer scope blocks.
5329
 
5330
     GDB circumvents the problem by treating the inner block as if it
5331
     had the same scope as the outer block.  In the error message,
5332
     SYMBOL may be shown as "`(don't know)'" if the outer block is not a
5333
     function.
5334
 
5335
`block at ADDRESS out of order'
5336
     The symbol information for symbol scope blocks should occur in
5337
     order of increasing addresses.  This error indicates that it does
5338
     not do so.
5339
 
5340
     GDB does not circumvent this problem, and has trouble locating
5341
     symbols in the source file whose symbols it is reading.  (You can
5342
     often determine what source file is affected by specifying `set
5343
     verbose on'.  *Note Optional Warnings and Messages:
5344
     Messages/Warnings.)
5345
 
5346
`bad block start address patched'
5347
     The symbol information for a symbol scope block has a start address
5348
     smaller than the address of the preceding source line.  This is
5349
     known to occur in the SunOS 4.1.1 (and earlier) C compiler.
5350
 
5351
     GDB circumvents the problem by treating the symbol scope block as
5352
     starting on the previous source line.
5353
 
5354
`bad string table offset in symbol N'
5355
     Symbol number N contains a pointer into the string table which is
5356
     larger than the size of the string table.
5357
 
5358
     GDB circumvents the problem by considering the symbol to have the
5359
     name `foo', which may cause other problems if many symbols end up
5360
     with this name.
5361
 
5362
`unknown symbol type `0xNN''
5363
     The symbol information contains new data types that GDB does not
5364
     yet know how to read.  `0xNN' is the symbol type of the
5365
     uncomprehended information, in hexadecimal.
5366
 
5367
     GDB circumvents the error by ignoring this symbol information.
5368
     This usually allows you to debug your program, though certain
5369
     symbols are not accessible.  If you encounter such a problem and
5370
     feel like debugging it, you can debug `gdb' with itself, breakpoint
5371
     on `complain', then go up to the function `read_dbx_symtab' and
5372
     examine `*bufp' to see the symbol.
5373
 
5374
`stub type has NULL name'
5375
     GDB could not find the full definition for a struct or class.
5376
 
5377
`const/volatile indicator missing (ok if using g++ v1.x), got...'
5378
     The symbol information for a C++ member function is missing some
5379
     information that recent versions of the compiler should have
5380
     output for it.
5381
 
5382
`info mismatch between compiler and debugger'
5383
     GDB could not parse a type specification output by the compiler.
5384
 
5385
 
5386

5387
File: gdb.info,  Node: Data Files,  Prev: Symbol Errors,  Up: GDB Files
5388
 
5389
18.4 GDB Data Files
5390
===================
5391
 
5392
GDB will sometimes read an auxiliary data file.  These files are kept
5393
in a directory known as the "data directory".
5394
 
5395
   You can set the data directory's name, and view the name GDB is
5396
currently using.
5397
 
5398
`set data-directory DIRECTORY'
5399
     Set the directory which GDB searches for auxiliary data files to
5400
     DIRECTORY.
5401
 
5402
`show data-directory'
5403
     Show the directory GDB searches for auxiliary data files.
5404
 
5405
   You can set the default data directory by using the configure-time
5406
`--with-gdb-datadir' option.  If the data directory is inside GDB's
5407
configured binary prefix (set with `--prefix' or `--exec-prefix'), then
5408
the default data directory will be updated automatically if the
5409
installed GDB is moved to a new location.
5410
 
5411

5412
File: gdb.info,  Node: Targets,  Next: Remote Debugging,  Prev: GDB Files,  Up: Top
5413
 
5414
19 Specifying a Debugging Target
5415
********************************
5416
 
5417
A "target" is the execution environment occupied by your program.
5418
 
5419
   Often, GDB runs in the same host environment as your program; in
5420
that case, the debugging target is specified as a side effect when you
5421
use the `file' or `core' commands.  When you need more flexibility--for
5422
example, running GDB on a physically separate host, or controlling a
5423
standalone system over a serial port or a realtime system over a TCP/IP
5424
connection--you can use the `target' command to specify one of the
5425
target types configured for GDB (*note Commands for Managing Targets:
5426
Target Commands.).
5427
 
5428
   It is possible to build GDB for several different "target
5429
architectures".  When GDB is built like that, you can choose one of the
5430
available architectures with the `set architecture' command.
5431
 
5432
`set architecture ARCH'
5433
     This command sets the current target architecture to ARCH.  The
5434
     value of ARCH can be `"auto"', in addition to one of the supported
5435
     architectures.
5436
 
5437
`show architecture'
5438
     Show the current target architecture.
5439
 
5440
`set processor'
5441
`processor'
5442
     These are alias commands for, respectively, `set architecture' and
5443
     `show architecture'.
5444
 
5445
* Menu:
5446
 
5447
* Active Targets::              Active targets
5448
* Target Commands::             Commands for managing targets
5449
* Byte Order::                  Choosing target byte order
5450
 
5451

5452
File: gdb.info,  Node: Active Targets,  Next: Target Commands,  Up: Targets
5453
 
5454
19.1 Active Targets
5455
===================
5456
 
5457
There are three classes of targets: processes, core files, and
5458
executable files.  GDB can work concurrently on up to three active
5459
targets, one in each class.  This allows you to (for example) start a
5460
process and inspect its activity without abandoning your work on a core
5461
file.
5462
 
5463
   For example, if you execute `gdb a.out', then the executable file
5464
`a.out' is the only active target.  If you designate a core file as
5465
well--presumably from a prior run that crashed and coredumped--then GDB
5466
has two active targets and uses them in tandem, looking first in the
5467
corefile target, then in the executable file, to satisfy requests for
5468
memory addresses.  (Typically, these two classes of target are
5469
complementary, since core files contain only a program's read-write
5470
memory--variables and so on--plus machine status, while executable
5471
files contain only the program text and initialized data.)
5472
 
5473
   When you type `run', your executable file becomes an active process
5474
target as well.  When a process target is active, all GDB commands
5475
requesting memory addresses refer to that target; addresses in an
5476
active core file or executable file target are obscured while the
5477
process target is active.
5478
 
5479
   Use the `core-file' and `exec-file' commands to select a new core
5480
file or executable target (*note Commands to Specify Files: Files.).
5481
To specify as a target a process that is already running, use the
5482
`attach' command (*note Debugging an Already-running Process: Attach.).
5483
 
5484

5485
File: gdb.info,  Node: Target Commands,  Next: Byte Order,  Prev: Active Targets,  Up: Targets
5486
 
5487
19.2 Commands for Managing Targets
5488
==================================
5489
 
5490
`target TYPE PARAMETERS'
5491
     Connects the GDB host environment to a target machine or process.
5492
     A target is typically a protocol for talking to debugging
5493
     facilities.  You use the argument TYPE to specify the type or
5494
     protocol of the target machine.
5495
 
5496
     Further PARAMETERS are interpreted by the target protocol, but
5497
     typically include things like device names or host names to connect
5498
     with, process numbers, and baud rates.
5499
 
5500
     The `target' command does not repeat if you press  again
5501
     after executing the command.
5502
 
5503
`help target'
5504
     Displays the names of all targets available.  To display targets
5505
     currently selected, use either `info target' or `info files'
5506
     (*note Commands to Specify Files: Files.).
5507
 
5508
`help target NAME'
5509
     Describe a particular target, including any parameters necessary to
5510
     select it.
5511
 
5512
`set gnutarget ARGS'
5513
     GDB uses its own library BFD to read your files.  GDB knows
5514
     whether it is reading an "executable", a "core", or a ".o" file;
5515
     however, you can specify the file format with the `set gnutarget'
5516
     command.  Unlike most `target' commands, with `gnutarget' the
5517
     `target' refers to a program, not a machine.
5518
 
5519
          _Warning:_ To specify a file format with `set gnutarget', you
5520
          must know the actual BFD name.
5521
 
5522
     *Note Commands to Specify Files: Files.
5523
 
5524
`show gnutarget'
5525
     Use the `show gnutarget' command to display what file format
5526
     `gnutarget' is set to read.  If you have not set `gnutarget', GDB
5527
     will determine the file format for each file automatically, and
5528
     `show gnutarget' displays `The current BDF target is "auto"'.
5529
 
5530
   Here are some common targets (available, or not, depending on the GDB
5531
configuration):
5532
 
5533
`target exec PROGRAM'
5534
     An executable file.  `target exec PROGRAM' is the same as
5535
     `exec-file PROGRAM'.
5536
 
5537
`target core FILENAME'
5538
     A core dump file.  `target core FILENAME' is the same as
5539
     `core-file FILENAME'.
5540
 
5541
`target remote MEDIUM'
5542
     A remote system connected to GDB via a serial line or network
5543
     connection.  This command tells GDB to use its own remote protocol
5544
     over MEDIUM for debugging.  *Note Remote Debugging::.
5545
 
5546
     For example, if you have a board connected to `/dev/ttya' on the
5547
     machine running GDB, you could say:
5548
 
5549
          target remote /dev/ttya
5550
 
5551
     `target remote' supports the `load' command.  This is only useful
5552
     if you have some other way of getting the stub to the target
5553
     system, and you can put it somewhere in memory where it won't get
5554
     clobbered by the download.
5555
 
5556
`target sim'
5557
     Builtin CPU simulator.  GDB includes simulators for most
5558
     architectures.  In general,
5559
                  target sim
5560
                  load
5561
                  run
5562
     works; however, you cannot assume that a specific memory map,
5563
     device drivers, or even basic I/O is available, although some
5564
     simulators do provide these.  For info about any
5565
     processor-specific simulator details, see the appropriate section
5566
     in *Note Embedded Processors: Embedded Processors.
5567
 
5568
 
5569
   Some configurations may include these targets as well:
5570
 
5571
`target nrom DEV'
5572
     NetROM ROM emulator.  This target only supports downloading.
5573
 
5574
 
5575
   Different targets are available on different configurations of GDB;
5576
your configuration may have more or fewer targets.
5577
 
5578
   Many remote targets require you to download the executable's code
5579
once you've successfully established a connection.  You may wish to
5580
control various aspects of this process.
5581
 
5582
`set hash'
5583
     This command controls whether a hash mark `#' is displayed while
5584
     downloading a file to the remote monitor.  If on, a hash mark is
5585
     displayed after each S-record is successfully downloaded to the
5586
     monitor.
5587
 
5588
`show hash'
5589
     Show the current status of displaying the hash mark.
5590
 
5591
`set debug monitor'
5592
     Enable or disable display of communications messages between GDB
5593
     and the remote monitor.
5594
 
5595
`show debug monitor'
5596
     Show the current status of displaying communications between GDB
5597
     and the remote monitor.
5598
 
5599
`load FILENAME'
5600
     Depending on what remote debugging facilities are configured into
5601
     GDB, the `load' command may be available.  Where it exists, it is
5602
     meant to make FILENAME (an executable) available for debugging on
5603
     the remote system--by downloading, or dynamic linking, for example.
5604
     `load' also records the FILENAME symbol table in GDB, like the
5605
     `add-symbol-file' command.
5606
 
5607
     If your GDB does not have a `load' command, attempting to execute
5608
     it gets the error message "`You can't do that when your target is
5609
     ...'"
5610
 
5611
     The file is loaded at whatever address is specified in the
5612
     executable.  For some object file formats, you can specify the
5613
     load address when you link the program; for other formats, like
5614
     a.out, the object file format specifies a fixed address.
5615
 
5616
     Depending on the remote side capabilities, GDB may be able to load
5617
     programs into flash memory.
5618
 
5619
     `load' does not repeat if you press  again after using it.
5620
 
5621

5622
File: gdb.info,  Node: Byte Order,  Prev: Target Commands,  Up: Targets
5623
 
5624
19.3 Choosing Target Byte Order
5625
===============================
5626
 
5627
Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
5628
offer the ability to run either big-endian or little-endian byte
5629
orders.  Usually the executable or symbol will include a bit to
5630
designate the endian-ness, and you will not need to worry about which
5631
to use.  However, you may still find it useful to adjust GDB's idea of
5632
processor endian-ness manually.
5633
 
5634
`set endian big'
5635
     Instruct GDB to assume the target is big-endian.
5636
 
5637
`set endian little'
5638
     Instruct GDB to assume the target is little-endian.
5639
 
5640
`set endian auto'
5641
     Instruct GDB to use the byte order associated with the executable.
5642
 
5643
`show endian'
5644
     Display GDB's current idea of the target byte order.
5645
 
5646
 
5647
   Note that these commands merely adjust interpretation of symbolic
5648
data on the host, and that they have absolutely no effect on the target
5649
system.
5650
 
5651

5652
File: gdb.info,  Node: Remote Debugging,  Next: Configurations,  Prev: Targets,  Up: Top
5653
 
5654
20 Debugging Remote Programs
5655
****************************
5656
 
5657
If you are trying to debug a program running on a machine that cannot
5658
run GDB in the usual way, it is often useful to use remote debugging.
5659
For example, you might use remote debugging on an operating system
5660
kernel, or on a small system which does not have a general purpose
5661
operating system powerful enough to run a full-featured debugger.
5662
 
5663
   Some configurations of GDB have special serial or TCP/IP interfaces
5664
to make this work with particular debugging targets.  In addition, GDB
5665
comes with a generic serial protocol (specific to GDB, but not specific
5666
to any particular target system) which you can use if you write the
5667
remote stubs--the code that runs on the remote system to communicate
5668
with GDB.
5669
 
5670
   Other remote targets may be available in your configuration of GDB;
5671
use `help target' to list them.
5672
 
5673
* Menu:
5674
 
5675
* Connecting::                  Connecting to a remote target
5676
* File Transfer::               Sending files to a remote system
5677
* Server::                      Using the gdbserver program
5678
* Remote Configuration::        Remote configuration
5679
* Remote Stub::                 Implementing a remote stub
5680
 
5681

5682
File: gdb.info,  Node: Connecting,  Next: File Transfer,  Up: Remote Debugging
5683
 
5684
20.1 Connecting to a Remote Target
5685
==================================
5686
 
5687
On the GDB host machine, you will need an unstripped copy of your
5688
program, since GDB needs symbol and debugging information.  Start up
5689
GDB as usual, using the name of the local copy of your program as the
5690
first argument.
5691
 
5692
   GDB can communicate with the target over a serial line, or over an
5693
IP network using TCP or UDP.  In each case, GDB uses the same protocol
5694
for debugging your program; only the medium carrying the debugging
5695
packets varies.  The `target remote' command establishes a connection
5696
to the target.  Its arguments indicate which medium to use:
5697
 
5698
`target remote SERIAL-DEVICE'
5699
     Use SERIAL-DEVICE to communicate with the target.  For example, to
5700
     use a serial line connected to the device named `/dev/ttyb':
5701
 
5702
          target remote /dev/ttyb
5703
 
5704
     If you're using a serial line, you may want to give GDB the
5705
     `--baud' option, or use the `set remotebaud' command (*note set
5706
     remotebaud: Remote Configuration.) before the `target' command.
5707
 
5708
`target remote `HOST:PORT''
5709
`target remote `tcp:HOST:PORT''
5710
     Debug using a TCP connection to PORT on HOST.  The HOST may be
5711
     either a host name or a numeric IP address; PORT must be a decimal
5712
     number.  The HOST could be the target machine itself, if it is
5713
     directly connected to the net, or it might be a terminal server
5714
     which in turn has a serial line to the target.
5715
 
5716
     For example, to connect to port 2828 on a terminal server named
5717
     `manyfarms':
5718
 
5719
          target remote manyfarms:2828
5720
 
5721
     If your remote target is actually running on the same machine as
5722
     your debugger session (e.g. a simulator for your target running on
5723
     the same host), you can omit the hostname.  For example, to
5724
     connect to port 1234 on your local machine:
5725
 
5726
          target remote :1234
5727
     Note that the colon is still required here.
5728
 
5729
`target remote `udp:HOST:PORT''
5730
     Debug using UDP packets to PORT on HOST.  For example, to connect
5731
     to UDP port 2828 on a terminal server named `manyfarms':
5732
 
5733
          target remote udp:manyfarms:2828
5734
 
5735
     When using a UDP connection for remote debugging, you should keep
5736
     in mind that the `U' stands for "Unreliable".  UDP can silently
5737
     drop packets on busy or unreliable networks, which will cause
5738
     havoc with your debugging session.
5739
 
5740
`target remote | COMMAND'
5741
     Run COMMAND in the background and communicate with it using a
5742
     pipe.  The COMMAND is a shell command, to be parsed and expanded
5743
     by the system's command shell, `/bin/sh'; it should expect remote
5744
     protocol packets on its standard input, and send replies on its
5745
     standard output.  You could use this to run a stand-alone simulator
5746
     that speaks the remote debugging protocol, to make net connections
5747
     using programs like `ssh', or for other similar tricks.
5748
 
5749
     If COMMAND closes its standard output (perhaps by exiting), GDB
5750
     will try to send it a `SIGTERM' signal.  (If the program has
5751
     already exited, this will have no effect.)
5752
 
5753
 
5754
   Once the connection has been established, you can use all the usual
5755
commands to examine and change data.  The remote program is already
5756
running; you can use `step' and `continue', and you do not need to use
5757
`run'.
5758
 
5759
   Whenever GDB is waiting for the remote program, if you type the
5760
interrupt character (often `Ctrl-c'), GDB attempts to stop the program.
5761
This may or may not succeed, depending in part on the hardware and the
5762
serial drivers the remote system uses.  If you type the interrupt
5763
character once again, GDB displays this prompt:
5764
 
5765
     Interrupted while waiting for the program.
5766
     Give up (and stop debugging it)?  (y or n)
5767
 
5768
   If you type `y', GDB abandons the remote debugging session.  (If you
5769
decide you want to try again later, you can use `target remote' again
5770
to connect once more.)  If you type `n', GDB goes back to waiting.
5771
 
5772
`detach'
5773
     When you have finished debugging the remote program, you can use
5774
     the `detach' command to release it from GDB control.  Detaching
5775
     from the target normally resumes its execution, but the results
5776
     will depend on your particular remote stub.  After the `detach'
5777
     command, GDB is free to connect to another target.
5778
 
5779
`disconnect'
5780
     The `disconnect' command behaves like `detach', except that the
5781
     target is generally not resumed.  It will wait for GDB (this
5782
     instance or another one) to connect and continue debugging.  After
5783
     the `disconnect' command, GDB is again free to connect to another
5784
     target.
5785
 
5786
`monitor CMD'
5787
     This command allows you to send arbitrary commands directly to the
5788
     remote monitor.  Since GDB doesn't care about the commands it
5789
     sends like this, this command is the way to extend GDB--you can
5790
     add new commands that only the external monitor will understand
5791
     and implement.
5792
 
5793

5794
File: gdb.info,  Node: File Transfer,  Next: Server,  Prev: Connecting,  Up: Remote Debugging
5795
 
5796
20.2 Sending files to a remote system
5797
=====================================
5798
 
5799
Some remote targets offer the ability to transfer files over the same
5800
connection used to communicate with GDB.  This is convenient for
5801
targets accessible through other means, e.g. GNU/Linux systems running
5802
`gdbserver' over a network interface.  For other targets, e.g. embedded
5803
devices with only a single serial port, this may be the only way to
5804
upload or download files.
5805
 
5806
   Not all remote targets support these commands.
5807
 
5808
`remote put HOSTFILE TARGETFILE'
5809
     Copy file HOSTFILE from the host system (the machine running GDB)
5810
     to TARGETFILE on the target system.
5811
 
5812
`remote get TARGETFILE HOSTFILE'
5813
     Copy file TARGETFILE from the target system to HOSTFILE on the
5814
     host system.
5815
 
5816
`remote delete TARGETFILE'
5817
     Delete TARGETFILE from the target system.
5818
 
5819
 
5820

5821
File: gdb.info,  Node: Server,  Next: Remote Configuration,  Prev: File Transfer,  Up: Remote Debugging
5822
 
5823
20.3 Using the `gdbserver' Program
5824
==================================
5825
 
5826
`gdbserver' is a control program for Unix-like systems, which allows
5827
you to connect your program with a remote GDB via `target remote'--but
5828
without linking in the usual debugging stub.
5829
 
5830
   `gdbserver' is not a complete replacement for the debugging stubs,
5831
because it requires essentially the same operating-system facilities
5832
that GDB itself does.  In fact, a system that can run `gdbserver' to
5833
connect to a remote GDB could also run GDB locally!  `gdbserver' is
5834
sometimes useful nevertheless, because it is a much smaller program
5835
than GDB itself.  It is also easier to port than all of GDB, so you may
5836
be able to get started more quickly on a new system by using
5837
`gdbserver'.  Finally, if you develop code for real-time systems, you
5838
may find that the tradeoffs involved in real-time operation make it
5839
more convenient to do as much development work as possible on another
5840
system, for example by cross-compiling.  You can use `gdbserver' to
5841
make a similar choice for debugging.
5842
 
5843
   GDB and `gdbserver' communicate via either a serial line or a TCP
5844
connection, using the standard GDB remote serial protocol.
5845
 
5846
     _Warning:_ `gdbserver' does not have any built-in security.  Do
5847
     not run `gdbserver' connected to any public network; a GDB
5848
     connection to `gdbserver' provides access to the target system
5849
     with the same privileges as the user running `gdbserver'.
5850
 
5851
20.3.1 Running `gdbserver'
5852
--------------------------
5853
 
5854
Run `gdbserver' on the target system.  You need a copy of the program
5855
you want to debug, including any libraries it requires.  `gdbserver'
5856
does not need your program's symbol table, so you can strip the program
5857
if necessary to save space.  GDB on the host system does all the symbol
5858
handling.
5859
 
5860
   To use the server, you must tell it how to communicate with GDB; the
5861
name of your program; and the arguments for your program.  The usual
5862
syntax is:
5863
 
5864
     target> gdbserver COMM PROGRAM [ ARGS ... ]
5865
 
5866
   COMM is either a device name (to use a serial line) or a TCP
5867
hostname and portnumber.  For example, to debug Emacs with the argument
5868
`foo.txt' and communicate with GDB over the serial port `/dev/com1':
5869
 
5870
     target> gdbserver /dev/com1 emacs foo.txt
5871
 
5872
   `gdbserver' waits passively for the host GDB to communicate with it.
5873
 
5874
   To use a TCP connection instead of a serial line:
5875
 
5876
     target> gdbserver host:2345 emacs foo.txt
5877
 
5878
   The only difference from the previous example is the first argument,
5879
specifying that you are communicating with the host GDB via TCP.  The
5880
`host:2345' argument means that `gdbserver' is to expect a TCP
5881
connection from machine `host' to local TCP port 2345.  (Currently, the
5882
`host' part is ignored.)  You can choose any number you want for the
5883
port number as long as it does not conflict with any TCP ports already
5884
in use on the target system (for example, `23' is reserved for
5885
`telnet').(1)  You must use the same port number with the host GDB
5886
`target remote' command.
5887
 
5888
20.3.1.1 Attaching to a Running Program
5889
.......................................
5890
 
5891
On some targets, `gdbserver' can also attach to running programs.  This
5892
is accomplished via the `--attach' argument.  The syntax is:
5893
 
5894
     target> gdbserver --attach COMM PID
5895
 
5896
   PID is the process ID of a currently running process.  It isn't
5897
necessary to point `gdbserver' at a binary for the running process.
5898
 
5899
   You can debug processes by name instead of process ID if your target
5900
has the `pidof' utility:
5901
 
5902
     target> gdbserver --attach COMM `pidof PROGRAM`
5903
 
5904
   In case more than one copy of PROGRAM is running, or PROGRAM has
5905
multiple threads, most versions of `pidof' support the `-s' option to
5906
only return the first process ID.
5907
 
5908
20.3.1.2 Multi-Process Mode for `gdbserver'
5909
...........................................
5910
 
5911
When you connect to `gdbserver' using `target remote', `gdbserver'
5912
debugs the specified program only once.  When the program exits, or you
5913
detach from it, GDB closes the connection and `gdbserver' exits.
5914
 
5915
   If you connect using `target extended-remote', `gdbserver' enters
5916
multi-process mode.  When the debugged program exits, or you detach
5917
from it, GDB stays connected to `gdbserver' even though no program is
5918
running.  The `run' and `attach' commands instruct `gdbserver' to run
5919
or attach to a new program.  The `run' command uses `set remote
5920
exec-file' (*note set remote exec-file::) to select the program to run.
5921
Command line arguments are supported, except for wildcard expansion
5922
and I/O redirection (*note Arguments::).
5923
 
5924
   To start `gdbserver' without supplying an initial command to run or
5925
process ID to attach, use the `--multi' command line option.  Then you
5926
can connect using `target extended-remote' and start the program you
5927
want to debug.
5928
 
5929
   `gdbserver' does not automatically exit in multi-process mode.  You
5930
can terminate it by using `monitor exit' (*note Monitor Commands for
5931
gdbserver::).
5932
 
5933
20.3.1.3 Other Command-Line Arguments for `gdbserver'
5934
.....................................................
5935
 
5936
The `--debug' option tells `gdbserver' to display extra status
5937
information about the debugging process.  The `--remote-debug' option
5938
tells `gdbserver' to display remote protocol debug output.  These
5939
options are intended for `gdbserver' development and for bug reports to
5940
the developers.
5941
 
5942
   The `--wrapper' option specifies a wrapper to launch programs for
5943
debugging.  The option should be followed by the name of the wrapper,
5944
then any command-line arguments to pass to the wrapper, then `--'
5945
indicating the end of the wrapper arguments.
5946
 
5947
   `gdbserver' runs the specified wrapper program with a combined
5948
command line including the wrapper arguments, then the name of the
5949
program to debug, then any arguments to the program.  The wrapper runs
5950
until it executes your program, and then GDB gains control.
5951
 
5952
   You can use any program that eventually calls `execve' with its
5953
arguments as a wrapper.  Several standard Unix utilities do this, e.g.
5954
`env' and `nohup'.  Any Unix shell script ending with `exec "$@"' will
5955
also work.
5956
 
5957
   For example, you can use `env' to pass an environment variable to
5958
the debugged program, without setting the variable in `gdbserver''s
5959
environment:
5960
 
5961
     $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
5962
 
5963
20.3.2 Connecting to `gdbserver'
5964
--------------------------------
5965
 
5966
Run GDB on the host system.
5967
 
5968
   First make sure you have the necessary symbol files.  Load symbols
5969
for your application using the `file' command before you connect.  Use
5970
`set sysroot' to locate target libraries (unless your GDB was compiled
5971
with the correct sysroot using `--with-sysroot').
5972
 
5973
   The symbol file and target libraries must exactly match the
5974
executable and libraries on the target, with one exception: the files
5975
on the host system should not be stripped, even if the files on the
5976
target system are.  Mismatched or missing files will lead to confusing
5977
results during debugging.  On GNU/Linux targets, mismatched or missing
5978
files may also prevent `gdbserver' from debugging multi-threaded
5979
programs.
5980
 
5981
   Connect to your target (*note Connecting to a Remote Target:
5982
Connecting.).  For TCP connections, you must start up `gdbserver' prior
5983
to using the `target remote' command.  Otherwise you may get an error
5984
whose text depends on the host system, but which usually looks
5985
something like `Connection refused'.  Don't use the `load' command in
5986
GDB when using `gdbserver', since the program is already on the target.
5987
 
5988
20.3.3 Monitor Commands for `gdbserver'
5989
---------------------------------------
5990
 
5991
During a GDB session using `gdbserver', you can use the `monitor'
5992
command to send special requests to `gdbserver'.  Here are the
5993
available commands.
5994
 
5995
`monitor help'
5996
     List the available monitor commands.
5997
 
5998
`monitor set debug 0'
5999
`monitor set debug 1'
6000
     Disable or enable general debugging messages.
6001
 
6002
`monitor set remote-debug 0'
6003
`monitor set remote-debug 1'
6004
     Disable or enable specific debugging messages associated with the
6005
     remote protocol (*note Remote Protocol::).
6006
 
6007
`monitor set libthread-db-search-path [PATH]'
6008
     When this command is issued, PATH is a colon-separated list of
6009
     directories to search for `libthread_db' (*note set
6010
     libthread-db-search-path: Threads.).  If you omit PATH,
6011
     `libthread-db-search-path' will be reset to an empty list.
6012
 
6013
`monitor exit'
6014
     Tell gdbserver to exit immediately.  This command should be
6015
     followed by `disconnect' to close the debugging session.
6016
     `gdbserver' will detach from any attached processes and kill any
6017
     processes it created.  Use `monitor exit' to terminate `gdbserver'
6018
     at the end of a multi-process mode debug session.
6019
 
6020
 
6021
   ---------- Footnotes ----------
6022
 
6023
   (1) If you choose a port number that conflicts with another service,
6024
`gdbserver' prints an error message and exits.
6025
 
6026

6027
File: gdb.info,  Node: Remote Configuration,  Next: Remote Stub,  Prev: Server,  Up: Remote Debugging
6028
 
6029
20.4 Remote Configuration
6030
=========================
6031
 
6032
This section documents the configuration options available when
6033
debugging remote programs.  For the options related to the File I/O
6034
extensions of the remote protocol, see *Note system-call-allowed:
6035
system.
6036
 
6037
`set remoteaddresssize BITS'
6038
     Set the maximum size of address in a memory packet to the specified
6039
     number of bits.  GDB will mask off the address bits above that
6040
     number, when it passes addresses to the remote target.  The
6041
     default value is the number of bits in the target's address.
6042
 
6043
`show remoteaddresssize'
6044
     Show the current value of remote address size in bits.
6045
 
6046
`set remotebaud N'
6047
     Set the baud rate for the remote serial I/O to N baud.  The value
6048
     is used to set the speed of the serial port used for debugging
6049
     remote targets.
6050
 
6051
`show remotebaud'
6052
     Show the current speed of the remote connection.
6053
 
6054
`set remotebreak'
6055
     If set to on, GDB sends a `BREAK' signal to the remote when you
6056
     type `Ctrl-c' to interrupt the program running on the remote.  If
6057
     set to off, GDB sends the `Ctrl-C' character instead.  The default
6058
     is off, since most remote systems expect to see `Ctrl-C' as the
6059
     interrupt signal.
6060
 
6061
`show remotebreak'
6062
     Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote
6063
     program.
6064
 
6065
`set remoteflow on'
6066
`set remoteflow off'
6067
     Enable or disable hardware flow control (`RTS'/`CTS') on the
6068
     serial port used to communicate to the remote target.
6069
 
6070
`show remoteflow'
6071
     Show the current setting of hardware flow control.
6072
 
6073
`set remotelogbase BASE'
6074
     Set the base (a.k.a. radix) of logging serial protocol
6075
     communications to BASE.  Supported values of BASE are: `ascii',
6076
     `octal', and `hex'.  The default is `ascii'.
6077
 
6078
`show remotelogbase'
6079
     Show the current setting of the radix for logging remote serial
6080
     protocol.
6081
 
6082
`set remotelogfile FILE'
6083
     Record remote serial communications on the named FILE.  The
6084
     default is not to record at all.
6085
 
6086
`show remotelogfile.'
6087
     Show the current setting  of the file name on which to record the
6088
     serial communications.
6089
 
6090
`set remotetimeout NUM'
6091
     Set the timeout limit to wait for the remote target to respond to
6092
     NUM seconds.  The default is 2 seconds.
6093
 
6094
`show remotetimeout'
6095
     Show the current number of seconds to wait for the remote target
6096
     responses.
6097
 
6098
`set remote hardware-watchpoint-limit LIMIT'
6099
`set remote hardware-breakpoint-limit LIMIT'
6100
     Restrict GDB to using LIMIT remote hardware breakpoint or
6101
     watchpoints.  A limit of -1, the default, is treated as unlimited.
6102
 
6103
`set remote exec-file FILENAME'
6104
`show remote exec-file'
6105
     Select the file used for `run' with `target extended-remote'.
6106
     This should be set to a filename valid on the target system.  If
6107
     it is not set, the target will use a default filename (e.g. the
6108
     last program run).
6109
 
6110
`set remote interrupt-sequence'
6111
     Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g'
6112
     as the sequence to the remote target in order to interrupt the
6113
     execution.  `Ctrl-C' is a default.  Some system prefers `BREAK'
6114
     which is high level of serial line for some certain time.  Linux
6115
     kernel prefers `BREAK-g', a.k.a Magic SysRq g.  It is `BREAK'
6116
     signal followed by character `g'.
6117
 
6118
`show interrupt-sequence'
6119
     Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to
6120
     interrupt the remote program.  `BREAK-g' is BREAK signal followed
6121
     by `g' and also known as Magic SysRq g.
6122
 
6123
`set remote interrupt-on-connect'
6124
     Specify whether interrupt-sequence is sent to remote target when
6125
     GDB connects to it.  This is mostly needed when you debug Linux
6126
     kernel.  Linux kernel expects `BREAK' followed by `g' which is
6127
     known as Magic SysRq g in order to connect GDB.
6128
 
6129
`show interrupt-on-connect'
6130
     Show whether interrupt-sequence is sent to remote target when GDB
6131
     connects to it.
6132
 
6133
`set tcp auto-retry on'
6134
     Enable auto-retry for remote TCP connections.  This is useful if
6135
     the remote debugging agent is launched in parallel with GDB; there
6136
     is a race condition because the agent may not become ready to
6137
     accept the connection before GDB attempts to connect.  When
6138
     auto-retry is enabled, if the initial attempt to connect fails,
6139
     GDB reattempts to establish the connection using the timeout
6140
     specified by `set tcp connect-timeout'.
6141
 
6142
`set tcp auto-retry off'
6143
     Do not auto-retry failed TCP connections.
6144
 
6145
`show tcp auto-retry'
6146
     Show the current auto-retry setting.
6147
 
6148
`set tcp connect-timeout SECONDS'
6149
     Set the timeout for establishing a TCP connection to the remote
6150
     target to SECONDS.  The timeout affects both polling to retry
6151
     failed connections (enabled by `set tcp auto-retry on') and
6152
     waiting for connections that are merely slow to complete, and
6153
     represents an approximate cumulative value.
6154
 
6155
`show tcp connect-timeout'
6156
     Show the current connection timeout setting.
6157
 
6158
   The GDB remote protocol autodetects the packets supported by your
6159
debugging stub.  If you need to override the autodetection, you can use
6160
these commands to enable or disable individual packets.  Each packet
6161
can be set to `on' (the remote target supports this packet), `off' (the
6162
remote target does not support this packet), or `auto' (detect remote
6163
target support for this packet).  They all default to `auto'.  For more
6164
information about each packet, see *Note Remote Protocol::.
6165
 
6166
   During normal use, you should not have to use any of these commands.
6167
If you do, that may be a bug in your remote debugging stub, or a bug in
6168
GDB.  You may want to report the problem to the GDB developers.
6169
 
6170
   For each packet NAME, the command to enable or disable the packet is
6171
`set remote NAME-packet'.  The available settings are:
6172
 
6173
Command Name         Remote Packet           Related Features
6174
`fetch-register'     `p'                     `info registers'
6175
`set-register'       `P'                     `set'
6176
`binary-download'    `X'                     `load', `set'
6177
`read-aux-vector'    `qXfer:auxv:read'       `info auxv'
6178
`symbol-lookup'      `qSymbol'               Detecting
6179
                                             multiple threads
6180
`attach'             `vAttach'               `attach'
6181
`verbose-resume'     `vCont'                 Stepping or
6182
                                             resuming multiple
6183
                                             threads
6184
`run'                `vRun'                  `run'
6185
`software-breakpoint'`Z0'                    `break'
6186
`hardware-breakpoint'`Z1'                    `hbreak'
6187
`write-watchpoint'   `Z2'                    `watch'
6188
`read-watchpoint'    `Z3'                    `rwatch'
6189
`access-watchpoint'  `Z4'                    `awatch'
6190
`target-features'    `qXfer:features:read'   `set architecture'
6191
`library-info'       `qXfer:libraries:read'  `info
6192
                                             sharedlibrary'
6193
`memory-map'         `qXfer:memory-map:read' `info mem'
6194
`read-spu-object'    `qXfer:spu:read'        `info spu'
6195
`write-spu-object'   `qXfer:spu:write'       `info spu'
6196
`read-siginfo-object'`qXfer:siginfo:read'    `print $_siginfo'
6197
`write-siginfo-object'`qXfer:siginfo:write'   `set $_siginfo'
6198
`threads'            `qXfer:threads:read'    `info threads'
6199
`get-thread-local-   `qGetTLSAddr'           Displaying
6200
storage-address'                             `__thread'
6201
                                             variables
6202
`search-memory'      `qSearch:memory'        `find'
6203
`supported-packets'  `qSupported'            Remote
6204
                                             communications
6205
                                             parameters
6206
`pass-signals'       `QPassSignals'          `handle SIGNAL'
6207
`hostio-close-packet'`vFile:close'           `remote get',
6208
                                             `remote put'
6209
`hostio-open-packet' `vFile:open'            `remote get',
6210
                                             `remote put'
6211
`hostio-pread-packet'`vFile:pread'           `remote get',
6212
                                             `remote put'
6213
`hostio-pwrite-packet'`vFile:pwrite'          `remote get',
6214
                                             `remote put'
6215
`hostio-unlink-packet'`vFile:unlink'          `remote delete'
6216
`noack-packet'       `QStartNoAckMode'       Packet
6217
                                             acknowledgment
6218
`osdata'             `qXfer:osdata:read'     `info os'
6219
`query-attached'     `qAttached'             Querying remote
6220
                                             process attach
6221
                                             state.
6222
 
6223

6224
File: gdb.info,  Node: Remote Stub,  Prev: Remote Configuration,  Up: Remote Debugging
6225
 
6226
20.5 Implementing a Remote Stub
6227
===============================
6228
 
6229
The stub files provided with GDB implement the target side of the
6230
communication protocol, and the GDB side is implemented in the GDB
6231
source file `remote.c'.  Normally, you can simply allow these
6232
subroutines to communicate, and ignore the details.  (If you're
6233
implementing your own stub file, you can still ignore the details: start
6234
with one of the existing stub files.  `sparc-stub.c' is the best
6235
organized, and therefore the easiest to read.)
6236
 
6237
   To debug a program running on another machine (the debugging
6238
"target" machine), you must first arrange for all the usual
6239
prerequisites for the program to run by itself.  For example, for a C
6240
program, you need:
6241
 
6242
  1. A startup routine to set up the C runtime environment; these
6243
     usually have a name like `crt0'.  The startup routine may be
6244
     supplied by your hardware supplier, or you may have to write your
6245
     own.
6246
 
6247
  2. A C subroutine library to support your program's subroutine calls,
6248
     notably managing input and output.
6249
 
6250
  3. A way of getting your program to the other machine--for example, a
6251
     download program.  These are often supplied by the hardware
6252
     manufacturer, but you may have to write your own from hardware
6253
     documentation.
6254
 
6255
   The next step is to arrange for your program to use a serial port to
6256
communicate with the machine where GDB is running (the "host" machine).
6257
In general terms, the scheme looks like this:
6258
 
6259
_On the host,_
6260
     GDB already understands how to use this protocol; when everything
6261
     else is set up, you can simply use the `target remote' command
6262
     (*note Specifying a Debugging Target: Targets.).
6263
 
6264
_On the target,_
6265
     you must link with your program a few special-purpose subroutines
6266
     that implement the GDB remote serial protocol.  The file
6267
     containing these subroutines is called  a "debugging stub".
6268
 
6269
     On certain remote targets, you can use an auxiliary program
6270
     `gdbserver' instead of linking a stub into your program.  *Note
6271
     Using the `gdbserver' Program: Server, for details.
6272
 
6273
   The debugging stub is specific to the architecture of the remote
6274
machine; for example, use `sparc-stub.c' to debug programs on SPARC
6275
boards.
6276
 
6277
   These working remote stubs are distributed with GDB:
6278
 
6279
`i386-stub.c'
6280
     For Intel 386 and compatible architectures.
6281
 
6282
`m68k-stub.c'
6283
     For Motorola 680x0 architectures.
6284
 
6285
`sh-stub.c'
6286
     For Renesas SH architectures.
6287
 
6288
`sparc-stub.c'
6289
     For SPARC architectures.
6290
 
6291
`sparcl-stub.c'
6292
     For Fujitsu SPARCLITE architectures.
6293
 
6294
 
6295
   The `README' file in the GDB distribution may list other recently
6296
added stubs.
6297
 
6298
* Menu:
6299
 
6300
* Stub Contents::       What the stub can do for you
6301
* Bootstrapping::       What you must do for the stub
6302
* Debug Session::       Putting it all together
6303
 
6304

6305
File: gdb.info,  Node: Stub Contents,  Next: Bootstrapping,  Up: Remote Stub
6306
 
6307
20.5.1 What the Stub Can Do for You
6308
-----------------------------------
6309
 
6310
The debugging stub for your architecture supplies these three
6311
subroutines:
6312
 
6313
`set_debug_traps'
6314
     This routine arranges for `handle_exception' to run when your
6315
     program stops.  You must call this subroutine explicitly near the
6316
     beginning of your program.
6317
 
6318
`handle_exception'
6319
     This is the central workhorse, but your program never calls it
6320
     explicitly--the setup code arranges for `handle_exception' to run
6321
     when a trap is triggered.
6322
 
6323
     `handle_exception' takes control when your program stops during
6324
     execution (for example, on a breakpoint), and mediates
6325
     communications with GDB on the host machine.  This is where the
6326
     communications protocol is implemented; `handle_exception' acts as
6327
     the GDB representative on the target machine.  It begins by
6328
     sending summary information on the state of your program, then
6329
     continues to execute, retrieving and transmitting any information
6330
     GDB needs, until you execute a GDB command that makes your program
6331
     resume; at that point, `handle_exception' returns control to your
6332
     own code on the target machine.
6333
 
6334
`breakpoint'
6335
     Use this auxiliary subroutine to make your program contain a
6336
     breakpoint.  Depending on the particular situation, this may be
6337
     the only way for GDB to get control.  For instance, if your target
6338
     machine has some sort of interrupt button, you won't need to call
6339
     this; pressing the interrupt button transfers control to
6340
     `handle_exception'--in effect, to GDB.  On some machines, simply
6341
     receiving characters on the serial port may also trigger a trap;
6342
     again, in that situation, you don't need to call `breakpoint' from
6343
     your own program--simply running `target remote' from the host GDB
6344
     session gets control.
6345
 
6346
     Call `breakpoint' if none of these is true, or if you simply want
6347
     to make certain your program stops at a predetermined point for the
6348
     start of your debugging session.
6349
 
6350

6351
File: gdb.info,  Node: Bootstrapping,  Next: Debug Session,  Prev: Stub Contents,  Up: Remote Stub
6352
 
6353
20.5.2 What You Must Do for the Stub
6354
------------------------------------
6355
 
6356
The debugging stubs that come with GDB are set up for a particular chip
6357
architecture, but they have no information about the rest of your
6358
debugging target machine.
6359
 
6360
   First of all you need to tell the stub how to communicate with the
6361
serial port.
6362
 
6363
`int getDebugChar()'
6364
     Write this subroutine to read a single character from the serial
6365
     port.  It may be identical to `getchar' for your target system; a
6366
     different name is used to allow you to distinguish the two if you
6367
     wish.
6368
 
6369
`void putDebugChar(int)'
6370
     Write this subroutine to write a single character to the serial
6371
     port.  It may be identical to `putchar' for your target system; a
6372
     different name is used to allow you to distinguish the two if you
6373
     wish.
6374
 
6375
   If you want GDB to be able to stop your program while it is running,
6376
you need to use an interrupt-driven serial driver, and arrange for it
6377
to stop when it receives a `^C' (`\003', the control-C character).
6378
That is the character which GDB uses to tell the remote system to stop.
6379
 
6380
   Getting the debugging target to return the proper status to GDB
6381
probably requires changes to the standard stub; one quick and dirty way
6382
is to just execute a breakpoint instruction (the "dirty" part is that
6383
GDB reports a `SIGTRAP' instead of a `SIGINT').
6384
 
6385
   Other routines you need to supply are:
6386
 
6387
`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
6388
     Write this function to install EXCEPTION_ADDRESS in the exception
6389
     handling tables.  You need to do this because the stub does not
6390
     have any way of knowing what the exception handling tables on your
6391
     target system are like (for example, the processor's table might
6392
     be in ROM, containing entries which point to a table in RAM).
6393
     EXCEPTION_NUMBER is the exception number which should be changed;
6394
     its meaning is architecture-dependent (for example, different
6395
     numbers might represent divide by zero, misaligned access, etc).
6396
     When this exception occurs, control should be transferred directly
6397
     to EXCEPTION_ADDRESS, and the processor state (stack, registers,
6398
     and so on) should be just as it is when a processor exception
6399
     occurs.  So if you want to use a jump instruction to reach
6400
     EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
6401
     subroutine.
6402
 
6403
     For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
6404
     gate so that interrupts are masked while the handler runs.  The
6405
     gate should be at privilege level 0 (the most privileged level).
6406
     The SPARC and 68k stubs are able to mask interrupts themselves
6407
     without help from `exceptionHandler'.
6408
 
6409
`void flush_i_cache()'
6410
     On SPARC and SPARCLITE only, write this subroutine to flush the
6411
     instruction cache, if any, on your target machine.  If there is no
6412
     instruction cache, this subroutine may be a no-op.
6413
 
6414
     On target machines that have instruction caches, GDB requires this
6415
     function to make certain that the state of your program is stable.
6416
 
6417
You must also make sure this library routine is available:
6418
 
6419
`void *memset(void *, int, int)'
6420
     This is the standard library function `memset' that sets an area of
6421
     memory to a known value.  If you have one of the free versions of
6422
     `libc.a', `memset' can be found there; otherwise, you must either
6423
     obtain it from your hardware manufacturer, or write your own.
6424
 
6425
   If you do not use the GNU C compiler, you may need other standard
6426
library subroutines as well; this varies from one stub to another, but
6427
in general the stubs are likely to use any of the common library
6428
subroutines which `GCC' generates as inline code.
6429
 
6430

6431
File: gdb.info,  Node: Debug Session,  Prev: Bootstrapping,  Up: Remote Stub
6432
 
6433
20.5.3 Putting it All Together
6434
------------------------------
6435
 
6436
In summary, when your program is ready to debug, you must follow these
6437
steps.
6438
 
6439
  1. Make sure you have defined the supporting low-level routines
6440
     (*note What You Must Do for the Stub: Bootstrapping.):
6441
          `getDebugChar', `putDebugChar',
6442
          `flush_i_cache', `memset', `exceptionHandler'.
6443
 
6444
  2. Insert these lines near the top of your program:
6445
 
6446
          set_debug_traps();
6447
          breakpoint();
6448
 
6449
  3. For the 680x0 stub only, you need to provide a variable called
6450
     `exceptionHook'.  Normally you just use:
6451
 
6452
          void (*exceptionHook)() = 0;
6453
 
6454
     but if before calling `set_debug_traps', you set it to point to a
6455
     function in your program, that function is called when `GDB'
6456
     continues after stopping on a trap (for example, bus error).  The
6457
     function indicated by `exceptionHook' is called with one
6458
     parameter: an `int' which is the exception number.
6459
 
6460
  4. Compile and link together: your program, the GDB debugging stub for
6461
     your target architecture, and the supporting subroutines.
6462
 
6463
  5. Make sure you have a serial connection between your target machine
6464
     and the GDB host, and identify the serial port on the host.
6465
 
6466
  6. Download your program to your target machine (or get it there by
6467
     whatever means the manufacturer provides), and start it.
6468
 
6469
  7. Start GDB on the host, and connect to the target (*note Connecting
6470
     to a Remote Target: Connecting.).
6471
 
6472
 
6473

6474
File: gdb.info,  Node: Configurations,  Next: Controlling GDB,  Prev: Remote Debugging,  Up: Top
6475
 
6476
21 Configuration-Specific Information
6477
*************************************
6478
 
6479
While nearly all GDB commands are available for all native and cross
6480
versions of the debugger, there are some exceptions.  This chapter
6481
describes things that are only available in certain configurations.
6482
 
6483
   There are three major categories of configurations: native
6484
configurations, where the host and target are the same, embedded
6485
operating system configurations, which are usually the same for several
6486
different processor architectures, and bare embedded processors, which
6487
are quite different from each other.
6488
 
6489
* Menu:
6490
 
6491
* Native::
6492
* Embedded OS::
6493
* Embedded Processors::
6494
* Architectures::
6495
 
6496

6497
File: gdb.info,  Node: Native,  Next: Embedded OS,  Up: Configurations
6498
 
6499
21.1 Native
6500
===========
6501
 
6502
This section describes details specific to particular native
6503
configurations.
6504
 
6505
* Menu:
6506
 
6507
* HP-UX::                       HP-UX
6508
* BSD libkvm Interface::        Debugging BSD kernel memory images
6509
* SVR4 Process Information::    SVR4 process information
6510
* DJGPP Native::                Features specific to the DJGPP port
6511
* Cygwin Native::               Features specific to the Cygwin port
6512
* Hurd Native::                 Features specific to GNU Hurd
6513
* Neutrino::                    Features specific to QNX Neutrino
6514
* Darwin::                      Features specific to Darwin
6515
 
6516

6517
File: gdb.info,  Node: HP-UX,  Next: BSD libkvm Interface,  Up: Native
6518
 
6519
21.1.1 HP-UX
6520
------------
6521
 
6522
On HP-UX systems, if you refer to a function or variable name that
6523
begins with a dollar sign, GDB searches for a user or system name
6524
first, before it searches for a convenience variable.
6525
 
6526

6527
File: gdb.info,  Node: BSD libkvm Interface,  Next: SVR4 Process Information,  Prev: HP-UX,  Up: Native
6528
 
6529
21.1.2 BSD libkvm Interface
6530
---------------------------
6531
 
6532
BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
6533
interface that provides a uniform interface for accessing kernel virtual
6534
memory images, including live systems and crash dumps.  GDB uses this
6535
interface to allow you to debug live kernels and kernel crash dumps on
6536
many native BSD configurations.  This is implemented as a special `kvm'
6537
debugging target.  For debugging a live system, load the currently
6538
running kernel into GDB and connect to the `kvm' target:
6539
 
6540
     (gdb) target kvm
6541
 
6542
   For debugging crash dumps, provide the file name of the crash dump
6543
as an argument:
6544
 
6545
     (gdb) target kvm /var/crash/bsd.0
6546
 
6547
   Once connected to the `kvm' target, the following commands are
6548
available:
6549
 
6550
`kvm pcb'
6551
     Set current context from the "Process Control Block" (PCB) address.
6552
 
6553
`kvm proc'
6554
     Set current context from proc address.  This command isn't
6555
     available on modern FreeBSD systems.
6556
 
6557

6558
File: gdb.info,  Node: SVR4 Process Information,  Next: DJGPP Native,  Prev: BSD libkvm Interface,  Up: Native
6559
 
6560
21.1.3 SVR4 Process Information
6561
-------------------------------
6562
 
6563
Many versions of SVR4 and compatible systems provide a facility called
6564
`/proc' that can be used to examine the image of a running process
6565
using file-system subroutines.  If GDB is configured for an operating
6566
system with this facility, the command `info proc' is available to
6567
report information about the process running your program, or about any
6568
process running on your system.  `info proc' works only on SVR4 systems
6569
that include the `procfs' code.  This includes, as of this writing,
6570
GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
6571
HP-UX, for example.
6572
 
6573
`info proc'
6574
`info proc PROCESS-ID'
6575
     Summarize available information about any running process.  If a
6576
     process ID is specified by PROCESS-ID, display information about
6577
     that process; otherwise display information about the program being
6578
     debugged.  The summary includes the debugged process ID, the
6579
     command line used to invoke it, its current working directory, and
6580
     its executable file's absolute file name.
6581
 
6582
     On some systems, PROCESS-ID can be of the form `[PID]/TID' which
6583
     specifies a certain thread ID within a process.  If the optional
6584
     PID part is missing, it means a thread from the process being
6585
     debugged (the leading `/' still needs to be present, or else GDB
6586
     will interpret the number as a process ID rather than a thread ID).
6587
 
6588
`info proc mappings'
6589
     Report the memory address space ranges accessible in the program,
6590
     with information on whether the process has read, write, or
6591
     execute access rights to each range.  On GNU/Linux systems, each
6592
     memory range includes the object file which is mapped to that
6593
     range, instead of the memory access rights to that range.
6594
 
6595
`info proc stat'
6596
`info proc status'
6597
     These subcommands are specific to GNU/Linux systems.  They show
6598
     the process-related information, including the user ID and group
6599
     ID; how many threads are there in the process; its virtual memory
6600
     usage; the signals that are pending, blocked, and ignored; its
6601
     TTY; its consumption of system and user time; its stack size; its
6602
     `nice' value; etc.  For more information, see the `proc' man page
6603
     (type `man 5 proc' from your shell prompt).
6604
 
6605
`info proc all'
6606
     Show all the information about the process described under all of
6607
     the above `info proc' subcommands.
6608
 
6609
`set procfs-trace'
6610
     This command enables and disables tracing of `procfs' API calls.
6611
 
6612
`show procfs-trace'
6613
     Show the current state of `procfs' API call tracing.
6614
 
6615
`set procfs-file FILE'
6616
     Tell GDB to write `procfs' API trace to the named FILE.  GDB
6617
     appends the trace info to the previous contents of the file.  The
6618
     default is to display the trace on the standard output.
6619
 
6620
`show procfs-file'
6621
     Show the file to which `procfs' API trace is written.
6622
 
6623
`proc-trace-entry'
6624
`proc-trace-exit'
6625
`proc-untrace-entry'
6626
`proc-untrace-exit'
6627
     These commands enable and disable tracing of entries into and exits
6628
     from the `syscall' interface.
6629
 
6630
`info pidlist'
6631
     For QNX Neutrino only, this command displays the list of all the
6632
     processes and all the threads within each process.
6633
 
6634
`info meminfo'
6635
     For QNX Neutrino only, this command displays the list of all
6636
     mapinfos.
6637
 
6638

6639
File: gdb.info,  Node: DJGPP Native,  Next: Cygwin Native,  Prev: SVR4 Process Information,  Up: Native
6640
 
6641
21.1.4 Features for Debugging DJGPP Programs
6642
--------------------------------------------
6643
 
6644
DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows.
6645
DJGPP programs are 32-bit protected-mode programs that use the "DPMI"
6646
(DOS Protected-Mode Interface) API to run on top of real-mode DOS
6647
systems and their emulations.
6648
 
6649
   GDB supports native debugging of DJGPP programs, and defines a few
6650
commands specific to the DJGPP port.  This subsection describes those
6651
commands.
6652
 
6653
`info dos'
6654
     This is a prefix of DJGPP-specific commands which print
6655
     information about the target system and important OS structures.
6656
 
6657
`info dos sysinfo'
6658
     This command displays assorted information about the underlying
6659
     platform: the CPU type and features, the OS version and flavor, the
6660
     DPMI version, and the available conventional and DPMI memory.
6661
 
6662
`info dos gdt'
6663
`info dos ldt'
6664
`info dos idt'
6665
     These 3 commands display entries from, respectively, Global, Local,
6666
     and Interrupt Descriptor Tables (GDT, LDT, and IDT).  The
6667
     descriptor tables are data structures which store a descriptor for
6668
     each segment that is currently in use.  The segment's selector is
6669
     an index into a descriptor table; the table entry for that index
6670
     holds the descriptor's base address and limit, and its attributes
6671
     and access rights.
6672
 
6673
     A typical DJGPP program uses 3 segments: a code segment, a data
6674
     segment (used for both data and the stack), and a DOS segment
6675
     (which allows access to DOS/BIOS data structures and absolute
6676
     addresses in conventional memory).  However, the DPMI host will
6677
     usually define additional segments in order to support the DPMI
6678
     environment.
6679
 
6680
     These commands allow to display entries from the descriptor tables.
6681
     Without an argument, all entries from the specified table are
6682
     displayed.  An argument, which should be an integer expression,
6683
     means display a single entry whose index is given by the argument.
6684
     For example, here's a convenient way to display information about
6685
     the debugged program's data segment:
6686
 
6687
     `(gdb) info dos ldt $ds'
6688
     `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)'
6689
 
6690
 
6691
     This comes in handy when you want to see whether a pointer is
6692
     outside the data segment's limit (i.e. "garbled").
6693
 
6694
`info dos pde'
6695
`info dos pte'
6696
     These two commands display entries from, respectively, the Page
6697
     Directory and the Page Tables.  Page Directories and Page Tables
6698
     are data structures which control how virtual memory addresses are
6699
     mapped into physical addresses.  A Page Table includes an entry
6700
     for every page of memory that is mapped into the program's address
6701
     space; there may be several Page Tables, each one holding up to
6702
     4096 entries.  A Page Directory has up to 4096 entries, one each
6703
     for every Page Table that is currently in use.
6704
 
6705
     Without an argument, `info dos pde' displays the entire Page
6706
     Directory, and `info dos pte' displays all the entries in all of
6707
     the Page Tables.  An argument, an integer expression, given to the
6708
     `info dos pde' command means display only that entry from the Page
6709
     Directory table.  An argument given to the `info dos pte' command
6710
     means display entries from a single Page Table, the one pointed to
6711
     by the specified entry in the Page Directory.
6712
 
6713
     These commands are useful when your program uses "DMA" (Direct
6714
     Memory Access), which needs physical addresses to program the DMA
6715
     controller.
6716
 
6717
     These commands are supported only with some DPMI servers.
6718
 
6719
`info dos address-pte ADDR'
6720
     This command displays the Page Table entry for a specified linear
6721
     address.  The argument ADDR is a linear address which should
6722
     already have the appropriate segment's base address added to it,
6723
     because this command accepts addresses which may belong to _any_
6724
     segment.  For example, here's how to display the Page Table entry
6725
     for the page where a variable `i' is stored:
6726
 
6727
     `(gdb) info dos address-pte __djgpp_base_address + (char *)&i'
6728
     `Page Table entry for address 0x11a00d30:'
6729
     `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30'
6730
 
6731
 
6732
     This says that `i' is stored at offset `0xd30' from the page whose
6733
     physical base address is `0x02698000', and shows all the
6734
     attributes of that page.
6735
 
6736
     Note that you must cast the addresses of variables to a `char *',
6737
     since otherwise the value of `__djgpp_base_address', the base
6738
     address of all variables and functions in a DJGPP program, will be
6739
     added using the rules of C pointer arithmetics: if `i' is declared
6740
     an `int', GDB will add 4 times the value of `__djgpp_base_address'
6741
     to the address of `i'.
6742
 
6743
     Here's another example, it displays the Page Table entry for the
6744
     transfer buffer:
6745
 
6746
     `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)'
6747
     `Page Table entry for address 0x29110:'
6748
     `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110'
6749
 
6750
 
6751
     (The `+ 3' offset is because the transfer buffer's address is the
6752
     3rd member of the `_go32_info_block' structure.)  The output
6753
     clearly shows that this DPMI server maps the addresses in
6754
     conventional memory 1:1, i.e. the physical (`0x00029000' +
6755
     `0x110') and linear (`0x29110') addresses are identical.
6756
 
6757
     This command is supported only with some DPMI servers.
6758
 
6759
   In addition to native debugging, the DJGPP port supports remote
6760
debugging via a serial data link.  The following commands are specific
6761
to remote serial debugging in the DJGPP port of GDB.
6762
 
6763
`set com1base ADDR'
6764
     This command sets the base I/O port address of the `COM1' serial
6765
     port.
6766
 
6767
`set com1irq IRQ'
6768
     This command sets the "Interrupt Request" (`IRQ') line to use for
6769
     the `COM1' serial port.
6770
 
6771
     There are similar commands `set com2base', `set com3irq', etc. for
6772
     setting the port address and the `IRQ' lines for the other 3 COM
6773
     ports.
6774
 
6775
     The related commands `show com1base', `show com1irq' etc.  display
6776
     the current settings of the base address and the `IRQ' lines used
6777
     by the COM ports.
6778
 
6779
`info serial'
6780
     This command prints the status of the 4 DOS serial ports.  For each
6781
     port, it prints whether it's active or not, its I/O base address
6782
     and IRQ number, whether it uses a 16550-style FIFO, its baudrate,
6783
     and the counts of various errors encountered so far.
6784
 
6785

6786
File: gdb.info,  Node: Cygwin Native,  Next: Hurd Native,  Prev: DJGPP Native,  Up: Native
6787
 
6788
21.1.5 Features for Debugging MS Windows PE Executables
6789
-------------------------------------------------------
6790
 
6791
GDB supports native debugging of MS Windows programs, including DLLs
6792
with and without symbolic debugging information.
6793
 
6794
   MS-Windows programs that call `SetConsoleMode' to switch off the
6795
special meaning of the `Ctrl-C' keystroke cannot be interrupted by
6796
typing `C-c'.  For this reason, GDB on MS-Windows supports `C-'
6797
as an alternative interrupt key sequence, which can be used to
6798
interrupt the debuggee even if it ignores `C-c'.
6799
 
6800
   There are various additional Cygwin-specific commands, described in
6801
this section.  Working with DLLs that have no debugging symbols is
6802
described in *Note Non-debug DLL Symbols::.
6803
 
6804
`info w32'
6805
     This is a prefix of MS Windows-specific commands which print
6806
     information about the target system and important OS structures.
6807
 
6808
`info w32 selector'
6809
     This command displays information returned by the Win32 API
6810
     `GetThreadSelectorEntry' function.  It takes an optional argument
6811
     that is evaluated to a long value to give the information about
6812
     this given selector.  Without argument, this command displays
6813
     information about the six segment registers.
6814
 
6815
`info dll'
6816
     This is a Cygwin-specific alias of `info shared'.
6817
 
6818
`dll-symbols'
6819
     This command loads symbols from a dll similarly to add-sym command
6820
     but without the need to specify a base address.
6821
 
6822
`set cygwin-exceptions MODE'
6823
     If MODE is `on', GDB will break on exceptions that happen inside
6824
     the Cygwin DLL.  If MODE is `off', GDB will delay recognition of
6825
     exceptions, and may ignore some exceptions which seem to be caused
6826
     by internal Cygwin DLL "bookkeeping".  This option is meant
6827
     primarily for debugging the Cygwin DLL itself; the default value
6828
     is `off' to avoid annoying GDB users with false `SIGSEGV' signals.
6829
 
6830
`show cygwin-exceptions'
6831
     Displays whether GDB will break on exceptions that happen inside
6832
     the Cygwin DLL itself.
6833
 
6834
`set new-console MODE'
6835
     If MODE is `on' the debuggee will be started in a new console on
6836
     next start.  If MODE is `off'i, the debuggee will be started in
6837
     the same console as the debugger.
6838
 
6839
`show new-console'
6840
     Displays whether a new console is used when the debuggee is
6841
     started.
6842
 
6843
`set new-group MODE'
6844
     This boolean value controls whether the debuggee should start a
6845
     new group or stay in the same group as the debugger.  This affects
6846
     the way the Windows OS handles `Ctrl-C'.
6847
 
6848
`show new-group'
6849
     Displays current value of new-group boolean.
6850
 
6851
`set debugevents'
6852
     This boolean value adds debug output concerning kernel events
6853
     related to the debuggee seen by the debugger.  This includes
6854
     events that signal thread and process creation and exit, DLL
6855
     loading and unloading, console interrupts, and debugging messages
6856
     produced by the Windows `OutputDebugString' API call.
6857
 
6858
`set debugexec'
6859
     This boolean value adds debug output concerning execute events
6860
     (such as resume thread) seen by the debugger.
6861
 
6862
`set debugexceptions'
6863
     This boolean value adds debug output concerning exceptions in the
6864
     debuggee seen by the debugger.
6865
 
6866
`set debugmemory'
6867
     This boolean value adds debug output concerning debuggee memory
6868
     reads and writes by the debugger.
6869
 
6870
`set shell'
6871
     This boolean values specifies whether the debuggee is called via a
6872
     shell or directly (default value is on).
6873
 
6874
`show shell'
6875
     Displays if the debuggee will be started with a shell.
6876
 
6877
 
6878
* Menu:
6879
 
6880
* Non-debug DLL Symbols::  Support for DLLs without debugging symbols
6881
 
6882

6883
File: gdb.info,  Node: Non-debug DLL Symbols,  Up: Cygwin Native
6884
 
6885
21.1.5.1 Support for DLLs without Debugging Symbols
6886
...................................................
6887
 
6888
Very often on windows, some of the DLLs that your program relies on do
6889
not include symbolic debugging information (for example,
6890
`kernel32.dll').  When GDB doesn't recognize any debugging symbols in a
6891
DLL, it relies on the minimal amount of symbolic information contained
6892
in the DLL's export table.  This section describes working with such
6893
symbols, known internally to GDB as "minimal symbols".
6894
 
6895
   Note that before the debugged program has started execution, no DLLs
6896
will have been loaded.  The easiest way around this problem is simply to
6897
start the program -- either by setting a breakpoint or letting the
6898
program run once to completion.  It is also possible to force GDB to
6899
load a particular DLL before starting the executable -- see the shared
6900
library information in *Note Files::, or the `dll-symbols' command in
6901
*Note Cygwin Native::.  Currently, explicitly loading symbols from a
6902
DLL with no debugging information will cause the symbol names to be
6903
duplicated in GDB's lookup table, which may adversely affect symbol
6904
lookup performance.
6905
 
6906
21.1.5.2 DLL Name Prefixes
6907
..........................
6908
 
6909
In keeping with the naming conventions used by the Microsoft debugging
6910
tools, DLL export symbols are made available with a prefix based on the
6911
DLL name, for instance `KERNEL32!CreateFileA'.  The plain name is also
6912
entered into the symbol table, so `CreateFileA' is often sufficient.
6913
In some cases there will be name clashes within a program (particularly
6914
if the executable itself includes full debugging symbols) necessitating
6915
the use of the fully qualified name when referring to the contents of
6916
the DLL.  Use single-quotes around the name to avoid the exclamation
6917
mark ("!")  being interpreted as a language operator.
6918
 
6919
   Note that the internal name of the DLL may be all upper-case, even
6920
though the file name of the DLL is lower-case, or vice-versa.  Since
6921
symbols within GDB are _case-sensitive_ this may cause some confusion.
6922
If in doubt, try the `info functions' and `info variables' commands or
6923
even `maint print msymbols' (*note Symbols::). Here's an example:
6924
 
6925
     (gdb) info function CreateFileA
6926
     All functions matching regular expression "CreateFileA":
6927
 
6928
     Non-debugging symbols:
6929
     0x77e885f4  CreateFileA
6930
     0x77e885f4  KERNEL32!CreateFileA
6931
 
6932
     (gdb) info function !
6933
     All functions matching regular expression "!":
6934
 
6935
     Non-debugging symbols:
6936
     0x6100114c  cygwin1!__assert
6937
     0x61004034  cygwin1!_dll_crt0@0
6938
     0x61004240  cygwin1!dll_crt0(per_process *)
6939
     [etc...]
6940
 
6941
21.1.5.3 Working with Minimal Symbols
6942
.....................................
6943
 
6944
Symbols extracted from a DLL's export table do not contain very much
6945
type information. All that GDB can do is guess whether a symbol refers
6946
to a function or variable depending on the linker section that contains
6947
the symbol. Also note that the actual contents of the memory contained
6948
in a DLL are not available unless the program is running. This means
6949
that you cannot examine the contents of a variable or disassemble a
6950
function within a DLL without a running program.
6951
 
6952
   Variables are generally treated as pointers and dereferenced
6953
automatically. For this reason, it is often necessary to prefix a
6954
variable name with the address-of operator ("&") and provide explicit
6955
type information in the command. Here's an example of the type of
6956
problem:
6957
 
6958
     (gdb) print 'cygwin1!__argv'
6959
     $1 = 268572168
6960
 
6961
     (gdb) x 'cygwin1!__argv'
6962
     0x10021610:      "\230y\""
6963
 
6964
   And two possible solutions:
6965
 
6966
     (gdb) print ((char **)'cygwin1!__argv')[0]
6967
     $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
6968
 
6969
     (gdb) x/2x &'cygwin1!__argv'
6970
     0x610c0aa8 :    0x10021608      0x00000000
6971
     (gdb) x/x 0x10021608
6972
     0x10021608:     0x0022fd98
6973
     (gdb) x/s 0x0022fd98
6974
     0x22fd98:        "/cygdrive/c/mydirectory/myprogram"
6975
 
6976
   Setting a break point within a DLL is possible even before the
6977
program starts execution. However, under these circumstances, GDB can't
6978
examine the initial instructions of the function in order to skip the
6979
function's frame set-up code. You can work around this by using "*&" to
6980
set the breakpoint at a raw memory address:
6981
 
6982
     (gdb) break *&'python22!PyOS_Readline'
6983
     Breakpoint 1 at 0x1e04eff0
6984
 
6985
   The author of these extensions is not entirely convinced that
6986
setting a break point within a shared DLL like `kernel32.dll' is
6987
completely safe.
6988
 
6989

6990
File: gdb.info,  Node: Hurd Native,  Next: Neutrino,  Prev: Cygwin Native,  Up: Native
6991
 
6992
21.1.6 Commands Specific to GNU Hurd Systems
6993
--------------------------------------------
6994
 
6995
This subsection describes GDB commands specific to the GNU Hurd native
6996
debugging.
6997
 
6998
`set signals'
6999
`set sigs'
7000
     This command toggles the state of inferior signal interception by
7001
     GDB.  Mach exceptions, such as breakpoint traps, are not affected
7002
     by this command.  `sigs' is a shorthand alias for `signals'.
7003
 
7004
`show signals'
7005
`show sigs'
7006
     Show the current state of intercepting inferior's signals.
7007
 
7008
`set signal-thread'
7009
`set sigthread'
7010
     This command tells GDB which thread is the `libc' signal thread.
7011
     That thread is run when a signal is delivered to a running
7012
     process.  `set sigthread' is the shorthand alias of `set
7013
     signal-thread'.
7014
 
7015
`show signal-thread'
7016
`show sigthread'
7017
     These two commands show which thread will run when the inferior is
7018
     delivered a signal.
7019
 
7020
`set stopped'
7021
     This commands tells GDB that the inferior process is stopped, as
7022
     with the `SIGSTOP' signal.  The stopped process can be continued
7023
     by delivering a signal to it.
7024
 
7025
`show stopped'
7026
     This command shows whether GDB thinks the debuggee is stopped.
7027
 
7028
`set exceptions'
7029
     Use this command to turn off trapping of exceptions in the
7030
     inferior.  When exception trapping is off, neither breakpoints nor
7031
     single-stepping will work.  To restore the default, set exception
7032
     trapping on.
7033
 
7034
`show exceptions'
7035
     Show the current state of trapping exceptions in the inferior.
7036
 
7037
`set task pause'
7038
     This command toggles task suspension when GDB has control.
7039
     Setting it to on takes effect immediately, and the task is
7040
     suspended whenever GDB gets control.  Setting it to off will take
7041
     effect the next time the inferior is continued.  If this option is
7042
     set to off, you can use `set thread default pause on' or `set
7043
     thread pause on' (see below) to pause individual threads.
7044
 
7045
`show task pause'
7046
     Show the current state of task suspension.
7047
 
7048
`set task detach-suspend-count'
7049
     This command sets the suspend count the task will be left with when
7050
     GDB detaches from it.
7051
 
7052
`show task detach-suspend-count'
7053
     Show the suspend count the task will be left with when detaching.
7054
 
7055
`set task exception-port'
7056
`set task excp'
7057
     This command sets the task exception port to which GDB will
7058
     forward exceptions.  The argument should be the value of the "send
7059
     rights" of the task.  `set task excp' is a shorthand alias.
7060
 
7061
`set noninvasive'
7062
     This command switches GDB to a mode that is the least invasive as
7063
     far as interfering with the inferior is concerned.  This is the
7064
     same as using `set task pause', `set exceptions', and `set
7065
     signals' to values opposite to the defaults.
7066
 
7067
`info send-rights'
7068
`info receive-rights'
7069
`info port-rights'
7070
`info port-sets'
7071
`info dead-names'
7072
`info ports'
7073
`info psets'
7074
     These commands display information about, respectively, send
7075
     rights, receive rights, port rights, port sets, and dead names of
7076
     a task.  There are also shorthand aliases: `info ports' for `info
7077
     port-rights' and `info psets' for `info port-sets'.
7078
 
7079
`set thread pause'
7080
     This command toggles current thread suspension when GDB has
7081
     control.  Setting it to on takes effect immediately, and the
7082
     current thread is suspended whenever GDB gets control.  Setting it
7083
     to off will take effect the next time the inferior is continued.
7084
     Normally, this command has no effect, since when GDB has control,
7085
     the whole task is suspended.  However, if you used `set task pause
7086
     off' (see above), this command comes in handy to suspend only the
7087
     current thread.
7088
 
7089
`show thread pause'
7090
     This command shows the state of current thread suspension.
7091
 
7092
`set thread run'
7093
     This command sets whether the current thread is allowed to run.
7094
 
7095
`show thread run'
7096
     Show whether the current thread is allowed to run.
7097
 
7098
`set thread detach-suspend-count'
7099
     This command sets the suspend count GDB will leave on a thread
7100
     when detaching.  This number is relative to the suspend count
7101
     found by GDB when it notices the thread; use `set thread
7102
     takeover-suspend-count' to force it to an absolute value.
7103
 
7104
`show thread detach-suspend-count'
7105
     Show the suspend count GDB will leave on the thread when detaching.
7106
 
7107
`set thread exception-port'
7108
`set thread excp'
7109
     Set the thread exception port to which to forward exceptions.  This
7110
     overrides the port set by `set task exception-port' (see above).
7111
     `set thread excp' is the shorthand alias.
7112
 
7113
`set thread takeover-suspend-count'
7114
     Normally, GDB's thread suspend counts are relative to the value
7115
     GDB finds when it notices each thread.  This command changes the
7116
     suspend counts to be absolute instead.
7117
 
7118
`set thread default'
7119
`show thread default'
7120
     Each of the above `set thread' commands has a `set thread default'
7121
     counterpart (e.g., `set thread default pause', `set thread default
7122
     exception-port', etc.).  The `thread default' variety of commands
7123
     sets the default thread properties for all threads; you can then
7124
     change the properties of individual threads with the non-default
7125
     commands.
7126
 
7127

7128
File: gdb.info,  Node: Neutrino,  Next: Darwin,  Prev: Hurd Native,  Up: Native
7129
 
7130
21.1.7 QNX Neutrino
7131
-------------------
7132
 
7133
GDB provides the following commands specific to the QNX Neutrino target:
7134
 
7135
`set debug nto-debug'
7136
     When set to on, enables debugging messages specific to the QNX
7137
     Neutrino support.
7138
 
7139
`show debug nto-debug'
7140
     Show the current state of QNX Neutrino messages.
7141
 
7142

7143
File: gdb.info,  Node: Darwin,  Prev: Neutrino,  Up: Native
7144
 
7145
21.1.8 Darwin
7146
-------------
7147
 
7148
GDB provides the following commands specific to the Darwin target:
7149
 
7150
`set debug darwin NUM'
7151
     When set to a non zero value, enables debugging messages specific
7152
     to the Darwin support.  Higher values produce more verbose output.
7153
 
7154
`show debug darwin'
7155
     Show the current state of Darwin messages.
7156
 
7157
`set debug mach-o NUM'
7158
     When set to a non zero value, enables debugging messages while GDB
7159
     is reading Darwin object files.  ("Mach-O" is the file format used
7160
     on Darwin for object and executable files.)  Higher values produce
7161
     more verbose output.  This is a command to diagnose problems
7162
     internal to GDB and should not be needed in normal usage.
7163
 
7164
`show debug mach-o'
7165
     Show the current state of Mach-O file messages.
7166
 
7167
`set mach-exceptions on'
7168
`set mach-exceptions off'
7169
     On Darwin, faults are first reported as a Mach exception and are
7170
     then mapped to a Posix signal.  Use this command to turn on
7171
     trapping of Mach exceptions in the inferior.  This might be
7172
     sometimes useful to better understand the cause of a fault.  The
7173
     default is off.
7174
 
7175
`show mach-exceptions'
7176
     Show the current state of exceptions trapping.
7177
 
7178

7179
File: gdb.info,  Node: Embedded OS,  Next: Embedded Processors,  Prev: Native,  Up: Configurations
7180
 
7181
21.2 Embedded Operating Systems
7182
===============================
7183
 
7184
This section describes configurations involving the debugging of
7185
embedded operating systems that are available for several different
7186
architectures.
7187
 
7188
* Menu:
7189
 
7190
* VxWorks::                     Using GDB with VxWorks
7191
 
7192
   GDB includes the ability to debug programs running on various
7193
real-time operating systems.
7194
 
7195

7196
File: gdb.info,  Node: VxWorks,  Up: Embedded OS
7197
 
7198
21.2.1 Using GDB with VxWorks
7199
-----------------------------
7200
 
7201
`target vxworks MACHINENAME'
7202
     A VxWorks system, attached via TCP/IP.  The argument MACHINENAME
7203
     is the target system's machine name or IP address.
7204
 
7205
 
7206
   On VxWorks, `load' links FILENAME dynamically on the current target
7207
system as well as adding its symbols in GDB.
7208
 
7209
   GDB enables developers to spawn and debug tasks running on networked
7210
VxWorks targets from a Unix host.  Already-running tasks spawned from
7211
the VxWorks shell can also be debugged.  GDB uses code that runs on
7212
both the Unix host and on the VxWorks target.  The program `gdb' is
7213
installed and executed on the Unix host.  (It may be installed with the
7214
name `vxgdb', to distinguish it from a GDB for debugging programs on
7215
the host itself.)
7216
 
7217
`VxWorks-timeout ARGS'
7218
     All VxWorks-based targets now support the option `vxworks-timeout'.
7219
     This option is set by the user, and  ARGS represents the number of
7220
     seconds GDB waits for responses to rpc's.  You might use this if
7221
     your VxWorks target is a slow software simulator or is on the far
7222
     side of a thin network line.
7223
 
7224
   The following information on connecting to VxWorks was current when
7225
this manual was produced; newer releases of VxWorks may use revised
7226
procedures.
7227
 
7228
   To use GDB with VxWorks, you must rebuild your VxWorks kernel to
7229
include the remote debugging interface routines in the VxWorks library
7230
`rdb.a'.  To do this, define `INCLUDE_RDB' in the VxWorks configuration
7231
file `configAll.h' and rebuild your VxWorks kernel.  The resulting
7232
kernel contains `rdb.a', and spawns the source debugging task
7233
`tRdbTask' when VxWorks is booted.  For more information on configuring
7234
and remaking VxWorks, see the manufacturer's manual.
7235
 
7236
   Once you have included `rdb.a' in your VxWorks system image and set
7237
your Unix execution search path to find GDB, you are ready to run GDB.
7238
From your Unix host, run `gdb' (or `vxgdb', depending on your
7239
installation).
7240
 
7241
   GDB comes up showing the prompt:
7242
 
7243
     (vxgdb)
7244
 
7245
* Menu:
7246
 
7247
* VxWorks Connection::          Connecting to VxWorks
7248
* VxWorks Download::            VxWorks download
7249
* VxWorks Attach::              Running tasks
7250
 
7251

7252
File: gdb.info,  Node: VxWorks Connection,  Next: VxWorks Download,  Up: VxWorks
7253
 
7254
21.2.1.1 Connecting to VxWorks
7255
..............................
7256
 
7257
The GDB command `target' lets you connect to a VxWorks target on the
7258
network.  To connect to a target whose host name is "`tt'", type:
7259
 
7260
     (vxgdb) target vxworks tt
7261
 
7262
   GDB displays messages like these:
7263
 
7264
     Attaching remote machine across net...
7265
     Connected to tt.
7266
 
7267
   GDB then attempts to read the symbol tables of any object modules
7268
loaded into the VxWorks target since it was last booted.  GDB locates
7269
these files by searching the directories listed in the command search
7270
path (*note Your Program's Environment: Environment.); if it fails to
7271
find an object file, it displays a message such as:
7272
 
7273
     prog.o: No such file or directory.
7274
 
7275
   When this happens, add the appropriate directory to the search path
7276
with the GDB command `path', and execute the `target' command again.
7277
 
7278

7279
File: gdb.info,  Node: VxWorks Download,  Next: VxWorks Attach,  Prev: VxWorks Connection,  Up: VxWorks
7280
 
7281
21.2.1.2 VxWorks Download
7282
.........................
7283
 
7284
If you have connected to the VxWorks target and you want to debug an
7285
object that has not yet been loaded, you can use the GDB `load' command
7286
to download a file from Unix to VxWorks incrementally.  The object file
7287
given as an argument to the `load' command is actually opened twice:
7288
first by the VxWorks target in order to download the code, then by GDB
7289
in order to read the symbol table.  This can lead to problems if the
7290
current working directories on the two systems differ.  If both systems
7291
have NFS mounted the same filesystems, you can avoid these problems by
7292
using absolute paths.  Otherwise, it is simplest to set the working
7293
directory on both systems to the directory in which the object file
7294
resides, and then to reference the file by its name, without any path.
7295
For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in
7296
VxWorks and in `HOSTPATH/vw/demo/rdb' on the host.  To load this
7297
program, type this on VxWorks:
7298
 
7299
     -> cd "VXPATH/vw/demo/rdb"
7300
 
7301
Then, in GDB, type:
7302
 
7303
     (vxgdb) cd HOSTPATH/vw/demo/rdb
7304
     (vxgdb) load prog.o
7305
 
7306
   GDB displays a response similar to this:
7307
 
7308
     Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
7309
 
7310
   You can also use the `load' command to reload an object module after
7311
editing and recompiling the corresponding source file.  Note that this
7312
makes GDB delete all currently-defined breakpoints, auto-displays, and
7313
convenience variables, and to clear the value history.  (This is
7314
necessary in order to preserve the integrity of debugger's data
7315
structures that reference the target system's symbol table.)
7316
 
7317

7318
File: gdb.info,  Node: VxWorks Attach,  Prev: VxWorks Download,  Up: VxWorks
7319
 
7320
21.2.1.3 Running Tasks
7321
......................
7322
 
7323
You can also attach to an existing task using the `attach' command as
7324
follows:
7325
 
7326
     (vxgdb) attach TASK
7327
 
7328
where TASK is the VxWorks hexadecimal task ID.  The task can be running
7329
or suspended when you attach to it.  Running tasks are suspended at the
7330
time of attachment.
7331
 
7332

7333
File: gdb.info,  Node: Embedded Processors,  Next: Architectures,  Prev: Embedded OS,  Up: Configurations
7334
 
7335
21.3 Embedded Processors
7336
========================
7337
 
7338
This section goes into details specific to particular embedded
7339
configurations.
7340
 
7341
   Whenever a specific embedded processor has a simulator, GDB allows
7342
to send an arbitrary command to the simulator.
7343
 
7344
`sim COMMAND'
7345
     Send an arbitrary COMMAND string to the simulator.  Consult the
7346
     documentation for the specific simulator in use for information
7347
     about acceptable commands.
7348
 
7349
* Menu:
7350
 
7351
* ARM::                         ARM RDI
7352
* M32R/D::                      Renesas M32R/D
7353
* M68K::                        Motorola M68K
7354
* MicroBlaze::                  Xilinx MicroBlaze
7355
* MIPS Embedded::               MIPS Embedded
7356
* OpenRISC 1000::               OpenRisc 1000
7357
* PA::                          HP PA Embedded
7358
* PowerPC Embedded::            PowerPC Embedded
7359
* Sparclet::                    Tsqware Sparclet
7360
* Sparclite::                   Fujitsu Sparclite
7361
* Z8000::                       Zilog Z8000
7362
* AVR::                         Atmel AVR
7363
* CRIS::                        CRIS
7364
* Super-H::                     Renesas Super-H
7365
 
7366

7367
File: gdb.info,  Node: ARM,  Next: M32R/D,  Up: Embedded Processors
7368
 
7369
21.3.1 ARM
7370
----------
7371
 
7372
`target rdi DEV'
7373
     ARM Angel monitor, via RDI library interface to ADP protocol.  You
7374
     may use this target to communicate with both boards running the
7375
     Angel monitor, or with the EmbeddedICE JTAG debug device.
7376
 
7377
`target rdp DEV'
7378
     ARM Demon monitor.
7379
 
7380
 
7381
   GDB provides the following ARM-specific commands:
7382
 
7383
`set arm disassembler'
7384
     This commands selects from a list of disassembly styles.  The
7385
     `"std"' style is the standard style.
7386
 
7387
`show arm disassembler'
7388
     Show the current disassembly style.
7389
 
7390
`set arm apcs32'
7391
     This command toggles ARM operation mode between 32-bit and 26-bit.
7392
 
7393
`show arm apcs32'
7394
     Display the current usage of the ARM 32-bit mode.
7395
 
7396
`set arm fpu FPUTYPE'
7397
     This command sets the ARM floating-point unit (FPU) type.  The
7398
     argument FPUTYPE can be one of these:
7399
 
7400
    `auto'
7401
          Determine the FPU type by querying the OS ABI.
7402
 
7403
    `softfpa'
7404
          Software FPU, with mixed-endian doubles on little-endian ARM
7405
          processors.
7406
 
7407
    `fpa'
7408
          GCC-compiled FPA co-processor.
7409
 
7410
    `softvfp'
7411
          Software FPU with pure-endian doubles.
7412
 
7413
    `vfp'
7414
          VFP co-processor.
7415
 
7416
`show arm fpu'
7417
     Show the current type of the FPU.
7418
 
7419
`set arm abi'
7420
     This command forces GDB to use the specified ABI.
7421
 
7422
`show arm abi'
7423
     Show the currently used ABI.
7424
 
7425
`set arm fallback-mode (arm|thumb|auto)'
7426
     GDB uses the symbol table, when available, to determine whether
7427
     instructions are ARM or Thumb.  This command controls GDB's
7428
     default behavior when the symbol table is not available.  The
7429
     default is `auto', which causes GDB to use the current execution
7430
     mode (from the `T' bit in the `CPSR' register).
7431
 
7432
`show arm fallback-mode'
7433
     Show the current fallback instruction mode.
7434
 
7435
`set arm force-mode (arm|thumb|auto)'
7436
     This command overrides use of the symbol table to determine whether
7437
     instructions are ARM or Thumb.  The default is `auto', which
7438
     causes GDB to use the symbol table and then the setting of `set
7439
     arm fallback-mode'.
7440
 
7441
`show arm force-mode'
7442
     Show the current forced instruction mode.
7443
 
7444
`set debug arm'
7445
     Toggle whether to display ARM-specific debugging messages from the
7446
     ARM target support subsystem.
7447
 
7448
`show debug arm'
7449
     Show whether ARM-specific debugging messages are enabled.
7450
 
7451
   The following commands are available when an ARM target is debugged
7452
using the RDI interface:
7453
 
7454
`rdilogfile [FILE]'
7455
     Set the filename for the ADP (Angel Debugger Protocol) packet log.
7456
     With an argument, sets the log file to the specified FILE.  With
7457
     no argument, show the current log file name.  The default log file
7458
     is `rdi.log'.
7459
 
7460
`rdilogenable [ARG]'
7461
     Control logging of ADP packets.  With an argument of 1 or `"yes"'
7462
     enables logging, with an argument 0 or `"no"' disables it.  With
7463
     no arguments displays the current setting.  When logging is
7464
     enabled, ADP packets exchanged between GDB and the RDI target
7465
     device are logged to a file.
7466
 
7467
`set rdiromatzero'
7468
     Tell GDB whether the target has ROM at address 0.  If on, vector
7469
     catching is disabled, so that zero address can be used.  If off
7470
     (the default), vector catching is enabled.  For this command to
7471
     take effect, it needs to be invoked prior to the `target rdi'
7472
     command.
7473
 
7474
`show rdiromatzero'
7475
     Show the current setting of ROM at zero address.
7476
 
7477
`set rdiheartbeat'
7478
     Enable or disable RDI heartbeat packets.  It is not recommended to
7479
     turn on this option, since it confuses ARM and EPI JTAG interface,
7480
     as well as the Angel monitor.
7481
 
7482
`show rdiheartbeat'
7483
     Show the setting of RDI heartbeat packets.
7484
 
7485

7486
File: gdb.info,  Node: M32R/D,  Next: M68K,  Prev: ARM,  Up: Embedded Processors
7487
 
7488
21.3.2 Renesas M32R/D and M32R/SDI
7489
----------------------------------
7490
 
7491
`target m32r DEV'
7492
     Renesas M32R/D ROM monitor.
7493
 
7494
`target m32rsdi DEV'
7495
     Renesas M32R SDI server, connected via parallel port to the board.
7496
 
7497
   The following GDB commands are specific to the M32R monitor:
7498
 
7499
`set download-path PATH'
7500
     Set the default path for finding downloadable SREC files.
7501
 
7502
`show download-path'
7503
     Show the default path for downloadable SREC files.
7504
 
7505
`set board-address ADDR'
7506
     Set the IP address for the M32R-EVA target board.
7507
 
7508
`show board-address'
7509
     Show the current IP address of the target board.
7510
 
7511
`set server-address ADDR'
7512
     Set the IP address for the download server, which is the GDB's
7513
     host machine.
7514
 
7515
`show server-address'
7516
     Display the IP address of the download server.
7517
 
7518
`upload [FILE]'
7519
     Upload the specified SREC FILE via the monitor's Ethernet upload
7520
     capability.  If no FILE argument is given, the current executable
7521
     file is uploaded.
7522
 
7523
`tload [FILE]'
7524
     Test the `upload' command.
7525
 
7526
   The following commands are available for M32R/SDI:
7527
 
7528
`sdireset'
7529
     This command resets the SDI connection.
7530
 
7531
`sdistatus'
7532
     This command shows the SDI connection status.
7533
 
7534
`debug_chaos'
7535
     Instructs the remote that M32R/Chaos debugging is to be used.
7536
 
7537
`use_debug_dma'
7538
     Instructs the remote to use the DEBUG_DMA method of accessing
7539
     memory.
7540
 
7541
`use_mon_code'
7542
     Instructs the remote to use the MON_CODE method of accessing
7543
     memory.
7544
 
7545
`use_ib_break'
7546
     Instructs the remote to set breakpoints by IB break.
7547
 
7548
`use_dbt_break'
7549
     Instructs the remote to set breakpoints by DBT.
7550
 
7551

7552
File: gdb.info,  Node: M68K,  Next: MicroBlaze,  Prev: M32R/D,  Up: Embedded Processors
7553
 
7554
21.3.3 M68k
7555
-----------
7556
 
7557
The Motorola m68k configuration includes ColdFire support, and a target
7558
command for the following ROM monitor.
7559
 
7560
`target dbug DEV'
7561
     dBUG ROM monitor for Motorola ColdFire.
7562
 
7563
 

powered by: WebSVN 2.1.0

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