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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gdb-7.2/] [gdb/] [doc/] [gdb.info-2] - Blame information for rev 853

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

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

44
File: gdb.info,  Node: Registers,  Next: Floating Point Hardware,  Prev: Convenience Vars,  Up: Data
45
 
46
10.12 Registers
47
===============
48
 
49
You can refer to machine register contents, in expressions, as variables
50
with names starting with `$'.  The names of registers are different for
51
each machine; use `info registers' to see the names used on your
52
machine.
53
 
54
`info registers'
55
     Print the names and values of all registers except floating-point
56
     and vector registers (in the selected stack frame).
57
 
58
`info all-registers'
59
     Print the names and values of all registers, including
60
     floating-point and vector registers (in the selected stack frame).
61
 
62
`info registers REGNAME ...'
63
     Print the "relativized" value of each specified register REGNAME.
64
     As discussed in detail below, register values are normally
65
     relative to the selected stack frame.  REGNAME may be any register
66
     name valid on the machine you are using, with or without the
67
     initial `$'.
68
 
69
   GDB has four "standard" register names that are available (in
70
expressions) on most machines--whenever they do not conflict with an
71
architecture's canonical mnemonics for registers.  The register names
72
`$pc' and `$sp' are used for the program counter register and the stack
73
pointer.  `$fp' is used for a register that contains a pointer to the
74
current stack frame, and `$ps' is used for a register that contains the
75
processor status.  For example, you could print the program counter in
76
hex with
77
 
78
     p/x $pc
79
 
80
or print the instruction to be executed next with
81
 
82
     x/i $pc
83
 
84
or add four to the stack pointer(1) with
85
 
86
     set $sp += 4
87
 
88
   Whenever possible, these four standard register names are available
89
on your machine even though the machine has different canonical
90
mnemonics, so long as there is no conflict.  The `info registers'
91
command shows the canonical names.  For example, on the SPARC, `info
92
registers' displays the processor status register as `$psr' but you can
93
also refer to it as `$ps'; and on x86-based machines `$ps' is an alias
94
for the EFLAGS register.
95
 
96
   GDB always considers the contents of an ordinary register as an
97
integer when the register is examined in this way.  Some machines have
98
special registers which can hold nothing but floating point; these
99
registers are considered to have floating point values.  There is no way
100
to refer to the contents of an ordinary register as floating point value
101
(although you can _print_ it as a floating point value with `print/f
102
$REGNAME').
103
 
104
   Some registers have distinct "raw" and "virtual" data formats.  This
105
means that the data format in which the register contents are saved by
106
the operating system is not the same one that your program normally
107
sees.  For example, the registers of the 68881 floating point
108
coprocessor are always saved in "extended" (raw) format, but all C
109
programs expect to work with "double" (virtual) format.  In such cases,
110
GDB normally works with the virtual format only (the format that makes
111
sense for your program), but the `info registers' command prints the
112
data in both formats.
113
 
114
   Some machines have special registers whose contents can be
115
interpreted in several different ways.  For example, modern x86-based
116
machines have SSE and MMX registers that can hold several values packed
117
together in several different formats.  GDB refers to such registers in
118
`struct' notation:
119
 
120
     (gdb) print $xmm1
121
     $1 = {
122
       v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044},
123
       v2_double = {9.92129282474342e-303, 2.7585945287983262e-313},
124
       v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
125
       v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0},
126
       v4_int32 = {0, 20657912, 11, 13},
127
       v2_int64 = {88725056443645952, 55834574859},
128
       uint128 = 0x0000000d0000000b013b36f800000000
129
     }
130
 
131
To set values of such registers, you need to tell GDB which view of the
132
register you wish to change, as if you were assigning value to a
133
`struct' member:
134
 
135
      (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
136
 
137
   Normally, register values are relative to the selected stack frame
138
(*note Selecting a Frame: Selection.).  This means that you get the
139
value that the register would contain if all stack frames farther in
140
were exited and their saved registers restored.  In order to see the
141
true contents of hardware registers, you must select the innermost
142
frame (with `frame 0').
143
 
144
   However, GDB must deduce where registers are saved, from the machine
145
code generated by your compiler.  If some registers are not saved, or if
146
GDB is unable to locate the saved registers, the selected stack frame
147
makes no difference.
148
 
149
   ---------- Footnotes ----------
150
 
151
   (1) This is a way of removing one word from the stack, on machines
152
where stacks grow downward in memory (most machines, nowadays).  This
153
assumes that the innermost stack frame is selected; setting `$sp' is
154
not allowed when other stack frames are selected.  To pop entire frames
155
off the stack, regardless of machine architecture, use `return'; see
156 342 jeremybenn
*note Returning from a Function: Returning.
157 330 jeremybenn
 
158

159
File: gdb.info,  Node: Floating Point Hardware,  Next: Vector Unit,  Prev: Registers,  Up: Data
160
 
161
10.13 Floating Point Hardware
162
=============================
163
 
164
Depending on the configuration, GDB may be able to give you more
165
information about the status of the floating point hardware.
166
 
167
`info float'
168
     Display hardware-dependent information about the floating point
169
     unit.  The exact contents and layout vary depending on the
170
     floating point chip.  Currently, `info float' is supported on the
171
     ARM and x86 machines.
172
 
173

174
File: gdb.info,  Node: Vector Unit,  Next: OS Information,  Prev: Floating Point Hardware,  Up: Data
175
 
176
10.14 Vector Unit
177
=================
178
 
179
Depending on the configuration, GDB may be able to give you more
180
information about the status of the vector unit.
181
 
182
`info vector'
183
     Display information about the vector unit.  The exact contents and
184
     layout vary depending on the hardware.
185
 
186

187
File: gdb.info,  Node: OS Information,  Next: Memory Region Attributes,  Prev: Vector Unit,  Up: Data
188
 
189
10.15 Operating System Auxiliary Information
190
============================================
191
 
192
GDB provides interfaces to useful OS facilities that can help you debug
193
your program.
194
 
195
   When GDB runs on a "Posix system" (such as GNU or Unix machines), it
196
interfaces with the inferior via the `ptrace' system call.  The
197
operating system creates a special sata structure, called `struct
198
user', for this interface.  You can use the command `info udot' to
199
display the contents of this data structure.
200
 
201
`info udot'
202
     Display the contents of the `struct user' maintained by the OS
203
     kernel for the program being debugged.  GDB displays the contents
204
     of `struct user' as a list of hex numbers, similar to the
205
     `examine' command.
206
 
207
   Some operating systems supply an "auxiliary vector" to programs at
208
startup.  This is akin to the arguments and environment that you
209
specify for a program, but contains a system-dependent variety of
210
binary values that tell system libraries important details about the
211
hardware, operating system, and process.  Each value's purpose is
212
identified by an integer tag; the meanings are well-known but
213
system-specific.  Depending on the configuration and operating system
214
facilities, GDB may be able to show you this information.  For remote
215
targets, this functionality may further depend on the remote stub's
216 342 jeremybenn
support of the `qXfer:auxv:read' packet, see *note qXfer auxiliary
217 330 jeremybenn
vector read::.
218
 
219
`info auxv'
220
     Display the auxiliary vector of the inferior, which can be either a
221
     live process or a core dump file.  GDB prints each tag value
222
     numerically, and also shows names and text descriptions for
223
     recognized tags.  Some values in the vector are numbers, some bit
224
     masks, and some pointers to strings or other data.  GDB displays
225
     each value in the most appropriate form for a recognized tag, and
226
     in hexadecimal for an unrecognized tag.
227
 
228
   On some targets, GDB can access operating-system-specific information
229
and display it to user, without interpretation.  For remote targets,
230
this functionality depends on the remote stub's support of the
231 342 jeremybenn
`qXfer:osdata:read' packet, see *note qXfer osdata read::.
232 330 jeremybenn
 
233
`info os'
234
     List the types of OS information available for the target.  If the
235
     target does not return a list of possible types, this command will
236
     report an error.
237
 
238
`info os processes'
239
     Display the list of processes on the target.  For each process,
240
     GDB prints the process identifier, the name of the user, and the
241
     command corresponding to the process.
242
 
243

244
File: gdb.info,  Node: Memory Region Attributes,  Next: Dump/Restore Files,  Prev: OS Information,  Up: Data
245
 
246
10.16 Memory Region Attributes
247
==============================
248
 
249
"Memory region attributes" allow you to describe special handling
250
required by regions of your target's memory.  GDB uses attributes to
251
determine whether to allow certain types of memory accesses; whether to
252
use specific width accesses; and whether to cache target memory.  By
253
default the description of memory regions is fetched from the target
254
(if the current target supports this), but the user can override the
255
fetched regions.
256
 
257
   Defined memory regions can be individually enabled and disabled.
258
When a memory region is disabled, GDB uses the default attributes when
259
accessing memory in that region.  Similarly, if no memory regions have
260
been defined, GDB uses the default attributes when accessing all memory.
261
 
262
   When a memory region is defined, it is given a number to identify it;
263
to enable, disable, or remove a memory region, you specify that number.
264
 
265
`mem LOWER UPPER ATTRIBUTES...'
266
     Define a memory region bounded by LOWER and UPPER with attributes
267
     ATTRIBUTES..., and add it to the list of regions monitored by GDB.
268
     Note that UPPER == 0 is a special case: it is treated as the
269
     target's maximum memory address.  (0xffff on 16 bit targets,
270
     0xffffffff on 32 bit targets, etc.)
271
 
272
`mem auto'
273
     Discard any user changes to the memory regions and use
274
     target-supplied regions, if available, or no regions if the target
275
     does not support.
276
 
277
`delete mem NUMS...'
278
     Remove memory regions NUMS... from the list of regions monitored
279
     by GDB.
280
 
281
`disable mem NUMS...'
282
     Disable monitoring of memory regions NUMS....  A disabled memory
283
     region is not forgotten.  It may be enabled again later.
284
 
285
`enable mem NUMS...'
286
     Enable monitoring of memory regions NUMS....
287
 
288
`info mem'
289
     Print a table of all defined memory regions, with the following
290
     columns for each region:
291
 
292
    _Memory Region Number_
293
 
294
    _Enabled or Disabled._
295
          Enabled memory regions are marked with `y'.  Disabled memory
296
          regions are marked with `n'.
297
 
298
    _Lo Address_
299
          The address defining the inclusive lower bound of the memory
300
          region.
301
 
302
    _Hi Address_
303
          The address defining the exclusive upper bound of the memory
304
          region.
305
 
306
    _Attributes_
307
          The list of attributes set for this memory region.
308
 
309
10.16.1 Attributes
310
------------------
311
 
312
10.16.1.1 Memory Access Mode
313
............................
314
 
315
The access mode attributes set whether GDB may make read or write
316
accesses to a memory region.
317
 
318
   While these attributes prevent GDB from performing invalid memory
319
accesses, they do nothing to prevent the target system, I/O DMA, etc.
320
from accessing memory.
321
 
322
`ro'
323
     Memory is read only.
324
 
325
`wo'
326
     Memory is write only.
327
 
328
`rw'
329
     Memory is read/write.  This is the default.
330
 
331
10.16.1.2 Memory Access Size
332
............................
333
 
334
The access size attribute tells GDB to use specific sized accesses in
335
the memory region.  Often memory mapped device registers require
336
specific sized accesses.  If no access size attribute is specified, GDB
337
may use accesses of any size.
338
 
339
`8'
340
     Use 8 bit memory accesses.
341
 
342
`16'
343
     Use 16 bit memory accesses.
344
 
345
`32'
346
     Use 32 bit memory accesses.
347
 
348
`64'
349
     Use 64 bit memory accesses.
350
 
351
10.16.1.3 Data Cache
352
....................
353
 
354
The data cache attributes set whether GDB will cache target memory.
355
While this generally improves performance by reducing debug protocol
356
overhead, it can lead to incorrect results because GDB does not know
357
about volatile variables or memory mapped device registers.
358
 
359
`cache'
360
     Enable GDB to cache target memory.
361
 
362
`nocache'
363
     Disable GDB from caching target memory.  This is the default.
364
 
365
10.16.2 Memory Access Checking
366
------------------------------
367
 
368
GDB can be instructed to refuse accesses to memory that is not
369
explicitly described.  This can be useful if accessing such regions has
370
undesired effects for a specific target, or to provide better error
371
checking.  The following commands control this behaviour.
372
 
373
`set mem inaccessible-by-default [on|off]'
374
     If `on' is specified, make  GDB treat memory not explicitly
375
     described by the memory ranges as non-existent and refuse accesses
376
     to such memory.  The checks are only performed if there's at least
377
     one memory range defined.  If `off' is specified, make GDB treat
378
     the memory not explicitly described by the memory ranges as RAM.
379
     The default value is `on'.
380
 
381
`show mem inaccessible-by-default'
382
     Show the current handling of accesses to unknown memory.
383
 
384

385
File: gdb.info,  Node: Dump/Restore Files,  Next: Core File Generation,  Prev: Memory Region Attributes,  Up: Data
386
 
387
10.17 Copy Between Memory and a File
388
====================================
389
 
390
You can use the commands `dump', `append', and `restore' to copy data
391
between target memory and a file.  The `dump' and `append' commands
392
write data to a file, and the `restore' command reads data from a file
393
back into the inferior's memory.  Files may be in binary, Motorola
394
S-record, Intel hex, or Tektronix Hex format; however, GDB can only
395
append to binary files.
396
 
397
`dump [FORMAT] memory FILENAME START_ADDR END_ADDR'
398
`dump [FORMAT] value FILENAME EXPR'
399
     Dump the contents of memory from START_ADDR to END_ADDR, or the
400
     value of EXPR, to FILENAME in the given format.
401
 
402
     The FORMAT parameter may be any one of:
403
    `binary'
404
          Raw binary form.
405
 
406
    `ihex'
407
          Intel hex format.
408
 
409
    `srec'
410
          Motorola S-record format.
411
 
412
    `tekhex'
413
          Tektronix Hex format.
414
 
415
     GDB uses the same definitions of these formats as the GNU binary
416
     utilities, like `objdump' and `objcopy'.  If FORMAT is omitted,
417
     GDB dumps the data in raw binary form.
418
 
419
`append [binary] memory FILENAME START_ADDR END_ADDR'
420
`append [binary] value FILENAME EXPR'
421
     Append the contents of memory from START_ADDR to END_ADDR, or the
422
     value of EXPR, to the file FILENAME, in raw binary form.  (GDB can
423
     only append data to files in raw binary form.)
424
 
425
`restore FILENAME [binary] BIAS START END'
426
     Restore the contents of file FILENAME into memory.  The `restore'
427
     command can automatically recognize any known BFD file format,
428
     except for raw binary.  To restore a raw binary file you must
429
     specify the optional keyword `binary' after the filename.
430
 
431
     If BIAS is non-zero, its value will be added to the addresses
432
     contained in the file.  Binary files always start at address zero,
433
     so they will be restored at address BIAS.  Other bfd files have a
434
     built-in location; they will be restored at offset BIAS from that
435
     location.
436
 
437
     If START and/or END are non-zero, then only data between file
438
     offset START and file offset END will be restored.  These offsets
439
     are relative to the addresses in the file, before the BIAS
440
     argument is applied.
441
 
442
 
443

444
File: gdb.info,  Node: Core File Generation,  Next: Character Sets,  Prev: Dump/Restore Files,  Up: Data
445
 
446
10.18 How to Produce a Core File from Your Program
447
==================================================
448
 
449
A "core file" or "core dump" is a file that records the memory image of
450
a running process and its process status (register values etc.).  Its
451
primary use is post-mortem debugging of a program that crashed while it
452
ran outside a debugger.  A program that crashes automatically produces
453
a core file, unless this feature is disabled by the user.  *Note
454
Files::, for information on invoking GDB in the post-mortem debugging
455
mode.
456
 
457
   Occasionally, you may wish to produce a core file of the program you
458
are debugging in order to preserve a snapshot of its state.  GDB has a
459
special command for that.
460
 
461
`generate-core-file [FILE]'
462
`gcore [FILE]'
463
     Produce a core dump of the inferior process.  The optional argument
464
     FILE specifies the file name where to put the core dump.  If not
465
     specified, the file name defaults to `core.PID', where PID is the
466
     inferior process ID.
467
 
468
     Note that this command is implemented only for some systems (as of
469
     this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390).
470
 
471

472
File: gdb.info,  Node: Character Sets,  Next: Caching Remote Data,  Prev: Core File Generation,  Up: Data
473
 
474
10.19 Character Sets
475
====================
476
 
477
If the program you are debugging uses a different character set to
478
represent characters and strings than the one GDB uses itself, GDB can
479
automatically translate between the character sets for you.  The
480
character set GDB uses we call the "host character set"; the one the
481
inferior program uses we call the "target character set".
482
 
483
   For example, if you are running GDB on a GNU/Linux system, which
484
uses the ISO Latin 1 character set, but you are using GDB's remote
485
protocol (*note Remote Debugging::) to debug a program running on an
486
IBM mainframe, which uses the EBCDIC character set, then the host
487
character set is Latin-1, and the target character set is EBCDIC.  If
488
you give GDB the command `set target-charset EBCDIC-US', then GDB
489
translates between EBCDIC and Latin 1 as you print character or string
490
values, or use character and string literals in expressions.
491
 
492
   GDB has no way to automatically recognize which character set the
493
inferior program uses; you must tell it, using the `set target-charset'
494
command, described below.
495
 
496
   Here are the commands for controlling GDB's character set support:
497
 
498
`set target-charset CHARSET'
499
     Set the current target character set to CHARSET.  To display the
500
     list of supported target character sets, type
501
     `set target-charset '.
502
 
503
`set host-charset CHARSET'
504
     Set the current host character set to CHARSET.
505
 
506
     By default, GDB uses a host character set appropriate to the
507
     system it is running on; you can override that default using the
508
     `set host-charset' command.  On some systems, GDB cannot
509
     automatically determine the appropriate host character set.  In
510
     this case, GDB uses `UTF-8'.
511
 
512
     GDB can only use certain character sets as its host character set.
513
     If you type `set target-charset ', GDB will list the
514
     host character sets it supports.
515
 
516
`set charset CHARSET'
517
     Set the current host and target character sets to CHARSET.  As
518
     above, if you type `set charset ', GDB will list the
519
     names of the character sets that can be used for both host and
520
     target.
521
 
522
`show charset'
523
     Show the names of the current host and target character sets.
524
 
525
`show host-charset'
526
     Show the name of the current host character set.
527
 
528
`show target-charset'
529
     Show the name of the current target character set.
530
 
531
`set target-wide-charset CHARSET'
532
     Set the current target's wide character set to CHARSET.  This is
533
     the character set used by the target's `wchar_t' type.  To display
534
     the list of supported wide character sets, type
535
     `set target-wide-charset '.
536
 
537
`show target-wide-charset'
538
     Show the name of the current target's wide character set.
539
 
540
   Here is an example of GDB's character set support in action.  Assume
541
that the following source code has been placed in the file
542
`charset-test.c':
543
 
544
     #include 
545
 
546
     char ascii_hello[]
547
       = {72, 101, 108, 108, 111, 44, 32, 119,
548
          111, 114, 108, 100, 33, 10, 0};
549
     char ibm1047_hello[]
550
       = {200, 133, 147, 147, 150, 107, 64, 166,
551
          150, 153, 147, 132, 90, 37, 0};
552
 
553
     main ()
554
     {
555
       printf ("Hello, world!\n");
556
     }
557
 
558
   In this program, `ascii_hello' and `ibm1047_hello' are arrays
559
containing the string `Hello, world!' followed by a newline, encoded in
560
the ASCII and IBM1047 character sets.
561
 
562
   We compile the program, and invoke the debugger on it:
563
 
564
     $ gcc -g charset-test.c -o charset-test
565
     $ gdb -nw charset-test
566
     GNU gdb 2001-12-19-cvs
567
     Copyright 2001 Free Software Foundation, Inc.
568
     ...
569
     (gdb)
570
 
571
   We can use the `show charset' command to see what character sets GDB
572
is currently using to interpret and display characters and strings:
573
 
574
     (gdb) show charset
575
     The current host and target character set is `ISO-8859-1'.
576
     (gdb)
577
 
578
   For the sake of printing this manual, let's use ASCII as our initial
579
character set:
580
     (gdb) set charset ASCII
581
     (gdb) show charset
582
     The current host and target character set is `ASCII'.
583
     (gdb)
584
 
585
   Let's assume that ASCII is indeed the correct character set for our
586
host system -- in other words, let's assume that if GDB prints
587
characters using the ASCII character set, our terminal will display
588
them properly.  Since our current target character set is also ASCII,
589
the contents of `ascii_hello' print legibly:
590
 
591
     (gdb) print ascii_hello
592
     $1 = 0x401698 "Hello, world!\n"
593
     (gdb) print ascii_hello[0]
594
     $2 = 72 'H'
595
     (gdb)
596
 
597
   GDB uses the target character set for character and string literals
598
you use in expressions:
599
 
600
     (gdb) print '+'
601
     $3 = 43 '+'
602
     (gdb)
603
 
604
   The ASCII character set uses the number 43 to encode the `+'
605
character.
606
 
607
   GDB relies on the user to tell it which character set the target
608
program uses.  If we print `ibm1047_hello' while our target character
609
set is still ASCII, we get jibberish:
610
 
611
     (gdb) print ibm1047_hello
612
     $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%"
613
     (gdb) print ibm1047_hello[0]
614
     $5 = 200 '\310'
615
     (gdb)
616
 
617
   If we invoke the `set target-charset' followed by , GDB
618
tells us the character sets it supports:
619
 
620
     (gdb) set target-charset
621
     ASCII       EBCDIC-US   IBM1047     ISO-8859-1
622
     (gdb) set target-charset
623
 
624
   We can select IBM1047 as our target character set, and examine the
625
program's strings again.  Now the ASCII string is wrong, but GDB
626
translates the contents of `ibm1047_hello' from the target character
627
set, IBM1047, to the host character set, ASCII, and they display
628
correctly:
629
 
630
     (gdb) set target-charset IBM1047
631
     (gdb) show charset
632
     The current host character set is `ASCII'.
633
     The current target character set is `IBM1047'.
634
     (gdb) print ascii_hello
635
     $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
636
     (gdb) print ascii_hello[0]
637
     $7 = 72 '\110'
638
     (gdb) print ibm1047_hello
639
     $8 = 0x4016a8 "Hello, world!\n"
640
     (gdb) print ibm1047_hello[0]
641
     $9 = 200 'H'
642
     (gdb)
643
 
644
   As above, GDB uses the target character set for character and string
645
literals you use in expressions:
646
 
647
     (gdb) print '+'
648
     $10 = 78 '+'
649
     (gdb)
650
 
651
   The IBM1047 character set uses the number 78 to encode the `+'
652
character.
653
 
654

655
File: gdb.info,  Node: Caching Remote Data,  Next: Searching Memory,  Prev: Character Sets,  Up: Data
656
 
657
10.20 Caching Data of Remote Targets
658
====================================
659
 
660
GDB caches data exchanged between the debugger and a remote target
661
(*note Remote Debugging::).  Such caching generally improves
662
performance, because it reduces the overhead of the remote protocol by
663
bundling memory reads and writes into large chunks.  Unfortunately,
664
simply caching everything would lead to incorrect results, since GDB
665
does not necessarily know anything about volatile values, memory-mapped
666
I/O addresses, etc.  Furthermore, in non-stop mode (*note Non-Stop
667
Mode::) memory can be changed _while_ a gdb command is executing.
668
Therefore, by default, GDB only caches data known to be on the stack(1).
669
Other regions of memory can be explicitly marked as cacheable; see
670
*note Memory Region Attributes::.
671
 
672
`set remotecache on'
673
`set remotecache off'
674
     This option no longer does anything; it exists for compatibility
675
     with old scripts.
676
 
677
`show remotecache'
678
     Show the current state of the obsolete remotecache flag.
679
 
680
`set stack-cache on'
681
`set stack-cache off'
682
     Enable or disable caching of stack accesses.  When `ON', use
683
     caching.  By default, this option is `ON'.
684
 
685
`show stack-cache'
686
     Show the current state of data caching for memory accesses.
687
 
688
`info dcache [line]'
689
     Print the information about the data cache performance.  The
690
     information displayed includes the dcache width and depth, and for
691
     each cache line, its number, address, and how many times it was
692
     referenced.  This command is useful for debugging the data cache
693
     operation.
694
 
695
     If a line number is specified, the contents of that line will be
696
     printed in hex.
697
 
698
   ---------- Footnotes ----------
699
 
700
   (1) In non-stop mode, it is moderately rare for a running thread to
701
modify the stack of a stopped thread in a way that would interfere with
702
a backtrace, and caching of stack reads provides a significant speed up
703
of remote backtraces.
704
 
705

706
File: gdb.info,  Node: Searching Memory,  Prev: Caching Remote Data,  Up: Data
707
 
708
10.21 Search Memory
709
===================
710
 
711
Memory can be searched for a particular sequence of bytes with the
712
`find' command.
713
 
714
`find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]'
715
`find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]'
716
     Search memory for the sequence of bytes specified by VAL1, VAL2,
717
     etc.  The search begins at address START_ADDR and continues for
718
     either LEN bytes or through to END_ADDR inclusive.
719
 
720
   S and N are optional parameters.  They may be specified in either
721
order, apart or together.
722
 
723
S, search query size
724
     The size of each search query value.
725
 
726
    `b'
727
          bytes
728
 
729
    `h'
730
          halfwords (two bytes)
731
 
732
    `w'
733
          words (four bytes)
734
 
735
    `g'
736
          giant words (eight bytes)
737
 
738
     All values are interpreted in the current language.  This means,
739
     for example, that if the current source language is C/C++ then
740
     searching for the string "hello" includes the trailing '\0'.
741
 
742
     If the value size is not specified, it is taken from the value's
743
     type in the current language.  This is useful when one wants to
744
     specify the search pattern as a mixture of types.  Note that this
745
     means, for example, that in the case of C-like languages a search
746
     for an untyped 0x42 will search for `(int) 0x42' which is
747
     typically four bytes.
748
 
749
N, maximum number of finds
750
     The maximum number of matches to print.  The default is to print
751
     all finds.
752
 
753
   You can use strings as search values.  Quote them with double-quotes
754 342 jeremybenn
(`"').  The string value is copied into the search pattern byte by byte,
755
regardless of the endianness of the target and the size specification.
756 330 jeremybenn
 
757
   The address of each match found is printed as well as a count of the
758
number of matches found.
759
 
760
   The address of the last value found is stored in convenience variable
761
`$_'.  A count of the number of matches is stored in `$numfound'.
762
 
763
   For example, if stopped at the `printf' in this function:
764
 
765
     void
766
     hello ()
767
     {
768
       static char hello[] = "hello-hello";
769
       static struct { char c; short s; int i; }
770
         __attribute__ ((packed)) mixed
771
         = { 'c', 0x1234, 0x87654321 };
772
       printf ("%s\n", hello);
773
     }
774
 
775
you get during debugging:
776
 
777
     (gdb) find &hello[0], +sizeof(hello), "hello"
778
     0x804956d 
779
     1 pattern found
780
     (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
781
     0x8049567 
782
     0x804956d 
783
     2 patterns found
784
     (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
785
     0x8049567 
786
     1 pattern found
787
     (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
788
     0x8049560 
789
     1 pattern found
790
     (gdb) print $numfound
791
     $1 = 1
792
     (gdb) print $_
793
     $2 = (void *) 0x8049560
794
 
795

796
File: gdb.info,  Node: Optimized Code,  Next: Macros,  Prev: Data,  Up: Top
797
 
798
11 Debugging Optimized Code
799
***************************
800
 
801
Almost all compilers support optimization.  With optimization disabled,
802
the compiler generates assembly code that corresponds directly to your
803
source code, in a simplistic way.  As the compiler applies more
804
powerful optimizations, the generated assembly code diverges from your
805
original source code.  With help from debugging information generated
806
by the compiler, GDB can map from the running program back to
807
constructs from your original source.
808
 
809
   GDB is more accurate with optimization disabled.  If you can
810
recompile without optimization, it is easier to follow the progress of
811
your program during debugging.  But, there are many cases where you may
812
need to debug an optimized version.
813
 
814
   When you debug a program compiled with `-g -O', remember that the
815
optimizer has rearranged your code; the debugger shows you what is
816
really there.  Do not be too surprised when the execution path does not
817
exactly match your source file!  An extreme example: if you define a
818
variable, but never use it, GDB never sees that variable--because the
819
compiler optimizes it out of existence.
820
 
821
   Some things do not work as well with `-g -O' as with just `-g',
822
particularly on machines with instruction scheduling.  If in doubt,
823
recompile with `-g' alone, and if this fixes the problem, please report
824
it to us as a bug (including a test case!).  *Note Variables::, for
825
more information about debugging optimized code.
826
 
827
* Menu:
828
 
829
* Inline Functions::            How GDB presents inlining
830
 
831

832
File: gdb.info,  Node: Inline Functions,  Up: Optimized Code
833
 
834
11.1 Inline Functions
835
=====================
836
 
837
"Inlining" is an optimization that inserts a copy of the function body
838
directly at each call site, instead of jumping to a shared routine.
839
GDB displays inlined functions just like non-inlined functions.  They
840
appear in backtraces.  You can view their arguments and local
841
variables, step into them with `step', skip them with `next', and
842
escape from them with `finish'.  You can check whether a function was
843
inlined by using the `info frame' command.
844
 
845
   For GDB to support inlined functions, the compiler must record
846
information about inlining in the debug information -- GCC using the
847
DWARF 2 format does this, and several other compilers do also.  GDB
848
only supports inlined functions when using DWARF 2.  Versions of GCC
849
before 4.1 do not emit two required attributes (`DW_AT_call_file' and
850
`DW_AT_call_line'); GDB does not display inlined function calls with
851
earlier versions of GCC.  It instead displays the arguments and local
852
variables of inlined functions as local variables in the caller.
853
 
854
   The body of an inlined function is directly included at its call
855
site; unlike a non-inlined function, there are no instructions devoted
856
to the call.  GDB still pretends that the call site and the start of
857
the inlined function are different instructions.  Stepping to the call
858
site shows the call site, and then stepping again shows the first line
859
of the inlined function, even though no additional instructions are
860
executed.
861
 
862
   This makes source-level debugging much clearer; you can see both the
863
context of the call and then the effect of the call.  Only stepping by
864
a single instruction using `stepi' or `nexti' does not do this; single
865
instruction steps always show the inlined body.
866
 
867
   There are some ways that GDB does not pretend that inlined function
868
calls are the same as normal calls:
869
 
870
   * You cannot set breakpoints on inlined functions.  GDB either
871
     reports that there is no symbol with that name, or else sets the
872
     breakpoint only on non-inlined copies of the function.  This
873
     limitation will be removed in a future version of GDB; until then,
874
     set a breakpoint by line number on the first line of the inlined
875
     function instead.
876
 
877
   * Setting breakpoints at the call site of an inlined function may not
878
     work, because the call site does not contain any code.  GDB may
879
     incorrectly move the breakpoint to the next line of the enclosing
880
     function, after the call.  This limitation will be removed in a
881
     future version of GDB; until then, set a breakpoint on an earlier
882
     line or inside the inlined function instead.
883
 
884
   * GDB cannot locate the return value of inlined calls after using
885
     the `finish' command.  This is a limitation of compiler-generated
886
     debugging information; after `finish', you can step to the next
887
     line and print a variable where your program stored the return
888
     value.
889
 
890
 
891

892
File: gdb.info,  Node: Macros,  Next: Tracepoints,  Prev: Optimized Code,  Up: Top
893
 
894
12 C Preprocessor Macros
895
************************
896
 
897
Some languages, such as C and C++, provide a way to define and invoke
898
"preprocessor macros" which expand into strings of tokens.  GDB can
899
evaluate expressions containing macro invocations, show the result of
900
macro expansion, and show a macro's definition, including where it was
901
defined.
902
 
903
   You may need to compile your program specially to provide GDB with
904
information about preprocessor macros.  Most compilers do not include
905
macros in their debugging information, even when you compile with the
906
`-g' flag.  *Note Compilation::.
907
 
908
   A program may define a macro at one point, remove that definition
909
later, and then provide a different definition after that.  Thus, at
910
different points in the program, a macro may have different
911
definitions, or have no definition at all.  If there is a current stack
912
frame, GDB uses the macros in scope at that frame's source code line.
913
Otherwise, GDB uses the macros in scope at the current listing location;
914 342 jeremybenn
see *note List::.
915 330 jeremybenn
 
916
   Whenever GDB evaluates an expression, it always expands any macro
917
invocations present in the expression.  GDB also provides the following
918
commands for working with macros explicitly.
919
 
920
`macro expand EXPRESSION'
921
`macro exp EXPRESSION'
922
     Show the results of expanding all preprocessor macro invocations in
923
     EXPRESSION.  Since GDB simply expands macros, but does not parse
924
     the result, EXPRESSION need not be a valid expression; it can be
925
     any string of tokens.
926
 
927
`macro expand-once EXPRESSION'
928
`macro exp1 EXPRESSION'
929
     (This command is not yet implemented.)  Show the results of
930
     expanding those preprocessor macro invocations that appear
931
     explicitly in EXPRESSION.  Macro invocations appearing in that
932
     expansion are left unchanged.  This command allows you to see the
933
     effect of a particular macro more clearly, without being confused
934
     by further expansions.  Since GDB simply expands macros, but does
935
     not parse the result, EXPRESSION need not be a valid expression; it
936
     can be any string of tokens.
937
 
938
`info macro MACRO'
939
     Show the definition of the macro named MACRO, and describe the
940
     source location or compiler command-line where that definition was
941
     established.
942
 
943
`macro define MACRO REPLACEMENT-LIST'
944
`macro define MACRO(ARGLIST) REPLACEMENT-LIST'
945
     Introduce a definition for a preprocessor macro named MACRO,
946
     invocations of which are replaced by the tokens given in
947
     REPLACEMENT-LIST.  The first form of this command defines an
948
     "object-like" macro, which takes no arguments; the second form
949
     defines a "function-like" macro, which takes the arguments given in
950
     ARGLIST.
951
 
952
     A definition introduced by this command is in scope in every
953
     expression evaluated in GDB, until it is removed with the `macro
954
     undef' command, described below.  The definition overrides all
955
     definitions for MACRO present in the program being debugged, as
956
     well as any previous user-supplied definition.
957
 
958
`macro undef MACRO'
959
     Remove any user-supplied definition for the macro named MACRO.
960
     This command only affects definitions provided with the `macro
961
     define' command, described above; it cannot remove definitions
962
     present in the program being debugged.
963
 
964
`macro list'
965
     List all the macros defined using the `macro define' command.
966
 
967
   Here is a transcript showing the above commands in action.  First, we
968
show our source files:
969
 
970
     $ cat sample.c
971
     #include 
972
     #include "sample.h"
973
 
974
     #define M 42
975
     #define ADD(x) (M + x)
976
 
977
     main ()
978
     {
979
     #define N 28
980
       printf ("Hello, world!\n");
981
     #undef N
982
       printf ("We're so creative.\n");
983
     #define N 1729
984
       printf ("Goodbye, world!\n");
985
     }
986
     $ cat sample.h
987
     #define Q <
988
     $
989
 
990
   Now, we compile the program using the GNU C compiler, GCC.  We pass
991
the `-gdwarf-2' and `-g3' flags to ensure the compiler includes
992
information about preprocessor macros in the debugging information.
993
 
994
     $ gcc -gdwarf-2 -g3 sample.c -o sample
995
     $
996
 
997
   Now, we start GDB on our sample program:
998
 
999
     $ gdb -nw sample
1000
     GNU gdb 2002-05-06-cvs
1001
     Copyright 2002 Free Software Foundation, Inc.
1002
     GDB is free software, ...
1003
     (gdb)
1004
 
1005
   We can expand macros and examine their definitions, even when the
1006
program is not running.  GDB uses the current listing position to
1007
decide which macro definitions are in scope:
1008
 
1009
     (gdb) list main
1010
     3
1011
     4       #define M 42
1012
     5       #define ADD(x) (M + x)
1013
     6
1014
     7       main ()
1015
     8       {
1016
     9       #define N 28
1017
     10        printf ("Hello, world!\n");
1018
     11      #undef N
1019
     12        printf ("We're so creative.\n");
1020
     (gdb) info macro ADD
1021
     Defined at /home/jimb/gdb/macros/play/sample.c:5
1022
     #define ADD(x) (M + x)
1023
     (gdb) info macro Q
1024
     Defined at /home/jimb/gdb/macros/play/sample.h:1
1025
       included at /home/jimb/gdb/macros/play/sample.c:2
1026
     #define Q <
1027
     (gdb) macro expand ADD(1)
1028
     expands to: (42 + 1)
1029
     (gdb) macro expand-once ADD(1)
1030
     expands to: once (M + 1)
1031
     (gdb)
1032
 
1033
   In the example above, note that `macro expand-once' expands only the
1034
macro invocation explicit in the original text -- the invocation of
1035
`ADD' -- but does not expand the invocation of the macro `M', which was
1036
introduced by `ADD'.
1037
 
1038
   Once the program is running, GDB uses the macro definitions in force
1039
at the source line of the current stack frame:
1040
 
1041
     (gdb) break main
1042
     Breakpoint 1 at 0x8048370: file sample.c, line 10.
1043
     (gdb) run
1044
     Starting program: /home/jimb/gdb/macros/play/sample
1045
 
1046
     Breakpoint 1, main () at sample.c:10
1047
     10        printf ("Hello, world!\n");
1048
     (gdb)
1049
 
1050
   At line 10, the definition of the macro `N' at line 9 is in force:
1051
 
1052
     (gdb) info macro N
1053
     Defined at /home/jimb/gdb/macros/play/sample.c:9
1054
     #define N 28
1055
     (gdb) macro expand N Q M
1056
     expands to: 28 < 42
1057
     (gdb) print N Q M
1058
     $1 = 1
1059
     (gdb)
1060
 
1061
   As we step over directives that remove `N''s definition, and then
1062
give it a new definition, GDB finds the definition (or lack thereof) in
1063
force at each point:
1064
 
1065
     (gdb) next
1066
     Hello, world!
1067
     12        printf ("We're so creative.\n");
1068
     (gdb) info macro N
1069
     The symbol `N' has no definition as a C/C++ preprocessor macro
1070
     at /home/jimb/gdb/macros/play/sample.c:12
1071
     (gdb) next
1072
     We're so creative.
1073
     14        printf ("Goodbye, world!\n");
1074
     (gdb) info macro N
1075
     Defined at /home/jimb/gdb/macros/play/sample.c:13
1076
     #define N 1729
1077
     (gdb) macro expand N Q M
1078
     expands to: 1729 < 42
1079
     (gdb) print N Q M
1080
     $2 = 0
1081
     (gdb)
1082
 
1083
   In addition to source files, macros can be defined on the
1084
compilation command line using the `-DNAME=VALUE' syntax.  For macros
1085
defined in such a way, GDB displays the location of their definition as
1086
line zero of the source file submitted to the compiler.
1087
 
1088
     (gdb) info macro __STDC__
1089
     Defined at /home/jimb/gdb/macros/play/sample.c:0
1090
     -D__STDC__=1
1091
     (gdb)
1092
 
1093

1094
File: gdb.info,  Node: Tracepoints,  Next: Overlays,  Prev: Macros,  Up: Top
1095
 
1096
13 Tracepoints
1097
**************
1098
 
1099
In some applications, it is not feasible for the debugger to interrupt
1100
the program's execution long enough for the developer to learn anything
1101
helpful about its behavior.  If the program's correctness depends on
1102
its real-time behavior, delays introduced by a debugger might cause the
1103
program to change its behavior drastically, or perhaps fail, even when
1104
the code itself is correct.  It is useful to be able to observe the
1105
program's behavior without interrupting it.
1106
 
1107
   Using GDB's `trace' and `collect' commands, you can specify
1108
locations in the program, called "tracepoints", and arbitrary
1109
expressions to evaluate when those tracepoints are reached.  Later,
1110
using the `tfind' command, you can examine the values those expressions
1111
had when the program hit the tracepoints.  The expressions may also
1112
denote objects in memory--structures or arrays, for example--whose
1113
values GDB should record; while visiting a particular tracepoint, you
1114
may inspect those objects as if they were in memory at that moment.
1115
However, because GDB records these values without interacting with you,
1116
it can do so quickly and unobtrusively, hopefully not disturbing the
1117
program's behavior.
1118
 
1119
   The tracepoint facility is currently available only for remote
1120
targets.  *Note Targets::.  In addition, your remote target must know
1121
how to collect trace data.  This functionality is implemented in the
1122
remote stub; however, none of the stubs distributed with GDB support
1123
tracepoints as of this writing.  The format of the remote packets used
1124 342 jeremybenn
to implement tracepoints are described in *note Tracepoint Packets::.
1125 330 jeremybenn
 
1126
   It is also possible to get trace data from a file, in a manner
1127
reminiscent of corefiles; you specify the filename, and use `tfind' to
1128
search through the file.  *Note Trace Files::, for more details.
1129
 
1130
   This chapter describes the tracepoint commands and features.
1131
 
1132
* Menu:
1133
 
1134
* Set Tracepoints::
1135
* Analyze Collected Data::
1136
* Tracepoint Variables::
1137
* Trace Files::
1138
 
1139

1140
File: gdb.info,  Node: Set Tracepoints,  Next: Analyze Collected Data,  Up: Tracepoints
1141
 
1142
13.1 Commands to Set Tracepoints
1143
================================
1144
 
1145
Before running such a "trace experiment", an arbitrary number of
1146
tracepoints can be set.  A tracepoint is actually a special type of
1147
breakpoint (*note Set Breaks::), so you can manipulate it using
1148
standard breakpoint commands.  For instance, as with breakpoints,
1149
tracepoint numbers are successive integers starting from one, and many
1150
of the commands associated with tracepoints take the tracepoint number
1151
as their argument, to identify which tracepoint to work on.
1152
 
1153
   For each tracepoint, you can specify, in advance, some arbitrary set
1154
of data that you want the target to collect in the trace buffer when it
1155
hits that tracepoint.  The collected data can include registers, local
1156
variables, or global data.  Later, you can use GDB commands to examine
1157
the values these data had at the time the tracepoint was hit.
1158
 
1159
   Tracepoints do not support every breakpoint feature.  Ignore counts
1160
on tracepoints have no effect, and tracepoints cannot run GDB commands
1161
when they are hit.  Tracepoints may not be thread-specific either.
1162
 
1163
   Some targets may support "fast tracepoints", which are inserted in a
1164
different way (such as with a jump instead of a trap), that is faster
1165
but possibly restricted in where they may be installed.
1166
 
1167
   Regular and fast tracepoints are dynamic tracing facilities, meaning
1168
that they can be used to insert tracepoints at (almost) any location in
1169
the target.  Some targets may also support controlling "static
1170
tracepoints" from GDB.  With static tracing, a set of instrumentation
1171
points, also known as "markers", are embedded in the target program,
1172
and can be activated or deactivated by name or address.  These are
1173
usually placed at locations which facilitate investigating what the
1174
target is actually doing.  GDB's support for static tracing includes
1175
being able to list instrumentation points, and attach them with GDB
1176
defined high level tracepoints that expose the whole range of
1177
convenience of GDB's tracepoints support.  Namelly, support for
1178
collecting registers values and values of global or local (to the
1179
instrumentation point) variables; tracepoint conditions and trace state
1180
variables.  The act of installing a GDB static tracepoint on an
1181
instrumentation point, or marker, is referred to as "probing" a static
1182
tracepoint marker.
1183
 
1184
   `gdbserver' supports tracepoints on some target systems.  *Note
1185
Tracepoints support in `gdbserver': Server.
1186
 
1187
   This section describes commands to set tracepoints and associated
1188
conditions and actions.
1189
 
1190
* Menu:
1191
 
1192
* Create and Delete Tracepoints::
1193
* Enable and Disable Tracepoints::
1194
* Tracepoint Passcounts::
1195
* Tracepoint Conditions::
1196
* Trace State Variables::
1197
* Tracepoint Actions::
1198
* Listing Tracepoints::
1199
* Listing Static Tracepoint Markers::
1200
* Starting and Stopping Trace Experiments::
1201
* Tracepoint Restrictions::
1202
 
1203

1204
File: gdb.info,  Node: Create and Delete Tracepoints,  Next: Enable and Disable Tracepoints,  Up: Set Tracepoints
1205
 
1206
13.1.1 Create and Delete Tracepoints
1207
------------------------------------
1208
 
1209
`trace LOCATION'
1210
     The `trace' command is very similar to the `break' command.  Its
1211
     argument LOCATION can be a source line, a function name, or an
1212
     address in the target program.  *Note Specify Location::.  The
1213
     `trace' command defines a tracepoint, which is a point in the
1214
     target program where the debugger will briefly stop, collect some
1215
     data, and then allow the program to continue.  Setting a
1216
     tracepoint or changing its actions doesn't take effect until the
1217
     next `tstart' command, and once a trace experiment is running,
1218
     further changes will not have any effect until the next trace
1219
     experiment starts.
1220
 
1221
     Here are some examples of using the `trace' command:
1222
 
1223
          (gdb) trace foo.c:121    // a source file and line number
1224
 
1225
          (gdb) trace +2           // 2 lines forward
1226
 
1227
          (gdb) trace my_function  // first source line of function
1228
 
1229
          (gdb) trace *my_function // EXACT start address of function
1230
 
1231
          (gdb) trace *0x2117c4    // an address
1232
 
1233
     You can abbreviate `trace' as `tr'.
1234
 
1235
`trace LOCATION if COND'
1236
     Set a tracepoint with condition COND; evaluate the expression COND
1237
     each time the tracepoint is reached, and collect data only if the
1238
     value is nonzero--that is, if COND evaluates as true.  *Note
1239
     Tracepoint Conditions: Tracepoint Conditions, for more information
1240
     on tracepoint conditions.
1241
 
1242
`ftrace LOCATION [ if COND ]'
1243
     The `ftrace' command sets a fast tracepoint.  For targets that
1244
     support them, fast tracepoints will use a more efficient but
1245
     possibly less general technique to trigger data collection, such
1246
     as a jump instruction instead of a trap, or some sort of hardware
1247
     support.  It may not be possible to create a fast tracepoint at
1248
     the desired location, in which case the command will exit with an
1249
     explanatory message.
1250
 
1251
     GDB handles arguments to `ftrace' exactly as for `trace'.
1252
 
1253
`strace LOCATION [ if COND ]'
1254
     The `strace' command sets a static tracepoint.  For targets that
1255
     support it, setting a static tracepoint probes a static
1256
     instrumentation point, or marker, found at LOCATION.  It may not
1257
     be possible to set a static tracepoint at the desired location, in
1258
     which case the command will exit with an explanatory message.
1259
 
1260
     GDB handles arguments to `strace' exactly as for `trace', with the
1261
     addition that the user can also specify `-m MARKER' as LOCATION.
1262
     This probes the marker identified by the MARKER string identifier.
1263
     This identifier depends on the static tracepoint backend library
1264
     your program is using.  You can find all the marker identifiers in
1265
     the `ID' field of the `info static-tracepoint-markers' command
1266
     output.  *Note Listing Static Tracepoint Markers: Listing Static
1267
     Tracepoint Markers.  For example, in the following small program
1268
     using the UST tracing engine:
1269
 
1270
          main ()
1271
          {
1272
            trace_mark(ust, bar33, "str %s", "FOOBAZ");
1273
          }
1274
 
1275
     the marker id is composed of joining the first two arguments to the
1276
     `trace_mark' call with a slash, which translates to:
1277
 
1278
          (gdb) info static-tracepoint-markers
1279
          Cnt Enb ID         Address            What
1280
          1   n   ust/bar33  0x0000000000400ddc in main at stexample.c:22
1281
                   Data: "str %s"
1282
          [etc...]
1283
 
1284
     so you may probe the marker above with:
1285
 
1286
          (gdb) strace -m ust/bar33
1287
 
1288
     Static tracepoints accept an extra collect action -- `collect
1289
     $_sdata'.  This collects arbitrary user data passed in the probe
1290
     point call to the tracing library.  In the UST example above,
1291
     you'll see that the third argument to `trace_mark' is a
1292
     printf-like format string.  The user data is then the result of
1293
     running that formating string against the following arguments.
1294
     Note that `info static-tracepoint-markers' command output lists
1295
     that format string in the `Data:' field.
1296
 
1297
     You can inspect this data when analyzing the trace buffer, by
1298
     printing the $_sdata variable like any other variable available to
1299
     GDB.  *Note Tracepoint Action Lists: Tracepoint Actions.
1300
 
1301
     The convenience variable `$tpnum' records the tracepoint number of
1302
     the most recently set tracepoint.
1303
 
1304
`delete tracepoint [NUM]'
1305
     Permanently delete one or more tracepoints.  With no argument, the
1306
     default is to delete all tracepoints.  Note that the regular
1307
     `delete' command can remove tracepoints also.
1308
 
1309
     Examples:
1310
 
1311
          (gdb) delete trace 1 2 3 // remove three tracepoints
1312
 
1313
          (gdb) delete trace       // remove all tracepoints
1314
 
1315
     You can abbreviate this command as `del tr'.
1316
 
1317

1318
File: gdb.info,  Node: Enable and Disable Tracepoints,  Next: Tracepoint Passcounts,  Prev: Create and Delete Tracepoints,  Up: Set Tracepoints
1319
 
1320
13.1.2 Enable and Disable Tracepoints
1321
-------------------------------------
1322
 
1323
These commands are deprecated; they are equivalent to plain `disable'
1324
and `enable'.
1325
 
1326
`disable tracepoint [NUM]'
1327
     Disable tracepoint NUM, or all tracepoints if no argument NUM is
1328
     given.  A disabled tracepoint will have no effect during the next
1329
     trace experiment, but it is not forgotten.  You can re-enable a
1330
     disabled tracepoint using the `enable tracepoint' command.
1331
 
1332
`enable tracepoint [NUM]'
1333
     Enable tracepoint NUM, or all tracepoints.  The enabled
1334
     tracepoints will become effective the next time a trace experiment
1335
     is run.
1336
 
1337

1338
File: gdb.info,  Node: Tracepoint Passcounts,  Next: Tracepoint Conditions,  Prev: Enable and Disable Tracepoints,  Up: Set Tracepoints
1339
 
1340
13.1.3 Tracepoint Passcounts
1341
----------------------------
1342
 
1343
`passcount [N [NUM]]'
1344
     Set the "passcount" of a tracepoint.  The passcount is a way to
1345
     automatically stop a trace experiment.  If a tracepoint's
1346
     passcount is N, then the trace experiment will be automatically
1347
     stopped on the N'th time that tracepoint is hit.  If the
1348
     tracepoint number NUM is not specified, the `passcount' command
1349
     sets the passcount of the most recently defined tracepoint.  If no
1350
     passcount is given, the trace experiment will run until stopped
1351
     explicitly by the user.
1352
 
1353
     Examples:
1354
 
1355
          (gdb) passcount 5 2 // Stop on the 5th execution of
1356
                                        `// tracepoint 2'
1357
 
1358
          (gdb) passcount 12  // Stop on the 12th execution of the
1359
                                        `// most recently defined tracepoint.'
1360
          (gdb) trace foo
1361
          (gdb) pass 3
1362
          (gdb) trace bar
1363
          (gdb) pass 2
1364
          (gdb) trace baz
1365
          (gdb) pass 1        // Stop tracing when foo has been
1366
                                         `// executed 3 times OR when bar has'
1367
                                         `// been executed 2 times'
1368
                                         `// OR when baz has been executed 1 time.'
1369
 
1370
 
1371

1372
File: gdb.info,  Node: Tracepoint Conditions,  Next: Trace State Variables,  Prev: Tracepoint Passcounts,  Up: Set Tracepoints
1373
 
1374
13.1.4 Tracepoint Conditions
1375
----------------------------
1376
 
1377
The simplest sort of tracepoint collects data every time your program
1378
reaches a specified place.  You can also specify a "condition" for a
1379
tracepoint.  A condition is just a Boolean expression in your
1380
programming language (*note Expressions: Expressions.).  A tracepoint
1381
with a condition evaluates the expression each time your program
1382
reaches it, and data collection happens only if the condition is true.
1383
 
1384
   Tracepoint conditions can be specified when a tracepoint is set, by
1385
using `if' in the arguments to the `trace' command.  *Note Setting
1386
Tracepoints: Create and Delete Tracepoints.  They can also be set or
1387
changed at any time with the `condition' command, just as with
1388
breakpoints.
1389
 
1390
   Unlike breakpoint conditions, GDB does not actually evaluate the
1391
conditional expression itself.  Instead, GDB encodes the expression
1392
into an agent expression (*note Agent Expressions:: suitable for
1393
execution on the target, independently of GDB.  Global variables become
1394
raw memory locations, locals become stack accesses, and so forth.
1395
 
1396
   For instance, suppose you have a function that is usually called
1397
frequently, but should not be called after an error has occurred.  You
1398
could use the following tracepoint command to collect data about calls
1399
of that function that happen while the error code is propagating
1400
through the program; an unconditional tracepoint could end up
1401
collecting thousands of useless trace frames that you would have to
1402
search through.
1403
 
1404
     (gdb) trace normal_operation if errcode > 0
1405
 
1406

1407
File: gdb.info,  Node: Trace State Variables,  Next: Tracepoint Actions,  Prev: Tracepoint Conditions,  Up: Set Tracepoints
1408
 
1409
13.1.5 Trace State Variables
1410
----------------------------
1411
 
1412
A "trace state variable" is a special type of variable that is created
1413
and managed by target-side code.  The syntax is the same as that for
1414
GDB's convenience variables (a string prefixed with "$"), but they are
1415
stored on the target.  They must be created explicitly, using a
1416
`tvariable' command.  They are always 64-bit signed integers.
1417
 
1418
   Trace state variables are remembered by GDB, and downloaded to the
1419
target along with tracepoint information when the trace experiment
1420
starts.  There are no intrinsic limits on the number of trace state
1421
variables, beyond memory limitations of the target.
1422
 
1423
   Although trace state variables are managed by the target, you can use
1424
them in print commands and expressions as if they were convenience
1425
variables; GDB will get the current value from the target while the
1426
trace experiment is running.  Trace state variables share the same
1427
namespace as other "$" variables, which means that you cannot have
1428
trace state variables with names like `$23' or `$pc', nor can you have
1429
a trace state variable and a convenience variable with the same name.
1430
 
1431
`tvariable $NAME [ = EXPRESSION ]'
1432
     The `tvariable' command creates a new trace state variable named
1433
     `$NAME', and optionally gives it an initial value of EXPRESSION.
1434
     EXPRESSION is evaluated when this command is entered; the result
1435
     will be converted to an integer if possible, otherwise GDB will
1436
     report an error. A subsequent `tvariable' command specifying the
1437
     same name does not create a variable, but instead assigns the
1438
     supplied initial value to the existing variable of that name,
1439
     overwriting any previous initial value. The default initial value
1440
     is 0.
1441
 
1442
`info tvariables'
1443
     List all the trace state variables along with their initial values.
1444
     Their current values may also be displayed, if the trace
1445
     experiment is currently running.
1446
 
1447
`delete tvariable [ $NAME ... ]'
1448
     Delete the given trace state variables, or all of them if no
1449
     arguments are specified.
1450
 
1451
 
1452

1453
File: gdb.info,  Node: Tracepoint Actions,  Next: Listing Tracepoints,  Prev: Trace State Variables,  Up: Set Tracepoints
1454
 
1455
13.1.6 Tracepoint Action Lists
1456
------------------------------
1457
 
1458
`actions [NUM]'
1459
     This command will prompt for a list of actions to be taken when the
1460
     tracepoint is hit.  If the tracepoint number NUM is not specified,
1461
     this command sets the actions for the one that was most recently
1462
     defined (so that you can define a tracepoint and then say
1463
     `actions' without bothering about its number).  You specify the
1464
     actions themselves on the following lines, one action at a time,
1465
     and terminate the actions list with a line containing just `end'.
1466
     So far, the only defined actions are `collect', `teval', and
1467
     `while-stepping'.
1468
 
1469
     `actions' is actually equivalent to `commands' (*note Breakpoint
1470
     Command Lists: Break Commands.), except that only the defined
1471
     actions are allowed; any other GDB command is rejected.
1472
 
1473
     To remove all actions from a tracepoint, type `actions NUM' and
1474
     follow it immediately with `end'.
1475
 
1476
          (gdb) collect DATA // collect some data
1477
 
1478
          (gdb) while-stepping 5 // single-step 5 times, collect data
1479
 
1480
          (gdb) end              // signals the end of actions.
1481
 
1482
     In the following example, the action list begins with `collect'
1483
     commands indicating the things to be collected when the tracepoint
1484
     is hit.  Then, in order to single-step and collect additional data
1485
     following the tracepoint, a `while-stepping' command is used,
1486
     followed by the list of things to be collected after each step in a
1487
     sequence of single steps.  The `while-stepping' command is
1488
     terminated by its own separate `end' command.  Lastly, the action
1489
     list is terminated by an `end' command.
1490
 
1491
          (gdb) trace foo
1492
          (gdb) actions
1493
          Enter actions for tracepoint 1, one per line:
1494
          > collect bar,baz
1495
          > collect $regs
1496
          > while-stepping 12
1497
            > collect $pc, arr[i]
1498
            > end
1499
          end
1500
 
1501
`collect EXPR1, EXPR2, ...'
1502
     Collect values of the given expressions when the tracepoint is hit.
1503
     This command accepts a comma-separated list of any valid
1504
     expressions.  In addition to global, static, or local variables,
1505
     the following special arguments are supported:
1506
 
1507
    `$regs'
1508
          Collect all registers.
1509
 
1510
    `$args'
1511
          Collect all function arguments.
1512
 
1513
    `$locals'
1514
          Collect all local variables.
1515
 
1516
    `$_sdata'
1517
          Collect static tracepoint marker specific data.  Only
1518
          available for static tracepoints.  *Note Tracepoint Action
1519
          Lists: Tracepoint Actions.  On the UST static tracepoints
1520
          library backend, an instrumentation point resembles a
1521
          `printf' function call.  The tracing library is able to
1522
          collect user specified data formatted to a character string
1523
          using the format provided by the programmer that instrumented
1524
          the program.  Other backends have similar mechanisms.  Here's
1525
          an example of a UST marker call:
1526
 
1527
                const char master_name[] = "$your_name";
1528
                trace_mark(channel1, marker1, "hello %s", master_name)
1529
 
1530
          In this case, collecting `$_sdata' collects the string `hello
1531
          $yourname'.  When analyzing the trace buffer, you can inspect
1532
          `$_sdata' like any other variable available to GDB.
1533
 
1534
     You can give several consecutive `collect' commands, each one with
1535
     a single argument, or one `collect' command with several arguments
1536
     separated by commas; the effect is the same.
1537
 
1538
     The command `info scope' (*note info scope: Symbols.) is
1539
     particularly useful for figuring out what data to collect.
1540
 
1541
`teval EXPR1, EXPR2, ...'
1542
     Evaluate the given expressions when the tracepoint is hit.  This
1543
     command accepts a comma-separated list of expressions.  The results
1544
     are discarded, so this is mainly useful for assigning values to
1545
     trace state variables (*note Trace State Variables::) without
1546
     adding those values to the trace buffer, as would be the case if
1547
     the `collect' action were used.
1548
 
1549
`while-stepping N'
1550
     Perform N single-step instruction traces after the tracepoint,
1551
     collecting new data after each step.  The `while-stepping' command
1552
     is followed by the list of what to collect while stepping
1553
     (followed by its own `end' command):
1554
 
1555
          > while-stepping 12
1556
            > collect $regs, myglobal
1557
            > end
1558
          >
1559
 
1560
     Note that `$pc' is not automatically collected by
1561
     `while-stepping'; you need to explicitly collect that register if
1562
     you need it.  You may abbreviate `while-stepping' as `ws' or
1563
     `stepping'.
1564
 
1565
`set default-collect EXPR1, EXPR2, ...'
1566
     This variable is a list of expressions to collect at each
1567
     tracepoint hit.  It is effectively an additional `collect' action
1568
     prepended to every tracepoint action list.  The expressions are
1569
     parsed individually for each tracepoint, so for instance a
1570
     variable named `xyz' may be interpreted as a global for one
1571
     tracepoint, and a local for another, as appropriate to the
1572
     tracepoint's location.
1573
 
1574
`show default-collect'
1575
     Show the list of expressions that are collected by default at each
1576
     tracepoint hit.
1577
 
1578
 
1579

1580
File: gdb.info,  Node: Listing Tracepoints,  Next: Listing Static Tracepoint Markers,  Prev: Tracepoint Actions,  Up: Set Tracepoints
1581
 
1582
13.1.7 Listing Tracepoints
1583
--------------------------
1584
 
1585
`info tracepoints [NUM]'
1586
     Display information about the tracepoint NUM.  If you don't
1587
     specify a tracepoint number, displays information about all the
1588
     tracepoints defined so far.  The format is similar to that used for
1589
     `info breakpoints'; in fact, `info tracepoints' is the same
1590
     command, simply restricting itself to tracepoints.
1591
 
1592
     A tracepoint's listing may include additional information specific
1593
     to tracing:
1594
 
1595
        * its passcount as given by the `passcount N' command
1596
 
1597
          (gdb) info trace
1598
          Num     Type           Disp Enb Address    What
1599
          1       tracepoint     keep y   0x0804ab57 in foo() at main.cxx:7
1600
                  while-stepping 20
1601
                    collect globfoo, $regs
1602
                  end
1603
                  collect globfoo2
1604
                  end
1605
                  pass count 1200
1606
          (gdb)
1607
 
1608
     This command can be abbreviated `info tp'.
1609
 
1610

1611
File: gdb.info,  Node: Listing Static Tracepoint Markers,  Next: Starting and Stopping Trace Experiments,  Prev: Listing Tracepoints,  Up: Set Tracepoints
1612
 
1613
13.1.8 Listing Static Tracepoint Markers
1614
----------------------------------------
1615
 
1616
`info static-tracepoint-markers'
1617
     Display information about all static tracepoint markers defined in
1618
     the program.
1619
 
1620
     For each marker, the following columns are printed:
1621
 
1622
    _Count_
1623
          An incrementing counter, output to help readability.  This is
1624
          not a stable identifier.
1625
 
1626
    _ID_
1627
          The marker ID, as reported by the target.
1628
 
1629
    _Enabled or Disabled_
1630
          Probed markers are tagged with `y'.  `n' identifies marks
1631
          that are not enabled.
1632
 
1633
    _Address_
1634
          Where the marker is in your program, as a memory address.
1635
 
1636
    _What_
1637
          Where the marker is in the source for your program, as a file
1638
          and line number.  If the debug information included in the
1639
          program does not allow GDB to locate the source of the
1640
          marker, this column will be left blank.
1641
 
1642
     In addition, the following information may be printed for each
1643
     marker:
1644
 
1645
    _Data_
1646
          User data passed to the tracing library by the marker call.
1647
          In the UST backend, this is the format string passed as
1648
          argument to the marker call.
1649
 
1650
    _Static tracepoints probing the marker_
1651
          The list of static tracepoints attached to the marker.
1652
 
1653
          (gdb) info static-tracepoint-markers
1654
          Cnt ID         Enb Address            What
1655
          1   ust/bar2   y   0x0000000000400e1a in main at stexample.c:25
1656
               Data: number1 %d number2 %d
1657
               Probed by static tracepoints: #2
1658
          2   ust/bar33  n   0x0000000000400c87 in main at stexample.c:24
1659
               Data: str %s
1660
          (gdb)
1661
 
1662

1663
File: gdb.info,  Node: Starting and Stopping Trace Experiments,  Next: Tracepoint Restrictions,  Prev: Listing Static Tracepoint Markers,  Up: Set Tracepoints
1664
 
1665
13.1.9 Starting and Stopping Trace Experiments
1666
----------------------------------------------
1667
 
1668
`tstart'
1669
     This command takes no arguments.  It starts the trace experiment,
1670
     and begins collecting data.  This has the side effect of
1671
     discarding all the data collected in the trace buffer during the
1672
     previous trace experiment.
1673
 
1674
`tstop'
1675
     This command takes no arguments.  It ends the trace experiment, and
1676
     stops collecting data.
1677
 
1678
     *Note*: a trace experiment and data collection may stop
1679
     automatically if any tracepoint's passcount is reached (*note
1680
     Tracepoint Passcounts::), or if the trace buffer becomes full.
1681
 
1682
`tstatus'
1683
     This command displays the status of the current trace data
1684
     collection.
1685
 
1686
   Here is an example of the commands we described so far:
1687
 
1688
     (gdb) trace gdb_c_test
1689
     (gdb) actions
1690
     Enter actions for tracepoint #1, one per line.
1691
     > collect $regs,$locals,$args
1692
     > while-stepping 11
1693
       > collect $regs
1694
       > end
1695
     > end
1696
     (gdb) tstart
1697
        [time passes ...]
1698
     (gdb) tstop
1699
 
1700
   You can choose to continue running the trace experiment even if GDB
1701
disconnects from the target, voluntarily or involuntarily.  For
1702
commands such as `detach', the debugger will ask what you want to do
1703
with the trace.  But for unexpected terminations (GDB crash, network
1704
outage), it would be unfortunate to lose hard-won trace data, so the
1705
variable `disconnected-tracing' lets you decide whether the trace should
1706
continue running without GDB.
1707
 
1708
`set disconnected-tracing on'
1709
`set disconnected-tracing off'
1710
     Choose whether a tracing run should continue to run if GDB has
1711
     disconnected from the target.  Note that `detach' or `quit' will
1712
     ask you directly what to do about a running trace no matter what
1713
     this variable's setting, so the variable is mainly useful for
1714
     handling unexpected situations, such as loss of the network.
1715
 
1716
`show disconnected-tracing'
1717
     Show the current choice for disconnected tracing.
1718
 
1719
 
1720
   When you reconnect to the target, the trace experiment may or may not
1721
still be running; it might have filled the trace buffer in the
1722
meantime, or stopped for one of the other reasons.  If it is running,
1723
it will continue after reconnection.
1724
 
1725
   Upon reconnection, the target will upload information about the
1726
tracepoints in effect.  GDB will then compare that information to the
1727
set of tracepoints currently defined, and attempt to match them up,
1728
allowing for the possibility that the numbers may have changed due to
1729
creation and deletion in the meantime.  If one of the target's
1730
tracepoints does not match any in GDB, the debugger will create a new
1731
tracepoint, so that you have a number with which to specify that
1732
tracepoint.  This matching-up process is necessarily heuristic, and it
1733
may result in useless tracepoints being created; you may simply delete
1734
them if they are of no use.
1735
 
1736
   If your target agent supports a "circular trace buffer", then you
1737
can run a trace experiment indefinitely without filling the trace
1738
buffer; when space runs out, the agent deletes already-collected trace
1739
frames, oldest first, until there is enough room to continue
1740
collecting.  This is especially useful if your tracepoints are being
1741
hit too often, and your trace gets terminated prematurely because the
1742
buffer is full.  To ask for a circular trace buffer, simply set
1743
`circular_trace_buffer' to on.  You can set this at any time, including
1744
during tracing; if the agent can do it, it will change buffer handling
1745
on the fly, otherwise it will not take effect until the next run.
1746
 
1747
`set circular-trace-buffer on'
1748
`set circular-trace-buffer off'
1749
     Choose whether a tracing run should use a linear or circular buffer
1750
     for trace data.  A linear buffer will not lose any trace data, but
1751
     may fill up prematurely, while a circular buffer will discard old
1752
     trace data, but it will have always room for the latest tracepoint
1753
     hits.
1754
 
1755
`show circular-trace-buffer'
1756
     Show the current choice for the trace buffer.  Note that this may
1757
     not match the agent's current buffer handling, nor is it
1758
     guaranteed to match the setting that might have been in effect
1759
     during a past run, for instance if you are looking at frames from
1760
     a trace file.
1761
 
1762
 
1763

1764
File: gdb.info,  Node: Tracepoint Restrictions,  Prev: Starting and Stopping Trace Experiments,  Up: Set Tracepoints
1765
 
1766
13.1.10 Tracepoint Restrictions
1767
-------------------------------
1768
 
1769
There are a number of restrictions on the use of tracepoints.  As
1770
described above, tracepoint data gathering occurs on the target without
1771
interaction from GDB.  Thus the full capabilities of the debugger are
1772
not available during data gathering, and then at data examination time,
1773
you will be limited by only having what was collected.  The following
1774
items describe some common problems, but it is not exhaustive, and you
1775
may run into additional difficulties not mentioned here.
1776
 
1777
   * Tracepoint expressions are intended to gather objects (lvalues).
1778
     Thus the full flexibility of GDB's expression evaluator is not
1779
     available.  You cannot call functions, cast objects to aggregate
1780
     types, access convenience variables or modify values (except by
1781
     assignment to trace state variables).  Some language features may
1782
     implicitly call functions (for instance Objective-C fields with
1783
     accessors), and therefore cannot be collected either.
1784
 
1785
   * Collection of local variables, either individually or in bulk with
1786
     `$locals' or `$args', during `while-stepping' may behave
1787
     erratically.  The stepping action may enter a new scope (for
1788
     instance by stepping into a function), or the location of the
1789
     variable may change (for instance it is loaded into a register).
1790
     The tracepoint data recorded uses the location information for the
1791
     variables that is correct for the tracepoint location.  When the
1792
     tracepoint is created, it is not possible, in general, to determine
1793
     where the steps of a `while-stepping' sequence will advance the
1794
     program--particularly if a conditional branch is stepped.
1795
 
1796
   * Collection of an incompletely-initialized or partially-destroyed
1797
     object may result in something that GDB cannot display, or displays
1798
     in a misleading way.
1799
 
1800
   * When GDB displays a pointer to character it automatically
1801
     dereferences the pointer to also display characters of the string
1802
     being pointed to.  However, collecting the pointer during tracing
1803
     does not automatically collect the string.  You need to explicitly
1804
     dereference the pointer and provide size information if you want to
1805
     collect not only the pointer, but the memory pointed to.  For
1806
     example, `*ptr@50' can be used to collect the 50 element array
1807
     pointed to by `ptr'.
1808
 
1809
   * It is not possible to collect a complete stack backtrace at a
1810
     tracepoint.  Instead, you may collect the registers and a few
1811
     hundred bytes from the stack pointer with something like
1812
     `*$esp@300' (adjust to use the name of the actual stack pointer
1813
     register on your target architecture, and the amount of stack you
1814
     wish to capture).  Then the `backtrace' command will show a
1815
     partial backtrace when using a trace frame.  The number of stack
1816
     frames that can be examined depends on the sizes of the frames in
1817
     the collected stack.  Note that if you ask for a block so large
1818
     that it goes past the bottom of the stack, the target agent may
1819
     report an error trying to read from an invalid address.
1820
 
1821
   * If you do not collect registers at a tracepoint, GDB can infer
1822
     that the value of `$pc' must be the same as the address of the
1823
     tracepoint and use that when you are looking at a trace frame for
1824
     that tracepoint.  However, this cannot work if the tracepoint has
1825
     multiple locations (for instance if it was set in a function that
1826
     was inlined), or if it has a `while-stepping' loop.  In those cases
1827
     GDB will warn you that it can't infer `$pc', and default it to
1828
     zero.
1829
 
1830
 
1831

1832
File: gdb.info,  Node: Analyze Collected Data,  Next: Tracepoint Variables,  Prev: Set Tracepoints,  Up: Tracepoints
1833
 
1834
13.2 Using the Collected Data
1835
=============================
1836
 
1837
After the tracepoint experiment ends, you use GDB commands for
1838
examining the trace data.  The basic idea is that each tracepoint
1839
collects a trace "snapshot" every time it is hit and another snapshot
1840
every time it single-steps.  All these snapshots are consecutively
1841
numbered from zero and go into a buffer, and you can examine them
1842
later.  The way you examine them is to "focus" on a specific trace
1843
snapshot.  When the remote stub is focused on a trace snapshot, it will
1844
respond to all GDB requests for memory and registers by reading from
1845
the buffer which belongs to that snapshot, rather than from _real_
1846
memory or registers of the program being debugged.  This means that
1847
*all* GDB commands (`print', `info registers', `backtrace', etc.) will
1848
behave as if we were currently debugging the program state as it was
1849
when the tracepoint occurred.  Any requests for data that are not in
1850
the buffer will fail.
1851
 
1852
* Menu:
1853
 
1854
* tfind::                       How to select a trace snapshot
1855
* tdump::                       How to display all data for a snapshot
1856
* save tracepoints::            How to save tracepoints for a future run
1857
 
1858

1859
File: gdb.info,  Node: tfind,  Next: tdump,  Up: Analyze Collected Data
1860
 
1861
13.2.1 `tfind N'
1862
----------------
1863
 
1864
The basic command for selecting a trace snapshot from the buffer is
1865
`tfind N', which finds trace snapshot number N, counting from zero.  If
1866
no argument N is given, the next snapshot is selected.
1867
 
1868
   Here are the various forms of using the `tfind' command.
1869
 
1870
`tfind start'
1871
     Find the first snapshot in the buffer.  This is a synonym for
1872
     `tfind 0' (since 0 is the number of the first snapshot).
1873
 
1874
`tfind none'
1875
     Stop debugging trace snapshots, resume _live_ debugging.
1876
 
1877
`tfind end'
1878
     Same as `tfind none'.
1879
 
1880
`tfind'
1881
     No argument means find the next trace snapshot.
1882
 
1883
`tfind -'
1884
     Find the previous trace snapshot before the current one.  This
1885
     permits retracing earlier steps.
1886
 
1887
`tfind tracepoint NUM'
1888
     Find the next snapshot associated with tracepoint NUM.  Search
1889
     proceeds forward from the last examined trace snapshot.  If no
1890
     argument NUM is given, it means find the next snapshot collected
1891
     for the same tracepoint as the current snapshot.
1892
 
1893
`tfind pc ADDR'
1894
     Find the next snapshot associated with the value ADDR of the
1895
     program counter.  Search proceeds forward from the last examined
1896
     trace snapshot.  If no argument ADDR is given, it means find the
1897
     next snapshot with the same value of PC as the current snapshot.
1898
 
1899
`tfind outside ADDR1, ADDR2'
1900
     Find the next snapshot whose PC is outside the given range of
1901
     addresses (exclusive).
1902
 
1903
`tfind range ADDR1, ADDR2'
1904
     Find the next snapshot whose PC is between ADDR1 and ADDR2
1905
     (inclusive).
1906
 
1907
`tfind line [FILE:]N'
1908
     Find the next snapshot associated with the source line N.  If the
1909
     optional argument FILE is given, refer to line N in that source
1910
     file.  Search proceeds forward from the last examined trace
1911
     snapshot.  If no argument N is given, it means find the next line
1912
     other than the one currently being examined; thus saying `tfind
1913
     line' repeatedly can appear to have the same effect as stepping
1914
     from line to line in a _live_ debugging session.
1915
 
1916
   The default arguments for the `tfind' commands are specifically
1917
designed to make it easy to scan through the trace buffer.  For
1918
instance, `tfind' with no argument selects the next trace snapshot, and
1919
`tfind -' with no argument selects the previous trace snapshot.  So, by
1920
giving one `tfind' command, and then simply hitting  repeatedly
1921
you can examine all the trace snapshots in order.  Or, by saying `tfind
1922
-' and then hitting  repeatedly you can examine the snapshots in
1923
reverse order.  The `tfind line' command with no argument selects the
1924
snapshot for the next source line executed.  The `tfind pc' command with
1925
no argument selects the next snapshot with the same program counter
1926
(PC) as the current frame.  The `tfind tracepoint' command with no
1927
argument selects the next trace snapshot collected by the same
1928
tracepoint as the current one.
1929
 
1930
   In addition to letting you scan through the trace buffer manually,
1931
these commands make it easy to construct GDB scripts that scan through
1932
the trace buffer and print out whatever collected data you are
1933
interested in.  Thus, if we want to examine the PC, FP, and SP
1934
registers from each trace frame in the buffer, we can say this:
1935
 
1936
     (gdb) tfind start
1937
     (gdb) while ($trace_frame != -1)
1938
     > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
1939
               $trace_frame, $pc, $sp, $fp
1940
     > tfind
1941
     > end
1942
 
1943
     Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
1944
     Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
1945
     Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
1946
     Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
1947
     Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
1948
     Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
1949
     Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
1950
     Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
1951
     Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
1952
     Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
1953
     Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
1954
 
1955
   Or, if we want to examine the variable `X' at each source line in
1956
the buffer:
1957
 
1958
     (gdb) tfind start
1959
     (gdb) while ($trace_frame != -1)
1960
     > printf "Frame %d, X == %d\n", $trace_frame, X
1961
     > tfind line
1962
     > end
1963
 
1964
     Frame 0, X = 1
1965
     Frame 7, X = 2
1966
     Frame 13, X = 255
1967
 
1968

1969
File: gdb.info,  Node: tdump,  Next: save tracepoints,  Prev: tfind,  Up: Analyze Collected Data
1970
 
1971
13.2.2 `tdump'
1972
--------------
1973
 
1974
This command takes no arguments.  It prints all the data collected at
1975
the current trace snapshot.
1976
 
1977
     (gdb) trace 444
1978
     (gdb) actions
1979
     Enter actions for tracepoint #2, one per line:
1980
     > collect $regs, $locals, $args, gdb_long_test
1981
     > end
1982
 
1983
     (gdb) tstart
1984
 
1985
     (gdb) tfind line 444
1986
     #0  gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
1987
     at gdb_test.c:444
1988
     444        printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
1989
 
1990
     (gdb) tdump
1991
     Data collected at tracepoint 2, trace frame 1:
1992
     d0             0xc4aa0085       -995491707
1993
     d1             0x18     24
1994
     d2             0x80     128
1995
     d3             0x33     51
1996
     d4             0x71aea3d        119204413
1997
     d5             0x22     34
1998
     d6             0xe0     224
1999
     d7             0x380035 3670069
2000
     a0             0x19e24a 1696330
2001
     a1             0x3000668        50333288
2002
     a2             0x100    256
2003
     a3             0x322000 3284992
2004
     a4             0x3000698        50333336
2005
     a5             0x1ad3cc 1758156
2006
     fp             0x30bf3c 0x30bf3c
2007
     sp             0x30bf34 0x30bf34
2008
     ps             0x0      0
2009
     pc             0x20b2c8 0x20b2c8
2010
     fpcontrol      0x0      0
2011
     fpstatus       0x0      0
2012
     fpiaddr        0x0      0
2013
     p = 0x20e5b4 "gdb-test"
2014
     p1 = (void *) 0x11
2015
     p2 = (void *) 0x22
2016
     p3 = (void *) 0x33
2017
     p4 = (void *) 0x44
2018
     p5 = (void *) 0x55
2019
     p6 = (void *) 0x66
2020
     gdb_long_test = 17 '\021'
2021
 
2022
     (gdb)
2023
 
2024
   `tdump' works by scanning the tracepoint's current collection
2025
actions and printing the value of each expression listed.  So `tdump'
2026
can fail, if after a run, you change the tracepoint's actions to
2027
mention variables that were not collected during the run.
2028
 
2029
   Also, for tracepoints with `while-stepping' loops, `tdump' uses the
2030
collected value of `$pc' to distinguish between trace frames that were
2031
collected at the tracepoint hit, and frames that were collected while
2032
stepping.  This allows it to correctly choose whether to display the
2033
basic list of collections, or the collections from the body of the
2034
while-stepping loop.  However, if `$pc' was not collected, then `tdump'
2035
will always attempt to dump using the basic collection list, and may
2036
fail if a while-stepping frame does not include all the same data that
2037
is collected at the tracepoint hit.
2038
 
2039

2040
File: gdb.info,  Node: save tracepoints,  Prev: tdump,  Up: Analyze Collected Data
2041
 
2042
13.2.3 `save tracepoints FILENAME'
2043
----------------------------------
2044
 
2045
This command saves all current tracepoint definitions together with
2046
their actions and passcounts, into a file `FILENAME' suitable for use
2047
in a later debugging session.  To read the saved tracepoint
2048
definitions, use the `source' command (*note Command Files::).  The
2049
`save-tracepoints' command is a deprecated alias for `save tracepoints'
2050
 
2051

2052
File: gdb.info,  Node: Tracepoint Variables,  Next: Trace Files,  Prev: Analyze Collected Data,  Up: Tracepoints
2053
 
2054
13.3 Convenience Variables for Tracepoints
2055
==========================================
2056
 
2057
`(int) $trace_frame'
2058
     The current trace snapshot (a.k.a. "frame") number, or -1 if no
2059
     snapshot is selected.
2060
 
2061
`(int) $tracepoint'
2062
     The tracepoint for the current trace snapshot.
2063
 
2064
`(int) $trace_line'
2065
     The line number for the current trace snapshot.
2066
 
2067
`(char []) $trace_file'
2068
     The source file for the current trace snapshot.
2069
 
2070
`(char []) $trace_func'
2071
     The name of the function containing `$tracepoint'.
2072
 
2073
   Note: `$trace_file' is not suitable for use in `printf', use
2074
`output' instead.
2075
 
2076
   Here's a simple example of using these convenience variables for
2077
stepping through all the trace snapshots and printing some of their
2078
data.  Note that these are not the same as trace state variables, which
2079
are managed by the target.
2080
 
2081
     (gdb) tfind start
2082
 
2083
     (gdb) while $trace_frame != -1
2084
     > output $trace_file
2085
     > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
2086
     > tfind
2087
     > end
2088
 
2089

2090
File: gdb.info,  Node: Trace Files,  Prev: Tracepoint Variables,  Up: Tracepoints
2091
 
2092
13.4 Using Trace Files
2093
======================
2094
 
2095
In some situations, the target running a trace experiment may no longer
2096
be available; perhaps it crashed, or the hardware was needed for a
2097
different activity.  To handle these cases, you can arrange to dump the
2098
trace data into a file, and later use that file as a source of trace
2099
data, via the `target tfile' command.
2100
 
2101
`tsave [ -r ] FILENAME'
2102
     Save the trace data to FILENAME.  By default, this command assumes
2103
     that FILENAME refers to the host filesystem, so if necessary GDB
2104
     will copy raw trace data up from the target and then save it.  If
2105
     the target supports it, you can also supply the optional argument
2106
     `-r' ("remote") to direct the target to save the data directly
2107
     into FILENAME in its own filesystem, which may be more efficient
2108
     if the trace buffer is very large.  (Note, however, that `target
2109
     tfile' can only read from files accessible to the host.)
2110
 
2111
`target tfile FILENAME'
2112
     Use the file named FILENAME as a source of trace data.  Commands
2113
     that examine data work as they do with a live target, but it is not
2114
     possible to run any new trace experiments.  `tstatus' will report
2115
     the state of the trace run at the moment the data was saved, as
2116
     well as the current trace frame you are examining.  FILENAME must
2117
     be on a filesystem accessible to the host.
2118
 
2119
 
2120

2121
File: gdb.info,  Node: Overlays,  Next: Languages,  Prev: Tracepoints,  Up: Top
2122
 
2123
14 Debugging Programs That Use Overlays
2124
***************************************
2125
 
2126
If your program is too large to fit completely in your target system's
2127
memory, you can sometimes use "overlays" to work around this problem.
2128
GDB provides some support for debugging programs that use overlays.
2129
 
2130
* Menu:
2131
 
2132
* How Overlays Work::              A general explanation of overlays.
2133
* Overlay Commands::               Managing overlays in GDB.
2134
* Automatic Overlay Debugging::    GDB can find out which overlays are
2135
                                   mapped by asking the inferior.
2136
* Overlay Sample Program::         A sample program using overlays.
2137
 
2138

2139
File: gdb.info,  Node: How Overlays Work,  Next: Overlay Commands,  Up: Overlays
2140
 
2141
14.1 How Overlays Work
2142
======================
2143
 
2144
Suppose you have a computer whose instruction address space is only 64
2145
kilobytes long, but which has much more memory which can be accessed by
2146
other means: special instructions, segment registers, or memory
2147
management hardware, for example.  Suppose further that you want to
2148
adapt a program which is larger than 64 kilobytes to run on this system.
2149
 
2150
   One solution is to identify modules of your program which are
2151
relatively independent, and need not call each other directly; call
2152
these modules "overlays".  Separate the overlays from the main program,
2153
and place their machine code in the larger memory.  Place your main
2154
program in instruction memory, but leave at least enough space there to
2155
hold the largest overlay as well.
2156
 
2157
   Now, to call a function located in an overlay, you must first copy
2158
that overlay's machine code from the large memory into the space set
2159
aside for it in the instruction memory, and then jump to its entry point
2160
there.
2161
 
2162
         Data             Instruction            Larger
2163
     Address Space       Address Space        Address Space
2164
     +-----------+       +-----------+        +-----------+
2165
     |           |       |           |        |           |
2166
     +-----------+       +-----------+        +-----------+<-- overlay 1
2167
     | program   |       |   main    |   .----| overlay 1 | load address
2168
     | variables |       |  program  |   |    +-----------+
2169
     | and heap  |       |           |   |    |           |
2170
     +-----------+       |           |   |    +-----------+<-- overlay 2
2171
     |           |       +-----------+   |    |           | load address
2172
     +-----------+       |           |   |  .-| overlay 2 |
2173
                         |           |   |  | |           |
2174
              mapped --->+-----------+   |  | +-----------+
2175
              address    |           |   |  | |           |
2176
                         |  overlay  | <-'  | |           |
2177
                         |   area    |  <---' +-----------+<-- overlay 3
2178
                         |           | <---.  |           | load address
2179
                         +-----------+     `--| overlay 3 |
2180
                         |           |        |           |
2181
                         +-----------+        |           |
2182
                                              +-----------+
2183
                                              |           |
2184
                                              +-----------+
2185
 
2186
                         A code overlay
2187
 
2188
   The diagram (*note A code overlay::) shows a system with separate
2189
data and instruction address spaces.  To map an overlay, the program
2190
copies its code from the larger address space to the instruction
2191
address space.  Since the overlays shown here all use the same mapped
2192
address, only one may be mapped at a time.  For a system with a single
2193
address space for data and instructions, the diagram would be similar,
2194
except that the program variables and heap would share an address space
2195
with the main program and the overlay area.
2196
 
2197
   An overlay loaded into instruction memory and ready for use is
2198
called a "mapped" overlay; its "mapped address" is its address in the
2199
instruction memory.  An overlay not present (or only partially present)
2200
in instruction memory is called "unmapped"; its "load address" is its
2201
address in the larger memory.  The mapped address is also called the
2202
"virtual memory address", or "VMA"; the load address is also called the
2203
"load memory address", or "LMA".
2204
 
2205
   Unfortunately, overlays are not a completely transparent way to
2206
adapt a program to limited instruction memory.  They introduce a new
2207
set of global constraints you must keep in mind as you design your
2208
program:
2209
 
2210
   * Before calling or returning to a function in an overlay, your
2211
     program must make sure that overlay is actually mapped.
2212
     Otherwise, the call or return will transfer control to the right
2213
     address, but in the wrong overlay, and your program will probably
2214
     crash.
2215
 
2216
   * If the process of mapping an overlay is expensive on your system,
2217
     you will need to choose your overlays carefully to minimize their
2218
     effect on your program's performance.
2219
 
2220
   * The executable file you load onto your system must contain each
2221
     overlay's instructions, appearing at the overlay's load address,
2222
     not its mapped address.  However, each overlay's instructions must
2223
     be relocated and its symbols defined as if the overlay were at its
2224
     mapped address.  You can use GNU linker scripts to specify
2225
     different load and relocation addresses for pieces of your
2226 342 jeremybenn
     program; see *note Overlay Description: (ld.info)Overlay
2227 330 jeremybenn
     Description.
2228
 
2229
   * The procedure for loading executable files onto your system must
2230
     be able to load their contents into the larger address space as
2231
     well as the instruction and data spaces.
2232
 
2233
 
2234
   The overlay system described above is rather simple, and could be
2235
improved in many ways:
2236
 
2237
   * If your system has suitable bank switch registers or memory
2238
     management hardware, you could use those facilities to make an
2239
     overlay's load area contents simply appear at their mapped address
2240
     in instruction space.  This would probably be faster than copying
2241
     the overlay to its mapped area in the usual way.
2242
 
2243
   * If your overlays are small enough, you could set aside more than
2244
     one overlay area, and have more than one overlay mapped at a time.
2245
 
2246
   * You can use overlays to manage data, as well as instructions.  In
2247
     general, data overlays are even less transparent to your design
2248
     than code overlays: whereas code overlays only require care when
2249
     you call or return to functions, data overlays require care every
2250
     time you access the data.  Also, if you change the contents of a
2251
     data overlay, you must copy its contents back out to its load
2252
     address before you can copy a different data overlay into the same
2253
     mapped area.
2254
 
2255
 
2256

2257
File: gdb.info,  Node: Overlay Commands,  Next: Automatic Overlay Debugging,  Prev: How Overlays Work,  Up: Overlays
2258
 
2259
14.2 Overlay Commands
2260
=====================
2261
 
2262
To use GDB's overlay support, each overlay in your program must
2263
correspond to a separate section of the executable file.  The section's
2264
virtual memory address and load memory address must be the overlay's
2265
mapped and load addresses.  Identifying overlays with sections allows
2266
GDB to determine the appropriate address of a function or variable,
2267
depending on whether the overlay is mapped or not.
2268
 
2269
   GDB's overlay commands all start with the word `overlay'; you can
2270
abbreviate this as `ov' or `ovly'.  The commands are:
2271
 
2272
`overlay off'
2273
     Disable GDB's overlay support.  When overlay support is disabled,
2274
     GDB assumes that all functions and variables are always present at
2275
     their mapped addresses.  By default, GDB's overlay support is
2276
     disabled.
2277
 
2278
`overlay manual'
2279
     Enable "manual" overlay debugging.  In this mode, GDB relies on
2280
     you to tell it which overlays are mapped, and which are not, using
2281
     the `overlay map-overlay' and `overlay unmap-overlay' commands
2282
     described below.
2283
 
2284
`overlay map-overlay OVERLAY'
2285
`overlay map OVERLAY'
2286
     Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of
2287
     the object file section containing the overlay.  When an overlay
2288
     is mapped, GDB assumes it can find the overlay's functions and
2289
     variables at their mapped addresses.  GDB assumes that any other
2290
     overlays whose mapped ranges overlap that of OVERLAY are now
2291
     unmapped.
2292
 
2293
`overlay unmap-overlay OVERLAY'
2294
`overlay unmap OVERLAY'
2295
     Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the
2296
     name of the object file section containing the overlay.  When an
2297
     overlay is unmapped, GDB assumes it can find the overlay's
2298
     functions and variables at their load addresses.
2299
 
2300
`overlay auto'
2301
     Enable "automatic" overlay debugging.  In this mode, GDB consults
2302
     a data structure the overlay manager maintains in the inferior to
2303 342 jeremybenn
     see which overlays are mapped.  For details, see *note Automatic
2304 330 jeremybenn
     Overlay Debugging::.
2305
 
2306
`overlay load-target'
2307
`overlay load'
2308
     Re-read the overlay table from the inferior.  Normally, GDB
2309
     re-reads the table GDB automatically each time the inferior stops,
2310
     so this command should only be necessary if you have changed the
2311
     overlay mapping yourself using GDB.  This command is only useful
2312
     when using automatic overlay debugging.
2313
 
2314
`overlay list-overlays'
2315
`overlay list'
2316
     Display a list of the overlays currently mapped, along with their
2317
     mapped addresses, load addresses, and sizes.
2318
 
2319
 
2320
   Normally, when GDB prints a code address, it includes the name of
2321
the function the address falls in:
2322
 
2323
     (gdb) print main
2324
     $3 = {int ()} 0x11a0 
2325
   When overlay debugging is enabled, GDB recognizes code in unmapped
2326
overlays, and prints the names of unmapped functions with asterisks
2327
around them.  For example, if `foo' is a function in an unmapped
2328
overlay, GDB prints it this way:
2329
 
2330
     (gdb) overlay list
2331
     No sections are mapped.
2332
     (gdb) print foo
2333
     $5 = {int (int)} 0x100000 <*foo*>
2334
   When `foo''s overlay is mapped, GDB prints the function's name
2335
normally:
2336
 
2337
     (gdb) overlay list
2338
     Section .ov.foo.text, loaded at 0x100000 - 0x100034,
2339
             mapped at 0x1016 - 0x104a
2340
     (gdb) print foo
2341
     $6 = {int (int)} 0x1016 
2342
 
2343
   When overlay debugging is enabled, GDB can find the correct address
2344
for functions and variables in an overlay, whether or not the overlay
2345
is mapped.  This allows most GDB commands, like `break' and
2346
`disassemble', to work normally, even on unmapped code.  However, GDB's
2347
breakpoint support has some limitations:
2348
 
2349
   * You can set breakpoints in functions in unmapped overlays, as long
2350
     as GDB can write to the overlay at its load address.
2351
 
2352
   * GDB can not set hardware or simulator-based breakpoints in
2353
     unmapped overlays.  However, if you set a breakpoint at the end of
2354
     your overlay manager (and tell GDB which overlays are now mapped,
2355
     if you are using manual overlay management), GDB will re-set its
2356
     breakpoints properly.
2357
 
2358

2359
File: gdb.info,  Node: Automatic Overlay Debugging,  Next: Overlay Sample Program,  Prev: Overlay Commands,  Up: Overlays
2360
 
2361
14.3 Automatic Overlay Debugging
2362
================================
2363
 
2364
GDB can automatically track which overlays are mapped and which are
2365
not, given some simple co-operation from the overlay manager in the
2366
inferior.  If you enable automatic overlay debugging with the `overlay
2367
auto' command (*note Overlay Commands::), GDB looks in the inferior's
2368
memory for certain variables describing the current state of the
2369
overlays.
2370
 
2371
   Here are the variables your overlay manager must define to support
2372
GDB's automatic overlay debugging:
2373
 
2374
`_ovly_table':
2375
     This variable must be an array of the following structures:
2376
 
2377
          struct
2378
          {
2379
            /* The overlay's mapped address.  */
2380
            unsigned long vma;
2381
 
2382
            /* The size of the overlay, in bytes.  */
2383
            unsigned long size;
2384
 
2385
            /* The overlay's load address.  */
2386
            unsigned long lma;
2387
 
2388
            /* Non-zero if the overlay is currently mapped;
2389
               zero otherwise.  */
2390
            unsigned long mapped;
2391
          }
2392
 
2393
`_novlys':
2394
     This variable must be a four-byte signed integer, holding the total
2395
     number of elements in `_ovly_table'.
2396
 
2397
 
2398
   To decide whether a particular overlay is mapped or not, GDB looks
2399
for an entry in `_ovly_table' whose `vma' and `lma' members equal the
2400
VMA and LMA of the overlay's section in the executable file.  When GDB
2401
finds a matching entry, it consults the entry's `mapped' member to
2402
determine whether the overlay is currently mapped.
2403
 
2404
   In addition, your overlay manager may define a function called
2405
`_ovly_debug_event'.  If this function is defined, GDB will silently
2406
set a breakpoint there.  If the overlay manager then calls this
2407
function whenever it has changed the overlay table, this will enable
2408
GDB to accurately keep track of which overlays are in program memory,
2409
and update any breakpoints that may be set in overlays.  This will
2410
allow breakpoints to work even if the overlays are kept in ROM or other
2411
non-writable memory while they are not being executed.
2412
 
2413

2414
File: gdb.info,  Node: Overlay Sample Program,  Prev: Automatic Overlay Debugging,  Up: Overlays
2415
 
2416
14.4 Overlay Sample Program
2417
===========================
2418
 
2419
When linking a program which uses overlays, you must place the overlays
2420
at their load addresses, while relocating them to run at their mapped
2421
addresses.  To do this, you must write a linker script (*note Overlay
2422
Description: (ld.info)Overlay Description.).  Unfortunately, since
2423
linker scripts are specific to a particular host system, target
2424
architecture, and target memory layout, this manual cannot provide
2425
portable sample code demonstrating GDB's overlay support.
2426
 
2427
   However, the GDB source distribution does contain an overlaid
2428
program, with linker scripts for a few systems, as part of its test
2429
suite.  The program consists of the following files from
2430
`gdb/testsuite/gdb.base':
2431
 
2432
`overlays.c'
2433
     The main program file.
2434
 
2435
`ovlymgr.c'
2436
     A simple overlay manager, used by `overlays.c'.
2437
 
2438
`foo.c'
2439
`bar.c'
2440
`baz.c'
2441
`grbx.c'
2442
     Overlay modules, loaded and used by `overlays.c'.
2443
 
2444
`d10v.ld'
2445
`m32r.ld'
2446
     Linker scripts for linking the test program on the `d10v-elf' and
2447
     `m32r-elf' targets.
2448
 
2449
   You can build the test program using the `d10v-elf' GCC
2450
cross-compiler like this:
2451
 
2452
     $ d10v-elf-gcc -g -c overlays.c
2453
     $ d10v-elf-gcc -g -c ovlymgr.c
2454
     $ d10v-elf-gcc -g -c foo.c
2455
     $ d10v-elf-gcc -g -c bar.c
2456
     $ d10v-elf-gcc -g -c baz.c
2457
     $ d10v-elf-gcc -g -c grbx.c
2458
     $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
2459
                       baz.o grbx.o -Wl,-Td10v.ld -o overlays
2460
 
2461
   The build process is identical for any other architecture, except
2462
that you must substitute the appropriate compiler and linker script for
2463
the target system for `d10v-elf-gcc' and `d10v.ld'.
2464
 
2465

2466
File: gdb.info,  Node: Languages,  Next: Symbols,  Prev: Overlays,  Up: Top
2467
 
2468
15 Using GDB with Different Languages
2469
*************************************
2470
 
2471
Although programming languages generally have common aspects, they are
2472
rarely expressed in the same manner.  For instance, in ANSI C,
2473
dereferencing a pointer `p' is accomplished by `*p', but in Modula-2,
2474
it is accomplished by `p^'.  Values can also be represented (and
2475
displayed) differently.  Hex numbers in C appear as `0x1ae', while in
2476
Modula-2 they appear as `1AEH'.
2477
 
2478
   Language-specific information is built into GDB for some languages,
2479
allowing you to express operations like the above in your program's
2480
native language, and allowing GDB to output values in a manner
2481
consistent with the syntax of your program's native language.  The
2482
language you use to build expressions is called the "working language".
2483
 
2484
* Menu:
2485
 
2486
* Setting::                     Switching between source languages
2487
* Show::                        Displaying the language
2488
* Checks::                      Type and range checks
2489
* Supported Languages::         Supported languages
2490
* Unsupported Languages::       Unsupported languages
2491
 
2492

2493
File: gdb.info,  Node: Setting,  Next: Show,  Up: Languages
2494
 
2495
15.1 Switching Between Source Languages
2496
=======================================
2497
 
2498
There are two ways to control the working language--either have GDB set
2499
it automatically, or select it manually yourself.  You can use the `set
2500
language' command for either purpose.  On startup, GDB defaults to
2501
setting the language automatically.  The working language is used to
2502
determine how expressions you type are interpreted, how values are
2503
printed, etc.
2504
 
2505
   In addition to the working language, every source file that GDB
2506
knows about has its own working language.  For some object file
2507
formats, the compiler might indicate which language a particular source
2508
file is in.  However, most of the time GDB infers the language from the
2509
name of the file.  The language of a source file controls whether C++
2510
names are demangled--this way `backtrace' can show each frame
2511
appropriately for its own language.  There is no way to set the
2512
language of a source file from within GDB, but you can set the language
2513
associated with a filename extension.  *Note Displaying the Language:
2514
Show.
2515
 
2516
   This is most commonly a problem when you use a program, such as
2517
`cfront' or `f2c', that generates C but is written in another language.
2518
In that case, make the program use `#line' directives in its C output;
2519
that way GDB will know the correct language of the source code of the
2520
original program, and will display that source code, not the generated
2521
C code.
2522
 
2523
* Menu:
2524
 
2525
* Filenames::                   Filename extensions and languages.
2526
* Manually::                    Setting the working language manually
2527
* Automatically::               Having GDB infer the source language
2528
 
2529

2530
File: gdb.info,  Node: Filenames,  Next: Manually,  Up: Setting
2531
 
2532
15.1.1 List of Filename Extensions and Languages
2533
------------------------------------------------
2534
 
2535
If a source file name ends in one of the following extensions, then GDB
2536
infers that its language is the one indicated.
2537
 
2538
`.ada'
2539
`.ads'
2540
`.adb'
2541
`.a'
2542
     Ada source file.
2543
 
2544
`.c'
2545
     C source file
2546
 
2547
`.C'
2548
`.cc'
2549
`.cp'
2550
`.cpp'
2551
`.cxx'
2552
`.c++'
2553
     C++ source file
2554
 
2555
`.d'
2556
     D source file
2557
 
2558
`.m'
2559
     Objective-C source file
2560
 
2561
`.f'
2562
`.F'
2563
     Fortran source file
2564
 
2565
`.mod'
2566
     Modula-2 source file
2567
 
2568
`.s'
2569
`.S'
2570
     Assembler source file.  This actually behaves almost like C, but
2571
     GDB does not skip over function prologues when stepping.
2572
 
2573
   In addition, you may set the language associated with a filename
2574
extension.  *Note Displaying the Language: Show.
2575
 
2576

2577
File: gdb.info,  Node: Manually,  Next: Automatically,  Prev: Filenames,  Up: Setting
2578
 
2579
15.1.2 Setting the Working Language
2580
-----------------------------------
2581
 
2582
If you allow GDB to set the language automatically, expressions are
2583
interpreted the same way in your debugging session and your program.
2584
 
2585
   If you wish, you may set the language manually.  To do this, issue
2586
the command `set language LANG', where LANG is the name of a language,
2587
such as `c' or `modula-2'.  For a list of the supported languages, type
2588
`set language'.
2589
 
2590
   Setting the language manually prevents GDB from updating the working
2591
language automatically.  This can lead to confusion if you try to debug
2592
a program when the working language is not the same as the source
2593
language, when an expression is acceptable to both languages--but means
2594
different things.  For instance, if the current source file were
2595
written in C, and GDB was parsing Modula-2, a command such as:
2596
 
2597
     print a = b + c
2598
 
2599
might not have the effect you intended.  In C, this means to add `b'
2600
and `c' and place the result in `a'.  The result printed would be the
2601
value of `a'.  In Modula-2, this means to compare `a' to the result of
2602
`b+c', yielding a `BOOLEAN' value.
2603
 
2604

2605
File: gdb.info,  Node: Automatically,  Prev: Manually,  Up: Setting
2606
 
2607
15.1.3 Having GDB Infer the Source Language
2608
-------------------------------------------
2609
 
2610
To have GDB set the working language automatically, use `set language
2611
local' or `set language auto'.  GDB then infers the working language.
2612
That is, when your program stops in a frame (usually by encountering a
2613
breakpoint), GDB sets the working language to the language recorded for
2614
the function in that frame.  If the language for a frame is unknown
2615
(that is, if the function or block corresponding to the frame was
2616
defined in a source file that does not have a recognized extension),
2617
the current working language is not changed, and GDB issues a warning.
2618
 
2619
   This may not seem necessary for most programs, which are written
2620
entirely in one source language.  However, program modules and libraries
2621
written in one source language can be used by a main program written in
2622
a different source language.  Using `set language auto' in this case
2623
frees you from having to set the working language manually.
2624
 
2625

2626
File: gdb.info,  Node: Show,  Next: Checks,  Prev: Setting,  Up: Languages
2627
 
2628
15.2 Displaying the Language
2629
============================
2630
 
2631
The following commands help you find out which language is the working
2632
language, and also what language source files were written in.
2633
 
2634
`show language'
2635
     Display the current working language.  This is the language you
2636
     can use with commands such as `print' to build and compute
2637
     expressions that may involve variables in your program.
2638
 
2639
`info frame'
2640
     Display the source language for this frame.  This language becomes
2641
     the working language if you use an identifier from this frame.
2642
     *Note Information about a Frame: Frame Info, to identify the other
2643
     information listed here.
2644
 
2645
`info source'
2646
     Display the source language of this source file.  *Note Examining
2647
     the Symbol Table: Symbols, to identify the other information
2648
     listed here.
2649
 
2650
   In unusual circumstances, you may have source files with extensions
2651
not in the standard list.  You can then set the extension associated
2652
with a language explicitly:
2653
 
2654
`set extension-language EXT LANGUAGE'
2655
     Tell GDB that source files with extension EXT are to be assumed as
2656
     written in the source language LANGUAGE.
2657
 
2658
`info extensions'
2659
     List all the filename extensions and the associated languages.
2660
 
2661

2662
File: gdb.info,  Node: Checks,  Next: Supported Languages,  Prev: Show,  Up: Languages
2663
 
2664
15.3 Type and Range Checking
2665
============================
2666
 
2667
     _Warning:_ In this release, the GDB commands for type and range
2668
     checking are included, but they do not yet have any effect.  This
2669
     section documents the intended facilities.
2670
 
2671
   Some languages are designed to guard you against making seemingly
2672
common errors through a series of compile- and run-time checks.  These
2673
include checking the type of arguments to functions and operators, and
2674
making sure mathematical overflows are caught at run time.  Checks such
2675
as these help to ensure a program's correctness once it has been
2676
compiled by eliminating type mismatches, and providing active checks
2677
for range errors when your program is running.
2678
 
2679
   GDB can check for conditions like the above if you wish.  Although
2680
GDB does not check the statements in your program, it can check
2681
expressions entered directly into GDB for evaluation via the `print'
2682
command, for example.  As with the working language, GDB can also
2683
decide whether or not to check automatically based on your program's
2684
source language.  *Note Supported Languages: Supported Languages, for
2685
the default settings of supported languages.
2686
 
2687
* Menu:
2688
 
2689
* Type Checking::               An overview of type checking
2690
* Range Checking::              An overview of range checking
2691
 
2692

2693
File: gdb.info,  Node: Type Checking,  Next: Range Checking,  Up: Checks
2694
 
2695
15.3.1 An Overview of Type Checking
2696
-----------------------------------
2697
 
2698
Some languages, such as Modula-2, are strongly typed, meaning that the
2699
arguments to operators and functions have to be of the correct type,
2700
otherwise an error occurs.  These checks prevent type mismatch errors
2701
from ever causing any run-time problems.  For example,
2702
 
2703
     1 + 2 => 3
2704
but
2705
     error--> 1 + 2.3
2706
 
2707
   The second example fails because the `CARDINAL' 1 is not
2708
type-compatible with the `REAL' 2.3.
2709
 
2710
   For the expressions you use in GDB commands, you can tell the GDB
2711
type checker to skip checking; to treat any mismatches as errors and
2712
abandon the expression; or to only issue warnings when type mismatches
2713
occur, but evaluate the expression anyway.  When you choose the last of
2714
these, GDB evaluates expressions like the second example above, but
2715
also issues a warning.
2716
 
2717
   Even if you turn type checking off, there may be other reasons
2718
related to type that prevent GDB from evaluating an expression.  For
2719
instance, GDB does not know how to add an `int' and a `struct foo'.
2720
These particular type errors have nothing to do with the language in
2721
use, and usually arise from expressions, such as the one described
2722
above, which make little sense to evaluate anyway.
2723
 
2724
   Each language defines to what degree it is strict about type.  For
2725
instance, both Modula-2 and C require the arguments to arithmetical
2726
operators to be numbers.  In C, enumerated types and pointers can be
2727
represented as numbers, so that they are valid arguments to mathematical
2728
operators.  *Note Supported Languages: Supported Languages, for further
2729
details on specific languages.
2730
 
2731
   GDB provides some additional commands for controlling the type
2732
checker:
2733
 
2734
`set check type auto'
2735
     Set type checking on or off based on the current working language.
2736
     *Note Supported Languages: Supported Languages, for the default
2737
     settings for each language.
2738
 
2739
`set check type on'
2740
`set check type off'
2741
     Set type checking on or off, overriding the default setting for the
2742
     current working language.  Issue a warning if the setting does not
2743
     match the language default.  If any type mismatches occur in
2744
     evaluating an expression while type checking is on, GDB prints a
2745
     message and aborts evaluation of the expression.
2746
 
2747
`set check type warn'
2748
     Cause the type checker to issue warnings, but to always attempt to
2749
     evaluate the expression.  Evaluating the expression may still be
2750
     impossible for other reasons.  For example, GDB cannot add numbers
2751
     and structures.
2752
 
2753
`show type'
2754
     Show the current setting of the type checker, and whether or not
2755
     GDB is setting it automatically.
2756
 
2757

2758
File: gdb.info,  Node: Range Checking,  Prev: Type Checking,  Up: Checks
2759
 
2760
15.3.2 An Overview of Range Checking
2761
------------------------------------
2762
 
2763
In some languages (such as Modula-2), it is an error to exceed the
2764
bounds of a type; this is enforced with run-time checks.  Such range
2765
checking is meant to ensure program correctness by making sure
2766
computations do not overflow, or indices on an array element access do
2767
not exceed the bounds of the array.
2768
 
2769
   For expressions you use in GDB commands, you can tell GDB to treat
2770
range errors in one of three ways: ignore them, always treat them as
2771
errors and abandon the expression, or issue warnings but evaluate the
2772
expression anyway.
2773
 
2774
   A range error can result from numerical overflow, from exceeding an
2775
array index bound, or when you type a constant that is not a member of
2776
any type.  Some languages, however, do not treat overflows as an error.
2777
In many implementations of C, mathematical overflow causes the result
2778
to "wrap around" to lower values--for example, if M is the largest
2779
integer value, and S is the smallest, then
2780
 
2781
     M + 1 => S
2782
 
2783
   This, too, is specific to individual languages, and in some cases
2784
specific to individual compilers or machines.  *Note Supported
2785
Languages: Supported Languages, for further details on specific
2786
languages.
2787
 
2788
   GDB provides some additional commands for controlling the range
2789
checker:
2790
 
2791
`set check range auto'
2792
     Set range checking on or off based on the current working language.
2793
     *Note Supported Languages: Supported Languages, for the default
2794
     settings for each language.
2795
 
2796
`set check range on'
2797
`set check range off'
2798
     Set range checking on or off, overriding the default setting for
2799
     the current working language.  A warning is issued if the setting
2800
     does not match the language default.  If a range error occurs and
2801
     range checking is on, then a message is printed and evaluation of
2802
     the expression is aborted.
2803
 
2804
`set check range warn'
2805
     Output messages when the GDB range checker detects a range error,
2806
     but attempt to evaluate the expression anyway.  Evaluating the
2807
     expression may still be impossible for other reasons, such as
2808
     accessing memory that the process does not own (a typical example
2809
     from many Unix systems).
2810
 
2811
`show range'
2812
     Show the current setting of the range checker, and whether or not
2813
     it is being set automatically by GDB.
2814
 
2815

2816
File: gdb.info,  Node: Supported Languages,  Next: Unsupported Languages,  Prev: Checks,  Up: Languages
2817
 
2818
15.4 Supported Languages
2819
========================
2820
 
2821
GDB supports C, C++, D, Objective-C, Fortran, Java, Pascal, assembly,
2822
Modula-2, and Ada.  Some GDB features may be used in expressions
2823
regardless of the language you use: the GDB `@' and `::' operators, and
2824
the `{type}addr' construct (*note Expressions: Expressions.) can be
2825
used with the constructs of any supported language.
2826
 
2827
   The following sections detail to what degree each source language is
2828
supported by GDB.  These sections are not meant to be language
2829
tutorials or references, but serve only as a reference guide to what the
2830
GDB expression parser accepts, and what input and output formats should
2831
look like for different languages.  There are many good books written
2832
on each of these languages; please look to these for a language
2833
reference or tutorial.
2834
 
2835
* Menu:
2836
 
2837
* C::                           C and C++
2838
* D::                           D
2839
* Objective-C::                 Objective-C
2840
* Fortran::                     Fortran
2841
* Pascal::                      Pascal
2842
* Modula-2::                    Modula-2
2843
* Ada::                         Ada
2844
 
2845

2846
File: gdb.info,  Node: C,  Next: D,  Up: Supported Languages
2847
 
2848
15.4.1 C and C++
2849
----------------
2850
 
2851
Since C and C++ are so closely related, many features of GDB apply to
2852
both languages.  Whenever this is the case, we discuss those languages
2853
together.
2854
 
2855
   The C++ debugging facilities are jointly implemented by the C++
2856
compiler and GDB.  Therefore, to debug your C++ code effectively, you
2857
must compile your C++ programs with a supported C++ compiler, such as
2858
GNU `g++', or the HP ANSI C++ compiler (`aCC').
2859
 
2860
   For best results when using GNU C++, use the DWARF 2 debugging
2861
format; if it doesn't work on your system, try the stabs+ debugging
2862
format.  You can select those formats explicitly with the `g++'
2863
command-line options `-gdwarf-2' and `-gstabs+'.  *Note Options for
2864
Debugging Your Program or GCC: (gcc.info)Debugging Options.
2865
 
2866
* Menu:
2867
 
2868
* C Operators::                 C and C++ operators
2869
* C Constants::                 C and C++ constants
2870
* C Plus Plus Expressions::     C++ expressions
2871
* C Defaults::                  Default settings for C and C++
2872
* C Checks::                    C and C++ type and range checks
2873
* Debugging C::                 GDB and C
2874
* Debugging C Plus Plus::       GDB features for C++
2875
* Decimal Floating Point::      Numbers in Decimal Floating Point format
2876
 
2877

2878
File: gdb.info,  Node: C Operators,  Next: C Constants,  Up: C
2879
 
2880
15.4.1.1 C and C++ Operators
2881
............................
2882
 
2883
Operators must be defined on values of specific types.  For instance,
2884
`+' is defined on numbers, but not on structures.  Operators are often
2885
defined on groups of types.
2886
 
2887
   For the purposes of C and C++, the following definitions hold:
2888
 
2889
   * _Integral types_ include `int' with any of its storage-class
2890
     specifiers; `char'; `enum'; and, for C++, `bool'.
2891
 
2892
   * _Floating-point types_ include `float', `double', and `long
2893
     double' (if supported by the target platform).
2894
 
2895
   * _Pointer types_ include all types defined as `(TYPE *)'.
2896
 
2897
   * _Scalar types_ include all of the above.
2898
 
2899
 
2900
The following operators are supported.  They are listed here in order
2901
of increasing precedence:
2902
 
2903
`,'
2904
     The comma or sequencing operator.  Expressions in a
2905
     comma-separated list are evaluated from left to right, with the
2906
     result of the entire expression being the last expression
2907
     evaluated.
2908
 
2909
`='
2910
     Assignment.  The value of an assignment expression is the value
2911
     assigned.  Defined on scalar types.
2912
 
2913
`OP='
2914
     Used in an expression of the form `A OP= B', and translated to
2915
     `A = A OP B'.  `OP=' and `=' have the same precedence.  OP is any
2916
     one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*',
2917
     `/', `%'.
2918
 
2919
`?:'
2920
     The ternary operator.  `A ? B : C' can be thought of as:  if A
2921
     then B else C.  A should be of an integral type.
2922
 
2923
`||'
2924
     Logical OR.  Defined on integral types.
2925
 
2926
`&&'
2927
     Logical AND.  Defined on integral types.
2928
 
2929
`|'
2930
     Bitwise OR.  Defined on integral types.
2931
 
2932
`^'
2933
     Bitwise exclusive-OR.  Defined on integral types.
2934
 
2935
`&'
2936
     Bitwise AND.  Defined on integral types.
2937
 
2938
`==, !='
2939
     Equality and inequality.  Defined on scalar types.  The value of
2940
     these expressions is 0 for false and non-zero for true.
2941
 
2942
`<, >, <=, >='
2943
     Less than, greater than, less than or equal, greater than or equal.
2944
     Defined on scalar types.  The value of these expressions is 0 for
2945
     false and non-zero for true.
2946
 
2947
`<<, >>'
2948
     left shift, and right shift.  Defined on integral types.
2949
 
2950
`@'
2951
     The GDB "artificial array" operator (*note Expressions:
2952
     Expressions.).
2953
 
2954
`+, -'
2955
     Addition and subtraction.  Defined on integral types,
2956
     floating-point types and pointer types.
2957
 
2958
`*, /, %'
2959
     Multiplication, division, and modulus.  Multiplication and
2960
     division are defined on integral and floating-point types.
2961
     Modulus is defined on integral types.
2962
 
2963
`++, --'
2964
     Increment and decrement.  When appearing before a variable, the
2965
     operation is performed before the variable is used in an
2966
     expression; when appearing after it, the variable's value is used
2967
     before the operation takes place.
2968
 
2969
`*'
2970
     Pointer dereferencing.  Defined on pointer types.  Same precedence
2971
     as `++'.
2972
 
2973
`&'
2974
     Address operator.  Defined on variables.  Same precedence as `++'.
2975
 
2976
     For debugging C++, GDB implements a use of `&' beyond what is
2977
     allowed in the C++ language itself: you can use `&(&REF)' to
2978
     examine the address where a C++ reference variable (declared with
2979
     `&REF') is stored.
2980
 
2981
`-'
2982
     Negative.  Defined on integral and floating-point types.  Same
2983
     precedence as `++'.
2984
 
2985
`!'
2986
     Logical negation.  Defined on integral types.  Same precedence as
2987
     `++'.
2988
 
2989
`~'
2990
     Bitwise complement operator.  Defined on integral types.  Same
2991
     precedence as `++'.
2992
 
2993
`., ->'
2994
     Structure member, and pointer-to-structure member.  For
2995
     convenience, GDB regards the two as equivalent, choosing whether
2996
     to dereference a pointer based on the stored type information.
2997
     Defined on `struct' and `union' data.
2998
 
2999
`.*, ->*'
3000
     Dereferences of pointers to members.
3001
 
3002
`[]'
3003
     Array indexing.  `A[I]' is defined as `*(A+I)'.  Same precedence
3004
     as `->'.
3005
 
3006
`()'
3007
     Function parameter list.  Same precedence as `->'.
3008
 
3009
`::'
3010
     C++ scope resolution operator.  Defined on `struct', `union', and
3011
     `class' types.
3012
 
3013
`::'
3014
     Doubled colons also represent the GDB scope operator (*note
3015
     Expressions: Expressions.).  Same precedence as `::', above.
3016
 
3017
   If an operator is redefined in the user code, GDB usually attempts
3018
to invoke the redefined version instead of using the operator's
3019
predefined meaning.
3020
 
3021

3022
File: gdb.info,  Node: C Constants,  Next: C Plus Plus Expressions,  Prev: C Operators,  Up: C
3023
 
3024
15.4.1.2 C and C++ Constants
3025
............................
3026
 
3027
GDB allows you to express the constants of C and C++ in the following
3028
ways:
3029
 
3030
   * Integer constants are a sequence of digits.  Octal constants are
3031
     specified by a leading `0' (i.e. zero), and hexadecimal constants
3032
     by a leading `0x' or `0X'.  Constants may also end with a letter
3033
     `l', specifying that the constant should be treated as a `long'
3034
     value.
3035
 
3036
   * Floating point constants are a sequence of digits, followed by a
3037
     decimal point, followed by a sequence of digits, and optionally
3038
     followed by an exponent.  An exponent is of the form:
3039
     `e[[+]|-]NNN', where NNN is another sequence of digits.  The `+'
3040
     is optional for positive exponents.  A floating-point constant may
3041
     also end with a letter `f' or `F', specifying that the constant
3042
     should be treated as being of the `float' (as opposed to the
3043
     default `double') type; or with a letter `l' or `L', which
3044
     specifies a `long double' constant.
3045
 
3046
   * Enumerated constants consist of enumerated identifiers, or their
3047
     integral equivalents.
3048
 
3049
   * Character constants are a single character surrounded by single
3050
     quotes (`''), or a number--the ordinal value of the corresponding
3051
     character (usually its ASCII value).  Within quotes, the single
3052
     character may be represented by a letter or by "escape sequences",
3053
     which are of the form `\NNN', where NNN is the octal representation
3054
     of the character's ordinal value; or of the form `\X', where `X'
3055
     is a predefined special character--for example, `\n' for newline.
3056
 
3057
   * String constants are a sequence of character constants surrounded
3058
     by double quotes (`"').  Any valid character constant (as described
3059
     above) may appear.  Double quotes within the string must be
3060
     preceded by a backslash, so for instance `"a\"b'c"' is a string of
3061
     five characters.
3062
 
3063
   * Pointer constants are an integral value.  You can also write
3064
     pointers to constants using the C operator `&'.
3065
 
3066
   * Array constants are comma-separated lists surrounded by braces `{'
3067
     and `}'; for example, `{1,2,3}' is a three-element array of
3068
     integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and
3069
     `{&"hi", &"there", &"fred"}' is a three-element array of pointers.
3070
 
3071

3072
File: gdb.info,  Node: C Plus Plus Expressions,  Next: C Defaults,  Prev: C Constants,  Up: C
3073
 
3074
15.4.1.3 C++ Expressions
3075
........................
3076
 
3077
GDB expression handling can interpret most C++ expressions.
3078
 
3079
     _Warning:_ GDB can only debug C++ code if you use the proper
3080
     compiler and the proper debug format.  Currently, GDB works best
3081
     when debugging C++ code that is compiled with GCC 2.95.3 or with
3082
     GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'.
3083
     DWARF 2 is preferred over stabs+.  Most configurations of GCC emit
3084
     either DWARF 2 or stabs+ as their default debug format, so you
3085
     usually don't need to specify a debug format explicitly.  Other
3086
     compilers and/or debug formats are likely to work badly or not at
3087
     all when using GDB to debug C++ code.
3088
 
3089
  1. Member function calls are allowed; you can use expressions like
3090
 
3091
          count = aml->GetOriginal(x, y)
3092
 
3093
  2. While a member function is active (in the selected stack frame),
3094
     your expressions have the same namespace available as the member
3095
     function; that is, GDB allows implicit references to the class
3096
     instance pointer `this' following the same rules as C++.
3097
 
3098
  3. You can call overloaded functions; GDB resolves the function call
3099
     to the right definition, with some restrictions.  GDB does not
3100
     perform overload resolution involving user-defined type
3101
     conversions, calls to constructors, or instantiations of templates
3102
     that do not exist in the program.  It also cannot handle ellipsis
3103
     argument lists or default arguments.
3104
 
3105
     It does perform integral conversions and promotions, floating-point
3106
     promotions, arithmetic conversions, pointer conversions,
3107
     conversions of class objects to base classes, and standard
3108
     conversions such as those of functions or arrays to pointers; it
3109
     requires an exact match on the number of function arguments.
3110
 
3111
     Overload resolution is always performed, unless you have specified
3112
     `set overload-resolution off'.  *Note GDB Features for C++:
3113
     Debugging C Plus Plus.
3114
 
3115
     You must specify `set overload-resolution off' in order to use an
3116
     explicit function signature to call an overloaded function, as in
3117
          p 'foo(char,int)'('x', 13)
3118
 
3119 342 jeremybenn
     The GDB command-completion facility can simplify this; see *note
3120 330 jeremybenn
     Command Completion: Completion.
3121
 
3122
  4. GDB understands variables declared as C++ references; you can use
3123
     them in expressions just as you do in C++ source--they are
3124
     automatically dereferenced.
3125
 
3126
     In the parameter list shown when GDB displays a frame, the values
3127
     of reference variables are not displayed (unlike other variables);
3128
     this avoids clutter, since references are often used for large
3129
     structures.  The _address_ of a reference variable is always
3130
     shown, unless you have specified `set print address off'.
3131
 
3132
  5. GDB supports the C++ name resolution operator `::'--your
3133
     expressions can use it just as expressions in your program do.
3134
     Since one scope may be defined in another, you can use `::'
3135
     repeatedly if necessary, for example in an expression like
3136
     `SCOPE1::SCOPE2::NAME'.  GDB also allows resolving name scope by
3137
     reference to source files, in both C and C++ debugging (*note
3138
     Program Variables: Variables.).
3139
 
3140
   In addition, when used with HP's C++ compiler, GDB supports calling
3141
virtual functions correctly, printing out virtual bases of objects,
3142
calling functions in a base subobject, casting objects, and invoking
3143
user-defined operators.
3144
 
3145

3146
File: gdb.info,  Node: C Defaults,  Next: C Checks,  Prev: C Plus Plus Expressions,  Up: C
3147
 
3148
15.4.1.4 C and C++ Defaults
3149
...........................
3150
 
3151
If you allow GDB to set type and range checking automatically, they
3152
both default to `off' whenever the working language changes to C or
3153
C++.  This happens regardless of whether you or GDB selects the working
3154
language.
3155
 
3156
   If you allow GDB to set the language automatically, it recognizes
3157
source files whose names end with `.c', `.C', or `.cc', etc, and when
3158
GDB enters code compiled from one of these files, it sets the working
3159
language to C or C++.  *Note Having GDB Infer the Source Language:
3160
Automatically, for further details.
3161
 
3162

3163
File: gdb.info,  Node: C Checks,  Next: Debugging C,  Prev: C Defaults,  Up: C
3164
 
3165
15.4.1.5 C and C++ Type and Range Checks
3166
........................................
3167
 
3168
By default, when GDB parses C or C++ expressions, type checking is not
3169
used.  However, if you turn type checking on, GDB considers two
3170
variables type equivalent if:
3171
 
3172
   * The two variables are structured and have the same structure,
3173
     union, or enumerated tag.
3174
 
3175
   * The two variables have the same type name, or types that have been
3176
     declared equivalent through `typedef'.
3177
 
3178
 
3179
   Range checking, if turned on, is done on mathematical operations.
3180
Array indices are not checked, since they are often used to index a
3181
pointer that is not itself an array.
3182
 
3183

3184
File: gdb.info,  Node: Debugging C,  Next: Debugging C Plus Plus,  Prev: C Checks,  Up: C
3185
 
3186
15.4.1.6 GDB and C
3187
..................
3188
 
3189
The `set print union' and `show print union' commands apply to the
3190
`union' type.  When set to `on', any `union' that is inside a `struct'
3191
or `class' is also printed.  Otherwise, it appears as `{...}'.
3192
 
3193
   The `@' operator aids in the debugging of dynamic arrays, formed
3194
with pointers and a memory allocation function.  *Note Expressions:
3195
Expressions.
3196
 
3197

3198
File: gdb.info,  Node: Debugging C Plus Plus,  Next: Decimal Floating Point,  Prev: Debugging C,  Up: C
3199
 
3200
15.4.1.7 GDB Features for C++
3201
.............................
3202
 
3203
Some GDB commands are particularly useful with C++, and some are
3204
designed specifically for use with C++.  Here is a summary:
3205
 
3206
`breakpoint menus'
3207
     When you want a breakpoint in a function whose name is overloaded,
3208
     GDB has the capability to display a menu of possible breakpoint
3209
     locations to help you specify which function definition you want.
3210
     *Note Ambiguous Expressions: Ambiguous Expressions.
3211
 
3212
`rbreak REGEX'
3213
     Setting breakpoints using regular expressions is helpful for
3214
     setting breakpoints on overloaded functions that are not members
3215
     of any special classes.  *Note Setting Breakpoints: Set Breaks.
3216
 
3217
`catch throw'
3218
`catch catch'
3219
     Debug C++ exception handling using these commands.  *Note Setting
3220
     Catchpoints: Set Catchpoints.
3221
 
3222
`ptype TYPENAME'
3223
     Print inheritance relationships as well as other information for
3224
     type TYPENAME.  *Note Examining the Symbol Table: Symbols.
3225
 
3226
`set print demangle'
3227
`show print demangle'
3228
`set print asm-demangle'
3229
`show print asm-demangle'
3230
     Control whether C++ symbols display in their source form, both when
3231
     displaying code as C++ source and when displaying disassemblies.
3232
     *Note Print Settings: Print Settings.
3233
 
3234
`set print object'
3235
`show print object'
3236
     Choose whether to print derived (actual) or declared types of
3237
     objects.  *Note Print Settings: Print Settings.
3238
 
3239
`set print vtbl'
3240
`show print vtbl'
3241
     Control the format for printing virtual function tables.  *Note
3242
     Print Settings: Print Settings.  (The `vtbl' commands do not work
3243
     on programs compiled with the HP ANSI C++ compiler (`aCC').)
3244
 
3245
`set overload-resolution on'
3246
     Enable overload resolution for C++ expression evaluation.  The
3247
     default is on.  For overloaded functions, GDB evaluates the
3248
     arguments and searches for a function whose signature matches the
3249 342 jeremybenn
     argument types, using the standard C++ conversion rules (see *note
3250 330 jeremybenn
     C++ Expressions: C Plus Plus Expressions, for details).  If it
3251
     cannot find a match, it emits a message.
3252
 
3253
`set overload-resolution off'
3254
     Disable overload resolution for C++ expression evaluation.  For
3255
     overloaded functions that are not class member functions, GDB
3256
     chooses the first function of the specified name that it finds in
3257
     the symbol table, whether or not its arguments are of the correct
3258
     type.  For overloaded functions that are class member functions,
3259
     GDB searches for a function whose signature _exactly_ matches the
3260
     argument types.
3261
 
3262
`show overload-resolution'
3263
     Show the current setting of overload resolution.
3264
 
3265
`Overloaded symbol names'
3266
     You can specify a particular definition of an overloaded symbol,
3267
     using the same notation that is used to declare such symbols in
3268
     C++: type `SYMBOL(TYPES)' rather than just SYMBOL.  You can also
3269
     use the GDB command-line word completion facilities to list the
3270
     available choices, or to finish the type list for you.  *Note
3271
     Command Completion: Completion, for details on how to do this.
3272
 
3273

3274
File: gdb.info,  Node: Decimal Floating Point,  Prev: Debugging C Plus Plus,  Up: C
3275
 
3276
15.4.1.8 Decimal Floating Point format
3277
......................................
3278
 
3279
GDB can examine, set and perform computations with numbers in decimal
3280
floating point format, which in the C language correspond to the
3281
`_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the
3282
extension to support decimal floating-point arithmetic.
3283
 
3284
   There are two encodings in use, depending on the architecture: BID
3285
(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed
3286
Decimal) for PowerPC.  GDB will use the appropriate encoding for the
3287
configured target.
3288
 
3289
   Because of a limitation in `libdecnumber', the library used by GDB
3290
to manipulate decimal floating point numbers, it is not possible to
3291
convert (using a cast, for example) integers wider than 32-bit to
3292
decimal float.
3293
 
3294
   In addition, in order to imitate GDB's behaviour with binary floating
3295
point computations, error checking in decimal float operations ignores
3296
underflow, overflow and divide by zero exceptions.
3297
 
3298
   In the PowerPC architecture, GDB provides a set of pseudo-registers
3299
to inspect `_Decimal128' values stored in floating point registers.
3300 342 jeremybenn
See *note PowerPC: PowerPC. for more details.
3301 330 jeremybenn
 
3302

3303
File: gdb.info,  Node: D,  Next: Objective-C,  Prev: C,  Up: Supported Languages
3304
 
3305
15.4.2 D
3306
--------
3307
 
3308
GDB can be used to debug programs written in D and compiled with GDC,
3309
LDC or DMD compilers. Currently GDB supports only one D specific
3310
feature -- dynamic arrays.
3311
 
3312

3313
File: gdb.info,  Node: Objective-C,  Next: Fortran,  Prev: D,  Up: Supported Languages
3314
 
3315
15.4.3 Objective-C
3316
------------------
3317
 
3318
This section provides information about some commands and command
3319 342 jeremybenn
options that are useful for debugging Objective-C code.  See also *note
3320
info classes: Symbols, and *note info selectors: Symbols, for a few
3321 330 jeremybenn
more commands specific to Objective-C support.
3322
 
3323
* Menu:
3324
 
3325
* Method Names in Commands::
3326
* The Print Command with Objective-C::
3327
 
3328

3329
File: gdb.info,  Node: Method Names in Commands,  Next: The Print Command with Objective-C,  Up: Objective-C
3330
 
3331
15.4.3.1 Method Names in Commands
3332
.................................
3333
 
3334
The following commands have been extended to accept Objective-C method
3335
names as line specifications:
3336
 
3337
   * `clear'
3338
 
3339
   * `break'
3340
 
3341
   * `info line'
3342
 
3343
   * `jump'
3344
 
3345
   * `list'
3346
 
3347
   A fully qualified Objective-C method name is specified as
3348
 
3349
     -[CLASS METHODNAME]
3350
 
3351
   where the minus sign is used to indicate an instance method and a
3352
plus sign (not shown) is used to indicate a class method.  The class
3353
name CLASS and method name METHODNAME are enclosed in brackets, similar
3354
to the way messages are specified in Objective-C source code.  For
3355
example, to set a breakpoint at the `create' instance method of class
3356
`Fruit' in the program currently being debugged, enter:
3357
 
3358
     break -[Fruit create]
3359
 
3360
   To list ten program lines around the `initialize' class method,
3361
enter:
3362
 
3363
     list +[NSText initialize]
3364
 
3365
   In the current version of GDB, the plus or minus sign is required.
3366
In future versions of GDB, the plus or minus sign will be optional, but
3367
you can use it to narrow the search.  It is also possible to specify
3368
just a method name:
3369
 
3370
     break create
3371
 
3372
   You must specify the complete method name, including any colons.  If
3373
your program's source files contain more than one `create' method,
3374
you'll be presented with a numbered list of classes that implement that
3375
method.  Indicate your choice by number, or type `0' to exit if none
3376
apply.
3377
 
3378
   As another example, to clear a breakpoint established at the
3379
`makeKeyAndOrderFront:' method of the `NSWindow' class, enter:
3380
 
3381
     clear -[NSWindow makeKeyAndOrderFront:]
3382
 
3383

3384
File: gdb.info,  Node: The Print Command with Objective-C,  Prev: Method Names in Commands,  Up: Objective-C
3385
 
3386
15.4.3.2 The Print Command With Objective-C
3387
...........................................
3388
 
3389
The print command has also been extended to accept methods.  For
3390
example:
3391
 
3392
     print -[OBJECT hash]
3393
 
3394
will tell GDB to send the `hash' message to OBJECT and print the
3395
result.  Also, an additional command has been added, `print-object' or
3396
`po' for short, which is meant to print the description of an object.
3397
However, this command may only work with certain Objective-C libraries
3398
that have a particular hook function, `_NSPrintForDebugger', defined.
3399
 
3400

3401
File: gdb.info,  Node: Fortran,  Next: Pascal,  Prev: Objective-C,  Up: Supported Languages
3402
 
3403
15.4.4 Fortran
3404
--------------
3405
 
3406
GDB can be used to debug programs written in Fortran, but it currently
3407
supports only the features of Fortran 77 language.
3408
 
3409
   Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers
3410
among them) append an underscore to the names of variables and
3411
functions.  When you debug programs compiled by those compilers, you
3412
will need to refer to variables and functions with a trailing
3413
underscore.
3414
 
3415
* Menu:
3416
 
3417
* Fortran Operators::           Fortran operators and expressions
3418
* Fortran Defaults::            Default settings for Fortran
3419
* Special Fortran Commands::    Special GDB commands for Fortran
3420
 
3421

3422
File: gdb.info,  Node: Fortran Operators,  Next: Fortran Defaults,  Up: Fortran
3423
 
3424
15.4.4.1 Fortran Operators and Expressions
3425
..........................................
3426
 
3427
Operators must be defined on values of specific types.  For instance,
3428
`+' is defined on numbers, but not on characters or other non-
3429
arithmetic types.  Operators are often defined on groups of types.
3430
 
3431
`**'
3432
     The exponentiation operator.  It raises the first operand to the
3433
     power of the second one.
3434
 
3435
`:'
3436
     The range operator.  Normally used in the form of array(low:high)
3437
     to represent a section of array.
3438
 
3439
`%'
3440
     The access component operator.  Normally used to access elements
3441
     in derived types.  Also suitable for unions.  As unions aren't
3442
     part of regular Fortran, this can only happen when accessing a
3443
     register that uses a gdbarch-defined union type.
3444
 
3445

3446
File: gdb.info,  Node: Fortran Defaults,  Next: Special Fortran Commands,  Prev: Fortran Operators,  Up: Fortran
3447
 
3448
15.4.4.2 Fortran Defaults
3449
.........................
3450
 
3451
Fortran symbols are usually case-insensitive, so GDB by default uses
3452
case-insensitive matches for Fortran symbols.  You can change that with
3453 342 jeremybenn
the `set case-insensitive' command, see *note Symbols::, for the
3454 330 jeremybenn
details.
3455
 
3456

3457
File: gdb.info,  Node: Special Fortran Commands,  Prev: Fortran Defaults,  Up: Fortran
3458
 
3459
15.4.4.3 Special Fortran Commands
3460
.................................
3461
 
3462
GDB has some commands to support Fortran-specific features, such as
3463
displaying common blocks.
3464
 
3465
`info common [COMMON-NAME]'
3466
     This command prints the values contained in the Fortran `COMMON'
3467
     block whose name is COMMON-NAME.  With no argument, the names of
3468
     all `COMMON' blocks visible at the current program location are
3469
     printed.
3470
 
3471

3472
File: gdb.info,  Node: Pascal,  Next: Modula-2,  Prev: Fortran,  Up: Supported Languages
3473
 
3474
15.4.5 Pascal
3475
-------------
3476
 
3477
Debugging Pascal programs which use sets, subranges, file variables, or
3478
nested functions does not currently work.  GDB does not support
3479
entering expressions, printing values, or similar features using Pascal
3480
syntax.
3481
 
3482
   The Pascal-specific command `set print pascal_static-members'
3483
controls whether static members of Pascal objects are displayed.  *Note
3484
pascal_static-members: Print Settings.
3485
 
3486

3487
File: gdb.info,  Node: Modula-2,  Next: Ada,  Prev: Pascal,  Up: Supported Languages
3488
 
3489
15.4.6 Modula-2
3490
---------------
3491
 
3492
The extensions made to GDB to support Modula-2 only support output from
3493
the GNU Modula-2 compiler (which is currently being developed).  Other
3494
Modula-2 compilers are not currently supported, and attempting to debug
3495
executables produced by them is most likely to give an error as GDB
3496
reads in the executable's symbol table.
3497
 
3498
* Menu:
3499
 
3500
* M2 Operators::                Built-in operators
3501
* Built-In Func/Proc::          Built-in functions and procedures
3502
* M2 Constants::                Modula-2 constants
3503
* M2 Types::                    Modula-2 types
3504
* M2 Defaults::                 Default settings for Modula-2
3505
* Deviations::                  Deviations from standard Modula-2
3506
* M2 Checks::                   Modula-2 type and range checks
3507
* M2 Scope::                    The scope operators `::' and `.'
3508
* GDB/M2::                      GDB and Modula-2
3509
 
3510

3511
File: gdb.info,  Node: M2 Operators,  Next: Built-In Func/Proc,  Up: Modula-2
3512
 
3513
15.4.6.1 Operators
3514
..................
3515
 
3516
Operators must be defined on values of specific types.  For instance,
3517
`+' is defined on numbers, but not on structures.  Operators are often
3518
defined on groups of types.  For the purposes of Modula-2, the
3519
following definitions hold:
3520
 
3521
   * _Integral types_ consist of `INTEGER', `CARDINAL', and their
3522
     subranges.
3523
 
3524
   * _Character types_ consist of `CHAR' and its subranges.
3525
 
3526
   * _Floating-point types_ consist of `REAL'.
3527
 
3528
   * _Pointer types_ consist of anything declared as `POINTER TO TYPE'.
3529
 
3530
   * _Scalar types_ consist of all of the above.
3531
 
3532
   * _Set types_ consist of `SET' and `BITSET' types.
3533
 
3534
   * _Boolean types_ consist of `BOOLEAN'.
3535
 
3536
The following operators are supported, and appear in order of
3537
increasing precedence:
3538
 
3539
`,'
3540
     Function argument or array index separator.
3541
 
3542
`:='
3543
     Assignment.  The value of VAR `:=' VALUE is VALUE.
3544
 
3545
`<, >'
3546
     Less than, greater than on integral, floating-point, or enumerated
3547
     types.
3548
 
3549
`<=, >='
3550
     Less than or equal to, greater than or equal to on integral,
3551
     floating-point and enumerated types, or set inclusion on set
3552
     types.  Same precedence as `<'.
3553
 
3554
`=, <>, #'
3555
     Equality and two ways of expressing inequality, valid on scalar
3556
     types.  Same precedence as `<'.  In GDB scripts, only `<>' is
3557
     available for inequality, since `#' conflicts with the script
3558
     comment character.
3559
 
3560
`IN'
3561
     Set membership.  Defined on set types and the types of their
3562
     members.  Same precedence as `<'.
3563
 
3564
`OR'
3565
     Boolean disjunction.  Defined on boolean types.
3566
 
3567
`AND, &'
3568
     Boolean conjunction.  Defined on boolean types.
3569
 
3570
`@'
3571
     The GDB "artificial array" operator (*note Expressions:
3572
     Expressions.).
3573
 
3574
`+, -'
3575
     Addition and subtraction on integral and floating-point types, or
3576
     union and difference on set types.
3577
 
3578
`*'
3579
     Multiplication on integral and floating-point types, or set
3580
     intersection on set types.
3581
 
3582
`/'
3583
     Division on floating-point types, or symmetric set difference on
3584
     set types.  Same precedence as `*'.
3585
 
3586
`DIV, MOD'
3587
     Integer division and remainder.  Defined on integral types.  Same
3588
     precedence as `*'.
3589
 
3590
`-'
3591
     Negative.  Defined on `INTEGER' and `REAL' data.
3592
 
3593
`^'
3594
     Pointer dereferencing.  Defined on pointer types.
3595
 
3596
`NOT'
3597
     Boolean negation.  Defined on boolean types.  Same precedence as
3598
     `^'.
3599
 
3600
`.'
3601
     `RECORD' field selector.  Defined on `RECORD' data.  Same
3602
     precedence as `^'.
3603
 
3604
`[]'
3605
     Array indexing.  Defined on `ARRAY' data.  Same precedence as `^'.
3606
 
3607
`()'
3608
     Procedure argument list.  Defined on `PROCEDURE' objects.  Same
3609
     precedence as `^'.
3610
 
3611
`::, .'
3612
     GDB and Modula-2 scope operators.
3613
 
3614
     _Warning:_ Set expressions and their operations are not yet
3615
     supported, so GDB treats the use of the operator `IN', or the use
3616
     of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>='
3617
     on sets as an error.
3618
 
3619

3620
File: gdb.info,  Node: Built-In Func/Proc,  Next: M2 Constants,  Prev: M2 Operators,  Up: Modula-2
3621
 
3622
15.4.6.2 Built-in Functions and Procedures
3623
..........................................
3624
 
3625
Modula-2 also makes available several built-in procedures and functions.
3626
In describing these, the following metavariables are used:
3627
 
3628
A
3629
     represents an `ARRAY' variable.
3630
 
3631
C
3632
     represents a `CHAR' constant or variable.
3633
 
3634
I
3635
     represents a variable or constant of integral type.
3636
 
3637
M
3638
     represents an identifier that belongs to a set.  Generally used in
3639
     the same function with the metavariable S.  The type of S should
3640
     be `SET OF MTYPE' (where MTYPE is the type of M).
3641
 
3642
N
3643
     represents a variable or constant of integral or floating-point
3644
     type.
3645
 
3646
R
3647
     represents a variable or constant of floating-point type.
3648
 
3649
T
3650
     represents a type.
3651
 
3652
V
3653
     represents a variable.
3654
 
3655
X
3656
     represents a variable or constant of one of many types.  See the
3657
     explanation of the function for details.
3658
 
3659
   All Modula-2 built-in procedures also return a result, described
3660
below.
3661
 
3662
`ABS(N)'
3663
     Returns the absolute value of N.
3664
 
3665
`CAP(C)'
3666
     If C is a lower case letter, it returns its upper case equivalent,
3667
     otherwise it returns its argument.
3668
 
3669
`CHR(I)'
3670
     Returns the character whose ordinal value is I.
3671
 
3672
`DEC(V)'
3673
     Decrements the value in the variable V by one.  Returns the new
3674
     value.
3675
 
3676
`DEC(V,I)'
3677
     Decrements the value in the variable V by I.  Returns the new
3678
     value.
3679
 
3680
`EXCL(M,S)'
3681
     Removes the element M from the set S.  Returns the new set.
3682
 
3683
`FLOAT(I)'
3684
     Returns the floating point equivalent of the integer I.
3685
 
3686
`HIGH(A)'
3687
     Returns the index of the last member of A.
3688
 
3689
`INC(V)'
3690
     Increments the value in the variable V by one.  Returns the new
3691
     value.
3692
 
3693
`INC(V,I)'
3694
     Increments the value in the variable V by I.  Returns the new
3695
     value.
3696
 
3697
`INCL(M,S)'
3698
     Adds the element M to the set S if it is not already there.
3699
     Returns the new set.
3700
 
3701
`MAX(T)'
3702
     Returns the maximum value of the type T.
3703
 
3704
`MIN(T)'
3705
     Returns the minimum value of the type T.
3706
 
3707
`ODD(I)'
3708
     Returns boolean TRUE if I is an odd number.
3709
 
3710
`ORD(X)'
3711
     Returns the ordinal value of its argument.  For example, the
3712
     ordinal value of a character is its ASCII value (on machines
3713
     supporting the ASCII character set).  X must be of an ordered
3714
     type, which include integral, character and enumerated types.
3715
 
3716
`SIZE(X)'
3717
     Returns the size of its argument.  X can be a variable or a type.
3718
 
3719
`TRUNC(R)'
3720
     Returns the integral part of R.
3721
 
3722
`TSIZE(X)'
3723
     Returns the size of its argument.  X can be a variable or a type.
3724
 
3725
`VAL(T,I)'
3726
     Returns the member of the type T whose ordinal value is I.
3727
 
3728
     _Warning:_  Sets and their operations are not yet supported, so
3729
     GDB treats the use of procedures `INCL' and `EXCL' as an error.
3730
 
3731

3732
File: gdb.info,  Node: M2 Constants,  Next: M2 Types,  Prev: Built-In Func/Proc,  Up: Modula-2
3733
 
3734
15.4.6.3 Constants
3735
..................
3736
 
3737
GDB allows you to express the constants of Modula-2 in the following
3738
ways:
3739
 
3740
   * Integer constants are simply a sequence of digits.  When used in an
3741
     expression, a constant is interpreted to be type-compatible with
3742
     the rest of the expression.  Hexadecimal integers are specified by
3743
     a trailing `H', and octal integers by a trailing `B'.
3744
 
3745
   * Floating point constants appear as a sequence of digits, followed
3746
     by a decimal point and another sequence of digits.  An optional
3747
     exponent can then be specified, in the form `E[+|-]NNN', where
3748
     `[+|-]NNN' is the desired exponent.  All of the digits of the
3749
     floating point constant must be valid decimal (base 10) digits.
3750
 
3751
   * Character constants consist of a single character enclosed by a
3752
     pair of like quotes, either single (`'') or double (`"').  They may
3753
     also be expressed by their ordinal value (their ASCII value,
3754
     usually) followed by a `C'.
3755
 
3756
   * String constants consist of a sequence of characters enclosed by a
3757
     pair of like quotes, either single (`'') or double (`"').  Escape
3758
     sequences in the style of C are also allowed.  *Note C and C++
3759
     Constants: C Constants, for a brief explanation of escape
3760
     sequences.
3761
 
3762
   * Enumerated constants consist of an enumerated identifier.
3763
 
3764
   * Boolean constants consist of the identifiers `TRUE' and `FALSE'.
3765
 
3766
   * Pointer constants consist of integral values only.
3767
 
3768
   * Set constants are not yet supported.
3769
 
3770

3771
File: gdb.info,  Node: M2 Types,  Next: M2 Defaults,  Prev: M2 Constants,  Up: Modula-2
3772
 
3773
15.4.6.4 Modula-2 Types
3774
.......................
3775
 
3776
Currently GDB can print the following data types in Modula-2 syntax:
3777
array types, record types, set types, pointer types, procedure types,
3778
enumerated types, subrange types and base types.  You can also print
3779
the contents of variables declared using these type.  This section
3780
gives a number of simple source code examples together with sample GDB
3781
sessions.
3782
 
3783
   The first example contains the following section of code:
3784
 
3785
     VAR
3786
        s: SET OF CHAR ;
3787
        r: [20..40] ;
3788
 
3789
and you can request GDB to interrogate the type and value of `r' and
3790
`s'.
3791
 
3792
     (gdb) print s
3793
     {'A'..'C', 'Z'}
3794
     (gdb) ptype s
3795
     SET OF CHAR
3796
     (gdb) print r
3797
     21
3798
     (gdb) ptype r
3799
     [20..40]
3800
 
3801
Likewise if your source code declares `s' as:
3802
 
3803
     VAR
3804
        s: SET ['A'..'Z'] ;
3805
 
3806
then you may query the type of `s' by:
3807
 
3808
     (gdb) ptype s
3809
     type = SET ['A'..'Z']
3810
 
3811
Note that at present you cannot interactively manipulate set
3812
expressions using the debugger.
3813
 
3814
   The following example shows how you might declare an array in
3815
Modula-2 and how you can interact with GDB to print its type and
3816
contents:
3817
 
3818
     VAR
3819
        s: ARRAY [-10..10] OF CHAR ;
3820
 
3821
     (gdb) ptype s
3822
     ARRAY [-10..10] OF CHAR
3823
 
3824
   Note that the array handling is not yet complete and although the
3825
type is printed correctly, expression handling still assumes that all
3826
arrays have a lower bound of zero and not `-10' as in the example above.
3827
 
3828
   Here are some more type related Modula-2 examples:
3829
 
3830
     TYPE
3831
        colour = (blue, red, yellow, green) ;
3832
        t = [blue..yellow] ;
3833
     VAR
3834
        s: t ;
3835
     BEGIN
3836
        s := blue ;
3837
 
3838
The GDB interaction shows how you can query the data type and value of
3839
a variable.
3840
 
3841
     (gdb) print s
3842
     $1 = blue
3843
     (gdb) ptype t
3844
     type = [blue..yellow]
3845
 
3846
In this example a Modula-2 array is declared and its contents
3847
displayed.  Observe that the contents are written in the same way as
3848
their `C' counterparts.
3849
 
3850
     VAR
3851
        s: ARRAY [1..5] OF CARDINAL ;
3852
     BEGIN
3853
        s[1] := 1 ;
3854
 
3855
     (gdb) print s
3856
     $1 = {1, 0, 0, 0, 0}
3857
     (gdb) ptype s
3858
     type = ARRAY [1..5] OF CARDINAL
3859
 
3860
   The Modula-2 language interface to GDB also understands pointer
3861
types as shown in this example:
3862
 
3863
     VAR
3864
        s: POINTER TO ARRAY [1..5] OF CARDINAL ;
3865
     BEGIN
3866
        NEW(s) ;
3867
        s^[1] := 1 ;
3868
 
3869
and you can request that GDB describes the type of `s'.
3870
 
3871
     (gdb) ptype s
3872
     type = POINTER TO ARRAY [1..5] OF CARDINAL
3873
 
3874
   GDB handles compound types as we can see in this example.  Here we
3875
combine array types, record types, pointer types and subrange types:
3876
 
3877
     TYPE
3878
        foo = RECORD
3879
                 f1: CARDINAL ;
3880
                 f2: CHAR ;
3881
                 f3: myarray ;
3882
              END ;
3883
 
3884
        myarray = ARRAY myrange OF CARDINAL ;
3885
        myrange = [-2..2] ;
3886
     VAR
3887
        s: POINTER TO ARRAY myrange OF foo ;
3888
 
3889
and you can ask GDB to describe the type of `s' as shown below.
3890
 
3891
     (gdb) ptype s
3892
     type = POINTER TO ARRAY [-2..2] OF foo = RECORD
3893
         f1 : CARDINAL;
3894
         f2 : CHAR;
3895
         f3 : ARRAY [-2..2] OF CARDINAL;
3896
     END
3897
 
3898

3899
File: gdb.info,  Node: M2 Defaults,  Next: Deviations,  Prev: M2 Types,  Up: Modula-2
3900
 
3901
15.4.6.5 Modula-2 Defaults
3902
..........................
3903
 
3904
If type and range checking are set automatically by GDB, they both
3905
default to `on' whenever the working language changes to Modula-2.
3906
This happens regardless of whether you or GDB selected the working
3907
language.
3908
 
3909
   If you allow GDB to set the language automatically, then entering
3910
code compiled from a file whose name ends with `.mod' sets the working
3911
language to Modula-2.  *Note Having GDB Infer the Source Language:
3912
Automatically, for further details.
3913
 
3914

3915
File: gdb.info,  Node: Deviations,  Next: M2 Checks,  Prev: M2 Defaults,  Up: Modula-2
3916
 
3917
15.4.6.6 Deviations from Standard Modula-2
3918
..........................................
3919
 
3920
A few changes have been made to make Modula-2 programs easier to debug.
3921
This is done primarily via loosening its type strictness:
3922
 
3923
   * Unlike in standard Modula-2, pointer constants can be formed by
3924
     integers.  This allows you to modify pointer variables during
3925
     debugging.  (In standard Modula-2, the actual address contained in
3926
     a pointer variable is hidden from you; it can only be modified
3927
     through direct assignment to another pointer variable or
3928
     expression that returned a pointer.)
3929
 
3930
   * C escape sequences can be used in strings and characters to
3931
     represent non-printable characters.  GDB prints out strings with
3932
     these escape sequences embedded.  Single non-printable characters
3933
     are printed using the `CHR(NNN)' format.
3934
 
3935
   * The assignment operator (`:=') returns the value of its right-hand
3936
     argument.
3937
 
3938
   * All built-in procedures both modify _and_ return their argument.
3939
 
3940

3941
File: gdb.info,  Node: M2 Checks,  Next: M2 Scope,  Prev: Deviations,  Up: Modula-2
3942
 
3943
15.4.6.7 Modula-2 Type and Range Checks
3944
.......................................
3945
 
3946
     _Warning:_ in this release, GDB does not yet perform type or range
3947
     checking.
3948
 
3949
   GDB considers two Modula-2 variables type equivalent if:
3950
 
3951
   * They are of types that have been declared equivalent via a `TYPE
3952
     T1 = T2' statement
3953
 
3954
   * They have been declared on the same line.  (Note:  This is true of
3955
     the GNU Modula-2 compiler, but it may not be true of other
3956
     compilers.)
3957
 
3958
   As long as type checking is enabled, any attempt to combine variables
3959
whose types are not equivalent is an error.
3960
 
3961
   Range checking is done on all mathematical operations, assignment,
3962
array index bounds, and all built-in functions and procedures.
3963
 
3964

3965
File: gdb.info,  Node: M2 Scope,  Next: GDB/M2,  Prev: M2 Checks,  Up: Modula-2
3966
 
3967
15.4.6.8 The Scope Operators `::' and `.'
3968
.........................................
3969
 
3970
There are a few subtle differences between the Modula-2 scope operator
3971
(`.') and the GDB scope operator (`::').  The two have similar syntax:
3972
 
3973
 
3974
     MODULE . ID
3975
     SCOPE :: ID
3976
 
3977
where SCOPE is the name of a module or a procedure, MODULE the name of
3978
a module, and ID is any declared identifier within your program, except
3979
another module.
3980
 
3981
   Using the `::' operator makes GDB search the scope specified by
3982
SCOPE for the identifier ID.  If it is not found in the specified
3983
scope, then GDB searches all scopes enclosing the one specified by
3984
SCOPE.
3985
 
3986
   Using the `.' operator makes GDB search the current scope for the
3987
identifier specified by ID that was imported from the definition module
3988
specified by MODULE.  With this operator, it is an error if the
3989
identifier ID was not imported from definition module MODULE, or if ID
3990
is not an identifier in MODULE.
3991
 
3992

3993
File: gdb.info,  Node: GDB/M2,  Prev: M2 Scope,  Up: Modula-2
3994
 
3995
15.4.6.9 GDB and Modula-2
3996
.........................
3997
 
3998
Some GDB commands have little use when debugging Modula-2 programs.
3999
Five subcommands of `set print' and `show print' apply specifically to
4000
C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'.
4001
The first four apply to C++, and the last to the C `union' type, which
4002
has no direct analogue in Modula-2.
4003
 
4004
   The `@' operator (*note Expressions: Expressions.), while available
4005
with any language, is not useful with Modula-2.  Its intent is to aid
4006
the debugging of "dynamic arrays", which cannot be created in Modula-2
4007
as they can in C or C++.  However, because an address can be specified
4008
by an integral constant, the construct `{TYPE}ADREXP' is still useful.
4009
 
4010
   In GDB scripts, the Modula-2 inequality operator `#' is interpreted
4011
as the beginning of a comment.  Use `<>' instead.
4012
 
4013

4014
File: gdb.info,  Node: Ada,  Prev: Modula-2,  Up: Supported Languages
4015
 
4016
15.4.7 Ada
4017
----------
4018
 
4019
The extensions made to GDB for Ada only support output from the GNU Ada
4020
(GNAT) compiler.  Other Ada compilers are not currently supported, and
4021
attempting to debug executables produced by them is most likely to be
4022
difficult.
4023
 
4024
* Menu:
4025
 
4026
* Ada Mode Intro::              General remarks on the Ada syntax
4027
                                   and semantics supported by Ada mode
4028
                                   in GDB.
4029
* Omissions from Ada::          Restrictions on the Ada expression syntax.
4030
* Additions to Ada::            Extensions of the Ada expression syntax.
4031
* Stopping Before Main Program:: Debugging the program during elaboration.
4032
* Ada Tasks::                   Listing and setting breakpoints in tasks.
4033
* Ada Tasks and Core Files::    Tasking Support when Debugging Core Files
4034
* Ada Glitches::                Known peculiarities of Ada mode.
4035
 
4036

4037
File: gdb.info,  Node: Ada Mode Intro,  Next: Omissions from Ada,  Up: Ada
4038
 
4039
15.4.7.1 Introduction
4040
.....................
4041
 
4042
The Ada mode of GDB supports a fairly large subset of Ada expression
4043
syntax, with some extensions.  The philosophy behind the design of this
4044
subset is
4045
 
4046
   * That GDB should provide basic literals and access to operations for
4047
     arithmetic, dereferencing, field selection, indexing, and
4048
     subprogram calls, leaving more sophisticated computations to
4049
     subprograms written into the program (which therefore may be
4050
     called from GDB).
4051
 
4052
   * That type safety and strict adherence to Ada language restrictions
4053
     are not particularly important to the GDB user.
4054
 
4055
   * That brevity is important to the GDB user.
4056
 
4057
   Thus, for brevity, the debugger acts as if all names declared in
4058
user-written packages are directly visible, even if they are not visible
4059
according to Ada rules, thus making it unnecessary to fully qualify most
4060
names with their packages, regardless of context.  Where this causes
4061
ambiguity, GDB asks the user's intent.
4062
 
4063
   The debugger will start in Ada mode if it detects an Ada main
4064
program.  As for other languages, it will enter Ada mode when stopped
4065
in a program that was translated from an Ada source file.
4066
 
4067
   While in Ada mode, you may use `-' for comments.  This is useful
4068
mostly for documenting command files.  The standard GDB comment (`#')
4069
still works at the beginning of a line in Ada mode, but not in the
4070
middle (to allow based literals).
4071
 
4072
   The debugger supports limited overloading.  Given a subprogram call
4073
in which the function symbol has multiple definitions, it will use the
4074
number of actual parameters and some information about their types to
4075
attempt to narrow the set of definitions.  It also makes very limited
4076
use of context, preferring procedures to functions in the context of
4077
the `call' command, and functions to procedures elsewhere.
4078
 
4079

4080
File: gdb.info,  Node: Omissions from Ada,  Next: Additions to Ada,  Prev: Ada Mode Intro,  Up: Ada
4081
 
4082
15.4.7.2 Omissions from Ada
4083
...........................
4084
 
4085
Here are the notable omissions from the subset:
4086
 
4087
   * Only a subset of the attributes are supported:
4088
 
4089
        - 'First, 'Last, and 'Length  on array objects (not on types
4090
          and subtypes).
4091
 
4092
        - 'Min and 'Max.
4093
 
4094
        - 'Pos and 'Val.
4095
 
4096
        - 'Tag.
4097
 
4098
        - 'Range on array objects (not subtypes), but only as the right
4099
          operand of the membership (`in') operator.
4100
 
4101
        - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT
4102
          extension).
4103
 
4104
        - 'Address.
4105
 
4106
   * The names in `Characters.Latin_1' are not available and
4107
     concatenation is not implemented.  Thus, escape characters in
4108
     strings are not currently available.
4109
 
4110
   * Equality tests (`=' and `/=') on arrays test for bitwise equality
4111
     of representations.  They will generally work correctly for
4112
     strings and arrays whose elements have integer or enumeration
4113
     types.  They may not work correctly for arrays whose element types
4114
     have user-defined equality, for arrays of real values (in
4115
     particular, IEEE-conformant floating point, because of negative
4116
     zeroes and NaNs), and for arrays whose elements contain unused
4117
     bits with indeterminate values.
4118
 
4119
   * The other component-by-component array operations (`and', `or',
4120
     `xor', `not', and relational tests other than equality) are not
4121
     implemented.
4122
 
4123
   * There is limited support for array and record aggregates.  They are
4124
     permitted only on the right sides of assignments, as in these
4125
     examples:
4126
 
4127
          (gdb) set An_Array := (1, 2, 3, 4, 5, 6)
4128
          (gdb) set An_Array := (1, others => 0)
4129
          (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
4130
          (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
4131
          (gdb) set A_Record := (1, "Peter", True);
4132
          (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True)
4133
 
4134
     Changing a discriminant's value by assigning an aggregate has an
4135
     undefined effect if that discriminant is used within the record.
4136
     However, you can first modify discriminants by directly assigning
4137
     to them (which normally would not be allowed in Ada), and then
4138
     performing an aggregate assignment.  For example, given a variable
4139
     `A_Rec' declared to have a type such as:
4140
 
4141
          type Rec (Len : Small_Integer := 0) is record
4142
              Id : Integer;
4143
              Vals : IntArray (1 .. Len);
4144
          end record;
4145
 
4146
     you can assign a value with a different size of `Vals' with two
4147
     assignments:
4148
 
4149
          (gdb) set A_Rec.Len := 4
4150
          (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
4151
 
4152
     As this example also illustrates, GDB is very loose about the usual
4153
     rules concerning aggregates.  You may leave out some of the
4154
     components of an array or record aggregate (such as the `Len'
4155
     component in the assignment to `A_Rec' above); they will retain
4156
     their original values upon assignment.  You may freely use dynamic
4157
     values as indices in component associations.  You may even use
4158
     overlapping or redundant component associations, although which
4159
     component values are assigned in such cases is not defined.
4160
 
4161
   * Calls to dispatching subprograms are not implemented.
4162
 
4163
   * The overloading algorithm is much more limited (i.e., less
4164
     selective) than that of real Ada.  It makes only limited use of
4165
     the context in which a subexpression appears to resolve its
4166
     meaning, and it is much looser in its rules for allowing type
4167
     matches.  As a result, some function calls will be ambiguous, and
4168
     the user will be asked to choose the proper resolution.
4169
 
4170
   * The `new' operator is not implemented.
4171
 
4172
   * Entry calls are not implemented.
4173
 
4174
   * Aside from printing, arithmetic operations on the native VAX
4175
     floating-point formats are not supported.
4176
 
4177
   * It is not possible to slice a packed array.
4178
 
4179
   * The names `True' and `False', when not part of a qualified name,
4180
     are interpreted as if implicitly prefixed by `Standard',
4181
     regardless of context.  Should your program redefine these names
4182
     in a package or procedure (at best a dubious practice), you will
4183
     have to use fully qualified names to access their new definitions.
4184
 
4185

4186
File: gdb.info,  Node: Additions to Ada,  Next: Stopping Before Main Program,  Prev: Omissions from Ada,  Up: Ada
4187
 
4188
15.4.7.3 Additions to Ada
4189
.........................
4190
 
4191
As it does for other languages, GDB makes certain generic extensions to
4192
Ada (*note Expressions::):
4193
 
4194
   * If the expression E is a variable residing in memory (typically a
4195
     local variable or array element) and N is a positive integer, then
4196
     `E@N' displays the values of E and the N-1 adjacent variables
4197
     following it in memory as an array.  In Ada, this operator is
4198
     generally not necessary, since its prime use is in displaying
4199
     parts of an array, and slicing will usually do this in Ada.
4200
     However, there are occasional uses when debugging programs in
4201
     which certain debugging information has been optimized away.
4202
 
4203
   * `B::VAR' means "the variable named VAR that appears in function or
4204
     file B."  When B is a file name, you must typically surround it in
4205
     single quotes.
4206
 
4207
   * The expression `{TYPE} ADDR' means "the variable of type TYPE that
4208
     appears at address ADDR."
4209
 
4210
   * A name starting with `$' is a convenience variable (*note
4211
     Convenience Vars::) or a machine register (*note Registers::).
4212
 
4213
   In addition, GDB provides a few other shortcuts and outright
4214
additions specific to Ada:
4215
 
4216
   * The assignment statement is allowed as an expression, returning
4217
     its right-hand operand as its value.  Thus, you may enter
4218
 
4219
          (gdb) set x := y + 3
4220
          (gdb) print A(tmp := y + 1)
4221
 
4222
   * The semicolon is allowed as an "operator,"  returning as its value
4223
     the value of its right-hand operand.  This allows, for example,
4224
     complex conditional breaks:
4225
 
4226
          (gdb) break f
4227
          (gdb) condition 1 (report(i); k += 1; A(k) > 100)
4228
 
4229
   * Rather than use catenation and symbolic character names to
4230
     introduce special characters into strings, one may instead use a
4231
     special bracket notation, which is also used to print strings.  A
4232
     sequence of characters of the form `["XX"]' within a string or
4233
     character literal denotes the (single) character whose numeric
4234
     encoding is XX in hexadecimal.  The sequence of characters `["""]'
4235
     also denotes a single quotation mark in strings.   For example,
4236
             "One line.["0a"]Next line.["0a"]"
4237
     contains an ASCII newline character (`Ada.Characters.Latin_1.LF')
4238
     after each period.
4239
 
4240
   * The subtype used as a prefix for the attributes 'Pos, 'Min, and
4241
     'Max is optional (and is ignored in any case).  For example, it is
4242
     valid to write
4243
 
4244
          (gdb) print 'max(x, y)
4245
 
4246
   * When printing arrays, GDB uses positional notation when the array
4247
     has a lower bound of 1, and uses a modified named notation
4248
     otherwise.  For example, a one-dimensional array of three integers
4249
     with a lower bound of 3 might print as
4250
 
4251
          (3 => 10, 17, 1)
4252
 
4253
     That is, in contrast to valid Ada, only the first component has a
4254
     `=>' clause.
4255
 
4256
   * You may abbreviate attributes in expressions with any unique,
4257
     multi-character subsequence of their names (an exact match gets
4258
     preference).  For example, you may use a'len, a'gth, or a'lh in
4259
     place of  a'length.
4260
 
4261
   * Since Ada is case-insensitive, the debugger normally maps
4262
     identifiers you type to lower case.  The GNAT compiler uses
4263
     upper-case characters for some of its internal identifiers, which
4264
     are normally of no interest to users.  For the rare occasions when
4265
     you actually have to look at them, enclose them in angle brackets
4266
     to avoid the lower-case mapping.  For example,
4267
          (gdb) print [0]
4268
 
4269
   * Printing an object of class-wide type or dereferencing an
4270
     access-to-class-wide value will display all the components of the
4271
     object's specific type (as indicated by its run-time tag).
4272
     Likewise, component selection on such a value will operate on the
4273
     specific type of the object.
4274
 
4275
 
4276

4277
File: gdb.info,  Node: Stopping Before Main Program,  Next: Ada Tasks,  Prev: Additions to Ada,  Up: Ada
4278
 
4279
15.4.7.4 Stopping at the Very Beginning
4280
.......................................
4281
 
4282
It is sometimes necessary to debug the program during elaboration, and
4283
before reaching the main procedure.  As defined in the Ada Reference
4284
Manual, the elaboration code is invoked from a procedure called
4285
`adainit'.  To run your program up to the beginning of elaboration,
4286
simply use the following two commands: `tbreak adainit' and `run'.
4287
 
4288

4289
File: gdb.info,  Node: Ada Tasks,  Next: Ada Tasks and Core Files,  Prev: Stopping Before Main Program,  Up: Ada
4290
 
4291
15.4.7.5 Extensions for Ada Tasks
4292
.................................
4293
 
4294
Support for Ada tasks is analogous to that for threads (*note
4295
Threads::).  GDB provides the following task-related commands:
4296
 
4297
`info tasks'
4298
     This command shows a list of current Ada tasks, as in the
4299
     following example:
4300
 
4301
          (gdb) info tasks
4302
            ID       TID P-ID Pri State                 Name
4303
             1   8088000   0   15 Child Activation Wait main_task
4304
             2   80a4000   1   15 Accept Statement      b
4305
             3   809a800   1   15 Child Activation Wait a
4306
          *  4   80ae800   3   15 Runnable              c
4307
 
4308
     In this listing, the asterisk before the last task indicates it to
4309
     be the task currently being inspected.
4310
 
4311
    ID
4312
          Represents GDB's internal task number.
4313
 
4314
    TID
4315
          The Ada task ID.
4316
 
4317
    P-ID
4318
          The parent's task ID (GDB's internal task number).
4319
 
4320
    Pri
4321
          The base priority of the task.
4322
 
4323
    State
4324
          Current state of the task.
4325
 
4326
         `Unactivated'
4327
               The task has been created but has not been activated.
4328
               It cannot be executing.
4329
 
4330
         `Runnable'
4331
               The task is not blocked for any reason known to Ada.
4332
               (It may be waiting for a mutex, though.) It is
4333
               conceptually "executing" in normal mode.
4334
 
4335
         `Terminated'
4336
               The task is terminated, in the sense of ARM 9.3 (5).
4337
               Any dependents that were waiting on terminate
4338
               alternatives have been awakened and have terminated
4339
               themselves.
4340
 
4341
         `Child Activation Wait'
4342
               The task is waiting for created tasks to complete
4343
               activation.
4344
 
4345
         `Accept Statement'
4346
               The task is waiting on an accept or selective wait
4347
               statement.
4348
 
4349
         `Waiting on entry call'
4350
               The task is waiting on an entry call.
4351
 
4352
         `Async Select Wait'
4353
               The task is waiting to start the abortable part of an
4354
               asynchronous select statement.
4355
 
4356
         `Delay Sleep'
4357
               The task is waiting on a select statement with only a
4358
               delay alternative open.
4359
 
4360
         `Child Termination Wait'
4361
               The task is sleeping having completed a master within
4362
               itself, and is waiting for the tasks dependent on that
4363
               master to become terminated or waiting on a terminate
4364
               Phase.
4365
 
4366
         `Wait Child in Term Alt'
4367
               The task is sleeping waiting for tasks on terminate
4368
               alternatives to finish terminating.
4369
 
4370
         `Accepting RV with TASKNO'
4371
               The task is accepting a rendez-vous with the task TASKNO.
4372
 
4373
    Name
4374
          Name of the task in the program.
4375
 
4376
 
4377
`info task TASKNO'
4378
     This command shows detailled informations on the specified task,
4379
     as in the following example:
4380
          (gdb) info tasks
4381
            ID       TID P-ID Pri State                  Name
4382
             1   8077880    0  15 Child Activation Wait  main_task
4383
          *  2   807c468    1  15 Runnable               task_1
4384
          (gdb) info task 2
4385
          Ada Task: 0x807c468
4386
          Name: task_1
4387
          Thread: 0x807f378
4388
          Parent: 1 (main_task)
4389
          Base Priority: 15
4390
          State: Runnable
4391
 
4392
`task'
4393
     This command prints the ID of the current task.
4394
 
4395
          (gdb) info tasks
4396
            ID       TID P-ID Pri State                  Name
4397
             1   8077870    0  15 Child Activation Wait  main_task
4398
          *  2   807c458    1  15 Runnable               t
4399
          (gdb) task
4400
          [Current task is 2]
4401
 
4402
`task TASKNO'
4403
     This command is like the `thread THREADNO' command (*note
4404
     Threads::).  It switches the context of debugging from the current
4405
     task to the given task.
4406
 
4407
          (gdb) info tasks
4408
            ID       TID P-ID Pri State                  Name
4409
             1   8077870    0  15 Child Activation Wait  main_task
4410
          *  2   807c458    1  15 Runnable               t
4411
          (gdb) task 1
4412
          [Switching to task 1]
4413
          #0  0x8067726 in pthread_cond_wait ()
4414
          (gdb) bt
4415
          #0  0x8067726 in pthread_cond_wait ()
4416
          #1  0x8056714 in system.os_interface.pthread_cond_wait ()
4417
          #2  0x805cb63 in system.task_primitives.operations.sleep ()
4418
          #3  0x806153e in system.tasking.stages.activate_tasks ()
4419
          #4  0x804aacc in un () at un.adb:5
4420
 
4421
`break LINESPEC task TASKNO'
4422
`break LINESPEC task TASKNO if ...'
4423
     These commands are like the `break ... thread ...' command (*note
4424
     Thread Stops::).  LINESPEC specifies source lines, as described in
4425 342 jeremybenn
     *note Specify Location::.
4426 330 jeremybenn
 
4427
     Use the qualifier `task TASKNO' with a breakpoint command to
4428
     specify that you only want GDB to stop the program when a
4429
     particular Ada task reaches this breakpoint.  TASKNO is one of the
4430
     numeric task identifiers assigned by GDB, shown in the first
4431
     column of the `info tasks' display.
4432
 
4433
     If you do not specify `task TASKNO' when you set a breakpoint, the
4434
     breakpoint applies to _all_ tasks of your program.
4435
 
4436
     You can use the `task' qualifier on conditional breakpoints as
4437
     well; in this case, place `task TASKNO' before the breakpoint
4438
     condition (before the `if').
4439
 
4440
     For example,
4441
 
4442
          (gdb) info tasks
4443
            ID       TID P-ID Pri State                 Name
4444
             1 140022020   0   15 Child Activation Wait main_task
4445
             2 140045060   1   15 Accept/Select Wait    t2
4446
             3 140044840   1   15 Runnable              t1
4447
          *  4 140056040   1   15 Runnable              t3
4448
          (gdb) b 15 task 2
4449
          Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
4450
          (gdb) cont
4451
          Continuing.
4452
          task # 1 running
4453
          task # 2 running
4454
 
4455
          Breakpoint 5, test_task_debug () at test_task_debug.adb:15
4456
          15               flush;
4457
          (gdb) info tasks
4458
            ID       TID P-ID Pri State                 Name
4459
             1 140022020   0   15 Child Activation Wait main_task
4460
          *  2 140045060   1   15 Runnable              t2
4461
             3 140044840   1   15 Runnable              t1
4462
             4 140056040   1   15 Delay Sleep           t3
4463
 
4464

4465
File: gdb.info,  Node: Ada Tasks and Core Files,  Next: Ada Glitches,  Prev: Ada Tasks,  Up: Ada
4466
 
4467
15.4.7.6 Tasking Support when Debugging Core Files
4468
..................................................
4469
 
4470
When inspecting a core file, as opposed to debugging a live program,
4471
tasking support may be limited or even unavailable, depending on the
4472
platform being used.  For instance, on x86-linux, the list of tasks is
4473
available, but task switching is not supported.  On Tru64, however,
4474
task switching will work as usual.
4475
 
4476
   On certain platforms, including Tru64, the debugger needs to perform
4477
some memory writes in order to provide Ada tasking support.  When
4478
inspecting a core file, this means that the core file must be opened
4479
with read-write privileges, using the command `"set write on"' (*note
4480
Patching::).  Under these circumstances, you should make a backup copy
4481
of the core file before inspecting it with GDB.
4482
 
4483

4484
File: gdb.info,  Node: Ada Glitches,  Prev: Ada Tasks and Core Files,  Up: Ada
4485
 
4486
15.4.7.7 Known Peculiarities of Ada Mode
4487
........................................
4488
 
4489
Besides the omissions listed previously (*note Omissions from Ada::),
4490
we know of several problems with and limitations of Ada mode in GDB,
4491
some of which will be fixed with planned future releases of the debugger
4492
and the GNU Ada compiler.
4493
 
4494
   * Currently, the debugger has insufficient information to determine
4495
     whether certain pointers represent pointers to objects or the
4496
     objects themselves.  Thus, the user may have to tack an extra
4497
     `.all' after an expression to get it printed properly.
4498
 
4499
   * Static constants that the compiler chooses not to materialize as
4500
     objects in storage are invisible to the debugger.
4501
 
4502
   * Named parameter associations in function argument lists are
4503
     ignored (the argument lists are treated as positional).
4504
 
4505
   * Many useful library packages are currently invisible to the
4506
     debugger.
4507
 
4508
   * Fixed-point arithmetic, conversions, input, and output is carried
4509
     out using floating-point arithmetic, and may give results that
4510
     only approximate those on the host machine.
4511
 
4512
   * The GNAT compiler never generates the prefix `Standard' for any of
4513
     the standard symbols defined by the Ada language.  GDB knows about
4514
     this: it will strip the prefix from names when you use it, and
4515
     will never look for a name you have so qualified among local
4516
     symbols, nor match against symbols in other packages or
4517
     subprograms.  If you have defined entities anywhere in your
4518
     program other than parameters and local variables whose simple
4519
     names match names in `Standard', GNAT's lack of qualification here
4520
     can cause confusion.  When this happens, you can usually resolve
4521
     the confusion by qualifying the problematic names with package
4522
     `Standard' explicitly.
4523
 
4524
   Older versions of the compiler sometimes generate erroneous debugging
4525
information, resulting in the debugger incorrectly printing the value
4526
of affected entities.  In some cases, the debugger is able to work
4527
around an issue automatically. In other cases, the debugger is able to
4528
work around the issue, but the work-around has to be specifically
4529
enabled.
4530
 
4531
`set ada trust-PAD-over-XVS on'
4532
     Configure GDB to strictly follow the GNAT encoding when computing
4533
     the value of Ada entities, particularly when `PAD' and `PAD___XVS'
4534
     types are involved (see `ada/exp_dbug.ads' in the GCC sources for
4535
     a complete description of the encoding used by the GNAT compiler).
4536
     This is the default.
4537
 
4538
`set ada trust-PAD-over-XVS off'
4539
     This is related to the encoding using by the GNAT compiler.  If
4540
     GDB sometimes prints the wrong value for certain entities,
4541
     changing `ada trust-PAD-over-XVS' to `off' activates a work-around
4542
     which may fix the issue.  It is always safe to set `ada
4543
     trust-PAD-over-XVS' to `off', but this incurs a slight performance
4544
     penalty, so it is recommended to leave this setting to `on' unless
4545
     necessary.
4546
 
4547
 
4548

4549
File: gdb.info,  Node: Unsupported Languages,  Prev: Supported Languages,  Up: Languages
4550
 
4551
15.5 Unsupported Languages
4552
==========================
4553
 
4554
In addition to the other fully-supported programming languages, GDB
4555
also provides a pseudo-language, called `minimal'.  It does not
4556
represent a real programming language, but provides a set of
4557
capabilities close to what the C or assembly languages provide.  This
4558
should allow most simple operations to be performed while debugging an
4559
application that uses a language currently not supported by GDB.
4560
 
4561
   If the language is set to `auto', GDB will automatically select this
4562
language if the current frame corresponds to an unsupported language.
4563
 
4564

4565
File: gdb.info,  Node: Symbols,  Next: Altering,  Prev: Languages,  Up: Top
4566
 
4567
16 Examining the Symbol Table
4568
*****************************
4569
 
4570
The commands described in this chapter allow you to inquire about the
4571
symbols (names of variables, functions and types) defined in your
4572
program.  This information is inherent in the text of your program and
4573
does not change as your program executes.  GDB finds it in your
4574
program's symbol table, in the file indicated when you started GDB
4575
(*note Choosing Files: File Options.), or by one of the file-management
4576
commands (*note Commands to Specify Files: Files.).
4577
 
4578
   Occasionally, you may need to refer to symbols that contain unusual
4579
characters, which GDB ordinarily treats as word delimiters.  The most
4580
frequent case is in referring to static variables in other source files
4581
(*note Program Variables: Variables.).  File names are recorded in
4582
object files as debugging symbols, but GDB would ordinarily parse a
4583
typical file name, like `foo.c', as the three words `foo' `.' `c'.  To
4584
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
4585
quotes; for example,
4586
 
4587
     p 'foo.c'::x
4588
 
4589
looks up the value of `x' in the scope of the file `foo.c'.
4590
 
4591
`set case-sensitive on'
4592
`set case-sensitive off'
4593
`set case-sensitive auto'
4594
     Normally, when GDB looks up symbols, it matches their names with
4595
     case sensitivity determined by the current source language.
4596
     Occasionally, you may wish to control that.  The command `set
4597
     case-sensitive' lets you do that by specifying `on' for
4598
     case-sensitive matches or `off' for case-insensitive ones.  If you
4599
     specify `auto', case sensitivity is reset to the default suitable
4600
     for the source language.  The default is case-sensitive matches
4601
     for all languages except for Fortran, for which the default is
4602
     case-insensitive matches.
4603
 
4604
`show case-sensitive'
4605
     This command shows the current setting of case sensitivity for
4606
     symbols lookups.
4607
 
4608
`info address SYMBOL'
4609
     Describe where the data for SYMBOL is stored.  For a register
4610
     variable, this says which register it is kept in.  For a
4611
     non-register local variable, this prints the stack-frame offset at
4612
     which the variable is always stored.
4613
 
4614
     Note the contrast with `print &SYMBOL', which does not work at all
4615
     for a register variable, and for a stack local variable prints the
4616
     exact address of the current instantiation of the variable.
4617
 
4618
`info symbol ADDR'
4619
     Print the name of a symbol which is stored at the address ADDR.
4620
     If no symbol is stored exactly at ADDR, GDB prints the nearest
4621
     symbol and an offset from it:
4622
 
4623
          (gdb) info symbol 0x54320
4624
          _initialize_vx + 396 in section .text
4625
 
4626
     This is the opposite of the `info address' command.  You can use
4627
     it to find out the name of a variable or a function given its
4628
     address.
4629
 
4630
     For dynamically linked executables, the name of executable or
4631
     shared library containing the symbol is also printed:
4632
 
4633
          (gdb) info symbol 0x400225
4634
          _start + 5 in section .text of /tmp/a.out
4635
          (gdb) info symbol 0x2aaaac2811cf
4636
          __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
4637
 
4638
`whatis [ARG]'
4639
     Print the data type of ARG, which can be either an expression or a
4640
     data type.  With no argument, print the data type of `$', the last
4641
     value in the value history.  If ARG is an expression, it is not
4642
     actually evaluated, and any side-effecting operations (such as
4643
     assignments or function calls) inside it do not take place.  If
4644
     ARG is a type name, it may be the name of a type or typedef, or
4645
     for C code it may have the form `class CLASS-NAME', `struct
4646
     STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'.  *Note
4647
     Expressions: Expressions.
4648
 
4649
`ptype [ARG]'
4650
     `ptype' accepts the same arguments as `whatis', but prints a
4651
     detailed description of the type, instead of just the name of the
4652
     type.  *Note Expressions: Expressions.
4653
 
4654
     For example, for this variable declaration:
4655
 
4656
          struct complex {double real; double imag;} v;
4657
 
4658
     the two commands give this output:
4659
 
4660
          (gdb) whatis v
4661
          type = struct complex
4662
          (gdb) ptype v
4663
          type = struct complex {
4664
              double real;
4665
              double imag;
4666
          }
4667
 
4668
     As with `whatis', using `ptype' without an argument refers to the
4669
     type of `$', the last value in the value history.
4670
 
4671
     Sometimes, programs use opaque data types or incomplete
4672
     specifications of complex data structure.  If the debug
4673
     information included in the program does not allow GDB to display
4674
     a full declaration of the data type, it will say `
4675
     type>'.  For example, given these declarations:
4676
 
4677
              struct foo;
4678
              struct foo *fooptr;
4679
 
4680
     but no definition for `struct foo' itself, GDB will say:
4681
 
4682
            (gdb) ptype foo
4683
            $1 = 
4684
 
4685
     "Incomplete type" is C terminology for data types that are not
4686
     completely specified.
4687
 
4688
`info types REGEXP'
4689
`info types'
4690
     Print a brief description of all types whose names match the
4691
     regular expression REGEXP (or all types in your program, if you
4692
     supply no argument).  Each complete typename is matched as though
4693
     it were a complete line; thus, `i type value' gives information on
4694
     all types in your program whose names include the string `value',
4695
     but `i type ^value$' gives information only on types whose complete
4696
     name is `value'.
4697
 
4698
     This command differs from `ptype' in two ways: first, like
4699
     `whatis', it does not print a detailed description; second, it
4700
     lists all source files where a type is defined.
4701
 
4702
`info scope LOCATION'
4703
     List all the variables local to a particular scope.  This command
4704
     accepts a LOCATION argument--a function name, a source line, or an
4705
     address preceded by a `*', and prints all the variables local to
4706
     the scope defined by that location.  (*Note Specify Location::, for
4707
     details about supported forms of LOCATION.)  For example:
4708
 
4709
          (gdb) info scope command_line_handler
4710
          Scope for command_line_handler:
4711
          Symbol rl is an argument at stack/frame offset 8, length 4.
4712
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
4713
          Symbol linelength is in static storage at address 0x150a1c, length 4.
4714
          Symbol p is a local variable in register $esi, length 4.
4715
          Symbol p1 is a local variable in register $ebx, length 4.
4716
          Symbol nline is a local variable in register $edx, length 4.
4717
          Symbol repeat is a local variable at frame offset -8, length 4.
4718
 
4719
     This command is especially useful for determining what data to
4720 342 jeremybenn
     collect during a "trace experiment", see *note collect: Tracepoint
4721 330 jeremybenn
     Actions.
4722
 
4723
`info source'
4724
     Show information about the current source file--that is, the
4725
     source file for the function containing the current point of
4726
     execution:
4727
        * the name of the source file, and the directory containing it,
4728
 
4729
        * the directory it was compiled in,
4730
 
4731
        * its length, in lines,
4732
 
4733
        * which programming language it is written in,
4734
 
4735
        * whether the executable includes debugging information for
4736
          that file, and if so, what format the information is in
4737
          (e.g., STABS, Dwarf 2, etc.), and
4738
 
4739
        * whether the debugging information includes information about
4740
          preprocessor macros.
4741
 
4742
`info sources'
4743
     Print the names of all source files in your program for which
4744
     there is debugging information, organized into two lists: files
4745
     whose symbols have already been read, and files whose symbols will
4746
     be read when needed.
4747
 
4748
`info functions'
4749
     Print the names and data types of all defined functions.
4750
 
4751
`info functions REGEXP'
4752
     Print the names and data types of all defined functions whose
4753
     names contain a match for regular expression REGEXP.  Thus, `info
4754
     fun step' finds all functions whose names include `step'; `info
4755
     fun ^step' finds those whose names start with `step'.  If a
4756
     function name contains characters that conflict with the regular
4757
     expression language (e.g.  `operator*()'), they may be quoted with
4758
     a backslash.
4759
 
4760
`info variables'
4761
     Print the names and data types of all variables that are defined
4762
     outside of functions (i.e. excluding local variables).
4763
 
4764
`info variables REGEXP'
4765
     Print the names and data types of all variables (except for local
4766
     variables) whose names contain a match for regular expression
4767
     REGEXP.
4768
 
4769
`info classes'
4770
`info classes REGEXP'
4771
     Display all Objective-C classes in your program, or (with the
4772
     REGEXP argument) all those matching a particular regular
4773
     expression.
4774
 
4775
`info selectors'
4776
`info selectors REGEXP'
4777
     Display all Objective-C selectors in your program, or (with the
4778
     REGEXP argument) all those matching a particular regular
4779
     expression.
4780
 
4781
     Some systems allow individual object files that make up your
4782
     program to be replaced without stopping and restarting your
4783
     program.  For example, in VxWorks you can simply recompile a
4784
     defective object file and keep on running.  If you are running on
4785
     one of these systems, you can allow GDB to reload the symbols for
4786
     automatically relinked modules:
4787
 
4788
    `set symbol-reloading on'
4789
          Replace symbol definitions for the corresponding source file
4790
          when an object file with a particular name is seen again.
4791
 
4792
    `set symbol-reloading off'
4793
          Do not replace symbol definitions when encountering object
4794
          files of the same name more than once.  This is the default
4795
          state; if you are not running on a system that permits
4796
          automatic relinking of modules, you should leave
4797
          `symbol-reloading' off, since otherwise GDB may discard
4798
          symbols when linking large programs, that may contain several
4799
          modules (from different directories or libraries) with the
4800
          same name.
4801
 
4802
    `show symbol-reloading'
4803
          Show the current `on' or `off' setting.
4804
 
4805
`set opaque-type-resolution on'
4806
     Tell GDB to resolve opaque types.  An opaque type is a type
4807
     declared as a pointer to a `struct', `class', or `union'--for
4808
     example, `struct MyType *'--that is used in one source file
4809
     although the full declaration of `struct MyType' is in another
4810
     source file.  The default is on.
4811
 
4812
     A change in the setting of this subcommand will not take effect
4813
     until the next time symbols for a file are loaded.
4814
 
4815
`set opaque-type-resolution off'
4816
     Tell GDB not to resolve opaque types.  In this case, the type is
4817
     printed as follows:
4818
          {}
4819
 
4820
`show opaque-type-resolution'
4821
     Show whether opaque types are resolved or not.
4822
 
4823
`maint print symbols FILENAME'
4824
`maint print psymbols FILENAME'
4825
`maint print msymbols FILENAME'
4826
     Write a dump of debugging symbol data into the file FILENAME.
4827
     These commands are used to debug the GDB symbol-reading code.  Only
4828
     symbols with debugging data are included.  If you use `maint print
4829
     symbols', GDB includes all the symbols for which it has already
4830
     collected full details: that is, FILENAME reflects symbols for
4831
     only those files whose symbols GDB has read.  You can use the
4832
     command `info sources' to find out which files these are.  If you
4833
     use `maint print psymbols' instead, the dump shows information
4834
     about symbols that GDB only knows partially--that is, symbols
4835
     defined in files that GDB has skimmed, but not yet read
4836
     completely.  Finally, `maint print msymbols' dumps just the
4837
     minimal symbol information required for each object file from
4838
     which GDB has read some symbols.  *Note Commands to Specify Files:
4839
     Files, for a discussion of how GDB reads symbols (in the
4840
     description of `symbol-file').
4841
 
4842
`maint info symtabs [ REGEXP ]'
4843
`maint info psymtabs [ REGEXP ]'
4844
     List the `struct symtab' or `struct partial_symtab' structures
4845
     whose names match REGEXP.  If REGEXP is not given, list them all.
4846
     The output includes expressions which you can copy into a GDB
4847
     debugging this one to examine a particular structure in more
4848
     detail.  For example:
4849
 
4850
          (gdb) maint info psymtabs dwarf2read
4851
          { objfile /home/gnu/build/gdb/gdb
4852
            ((struct objfile *) 0x82e69d0)
4853
            { psymtab /home/gnu/src/gdb/dwarf2read.c
4854
              ((struct partial_symtab *) 0x8474b10)
4855
              readin no
4856
              fullname (null)
4857
              text addresses 0x814d3c8 -- 0x8158074
4858
              globals (* (struct partial_symbol **) 0x8507a08 @ 9)
4859
              statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
4860
              dependencies (none)
4861
            }
4862
          }
4863
          (gdb) maint info symtabs
4864
          (gdb)
4865
     We see that there is one partial symbol table whose filename
4866
     contains the string `dwarf2read', belonging to the `gdb'
4867
     executable; and we see that GDB has not read in any symtabs yet at
4868
     all.  If we set a breakpoint on a function, that will cause GDB to
4869
     read the symtab for the compilation unit containing that function:
4870
 
4871
          (gdb) break dwarf2_psymtab_to_symtab
4872
          Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
4873
          line 1574.
4874
          (gdb) maint info symtabs
4875
          { objfile /home/gnu/build/gdb/gdb
4876
            ((struct objfile *) 0x82e69d0)
4877
            { symtab /home/gnu/src/gdb/dwarf2read.c
4878
              ((struct symtab *) 0x86c1f38)
4879
              dirname (null)
4880
              fullname (null)
4881
              blockvector ((struct blockvector *) 0x86c1bd0) (primary)
4882
              linetable ((struct linetable *) 0x8370fa0)
4883
              debugformat DWARF 2
4884
            }
4885
          }
4886
          (gdb)
4887
 
4888

4889
File: gdb.info,  Node: Altering,  Next: GDB Files,  Prev: Symbols,  Up: Top
4890
 
4891
17 Altering Execution
4892
*********************
4893
 
4894
Once you think you have found an error in your program, you might want
4895
to find out for certain whether correcting the apparent error would
4896
lead to correct results in the rest of the run.  You can find the
4897
answer by experiment, using the GDB features for altering execution of
4898
the program.
4899
 
4900
   For example, you can store new values into variables or memory
4901
locations, give your program a signal, restart it at a different
4902
address, or even return prematurely from a function.
4903
 
4904
* Menu:
4905
 
4906
* Assignment::                  Assignment to variables
4907
* Jumping::                     Continuing at a different address
4908
* Signaling::                   Giving your program a signal
4909
* Returning::                   Returning from a function
4910
* Calling::                     Calling your program's functions
4911
* Patching::                    Patching your program
4912
 
4913

4914
File: gdb.info,  Node: Assignment,  Next: Jumping,  Up: Altering
4915
 
4916
17.1 Assignment to Variables
4917
============================
4918
 
4919
To alter the value of a variable, evaluate an assignment expression.
4920
*Note Expressions: Expressions.  For example,
4921
 
4922
     print x=4
4923
 
4924
stores the value 4 into the variable `x', and then prints the value of
4925
the assignment expression (which is 4).  *Note Using GDB with Different
4926
Languages: Languages, for more information on operators in supported
4927
languages.
4928
 
4929
   If you are not interested in seeing the value of the assignment, use
4930
the `set' command instead of the `print' command.  `set' is really the
4931
same as `print' except that the expression's value is not printed and
4932
is not put in the value history (*note Value History: Value History.).
4933
The expression is evaluated only for its effects.
4934
 
4935
   If the beginning of the argument string of the `set' command appears
4936
identical to a `set' subcommand, use the `set variable' command instead
4937
of just `set'.  This command is identical to `set' except for its lack
4938
of subcommands.  For example, if your program has a variable `width',
4939
you get an error if you try to set a new value with just `set
4940
width=13', because GDB has the command `set width':
4941
 
4942
     (gdb) whatis width
4943
     type = double
4944
     (gdb) p width
4945
     $4 = 13
4946
     (gdb) set width=47
4947
     Invalid syntax in expression.
4948
 
4949
The invalid expression, of course, is `=47'.  In order to actually set
4950
the program's variable `width', use
4951
 
4952
     (gdb) set var width=47
4953
 
4954
   Because the `set' command has many subcommands that can conflict
4955
with the names of program variables, it is a good idea to use the `set
4956
variable' command instead of just `set'.  For example, if your program
4957
has a variable `g', you run into problems if you try to set a new value
4958
with just `set g=4', because GDB has the command `set gnutarget',
4959
abbreviated `set g':
4960
 
4961
     (gdb) whatis g
4962
     type = double
4963
     (gdb) p g
4964
     $1 = 1
4965
     (gdb) set g=4
4966
     (gdb) p g
4967
     $2 = 1
4968
     (gdb) r
4969
     The program being debugged has been started already.
4970
     Start it from the beginning? (y or n) y
4971
     Starting program: /home/smith/cc_progs/a.out
4972
     "/home/smith/cc_progs/a.out": can't open to read symbols:
4973
                                      Invalid bfd target.
4974
     (gdb) show g
4975
     The current BFD target is "=4".
4976
 
4977
The program variable `g' did not change, and you silently set the
4978
`gnutarget' to an invalid value.  In order to set the variable `g', use
4979
 
4980
     (gdb) set var g=4
4981
 
4982
   GDB allows more implicit conversions in assignments than C; you can
4983
freely store an integer value into a pointer variable or vice versa,
4984
and you can convert any structure to any other structure that is the
4985
same length or shorter.
4986
 
4987
   To store values into arbitrary places in memory, use the `{...}'
4988
construct to generate a value of specified type at a specified address
4989
(*note Expressions: Expressions.).  For example, `{int}0x83040' refers
4990
to memory location `0x83040' as an integer (which implies a certain size
4991
and representation in memory), and
4992
 
4993
     set {int}0x83040 = 4
4994
 
4995
stores the value 4 into that memory location.
4996
 
4997

4998
File: gdb.info,  Node: Jumping,  Next: Signaling,  Prev: Assignment,  Up: Altering
4999
 
5000
17.2 Continuing at a Different Address
5001
======================================
5002
 
5003
Ordinarily, when you continue your program, you do so at the place where
5004
it stopped, with the `continue' command.  You can instead continue at
5005
an address of your own choosing, with the following commands:
5006
 
5007
`jump LINESPEC'
5008
`jump LOCATION'
5009
     Resume execution at line LINESPEC or at address given by LOCATION.
5010
     Execution stops again immediately if there is a breakpoint there.
5011 342 jeremybenn
     *Note Specify Location::, for a description of the different forms
5012
     of LINESPEC and LOCATION.  It is common practice to use the
5013 330 jeremybenn
     `tbreak' command in conjunction with `jump'.  *Note Setting
5014
     Breakpoints: Set Breaks.
5015
 
5016
     The `jump' command does not change the current stack frame, or the
5017
     stack pointer, or the contents of any memory location or any
5018
     register other than the program counter.  If line LINESPEC is in a
5019
     different function from the one currently executing, the results
5020
     may be bizarre if the two functions expect different patterns of
5021
     arguments or of local variables.  For this reason, the `jump'
5022
     command requests confirmation if the specified line is not in the
5023
     function currently executing.  However, even bizarre results are
5024
     predictable if you are well acquainted with the machine-language
5025
     code of your program.
5026
 
5027
   On many systems, you can get much the same effect as the `jump'
5028
command by storing a new value into the register `$pc'.  The difference
5029
is that this does not start your program running; it only changes the
5030
address of where it _will_ run when you continue.  For example,
5031
 
5032
     set $pc = 0x485
5033
 
5034
makes the next `continue' command or stepping command execute at
5035
address `0x485', rather than at the address where your program stopped.
5036
*Note Continuing and Stepping: Continuing and Stepping.
5037
 
5038
   The most common occasion to use the `jump' command is to back
5039
up--perhaps with more breakpoints set--over a portion of a program that
5040
has already executed, in order to examine its execution in more detail.
5041
 
5042

5043
File: gdb.info,  Node: Signaling,  Next: Returning,  Prev: Jumping,  Up: Altering
5044
 
5045
17.3 Giving your Program a Signal
5046
=================================
5047
 
5048
`signal SIGNAL'
5049
     Resume execution where your program stopped, but immediately give
5050
     it the signal SIGNAL.  SIGNAL can be the name or the number of a
5051
     signal.  For example, on many systems `signal 2' and `signal
5052
     SIGINT' are both ways of sending an interrupt signal.
5053
 
5054
     Alternatively, if SIGNAL is zero, continue execution without
5055
     giving a signal.  This is useful when your program stopped on
5056
     account of a signal and would ordinary see the signal when resumed
5057
     with the `continue' command; `signal 0' causes it to resume
5058
     without a signal.
5059
 
5060
     `signal' does not repeat when you press  a second time after
5061
     executing the command.
5062
 
5063
   Invoking the `signal' command is not the same as invoking the `kill'
5064
utility from the shell.  Sending a signal with `kill' causes GDB to
5065
decide what to do with the signal depending on the signal handling
5066
tables (*note Signals::).  The `signal' command passes the signal
5067
directly to your program.
5068
 
5069

5070
File: gdb.info,  Node: Returning,  Next: Calling,  Prev: Signaling,  Up: Altering
5071
 
5072
17.4 Returning from a Function
5073
==============================
5074
 
5075
`return'
5076
`return EXPRESSION'
5077
     You can cancel execution of a function call with the `return'
5078
     command.  If you give an EXPRESSION argument, its value is used as
5079
     the function's return value.
5080
 
5081
   When you use `return', GDB discards the selected stack frame (and
5082
all frames within it).  You can think of this as making the discarded
5083
frame return prematurely.  If you wish to specify a value to be
5084
returned, give that value as the argument to `return'.
5085
 
5086
   This pops the selected stack frame (*note Selecting a Frame:
5087
Selection.), and any other frames inside of it, leaving its caller as
5088
the innermost remaining frame.  That frame becomes selected.  The
5089
specified value is stored in the registers used for returning values of
5090
functions.
5091
 
5092
   The `return' command does not resume execution; it leaves the
5093
program stopped in the state that would exist if the function had just
5094
returned.  In contrast, the `finish' command (*note Continuing and
5095
Stepping: Continuing and Stepping.) resumes execution until the
5096
selected stack frame returns naturally.
5097
 
5098
   GDB needs to know how the EXPRESSION argument should be set for the
5099
inferior.  The concrete registers assignment depends on the OS ABI and
5100
the type being returned by the selected stack frame.  For example it is
5101
common for OS ABI to return floating point values in FPU registers
5102
while integer values in CPU registers.  Still some ABIs return even
5103
floating point values in CPU registers.  Larger integer widths (such as
5104
`long long int') also have specific placement rules.  GDB already knows
5105
the OS ABI from its current target so it needs to find out also the
5106
type being returned to make the assignment into the right register(s).
5107
 
5108
   Normally, the selected stack frame has debug info.  GDB will always
5109
use the debug info instead of the implicit type of EXPRESSION when the
5110
debug info is available.  For example, if you type `return -1', and the
5111
function in the current stack frame is declared to return a `long long
5112
int', GDB transparently converts the implicit `int' value of -1 into a
5113
`long long int':
5114
 
5115
     Breakpoint 1, func () at gdb.base/return-nodebug.c:29
5116
     29        return 31;
5117
     (gdb) return -1
5118
     Make func return now? (y or n) y
5119
     #0  0x004004f6 in main () at gdb.base/return-nodebug.c:43
5120
     43        printf ("result=%lld\n", func ());
5121
     (gdb)
5122
 
5123
   However, if the selected stack frame does not have a debug info,
5124
e.g., if the function was compiled without debug info, GDB has to find
5125
out the type to return from user.  Specifying a different type by
5126
mistake may set the value in different inferior registers than the
5127
caller code expects.  For example, typing `return -1' with its implicit
5128
type `int' would set only a part of a `long long int' result for a
5129
debug info less function (on 32-bit architectures).  Therefore the user
5130
is required to specify the return type by an appropriate cast
5131
explicitly:
5132
 
5133
     Breakpoint 2, 0x0040050b in func ()
5134
     (gdb) return -1
5135
     Return value type not available for selected stack frame.
5136
     Please use an explicit cast of the value to return.
5137
     (gdb) return (long long int) -1
5138
     Make selected stack frame return now? (y or n) y
5139
     #0  0x00400526 in main ()
5140
     (gdb)
5141
 
5142

5143
File: gdb.info,  Node: Calling,  Next: Patching,  Prev: Returning,  Up: Altering
5144
 
5145
17.5 Calling Program Functions
5146
==============================
5147
 
5148
`print EXPR'
5149
     Evaluate the expression EXPR and display the resulting value.
5150
     EXPR may include calls to functions in the program being debugged.
5151
 
5152
`call EXPR'
5153
     Evaluate the expression EXPR without displaying `void' returned
5154
     values.
5155
 
5156
     You can use this variant of the `print' command if you want to
5157
     execute a function from your program that does not return anything
5158
     (a.k.a. "a void function"), but without cluttering the output with
5159
     `void' returned values that GDB will otherwise print.  If the
5160
     result is not void, it is printed and saved in the value history.
5161
 
5162
   It is possible for the function you call via the `print' or `call'
5163
command to generate a signal (e.g., if there's a bug in the function,
5164
or if you passed it incorrect arguments).  What happens in that case is
5165
controlled by the `set unwindonsignal' command.
5166
 
5167
   Similarly, with a C++ program it is possible for the function you
5168
call via the `print' or `call' command to generate an exception that is
5169
not handled due to the constraints of the dummy frame.  In this case,
5170
any exception that is raised in the frame, but has an out-of-frame
5171
exception handler will not be found.  GDB builds a dummy-frame for the
5172
inferior function call, and the unwinder cannot seek for exception
5173
handlers outside of this dummy-frame.  What happens in that case is
5174
controlled by the `set unwind-on-terminating-exception' command.
5175
 
5176
`set unwindonsignal'
5177
     Set unwinding of the stack if a signal is received while in a
5178
     function that GDB called in the program being debugged.  If set to
5179
     on, GDB unwinds the stack it created for the call and restores the
5180
     context to what it was before the call.  If set to off (the
5181
     default), GDB stops in the frame where the signal was received.
5182
 
5183
`show unwindonsignal'
5184
     Show the current setting of stack unwinding in the functions
5185
     called by GDB.
5186
 
5187
`set unwind-on-terminating-exception'
5188
     Set unwinding of the stack if a C++ exception is raised, but left
5189
     unhandled while in a function that GDB called in the program being
5190
     debugged.  If set to on (the default), GDB unwinds the stack it
5191
     created for the call and restores the context to what it was before
5192
     the call.  If set to off, GDB the exception is delivered to the
5193
     default C++ exception handler and the inferior terminated.
5194
 
5195
`show unwind-on-terminating-exception'
5196
     Show the current setting of stack unwinding in the functions
5197
     called by GDB.
5198
 
5199
 
5200
   Sometimes, a function you wish to call is actually a "weak alias"
5201
for another function.  In such case, GDB might not pick up the type
5202
information, including the types of the function arguments, which
5203
causes GDB to call the inferior function incorrectly.  As a result, the
5204
called function will function erroneously and may even crash.  A
5205
solution to that is to use the name of the aliased function instead.
5206
 
5207

5208
File: gdb.info,  Node: Patching,  Prev: Calling,  Up: Altering
5209
 
5210
17.6 Patching Programs
5211
======================
5212
 
5213
By default, GDB opens the file containing your program's executable
5214
code (or the corefile) read-only.  This prevents accidental alterations
5215
to machine code; but it also prevents you from intentionally patching
5216
your program's binary.
5217
 
5218
   If you'd like to be able to patch the binary, you can specify that
5219
explicitly with the `set write' command.  For example, you might want
5220
to turn on internal debugging flags, or even to make emergency repairs.
5221
 
5222
`set write on'
5223
`set write off'
5224
     If you specify `set write on', GDB opens executable and core files
5225
     for both reading and writing; if you specify `set write off' (the
5226
     default), GDB opens them read-only.
5227
 
5228
     If you have already loaded a file, you must load it again (using
5229
     the `exec-file' or `core-file' command) after changing `set
5230
     write', for your new setting to take effect.
5231
 
5232
`show write'
5233
     Display whether executable files and core files are opened for
5234
     writing as well as reading.
5235
 
5236

5237
File: gdb.info,  Node: GDB Files,  Next: Targets,  Prev: Altering,  Up: Top
5238
 
5239
18 GDB Files
5240
************
5241
 
5242
GDB needs to know the file name of the program to be debugged, both in
5243
order to read its symbol table and in order to start your program.  To
5244
debug a core dump of a previous run, you must also tell GDB the name of
5245
the core dump file.
5246
 
5247
* Menu:
5248
 
5249
* Files::                       Commands to specify files
5250
* Separate Debug Files::        Debugging information in separate files
5251
* Symbol Errors::               Errors reading symbol files
5252
* Data Files::                  GDB data files
5253
 
5254

5255
File: gdb.info,  Node: Files,  Next: Separate Debug Files,  Up: GDB Files
5256
 
5257
18.1 Commands to Specify Files
5258
==============================
5259
 
5260
You may want to specify executable and core dump file names.  The usual
5261
way to do this is at start-up time, using the arguments to GDB's
5262
start-up commands (*note Getting In and Out of GDB: Invocation.).
5263
 
5264
   Occasionally it is necessary to change to a different file during a
5265
GDB session.  Or you may run GDB and forget to specify a file you want
5266
to use.  Or you are debugging a remote target via `gdbserver' (*note
5267
file: Server.).  In these situations the GDB commands to specify new
5268
files are useful.
5269
 
5270
`file FILENAME'
5271
     Use FILENAME as the program to be debugged.  It is read for its
5272
     symbols and for the contents of pure memory.  It is also the
5273
     program executed when you use the `run' command.  If you do not
5274
     specify a directory and the file is not found in the GDB working
5275
     directory, GDB uses the environment variable `PATH' as a list of
5276
     directories to search, just as the shell does when looking for a
5277
     program to run.  You can change the value of this variable, for
5278
     both GDB and your program, using the `path' command.
5279
 
5280
     You can load unlinked object `.o' files into GDB using the `file'
5281
     command.  You will not be able to "run" an object file, but you
5282
     can disassemble functions and inspect variables.  Also, if the
5283
     underlying BFD functionality supports it, you could use `gdb
5284
     -write' to patch object files using this technique.  Note that GDB
5285
     can neither interpret nor modify relocations in this case, so
5286
     branches and some initialized variables will appear to go to the
5287
     wrong place.  But this feature is still handy from time to time.
5288
 
5289
`file'
5290
     `file' with no argument makes GDB discard any information it has
5291
     on both executable file and the symbol table.
5292
 
5293
`exec-file [ FILENAME ]'
5294
     Specify that the program to be run (but not the symbol table) is
5295
     found in FILENAME.  GDB searches the environment variable `PATH'
5296
     if necessary to locate your program.  Omitting FILENAME means to
5297
     discard information on the executable file.
5298
 
5299
`symbol-file [ FILENAME ]'
5300
     Read symbol table information from file FILENAME.  `PATH' is
5301
     searched when necessary.  Use the `file' command to get both symbol
5302
     table and program to run from the same file.
5303
 
5304
     `symbol-file' with no argument clears out GDB information on your
5305
     program's symbol table.
5306
 
5307
     The `symbol-file' command causes GDB to forget the contents of
5308
     some breakpoints and auto-display expressions.  This is because
5309
     they may contain pointers to the internal data recording symbols
5310
     and data types, which are part of the old symbol table data being
5311
     discarded inside GDB.
5312
 
5313
     `symbol-file' does not repeat if you press  again after
5314
     executing it once.
5315
 
5316
     When GDB is configured for a particular environment, it
5317
     understands debugging information in whatever format is the
5318
     standard generated for that environment; you may use either a GNU
5319
     compiler, or other compilers that adhere to the local conventions.
5320
     Best results are usually obtained from GNU compilers; for example,
5321
     using `GCC' you can generate debugging information for optimized
5322
     code.
5323
 
5324
     For most kinds of object files, with the exception of old SVR3
5325
     systems using COFF, the `symbol-file' command does not normally
5326
     read the symbol table in full right away.  Instead, it scans the
5327
     symbol table quickly to find which source files and which symbols
5328
     are present.  The details are read later, one source file at a
5329
     time, as they are needed.
5330
 
5331
     The purpose of this two-stage reading strategy is to make GDB
5332
     start up faster.  For the most part, it is invisible except for
5333
     occasional pauses while the symbol table details for a particular
5334
     source file are being read.  (The `set verbose' command can turn
5335
     these pauses into messages if desired.  *Note Optional Warnings
5336
     and Messages: Messages/Warnings.)
5337
 
5338
     We have not implemented the two-stage strategy for COFF yet.  When
5339
     the symbol table is stored in COFF format, `symbol-file' reads the
5340
     symbol table data in full right away.  Note that "stabs-in-COFF"
5341
     still does the two-stage strategy, since the debug info is actually
5342
     in stabs format.
5343
 
5344
`symbol-file [ -readnow ] FILENAME'
5345
`file [ -readnow ] FILENAME'
5346
     You can override the GDB two-stage strategy for reading symbol
5347
     tables by using the `-readnow' option with any of the commands that
5348
     load symbol table information, if you want to be sure GDB has the
5349
     entire symbol table available.
5350
 
5351
`core-file [FILENAME]'
5352
`core'
5353
     Specify the whereabouts of a core dump file to be used as the
5354
     "contents of memory".  Traditionally, core files contain only some
5355
     parts of the address space of the process that generated them; GDB
5356
     can access the executable file itself for other parts.
5357
 
5358
     `core-file' with no argument specifies that no core file is to be
5359
     used.
5360
 
5361
     Note that the core file is ignored when your program is actually
5362
     running under GDB.  So, if you have been running your program and
5363
     you wish to debug a core file instead, you must kill the
5364
     subprocess in which the program is running.  To do this, use the
5365
     `kill' command (*note Killing the Child Process: Kill Process.).
5366
 
5367
`add-symbol-file FILENAME ADDRESS'
5368
`add-symbol-file FILENAME ADDRESS [ -readnow ]'
5369
`add-symbol-file FILENAME -sSECTION ADDRESS ...'
5370
     The `add-symbol-file' command reads additional symbol table
5371
     information from the file FILENAME.  You would use this command
5372
     when FILENAME has been dynamically loaded (by some other means)
5373
     into the program that is running.  ADDRESS should be the memory
5374
     address at which the file has been loaded; GDB cannot figure this
5375
     out for itself.  You can additionally specify an arbitrary number
5376
     of `-sSECTION ADDRESS' pairs, to give an explicit section name and
5377
     base address for that section.  You can specify any ADDRESS as an
5378
     expression.
5379
 
5380
     The symbol table of the file FILENAME is added to the symbol table
5381
     originally read with the `symbol-file' command.  You can use the
5382
     `add-symbol-file' command any number of times; the new symbol data
5383
     thus read keeps adding to the old.  To discard all old symbol data
5384
     instead, use the `symbol-file' command without any arguments.
5385
 
5386
     Although FILENAME is typically a shared library file, an
5387
     executable file, or some other object file which has been fully
5388
     relocated for loading into a process, you can also load symbolic
5389
     information from relocatable `.o' files, as long as:
5390
 
5391
        * the file's symbolic information refers only to linker symbols
5392
          defined in that file, not to symbols defined by other object
5393
          files,
5394
 
5395
        * every section the file's symbolic information refers to has
5396
          actually been loaded into the inferior, as it appears in the
5397
          file, and
5398
 
5399
        * you can determine the address at which every section was
5400
          loaded, and provide these to the `add-symbol-file' command.
5401
 
5402
     Some embedded operating systems, like Sun Chorus and VxWorks, can
5403
     load relocatable files into an already running program; such
5404
     systems typically make the requirements above easy to meet.
5405
     However, it's important to recognize that many native systems use
5406
     complex link procedures (`.linkonce' section factoring and C++
5407
     constructor table assembly, for example) that make the
5408
     requirements difficult to meet.  In general, one cannot assume
5409
     that using `add-symbol-file' to read a relocatable object file's
5410
     symbolic information will have the same effect as linking the
5411
     relocatable object file into the program in the normal way.
5412
 
5413
     `add-symbol-file' does not repeat if you press  after using
5414
     it.
5415
 
5416
`add-symbol-file-from-memory ADDRESS'
5417
     Load symbols from the given ADDRESS in a dynamically loaded object
5418
     file whose image is mapped directly into the inferior's memory.
5419
     For example, the Linux kernel maps a `syscall DSO' into each
5420
     process's address space; this DSO provides kernel-specific code for
5421
     some system calls.  The argument can be any expression whose
5422
     evaluation yields the address of the file's shared object file
5423
     header.  For this command to work, you must have used
5424
     `symbol-file' or `exec-file' commands in advance.
5425
 
5426
`add-shared-symbol-files LIBRARY-FILE'
5427
`assf LIBRARY-FILE'
5428
     The `add-shared-symbol-files' command can currently be used only
5429
     in the Cygwin build of GDB on MS-Windows OS, where it is an alias
5430
     for the `dll-symbols' command (*note Cygwin Native::).  GDB
5431
     automatically looks for shared libraries, however if GDB does not
5432
     find yours, you can invoke `add-shared-symbol-files'.  It takes
5433
     one argument: the shared library's file name.  `assf' is a
5434
     shorthand alias for `add-shared-symbol-files'.
5435
 
5436
`section SECTION ADDR'
5437
     The `section' command changes the base address of the named
5438
     SECTION of the exec file to ADDR.  This can be used if the exec
5439
     file does not contain section addresses, (such as in the `a.out'
5440
     format), or when the addresses specified in the file itself are
5441
     wrong.  Each section must be changed separately.  The `info files'
5442
     command, described below, lists all the sections and their
5443
     addresses.
5444
 
5445
`info files'
5446
`info target'
5447
     `info files' and `info target' are synonymous; both print the
5448
     current target (*note Specifying a Debugging Target: Targets.),
5449
     including the names of the executable and core dump files
5450
     currently in use by GDB, and the files from which symbols were
5451
     loaded.  The command `help target' lists all possible targets
5452
     rather than current ones.
5453
 
5454
`maint info sections'
5455
     Another command that can give you extra information about program
5456
     sections is `maint info sections'.  In addition to the section
5457
     information displayed by `info files', this command displays the
5458
     flags and file offset of each section in the executable and core
5459
     dump files.  In addition, `maint info sections' provides the
5460
     following command options (which may be arbitrarily combined):
5461
 
5462
    `ALLOBJ'
5463
          Display sections for all loaded object files, including
5464
          shared libraries.
5465
 
5466
    `SECTIONS'
5467
          Display info only for named SECTIONS.
5468
 
5469
    `SECTION-FLAGS'
5470
          Display info only for sections for which SECTION-FLAGS are
5471
          true.  The section flags that GDB currently knows about are:
5472
         `ALLOC'
5473
               Section will have space allocated in the process when
5474
               loaded.  Set for all sections except those containing
5475
               debug information.
5476
 
5477
         `LOAD'
5478
               Section will be loaded from the file into the child
5479
               process memory.  Set for pre-initialized code and data,
5480
               clear for `.bss' sections.
5481
 
5482
         `RELOC'
5483
               Section needs to be relocated before loading.
5484
 
5485
         `READONLY'
5486
               Section cannot be modified by the child process.
5487
 
5488
         `CODE'
5489
               Section contains executable code only.
5490
 
5491
         `DATA'
5492
               Section contains data only (no executable code).
5493
 
5494
         `ROM'
5495
               Section will reside in ROM.
5496
 
5497
         `CONSTRUCTOR'
5498
               Section contains data for constructor/destructor lists.
5499
 
5500
         `HAS_CONTENTS'
5501
               Section is not empty.
5502
 
5503
         `NEVER_LOAD'
5504
               An instruction to the linker to not output the section.
5505
 
5506
         `COFF_SHARED_LIBRARY'
5507
               A notification to the linker that the section contains
5508
               COFF shared library information.
5509
 
5510
         `IS_COMMON'
5511
               Section contains common symbols.
5512
 
5513
`set trust-readonly-sections on'
5514
     Tell GDB that readonly sections in your object file really are
5515
     read-only (i.e. that their contents will not change).  In that
5516
     case, GDB can fetch values from these sections out of the object
5517
     file, rather than from the target program.  For some targets
5518
     (notably embedded ones), this can be a significant enhancement to
5519
     debugging performance.
5520
 
5521
     The default is off.
5522
 
5523
`set trust-readonly-sections off'
5524
     Tell GDB not to trust readonly sections.  This means that the
5525
     contents of the section might change while the program is running,
5526
     and must therefore be fetched from the target when needed.
5527
 
5528
`show trust-readonly-sections'
5529
     Show the current setting of trusting readonly sections.
5530
 
5531
   All file-specifying commands allow both absolute and relative file
5532
names as arguments.  GDB always converts the file name to an absolute
5533
file name and remembers it that way.
5534
 
5535
   GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and
5536
IBM RS/6000 AIX shared libraries.
5537
 
5538
   On MS-Windows GDB must be linked with the Expat library to support
5539
shared libraries.  *Note Expat::.
5540
 
5541
   GDB automatically loads symbol definitions from shared libraries
5542
when you use the `run' command, or when you examine a core file.
5543
(Before you issue the `run' command, GDB does not understand references
5544
to a function in a shared library, however--unless you are debugging a
5545
core file).
5546
 
5547
   On HP-UX, if the program loads a library explicitly, GDB
5548
automatically loads the symbols at the time of the `shl_load' call.
5549
 
5550
   There are times, however, when you may wish to not automatically load
5551
symbol definitions from shared libraries, such as when they are
5552
particularly large or there are many of them.
5553
 
5554
   To control the automatic loading of shared library symbols, use the
5555
commands:
5556
 
5557
`set auto-solib-add MODE'
5558
     If MODE is `on', symbols from all shared object libraries will be
5559
     loaded automatically when the inferior begins execution, you
5560
     attach to an independently started inferior, or when the dynamic
5561
     linker informs GDB that a new library has been loaded.  If MODE is
5562
     `off', symbols must be loaded manually, using the `sharedlibrary'
5563
     command.  The default value is `on'.
5564
 
5565
     If your program uses lots of shared libraries with debug info that
5566
     takes large amounts of memory, you can decrease the GDB memory
5567
     footprint by preventing it from automatically loading the symbols
5568
     from shared libraries.  To that end, type `set auto-solib-add off'
5569
     before running the inferior, then load each library whose debug
5570
     symbols you do need with `sharedlibrary REGEXP', where REGEXP is a
5571
     regular expression that matches the libraries whose symbols you
5572
     want to be loaded.
5573
 
5574
`show auto-solib-add'
5575
     Display the current autoloading mode.
5576
 
5577
   To explicitly load shared library symbols, use the `sharedlibrary'
5578
command:
5579
 
5580
`info share REGEX'
5581
`info sharedlibrary REGEX'
5582
     Print the names of the shared libraries which are currently loaded
5583
     that match REGEX.  If REGEX is omitted then print all shared
5584
     libraries that are loaded.
5585
 
5586
`sharedlibrary REGEX'
5587
`share REGEX'
5588
     Load shared object library symbols for files matching a Unix
5589
     regular expression.  As with files loaded automatically, it only
5590
     loads shared libraries required by your program for a core file or
5591
     after typing `run'.  If REGEX is omitted all shared libraries
5592
     required by your program are loaded.
5593
 
5594
`nosharedlibrary'
5595
     Unload all shared object library symbols.  This discards all
5596
     symbols that have been loaded from all shared libraries.  Symbols
5597
     from shared libraries that were loaded by explicit user requests
5598
     are not discarded.
5599
 
5600
   Sometimes you may wish that GDB stops and gives you control when any
5601
of shared library events happen.  Use the `set stop-on-solib-events'
5602
command for this:
5603
 
5604
`set stop-on-solib-events'
5605
     This command controls whether GDB should give you control when the
5606
     dynamic linker notifies it about some shared library event.  The
5607
     most common event of interest is loading or unloading of a new
5608
     shared library.
5609
 
5610
`show stop-on-solib-events'
5611
     Show whether GDB stops and gives you control when shared library
5612
     events happen.
5613
 
5614
   Shared libraries are also supported in many cross or remote debugging
5615
configurations.  GDB needs to have access to the target's libraries;
5616
this can be accomplished either by providing copies of the libraries on
5617
the host system, or by asking GDB to automatically retrieve the
5618
libraries from the target.  If copies of the target libraries are
5619
provided, they need to be the same as the target libraries, although the
5620
copies on the target can be stripped as long as the copies on the host
5621
are not.
5622
 
5623
   For remote debugging, you need to tell GDB where the target
5624
libraries are, so that it can load the correct copies--otherwise, it
5625
may try to load the host's libraries.  GDB has two variables to specify
5626
the search directories for target libraries.
5627
 
5628
`set sysroot PATH'
5629
     Use PATH as the system root for the program being debugged.  Any
5630
     absolute shared library paths will be prefixed with PATH; many
5631
     runtime loaders store the absolute paths to the shared library in
5632
     the target program's memory.  If you use `set sysroot' to find
5633
     shared libraries, they need to be laid out in the same way that
5634
     they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy
5635
     under PATH.
5636
 
5637
     If PATH starts with the sequence `remote:', GDB will retrieve the
5638
     target libraries from the remote system.  This is only supported
5639
     when using a remote target that supports the `remote get' command
5640
     (*note Sending files to a remote system: File Transfer.).  The
5641
     part of PATH following the initial `remote:' (if present) is used
5642
     as system root prefix on the remote file system.  (1)
5643
 
5644
     For targets with an MS-DOS based filesystem, such as MS-Windows and
5645
     SymbianOS, GDB tries prefixing a few variants of the target
5646
     absolute file name with PATH.  But first, on Unix hosts, GDB
5647
     converts all backslash directory separators into forward slashes,
5648
     because the backslash is not a directory separator on Unix:
5649
 
5650
            c:\foo\bar.dll => c:/foo/bar.dll
5651
 
5652
     Then, GDB attempts prefixing the target file name with PATH, and
5653
     looks for the resulting file name in the host file system:
5654
 
5655
            c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll
5656
 
5657
     If that does not find the shared library, GDB tries removing the
5658
     `:' character from the drive spec, both for convenience, and, for
5659
     the case of the host file system not supporting file names with
5660
     colons:
5661
 
5662
            c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll
5663
 
5664
     This makes it possible to have a system root that mirrors a target
5665
     with more than one drive.  E.g., you may want to setup your local
5666
     copies of the target system shared libraries like so (note `c' vs
5667
     `z'):
5668
 
5669
           `/path/to/sysroot/c/sys/bin/foo.dll'
5670
           `/path/to/sysroot/c/sys/bin/bar.dll'
5671
           `/path/to/sysroot/z/sys/bin/bar.dll'
5672
 
5673
     and point the system root at `/path/to/sysroot', so that GDB can
5674
     find the correct copies of both `c:\sys\bin\foo.dll', and
5675
     `z:\sys\bin\bar.dll'.
5676
 
5677
     If that still does not find the shared library, GDB tries removing
5678
     the whole drive spec from the target file name:
5679
 
5680
            c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll
5681
 
5682
     This last lookup makes it possible to not care about the drive
5683
     name, if you don't want or need to.
5684
 
5685
     The `set solib-absolute-prefix' command is an alias for `set
5686
     sysroot'.
5687
 
5688
     You can set the default system root by using the configure-time
5689
     `--with-sysroot' option.  If the system root is inside GDB's
5690
     configured binary prefix (set with `--prefix' or `--exec-prefix'),
5691
     then the default system root will be updated automatically if the
5692
     installed GDB is moved to a new location.
5693
 
5694
`show sysroot'
5695
     Display the current shared library prefix.
5696
 
5697
`set solib-search-path PATH'
5698
     If this variable is set, PATH is a colon-separated list of
5699
     directories to search for shared libraries.  `solib-search-path'
5700
     is used after `sysroot' fails to locate the library, or if the
5701
     path to the library is relative instead of absolute.  If you want
5702
     to use `solib-search-path' instead of `sysroot', be sure to set
5703
     `sysroot' to a nonexistent directory to prevent GDB from finding
5704
     your host's libraries.  `sysroot' is preferred; setting it to a
5705
     nonexistent directory may interfere with automatic loading of
5706
     shared library symbols.
5707
 
5708
`show solib-search-path'
5709
     Display the current shared library search path.
5710
 
5711
`set target-file-system-kind KIND'
5712
     Set assumed file system kind for target reported file names.
5713
 
5714
     Shared library file names as reported by the target system may not
5715
     make sense as is on the system GDB is running on.  For example,
5716
     when remote debugging a target that has MS-DOS based file system
5717
     semantics, from a Unix host, the target may be reporting to GDB a
5718
     list of loaded shared libraries with file names such as
5719
     `c:\Windows\kernel32.dll'.  On Unix hosts, there's no concept of
5720
     drive letters, so the `c:\' prefix is not normally understood as
5721
     indicating an absolute file name, and neither is the backslash
5722
     normally considered a directory separator character.  In that case,
5723
     the native file system would interpret this whole absolute file
5724
     name as a relative file name with no directory components.  This
5725
     would make it impossible to point GDB at a copy of the remote
5726
     target's shared libraries on the host using `set sysroot', and
5727
     impractical with `set solib-search-path'.  Setting
5728
     `target-file-system-kind' to `dos-based' tells GDB to interpret
5729
     such file names similarly to how the target would, and to map them
5730
     to file names valid on GDB's native file system semantics.  The
5731
     value of KIND can be `"auto"', in addition to one of the supported
5732
     file system kinds.  In that case, GDB tries to determine the
5733
     appropriate file system variant based on the current target's
5734
     operating system (*note Configuring the Current ABI: ABI.).  The
5735
     supported file system settings are:
5736
 
5737
    `unix'
5738
          Instruct GDB to assume the target file system is of Unix
5739
          kind.  Only file names starting the forward slash (`/')
5740
          character are considered absolute, and the directory
5741
          separator character is also the forward slash.
5742
 
5743
    `dos-based'
5744
          Instruct GDB to assume the target file system is DOS based.
5745
          File names starting with either a forward slash, or a drive
5746
          letter followed by a colon (e.g., `c:'), are considered
5747
          absolute, and both the slash (`/') and the backslash (`\\')
5748
          characters are considered directory separators.
5749
 
5750
    `auto'
5751
          Instruct GDB to use the file system kind associated with the
5752
          target operating system (*note Configuring the Current ABI:
5753
          ABI.).  This is the default.
5754
 
5755
   ---------- Footnotes ----------
5756
 
5757
   (1) If you want to specify a local system root using a directory
5758
that happens to be named `remote:', you need to use some equivalent
5759
variant of the name like `./remote:'.
5760
 
5761

5762
File: gdb.info,  Node: Separate Debug Files,  Next: Symbol Errors,  Prev: Files,  Up: GDB Files
5763
 
5764
18.2 Debugging Information in Separate Files
5765
============================================
5766
 
5767
GDB allows you to put a program's debugging information in a file
5768
separate from the executable itself, in a way that allows GDB to find
5769
and load the debugging information automatically.  Since debugging
5770
information can be very large--sometimes larger than the executable
5771
code itself--some systems distribute debugging information for their
5772
executables in separate files, which users can install only when they
5773
need to debug a problem.
5774
 
5775
   GDB supports two ways of specifying the separate debug info file:
5776
 
5777
   * The executable contains a "debug link" that specifies the name of
5778
     the separate debug info file.  The separate debug file's name is
5779
     usually `EXECUTABLE.debug', where EXECUTABLE is the name of the
5780
     corresponding executable file without leading directories (e.g.,
5781
     `ls.debug' for `/usr/bin/ls').  In addition, the debug link
5782
     specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for
5783
     the debug file, which GDB uses to validate that the executable and
5784
     the debug file came from the same build.
5785
 
5786
   * The executable contains a "build ID", a unique bit string that is
5787
     also present in the corresponding debug info file.  (This is
5788
     supported only on some operating systems, notably those which use
5789
     the ELF format for binary files and the GNU Binutils.)  For more
5790
     details about this feature, see the description of the `--build-id'
5791 342 jeremybenn
     command-line option in *note Command Line Options:
5792 330 jeremybenn
     (ld.info)Options.  The debug info file's name is not specified
5793
     explicitly by the build ID, but can be computed from the build ID,
5794
     see below.
5795
 
5796
   Depending on the way the debug info file is specified, GDB uses two
5797
different methods of looking for the debug file:
5798
 
5799
   * For the "debug link" method, GDB looks up the named file in the
5800
     directory of the executable file, then in a subdirectory of that
5801
     directory named `.debug', and finally under the global debug
5802
     directory, in a subdirectory whose name is identical to the leading
5803
     directories of the executable's absolute file name.
5804
 
5805
   * For the "build ID" method, GDB looks in the `.build-id'
5806
     subdirectory of the global debug directory for a file named
5807
     `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of
5808
     the build ID bit string, and NNNNNNNN are the rest of the bit
5809
     string.  (Real build ID strings are 32 or more hex characters, not
5810
     10.)
5811
 
5812
   So, for example, suppose you ask GDB to debug `/usr/bin/ls', which
5813
has a debug link that specifies the file `ls.debug', and a build ID
5814
whose value in hex is `abcdef1234'.  If the global debug directory is
5815
`/usr/lib/debug', then GDB will look for the following debug
5816
information files, in the indicated order:
5817
 
5818
   - `/usr/lib/debug/.build-id/ab/cdef1234.debug'
5819
 
5820
   - `/usr/bin/ls.debug'
5821
 
5822
   - `/usr/bin/.debug/ls.debug'
5823
 
5824
   - `/usr/lib/debug/usr/bin/ls.debug'.
5825
 
5826
   You can set the global debugging info directory's name, and view the
5827
name GDB is currently using.
5828
 
5829
`set debug-file-directory DIRECTORIES'
5830
     Set the directories which GDB searches for separate debugging
5831
     information files to DIRECTORY.  Multiple directory components can
5832
     be set concatenating them by a directory separator.
5833
 
5834
`show debug-file-directory'
5835
     Show the directories GDB searches for separate debugging
5836
     information files.
5837
 
5838
 
5839
   A debug link is a special section of the executable file named
5840
`.gnu_debuglink'.  The section must contain:
5841
 
5842
   * A filename, with any leading directory components removed,
5843
     followed by a zero byte,
5844
 
5845
   * zero to three bytes of padding, as needed to reach the next
5846
     four-byte boundary within the section, and
5847
 
5848
   * a four-byte CRC checksum, stored in the same endianness used for
5849
     the executable file itself.  The checksum is computed on the
5850
     debugging information file's full contents by the function given
5851
     below, passing zero as the CRC argument.
5852
 
5853
   Any executable file format can carry a debug link, as long as it can
5854
contain a section named `.gnu_debuglink' with the contents described
5855
above.
5856
 
5857
   The build ID is a special section in the executable file (and in
5858
other ELF binary files that GDB may consider).  This section is often
5859
named `.note.gnu.build-id', but that name is not mandatory.  It
5860
contains unique identification for the built files--the ID remains the
5861
same across multiple builds of the same build tree.  The default
5862
algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
5863
content for the build ID string.  The same section with an identical
5864
value is present in the original built binary with symbols, in its
5865
stripped variant, and in the separate debugging information file.
5866
 
5867
   The debugging information file itself should be an ordinary
5868
executable, containing a full set of linker symbols, sections, and
5869
debugging information.  The sections of the debugging information file
5870
should have the same names, addresses, and sizes as the original file,
5871
but they need not contain any data--much like a `.bss' section in an
5872
ordinary executable.
5873
 
5874
   The GNU binary utilities (Binutils) package includes the `objcopy'
5875
utility that can produce the separated executable / debugging
5876
information file pairs using the following commands:
5877
 
5878
     objcopy --only-keep-debug foo foo.debug
5879
     strip -g foo
5880
 
5881
These commands remove the debugging information from the executable
5882
file `foo' and place it in the file `foo.debug'.  You can use the
5883
first, second or both methods to link the two files:
5884
 
5885
   * The debug link method needs the following additional command to
5886
     also leave behind a debug link in `foo':
5887
 
5888
          objcopy --add-gnu-debuglink=foo.debug foo
5889
 
5890
     Ulrich Drepper's `elfutils' package, starting with version 0.53,
5891
     contains a version of the `strip' command such that the command
5892
     `strip foo -f foo.debug' has the same functionality as the two
5893
     `objcopy' commands and the `ln -s' command above, together.
5894
 
5895
   * Build ID gets embedded into the main executable using `ld
5896
     --build-id' or the GCC counterpart `gcc -Wl,--build-id'.  Build ID
5897
     support plus compatibility fixes for debug files separation are
5898
     present in GNU binary utilities (Binutils) package since version
5899
     2.18.
5900
 
5901
The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3
5902
using the polynomial:
5903
 
5904
      x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11
5905
      + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
5906
 
5907
   The function is computed byte at a time, taking the least
5908
significant bit of each byte first.  The initial pattern `0xffffffff'
5909
is used, to ensure leading zeros affect the CRC and the final result is
5910
inverted to ensure trailing zeros also affect the CRC.
5911
 
5912
   _Note:_ This is the same CRC polynomial as used in handling the
5913
"Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial
5914
Protocol: Remote Protocol.).  However in the case of the Remote Serial
5915
Protocol, the CRC is computed _most_ significant bit first, and the
5916
result is not inverted, so trailing zeros have no effect on the CRC
5917
value.
5918
 
5919
   To complete the description, we show below the code of the function
5920
which produces the CRC used in `.gnu_debuglink'.  Inverting the
5921
initially supplied `crc' argument means that an initial call to this
5922
function passing in zero will start computing the CRC using
5923
`0xffffffff'.
5924
 
5925
     unsigned long
5926
     gnu_debuglink_crc32 (unsigned long crc,
5927
                          unsigned char *buf, size_t len)
5928
     {
5929
       static const unsigned long crc32_table[256] =
5930
         {
5931
           0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
5932
           0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
5933
           0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
5934
           0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
5935
           0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
5936
           0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
5937
           0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
5938
           0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
5939
           0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
5940
           0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
5941
           0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
5942
           0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
5943
           0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
5944
           0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
5945
           0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
5946
           0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
5947
           0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
5948
           0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
5949
           0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
5950
           0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
5951
           0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
5952
           0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
5953
           0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
5954
           0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
5955
           0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
5956
           0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
5957
           0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
5958
           0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
5959
           0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
5960
           0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
5961
           0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
5962
           0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
5963
           0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
5964
           0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
5965
           0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
5966
           0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
5967
           0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
5968
           0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
5969
           0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
5970
           0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
5971
           0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
5972
           0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
5973
           0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
5974
           0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
5975
           0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
5976
           0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
5977
           0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
5978
           0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
5979
           0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
5980
           0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
5981
           0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
5982
           0x2d02ef8d
5983
         };
5984
       unsigned char *end;
5985
 
5986
       crc = ~crc & 0xffffffff;
5987
       for (end = buf + len; buf < end; ++buf)
5988
         crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
5989
       return ~crc & 0xffffffff;
5990
     }
5991
 
5992
This computation does not apply to the "build ID" method.
5993
 
5994

5995
File: gdb.info,  Node: Symbol Errors,  Next: Data Files,  Prev: Separate Debug Files,  Up: GDB Files
5996
 
5997
18.3 Errors Reading Symbol Files
5998
================================
5999
 
6000
While reading a symbol file, GDB occasionally encounters problems, such
6001
as symbol types it does not recognize, or known bugs in compiler
6002
output.  By default, GDB does not notify you of such problems, since
6003
they are relatively common and primarily of interest to people
6004
debugging compilers.  If you are interested in seeing information about
6005
ill-constructed symbol tables, you can either ask GDB to print only one
6006
message about each such type of problem, no matter how many times the
6007
problem occurs; or you can ask GDB to print more messages, to see how
6008
many times the problems occur, with the `set complaints' command (*note
6009
Optional Warnings and Messages: Messages/Warnings.).
6010
 
6011
   The messages currently printed, and their meanings, include:
6012
 
6013
`inner block not inside outer block in SYMBOL'
6014
     The symbol information shows where symbol scopes begin and end
6015
     (such as at the start of a function or a block of statements).
6016
     This error indicates that an inner scope block is not fully
6017
     contained in its outer scope blocks.
6018
 
6019
     GDB circumvents the problem by treating the inner block as if it
6020
     had the same scope as the outer block.  In the error message,
6021
     SYMBOL may be shown as "`(don't know)'" if the outer block is not a
6022
     function.
6023
 
6024
`block at ADDRESS out of order'
6025
     The symbol information for symbol scope blocks should occur in
6026
     order of increasing addresses.  This error indicates that it does
6027
     not do so.
6028
 
6029
     GDB does not circumvent this problem, and has trouble locating
6030
     symbols in the source file whose symbols it is reading.  (You can
6031
     often determine what source file is affected by specifying `set
6032
     verbose on'.  *Note Optional Warnings and Messages:
6033
     Messages/Warnings.)
6034
 
6035
`bad block start address patched'
6036
     The symbol information for a symbol scope block has a start address
6037
     smaller than the address of the preceding source line.  This is
6038
     known to occur in the SunOS 4.1.1 (and earlier) C compiler.
6039
 
6040
     GDB circumvents the problem by treating the symbol scope block as
6041
     starting on the previous source line.
6042
 
6043
`bad string table offset in symbol N'
6044
     Symbol number N contains a pointer into the string table which is
6045
     larger than the size of the string table.
6046
 
6047
     GDB circumvents the problem by considering the symbol to have the
6048
     name `foo', which may cause other problems if many symbols end up
6049
     with this name.
6050
 
6051
`unknown symbol type `0xNN''
6052
     The symbol information contains new data types that GDB does not
6053
     yet know how to read.  `0xNN' is the symbol type of the
6054
     uncomprehended information, in hexadecimal.
6055
 
6056
     GDB circumvents the error by ignoring this symbol information.
6057
     This usually allows you to debug your program, though certain
6058
     symbols are not accessible.  If you encounter such a problem and
6059
     feel like debugging it, you can debug `gdb' with itself, breakpoint
6060
     on `complain', then go up to the function `read_dbx_symtab' and
6061
     examine `*bufp' to see the symbol.
6062
 
6063
`stub type has NULL name'
6064
     GDB could not find the full definition for a struct or class.
6065
 
6066
`const/volatile indicator missing (ok if using g++ v1.x), got...'
6067
     The symbol information for a C++ member function is missing some
6068
     information that recent versions of the compiler should have
6069
     output for it.
6070
 
6071
`info mismatch between compiler and debugger'
6072
     GDB could not parse a type specification output by the compiler.
6073
 
6074
 
6075

6076
File: gdb.info,  Node: Data Files,  Prev: Symbol Errors,  Up: GDB Files
6077
 
6078
18.4 GDB Data Files
6079
===================
6080
 
6081
GDB will sometimes read an auxiliary data file.  These files are kept
6082
in a directory known as the "data directory".
6083
 
6084
   You can set the data directory's name, and view the name GDB is
6085
currently using.
6086
 
6087
`set data-directory DIRECTORY'
6088
     Set the directory which GDB searches for auxiliary data files to
6089
     DIRECTORY.
6090
 
6091
`show data-directory'
6092
     Show the directory GDB searches for auxiliary data files.
6093
 
6094
   You can set the default data directory by using the configure-time
6095
`--with-gdb-datadir' option.  If the data directory is inside GDB's
6096
configured binary prefix (set with `--prefix' or `--exec-prefix'), then
6097
the default data directory will be updated automatically if the
6098
installed GDB is moved to a new location.
6099
 
6100

6101
File: gdb.info,  Node: Targets,  Next: Remote Debugging,  Prev: GDB Files,  Up: Top
6102
 
6103
19 Specifying a Debugging Target
6104
********************************
6105
 
6106
A "target" is the execution environment occupied by your program.
6107
 
6108
   Often, GDB runs in the same host environment as your program; in
6109
that case, the debugging target is specified as a side effect when you
6110
use the `file' or `core' commands.  When you need more flexibility--for
6111
example, running GDB on a physically separate host, or controlling a
6112
standalone system over a serial port or a realtime system over a TCP/IP
6113
connection--you can use the `target' command to specify one of the
6114
target types configured for GDB (*note Commands for Managing Targets:
6115
Target Commands.).
6116
 
6117
   It is possible to build GDB for several different "target
6118
architectures".  When GDB is built like that, you can choose one of the
6119
available architectures with the `set architecture' command.
6120
 
6121
`set architecture ARCH'
6122
     This command sets the current target architecture to ARCH.  The
6123
     value of ARCH can be `"auto"', in addition to one of the supported
6124
     architectures.
6125
 
6126
`show architecture'
6127
     Show the current target architecture.
6128
 
6129
`set processor'
6130
`processor'
6131
     These are alias commands for, respectively, `set architecture' and
6132
     `show architecture'.
6133
 
6134
* Menu:
6135
 
6136
* Active Targets::              Active targets
6137
* Target Commands::             Commands for managing targets
6138
* Byte Order::                  Choosing target byte order
6139
 
6140

6141
File: gdb.info,  Node: Active Targets,  Next: Target Commands,  Up: Targets
6142
 
6143
19.1 Active Targets
6144
===================
6145
 
6146
There are three classes of targets: processes, core files, and
6147
executable files.  GDB can work concurrently on up to three active
6148
targets, one in each class.  This allows you to (for example) start a
6149
process and inspect its activity without abandoning your work on a core
6150
file.
6151
 
6152
   For example, if you execute `gdb a.out', then the executable file
6153
`a.out' is the only active target.  If you designate a core file as
6154
well--presumably from a prior run that crashed and coredumped--then GDB
6155
has two active targets and uses them in tandem, looking first in the
6156
corefile target, then in the executable file, to satisfy requests for
6157
memory addresses.  (Typically, these two classes of target are
6158
complementary, since core files contain only a program's read-write
6159
memory--variables and so on--plus machine status, while executable
6160
files contain only the program text and initialized data.)
6161
 
6162
   When you type `run', your executable file becomes an active process
6163
target as well.  When a process target is active, all GDB commands
6164
requesting memory addresses refer to that target; addresses in an
6165
active core file or executable file target are obscured while the
6166
process target is active.
6167
 
6168
   Use the `core-file' and `exec-file' commands to select a new core
6169
file or executable target (*note Commands to Specify Files: Files.).
6170
To specify as a target a process that is already running, use the
6171
`attach' command (*note Debugging an Already-running Process: Attach.).
6172
 
6173

6174
File: gdb.info,  Node: Target Commands,  Next: Byte Order,  Prev: Active Targets,  Up: Targets
6175
 
6176
19.2 Commands for Managing Targets
6177
==================================
6178
 
6179
`target TYPE PARAMETERS'
6180
     Connects the GDB host environment to a target machine or process.
6181
     A target is typically a protocol for talking to debugging
6182
     facilities.  You use the argument TYPE to specify the type or
6183
     protocol of the target machine.
6184
 
6185
     Further PARAMETERS are interpreted by the target protocol, but
6186
     typically include things like device names or host names to connect
6187
     with, process numbers, and baud rates.
6188
 
6189
     The `target' command does not repeat if you press  again
6190
     after executing the command.
6191
 
6192
`help target'
6193
     Displays the names of all targets available.  To display targets
6194
     currently selected, use either `info target' or `info files'
6195
     (*note Commands to Specify Files: Files.).
6196
 
6197
`help target NAME'
6198
     Describe a particular target, including any parameters necessary to
6199
     select it.
6200
 
6201
`set gnutarget ARGS'
6202
     GDB uses its own library BFD to read your files.  GDB knows
6203
     whether it is reading an "executable", a "core", or a ".o" file;
6204
     however, you can specify the file format with the `set gnutarget'
6205
     command.  Unlike most `target' commands, with `gnutarget' the
6206
     `target' refers to a program, not a machine.
6207
 
6208
          _Warning:_ To specify a file format with `set gnutarget', you
6209
          must know the actual BFD name.
6210
 
6211
     *Note Commands to Specify Files: Files.
6212
 
6213
`show gnutarget'
6214
     Use the `show gnutarget' command to display what file format
6215
     `gnutarget' is set to read.  If you have not set `gnutarget', GDB
6216
     will determine the file format for each file automatically, and
6217
     `show gnutarget' displays `The current BDF target is "auto"'.
6218
 
6219
   Here are some common targets (available, or not, depending on the GDB
6220
configuration):
6221
 
6222
`target exec PROGRAM'
6223
     An executable file.  `target exec PROGRAM' is the same as
6224
     `exec-file PROGRAM'.
6225
 
6226
`target core FILENAME'
6227
     A core dump file.  `target core FILENAME' is the same as
6228
     `core-file FILENAME'.
6229
 
6230
`target remote MEDIUM'
6231
     A remote system connected to GDB via a serial line or network
6232
     connection.  This command tells GDB to use its own remote protocol
6233
     over MEDIUM for debugging.  *Note Remote Debugging::.
6234
 
6235
     For example, if you have a board connected to `/dev/ttya' on the
6236
     machine running GDB, you could say:
6237
 
6238
          target remote /dev/ttya
6239
 
6240
     `target remote' supports the `load' command.  This is only useful
6241
     if you have some other way of getting the stub to the target
6242
     system, and you can put it somewhere in memory where it won't get
6243
     clobbered by the download.
6244
 
6245
`target sim [SIMARGS] ...'
6246
     Builtin CPU simulator.  GDB includes simulators for most
6247
     architectures.  In general,
6248
                  target sim
6249
                  load
6250
                  run
6251
     works; however, you cannot assume that a specific memory map,
6252
     device drivers, or even basic I/O is available, although some
6253
     simulators do provide these.  For info about any
6254
     processor-specific simulator details, see the appropriate section
6255 342 jeremybenn
     in *note Embedded Processors: Embedded Processors.
6256 330 jeremybenn
 
6257
 
6258
   Some configurations may include these targets as well:
6259
 
6260
`target nrom DEV'
6261
     NetROM ROM emulator.  This target only supports downloading.
6262
 
6263
 
6264
   Different targets are available on different configurations of GDB;
6265
your configuration may have more or fewer targets.
6266
 
6267
   Many remote targets require you to download the executable's code
6268
once you've successfully established a connection.  You may wish to
6269
control various aspects of this process.
6270
 
6271
`set hash'
6272
     This command controls whether a hash mark `#' is displayed while
6273
     downloading a file to the remote monitor.  If on, a hash mark is
6274
     displayed after each S-record is successfully downloaded to the
6275
     monitor.
6276
 
6277
`show hash'
6278
     Show the current status of displaying the hash mark.
6279
 
6280
`set debug monitor'
6281
     Enable or disable display of communications messages between GDB
6282
     and the remote monitor.
6283
 
6284
`show debug monitor'
6285
     Show the current status of displaying communications between GDB
6286
     and the remote monitor.
6287
 
6288
`load FILENAME'
6289
     Depending on what remote debugging facilities are configured into
6290
     GDB, the `load' command may be available.  Where it exists, it is
6291
     meant to make FILENAME (an executable) available for debugging on
6292
     the remote system--by downloading, or dynamic linking, for example.
6293
     `load' also records the FILENAME symbol table in GDB, like the
6294
     `add-symbol-file' command.
6295
 
6296
     If your GDB does not have a `load' command, attempting to execute
6297
     it gets the error message "`You can't do that when your target is
6298
     ...'"
6299
 
6300
     The file is loaded at whatever address is specified in the
6301
     executable.  For some object file formats, you can specify the
6302
     load address when you link the program; for other formats, like
6303
     a.out, the object file format specifies a fixed address.
6304
 
6305
     Depending on the remote side capabilities, GDB may be able to load
6306
     programs into flash memory.
6307
 
6308
     `load' does not repeat if you press  again after using it.
6309
 
6310

6311
File: gdb.info,  Node: Byte Order,  Prev: Target Commands,  Up: Targets
6312
 
6313
19.3 Choosing Target Byte Order
6314
===============================
6315
 
6316
Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
6317
offer the ability to run either big-endian or little-endian byte
6318
orders.  Usually the executable or symbol will include a bit to
6319
designate the endian-ness, and you will not need to worry about which
6320
to use.  However, you may still find it useful to adjust GDB's idea of
6321
processor endian-ness manually.
6322
 
6323
`set endian big'
6324
     Instruct GDB to assume the target is big-endian.
6325
 
6326
`set endian little'
6327
     Instruct GDB to assume the target is little-endian.
6328
 
6329
`set endian auto'
6330
     Instruct GDB to use the byte order associated with the executable.
6331
 
6332
`show endian'
6333
     Display GDB's current idea of the target byte order.
6334
 
6335
 
6336
   Note that these commands merely adjust interpretation of symbolic
6337
data on the host, and that they have absolutely no effect on the target
6338
system.
6339
 
6340

6341
File: gdb.info,  Node: Remote Debugging,  Next: Configurations,  Prev: Targets,  Up: Top
6342
 
6343
20 Debugging Remote Programs
6344
****************************
6345
 
6346
If you are trying to debug a program running on a machine that cannot
6347
run GDB in the usual way, it is often useful to use remote debugging.
6348
For example, you might use remote debugging on an operating system
6349
kernel, or on a small system which does not have a general purpose
6350
operating system powerful enough to run a full-featured debugger.
6351
 
6352
   Some configurations of GDB have special serial or TCP/IP interfaces
6353
to make this work with particular debugging targets.  In addition, GDB
6354
comes with a generic serial protocol (specific to GDB, but not specific
6355
to any particular target system) which you can use if you write the
6356
remote stubs--the code that runs on the remote system to communicate
6357
with GDB.
6358
 
6359
   Other remote targets may be available in your configuration of GDB;
6360
use `help target' to list them.
6361
 
6362
* Menu:
6363
 
6364
* Connecting::                  Connecting to a remote target
6365
* File Transfer::               Sending files to a remote system
6366
* Server::                      Using the gdbserver program
6367
* Remote Configuration::        Remote configuration
6368
* Remote Stub::                 Implementing a remote stub
6369
 
6370

6371
File: gdb.info,  Node: Connecting,  Next: File Transfer,  Up: Remote Debugging
6372
 
6373
20.1 Connecting to a Remote Target
6374
==================================
6375
 
6376
On the GDB host machine, you will need an unstripped copy of your
6377
program, since GDB needs symbol and debugging information.  Start up
6378
GDB as usual, using the name of the local copy of your program as the
6379
first argument.
6380
 
6381
   GDB can communicate with the target over a serial line, or over an
6382
IP network using TCP or UDP.  In each case, GDB uses the same protocol
6383
for debugging your program; only the medium carrying the debugging
6384
packets varies.  The `target remote' command establishes a connection
6385
to the target.  Its arguments indicate which medium to use:
6386
 
6387
`target remote SERIAL-DEVICE'
6388
     Use SERIAL-DEVICE to communicate with the target.  For example, to
6389
     use a serial line connected to the device named `/dev/ttyb':
6390
 
6391
          target remote /dev/ttyb
6392
 
6393
     If you're using a serial line, you may want to give GDB the
6394
     `--baud' option, or use the `set remotebaud' command (*note set
6395
     remotebaud: Remote Configuration.) before the `target' command.
6396
 
6397
`target remote `HOST:PORT''
6398
`target remote `tcp:HOST:PORT''
6399
     Debug using a TCP connection to PORT on HOST.  The HOST may be
6400
     either a host name or a numeric IP address; PORT must be a decimal
6401
     number.  The HOST could be the target machine itself, if it is
6402
     directly connected to the net, or it might be a terminal server
6403
     which in turn has a serial line to the target.
6404
 
6405
     For example, to connect to port 2828 on a terminal server named
6406
     `manyfarms':
6407
 
6408
          target remote manyfarms:2828
6409
 
6410
     If your remote target is actually running on the same machine as
6411
     your debugger session (e.g. a simulator for your target running on
6412
     the same host), you can omit the hostname.  For example, to
6413
     connect to port 1234 on your local machine:
6414
 
6415
          target remote :1234
6416
     Note that the colon is still required here.
6417
 
6418
`target remote `udp:HOST:PORT''
6419
     Debug using UDP packets to PORT on HOST.  For example, to connect
6420
     to UDP port 2828 on a terminal server named `manyfarms':
6421
 
6422
          target remote udp:manyfarms:2828
6423
 
6424
     When using a UDP connection for remote debugging, you should keep
6425
     in mind that the `U' stands for "Unreliable".  UDP can silently
6426
     drop packets on busy or unreliable networks, which will cause
6427
     havoc with your debugging session.
6428
 
6429
`target remote | COMMAND'
6430
     Run COMMAND in the background and communicate with it using a
6431
     pipe.  The COMMAND is a shell command, to be parsed and expanded
6432
     by the system's command shell, `/bin/sh'; it should expect remote
6433
     protocol packets on its standard input, and send replies on its
6434
     standard output.  You could use this to run a stand-alone simulator
6435
     that speaks the remote debugging protocol, to make net connections
6436
     using programs like `ssh', or for other similar tricks.
6437
 
6438
     If COMMAND closes its standard output (perhaps by exiting), GDB
6439
     will try to send it a `SIGTERM' signal.  (If the program has
6440
     already exited, this will have no effect.)
6441
 
6442
 
6443
   Once the connection has been established, you can use all the usual
6444
commands to examine and change data.  The remote program is already
6445
running; you can use `step' and `continue', and you do not need to use
6446
`run'.
6447
 
6448
   Whenever GDB is waiting for the remote program, if you type the
6449
interrupt character (often `Ctrl-c'), GDB attempts to stop the program.
6450
This may or may not succeed, depending in part on the hardware and the
6451
serial drivers the remote system uses.  If you type the interrupt
6452
character once again, GDB displays this prompt:
6453
 
6454
     Interrupted while waiting for the program.
6455
     Give up (and stop debugging it)?  (y or n)
6456
 
6457
   If you type `y', GDB abandons the remote debugging session.  (If you
6458
decide you want to try again later, you can use `target remote' again
6459
to connect once more.)  If you type `n', GDB goes back to waiting.
6460
 
6461
`detach'
6462
     When you have finished debugging the remote program, you can use
6463
     the `detach' command to release it from GDB control.  Detaching
6464
     from the target normally resumes its execution, but the results
6465
     will depend on your particular remote stub.  After the `detach'
6466
     command, GDB is free to connect to another target.
6467
 
6468
`disconnect'
6469
     The `disconnect' command behaves like `detach', except that the
6470
     target is generally not resumed.  It will wait for GDB (this
6471
     instance or another one) to connect and continue debugging.  After
6472
     the `disconnect' command, GDB is again free to connect to another
6473
     target.
6474
 
6475
`monitor CMD'
6476
     This command allows you to send arbitrary commands directly to the
6477
     remote monitor.  Since GDB doesn't care about the commands it
6478
     sends like this, this command is the way to extend GDB--you can
6479
     add new commands that only the external monitor will understand
6480
     and implement.
6481
 
6482

6483
File: gdb.info,  Node: File Transfer,  Next: Server,  Prev: Connecting,  Up: Remote Debugging
6484
 
6485
20.2 Sending files to a remote system
6486
=====================================
6487
 
6488
Some remote targets offer the ability to transfer files over the same
6489
connection used to communicate with GDB.  This is convenient for
6490
targets accessible through other means, e.g. GNU/Linux systems running
6491
`gdbserver' over a network interface.  For other targets, e.g. embedded
6492
devices with only a single serial port, this may be the only way to
6493
upload or download files.
6494
 
6495
   Not all remote targets support these commands.
6496
 
6497
`remote put HOSTFILE TARGETFILE'
6498
     Copy file HOSTFILE from the host system (the machine running GDB)
6499
     to TARGETFILE on the target system.
6500
 
6501
`remote get TARGETFILE HOSTFILE'
6502
     Copy file TARGETFILE from the target system to HOSTFILE on the
6503
     host system.
6504
 
6505
`remote delete TARGETFILE'
6506
     Delete TARGETFILE from the target system.
6507
 
6508
 
6509

6510
File: gdb.info,  Node: Server,  Next: Remote Configuration,  Prev: File Transfer,  Up: Remote Debugging
6511
 
6512
20.3 Using the `gdbserver' Program
6513
==================================
6514
 
6515
`gdbserver' is a control program for Unix-like systems, which allows
6516
you to connect your program with a remote GDB via `target remote'--but
6517
without linking in the usual debugging stub.
6518
 
6519
   `gdbserver' is not a complete replacement for the debugging stubs,
6520
because it requires essentially the same operating-system facilities
6521
that GDB itself does.  In fact, a system that can run `gdbserver' to
6522
connect to a remote GDB could also run GDB locally!  `gdbserver' is
6523
sometimes useful nevertheless, because it is a much smaller program
6524
than GDB itself.  It is also easier to port than all of GDB, so you may
6525
be able to get started more quickly on a new system by using
6526
`gdbserver'.  Finally, if you develop code for real-time systems, you
6527
may find that the tradeoffs involved in real-time operation make it
6528
more convenient to do as much development work as possible on another
6529
system, for example by cross-compiling.  You can use `gdbserver' to
6530
make a similar choice for debugging.
6531
 
6532
   GDB and `gdbserver' communicate via either a serial line or a TCP
6533
connection, using the standard GDB remote serial protocol.
6534
 
6535
     _Warning:_ `gdbserver' does not have any built-in security.  Do
6536
     not run `gdbserver' connected to any public network; a GDB
6537
     connection to `gdbserver' provides access to the target system
6538
     with the same privileges as the user running `gdbserver'.
6539
 
6540
20.3.1 Running `gdbserver'
6541
--------------------------
6542
 
6543
Run `gdbserver' on the target system.  You need a copy of the program
6544
you want to debug, including any libraries it requires.  `gdbserver'
6545
does not need your program's symbol table, so you can strip the program
6546
if necessary to save space.  GDB on the host system does all the symbol
6547
handling.
6548
 
6549
   To use the server, you must tell it how to communicate with GDB; the
6550
name of your program; and the arguments for your program.  The usual
6551
syntax is:
6552
 
6553
     target> gdbserver COMM PROGRAM [ ARGS ... ]
6554
 
6555
   COMM is either a device name (to use a serial line) or a TCP
6556
hostname and portnumber.  For example, to debug Emacs with the argument
6557
`foo.txt' and communicate with GDB over the serial port `/dev/com1':
6558
 
6559
     target> gdbserver /dev/com1 emacs foo.txt
6560
 
6561
   `gdbserver' waits passively for the host GDB to communicate with it.
6562
 
6563
   To use a TCP connection instead of a serial line:
6564
 
6565
     target> gdbserver host:2345 emacs foo.txt
6566
 
6567
   The only difference from the previous example is the first argument,
6568
specifying that you are communicating with the host GDB via TCP.  The
6569
`host:2345' argument means that `gdbserver' is to expect a TCP
6570
connection from machine `host' to local TCP port 2345.  (Currently, the
6571
`host' part is ignored.)  You can choose any number you want for the
6572
port number as long as it does not conflict with any TCP ports already
6573
in use on the target system (for example, `23' is reserved for
6574
`telnet').(1)  You must use the same port number with the host GDB
6575
`target remote' command.
6576
 
6577
20.3.1.1 Attaching to a Running Program
6578
.......................................
6579
 
6580
On some targets, `gdbserver' can also attach to running programs.  This
6581
is accomplished via the `--attach' argument.  The syntax is:
6582
 
6583
     target> gdbserver --attach COMM PID
6584
 
6585
   PID is the process ID of a currently running process.  It isn't
6586
necessary to point `gdbserver' at a binary for the running process.
6587
 
6588
   You can debug processes by name instead of process ID if your target
6589
has the `pidof' utility:
6590
 
6591
     target> gdbserver --attach COMM `pidof PROGRAM`
6592
 
6593
   In case more than one copy of PROGRAM is running, or PROGRAM has
6594
multiple threads, most versions of `pidof' support the `-s' option to
6595
only return the first process ID.
6596
 
6597
20.3.1.2 Multi-Process Mode for `gdbserver'
6598
...........................................
6599
 
6600
When you connect to `gdbserver' using `target remote', `gdbserver'
6601
debugs the specified program only once.  When the program exits, or you
6602
detach from it, GDB closes the connection and `gdbserver' exits.
6603
 
6604
   If you connect using `target extended-remote', `gdbserver' enters
6605
multi-process mode.  When the debugged program exits, or you detach
6606
from it, GDB stays connected to `gdbserver' even though no program is
6607
running.  The `run' and `attach' commands instruct `gdbserver' to run
6608
or attach to a new program.  The `run' command uses `set remote
6609
exec-file' (*note set remote exec-file::) to select the program to run.
6610 342 jeremybenn
Command line arguments are supported, except for wildcard expansion and
6611
I/O redirection (*note Arguments::).
6612 330 jeremybenn
 
6613
   To start `gdbserver' without supplying an initial command to run or
6614
process ID to attach, use the `--multi' command line option.  Then you
6615
can connect using `target extended-remote' and start the program you
6616
want to debug.
6617
 
6618
   `gdbserver' does not automatically exit in multi-process mode.  You
6619
can terminate it by using `monitor exit' (*note Monitor Commands for
6620
gdbserver::).
6621
 
6622
20.3.1.3 Other Command-Line Arguments for `gdbserver'
6623
.....................................................
6624
 
6625
The `--debug' option tells `gdbserver' to display extra status
6626
information about the debugging process.  The `--remote-debug' option
6627
tells `gdbserver' to display remote protocol debug output.  These
6628
options are intended for `gdbserver' development and for bug reports to
6629
the developers.
6630
 
6631
   The `--wrapper' option specifies a wrapper to launch programs for
6632
debugging.  The option should be followed by the name of the wrapper,
6633
then any command-line arguments to pass to the wrapper, then `--'
6634
indicating the end of the wrapper arguments.
6635
 
6636
   `gdbserver' runs the specified wrapper program with a combined
6637
command line including the wrapper arguments, then the name of the
6638
program to debug, then any arguments to the program.  The wrapper runs
6639
until it executes your program, and then GDB gains control.
6640
 
6641
   You can use any program that eventually calls `execve' with its
6642
arguments as a wrapper.  Several standard Unix utilities do this, e.g.
6643
`env' and `nohup'.  Any Unix shell script ending with `exec "$@"' will
6644
also work.
6645
 
6646
   For example, you can use `env' to pass an environment variable to
6647
the debugged program, without setting the variable in `gdbserver''s
6648
environment:
6649
 
6650
     $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
6651
 
6652
20.3.2 Connecting to `gdbserver'
6653
--------------------------------
6654
 
6655
Run GDB on the host system.
6656
 
6657
   First make sure you have the necessary symbol files.  Load symbols
6658
for your application using the `file' command before you connect.  Use
6659
`set sysroot' to locate target libraries (unless your GDB was compiled
6660
with the correct sysroot using `--with-sysroot').
6661
 
6662
   The symbol file and target libraries must exactly match the
6663
executable and libraries on the target, with one exception: the files
6664
on the host system should not be stripped, even if the files on the
6665
target system are.  Mismatched or missing files will lead to confusing
6666
results during debugging.  On GNU/Linux targets, mismatched or missing
6667
files may also prevent `gdbserver' from debugging multi-threaded
6668
programs.
6669
 
6670
   Connect to your target (*note Connecting to a Remote Target:
6671
Connecting.).  For TCP connections, you must start up `gdbserver' prior
6672
to using the `target remote' command.  Otherwise you may get an error
6673
whose text depends on the host system, but which usually looks
6674
something like `Connection refused'.  Don't use the `load' command in
6675
GDB when using `gdbserver', since the program is already on the target.
6676
 
6677
20.3.3 Monitor Commands for `gdbserver'
6678
---------------------------------------
6679
 
6680
During a GDB session using `gdbserver', you can use the `monitor'
6681
command to send special requests to `gdbserver'.  Here are the
6682
available commands.
6683
 
6684
`monitor help'
6685
     List the available monitor commands.
6686
 
6687
`monitor set debug 0'
6688
`monitor set debug 1'
6689
     Disable or enable general debugging messages.
6690
 
6691
`monitor set remote-debug 0'
6692
`monitor set remote-debug 1'
6693
     Disable or enable specific debugging messages associated with the
6694
     remote protocol (*note Remote Protocol::).
6695
 
6696
`monitor set libthread-db-search-path [PATH]'
6697
     When this command is issued, PATH is a colon-separated list of
6698
     directories to search for `libthread_db' (*note set
6699
     libthread-db-search-path: Threads.).  If you omit PATH,
6700
     `libthread-db-search-path' will be reset to an empty list.
6701
 
6702
`monitor exit'
6703
     Tell gdbserver to exit immediately.  This command should be
6704
     followed by `disconnect' to close the debugging session.
6705
     `gdbserver' will detach from any attached processes and kill any
6706
     processes it created.  Use `monitor exit' to terminate `gdbserver'
6707
     at the end of a multi-process mode debug session.
6708
 
6709
 
6710
20.3.4 Tracepoints support in `gdbserver'
6711
-----------------------------------------
6712
 
6713
On some targets, `gdbserver' supports tracepoints, fast tracepoints and
6714
static tracepoints.
6715
 
6716
   For fast or static tracepoints to work, a special library called the
6717
"in-process agent" (IPA), must be loaded in the inferior process.  This
6718
library is built and distributed as an integral part of `gdbserver'.
6719
In addition, support for static tracepoints requires building the
6720
in-process agent library with static tracepoints support.  At present,
6721
the UST (LTTng Userspace Tracer, `http://lttng.org/ust') tracing engine
6722
is supported.  This support is automatically available if UST
6723
development headers are found in the standard include path when
6724
`gdbserver' is built, or if `gdbserver' was explicitly configured using
6725
`--with-ust' to point at such headers.  You can explicitly disable the
6726
support using `--with-ust=no'.
6727
 
6728
   There are several ways to load the in-process agent in your program:
6729
 
6730
`Specifying it as dependency at link time'
6731
     You can link your program dynamically with the in-process agent
6732
     library.  On most systems, this is accomplished by adding
6733
     `-linproctrace' to the link command.
6734
 
6735
`Using the system's preloading mechanisms'
6736
     You can force loading the in-process agent at startup time by using
6737
     your system's support for preloading shared libraries.  Many Unixes
6738
     support the concept of preloading user defined libraries.  In most
6739
     cases, you do that by specifying `LD_PRELOAD=libinproctrace.so' in
6740
     the environment.  See also the description of `gdbserver''s
6741
     `--wrapper' command line option.
6742
 
6743
`Using GDB to force loading the agent at run time'
6744
     On some systems, you can force the inferior to load a shared
6745
     library, by calling a dynamic loader function in the inferior that
6746
     takes care of dynamically looking up and loading a shared library.
6747
     On most Unix systems, the function is `dlopen'.  You'll use the
6748
     `call' command for that.  For example:
6749
 
6750
          (gdb) call dlopen ("libinproctrace.so", ...)
6751
 
6752
     Note that on most Unix systems, for the `dlopen' function to be
6753
     available, the program needs to be linked with `-ldl'.
6754
 
6755
   On systems that have a userspace dynamic loader, like most Unix
6756
systems, when you connect to `gdbserver' using `target remote', you'll
6757
find that the program is stopped at the dynamic loader's entry point,
6758
and no shared library has been loaded in the program's address space
6759
yet, including the in-process agent.  In that case, before being able
6760
to use any of the fast or static tracepoints features, you need to let
6761
the loader run and load the shared libraries.  The simplest way to do
6762
that is to run the program to the main procedure.  E.g., if debugging a
6763
C or C++ program, start `gdbserver' like so:
6764
 
6765
     $ gdbserver :9999 myprogram
6766
 
6767
   Start GDB and connect to `gdbserver' like so, and run to main:
6768
 
6769
     $ gdb myprogram
6770
     (gdb) target remote myhost:9999
6771
     0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2
6772
     (gdb) b main
6773
     (gdb) continue
6774
 
6775
   The in-process tracing agent library should now be loaded into the
6776
process; you can confirm it with the `info sharedlibrary' command,
6777
which will list `libinproctrace.so' as loaded in the process.  You are
6778
now ready to install fast tracepoints, list static tracepoint markers,
6779
probe static tracepoints markers, and start tracing.
6780
 
6781
   ---------- Footnotes ----------
6782
 
6783
   (1) If you choose a port number that conflicts with another service,
6784
`gdbserver' prints an error message and exits.
6785
 
6786

6787
File: gdb.info,  Node: Remote Configuration,  Next: Remote Stub,  Prev: Server,  Up: Remote Debugging
6788
 
6789
20.4 Remote Configuration
6790
=========================
6791
 
6792
This section documents the configuration options available when
6793
debugging remote programs.  For the options related to the File I/O
6794 342 jeremybenn
extensions of the remote protocol, see *note system-call-allowed:
6795 330 jeremybenn
system.
6796
 
6797
`set remoteaddresssize BITS'
6798
     Set the maximum size of address in a memory packet to the specified
6799
     number of bits.  GDB will mask off the address bits above that
6800
     number, when it passes addresses to the remote target.  The
6801
     default value is the number of bits in the target's address.
6802
 
6803
`show remoteaddresssize'
6804
     Show the current value of remote address size in bits.
6805
 
6806
`set remotebaud N'
6807
     Set the baud rate for the remote serial I/O to N baud.  The value
6808
     is used to set the speed of the serial port used for debugging
6809
     remote targets.
6810
 
6811
`show remotebaud'
6812
     Show the current speed of the remote connection.
6813
 
6814
`set remotebreak'
6815
     If set to on, GDB sends a `BREAK' signal to the remote when you
6816
     type `Ctrl-c' to interrupt the program running on the remote.  If
6817
     set to off, GDB sends the `Ctrl-C' character instead.  The default
6818
     is off, since most remote systems expect to see `Ctrl-C' as the
6819
     interrupt signal.
6820
 
6821
`show remotebreak'
6822
     Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote
6823
     program.
6824
 
6825
`set remoteflow on'
6826
`set remoteflow off'
6827
     Enable or disable hardware flow control (`RTS'/`CTS') on the
6828
     serial port used to communicate to the remote target.
6829
 
6830
`show remoteflow'
6831
     Show the current setting of hardware flow control.
6832
 
6833
`set remotelogbase BASE'
6834
     Set the base (a.k.a. radix) of logging serial protocol
6835
     communications to BASE.  Supported values of BASE are: `ascii',
6836
     `octal', and `hex'.  The default is `ascii'.
6837
 
6838
`show remotelogbase'
6839
     Show the current setting of the radix for logging remote serial
6840
     protocol.
6841
 
6842
`set remotelogfile FILE'
6843
     Record remote serial communications on the named FILE.  The
6844
     default is not to record at all.
6845
 
6846
`show remotelogfile.'
6847
     Show the current setting  of the file name on which to record the
6848
     serial communications.
6849
 
6850
`set remotetimeout NUM'
6851
     Set the timeout limit to wait for the remote target to respond to
6852
     NUM seconds.  The default is 2 seconds.
6853
 
6854
`show remotetimeout'
6855
     Show the current number of seconds to wait for the remote target
6856
     responses.
6857
 
6858
`set remote hardware-watchpoint-limit LIMIT'
6859
`set remote hardware-breakpoint-limit LIMIT'
6860
     Restrict GDB to using LIMIT remote hardware breakpoint or
6861
     watchpoints.  A limit of -1, the default, is treated as unlimited.
6862
 
6863
`set remote exec-file FILENAME'
6864
`show remote exec-file'
6865
     Select the file used for `run' with `target extended-remote'.
6866
     This should be set to a filename valid on the target system.  If
6867
     it is not set, the target will use a default filename (e.g. the
6868
     last program run).
6869
 
6870
`set remote interrupt-sequence'
6871
     Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g'
6872
     as the sequence to the remote target in order to interrupt the
6873
     execution.  `Ctrl-C' is a default.  Some system prefers `BREAK'
6874
     which is high level of serial line for some certain time.  Linux
6875
     kernel prefers `BREAK-g', a.k.a Magic SysRq g.  It is `BREAK'
6876
     signal followed by character `g'.
6877
 
6878
`show interrupt-sequence'
6879
     Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to
6880
     interrupt the remote program.  `BREAK-g' is BREAK signal followed
6881
     by `g' and also known as Magic SysRq g.
6882
 
6883
`set remote interrupt-on-connect'
6884
     Specify whether interrupt-sequence is sent to remote target when
6885
     GDB connects to it.  This is mostly needed when you debug Linux
6886
     kernel.  Linux kernel expects `BREAK' followed by `g' which is
6887
     known as Magic SysRq g in order to connect GDB.
6888
 
6889
`show interrupt-on-connect'
6890
     Show whether interrupt-sequence is sent to remote target when GDB
6891
     connects to it.
6892
 
6893
`set tcp auto-retry on'
6894
     Enable auto-retry for remote TCP connections.  This is useful if
6895
     the remote debugging agent is launched in parallel with GDB; there
6896
     is a race condition because the agent may not become ready to
6897
     accept the connection before GDB attempts to connect.  When
6898
     auto-retry is enabled, if the initial attempt to connect fails,
6899
     GDB reattempts to establish the connection using the timeout
6900
     specified by `set tcp connect-timeout'.
6901
 
6902
`set tcp auto-retry off'
6903
     Do not auto-retry failed TCP connections.
6904
 
6905
`show tcp auto-retry'
6906
     Show the current auto-retry setting.
6907
 
6908
`set tcp connect-timeout SECONDS'
6909
     Set the timeout for establishing a TCP connection to the remote
6910
     target to SECONDS.  The timeout affects both polling to retry
6911
     failed connections (enabled by `set tcp auto-retry on') and
6912
     waiting for connections that are merely slow to complete, and
6913
     represents an approximate cumulative value.
6914
 
6915
`show tcp connect-timeout'
6916
     Show the current connection timeout setting.
6917
 
6918
   The GDB remote protocol autodetects the packets supported by your
6919
debugging stub.  If you need to override the autodetection, you can use
6920
these commands to enable or disable individual packets.  Each packet
6921
can be set to `on' (the remote target supports this packet), `off' (the
6922
remote target does not support this packet), or `auto' (detect remote
6923
target support for this packet).  They all default to `auto'.  For more
6924 342 jeremybenn
information about each packet, see *note Remote Protocol::.
6925 330 jeremybenn
 
6926
   During normal use, you should not have to use any of these commands.
6927
If you do, that may be a bug in your remote debugging stub, or a bug in
6928
GDB.  You may want to report the problem to the GDB developers.
6929
 
6930
   For each packet NAME, the command to enable or disable the packet is
6931
`set remote NAME-packet'.  The available settings are:
6932
 
6933
Command Name         Remote Packet           Related Features
6934
`fetch-register'     `p'                     `info registers'
6935
`set-register'       `P'                     `set'
6936
`binary-download'    `X'                     `load', `set'
6937
`read-aux-vector'    `qXfer:auxv:read'       `info auxv'
6938
`symbol-lookup'      `qSymbol'               Detecting
6939
                                             multiple threads
6940
`attach'             `vAttach'               `attach'
6941
`verbose-resume'     `vCont'                 Stepping or
6942
                                             resuming multiple
6943
                                             threads
6944
`run'                `vRun'                  `run'
6945
`software-breakpoint'`Z0'                    `break'
6946
`hardware-breakpoint'`Z1'                    `hbreak'
6947
`write-watchpoint'   `Z2'                    `watch'
6948
`read-watchpoint'    `Z3'                    `rwatch'
6949
`access-watchpoint'  `Z4'                    `awatch'
6950
`target-features'    `qXfer:features:read'   `set architecture'
6951
`library-info'       `qXfer:libraries:read'  `info
6952
                                             sharedlibrary'
6953
`memory-map'         `qXfer:memory-map:read' `info mem'
6954
`read-sdata-object'  `qXfer:sdata:read'      `print $_sdata'
6955
`read-spu-object'    `qXfer:spu:read'        `info spu'
6956
`write-spu-object'   `qXfer:spu:write'       `info spu'
6957
`read-siginfo-object'`qXfer:siginfo:read'    `print $_siginfo'
6958
`write-siginfo-object'`qXfer:siginfo:write'   `set $_siginfo'
6959
`threads'            `qXfer:threads:read'    `info threads'
6960
`get-thread-local-   `qGetTLSAddr'           Displaying
6961
storage-address'                             `__thread'
6962
                                             variables
6963
`get-thread-information-block-address'`qGetTIBAddr'           Display
6964
                                             MS-Windows Thread
6965
                                             Information Block.
6966
`search-memory'      `qSearch:memory'        `find'
6967
`supported-packets'  `qSupported'            Remote
6968
                                             communications
6969
                                             parameters
6970
`pass-signals'       `QPassSignals'          `handle SIGNAL'
6971
`hostio-close-packet'`vFile:close'           `remote get',
6972
                                             `remote put'
6973
`hostio-open-packet' `vFile:open'            `remote get',
6974
                                             `remote put'
6975
`hostio-pread-packet'`vFile:pread'           `remote get',
6976
                                             `remote put'
6977
`hostio-pwrite-packet'`vFile:pwrite'          `remote get',
6978
                                             `remote put'
6979
`hostio-unlink-packet'`vFile:unlink'          `remote delete'
6980
`noack-packet'       `QStartNoAckMode'       Packet
6981
                                             acknowledgment
6982
`osdata'             `qXfer:osdata:read'     `info os'
6983
`query-attached'     `qAttached'             Querying remote
6984
                                             process attach
6985
                                             state.
6986
 
6987

6988
File: gdb.info,  Node: Remote Stub,  Prev: Remote Configuration,  Up: Remote Debugging
6989
 
6990
20.5 Implementing a Remote Stub
6991
===============================
6992
 
6993
The stub files provided with GDB implement the target side of the
6994
communication protocol, and the GDB side is implemented in the GDB
6995
source file `remote.c'.  Normally, you can simply allow these
6996
subroutines to communicate, and ignore the details.  (If you're
6997
implementing your own stub file, you can still ignore the details: start
6998
with one of the existing stub files.  `sparc-stub.c' is the best
6999
organized, and therefore the easiest to read.)
7000
 
7001
   To debug a program running on another machine (the debugging
7002
"target" machine), you must first arrange for all the usual
7003
prerequisites for the program to run by itself.  For example, for a C
7004
program, you need:
7005
 
7006
  1. A startup routine to set up the C runtime environment; these
7007
     usually have a name like `crt0'.  The startup routine may be
7008
     supplied by your hardware supplier, or you may have to write your
7009
     own.
7010
 
7011
  2. A C subroutine library to support your program's subroutine calls,
7012
     notably managing input and output.
7013
 
7014
  3. A way of getting your program to the other machine--for example, a
7015
     download program.  These are often supplied by the hardware
7016
     manufacturer, but you may have to write your own from hardware
7017
     documentation.
7018
 
7019
   The next step is to arrange for your program to use a serial port to
7020
communicate with the machine where GDB is running (the "host" machine).
7021
In general terms, the scheme looks like this:
7022
 
7023
_On the host,_
7024
     GDB already understands how to use this protocol; when everything
7025
     else is set up, you can simply use the `target remote' command
7026
     (*note Specifying a Debugging Target: Targets.).
7027
 
7028
_On the target,_
7029
     you must link with your program a few special-purpose subroutines
7030
     that implement the GDB remote serial protocol.  The file
7031
     containing these subroutines is called  a "debugging stub".
7032
 
7033
     On certain remote targets, you can use an auxiliary program
7034
     `gdbserver' instead of linking a stub into your program.  *Note
7035
     Using the `gdbserver' Program: Server, for details.
7036
 
7037
   The debugging stub is specific to the architecture of the remote
7038
machine; for example, use `sparc-stub.c' to debug programs on SPARC
7039
boards.
7040
 
7041
   These working remote stubs are distributed with GDB:
7042
 
7043
`i386-stub.c'
7044
     For Intel 386 and compatible architectures.
7045
 
7046
`m68k-stub.c'
7047
     For Motorola 680x0 architectures.
7048
 
7049
`sh-stub.c'
7050
     For Renesas SH architectures.
7051
 
7052
`sparc-stub.c'
7053
     For SPARC architectures.
7054
 
7055
`sparcl-stub.c'
7056
     For Fujitsu SPARCLITE architectures.
7057
 
7058
 
7059
   The `README' file in the GDB distribution may list other recently
7060
added stubs.
7061
 
7062
* Menu:
7063
 
7064
* Stub Contents::       What the stub can do for you
7065
* Bootstrapping::       What you must do for the stub
7066
* Debug Session::       Putting it all together
7067
 
7068

7069
File: gdb.info,  Node: Stub Contents,  Next: Bootstrapping,  Up: Remote Stub
7070
 
7071
20.5.1 What the Stub Can Do for You
7072
-----------------------------------
7073
 
7074
The debugging stub for your architecture supplies these three
7075
subroutines:
7076
 
7077
`set_debug_traps'
7078
     This routine arranges for `handle_exception' to run when your
7079
     program stops.  You must call this subroutine explicitly near the
7080
     beginning of your program.
7081
 
7082
`handle_exception'
7083
     This is the central workhorse, but your program never calls it
7084
     explicitly--the setup code arranges for `handle_exception' to run
7085
     when a trap is triggered.
7086
 
7087
     `handle_exception' takes control when your program stops during
7088
     execution (for example, on a breakpoint), and mediates
7089
     communications with GDB on the host machine.  This is where the
7090
     communications protocol is implemented; `handle_exception' acts as
7091
     the GDB representative on the target machine.  It begins by
7092
     sending summary information on the state of your program, then
7093
     continues to execute, retrieving and transmitting any information
7094
     GDB needs, until you execute a GDB command that makes your program
7095
     resume; at that point, `handle_exception' returns control to your
7096
     own code on the target machine.
7097
 
7098
`breakpoint'
7099
     Use this auxiliary subroutine to make your program contain a
7100
     breakpoint.  Depending on the particular situation, this may be
7101
     the only way for GDB to get control.  For instance, if your target
7102
     machine has some sort of interrupt button, you won't need to call
7103
     this; pressing the interrupt button transfers control to
7104
     `handle_exception'--in effect, to GDB.  On some machines, simply
7105
     receiving characters on the serial port may also trigger a trap;
7106
     again, in that situation, you don't need to call `breakpoint' from
7107
     your own program--simply running `target remote' from the host GDB
7108
     session gets control.
7109
 
7110
     Call `breakpoint' if none of these is true, or if you simply want
7111
     to make certain your program stops at a predetermined point for the
7112
     start of your debugging session.
7113
 
7114

7115
File: gdb.info,  Node: Bootstrapping,  Next: Debug Session,  Prev: Stub Contents,  Up: Remote Stub
7116
 
7117
20.5.2 What You Must Do for the Stub
7118
------------------------------------
7119
 
7120
The debugging stubs that come with GDB are set up for a particular chip
7121
architecture, but they have no information about the rest of your
7122
debugging target machine.
7123
 
7124
   First of all you need to tell the stub how to communicate with the
7125
serial port.
7126
 
7127
`int getDebugChar()'
7128
     Write this subroutine to read a single character from the serial
7129
     port.  It may be identical to `getchar' for your target system; a
7130
     different name is used to allow you to distinguish the two if you
7131
     wish.
7132
 
7133
`void putDebugChar(int)'
7134
     Write this subroutine to write a single character to the serial
7135
     port.  It may be identical to `putchar' for your target system; a
7136
     different name is used to allow you to distinguish the two if you
7137
     wish.
7138
 
7139
   If you want GDB to be able to stop your program while it is running,
7140
you need to use an interrupt-driven serial driver, and arrange for it
7141
to stop when it receives a `^C' (`\003', the control-C character).
7142
That is the character which GDB uses to tell the remote system to stop.
7143
 
7144
   Getting the debugging target to return the proper status to GDB
7145
probably requires changes to the standard stub; one quick and dirty way
7146
is to just execute a breakpoint instruction (the "dirty" part is that
7147
GDB reports a `SIGTRAP' instead of a `SIGINT').
7148
 
7149
   Other routines you need to supply are:
7150
 
7151
`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
7152
     Write this function to install EXCEPTION_ADDRESS in the exception
7153
     handling tables.  You need to do this because the stub does not
7154
     have any way of knowing what the exception handling tables on your
7155
     target system are like (for example, the processor's table might
7156
     be in ROM, containing entries which point to a table in RAM).
7157
     EXCEPTION_NUMBER is the exception number which should be changed;
7158
     its meaning is architecture-dependent (for example, different
7159
     numbers might represent divide by zero, misaligned access, etc).
7160
     When this exception occurs, control should be transferred directly
7161
     to EXCEPTION_ADDRESS, and the processor state (stack, registers,
7162
     and so on) should be just as it is when a processor exception
7163
     occurs.  So if you want to use a jump instruction to reach
7164
     EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
7165
     subroutine.
7166
 
7167
     For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
7168
     gate so that interrupts are masked while the handler runs.  The
7169
     gate should be at privilege level 0 (the most privileged level).
7170
     The SPARC and 68k stubs are able to mask interrupts themselves
7171
     without help from `exceptionHandler'.
7172
 
7173
`void flush_i_cache()'
7174
     On SPARC and SPARCLITE only, write this subroutine to flush the
7175
     instruction cache, if any, on your target machine.  If there is no
7176
     instruction cache, this subroutine may be a no-op.
7177
 
7178
     On target machines that have instruction caches, GDB requires this
7179
     function to make certain that the state of your program is stable.
7180
 
7181
You must also make sure this library routine is available:
7182
 
7183
`void *memset(void *, int, int)'
7184
     This is the standard library function `memset' that sets an area of
7185
     memory to a known value.  If you have one of the free versions of
7186
     `libc.a', `memset' can be found there; otherwise, you must either
7187
     obtain it from your hardware manufacturer, or write your own.
7188
 
7189
   If you do not use the GNU C compiler, you may need other standard
7190
library subroutines as well; this varies from one stub to another, but
7191
in general the stubs are likely to use any of the common library
7192
subroutines which `GCC' generates as inline code.
7193
 
7194

7195
File: gdb.info,  Node: Debug Session,  Prev: Bootstrapping,  Up: Remote Stub
7196
 
7197
20.5.3 Putting it All Together
7198
------------------------------
7199
 
7200
In summary, when your program is ready to debug, you must follow these
7201
steps.
7202
 
7203
  1. Make sure you have defined the supporting low-level routines
7204
     (*note What You Must Do for the Stub: Bootstrapping.):
7205
          `getDebugChar', `putDebugChar',
7206
          `flush_i_cache', `memset', `exceptionHandler'.
7207
 
7208
  2. Insert these lines near the top of your program:
7209
 
7210
          set_debug_traps();
7211
          breakpoint();
7212
 
7213
  3. For the 680x0 stub only, you need to provide a variable called
7214
     `exceptionHook'.  Normally you just use:
7215
 
7216
          void (*exceptionHook)() = 0;
7217
 
7218
     but if before calling `set_debug_traps', you set it to point to a
7219
     function in your program, that function is called when `GDB'
7220
     continues after stopping on a trap (for example, bus error).  The
7221
     function indicated by `exceptionHook' is called with one
7222
     parameter: an `int' which is the exception number.
7223
 
7224
  4. Compile and link together: your program, the GDB debugging stub for
7225
     your target architecture, and the supporting subroutines.
7226
 
7227
  5. Make sure you have a serial connection between your target machine
7228
     and the GDB host, and identify the serial port on the host.
7229
 
7230
  6. Download your program to your target machine (or get it there by
7231
     whatever means the manufacturer provides), and start it.
7232
 
7233
  7. Start GDB on the host, and connect to the target (*note Connecting
7234
     to a Remote Target: Connecting.).
7235
 
7236
 
7237

7238
File: gdb.info,  Node: Configurations,  Next: Controlling GDB,  Prev: Remote Debugging,  Up: Top
7239
 
7240
21 Configuration-Specific Information
7241
*************************************
7242
 
7243
While nearly all GDB commands are available for all native and cross
7244
versions of the debugger, there are some exceptions.  This chapter
7245
describes things that are only available in certain configurations.
7246
 
7247
   There are three major categories of configurations: native
7248
configurations, where the host and target are the same, embedded
7249
operating system configurations, which are usually the same for several
7250
different processor architectures, and bare embedded processors, which
7251
are quite different from each other.
7252
 
7253
* Menu:
7254
 
7255
* Native::
7256
* Embedded OS::
7257
* Embedded Processors::
7258
* Architectures::
7259
 
7260

7261
File: gdb.info,  Node: Native,  Next: Embedded OS,  Up: Configurations
7262
 
7263
21.1 Native
7264
===========
7265
 
7266
This section describes details specific to particular native
7267
configurations.
7268
 
7269
* Menu:
7270
 
7271
* HP-UX::                       HP-UX
7272
* BSD libkvm Interface::        Debugging BSD kernel memory images
7273
* SVR4 Process Information::    SVR4 process information
7274
* DJGPP Native::                Features specific to the DJGPP port
7275
* Cygwin Native::               Features specific to the Cygwin port
7276
* Hurd Native::                 Features specific to GNU Hurd
7277
* Neutrino::                    Features specific to QNX Neutrino
7278
* Darwin::                      Features specific to Darwin
7279
 
7280

7281
File: gdb.info,  Node: HP-UX,  Next: BSD libkvm Interface,  Up: Native
7282
 
7283
21.1.1 HP-UX
7284
------------
7285
 
7286
On HP-UX systems, if you refer to a function or variable name that
7287
begins with a dollar sign, GDB searches for a user or system name
7288
first, before it searches for a convenience variable.
7289
 
7290

7291
File: gdb.info,  Node: BSD libkvm Interface,  Next: SVR4 Process Information,  Prev: HP-UX,  Up: Native
7292
 
7293
21.1.2 BSD libkvm Interface
7294
---------------------------
7295
 
7296
BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
7297
interface that provides a uniform interface for accessing kernel virtual
7298
memory images, including live systems and crash dumps.  GDB uses this
7299
interface to allow you to debug live kernels and kernel crash dumps on
7300
many native BSD configurations.  This is implemented as a special `kvm'
7301
debugging target.  For debugging a live system, load the currently
7302
running kernel into GDB and connect to the `kvm' target:
7303
 
7304
     (gdb) target kvm
7305
 
7306
   For debugging crash dumps, provide the file name of the crash dump
7307
as an argument:
7308
 
7309
     (gdb) target kvm /var/crash/bsd.0
7310
 
7311
   Once connected to the `kvm' target, the following commands are
7312
available:
7313
 
7314
`kvm pcb'
7315
     Set current context from the "Process Control Block" (PCB) address.
7316
 
7317
`kvm proc'
7318
     Set current context from proc address.  This command isn't
7319
     available on modern FreeBSD systems.
7320
 
7321

7322
File: gdb.info,  Node: SVR4 Process Information,  Next: DJGPP Native,  Prev: BSD libkvm Interface,  Up: Native
7323
 
7324
21.1.3 SVR4 Process Information
7325
-------------------------------
7326
 
7327
Many versions of SVR4 and compatible systems provide a facility called
7328
`/proc' that can be used to examine the image of a running process
7329
using file-system subroutines.  If GDB is configured for an operating
7330
system with this facility, the command `info proc' is available to
7331
report information about the process running your program, or about any
7332
process running on your system.  `info proc' works only on SVR4 systems
7333
that include the `procfs' code.  This includes, as of this writing,
7334
GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
7335
HP-UX, for example.
7336
 
7337
`info proc'
7338
`info proc PROCESS-ID'
7339
     Summarize available information about any running process.  If a
7340
     process ID is specified by PROCESS-ID, display information about
7341
     that process; otherwise display information about the program being
7342
     debugged.  The summary includes the debugged process ID, the
7343
     command line used to invoke it, its current working directory, and
7344
     its executable file's absolute file name.
7345
 
7346
     On some systems, PROCESS-ID can be of the form `[PID]/TID' which
7347
     specifies a certain thread ID within a process.  If the optional
7348
     PID part is missing, it means a thread from the process being
7349
     debugged (the leading `/' still needs to be present, or else GDB
7350
     will interpret the number as a process ID rather than a thread ID).
7351
 
7352
`info proc mappings'
7353
     Report the memory address space ranges accessible in the program,
7354
     with information on whether the process has read, write, or
7355
     execute access rights to each range.  On GNU/Linux systems, each
7356
     memory range includes the object file which is mapped to that
7357
     range, instead of the memory access rights to that range.
7358
 
7359
`info proc stat'
7360
`info proc status'
7361
     These subcommands are specific to GNU/Linux systems.  They show
7362
     the process-related information, including the user ID and group
7363
     ID; how many threads are there in the process; its virtual memory
7364
     usage; the signals that are pending, blocked, and ignored; its
7365
     TTY; its consumption of system and user time; its stack size; its
7366
     `nice' value; etc.  For more information, see the `proc' man page
7367
     (type `man 5 proc' from your shell prompt).
7368
 
7369
`info proc all'
7370
     Show all the information about the process described under all of
7371
     the above `info proc' subcommands.
7372
 
7373
`set procfs-trace'
7374
     This command enables and disables tracing of `procfs' API calls.
7375
 
7376
`show procfs-trace'
7377
     Show the current state of `procfs' API call tracing.
7378
 
7379
`set procfs-file FILE'
7380
     Tell GDB to write `procfs' API trace to the named FILE.  GDB
7381
     appends the trace info to the previous contents of the file.  The
7382
     default is to display the trace on the standard output.
7383
 
7384
`show procfs-file'
7385
     Show the file to which `procfs' API trace is written.
7386
 
7387
`proc-trace-entry'
7388
`proc-trace-exit'
7389
`proc-untrace-entry'
7390
`proc-untrace-exit'
7391
     These commands enable and disable tracing of entries into and exits
7392
     from the `syscall' interface.
7393
 
7394
`info pidlist'
7395
     For QNX Neutrino only, this command displays the list of all the
7396
     processes and all the threads within each process.
7397
 
7398
`info meminfo'
7399
     For QNX Neutrino only, this command displays the list of all
7400
     mapinfos.
7401
 

powered by: WebSVN 2.1.0

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